$schema : URI

$schema

URI

This keyword is both used as a JSON Schema dialect identifier and as a reference to a JSON Schema which describes the set of valid schemas written for this particular dialect.

Value This keyword must be set to an absolute URI as defined by RFC 3986
Kind Identifier
Applies To Any
Dialect 2020-12
Changed In None
Introduced In Draft 3
Vocabulary Core
Specification https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.1.1
Metaschema https://json-schema.org/draft/2020-12/meta/core
Official Tests None
Default Implementation dependent
Annotation None
Affected By None
Affects None
Also See

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

This declaration indicates that the schema is described by the JSON Schema 2020-12 dialect Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string"
}
Schema not adhering to its meta-schema is invalid Schema
{
  "$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.
Schema with no dialect specified Schema
{
  "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 with nested '$schema' keyword Schema
{
  "$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.