The $schema keyword is a fundamental element in JSON Schema. It serves the two crucial purposes:

1. Dialect Identification: It specifies the specific dialect of JSON Schema the schema adheres to. This ensures implementations (tools and libraries) interpret the schema correctly based on the intended dialect’s rules and imported vocabularies.

2. Meta-Schema Validation: The value of $schema is a URI pointing to a “meta-schema”, which defines the structure and validation rules for JSON Schemas. A schema that describes another schema is called a “meta-schema”. The schema is expected to be valid against its own meta-schema.

• The current schema must be valid against the meta-schema identified by this URI.
• The $schema keyword should be used in the document root schema object, and may be used in the root schema objects of embedded schema resources.
• If this keyword is absent from the document root schema, the resulting behavior is implementation-defined.

Examples

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string"
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": [ { "type": "number" } ]
}

• The properties keyword can only be set to a single valid JSON Schema. Therefore, setting the properties keyword to an array of JSON Schemas makes the schema invalid according to the 2020-12 specification.

{
  "items": [ { "type": "number" } ]
}

• The above schema doesn’t specify the dialect of JSON Schema it adheres to. Therefore, the implementation might determine the dialect independently, which could lead to unexpected results. For instance, if the implementation assumes the 2019-09 dialect, the schema would be considered valid. However, if it assumes the 2020-12 dialect, the schema would be invalid.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Product schema",
  "properties": {
    "name": { "type": "string" },
    "price": { "type": "number" },
    "discount": {
      "$ref": "#/$defs/discount"
    }
  },
  "$defs": {
    "discount": {
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "type": "number"
    }
  }
}

• Embedded schemas within a bundled JSON document can have their own $schema declarations. This allows different parts of your schema to use the most suitable dialect for their specific needs, ensuring accurate validation and flexibility. Check out this blog to learn more about schema bundling.