{"id":25677896,"url":"https://github.com/cosium/json-schema-to-java-record","last_synced_at":"2025-02-24T15:27:32.808Z","repository":{"id":277893662,"uuid":"933322114","full_name":"Cosium/json-schema-to-java-record","owner":"Cosium","description":"An annotation processor converting JSON schemas to java records.","archived":false,"fork":false,"pushed_at":"2025-02-24T06:49:13.000Z","size":62,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-24T07:37:17.399Z","etag":null,"topics":["annotation-processing","annotation-processor","json-schema"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cosium.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,"publiccode":null,"codemeta":null}},"created_at":"2025-02-15T17:20:57.000Z","updated_at":"2025-02-24T06:49:09.000Z","dependencies_parsed_at":"2025-02-16T20:38:21.746Z","dependency_job_id":"7e9a66ba-4eef-4306-b7ce-8d64cb607bc3","html_url":"https://github.com/Cosium/json-schema-to-java-record","commit_stats":null,"previous_names":["cosium/json-schema-to-java-record"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cosium%2Fjson-schema-to-java-record","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cosium%2Fjson-schema-to-java-record/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cosium%2Fjson-schema-to-java-record/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cosium%2Fjson-schema-to-java-record/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cosium","download_url":"https://codeload.github.com/Cosium/json-schema-to-java-record/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240502637,"owners_count":19811845,"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":["annotation-processing","annotation-processor","json-schema"],"created_at":"2025-02-24T15:27:32.003Z","updated_at":"2025-02-24T15:27:32.803Z","avatar_url":"https://github.com/Cosium.png","language":"Java","readme":"[![Build Status](https://github.com/Cosium/json-schema-to-java-record/actions/workflows/ci.yml/badge.svg)](https://github.com/Cosium/json-schema-to-java-record/actions/workflows/ci.yml)\n[![Maven Central Version](https://img.shields.io/maven-central/v/com.cosium.json_schema_to_java_record/json-schema-to-java-record)](https://central.sonatype.com/artifact/com.cosium.json_schema_to_java_record/json-schema-to-java-record)\n\n# JSON Schema To Java Record\n\nAn annotation processor converting JSON schemas to java records.\n\n# Quick start\n\n1. Import the API:\n   ```xml\n   \u003cdependencies\u003e\n     \u003c!-- ... --\u003e\n     \u003cdependency\u003e\n       \u003cgroupId\u003ecom.cosium.json_schema_to_java_record\u003c/groupId\u003e\n       \u003cartifactId\u003ejson-schema-to-java-record-api\u003c/artifactId\u003e\n       \u003cversion\u003e${json-schema-to-java-record.version}\u003c/version\u003e\n       \u003cscope\u003eprovided\u003c/scope\u003e\n     \u003c/dependency\u003e\n     \u003c!-- ... --\u003e\n   \u003c/dependencies\u003e\n   ```\n2. Import the annotation processor:\n   ```xml\n   \u003cplugin\u003e\n     \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n     \u003cartifactId\u003emaven-compiler-plugin\u003c/artifactId\u003e\n     \u003cconfiguration\u003e\n       \u003cannotationProcessorPaths\u003e\n         \u003cpath\u003e\n           \u003cgroupId\u003ecom.cosium.json_schema_to_java_record\u003c/groupId\u003e\n           \u003cartifactId\u003ejson-schema-to-java-record\u003c/artifactId\u003e\n           \u003cversion\u003e${json-schema-to-java-record.version}\u003c/version\u003e\n         \u003c/path\u003e\n       \u003c/annotationProcessorPaths\u003e\n     \u003c/configuration\u003e\n   \u003c/plugin\u003e\n   ```\n3. Add your JSON schema files to the class path:\n   ```\n   src/main/resources/com/aqme\n   └── customer.json\n   ```\n   ```json\n   {\n     \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n     \"$id\": \"customer\",\n     \"type\": \"object\",\n     \"properties\": {\n       \"firstName\": {\n         \"type\": \"string\"\n       },\n       \"lastName\": {\n         \"type\": \"string\"\n       }\n     },\n     \"required\": [\n       \"firstName\",\n       \"lastName\"\n     ]\n   }\n   ```\n4. Annotate a `package-info.java` file like this:\n   ```java\n   @GenerateRecordsFromJsonSchemas(\n     schemaRootFileLocations =\n     @JsonSchemaFileLocation(\n       moduleAndPackage = \"com.aqme\",\n       relativeName = \"customer.json\"\n     )\n   )\n   package com.aqme;\n   \n   import com.cosium.json_schema_to_java_record_api.GenerateRecordsFromJsonSchemas;\n   import com.cosium.json_schema_to_java_record_api.JsonSchemaConfiguration;\n   import com.cosium.json_schema_to_java_record_api.JsonSchemaFileLocation;\n   ```\n5. Compile to generate this kind of output:\n   ```java\n   package com.aqme;\n   \n   import com.fasterxml.jackson.annotation.JsonInclude;\n   import com.fasterxml.jackson.annotation.JsonProperty;\n   import java.util.Objects;\n   import javax.annotation.processing.Generated;\n   import org.jspecify.annotations.NonNull;\n   import org.jspecify.annotations.Nullable;\n   \n   @JsonInclude(JsonInclude.Include.NON_NULL)\n   @Generated(\"com.cosium.json_schema_to_java_record_api.GenerateRecordsFromJsonSchemas\")\n   public record Customer(\n       @JsonProperty(\"firstName\") @NonNull String firstName,\n       @JsonProperty(\"lastName\") @NonNull String lastName) {\n     public Customer {\n       Objects.requireNonNull(firstName);\n       Objects.requireNonNull(lastName);\n     }\n   }\n   ```\n\n# Type mapping\n\n| JSON `type` | JSON `format` | JSON required | Java type                |\n|-------------|---------------|---------------|--------------------------|\n| object      |               |               | A java record            |\n| string      | date-time     |               | java.time.ZonedDateTime  |\n| string      | uri           |               | java.net.URI             |\n| string      |               |               | java.lang.String         |\n| array       |               |               | Immutable java.util.List |\n| number      |               | required      | double                   |\n| number      |               | non required  | java.lang.Double         |\n| integer     |               | required      | int                      |\n| integer     |               | non required  | java.lang.Integer        |\n| boolean     |               | required      | boolean                  |\n| boolean     |               | non required  | java.lang.Boolean        |\n| null        |               |               | java.lang.Void           |\n\n# JSON enum\n\nA schema having a non-null `enum` array will be converted to a java enum.\n\n# Java JSON binding\n\nRecord components will be annotated with [Jackson annotations](https://github.com/FasterXML/jackson-annotations) .\n\n# Nullability\n\nJSON schema [required](https://json-schema.org/understanding-json-schema/reference/object#required) is supported.\nBy default, a property is considered as nullable. If a property is part of JSON schema [required](https://json-schema.org/understanding-json-schema/reference/object#required) array, it will be considered as non-nullable.\n\n## JSpecify\n\nIf [JSpecify](https://jspecify.dev) nullness annotations (`@Nullable` and `@NonNull`) are part of the classpath,\nthey will be used to annotate generated java record components.\n\n## Array\n\nA non-null `array` will default to an empty immutable `java.util.List`.   \n\n# Builder\n\n## RecordBuilder\n\nIf [RecordBuilder](https://github.com/Randgalt/record-builder) annotation `io.soabase.recordbuilder.core.RecordBuilder` \nis part of the classpath, the former will be added to each generated java record.\n\n# $ref\n\nJSON schema [$ref](https://json-schema.org/understanding-json-schema/structuring#dollarref) is supported via the classpath \"protocol.\"\n\nThis allows you to have multiple JSON schema files referring to each other.\n\nAll `$ref` values should start with `classpath:`, followed by the absolute path to the referred JSON file like this:\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"address\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"country\": {\n      \"$ref\": \"classpath:/com/cosium/json_schema_to_java_record_tests/case1/country.json\"\n    }\n  }\n}\n```\n\n# Customization\n\nMost customizations rely on the JSON schema `$id` attribute (aka `schemaId` on the java API side).\nMake sure this attribute is valued and unique to benefit from customizations using it.\n\n## Forcing the Java type qualified name of a particular schema\n\nYou can ask a particular `schemaId`\nto be bound to an explicit Java type qualified name via `JsonSchemaConfiguration#javaTypeQualifiedName`.\n\nExample of JSON schema `country.json`:\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"country\",\n  \"enum\": [\"FRANCE\", \"MOROCCO\"]\n}\n```\n\nExample of configuration:\n```java\n@GenerateRecordsFromJsonSchemas(\n    schemaRootFileLocations =\n        @JsonSchemaFileLocation(\n            moduleAndPackage = \"com.cosium.json_schema_to_java_record_tests.case1\",\n            relativeName = \"country.json\"),\n    schemaConfigurations = \n      @JsonSchemaConfiguration(\n          schemaId = \"country\",\n          javaTypeQualifiedName = \"com.cosium.json_schema_to_java_record_tests.case1.Country\")\n    )\npackage com.cosium.json_schema_to_java_record_tests.case1;\n```\n\nExample of generated java class:\n```java\npackage com.cosium.json_schema_to_java_record_tests.case1;\n\nimport javax.annotation.processing.Generated;\n\n@Generated(\"com.cosium.json_schema_to_java_record_api.GenerateRecordsFromJsonSchemas\")\npublic enum Country {\n  FRANCE,\n  MOROCCO\n}\n\n```\n\n## Making a generated type implement interfaces\n\nYou can ask a generated Java type\nto implement a list of interfaces via `JsonSchemaConfiguration#javaInterfaceQualifiedNames`.\n\nExample of JSON schema `country.json`:\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"country\",\n  \"enum\": [\"FRANCE\", \"MOROCCO\"]\n}\n```\n\nExample of configuration:\n```java\n@GenerateRecordsFromJsonSchemas(\n    schemaRootFileLocations =\n        @JsonSchemaFileLocation(\n            moduleAndPackage = \"com.cosium.json_schema_to_java_record_tests.case1\",\n            relativeName = \"country.json\"),\n    schemaConfigurations =\n    @JsonSchemaConfiguration(\n            schemaId = \"country\",\n            javaInterfaceQualifiedNames =\n                    \"com.cosium.json_schema_to_java_record_tests.case1.Location\")\n    )\npackage com.cosium.json_schema_to_java_record_tests.case1;\n```\n\nExample of generated java class:\n```java\nimport com.cosium.json_schema_to_java_record_tests.case1.Location;\nimport javax.annotation.processing.Generated;\n\n@Generated(\"com.cosium.json_schema_to_java_record_api.GenerateRecordsFromJsonSchemas\")\npublic enum Country implements Location {\n   FRANCE,\n   MOROCCO\n}\n```\n\n## Report generation\n\nYou can ask for the creation of a Java class generation report\nby providing a non-empty value to `GenerateRecordsFromJsonSchemas#reportClassQualifiedName`.\n\nThe generated report class will contain:\n- A public constant `Map\u003cString, Class\u003e CLASS_BY_SCHEMA_ID` mapping each generated class to its JSON schema `$id`. If the latter was missing, there will be no entry in the Map.\n\nExample of configuration:\n```java\n@GenerateRecordsFromJsonSchemas(\n  schemaRootFileLocations =\n    @JsonSchemaFileLocation(\n      moduleAndPackage = \"com.cosium.json_schema_to_java_record_tests.case1\",\n      relativeName = \"customers.json\"\n    ),\n  reportClassQualifiedName = \"com.cosium.json_schema_to_java_record_tests.case1.Report\"   \n)\npackage com.aqme;\n```\n\nExample of generated report class:\n```java\npackage com.cosium.json_schema_to_java_record_tests.case1;\n\nimport java.lang.Class;\nimport java.lang.String;\nimport java.util.Map;\nimport javax.annotation.processing.Generated;\n\n@Generated(\"com.cosium.json_schema_to_java_record_api.GenerateRecordsFromJsonSchemas\")\npublic final class Report {\n  public static final Map\u003cString, Class\u003e CLASS_BY_SCHEMA_ID = Map.ofEntries(Map.entry(\"country\",Country.class),Map.entry(\"address\",Address.class),Map.entry(\"customers\",Customers.class),Map.entry(\"customer\",Customer.class));\n\n  private Report() {\n  }\n}\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosium%2Fjson-schema-to-java-record","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcosium%2Fjson-schema-to-java-record","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosium%2Fjson-schema-to-java-record/lists"}