{"id":15102786,"url":"https://github.com/unitvectory-labs/jsonschema4springboot","last_synced_at":"2026-03-08T04:32:27.952Z","repository":{"id":227363076,"uuid":"771208741","full_name":"UnitVectorY-Labs/jsonschema4springboot","owner":"UnitVectorY-Labs","description":"Add JSON Schema Validation to Spring Boot 3 with Annotations","archived":false,"fork":false,"pushed_at":"2024-04-09T00:27:15.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-09T01:55:38.608Z","etag":null,"topics":["java-17","jsonschema","spring-boot-3"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UnitVectorY-Labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-03-12T22:11:42.000Z","updated_at":"2024-04-15T02:29:02.677Z","dependencies_parsed_at":"2024-04-15T02:28:59.864Z","dependency_job_id":null,"html_url":"https://github.com/UnitVectorY-Labs/jsonschema4springboot","commit_stats":null,"previous_names":["unitvectory-labs/jsonschema4springboot"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fjsonschema4springboot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fjsonschema4springboot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fjsonschema4springboot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fjsonschema4springboot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UnitVectorY-Labs","download_url":"https://codeload.github.com/UnitVectorY-Labs/jsonschema4springboot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332525,"owners_count":20921852,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java-17","jsonschema","spring-boot-3"],"created_at":"2024-09-25T19:06:51.724Z","updated_at":"2026-03-08T04:32:27.937Z","avatar_url":"https://github.com/UnitVectorY-Labs.png","language":"Java","readme":"[![GitHub release](https://img.shields.io/github/release/UnitVectorY-Labs/jsonschema4springboot.svg)](https://github.com/UnitVectorY-Labs/jsonschema4springboot/releases/latest) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Active](https://img.shields.io/badge/Status-Active-green)](https://guide.unitvectorylabs.com/bestpractices/status/#active) [![Maven Central](https://img.shields.io/maven-central/v/com.unitvectory/jsonschema4springboot)](https://central.sonatype.com/artifact/com.unitvectory/jsonschema4springboot) [![javadoc](https://javadoc.io/badge2/com.unitvectory/jsonschema4springboot/javadoc.svg)](https://javadoc.io/doc/com.unitvectory/jsonschema4springboot) [![codecov](https://codecov.io/gh/UnitVectorY-Labs/jsonschema4springboot/graph/badge.svg?token=UJ2HAD30E7)](https://codecov.io/gh/UnitVectorY-Labs/jsonschema4springboot)\n\n# jsonschema4springboot\n\nAdd JSON Schema Validation to Spring Boot 3 with Annotations\n\n## Purpose\n\nThis library provides an annotation for deserializing JSON in Spring Boot 3 to include JSON Schema validation as part of the process using the [networknt/json-schema-validator](https://github.com/networknt/json-schema-validator) library. This replaces the `@RequestBody` annotation with the `@ValidateJsonSchema` annotation that allows the JSON Schema to be specified for a specific payload when parsing it into an object.\n\nThis is an opinionated design first approach to implementing the APIs where the input validation logic lives in the JSON Schema instead of in the Java code. While the JSON Schema and POJO are not validated against one another, the flexible input validation provided by a JSON Schema is intended to reduce the complexity of the API implementation.\n\n## Getting Started\n\nThis library requires Java 17 and Spring Boot 3 and is available in the Maven Central Repository:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.unitvectory\u003c/groupId\u003e\n    \u003cartifactId\u003ejsonschema4springboot\u003c/artifactId\u003e\n    \u003cversion\u003e0.0.5\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\nFor a Spring Boot 3 project to utilize the `@ValidateJsonSchema` annotation the `ValidateJsonSchemaArgumentResolver` class must be registered with Spring Boot using the `addArgumentResolvers` method. This can be accomplished with the following code.\n\n```java\npackage example;\n\nimport java.util.List;\nimport org.springframework.context.annotation.Configuration;\nimport org.springframework.web.servlet.config.annotation.WebMvcConfigurer;\nimport com.unitvectory.jsonschema4springboot.ValidateJsonSchemaArgumentResolver;\nimport org.springframework.web.method.support.HandlerMethodArgumentResolver;\n\n@Configuration\npublic class JsonValidationConfiguration implements WebMvcConfigurer {\n\n    @Override\n    public void addArgumentResolvers(\n            @SuppressWarnings(\"null\") List\u003cHandlerMethodArgumentResolver\u003e resolvers) {\n        resolvers.add(ValidateJsonSchemaArgumentResolver.newInstance());\n    }\n}\n```\n\nEach request can have a schema defined, in this example the schema is located at `src/main/resources/jsonschema.json`. While this example shows a draft-07 JSON Schema example, all versions of JSON Schema supported by [networknt/json-schema-validator](https://github.com/networknt/json-schema-validator) can be used.\n\n```json\n{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"value\": {\n      \"type\": \"string\",\n      \"pattern\": \"^[a-zA-Z0-9]+$\"\n    }\n  },\n  \"required\": [\"value\"],\n  \"additionalProperties\": false\n}\n```\n\nThe following example shows a controller that utilizies the prior JSON Schema with a nominal API implementation.\n\n```java\npackage example;\n\nimport org.springframework.http.MediaType;\nimport org.springframework.web.bind.annotation.PostMapping;\nimport org.springframework.web.bind.annotation.RestController;\nimport com.unitvectory.jsonschema4springboot.ValidateJsonSchemaVersion;\nimport com.unitvectory.jsonschema4springboot.ValidateJsonSchema;\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@RestController\npublic class ExampleController {\n\n    @PostMapping(path = \"/example\", consumes = MediaType.APPLICATION_JSON_VALUE,\n            produces = MediaType.APPLICATION_JSON_VALUE)\n    public ExampleResponse example(@ValidateJsonSchema(version = ValidateJsonSchemaVersion.V7,\n            schemaPath = \"classpath:jsonschema.json\") ExampleRequest request) {\n        // Trivial API example\n        return new ExampleResponse(request.getValue().length());\n    }\n\n    @Data\n    @NoArgsConstructor\n    @AllArgsConstructor\n    public static class ExampleRequest {\n        private String value;\n    }\n\n    @Data\n    @NoArgsConstructor\n    @AllArgsConstructor\n    public static class ExampleResponse {\n        private int length;\n    }\n}\n```\n\nIn the case the JSON Schema does not validate a `ValidateJsonSchemaException` will be thrown which can be mapped to an API response. The `ValidateJsonSchemaFailedResponse` class is provided and provides a simple error object listing the JSON Schema validation errors.\n\n```json\n{\n  \"message\": \"JSON validation failed\",\n  \"details\": [\"$: required property 'value' not found\"]\n}\n```\n\nTo return this error an exception mapper must be provided. However, this is flexible and a different error structure can be used specific to an implementation.\n\n```java\npackage example;\n\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.web.bind.annotation.ControllerAdvice;\nimport org.springframework.web.bind.annotation.ExceptionHandler;\nimport com.unitvectory.jsonschema4springboot.ValidateJsonSchemaException;\nimport com.unitvectory.jsonschema4springboot.ValidateJsonSchemaFailedResponse;\n\n@ControllerAdvice\npublic class JsonValidationExceptionHandler {\n\n    @ExceptionHandler(ValidateJsonSchemaException.class)\n    public ResponseEntity\u003cValidateJsonSchemaFailedResponse\u003e onValidateJsonSchemaException(\n            ValidateJsonSchemaException ex) {\n        return ResponseEntity.badRequest().body(new ValidateJsonSchemaFailedResponse(ex));\n    }\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funitvectory-labs%2Fjsonschema4springboot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funitvectory-labs%2Fjsonschema4springboot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funitvectory-labs%2Fjsonschema4springboot/lists"}