JSON Schema

4.1.1. Trivial schema documents

The schema values "true" and "false" are trivial schemas. The valid set for the 'true' schema is all possible JSON documents, and the valid set for the 'false' schema is empty. The trivial boolean schemas exist to clarify schema author intent and facilitate schema processing optimizations. They behave identically to the following schema objects (where "not" is part of the subschema application vocabulary defined in this document).¶

true

Always passes validation, as if the empty schema {}¶

false

Always fails validation, as if the schema { "not": {} }¶

While the empty schema object is unambiguous, there are many possible equivalents to the "false" schema. Using the boolean values ensures that the intent is clear to both human readers and implementations.¶

4.1.2. Root Schema and Subschemas and Resources

A JSON Schema resource is a schema which is canonically identified (in the sense of [RFC6596]) by an absolute URI ([RFC3986], Section 4.3). Schema resources MAY also be identified by URIs, including URIs with fragments, if the resulting secondary resource (as defined by [RFC3986], Section 3.5) is identical to the primary resource. This can occur with the empty fragment, or when one schema resource is embedded in another. Any such URIs with fragments are considered to be non-canonical.¶

The root schema is always a schema resource, where the URI is determined as described in Section 12.1.1.Note that documents that embed schemas in another format will not have a root schema resource in this sense. Exactly how such usages fit with the JSON Schema document and resource concepts will be clarified in a future draft.¶

Some keywords take schemas themselves, allowing JSON Schemas to be nested:¶

{
    "title": "root",
    "items": {
        "title": "array item"
    }
}

In this example document, the schema titled "array item" is a subschema, and the schema titled "root" is the root schema.¶

As with the root schema, a subschema is either an object or a boolean.¶

As discussed in Section 5.1.3, a JSON Schema document can contain multiple JSON Schema resources. When used without qualification, the term "root schema" refers to the document's root schema. In some cases, resource root schemas are discussed. A resource's root schema is its top-level schema object, which would also be a document root schema if the resource were to be extracted to a standalone JSON Schema document.¶

Whether multiple schema resources are embedded or linked with a reference, they are processed in the same way, with the same available behaviors.¶

4.2.1. Input Equality

Two JSON inputs are said to be equal if and only if they are of the same type and have the same value according to the JSON data model. Specifically, this means:¶

• both are null; or¶

• both are true; or¶

• both are false; or¶

• both are strings, and are the same codepoint-for-codepoint; or¶

• both are numbers, and have the same mathematical value; or¶

• both are arrays, and have an equal value item-for-item; or¶

• both are objects, and each property in one has exactly one property with a key equal to the other's, and that other property has an equal value.¶

Implied in this definition is that arrays must be the same length, objects must have the same number of members, properties in objects are unordered, there is no way to define multiple properties with the same key, and mere formatting differences (indentation, placement of commas, trailing zeros) are insignificant. Two equal inputs are guaranteed to yield identical validation results for a given schema, regardless of their original formatting.¶

4.5.1. Range of JSON Values

An instance may be any valid JSON value as defined by JSON ([RFC8259]). JSON Schema imposes no restrictions on type: JSON Schema can describe any JSON value, including, for example, null.¶

4.5.2. Requirements for handling extensions

Additional schema keywords and schema vocabularies MAY be defined by any entity. Save for explicit agreement, schema authors SHALL NOT expect these additional keywords and vocabularies to be supported by implementations that do not explicitly document such support. Implementations SHOULD treat keywords they do not support as annotations, where the value of the keyword is the value of the annotation.¶

Implementations MAY provide the ability to register or load handlers for vocabularies that they do not support directly. The exact mechanism for registering and implementing such handlers is implementation-dependent.¶

4.5.3. Validation

JSON Schema validation applies the rules of a JSON Schema to determine if an input is in the valid set for that schema. An instance location that satisfies all asserted constraints is then annotated with any keywords that contain non-assertion information, such as descriptive metadata and usage hints.¶

Each schema object is independently evaluated against each input location to which it applies. This greatly simplifies implementation requirements by ensuring that implementations do not need to maintain state across the document-wide validation process.¶

This specification defines a set of assertion keywords, as well as a small vocabulary of metadata keywords that can be used to annotate the JSON instance with useful information. The Section 9 keyword is intended primarily as an annotation, but can optionally be used as an assertion. The Section 10 keywords are annotations for working with documents embedded as JSON strings.¶

5.1.1. "$schema"

The "$schema" keyword is both used as a JSON Schema dialect identifier and as the identifier of a resource which is itself a JSON Schema, which describes the set of valid schemas written for this particular dialect.¶

The value of this keyword MUST be a (containing a scheme, per [RFC3986], Section 3) and this URI MUST be normalized. The current schema MUST be valid against the meta-schema identified by this URI.¶

If this URI identifies a retrievable resource, that resource SHOULD be of media type "application/schema+json".¶

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. It MUST NOT appear in non-resource root schema objects. If absent from the document root schema, the resulting behavior is implementation-defined.¶

Values for this property are defined elsewhere in this and other documents, and by other parties.¶

5.1.2. "$vocabulary"

The "$vocabulary" keyword is used in meta-schemas to identify the vocabularies available for use in schemas described by that meta-schema. It is also used to indicate whether each vocabulary is required or optional, in the sense that an implementation MUST understand the required vocabularies in order to successfully process the schema. Together, this information forms a dialect. Any vocabulary that is understood by the implementation MUST be processed in a manner consistent with the semantic definitions contained within the vocabulary.¶

The value of this keyword MUST be an object. The property names in the object MUST be URIs (containing a scheme) and this URI MUST be normalized. Each URI that appears as a property name identifies a specific set of keywords and their semantics.¶

The URI MAY be a URL, but the nature of the retrievable resource is currently undefined, and reserved for future use. Vocabulary authors MAY use the URL of the vocabulary specification, in a human-readable media type such as text/html or text/plain, as the vocabulary URI.Vocabulary documents may be added in forthcoming drafts. For now, identifying the keyword set is deemed sufficient as that, along with meta-schema validation, is how the current "vocabularies" work today. Any future vocabulary document format will be specified as a JSON document, so using text/html or other non-JSON formats in the meantime will not produce any future ambiguity.¶

The values of the object properties MUST be booleans. If the value is true, then implementations that do not recognize the vocabulary MUST refuse to process any schemas that declare this meta-schema with "$schema". If the value is false, implementations that do not recognize the vocabulary SHOULD proceed with processing such schemas. The value has no impact if the implementation understands the vocabulary.¶

Per Section 4.5.2, unrecognized keywords SHOULD be treated as annotations. This remains the case for keywords defined by unrecognized vocabularies. It is not currently possible to distinguish between unrecognized keywords that are defined in vocabularies from those that are not part of any vocabulary.¶

