JSON Schema Specification

JSON Schema keywords are categorized into three primary behaviors:

1. Assertions: Validate that an instance satisfies specific constraints, returning true if satisfied and false otherwise.
2. Annotations: Attach metadata to specific instance locations for application-level use (e.g., title, description).
3. Applicators: Apply subschemas to parts of the instance and combine their results (e.g., allOf, anyOf, not).

Note that operational directive keywords like $id and $schema provide metadata for implementation processing and do not fall into these three categories.

Applicators are used to build complex schemas by applying subschemas to the instance. They behave as assertions by combining the boolean results of their subschemas using logic (e.g., allOf for conjunction, not for negation).

Applicators can work in two ways:

1. In-place: Applying subschemas to the current location.
2. By Reference: Referring to a schema elsewhere (the referenced schema) from the current schema (the referencing schema). Keywords like $ref use static analysis, while $dynamicRef uses dynamic scoping.

JSON Schema validation is used to assert constraints on the structure of JSON instance data. An instance is considered valid if all locations within the instance satisfy all asserted constraints defined by the schema keywords.

Key concepts:

• Assertion Keywords: Keywords that define constraints (e.g., requiring a specific type or value).
• Metadata Keywords: Keywords used to annotate instances with non-assertion information (e.g., descriptions or UI hints).
• Container Instance: Refers to both JSON arrays and objects.
• Children Instances: Refers to array elements or object member values.
• Independent Evaluation: Each schema object is evaluated independently against each instance location, meaning validators do not need to maintain state across the document-wide validation process.

JSON Schema has decoupled from the IETF (Internet Engineering Task Force) standards track to implement a custom Specification Development Lifecycle (SDLC). Unlike typical IETF Internet-Drafts (I-Ds) which are often considered "incomplete" or "not ready for production," JSON Schema releases are intended for immediate production use.

Key characteristics of the current approach:

• Production Readiness: All releases are intended to be used in production environments.
• Versioning: The project uses date-based versioning rather than the standard IETF draft versioning system.
• Governance: The project is a member of the OpenJS Foundation (a sub-group of the Linux Foundation), which provides the necessary credibility for standards referencing in lieu of IETF/W3C status.

JSON Schema is a declarative language used for two primary purposes:

1. Validation: Ensuring a JSON instance conforms to a specific structure and set of constraints.
2. Annotation: Attaching metadata to values in a JSON document for use by applications (e.g., documentation generation, form builders, or type code generation).

A JSON Schema is itself a JSON document. A JSON value is considered valid against a schema if it satisfies the constraints defined by every keyword within that schema. Evaluation is a recursive process where keywords can contain subschemas to describe complex structures like objects and arrays.

The specification defines three distinct machine-readable output formats for JSON Schema validation and annotation results. An implementation MUST provide the flag format and SHOULD provide at least one of the list or hierarchical formats.

• Flag: A simple boolean indicating the overall validation result (valid).
• List: A flat list of output units contained within a root output unit.
• Hierarchical: A tree structure that follows the evaluation paths generated during processing, resembling the schema structure (with references inlined).

Most assertions only constrain values within a specific primitive type. If the instance's type does not match the type targeted by the keyword, the instance is considered to conform to that assertion.

For example, the maxLength keyword only restricts strings. If the instance is a number, boolean, null, array, or object, it is considered valid against the maxLength assertion. This allows you to combine keywords using type to create flexible schemas:

{
  "type": ["string", "null"],
  "maxLength": 255
}

In this example, if the value is a string, it must be $\le$ 255 characters. If the value is null, it passes the maxLength assertion automatically.

Implementations should ideally know which schemas and IRIs they will use ahead of time.

• Pre-loading: You can supply IRIs and their associated schemas to an implementation prior to processing instances.
• Automatic Association: Implementations can associate arbitrary IRIs with schemas, often using the $id value.
• Fetching: While implementations MAY automatically fetch schemas via HTTP, this functionality SHOULD be disabled by default to support offline operation.