Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zenwave360/json-schema-ref-parser-jvm
Parse, Resolve, and Dereference JSON Schema $ref pointers for JVM
https://github.com/zenwave360/json-schema-ref-parser-jvm
java json-pointer json-schema resolver
Last synced: about 13 hours ago
JSON representation
Parse, Resolve, and Dereference JSON Schema $ref pointers for JVM
- Host: GitHub
- URL: https://github.com/zenwave360/json-schema-ref-parser-jvm
- Owner: ZenWave360
- License: mit
- Created: 2022-02-01T19:16:17.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-06T10:54:51.000Z (2 days ago)
- Last Synced: 2024-11-06T11:44:38.467Z (2 days ago)
- Topics: java, json-pointer, json-schema, resolver
- Language: Java
- Homepage: https://zenwave360.github.io/json-schema-ref-parser-jvm/
- Size: 188 KB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
JSON Schema $Ref Parser for the JVM
=====================================
[](https://search.maven.org/artifact/io.github.zenwave360/json-schema-ref-parser-jvm)
[](https://github.com/ZenWave360/json-schema-ref-parser-jvm/releases)
[](https://github.com/ZenWave360/json-schema-ref-parser-jvm/actions/workflows/build.yml)
[](https://github.com/ZenWave360/json-schema-ref-parser-jvm/actions/workflows/build.yml)
[](https://github.com/ZenWave360/json-schema-ref-parser-jvm/actions/workflows/build.yml)
[](https://github.com/ZenWave360/json-schema-ref-parser-jvm/blob/main/LICENSE)
Parse, Resolve, and Dereference JSON Schema $ref pointers
This is a Java implementation of the wonderful Node.js [JSON Schema $Ref Parser](https://apitools.dev/json-schema-ref-parser/).
It also calculates [json-path -> to file location range](#calculate-json-path---to-file-location-range) for parsed files inspired in [@stoplight/yaml](https://github.com/stoplightio/yaml)
It even supports loading files and references from the classpath! (just use `classpath:org/foo/bar.json`)
The Problem:
--------------------------
If 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!
JSON 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.
Example:
--------------------------
```javascript
{
"definitions": {
"person": {
// references an external file
"$ref": "schemas/people/Bruce-Wayne.json"
},
"place": {
// references a sub-schema in an external file
"$ref": "schemas/places.yaml#/definitions/Gotham-City"
},
"thing": {
// references a URL
"$ref": "http://wayne-enterprises.com/things/batmobile"
},
"color": {
// references a value in an external file via an internal reference
"$ref": "#/definitions/thing/properties/colors/black-as-the-night"
}
}
}
```
Solution:
--------------------------
```java
File file = new File("src/test/resources/openapi/allOf.yml");
$RefParser parser = new $RefParser(file);
$Refs refs = parser
.parse()
.dereference()
.mergeAllOf()
.getRefs();
Object resultMapOrList = refs.schema();
```
Skip (leave unresolved) circular references:
```java
$RefParser parser = new $RefParser(file)
.withOptions(new $RefParserOptions().withOnCircular(SKIP));
$Refs refs = parser.parse().dereference().getRefs();
Assert.assertFalse(refs.circular);
```
With authentication:
```java
File file = new File("src/test/resources/openapi/http-external-refs.yml");
$RefParser parser = new $RefParser(file)
.withAuthentication(new AuthenticationValue()
.withHeader("Bearer", "")
.withUrlMatcher(url -> url.getHost().equals("raw.githubusercontent.com")))
.withOptions(new $RefParserOptions().withOnCircular(SKIP));
$Refs refs = parser.parse().dereference().mergeAllOf().getRefs();
Object resultMapOrList = refs.schema();
```
From classpath:
```java
URI uri = URI.create("classpath:/asyncapi/schemas/json-schemas-external-ref.yml");
$RefParser parser = new $RefParser(uri);
$Refs refs = parser.parse().dereference().mergeAllOf().getRefs();
Object resultMapOrList = refs.schema();
```
Skip missing resources:
```java
URI uri = URI.create("src/test/resources/openapi/openapi-missing.yml");
$RefParser parser = new $RefParser(uri)
.withOptions(new $RefParserOptions().withOnMissing(OnMissing.SKIP));
$Refs refs = parser.parse().dereference().mergeAllOf().getRefs();
Object resultMapOrList = refs.schema();
```
Calculate json-path -> to file location range:
--------------------------
```java
File file = new File("src/test/resources/openapi/allOf.yml");
$RefParser parser = new $RefParser(file).parse();
Pair locationRange = parser.getRefs().getJsonLocationRange("$.info");
int startLine = locationRange.getLeft().getLineNr();
int endLine = locationRange.getRight().getLineNr();
```
Installation:
--------------------------
```xml
io.github.zenwave360
json-schema-ref-parser-jvm
${json-schema-ref-parser-jvm.version}
```
Features
--------------------------
- Use JSON, YAML or even Avro Schemas (avsc) — or even a mix of them!
- Fully dereference your schema producing a simple Map of nodes
- Caching: Results from remote URIs and local references are cached.
- Reference equality: Maintains object reference equality — $ref pointers to the same value always resolve to the same object instance
- Flexible: Bring your own readers for http://, file://, or use default ones.
- It even supports loading files and references from the classpath! (just use `classpath:org/foo/bar.json`)
- Authentication: Configure authentication headers or query parameters with url matchers.
- Circular references: Detects circular references, and you can `resolve` them, `skip` leaving unresolved or just `fail`.
- Merge `allOf` references into a single object.
- Back References Map: consult anytime the original reference of a given node.
- JsonPath: use [Jayway's JsonPath](https://github.com/json-path/JsonPath) to transverse/filter the resulting tree.
# License
JSON Schema $Ref Parser is 100% free and open-source, under the MIT license. Use it however you want.