README.md

JSON Referencing Test Suite

This repository contains a set of JSON objects that implementers of JSON referencing specifications can use to test their implementations.

It is meant to be language agnostic and should require only a JSON parser. The conversion of the JSON objects into tests within a specific language and test framework of choice is left to be done by the implementer.

This suite is inspired by the official JSON Schema Test Suite, where some of its tests originated. Indeed JSON referencing is heavily influenced by JSON Schema, and it is only recently that discussions have begun to formalize JSON referencing in a more cross-specification-amenable way.

Structure of the Suite

The tests directory contains a set of folders corresponding to each specification which is tested by this suite.

Currently, this covers all modern JSON Schema specifications (notably, not yet OpenAPI specifications). A specifications.json file is also included which maps each folder to a URL which identifies the specification (for JSON Schema these are known as "dialect ID"s).

Within each directory are tests corresponding to the particular specification. Below is an example of such a test file, followed by a description of how to interpret the test.

{
  "$schema": "../../test-schema.json",
  "registry": {
    "http://example.com/": {
      "definitions": {
        "foo": {
          "$id": "#foo",
          "foo": "bar"
        }
      }
    }
  },
  "tests": [
    {
      "base_uri": "http://example.com/",
      "ref": "#foo",
      "target": {
        "$id": "#foo",
        "foo": "bar"
      }
    }
  ]
}

Ignore the $schema property, it simply denotes that each test file satisfies a JSON Schema found at the given path. The registry property contains a mapping between URIs and documents which are expected to be available for the duration of the tests. The tests are found in the tests array, and each object within the array contain:

• a ref key which is a reference to be resolved, along with an optional base URI to use to resolve a relative reference against

• either of a target key which is the expected result of resolving the reference (taking into account the registry), or contain the key error, indicating that resolving the reference should produce some sort of error (because the reference is broken or somehow invalid)

• an optional then key, which itself is a further test (recursively), and which is meant to be resolved statefully given the result of parent tests