{"id":28442350,"url":"https://github.com/torand/jsonschema2java","last_synced_at":"2026-04-30T19:31:46.260Z","repository":{"id":263838466,"uuid":"890365060","full_name":"torand/jsonschema2java","owner":"torand","description":"Maven plugin to generate Java models from JSON Schema files","archived":false,"fork":false,"pushed_at":"2026-03-28T15:46:18.000Z","size":362,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-28T17:55:07.859Z","etag":null,"topics":["code-generation","contract-first","java","json-schema","kotlin","maven-plugin"],"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/torand.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-18T12:55:11.000Z","updated_at":"2026-03-28T15:46:18.000Z","dependencies_parsed_at":"2025-02-03T10:25:07.481Z","dependency_job_id":"e2545972-e5a0-42e8-8914-8cf97396c412","html_url":"https://github.com/torand/jsonschema2java","commit_stats":null,"previous_names":["torand/jsonschema2java"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/torand/jsonschema2java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torand%2Fjsonschema2java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torand%2Fjsonschema2java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torand%2Fjsonschema2java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torand%2Fjsonschema2java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/torand","download_url":"https://codeload.github.com/torand/jsonschema2java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torand%2Fjsonschema2java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32475191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["code-generation","contract-first","java","json-schema","kotlin","maven-plugin"],"created_at":"2025-06-06T06:00:46.089Z","updated_at":"2026-04-30T19:31:46.253Z","avatar_url":"https://github.com/torand.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"JSONSchema2Java\n===============\n\n[![CI](https://github.com/torand/jsonschema2java/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/torand/jsonschema2java/actions/workflows/continuous-integration.yml)\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.torand/jsonschema2java.svg?label=maven%20central)](https://central.sonatype.com/artifact/io.github.torand/jsonschema2java)\n[![Javadoc](https://img.shields.io/badge/javadoc-online-green)](https://torand.github.io/jsonschema2java/apidocs/)\n[![Coverage](https://coveralls.io/repos/github/torand/jsonschema2java/badge.svg?branch=main)](https://coveralls.io/github/torand/jsonschema2java?branch=main)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=torand_jsonschema2java\u0026metric=alert_status)](https://sonarcloud.io/summary/overall?id=torand_jsonschema2java)\n[![Apache 2.0 License](https://img.shields.io/badge/license-Apache%202.0-orange)](LICENSE)\n\nA Maven plugin to generate Java source code (POJOs) from [JSON Schema](https://json-schema.org/) files.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Type Mapping](#type-mapping)\n- [Constraint Mapping](#constraint-mapping)\n- [Guidelines](#guidelines)\n- [Limitations](#Limitations)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nInclude this Maven plugin in any Java project processing JSON payloads to enable a [Contract First](https://dzone.com/articles/designing-rest-api-what-is-contract-first) build workflow.\nThe current version supports the JSON Schema specification version \"2020-12\".\n\nThe JSON Schema files are read, parsed and validated using the [networknt/json-schema-validator](https://github.com/networknt/json-schema-validator) library.\nFor each JSON Schema file a Java class or enum definition is written to a specified output directory.\n\nThe generated source code is compatible with Java 17+ and optionally includes annotations from the following libraries:\n\n* [Microprofile OpenAPI](https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html)\n* [Jakarta Bean Validation](https://jakarta.ee/specifications/bean-validation/)\n* [Jackson](https://github.com/FasterXML/jackson)\n\n## Usage\n\nThe package is available from the [Maven Central Repository](https://central.sonatype.com/artifact/io.github.torand/jsonschema2java).\n\n### Include in a Maven POM File\n\n```xml\n\u003cbuild\u003e\n  \u003cplugins\u003e\n    \u003cplugin\u003e\n      \u003cgroupId\u003eio.github.torand\u003c/groupId\u003e\n      \u003cartifactId\u003ejsonschema2java\u003c/artifactId\u003e\n      \u003cversion\u003e1.2.0\u003c/version\u003e\n      \u003cexecutions\u003e\n        \u003cexecution\u003e\n          \u003cid\u003egenerate\u003c/id\u003e\n          \u003cphase\u003egenerate-sources\u003c/phase\u003e\n          \u003cgoals\u003e\n            \u003cgoal\u003egenerate\u003c/goal\u003e\n          \u003c/goals\u003e\n        \u003c/execution\u003e\n      \u003c/executions\u003e\n      \u003cconfiguration\u003e\n        \u003csearchRootDir\u003e.\u003c/searchRootDir\u003e\n        \u003csearchFilePattern\u003e*.json\u003c/searchFilePattern\u003e\n        \u003cschemaIdRootUri\u003ehttps://my-domain.com/my-api/schemas\u003c/schemaIdRootUri\u003e\n        \u003coutputDir\u003etarget/jsonschema2java\u003c/outputDir\u003e\n        \u003crootPackage\u003eio.github.torand.mymodel\u003c/rootPackage\u003e\n      \u003c/configuration\u003e\n    \u003c/plugin\u003e\n  \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n### Run from the Command Line\n\n```bash\n$ mvn io.github.torand:jsonschema2java:1.2.0:generate \\\n  -DsearchRootDir=. \\\n  -DsearchFilePattern=*.json \\\n  -DschemaIdRootUri=https://my-domain.com/my-api/schemas \\\n  -DoutputDir=target/jsonschema2java \\\n  -DrootPackage=io.github.torand.mymodel\n```\n\n## Configuration\n\n| Parameter                           | Default                   | Description                                                                                                                         |\n|-------------------------------------|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------|\n| searchRootDir                       | Project root dir          | Root directory to search for schema files                                                                                           |\n| searchFilePattern                   |                           | Schema file path search pattern. Supports [glob](https://github.com/begin/globbing/blob/master/cheatsheet.md) patterns              |\n| schemaIdRootUri                     |                           | Root URI of $id property in schema files. Path elements beyond this value must correspond to subdirectories inside 'searchRootDir'. |\n| outputDir                           | Project build dir         | Directory to write POJO source code files to                                                                                        |\n| rootPackage                         |                           | Root package path of output POJO classes and enums                                                                                  |\n| pojoNameSuffix                      | \"Dto\"                     | Suffix for POJO class and enum names                                                                                                |\n| pojosAsRecords                      | true                      | Whether to output Java records instead of Java classes                                                                              |\n| durationClassName                   | \"java.time.Duration\"      | Fully qualified name of the class to represent schemas of type \"string\" and format \"duration\" in generated code                     |\n| dateClassName                       | \"java.time.LocalDate\"     | Fully qualified name of the class to represent schemas of type \"string\" and format \"date\" in generated code                         |\n| dateTimeClassName                   | \"java.time.LocalDateTime\" | Fully qualified name of the class to represent schemas of type \"string\" and format \"date-time\" in generated code                    |\n| addMpOpenApiAnnotations             | false                     | Whether to generate model files with Microprofile OpenAPI schema annotations                                                        |\n| addJsonPropertyAnnotations          | true                      | Whether to generate model files with JSON property annotations                                                                      |\n| addJakartaBeanValidationAnnotations | true                      | Whether to generate model files with Jakarta Bean Validation annotations                                                            |\n| useKotlinSyntax                     | false                     | Whether to generate model files with Kotlin syntax                                                                                  |\n| indentWithTab                       | false                     | Whether to output indents with the tab character                                                                                    |\n| indentSize                          | 4                         | Number of spaces in one indentation level. Relevant only when 'indentWithTab' is false.                                             |\n| verbose                             | false                     | Whether to log extra details                                                                                                        |\n\n## Type Mapping\n\nJSON schema types and formats map to the following Java and Kotlin types in generated source code:\n\n| Type                                         | Format            | Java type                    | Kotlin type                 |\n|----------------------------------------------|-------------------|------------------------------|-----------------------------|\n| \"array\"                                      | N/A               | java.util.List               | java.util.List              |\n| \"array\" with \"uniqueItems\" = true            | N/A               | java.util.Set                | java.util.Set               |\n| \"boolean\"                                    | N/A               | Boolean                      | Boolean                     |\n| \"integer\"                                    |                   | Integer                      | Int                         |\n| \"integer\"                                    | \"int32\"           | Integer                      | Int                         |\n| \"integer\"                                    | \"int64\"           | Long                         | Long                        |\n| \"number\"                                     |                   | java.math.BigDecimal         | java.math.BigDecimal        |\n| \"number\"                                     | \"double\"          | Double                       | Double                      |\n| \"number\"                                     | \"float\"           | Float                        | Float                       |\n| \"object\"                                     | N/A               | [^1]                         | [^1]                        |\n| \"object\" with \"additionalProperties\" = {...} | N/A               | java.util.Map                | java.util.Map               |\n| \"string\"                                     |                   | String                       | String                      |\n| \"string\"                                     | \"uri\"             | java.net.URI                 | java.net.URI                |\n| \"string\"                                     | \"uuid\"            | java.util.UUID               | java.util.UUID              |\n| \"string\"                                     | \"duration\"[^2]    | java.time.Duration[^5]       | java.time.Duration[^5]      |\n| \"string\"                                     | \"date\"[^3]        | java.time.LocalDate[^6]      | java.time.LocalDate[^6]     |\n| \"string\"                                     | \"date-time\"[^4]   | java.time.LocalDateTime[^7]  | java.time.LocalDateTime[^7] |\n| \"string\"                                     | \"binary\"          | byte[]                       | ByteArray                   |\n| \"string\"                                     | All other formats | String                       | String                      |\n\n[^1]: Inline objects not supported.\n[^2]: Expects string in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) duration format.\n[^3]: Expects string in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) local date format.\n[^4]: Expects string in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) local date time format (without milliseconds).\n[^5]: Can be overridden using the 'durationClassName' configuration parameter.\n[^6]: Can be overridden using the 'dateClassName' configuration parameter.\n[^7]: Can be overridden using the 'dateTimeClassName' configuration parameter.\n\n## Constraint Mapping\n\nJSON schema restriction properties map to the following Jakarta Bean Validation annotations (when enabled):\n\n| Type      | Restriction                         | Annotation                |\n|-----------|-------------------------------------|---------------------------|\n| \"array\"   |                                     | @Valid                    |\n| \"array\"   | Not nullable                        | @Valid @NotNull           |\n| \"array\"   | \"minItems\": n                       | @Valid @Size(min = n)     |\n| \"array\"   | \"maxItems\": n                       | @Valid @Size(max = n)     |\n| \"boolean\" | Not nullable                        | @NotNull                  |\n| \"integer\" | Not nullable                        | @NotNull                  |\n| \"integer\" | \"minimum\": n                        | @Min(n)                   |\n| \"integer\" | \"maximum\": n                        | @Max(n)                   |\n| \"number\"  | Not nullable                        | @NotNull                  |\n| \"number\"  | \"minimum\": n[^5]                    | @Min(n)                   |\n| \"number\"  | \"maximum\": n[^5]                    | @Max(n)                   |\n| \"object\"  |                                     | @Valid                    |\n| \"object\"  | Not nullable                        | @Valid @NotNull           |\n| \"string\"  | Not nullable                        | @NotBlank                 |\n| \"string\"  | Not nullable and \"format\": \"binary\" | @NotEmpty                 |\n| \"string\"  | \"pattern\": \"expr\"                   | @Pattern(regexp = \"expr\") |\n| \"string\"  | \"minLength\": n                      | @Size(min = n)            |\n| \"string\"  | \"maxLength\": n                      | @Size(max = n)            |\n| \"string\"  | \"format\": \"email\"                   | @Email                    |\n\n[^5]: When \"format\" is unspecified (i.e. BigDecimal).\n\n## Guidelines\n\n### General\n\nRelaxed, abstract schemas are useful for validation, not so much for code generation. As a general rule, to produce meaningful POJOs, strict schemas are necessary.\nHence, the \"type\" property is mandatory.\n\n### Ids and Refs\n\nAlways use absolute URIs for \"$id\" and \"$ref\"  properties, e.g. \"https://my-domain.com/my-api/schemas/my-entity\".\nRelative URIs are [discouraged](https://json-schema.org/understanding-json-schema/structuring#id) by the official JSON Schema documentation,\nand therefore not supported by this project.  \n\n### Customizing Code Generation\n\nThe code generation can be customized per JSON Schema by using the following extension properties in the schema definition:\n\n| Extension property      | Type    | Allowed where                                             | Description                                                                                                                                                                        |\n|-------------------------|---------|-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| x-json-serializer       | String  | In a property schema                                      | Fully qualified classname of a Jackson serializer class for the property                                                                                                           |\n| x-json-deserializer     | String  | In a property schema                                      | Fully qualified classname of a Jackson deserializer class for the property                                                                                                         |\n| x-json-format           | String  | In a schema of type \"string\", format \"date\" or date-time\" | Custom [date/time format pattern](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/SimpleDateFormat.html) for Jackson java.time.* deserializers/serializers  |\n| x-validation-constraint | String  | In a property schema                                      | Fully qualified classname of an annotation class to validate the property                                                                                                          |\n| x-nullable              | Boolean | In a property schema                                      | If `true` the type of the property can be `null`                                                                                                                                   |\n| x-model-subdir          | String  | In an enum or object schema                               | Subdirectory to place the generated DTO model classes                                                                                                                              |\n| x-deprecation-message   | String  | Everywhere `deprecated` can be used                       | Describing why something is deprecated, and what to use instead                                                                                                                    |\n\n### Nullability\n\nMandatory properties are (optionally) decorated with @NonNull and similar Jakarta Bean Validation annotations during code generation.\nFor a JSON Schema property to be considered mandatory, i.e. present and with a non-null value, it must be mentioned in the \"required\" list\nAND NOT have a \"nullable\" indicator.\n\nThe standard way to represent mandatory properties is as follows:\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://my-domain.com/my-api/schemas/person\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\"\n    },\n    \"address\": {\n      \"$ref\": \"https://my-domain.com/my-api/schemas/address\"\n    }\n  },\n  \"required\": [ \"name\", \"address\" ]\n}\n```\n\nCorrespondingly, the standard way to represent non-mandatory (nullable) properties is like this:\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://my-domain.com/my-api/schemas/person\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": [\"string\", \"null\"]\n    },\n    \"address\": {\n      \"oneOf\": [\n        {\n          \"$ref\": \"https://my-domain.com/my-api/schemas/address\"\n        },\n        {\n          \"type\": \"null\"\n        }\n      ]\n    }\n  },\n  \"required\": []\n}\n```\n\nNote the use of \"OneOf\" to express a nullable object reference.\n\nFor convenience, a non-standard [schema extension](#customizing-code-generation) is available to express nullability uniformly regardless of property type:\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://my-domain.com/my-api/schemas/person\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\",\n      \"x-nullable\": true\n    },\n    \"address\": {\n      \"$ref\": \"https://my-domain.com/my-api/schemas/address\",\n      \"x-nullable\": true\n    }\n  },\n  \"required\": []\n}\n```\n\n### Inheritance\n\nInheritance is not supported, nor has JSON Schema such a construct. Inheritance can be \"simulated\" with composition using \"allOf\" on the root schema:\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://my-domain.com/my-api/schemas/vehicle\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"brand\": {\n      \"type\": \"string\"\n    }\n  },\n  \"required\": [ \"brand\" ]\n}\n```\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://my-domain.com/my-api/schemas/car\",\n  \"allOf\" : [\n    {\n      \"$ref\": \"https://my-domain.com/my-api/schemas/vehicle\"\n    },\n    {\n      \"type\": \"object\",\n      \"properties\": {\n        \"doors\": {\n          \"type\": \"integer\"\n        }\n      },\n      \"required\": [ \"doors\" ]\n    }\n  ]\n}\n```\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://my-domain.com/my-api/schemas/motor-cycle\",\n  \"allOf\" : [\n    {\n      \"$ref\": \"https://my-domain.com/my-api/schemas/vehicle\"\n    },\n    {\n      \"type\": \"object\",\n      \"properties\": {\n        \"sidekick\": {\n          \"type\": \"boolean\"\n        }\n      },\n      \"required\": [ \"sidekick\" ]\n    }\n  ]\n}\n```\n\nThis produces the following Java records:\n\n```java\npublic record VehicleDto (\n    @NotBlank String brand\n) {}\n```\n```java\npublic record CarDto (\n    @NotBlank String brand,\n    @NotNull Integer doors\n) {}\n```\n```java\npublic record MotorCycleDto (\n    @NotBlank String brand,\n    @NotNull Boolean sidekick\n) {}\n```\n\nNote that this is not the correct interpretation of the \"allOf\" clause in a JSON Schema,\nand as such, the output from the code generation is non-standard. A future release will support [inheritance using the \"$ref\" property](https://json-schema.org/blog/posts/modelling-inheritance).\n\n## Limitations\n\nThe following JSON Schema constructs are currently not supported, and for the most part silently ignored during code generation:\n\n* Restrictions on the \"number\" type: \"multipleOf\".\n* Properties with \"const\".\n* \"string\" properties with: \"contentMediaType\", \"contentEncoding\", \"contentSchema\".\n* Dynamic objects: \"if\", \"then\", \"unevaluatedProperties\".\n* Nested inline objects. Creating a separate JSON Schema and referencing it with \"$ref\" is recommended.\n* Extended schema validation features: \"patternProperties\", \"propertyNames\", \"minProperties\", \"maxProperties\".\n* Restrictions on arrays: tuple validation with \"prefixItems\".\n* Dynamic arrays: \"unevaluatedItems\", \"contains\", \"minContains\", \"maxContains\".\n* Documentation: \"readOnly\", \"writeOnly\".\n* Property schema composition: \"allOf\", \"anyOf\", \"not\". Only supports two subschemas for \"oneOf\", one of which must be {\"type\": \"null\"}.\n* Conditional subschemas: \"dependentRequired\", \"dependentSchemas\", \"if\"-\"then\"-\"else\".\n* Structuring: \"$anchor\", \"$defs\", recursion using \"$ref\".\n\n## Contributing\n\n1. Fork it (https://github.com/torand/jsonschema2java/fork)\n2. Create your feature branch (git checkout -b feature/fooBar)\n3. Commit your changes (git commit -am 'Add some fooBar')\n4. Push to the branch (git push origin feature/fooBar)\n5. Create a new Pull Request\n\n## License\n\nThis project is licensed under the [Apache-2.0 License](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorand%2Fjsonschema2java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftorand%2Fjsonschema2java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorand%2Fjsonschema2java/lists"}