$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 Hint: Use the `jsonschema metaschema` and `jsonschema lint` commands to catch keywords set to invalid values
Kind	Identifier
Applies To	Any
Base 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 or context dependent
Annotation	None
Affected By	None
Affects	None
Also See	$id (Vocabulary: Core) $vocabulary (Vocabulary: Core) $defs (Vocabulary: Core)

The $schema keyword serves to explicitly associate a schema resource with the JSON Schema dialect that defines it, where the dialect is the identifier of a meta-schema that defines the vocabularies in use and imposes syntactic constraints on its schema instances. If the $schema keyword is not declared, the schema inherits its context-specific or implementation-specific default dialect.

Digging Deeper

It is common to avoid the $schema keyword when working with OpenAPI. This is possible because the OpenAPI specification clearly documents what the default JSON Schema dialect is for every version. For example, OpenAPI v3.1.1 defines the default dialect as https://spec.openapis.org/oas/3.1/dialect/base.

Strictly-compliant JSON Schema implementations will refuse to process a schema whose dialect cannot be unambiguously determined.

Best Practice

To avoid undefined behavior, it is generally recommended to always explicitly set the dialect of a schema using the $schema keyword. This ensures that less strict implementations unambiguously know how to process the schema and don’t attempt to guess.

Note that the $schema keyword can occur multiple times in the same schema, and not only at the top-level. This is often the case when performing JSON Schema Bundling to inline externally referenced schemas that might be based on different dialects of JSON Schema.

Common Pitfall

JSON Schema prohibits the use of the this keyword on arbitrary subschemas that do not represent schema resources. It can only be present at the root of the schema (an implicit schema resource) or as a sibling of the $id keyword (an explicit schema resource).

A schema is considered syntactic valid if it successfully validates against its dialect meta-schema. You can validate a schema against its meta-schema using the jsonschema metaschema command. For example:

$ jsonschema metaschema my-schema.json

To debug the role of the $schema keyword on a schema (particularly schemas with embedded resources), try the jsonschema inspect command. This command prints detailed information about each schema resource, subschema, location, and reference present in the schema. For example:

$ jsonschema inspect schema.json
(RESOURCE) URI: https://example.com/schema
    Type              : Static
    Root              : https://example.com/schema
    Pointer           :
    Base              : https://example.com/schema
    Relative Pointer  :
    Dialect           : https://json-schema.org/draft/2020-12/schema
    Base Dialect      : https://json-schema.org/draft/2020-12/schema
    Parent            : <NONE>
    Instance Location :

...

(SUBSCHEMA) URI: https://example.com/schema#/properties/foo
    Type              : Static
    Root              : https://example.com/schema
    Pointer           : /properties/foo
    Base              : https://example.com/schema
    Relative Pointer  : /properties/foo
    Dialect           : https://json-schema.org/draft/2020-12/schema
    Base Dialect      : https://json-schema.org/draft/2020-12/schema
    Parent            :
    Instance Location : /foo

...

(REFERENCE) ORIGIN: /$schema
    Type              : Static
    Destination       : https://json-schema.org/draft/2020-12/schema
    - (w/o fragment)  : https://json-schema.org/draft/2020-12/schema
    - (fragment)      : <NONE>

Examples

A schema described by the JSON Schema 2020-12 official dialect Schema

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

A valid schema without an explicitly declared dialect, prone to undefined behavior Schema

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

A valid schema that mixes the 2020-12 and 2019-09 official dialects Schema

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