Mechanism 2: $vocabulary Declaration

The $vocabulary keyword appears in meta-schemas to declare which vocabulary implementations a validator must support. It maps vocabulary URIs to boolean flags:

Flag	Meaning
true	Required — validator MUST implement this vocabulary
false	Optional — validator MUST ignore unknown keywords from this vocabulary

This is what makes the FAIR project’s extension backward-compatible: our custom vocabularies are typically declared as false (optional), meaning standard validators will treat them as simple annotations.

Specification

Detailed documentation of the vocabulary keyword and its implementation can be found in the SPEC.md.

Example

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://highvaluedata.net/fair-data-schema",
  "$vocabulary": {
    "https://json-schema.org/draft/2020-12/vocab/core": true,
    "https://json-schema.org/draft/2020-12/vocab/validation": true,
    "https://highvaluedata.net/fair-data-schema/vocab/annotations": false
  }
}

Working Example File

../../../examples/mechanism-2-vocabulary.json

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.org/schemas/mechanism-2-vocabulary",
    "title": "Mechanism 2: $vocabulary Declaration Example",
    "description": "This schema IS itself a meta-schema demonstrating $vocabulary usage. It declares standard 2020-12 vocabularies as required and the FAIR annotations vocabulary as optional. A validator that encounters this as a dialect $schema and does not implement the FAIR vocabulary will silently ignore fair: keywords.",
    "$vocabulary": {
        "https://json-schema.org/draft/2020-12/vocab/core": true,
        "https://json-schema.org/draft/2020-12/vocab/applicator": true,
        "https://json-schema.org/draft/2020-12/vocab/unevaluated": true,
        "https://json-schema.org/draft/2020-12/vocab/validation": true,
        "https://json-schema.org/draft/2020-12/vocab/meta-data": true,
        "https://json-schema.org/draft/2020-12/vocab/format-annotation": true,
        "https://json-schema.org/draft/2020-12/vocab/content": true,
        "https://highvaluedata.net/fair-data-schema/dev/vocab/annotations": false
    },
    "allOf": [
        {
            "$ref": "https://json-schema.org/draft/2020-12/schema"
        },
        {
            "$ref": "https://highvaluedata.net/fair-data-schema/dev/vocab/annotations"
        }
    ],
    "$comment": "The $vocabulary map is what transforms an ordinary meta-schema into a dialect. 'true' entries cause validators to refuse validation if they cannot implement that vocabulary. 'false' entries instruct validators to silently ignore unknown keywords from that vocabulary. This is the mechanism that makes FAIR annotations backward-compatible with all standard validators."
}