required-schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://json-schema.org/draft/2020-12/output/schema",
  "description": "A schema that validates the minimum requirements for validation output",

  "anyOf": [
    { "$ref": "#/$defs/flag" },
    { "$ref": "#/$defs/basic" },
    { "$ref": "#/$defs/detailed" },
    { "$ref": "#/$defs/verbose" }
  ],
  "$defs": {
    "outputUnit":{
      "properties": {
        "valid": { "type": "boolean" },
        "keywordLocation": {
          "type": "string",
          "format": "json-pointer"
        },
        "absoluteKeywordLocation": {
          "type": "string",
          "format": "uri"
        },
        "instanceLocation": {
          "type": "string",
          "format": "json-pointer"
        },
        "error": {
          "type": "string"
        },
        "errors": {
          "$ref": "#/$defs/outputUnitArray"
        },
        "annotations": {
          "$ref": "#/$defs/outputUnitArray"
        }
      },
      "required": [ "valid", "keywordLocation", "instanceLocation" ],
      "allOf": [
        {
          "if": {
            "properties": {
              "valid": { "const": false }
            }
          },
          "then": {
            "anyOf": [
              {
                "required": [ "error" ]
              },
              {
                "required": [ "errors" ]
              }
            ]
          }
        },
        {
          "if": {
            "anyOf": [
              {
                "properties": {
                  "keywordLocation": {
                    "pattern": "/\\$ref/"
                  }
                }
              },
              {
                "properties": {
                  "keywordLocation": {
                    "pattern": "/\\$dynamicRef/"
                  }
                }
              }
            ]
          },
          "then": {
            "required": [ "absoluteKeywordLocation" ]
          }
        }
      ]
    },
    "outputUnitArray": {
      "type": "array",
      "items": { "$ref": "#/$defs/outputUnit" }
    },
    "flag": {
      "properties": {
        "valid": { "type": "boolean" }
      },
      "required": [ "valid" ]
    },
    "basic": { "$ref": "#/$defs/outputUnit" },
    "detailed": { "$ref": "#/$defs/outputUnit" },
    "verbose": { "$ref": "#/$defs/outputUnit" }
  }
}
Result
The type of JSON Schema validation results, i.e. an object which encapsulates the validity of a given Instance under a Schema. This type may simply be Boolean in some implementations or languages.

ResultWithAnnotations

The type of JSON Schema validation results that include JSON Schema annotations collected during validation.

URI
The type of RFC 3986 compliant URIs. This type should not generally be the same as String, as URIs have multiple possible string representations and require normalization to have correct semantics.

Because this page deals with concerns which cross language barriers, and different programming languages have different capabilities particularly around how they represent out of band errors (via exceptions, option types, wrapper return types, sentinel values or some other mechanism), this page also introduces1 specific notation for representing the types of functions which include explicit representation for their out-of-band errors. Interpreting these types will depend on the programming language. It's easier to explain the above with an example:

Consider a division function on floats, represented as x / y.

We will write the type of this function as Float → Float → Float <!> DivideByZeroError, where the interpretation of this signature is that the function takes 2 floats and returns a float, but the <!> signals it may also propagate a DivideByZeroError (in this case when the function is asked to divide by zero).

The specific manifestation of DivideByZeroError will depend on the programming language. In a language with exceptions, this function may raise a DivideByZeroError-equivalent as an exception, which must or may be handled by the caller. In a language with option types, the "correct" type signature may really be wrapped in an Option type which represents the division by zero case (so the "true" signature in such a language would be Option[Float → Float → Float]). In a language with wrapper return types, the true type signature may be Result<Float, DivideByZeroError> where the returned value must be inspected to ensure it contains a successful result, and where the divide by zero error is instead a possible error value. In a language with a convention to return "junk" values, the true type may be precisely Float → Float → Float where some arbitrary float value is returned when dividing by zero, with no further indication.

In all cases above, when an exception (corresp. error or junk value) is raised (corresp. returned), we by convention assume that any normal return value is either completely not present by the mechanisms of the programming language, or else is considered meaningless.

In addition, this page will not, in general, consider or mention the possibility that an error might be raised for reasons other than those discussed in a particular section. For example, the division example mentioned above may raise other kinds of errors if provided with strings, in a dynamically typed language where such possibilities exist at runtime, such that the "real" division function may look more like Float → Float → Float <!> DivideByZeroError | TypeError or even further error possibilities. In the case of JSON Schema, this may mean every interface mentioned below has a type containing <!> InvalidSchema | NotValidJSON | ... representing cases where they are provided with schemas that are not valid according to the specification, or which do not fit the JSON data model, etc., but we consider these to be implicit and will not mention them explicitly unless directly relevant to the interface being discussed.