The "$vocabulary" keyword SHOULD be used in the root schema of any schema resource intended for use as a meta-schema. It MUST NOT appear in subschemas.¶

The "$vocabulary" keyword MUST be ignored in schema resources that are not being processed as a meta-schema. This allows validating a meta-schema M against its own meta-schema M' without requiring the implementation to understand the vocabularies declared by M.¶

5.1.3. "$id"

The $id keyword identifies a schema resource with its canonical URI (in the sense of [RFC6596]). Explicit identification makes it easier for a schema to be referenced, especially from other schemas, allowing re-use, modularity and extensibility of schemas. An explicit identifier is a more stable way to reference a schema than its location (either its URL on the Web or as a location within the structure of a parent schema).¶

Requirements on $id value:¶

• MUST be a string¶

• MUST be a valid URI reference ([RFC3986], Section 4.1)¶

• SHOULD be normalized¶

• MUST NOT have a fragment ([RFC3986], Section 3.5)¶

The value of an $id may be a full URI or a relative reference ([RFC3986], Section 4.2). When a relative URI is used, knowing the base URI becomes important. Read Section 12.2.1 and Appendix A to understand how that must be done.¶

Note that an URI does not have to be a URL. Even if it is a URL, the URL may not resolve and return a schema, and implementations are warned against automatically resolving network references to fetch schemas (see Section 12.1.2). Nevertheless, the URI still identifies the schema.¶

The presence of "$id" in a subschema indicates that the subschema constitutes a distinct schema resource within a single schema document.¶

See also the $anchor keyword (Section 5.1.4) for naming subschemas, and the $ref keyword (Section 5.2.1) in which $id and $anchor values are frequently used.¶

5.1.4. "$anchor" and "$dynamicAnchor"

Using JSON Pointer fragments requires knowledge of the structure of the schema. When writing schema documents with the intention to provide re-usable schemas, it may be preferable to use a plain name fragment that is not tied to any particular structural location. This allows a subschema to be relocated without requiring JSON Pointer references to be updated.¶

The "$anchor" and "$dynamicAnchor" keywords are used to specify such fragments. They are identifier keywords that can only be used to create plain name fragments.¶

The base URI to which the resulting fragment is appended is the canonical URI of the schema resource containing the "$anchor" or "$dynamicAnchor" in question. As discussed in the previous section, this is either the nearest "$id" in the same or parent schema object, or the base URI for the document as determined according to RFC 3986.¶

Separately from the usual usage of URIs, "$dynamicAnchor" indicates that the fragment is an extension point when used with the "$dynamicRef" keyword. This low-level, advanced feature makes it easier to extend recursive schemas such as the meta-schemas, without imposing any particular semantics on that extension. See the section on "$dynamicRef" (Section 5.2.1) for details.¶

In most cases, the normal fragment behavior both suffices and is more intuitive. Therefore it is RECOMMENDED that "$anchor" be used to create plain name fragments unless there is a clear need for "$dynamicAnchor".¶

If present, the value of this keyword MUST be a string and MUST start with a letter ([A-Za-z]) or underscore ("_"), followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), and periods ("."). This matches the US-ASCII part of XML's NCName production, per [XMLNS].Note that the anchor string does not include the "#" character, as it is not a URI-reference. An "$anchor": "foo" becomes the fragment "#foo" when used in a URI. See below for full examples.¶

The effect of specifying the same fragment name multiple times within the same resource, using any combination of "$anchor" and/or "$dynamicAnchor", is undefined. Implementations MAY raise an error if such usage is detected.¶

5.2.1. "$ref" and "$dynamicRef"

The "$ref" and "$dynamicRef" keywords are applicator keywords used to reference a schema. Their results are the results of the referenced schema.Note that this definition of how the results are determined means that other keywords can appear alongside of "$ref" in the same schema object.¶

As the values of "$ref" and "$dynamicRef" are URI References, this allows the possibility to externalise or divide a schema across multiple files, and provides the ability to validate recursive structures through self-reference.¶

The resolved URI produced by these keywords is not necessarily a network locator, only an identifier. Even if it is a network locator, implementations should refer to Section 12.1.2 about loading such schemas.¶

The value of the "$ref" keyword MUST be a string which is a URI-Reference. Resolved against the current URI base, it produces the URI of the schema to apply. This resolution is safe to perform on schema load, as the process of evaluating an input cannot change how the reference resolves.¶

The "$dynamicRef" keyword is an applicator that allows for deferring the full resolution until runtime, at which point it is resolved each time it is encountered while evaluating an input.¶

Together with "$dynamicAnchor", "$dynamicRef" implements a cooperative extension mechanism that is primarily useful with recursive schemas (schemas that reference themselves). Both the extension point and the runtime-determined extension target are defined with "$dynamicAnchor", and only exhibit runtime dynamic behavior when referenced with "$dynamicRef".¶

The value of the "$dynamicRef" property MUST be a string which is a URI-Reference. Resolved against the current URI base, it produces the URI used as the starting point for runtime resolution. This initial resolution is safe to perform on schema load.¶

If the initially resolved starting point URI includes a fragment that was created by the "$dynamicAnchor" keyword, the initial URI MUST be replaced by the URI (including the fragment) for the outermost schema resource in the dynamic scope (Section 13.1) that defines an identically named fragment with "$dynamicAnchor".¶

Otherwise, its behavior is identical to "$ref", and no runtime resolution is needed.¶

For a full example using these keyword, see Appendix C.The difference between the hyper-schema meta-schema in pre-2019 drafts and an this draft dramatically demonstrates the utility of these keywords.¶

5.2.2. "$defs"

The "$defs" keyword reserves a location for schema authors to inline re-usable JSON Schemas into a more general schema. The keyword does not directly affect the validation result.¶

This keyword's value MUST be an object. Each member value of this object MUST be a valid JSON Schema.¶

As an example, here is a schema describing an array of positive integers, where the positive integer constraint is a subschema in "$defs":¶

{
    "type": "array",
    "items": { "$ref": "#/$defs/positiveInteger" },
    "$defs": {
        "positiveInteger": {
            "type": "integer",
            "exclusiveMinimum": 0
        }
    }
}

6.2.1. "allOf"

This keyword's value MUST be a non-empty array. Each item of the array MUST be a valid JSON Schema.¶

An input validates successfully against this keyword if it validates successfully against all schemas defined by this keyword's value.¶

6.2.2. "anyOf"

This keyword's value MUST be a non-empty array. Each item of the array MUST be a valid JSON Schema.¶

An input validates successfully against this keyword if it validates successfully against at least one schema defined by this keyword's value. Note that when annotations are being collected, all subschemas MUST be examined so that annotations are collected from each subschema that validates successfully.¶

6.2.3. "oneOf"

