JSON Schema $Ref Parser for the JVM

Parse, Resolve, and Dereference JSON Schema $ref pointers

This is a Java implementation of the wonderful Node.js JSON Schema $Ref Parser.

It also calculates json-path -> to file location range for parsed files inspired in @stoplight/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 and JSON Pointer implementation that crawls even the most complex JSON Schemas returning a simple Map of nodes. Results include also for convenience a Jayway JSONPath JsonContext for reading, transversing and filtering the resulting schema.

Example:

{
  "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:

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:

$RefParser parser = new $RefParser(file)
        .withOptions(new $RefParserOptions().withOnCircular(SKIP));
$Refs refs = parser.parse().dereference().getRefs();
Assert.assertFalse(refs.circular);

With authentication:

File file = new File("src/test/resources/openapi/http-external-refs.yml");
$RefParser parser = new $RefParser(file)
        .withAuthentication(new AuthenticationValue()
                .withHeader("Bearer", "<token>")
                .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:

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:

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:

File file = new File("src/test/resources/openapi/allOf.yml");
$RefParser parser = new $RefParser(file).parse();
Pair<JsonLocation, JsonLocation> locationRange = parser.getRefs().getJsonLocationRange("$.info");
int startLine = locationRange.getLeft().getLineNr();
int endLine = locationRange.getRight().getLineNr();

Installation:

<dependency>
  <groupId>io.github.zenwave360</groupId>
  <artifactId>json-schema-ref-parser-jvm</artifactId>
  <version>${json-schema-ref-parser-jvm.version}</version>
</dependency>

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 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.