{"id":18828527,"url":"https://github.com/zenwave360/json-schema-ref-parser-jvm","last_synced_at":"2026-03-06T18:03:18.003Z","repository":{"id":41573306,"uuid":"454518922","full_name":"ZenWave360/json-schema-ref-parser-jvm","owner":"ZenWave360","description":"Parse, Resolve, and Dereference JSON Schema $ref pointers for JVM","archived":false,"fork":false,"pushed_at":"2025-02-25T15:57:11.000Z","size":213,"stargazers_count":12,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T16:55:50.135Z","etag":null,"topics":["java","json-pointer","json-schema","resolver"],"latest_commit_sha":null,"homepage":"https://zenwave360.github.io/json-schema-ref-parser-jvm/","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/ZenWave360.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":"2022-02-01T19:16:17.000Z","updated_at":"2025-03-12T14:13:37.000Z","dependencies_parsed_at":"2023-11-15T12:27:07.731Z","dependency_job_id":"9c9bfee5-be7b-4a47-bac2-1e96b00f3be7","html_url":"https://github.com/ZenWave360/json-schema-ref-parser-jvm","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZenWave360%2Fjson-schema-ref-parser-jvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZenWave360%2Fjson-schema-ref-parser-jvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZenWave360%2Fjson-schema-ref-parser-jvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZenWave360%2Fjson-schema-ref-parser-jvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZenWave360","download_url":"https://codeload.github.com/ZenWave360/json-schema-ref-parser-jvm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813827,"owners_count":21165631,"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","json-pointer","json-schema","resolver"],"created_at":"2024-11-08T01:30:17.161Z","updated_at":"2026-03-06T18:03:17.994Z","avatar_url":"https://github.com/ZenWave360.png","language":"Java","readme":"JSON Schema $Ref Parser for the JVM\n=====================================\n\n[![Maven Central](https://img.shields.io/maven-central/v/io.zenwave360/json-schema-ref-parser-jvm.svg?label=Maven%20Central\u0026logo=apachemaven)](https://search.maven.org/artifact/io.github.zenwave360/json-schema-ref-parser-jvm)\n[![build](https://github.com/ZenWave360/json-schema-ref-parser-jvm/workflows/Build%20and%20Publish%20Maven%20Snapshots/badge.svg)](https://github.com/ZenWave360/json-schema-ref-parser-jvm/actions/workflows/publish-maven-snapshots.yml)\n[![coverage](https://raw.githubusercontent.com/ZenWave360/json-schema-ref-parser-jvm/badges/jacoco.svg)](https://github.com/ZenWave360/json-schema-ref-parser-jvm/actions/workflows/build.yml)\n[![branches coverage](https://raw.githubusercontent.com/ZenWave360/json-schema-ref-parser-jvm/badges/branches.svg)](https://github.com/ZenWave360/json-schema-ref-parser-jvm/actions/workflows/build.yml)\n[![GitHub](https://img.shields.io/github/license/ZenWave360/json-schema-ref-parser-jvm)](https://github.com/ZenWave360/json-schema-ref-parser-jvm/blob/main/LICENSE)\n\n\u003e **Note**: Starting with version 0.9.0, the Maven `groupId` has changed to `io.zenwave360`. The code remains fully compatible.\n\nParse, Resolve, and Dereference JSON Schema $ref pointers\n\nThis is a Java implementation of the wonderful Node.js [JSON Schema $Ref Parser](https://apidevtools.com/json-schema-ref-parser/).\n\nIt also calculates [json-path -\u003e to file location range](#calculate-json-path---to-file-location-range) for parsed files inspired in [@stoplight/yaml](https://github.com/stoplightio/yaml)\n\nIt even supports loading files and references from the classpath! (just use `classpath:org/foo/bar.json`)\n\nThe Problem:\n--------------------------\n\nIf you need to parse a JSON/Yaml based specification that uses JSON Pointers as ($ref) references like JSON Schema, OpenAPI or AsyncAPI and you find yourself writing yet another ad hoc JSON Schema parser... we got you covered!\n\nJSON Schema $Ref Parser for Java is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) returning a simple Map of nodes. Results include also for convenience a [Jayway JSONPath JsonContext](https://github.com/json-path/JsonPath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java) for reading, transversing and filtering the resulting schema.\n\nExample:\n--------------------------\n\n```javascript\n{\n  \"definitions\": {\n    \"person\": {\n      // references an external file\n      \"$ref\": \"schemas/people/Bruce-Wayne.json\"\n    },\n    \"place\": {\n      // references a sub-schema in an external file\n      \"$ref\": \"schemas/places.yaml#/definitions/Gotham-City\"\n    },\n    \"thing\": {\n      // references a URL\n      \"$ref\": \"http://wayne-enterprises.com/things/batmobile\"\n    },\n    \"color\": {\n      // references a value in an external file via an internal reference\n      \"$ref\": \"#/definitions/thing/properties/colors/black-as-the-night\"\n    }\n  }\n}\n```\n\nSolution:\n--------------------------\n\n```java\nFile file = new File(\"src/test/resources/openapi/allOf.yml\");\n$RefParser parser = new $RefParser(file);\n$Refs refs = parser\n        .parse()\n        .dereference()\n        .mergeAllOf()\n        .getRefs();\nObject resultMapOrList = refs.schema();\n```\n\nSkip (leave unresolved) circular references:\n\n```java\n$RefParser parser = new $RefParser(file)\n        .withOptions(new $RefParserOptions().withOnCircular(SKIP));\n$Refs refs = parser.parse().dereference().getRefs();\nAssert.assertFalse(refs.circular);\n\n```\n\nWith authentication:\n\n```java\nFile file = new File(\"src/test/resources/openapi/http-external-refs.yml\");\n$RefParser parser = new $RefParser(file)\n        .withAuthentication(new AuthenticationValue()\n                .withHeader(\"Bearer\", \"\u003ctoken\u003e\")\n                .withUrlMatcher(url -\u003e url.getHost().equals(\"raw.githubusercontent.com\")))\n        .withOptions(new $RefParserOptions().withOnCircular(SKIP));\n$Refs refs = parser.parse().dereference().mergeAllOf().getRefs();\nObject resultMapOrList = refs.schema();\n```\n\nFrom classpath:\n\n```java\nURI uri = URI.create(\"classpath:/asyncapi/schemas/json-schemas-external-ref.yml\");\n$RefParser parser = new $RefParser(uri);\n$Refs refs = parser.parse().dereference().mergeAllOf().getRefs();\nObject resultMapOrList = refs.schema();\n```\n\nSkip missing resources:\n\n```java\nURI uri = URI.create(\"src/test/resources/openapi/openapi-missing.yml\");\n$RefParser parser = new $RefParser(uri)\n        .withOptions(new $RefParserOptions().withOnMissing(OnMissing.SKIP));\n$Refs refs = parser.parse().dereference().mergeAllOf().getRefs();\nObject resultMapOrList = refs.schema();\n```\n\nCalculate json-path -\u003e to file location range:\n--------------------------\n\n```java\nFile file = new File(\"src/test/resources/openapi/allOf.yml\");\n$RefParser parser = new $RefParser(file).parse();\nPair\u003cJsonLocation, JsonLocation\u003e locationRange = parser.getRefs().getJsonLocationRange(\"$.info\");\nint startLine = locationRange.getLeft().getLineNr();\nint endLine = locationRange.getRight().getLineNr();\n```\n\nInstallation:\n--------------------------\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.zenwave360\u003c/groupId\u003e\n  \u003cartifactId\u003ejson-schema-ref-parser-jvm\u003c/artifactId\u003e\n  \u003cversion\u003e${json-schema-ref-parser-jvm.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nFeatures\n--------------------------\n- Use JSON, YAML or even Avro Schemas (avsc) — or even a mix of them!\n- Fully dereference your schema producing a simple Map of nodes\n- Caching: Results from remote URIs and local references are cached.\n- Reference equality: Maintains object reference equality — $ref pointers to the same value always resolve to the same object instance\n- Flexible: Bring your own readers for http://, file://, or use default ones.\n- It even supports loading files and references from the classpath! (just use `classpath:org/foo/bar.json`)\n- Authentication: Configure authentication headers or query parameters with url matchers.\n- Circular references: Detects circular references, and you can `resolve` them, `skip` leaving unresolved or just `fail`.\n- Merge `allOf` references into a single object.\n- Back References Map: consult anytime the original reference of a given node.\n- JsonPath: use [Jayway's JsonPath](https://github.com/json-path/JsonPath) to transverse/filter the resulting tree.\n\n\n# License\nJSON Schema $Ref Parser is 100% free and open-source, under the MIT license. Use it however you want.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenwave360%2Fjson-schema-ref-parser-jvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzenwave360%2Fjson-schema-ref-parser-jvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenwave360%2Fjson-schema-ref-parser-jvm/lists"}