This keyword's value MUST be a non-empty array. Each item of the array MUST be a valid JSON Schema.¶

An input validates successfully against this keyword if it validates successfully against exactly one schema defined by this keyword's value.¶

6.2.4. "not"

This keyword's value MUST be a valid JSON Schema.¶

An input is valid against this keyword if it fails to validate successfully against the schema defined by this keyword.¶

6.2.5. "if"

This keyword's value MUST be a valid JSON Schema.¶

This validation outcome of this keyword's subschema has no direct effect on the overall validation result. Rather, it controls which of the "then" or "else" keywords are evaluated.¶

Inputs that successfully validate against this keyword's subschema MUST also be valid against the subschema value of the "then" keyword, if present.¶

Iputs that fail to validate against this keyword's subschema MUST also be valid against the subschema value of the "else" keyword, if present.¶

If Section 13.8 are being collected, they are collected from this keyword's subschema in the usual way, including when the keyword is present without either "then" or "else".¶

6.2.6. "then"

This keyword's value MUST be a valid JSON Schema.¶

When "if" is present, and the input successfully validates against its subschema, then validation succeeds against this keyword if the input also successfully validates against this keyword's subschema.¶

This keyword has no effect when "if" is absent, or when the input fails to validate against its subschema. Implementations MUST NOT evaluate the input against this keyword, for either validation or annotation collection purposes, in such cases.¶

6.2.7. "else"

This keyword's value MUST be a valid JSON Schema.¶

When "if" is present, and the input fails to validate against its subschema, then validation succeeds against this keyword if the input successfully validates against this keyword's subschema.¶

This keyword has no effect when "if" is absent, or when the input successfully validates against its subschema. Implementations MUST NOT evaluate the input against this keyword, for either validation or annotation collection purposes, in such cases.¶

6.2.8. "dependentSchemas"

This keyword specifies subschemas that are evaluated if the input is an object and contains a certain property.¶

This keyword's value MUST be an object. Each value in the object MUST be a valid JSON Schema.¶

If the object key is a property in the instance, the entire instance must validate against the subschema. Its use is dependent on the presence of the property.¶

Omitting this keyword has the same behavior as an empty object.¶

6.3.1. "prefixItems"

The value of "prefixItems" MUST be a non-empty array of valid JSON Schemas.¶

Validation succeeds if each element of the input validates against the schema at the same position, if any. This keyword does not constrain the length of the array. If the array is longer than this keyword's value, this keyword validates only the prefix of matching length.¶

This keyword produces an annotation value which is the largest index to which this keyword applied a subschema. The value MAY be a boolean true if a subschema was applied to every index of the instance, such as is produced by the "items" keyword. This annotation affects the behavior of "items" and "unevaluatedItems".¶

Omitting this keyword has the same assertion behavior as an empty array.¶

6.3.2. "items"

The value of "items" MUST be a valid JSON Schema.¶

This keyword applies its subschema to all input elements at indexes greater than the length of the "prefixItems" array in the same schema object, as reported by the annotation result of that "prefixItems" keyword. If no such annotation result exists, "items" applies its subschema to all input array elements.Note that the behavior of "items" without "prefixItems" is identical to that of the schema form of "items" in prior drafts. When "prefixItems" is present, the behavior of "items" is identical to the former "additionalItems" keyword.¶

If the "items" subschema is applied to any positions within the input array, it produces an annotation result of boolean true, indicating that all remaining array elements have been evaluated against this keyword's subschema. This annotation affects the behavior of "unevaluatedItems" in the Unevaluated vocabulary.¶

Omitting this keyword has the same assertion behavior as an empty schema.¶

Implementations MAY choose to implement or optimize this keyword in another way that produces the same effect, such as by directly checking for the presence and size of a "prefixItems" array. Implementations that do not support annotation collection MUST do so.¶

6.3.3. "contains"

The value of this keyword MUST be a valid JSON Schema.¶

An array input is valid against "contains" if the number of elements that are valid against its subschema is within the inclusive range of the minimum and (if any) maximum number of occurrences.¶

The minimum and maximum numbers of occurrences are provided by the "minContains" and "maxContains" keywords, respectively, within the same schema object as "contains". If "minContains" is absent, the minimum MUST be 1. If "maxContains" is absent, the maximum MUST be unbounded.¶

Implementations MAY implement the dependency on "minContains" and "maxContains" by inspecting their values rather than by reading annotations provided by those keywords.¶

This keyword produces an annotation value which is an array of the indexes to which this keyword validates successfully when applying its subschema, in ascending order. The value MAY be a boolean "true" if the subschema validates successfully when applied to every index of the instance. The annotation MUST be present if the input array to which this keyword's schema applies is empty.¶

This annotation affects the behavior of "unevaluatedItems" in the Unevaluated vocabulary.¶

The subschema MUST be applied to every array element even after the first match has been found, in order to collect annotations for use by other keywords. This is to ensure that all possible annotations are collected.¶

6.4.1. "properties"

The value of "properties" MUST be an object. Each value of this object MUST be a valid JSON Schema.¶

Validation succeeds if, for each name that appears in both the input and as a name within this keyword's value, the contents successfully validate against the corresponding schema.¶

The annotation result of this keyword is the set of instance property names matched by this keyword. This annotation affects the behavior of "additionalProperties" (in this vocabulary) and "unevaluatedProperties" in the Unevaluated vocabulary.¶

Omitting this keyword has the same assertion behavior as an empty object.¶

6.4.2. "patternProperties"

The value of "patternProperties" MUST be an object. Each property name of this object SHOULD be a valid regular expression, according to the ECMA-262 regular expression dialect. Each property value of this object MUST be a valid JSON Schema.¶

Validation succeeds if, for each input name that matches any regular expressions that appear as a property name in this keyword's value, the contents successfully validate against each schema that corresponds to a matching regular expression. Recall: Regular expressions are not explicitly anchored.¶

The annotation result of this keyword is the set of instance property names matched by this keyword. This annotation affects the behavior of "additionalProperties" (in this vocabulary) and "unevaluatedProperties" (in the Unevaluated vocabulary).¶

Omitting this keyword has the same assertion behavior as an empty object.¶

6.4.3. "additionalProperties"

The value of "additionalProperties" MUST be a valid JSON Schema.¶

The behavior of this keyword depends on the presence and annotation results of "properties" and "patternProperties" within the same schema object. Validation with "additionalProperties" applies only to the child values of input names that do not appear in the annotation results of either "properties" or "patternProperties".¶

For all such properties, validation succeeds if the contents validate against the "additionalProperties" schema.¶

The annotation result of this keyword is the set of input property names validated by this keyword's subschema. This annotation affects the behavior of "unevaluatedProperties" in the Unevaluated vocabulary.¶