Instance Validation
Instance validation is one of the key capabilities of JSON Schema. It is the process in which a given piece of data is deemed valid or invalid under a specific schema. Implementations may offer one or more of the specific interfaces below in order to perform this validation.

Exception-Driven Validation
Type: EvaluationOptions → None <!> ValidationError or EvaluationOptions → Result <!> ValidationError

A validation API which causes a language-specific failure or exception when validation itself fails. If it succeeds, this API may return a result with further detail, or may simply continue execution silently.

Boolean Validation
Type: EvaluationOptions → Boolean

An API which produces a simple boolean result indicating an instance's validity under a schema.

Two-Argument Validation
Type: Schema × Instance → Result

An API which takes a schema and instance simultaneously and produces a result indicating whether the instance is valid under the given schema.

In some sense, two argument validation is the simplest possible API for JSON Schema validation; it asks simply whether a given instance is valid under a given schema with no presumptions of repeated use (of the schema) or additional calculation.

Repeated Validation / Schema Compilation
Type: Schema → Instance → Result

An API which attempts to prepare a schema for repeated use. It may (and likely will) perform some form of preoptimization, performing some set of work ahead of time such that it will not be necessary to repeat when validating many instances.

Subschema Validation
Type: Schema × String × Instance → Result

An API which supports validating an instance against a subschema contained within the given schema.

The subschema is typically identified via a JSON Pointer, or equivalent syntax, and is as opposed to validation using a new schema referencing the subschema via the $ref keyword.

Annotation Collection
Type: EvaluationOptions → ResultWithAnnotations

An API which collects annotations produced when processing a given schema and instance.

Schema Validation
Type: Schema → Result

An API which validates a schema itself under the dialect it is written for. This API likely makes use of a corresponding metaschema (or metaschemas) for the dialect, but generally must do additional work to ensure the schema is not invalid even under conditions not checked for within the metaschema.

Explicit Version Selection
Type: Dialect → EvaluationOptions → Result

An API which controls which dialect the implementation will assume when given a schema which does not otherwise indicate its dialect (i.e. which does not declare a $schema property).

Version Detection
Type: Schema → Dialect

An API which identifies which dialect a given schema is written for, returning either the dialect itself or otherwise a dialect-specific validation function.

Type Customization
An API which allows (re-)configuring which language-level types correspond to which JSON Schema types, and additionally potentially allowing for the definition of new types.

String Validation
Type: String → String → Result

An API which directly validates instances using schemas where both are represented as strings -- serialized JSON -- as opposed to deserialized JSON.

Language Object Validation
Type: EvaluationOptions → Result

An API which validates instances using schemas where both have been deserialized into language-level objects, or potentially built up programmatically directly as language-level objects.

format Validation
Format Assertion Enablement
An API which configures the behavior of the format keyword, in dialects where this behavior is not solely controlled by JSON Schema vocabulary enablement.

Format Registration
Type: String × (Instance → Boolean)→EvaluationOptions`

An API which allows registering a new format and its implementation for use with the format keyword, typically when it is used to assert.

Some implementations may further allow registering different sets of available formats for different dialects.

Format Querying
An API which queries or lists the set of available formats which have been registered.

Direct Format Validation
Type: String × Instance → Boolean

An API which allows directly checking whether a JSON-like value satisfies a specific format, without the presence of a schema.

Schema Registry Population
An API which configures the bundle of schemas available for referencing during the validation process.

Externally Identified Schemas
An API which allows associating one or more URIs with a schema where the URIs are not internally indicated by an $id keyword (or a dialect-specific equivalent).

Internally Identified Schemas
An API which allows associating URIs with a schema where the URI is internally indicated by the presence of an $id keyword (or a dialect-specific equivalent) in the schema.

Schema Discovery
An API which (recursively) crawls a root schema or schemas, discovering any subresources (subschemas) which are present and identifiable, and making those subresources' URIs available for further referencing.

Dynamic URI Resolution
An API which allows for arbitrary dynamic lookup behavior for any reference not prepopulated in the registry.

Output Format Selection / Generation
An API which configures which of JSON Schema's output format(s) are used when producing results, or which allows generating a particular output format given a Result.

Vocabulary Registration
An API which facilitates the creation of new JSON Schema vocabularies, typically for use when later building new dialects.

Dialect Creation
An API which facilitates the creation of new JSON Schema dialects, typically registering them in some way such that they can be further used inside the implementation.

Failure Details
An API which allows for programmatic introspection of the causes of a particular validation failure, at minimum containing the failing keyword(s), value(s) and individual message(s) which led to the failure.