Complete Example does not conform: wrong $schema, missing $uses, bare $ref in items

[clemensv]

The schema in Complete Example is not a conforming JSON Structure document. A reader who copies it gets five errors from the reference implementation, three of them on the very keywords the section exists to demonstrate.

$ json-structure-check --extended --allowimport library.struct.json
Schema is invalid:
 - #/definitions/Library/properties/authors/items/$ref [SCHEMA_REF_NOT_IN_TYPE] '$ref' is only permitted inside the 'type' attribute. Use { "type": { "$ref": "..." } } instead of { "$ref": "..." }
 - #/definitions/Library/properties/books/items/$ref [SCHEMA_REF_NOT_IN_TYPE] '$ref' is only permitted inside the 'type' attribute. Use { "type": { "$ref": "..." } } instead of { "$ref": "..." }
 - #/definitions/Author/identity [SCHEMA_ERROR] 'identity' requires JSONStructureRelations extension.
 - #/definitions/Book/identity [SCHEMA_ERROR] 'identity' requires JSONStructureRelations extension.
 - #/definitions/Book/relations [SCHEMA_ERROR] 'relations' requires JSONStructureRelations extension.

Three separate defects:

1. $schema names the Core meta-schema. The document is declared as

"$schema": "https://json-structure.org/meta/core/v0/#"

but it uses identity and relations, which Core does not define. It should name the extension meta-schema, https://json-structure.org/meta/relations/v0/#.

2. $uses is absent. Relations keywords are contributed by an add-in and have to be activated:

"$uses": ["JSONStructureRelations"]

Without it a validator rejects identity and relations even when $schema is correct. This is the point most likely to trip up a first-time reader, because nothing else in the document hints that the keywords need switching on, and no other section of the draft shows $uses in context.

3. items carries a bare $ref. Both collections are written

"items": { "$ref": "#/definitions/Author" }

Core requires items to hold a type declaration, so the reference belongs under type:

"items": { "type": { "$ref": "#/definitions/Author" } }

Fix

With those three changes the schema conforms, the instance document printed beneath it validates against it unchanged, and every relation in the instance resolves:

{
  "$schema": "https://json-structure.org/meta/relations/v0/#",
  "$id": "https://example.com/library",
  "$uses": ["JSONStructureRelations"],
  "$root": "#/definitions/Library",
  "definitions": {
    "Library": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "authors": {
          "type": "array",
          "items": { "type": { "$ref": "#/definitions/Author" } }
        },
        "books": {
          "type": "array",
          "items": { "type": { "$ref": "#/definitions/Book" } }
        }
      },
      "required": ["name", "authors", "books"]
    },
    "Author": {
      "type": "object",
      "properties": {
        "id": { "type": "uuid" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"],
      "identity": ["id"]
    },
    "Book": {
      "type": "object",
      "properties": {
        "isbn": { "type": "string" },
        "title": { "type": "string" }
      },
      "required": ["isbn", "title"],
      "identity": ["isbn"],
      "relations": {
        "authors": {
          "cardinality": "multiple",
          "targettype": { "$ref": "#/definitions/Author" },
          "scope": "#/definitions/Library/properties/authors"
        }
      }
    }
  }
}

$ json-structure-check --extended --allowimport library.struct.json
Schema is valid.
$ json-structure-validate --extended --allowimport library.json library.struct.json
Instance is valid.

Related

Every other schema fragment in the draft should be checked for the same three defects, since they are the kind of mistake that gets copied from section to section. The worked examples under samples/relations/ all carry the correct $schema and $uses and can serve as a reference.