Omitting this keyword has the same assertion behavior as an empty schema.¶

Implementations MAY choose to implement or optimize this keyword in another way that produces the same effect, such as by directly checking the names in "properties" and the patterns in "patternProperties" against the input property set. Implementations that do not support annotation collection MUST do so.In defining this option, it seems there is the potential for ambiguity in the output format. The ambiguity does not affect validation results, but it does affect the resulting output format. The ambiguity allows for multiple valid output results depending on whether annotations are used or a solution that "produces the same effect" as draft-07. It is understood that annotations from failing schemas are dropped. See our Decision Record for further details.¶

6.4.4. "propertyNames"

The value of "propertyNames" MUST be a valid JSON Schema.¶

If the input is an object, this keyword validates if every property name in the input validates against the provided schema. Note the property name that the schema is testing will always be a string.¶

Omitting this keyword has the same behavior as an empty schema.¶

8.1.1. "type"

The value of this keyword MUST be either a string or an array. If it is an array, elements of the array MUST be strings and MUST be unique.¶

String values MUST be one of the six primitive types ("null", "boolean", "object", "array", "number", or "string"), or "integer" which matches any number with a zero fractional part.¶

If the value of "type" is a string, then an input validates successfully if its type matches the type represented by the value of the string.¶

If the value of "type" is an array, then an input validates successfully if its type matches any of the types indicated by the strings in the array.¶

8.1.2. "enum"

The value of this keyword MUST be an array. This array SHOULD have at least one element. Elements in the array SHOULD be unique.¶

An input validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.¶

Elements in the array might be of any type, including null.¶

8.1.3. "const"

The value of this keyword MAY be of any type, including null.¶

Use of this keyword is functionally equivalent to an Section 8.1.2 with a single value.¶

An input validates successfully against this keyword if its value is equal to the value of the keyword.¶

8.2.1. "multipleOf"

The value of "multipleOf" MUST be a number, strictly greater than 0.¶

A numeric input value is valid only if division by this keyword's value results in an integer.¶

8.2.2. "maximum"

The value of "maximum" MUST be a number, representing an inclusive upper limit for a numeric input value.¶

If the input value is a number, then this keyword validates only if the input value is less than or exactly equal to "maximum".¶

8.2.3. "exclusiveMaximum"

The value of "exclusiveMaximum" MUST be a number, representing an exclusive upper limit for a numeric input value.¶

If the input value is a number, then it is valid only if it has a value strictly less than (not equal to) "exclusiveMaximum".¶

8.2.4. "minimum"

The value of "minimum" MUST be a number, representing an inclusive lower limit for a numeric input value.¶

If the input value is a number, then it is valid only if it has a value that is greater than or exactly equal to "minimum".¶

8.2.5. "exclusiveMinimum"

The value of "exclusiveMinimum" MUST be a number, representing an exclusive lower limit for a numeric input value.¶

If the input value is a number, then it is valid only if it has a value strictly greater than (not equal to) "exclusiveMinimum".¶

8.3.1. "maxLength"

The value of this keyword MUST be a non-negative integer.¶

A string input value is valid against this keyword if its length is less than, or equal to, the value of this keyword.¶

The length of a string input value is defined as the number of its characters as defined by [RFC8259].¶

8.3.2. "minLength"

The value of this keyword MUST be a non-negative integer.¶

A string input value is valid against this keyword if its length is greater than, or equal to, the value of this keyword.¶

The length of a string input value is defined as the number of its characters as defined by [RFC8259].¶

Omitting this keyword has the same behavior as a value of 0.¶

8.3.3. "pattern"

The value of this keyword MUST be a string. This string SHOULD be a valid regular expression, according to the ECMA-262 regular expression dialect.¶

A string input value is considered valid if the regular expression matches the input value successfully. Recall: regular expressions are not implicitly anchored.¶

8.4.1. "maxItems"

The value of this keyword MUST be a non-negative integer.¶

An array input value is valid against "maxItems" if its size is less than, or equal to, the value of this keyword.¶

8.4.2. "minItems"

The value of this keyword MUST be a non-negative integer.¶

An array input value is valid against "minItems" if its size is greater than, or equal to, the value of this keyword.¶

Omitting this keyword has the same behavior as a value of 0.¶

8.4.3. "uniqueItems"

The value of this keyword MUST be a boolean.¶

If this keyword has boolean value false, the input array validates successfully. If it has boolean value true, the input array validates successfully if all of its elements are unique.¶

Omitting this keyword has the same behavior as a value of false.¶

8.4.4. "maxContains"

The value of this keyword MUST be a non-negative integer.¶

Validation MUST always succeed against this keyword; its validation effect is to modify the behavior of "contains" within the same schema object, as described in that keyword's section.¶

This keyword behaves as an annotation, which MAY be used by "Section 6.3.3".¶

8.4.5. "minContains"

The value of this keyword MUST be a non-negative integer.¶

Validation MUST always succeed against this keyword; its validation effect is to modify the behavior of "contains" within the same schema object, as described in that keyword's section.¶

This keyword behaves as an annotation, which MAY be used by "Section 6.3.3".¶

Omitting this keyword has the same behavior as a value of 1. Per Section 13.3, omitted keywords MUST NOT produce annotation results. However, as described in the section for "contains", the absence of this keyword's annotation causes "contains" to assume a value of 1.¶

8.5.1. "maxProperties"

The value of this keyword MUST be a non-negative integer.¶

An object is valid against "maxProperties" if its number of properties is less than, or equal to, the value of this keyword.¶

8.5.2. "minProperties"

The value of this keyword MUST be a non-negative integer.¶

An object is valid against "minProperties" if its number of properties is greater than, or equal to, the value of this keyword.¶

Omitting this keyword has the same behavior as a value of 0.¶

8.5.3. "required"

The value of this keyword MUST be an array. Elements of this array, if any, MUST be strings, and MUST be unique.¶

An object is valid against this keyword if every item in the array is the name of a property in the object.¶

Omitting this keyword has the same behavior as an empty array.¶

8.5.4. "dependentRequired"

The value of this keyword MUST be an object. Properties in this object, if any, MUST be arrays. Elements in each array, if any, MUST be strings, and MUST be unique.¶

This keyword specifies properties that are required if a specific other property is present. Their requirement is dependent on the presence of the other property.¶

Validation succeeds if, for each name that appears in both the input object and as a name within this keyword's value, every item in the corresponding array is also the name of a property in the input object.¶

Omitting this keyword has the same behavior as an empty object.¶

9.2.1. Format-Annotation Vocabulary

The value of format MUST be collected as an annotation, if the implementation supports annotation collection. This enables application-level validation when schema validation is unavailable or inadequate.¶

Implementations MAY still treat "format" as an assertion in addition to an annotation and attempt to validate the value's conformance to the specified semantics. The implementation MUST provide options to enable and disable such evaluation and MUST be disabled by default. Implementations SHOULD document their level of support for such validation.Specifying the Format-Annotation vocabulary and enabling validation in an implementation should not be viewed as being equivalent to specifying the Format-Assertion vocabulary since implementations are not required to provide full validation support when the Format-Assertion vocabulary is not specified.¶

When the implementation is configured for assertion behavior, it:¶

• SHOULD provide an implementation-specific best effort validation for each format attribute defined below;¶

• MAY choose to implement validation of any or all format attributes as a no-op by always producing a validation result of true;¶

This matches the current reality of implementations, which provide widely varying levels of validation, including no validation at all, for some or all format attributes. It is also designed to encourage relying only on the annotation behavior and performing semantic validation in the application, which is the recommended best practice.¶

9.2.2. Format-Assertion Vocabulary

When the Format-Assertion vocabulary is declared with a value of true, implementations MUST provide full validation support for all of the formats defined by this specificaion. Implementations that cannot provide full validation support MUST refuse to process the schema.¶

An implementation that supports the Format-Assertion vocabulary:¶

• MUST still collect "format" as an annotation if the implementation supports annotation collection;¶

• MUST evaluate "format" as an assertion;¶

• MUST implement syntactic validation for all format attributes defined in this specification, and for any additional format attributes that it recognizes, such that there exist possible input values of the correct type that will fail validation.¶

The requirement for minimal validation of format attributes is intentionally vague and permissive, due to the complexity involved in many of the attributes. Note in particular that the requirement is limited to syntactic checking; it is not to be expected that an implementation would send an email, attempt to connect to a URL, or otherwise check the existence of an entity identified by a format instance.The expectation is that for simple formats such as date-time, syntactic validation will be thorough. For a complex format such as email addresses, which are the amalgamation of various standards and numerous adjustments over time, with obscure and/or obsolete rules that may or may not be restricted by other applications making use of the value, a minimal validation is sufficient. For example, an input string that does not contain an "@" is clearly not a valid email address, and an "email" or "hostname" containing characters outside of 7-bit ASCII is likewise clearly invalid.¶

It is RECOMMENDED that implementations use a common parsing library for each format, or a well-known regular expression. Implementations SHOULD clearly document how and to what degree each format attribute is validated.¶

The standard core and validation meta-schema includes this vocabulary in its "$vocabulary" keyword with a value of false, since by default implementations are not required to support this keyword as an assertion. Supporting the format vocabulary with a value of true is understood to greatly increase code size and in some cases execution time, and will not be appropriate for all implementations.¶

9.2.3. Custom format attributes

Implementations MAY support custom format attributes. Save for agreement between parties, schema authors SHALL NOT expect a peer implementation to support such custom format attributes. An implementation MUST NOT fail to collect unknown formats as annotations. When the Format-Assertion vocabulary is specified, implementations MUST fail upon encountering unknown formats.¶

Vocabularies do not support specifically declaring different value sets for keywords. Due to this limitation, and the historically uneven implementation of this keyword, it is RECOMMENDED to define additional keywords in a custom vocabulary rather than additional format attributes if interoperability is desired.¶

9.3.1. Dates, Times, and Duration

These attributes apply to string inputs.¶

Date and time format names are derived from [RFC3339], Section 5.6. The duration format is from the ISO 8601 ABNF as given in Appendix A of RFC 3339.¶

Implementations supporting formats SHOULD implement support for the following attributes:¶

9.3.2. Email Addresses

These attributes apply to string inputs.¶

A string input is valid against these attributes if it is a valid Internet email address as follows:¶

9.3.3. Hostnames

These attributes apply to string inputs.¶

A string input is valid against these attributes if it is a valid representation for an Internet hostname as follows:¶

9.3.4. IP Addresses

These attributes apply to string inputs.¶

A string input is valid against these attributes if it is a valid representation of an IP address as follows:¶

9.3.5. Resource Identifiers

These attributes apply to string inputs.¶

9.3.6. Templates

9.3.7. JSON Pointers

These attributes apply to string inputs.¶

To allow for both regular and relative JSON Pointers, use "anyOf" or "oneOf" to indicate support for either format.¶

9.3.8. Expressions

12.1.1. Initial Base URI

[RFC3986], Section 5.1 defines how to determine the default base URI of a document.¶

Informatively, the initial base URI of a schema is the URI at which it was found, whether that was a network location, a local filesystem, or any other situation identifiable by a URI of any known scheme.¶

If a schema document defines no explicit base URI with "$id" (embedded in content), the base URI is that determined per [RFC3986], Section 5.¶

If no source is known, or no URI scheme is known for the source, a suitable implementation-specific default URI MAY be used as described in [RFC3986], Section 5.1.4. It is RECOMMENDED that implementations document any default base URI that they assume.¶

If a schema object is embedded in a document of another media type, then the initial base URI is determined according to the rules of that media type.¶

Unless the "$id" keyword described in an earlier section is present in the root schema, this base URI SHOULD be considered the canonical URI of the schema document's root schema resource.¶

12.1.2. Loading a referenced schema

Although it's impossible to cover all use cases, we start by assuming that an implementation given a schema with references to other schemas not in the same document can be given instructions about those other documents, and the implementation therefore SHOULD NOT automatically dereference network locations or search the network for schemas not already loaded in.¶

What should implementations do when the referenced schema is not known? The implementation could have error messages, flags or UX to explicitly get instructions to fetch a schema or to signal that it should be configured differently. The examples from HTTP of same-origin policies would seem relevant here too, but such a feature has not yet been defined for JSON Schema.¶

Some use cases may involve schema definitions that regularly are extended or updated by reference. For example, a service hosting an evolving API might include documentation and requirements via JSON schemas, and the schemas might be intended for dynamic fetching and inclusion of sub-schemas, so placing an absolute requirement of pre-loading schema documents is not feasible.¶

When schemas are downloaded, for example by a generic user-agent that does not know until runtime which schemas to download, see Usage for Hypermedia (Section 12.5).¶

Implementations SHOULD be able to associate arbitrary URIs with an arbitrary schema and/or automatically associate a schema's "$id"-given URI, depending on the trust that the implementation has in the schema. Such URIs and schemas can be supplied to an implementation prior to processing instances, or may be noted within a schema document as it is processed, producing associations as shown in Appendix A.¶

A schema MAY (and likely will) have multiple URIs, but there is no way for a URI to identify more than one schema. When multiple schemas try to identify as the same URI, an implementation SHOULD raise an error condition.¶

12.1.3. Detecting a Meta-Schema

Implementations MUST recognize a schema as a meta-schema if it is being examined because it was identified as such by another schema's "$schema" keyword. This means that a single schema document might sometimes be considered a regular schema, and other times be considered a meta-schema.¶

In the case of examining a schema which is its own meta-schema, when an implementation begins processing it as a regular schema, it is processed under those rules. However, when loaded a second time as a result of checking its own "$schema" value, it is treated as a meta-schema. So the same document is processed both ways in the course of one session.¶

Implementations MAY allow a schema to be explicitly passed as a meta-schema, for implementation-specific purposes, such as pre-loading a commonly used meta-schema and checking its vocabulary support requirements up front. Meta-schema authors MUST NOT expect such features to be interoperable across implementations.¶

12.2.1. Relative References

Many hypermedia contexts (like HTML) make use of full URIs, anchors/names, and relative references ([RFC3986], Section 5.1). In JSON Schema, different contexts and use cases may make any of these three approaches the most convenient and least brittle; but relative references do require the most care in implementations.¶

A fully conformant implementation MUST handle relative references, with the following guidance hopefully keeping implementation logic and overhead to a reasonable level. A schema's $id acts as a base URI (see [RFC3986], Section 5.1.1) for relative references within the schema.¶

In accordance with [RFC3986], Section 5.1.2 regarding encapsulating entities, if an "$id" in a subschema is a relative reference, the base URI for resolving that reference is the URI of the parent schema resource.¶

If no parent schema object explicitly identifies itself as a resource with "$id", the base URI is that of the entire document, as established by the steps given in Section 12.1.1.¶

12.2.2. JSON Pointer fragments and embedded schema resources

JSON Pointer URI fragments are constructed based on the structure of the schema document, allowing an embedded schema resource and its subschemas to be identified by JSON Pointer fragments relative to either its own canonical URI, or relative to any containing resource's URI.¶

Conceptually, a set of linked schema resources should behave identically whether each resource is a separate document connected with schema references (Section 5.2.1), or is structured as a single document with one or more schema resources embedded as subschemas.¶

Since URIs involving JSON Pointer fragments relative to the parent schema resource's URI cease to be valid when the embedded schema is moved to a separate document and referenced, applications and schemas SHOULD NOT use such URIs to identify embedded schema resources or locations within them.¶

Consider the following schema document that contains another schema resource embedded within it:¶

{
  "$id": "https://example.com/foo",
  "items": {
    "$id": "https://example.com/bar",
    "additionalProperties": { }
  }
}

The URI "https://example.com/foo#/items" points to the "items" schema, which is an embedded resource. The canonical URI of that schema resource, however, is "https://example.com/bar".¶

For the "additionalProperties" schema within that embedded resource, the URI "https://example.com/foo#/items/additionalProperties" points to the correct object, but that object's URI relative to its resource's canonical URI is "https://example.com/bar#/additionalProperties".¶

Now consider the following two schema resources linked by reference using a URI value for "$ref":¶

{
  "$id": "https://example.com/foo",
  "items": {
    "$ref": "bar"
  }
}

{
  "$id": "https://example.com/bar",
  "additionalProperties": { }
}

Here we see that "https://example.com/bar#/additionalProperties", using a JSON Pointer fragment appended to the canonical URI of the "bar" schema resource, is still valid, while "https://example.com/foo#/items/additionalProperties", which relied on a JSON Pointer fragment appended to the canonical URI of the "foo" schema resource, no longer resolves to anything.¶

Note also that "https://example.com/foo#/items" is valid in both arrangements, but resolves to a different value. This URI ends up functioning similarly to a retrieval URI for a resource. While this URI is valid, it is more robust to use the "$id" of the embedded or referenced resource unless it is specifically desired to identify the object containing the "$ref" in the second (non-embedded) arrangement.¶

An implementation MAY choose not to support addressing schema resource contents by URIs using a base other than the resource's canonical URI, plus a JSON Pointer fragment relative to that base. Therefore, schema authors SHOULD NOT rely on such URIs, as using them may reduce interoperability.This is to avoid requiring implementations to keep track of a whole stack of possible base URIs and JSON Pointer fragments for each, given that all but one will be fragile if the schema resources are reorganized. Some have argued that this is easy so there is no point in forbidding it, while others have argued that it complicates schema identification and should be forbidden. Feedback on this topic is encouraged. After some discussion, we feel that we need to remove the use of "canonical" in favour of talking about JSON Pointers which reference across schema resource boundaries as undefined or even forbidden behavior (https://github.com/json-schema-org/json-schema-spec/issues/937, https://github.com/json-schema-org/json-schema-spec/issues/1183)¶

Further examples of such non-canonical URI construction, as well as the appropriate canonical URI-based fragments to use instead, are provided in Appendix A.¶

12.3.1. Bundling

The bundling process for creating a Compound Schema Document is defined as taking references (such as "$ref") to an external Schema Resource and embedding the referenced Schema Resources within the referring document. Bundling SHOULD be done in such a way that all URIs (used for referencing) in the base document and any referenced/embedded documents do not require altering.¶

Each embedded JSON Schema Resource MUST identify itself with a URI using the "$id" keyword, and SHOULD make use of the "$schema" keyword to identify the dialect it is using, in the root of the schema resource. It is RECOMMENDED that the URI identifier value of "$id" be an absolute URI.¶

When the Schema Resource referenced by a by-reference applicator is bundled, it is RECOMMENDED that the Schema Resource be located as a value of a "$defs" object at the containing schema's root. The key of the "$defs" for the now embedded Schema Resource MAY be the "$id" of the bundled schema or some other form of application defined unique identifer (such as a UUID). This key is not intended to be referenced in JSON Schema, but may be used by an application to aid the bundling process.¶

A Schema Resource MAY be embedded in a location other than "$defs" where the location is defined as a schema value.¶

A Bundled Schema Resource MUST NOT be bundled by replacing the schema object from which it was referenced, or by wrapping the Schema Resource in other applicator keywords.¶

In order to produce identical output, references in the containing schema document to the previously external Schema Resources MUST NOT be changed, and now resolve to a schema using the "$id" of an embedded Schema Resource. Such identical output includes validation evaluation and URIs or paths used in resulting annotations or errors.¶

While the bundling process will often be the main method for creating a Compound Schema Document, it is also possible and expected that some will be created by hand, potentially without individual Schema Resources existing on their own previously.¶

12.3.2. Differing and Default Dialects

When multiple schema resources are present in a single document, schema resources which do not define with which dialect they should be processed MUST be processed with the same dialect as the enclosing resource.¶

Since any schema that can be referenced can also be embedded, embedded schema resources MAY specify different processing dialects using the "$schema" values from their enclosing resource.¶

12.3.3. Validating

Given that a Compound Schema Document may have embedded resources which identify as using different dialects, these documents SHOULD NOT be validated by applying a meta-schema to the Compound Schema Document as an instance. It is RECOMMENDED that an alternate validation process be provided in order to validate Schema Documents. Each Schema Resource SHOULD be separately validated against its associated meta-schema.If you know a schema is what's being validated, you can identify if the schemas is a Compound Schema Document or not, by way of use of "$id", which identifies an embedded resource when used not at the document's root.¶

A Compound Schema Document in which all embedded resources identify as using the same dialect, or in which "$schema" is omitted and therefore defaults to that of the enclosing resource, MAY be validated by applying the appropriate meta-schema.¶

12.4.1. Guarding Against Infinite Recursion

A schema MUST NOT be run into an infinite loop evaluating input. For example, if two schemas "#alice" and "#bob" both have an "allOf" property that refers to the other, a naive implementation might get stuck in an infinite recursive loop trying to validate the input. Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is undefined.¶

12.4.2. References to Possible Non-Schemas"

Subschema objects (or booleans) are recognized by their use with known applicator keywords or with location-reserving keywords such as "$defs" (Section 5.2.2) that take one or more subschemas as a value. These keywords may be "$defs" and the standard applicators from this document, or extension keywords from a known vocabulary, or implementation-specific custom keywords.¶

Multi-level structures of unknown keywords are capable of introducing nested subschemas, which would be subject to the processing rules for "$id". Therefore, having a reference target in such an unrecognized structure cannot be reliably implemented, and the resulting behavior is undefined. Similarly, a reference target under a known keyword, for which the value is known not to be a schema, results in undefined behavior in order to avoid burdening implementations with the need to detect such targets.These scenarios are analogous to fetching a schema over HTTP but receiving a response with a Content-Type other than application/schema+json. An implementation can certainly try to interpret it as a schema, but the origin server offered no guarantee that it actually is any such thing. Therefore, interpreting it as such has security implications and may produce unpredictable results.¶

Note that single-level custom keywords with identical syntax and semantics to "$defs" do not allow for any intervening "$id" keywords, and therefore will behave correctly under implementations that attempt to use any reference target as a schema. However, this behavior is¶

12.5.1. Linking to a Schema

It is RECOMMENDED that instances described by a schema provide a link to a downloadable JSON Schema using the link relation "describedby", as defined by Linked Data Protocol 1.0, ([LDP] Section 8.1.¶

In HTTP, such links can be attached to any response using the Link header ([RFC8288]). An example of such a header would be:¶

        Link: <https://example.com/my-hyper-schema>; rel="describedby"

12.5.2. Usage Over HTTP

When used for hypermedia systems over a network, HTTP ([RFC9110]) is frequently the protocol of choice for distributing schemas. Misbehaving clients can pose problems for server maintainers if they pull a schema over the network more frequently than necessary, when it's instead possible to cache a schema for a long period of time.¶

HTTP servers SHOULD set long-lived caching headers on JSON Schemas. HTTP clients SHOULD observe caching headers and not re-request documents within their freshness period. Distributed systems SHOULD make use of a shared cache and/or caching proxy.¶

Clients SHOULD set or prepend a User-Agent header specific to the JSON Schema implementation or software product. Since symbols are listed in decreasing order of significance, the JSON Schema library name/version should precede the more generic HTTP library name (if any). For example:¶

        User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0

Clients SHOULD be able to make requests with a "From" header so that server operators can contact the owner of a potentially misbehaving script.¶

13.6.1. Referenced and Referencing Schemas

As noted in Section 13.6, an applicator keyword may refer to a schema to be applied, rather than including it as a subschema in the applicator's value. In such situations, the schema being applied is known as the referenced schema, while the schema containing the applicator keyword is the referencing schema.¶

While root schemas and subschemas are static concepts based on a schema's position within a schema document, referenced and referencing schemas are dynamic. Different pairs of schemas may find themselves in various referenced and referencing arrangements during the evaluation of input against a schema.¶

For some by-reference applicators, such as "$ref" (Section 5.2.1), the referenced schema can be determined by static analysis of the schema document's lexical scope. Others, such as "$dynamicRef" (with "$dynamicAnchor"), may make use of dynamic scoping, and therefore only be resolvable in the process of evaluating an input with the schema.¶

13.7.1. Assertions and Input Primitive Types

Most assertions only constrain values within a certain primitive type. When the type of the input is not of the type targeted by the keyword, the input is considered to conform to the assertion.¶

For example, the "maxLength" keyword from the companion validation vocabulary ([I-D.bhutton-json-schema-validation]): will only restrict certain strings (that are too long) from being valid. If the input is a number, boolean, null, array, or object, then it is valid against this assertion.¶

This behavior allows keywords to be used more easily with inputs that can be of multiple primitive types. The companion validation vocabulary also includes a "type" keyword which can independently restrict the input to one or more primitive types. This allows for a concise expression of use cases such as a function that might return either a string of a certain length or a null value:¶

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

If "maxLength" also restricted the input type to be a string, then this would be substantially more cumbersome to express because the example as written would not actually allow null values. Each keyword is evaluated separately unless explicitly specified otherwise, so if "maxLength" restricted the input to strings, then including "null" in "type" would not have any useful effect.¶

13.8.1. Collecting Annotations

Annotations are collected by keywords that explicitly define annotation-collecting behavior. Note that boolean schemas cannot produce annotations as they do not make use of keywords.¶

A collected annotation MUST include the following information:¶

• The name of the keyword that produces the annotation¶

• The instance location to which it is attached, as a JSON Pointer¶

• The schema location path, indicating how reference keywords such as "$ref" were followed to reach the absolute schema location.¶

• The absolute schema location of the attaching keyword, as a URI. This MAY be omitted if it is the same as the schema location path from above.¶

• The attached value(s)¶

{
  "title": "Feature list",
  "type": "array",
  "prefixItems": [
    {
      "title": "Feature A",
      "properties": {
        "enabled": {
          "$ref": "#/$defs/enabledToggle",
          "default": true
        }
      }
    },
    {
      "title": "Feature B",
      "properties": {
        "enabled": {
          "description": "If set to null, Feature B inherits the enabled value from Feature A",
          "$ref": "#/$defs/enabledToggle"
        }
      }
    }
  ],
  "$defs": {
    "enabledToggle": {
      "title": "Enabled",
      "description": "Whether the feature is enabled (true), disabled (false), or under automatic control (null)",
      "type": ["boolean", "null"],
      "default": null
    }
  }
}

{
    "oneOf": [
        {
            "title": "Integer Value",
            "type": "integer"
        },
        {
            "title": "String Value",
            "type": "string"
        }
    ]
}

14.3.1. Keyword Relative Location

The relative location of the validating keyword that follows the validation path. The value MUST be expressed as a JSON Pointer, and it MUST include any by-reference applicators such as "$ref" or "$dynamicRef".¶

/properties/width/$ref/minimum

Note that this pointer may not be resolvable by the normal JSON Pointer process due to the inclusion of these by-reference applicator keywords.¶

The JSON key for this information is "keywordLocation".¶

14.3.2. Keyword Absolute Location

The absolute, dereferenced location of the validating keyword. The value MUST be expressed as a full URI using the canonical URI of the relevant schema resource with a JSON Pointer fragment, and it MUST NOT include by-reference applicators such as "$ref" or "$dynamicRef" as non-terminal path components. It MAY end in such keywords if the error or annotation is for that keyword, such as an unresolvable reference.Note that "absolute" here is in the sense of "absolute filesystem path" (meaning the complete location) rather than the "absolute-URI" terminology from RFC 3986 (meaning with scheme but without fragment). Keyword absolute locations will have a fragment in order to identify the keyword.¶

https://example.com/schemas/common#/$defs/count/minimum

This information MAY be omitted only if either the dynamic scope did not pass over a reference or if the schema does not declare an absolute URI as its "$id".¶

The JSON key for this information is "absoluteKeywordLocation".¶

14.3.3. Instance Location

The location of the JSON value within the instance. The value MUST be expressed as a JSON Pointer.¶

The JSON key for this information is "instanceLocation".¶

14.3.4. Error or Annotation

The error or annotation that is produced by the validation.¶

For errors, the specific wording for the message is not defined by this specification. Implementations will need to provide this.¶

For annotations, each keyword that produces an annotation specifies its format. By default, it is the keyword's value.¶

The JSON key for failed validations is "error"; for successful validations it is "annotation".¶

14.3.5. Nested Results

For the two hierarchical structures, this property will hold nested errors and annotations.¶

The JSON key for nested results in failed validations is "errors"; for successful validations it is "annotations". Note the plural forms, as a keyword with nested results can also have a local error or annotation.¶

14.4.1. Flag

In the simplest case, merely the boolean result for the "valid" valid property needs to be fulfilled.¶

{
  "valid": false
}

Because no errors or annotations are returned with this format, it is RECOMMENDED that implementations use short-circuiting logic to return failure or success as soon as the outcome can be determined. For example, if an "anyOf" keyword contains five sub-schemas, and the second one passes, there is no need to check the other three. The logic can simply return with success.¶

14.4.2. Basic

The "Basic" structure is a flat list of output units.¶

{
  "valid": false,
  "errors": [
    {
      "keywordLocation": "",
      "instanceLocation": "",
      "error": "A subschema had errors."
    },
    {
      "keywordLocation": "/items/$ref",
      "absoluteKeywordLocation":
        "https://example.com/polygon#/$defs/point",
      "instanceLocation": "/1",
      "error": "A subschema had errors."
    },
    {
      "keywordLocation": "/items/$ref/required",
      "absoluteKeywordLocation":
        "https://example.com/polygon#/$defs/point/required",
      "instanceLocation": "/1",
      "error": "Required property 'y' not found."
    },
    {
      "keywordLocation": "/items/$ref/additionalProperties",
      "absoluteKeywordLocation":
        "https://example.com/polygon#/$defs/point/additionalProperties",
      "instanceLocation": "/1/z",
      "error": "Additional property 'z' found but was invalid."
    },
    {
      "keywordLocation": "/minItems",
      "instanceLocation": "",
      "error": "Expected at least 3 items but found 2"
    }
  ]
}

14.4.3. Detailed

The "Detailed" structure is based on the schema and can be more readable for both humans and machines. Having the structure organized this way makes associations between the errors more apparent. For example, the fact that the missing "y" property and the extra "z" property both stem from the same location in the instance is not immediately obvious in the "Basic" structure. In a hierarchy, the correlation is more easily identified.¶

The following rules govern the construction of the results object:¶

• All applicator keywords ("*Of", "$ref", "if"/"then"/"else", etc.) require a node.¶

• Nodes that have no children are removed.¶

• Nodes that have a single child are replaced by the child.¶

Branch nodes do not require an error message or an annotation.¶

{
  "valid": false,
  "keywordLocation": "",
  "instanceLocation": "",
  "errors": [
    {
      "valid": false,
      "keywordLocation": "/items/$ref",
      "absoluteKeywordLocation":
        "https://example.com/polygon#/$defs/point",
      "instanceLocation": "/1",
      "errors": [
        {
          "valid": false,
          "keywordLocation": "/items/$ref/required",
          "absoluteKeywordLocation":
            "https://example.com/polygon#/$defs/point/required",
          "instanceLocation": "/1",
          "error": "Required property 'y' not found."
        },
        {
          "valid": false,
          "keywordLocation": "/items/$ref/additionalProperties",
          "absoluteKeywordLocation":
            "https://example.com/polygon#/$defs/point/additionalProperties",
          "instanceLocation": "/1/z",
          "error": "Additional property 'z' found but was invalid."
        }
      ]
    },
    {
      "valid": false,
      "keywordLocation": "/minItems",
      "instanceLocation": "",
      "error": "Expected at least 3 items but found 2"
    }
  ]
}

14.4.4. Verbose

The "Verbose" structure is a fully realized hierarchy that exactly matches that of the schema. This structure has applications in form generation and validation where the error's location is important.¶

The primary difference between this and the "Detailed" structure is that all results are returned. This includes sub-schema validation results that would otherwise be removed (e.g. annotations for failed validations, successful validations inside a not keyword, etc.). Because of this, it is RECOMMENDED that each node also carry a valid property to indicate the validation result for that node.¶

Because this output structure can be quite large, a smaller example is given here for brevity. The URI of the full output structure of the example above is: https://json-schema.org/draft/2020-12/output/verbose-example.¶

schema:¶

{
  "$id": "https://example.com/polygon",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "validProp": true
  },
  "additionalProperties": false
}

input:¶

{
  "validProp": 5,
  "disallowedProp": "value"
}

result:¶

{
  "valid": false,
  "keywordLocation": "",
  "instanceLocation": "",
  "errors": [
    {
      "valid": true,
      "keywordLocation": "/type",
      "instanceLocation": ""
    },
    {
      "valid": true,
      "keywordLocation": "/properties",
      "instanceLocation": ""
    },
    {
      "valid": false,
      "keywordLocation": "/additionalProperties",
      "instanceLocation": "",
      "errors": [
        {
          "valid": false,
          "keywordLocation": "/additionalProperties",
          "instanceLocation": "/disallowedProp",
          "error": "Additional property 'disallowedProp' found but was invalid."
        }
      ]
    }
  ]
}

14.4.5. Output validation schemas

For convenience, JSON Schema has been provided to validate output generated by implementations. Its URI is: https://json-schema.org/draft/2020-12/output/schema.¶