+ JSON Schema defines the media type "application/schema+json", a JSON-based format
+ for describing the structure of JSON data.
+ JSON Schema asserts what a JSON document must look like,
+ ways to extract information from it,
+ and how to interact with it.
+ The "application/schema-instance+json" media type provides additional
+ feature-rich integration with "application/schema+json" beyond what can be offered
+ for "application/json" documents.¶
+ This Internet-Draft is submitted in full conformance with the
+ provisions of BCP 78 and BCP 79.¶
+
+ Internet-Drafts are working documents of the Internet Engineering Task
+ Force (IETF). Note that other groups may also distribute working
+ documents as Internet-Drafts. The list of current Internet-Drafts is
+ at https://datatracker.ietf.org/drafts/current/.¶
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."¶
+
+ This Internet-Draft will expire on 30 October 2022.¶
+ Copyright (c) 2022 IETF Trust and the persons identified as the
+ document authors. All rights reserved.¶
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (https://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with
+ respect to this document. Code Components extracted from this
+ document must include Revised BSD License text as described in
+ Section 4.e of the Trust Legal Provisions and are provided without
+ warranty as described in the Revised BSD License.¶
+ JSON Schema is a JSON media type for defining the structure of JSON data. JSON Schema
+ is intended to define validation, documentation, hyperlink navigation, and interaction
+ control of JSON data.¶
+
+ This specification defines JSON Schema core terminology and mechanisms, including
+ pointing to another JSON Schema by reference,
+ dereferencing a JSON Schema reference,
+ specifying the dialect being used,
+ specifying a dialect's vocabulary requirements,
+ and defining the expected output.¶
+
+ Other specifications define the vocabularies that perform assertions about validation,
+ linking, annotation, navigation, and interaction.¶
+
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+ "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+ interpreted as described in RFC 2119 [RFC2119].¶
+
+ The terms "JSON", "JSON text", "JSON value", "member", "element", "object", "array",
+ "number", "string", "boolean", "true", "false", and "null" in this document are to
+ be interpreted as defined in RFC 8259 [RFC8259].¶
+ This document proposes a new media type "application/schema+json" to identify a JSON
+ Schema for describing JSON data.
+ It also proposes a further optional media type, "application/schema-instance+json",
+ to provide additional integration features.
+ JSON Schemas are themselves JSON documents.
+ This, and related specifications, define keywords allowing authors to describe JSON
+ data in several ways.¶
+
+ JSON Schema uses keywords to assert constraints on JSON instances or annotate those
+ instances with additional information. Additional keywords are used to apply
+ assertions and annotations to more complex JSON data structures, or based on
+ some sort of condition.¶
+
+ To facilitate re-use, keywords can be organized into vocabularies. A vocabulary
+ consists of a list of keywords, together with their syntax and semantics.
+ A dialect is defined as a set of vocabularies and their required support
+ identified in a meta-schema.¶
+
+ JSON Schema can be extended either by defining additional vocabularies,
+ or less formally by defining additional keywords outside of any vocabulary.
+ Unrecognized individual keywords simply have their values collected as annotations,
+ while the behavior with respect to an unrecognized vocabulary can be controlled
+ when declaring which vocabularies are in use.¶
+
+ This document defines a core vocabulary that MUST be supported by any
+ implementation, and cannot be disabled. Its keywords are each prefixed
+ with a "$" character to emphasize their required nature. This vocabulary
+ is essential to the functioning of the "application/schema+json" media
+ type, and is used to bootstrap the loading of other vocabularies.¶
+
+ Additionally, this document defines a RECOMMENDED vocabulary of keywords
+ for applying subschemas conditionally, and for applying subschemas to
+ the contents of objects and arrays. Either this vocabulary or one very
+ much like it is required to write schemas for non-trivial JSON instances,
+ whether those schemas are intended for assertion validation, annotation,
+ or both. While not part of the required core vocabulary, for maximum
+ interoperability this additional vocabulary is included in this document
+ and its use is strongly encouraged.¶
+
+ Further vocabularies for purposes such as structural validation or
+ hypermedia annotation are defined in other documents. These other
+ documents each define a dialect collecting the standard sets of
+ vocabularies needed to write schemas for that document's purpose.¶
+ A JSON document is an information resource (series of octets) described by the
+ application/json media type.¶
+
+ In JSON Schema, the terms "JSON document", "JSON text", and "JSON value" are
+ interchangeable because of the data model it defines.¶
+
+ JSON Schema is only defined over JSON documents. However, any document or memory
+ structure that can be parsed into or processed according to the JSON Schema data
+ model can be interpreted against a JSON Schema, including media types like
+ CBOR [RFC7049].¶
A "true" or "false" value, from the JSON "true" or "false" value¶
+
+
+
object:
+
An unordered set of properties mapping a string to an instance, from the JSON "object" value¶
+
+
+
array:
+
An ordered list of instances, from the JSON "array" value¶
+
+
+
number:
+
An arbitrary-precision, base-10 decimal number value, from the JSON "number" value¶
+
+
+
string:
+
A string of Unicode code points, from the JSON "string" value¶
+
+
+
+
+ Whitespace and formatting concerns, including different lexical
+ representations of numbers that are equal within the data model, are thus
+ outside the scope of JSON Schema. JSON Schema
+ vocabularies (Section 8.1) that wish
+ to work with such differences in lexical representations SHOULD define
+ keywords to precisely interpret formatted strings within the data model
+ rather than relying on having the original JSON representation Unicode
+ characters available.¶
+
+ Since an object cannot have two properties with the same key, behavior for a
+ JSON document that tries to define two properties with
+ the same key in a single object is undefined.¶
+
+ Note that JSON Schema vocabularies are free to define their own extended
+ type system. This should not be confused with the core data model types
+ defined here. As an example, "integer" is a reasonable type for a
+ vocabulary to define as a value for a keyword, but the data model
+ makes no distinction between integers and other numbers.¶
+ Two JSON instances are said to be equal if and only if they are of the same type
+ and have the same value according to the data model. Specifically, this means:¶
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.¶
+ It is possible to use JSON Schema with a superset of the JSON Schema data model,
+ where an instance may be outside any of the six JSON data types.¶
+
+ In this case, annotations still apply; but most validation keywords will not be useful,
+ as they will always pass or always fail.¶
+
+ A custom vocabulary may define support for a superset of the core data model.
+ The schema itself may only be expressible in this superset;
+ for example, to make use of the "const" keyword.¶
+ A JSON Schema document, or simply a schema, is a JSON document used to describe
+ an instance.
+ A schema can itself be interpreted as an instance, but SHOULD always be given
+ the media type "application/schema+json" rather than
+ "application/schema-instance+json". The "application/schema+json" media
+ type is defined to offer a superset of the
+ fragment identifier syntax and semantics provided by
+ "application/schema-instance+json".¶
+ Object properties that are applied to the instance are called keywords,
+ or schema keywords. Broadly speaking, keywords fall into one
+ of five categories:¶
+
+
identifiers:
+
+ control schema identification through setting a URI
+ for the schema and/or changing how the base URI is determined¶
+
+
+
assertions:
+
+ produce a boolean result when applied to an instance¶
+
+
+
annotations:
+
+ attach information to an instance for application use¶
+
+
+
applicators:
+
+ apply one or more subschemas to a particular location
+ in the instance, and combine or modify their results¶
+
+
+
reserved locations:
+
+ do not directly affect results, but reserve a place
+ for a specific purpose to ensure interoperability¶
+
+
+
+
+ Keywords may fall into multiple categories, although applicators
+ SHOULD only produce assertion results based on their subschemas'
+ results. They should not define additional constraints independent
+ of their subschemas.¶
+
+ Keywords which are properties within the same schema object are referred to as adjacent keywords.¶
+
+ Extension keywords, meaning those defined outside of this document
+ and its companions, are free to define other behaviors as well.¶
+
+ A JSON Schema MAY contain properties which are not schema keywords.
+ Unknown keywords SHOULD be treated as annotations, where the value
+ of the keyword is the value of the annotation.¶
+
+ An empty schema is a JSON Schema with no properties, or only unknown
+ properties.¶
+ The boolean schema values "true" and "false" are trivial schemas that
+ always produce themselves as assertion results, regardless of the
+ instance value. They never produce annotation results.¶
+
+ These 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.¶
+ A schema vocabulary, or simply a vocabulary, is a set of keywords,
+ their syntax, and their semantics. A vocabulary is generally organized
+ around a particular purpose. Different uses of JSON Schema, such
+ as validation, hypermedia, or user interface generation, will
+ involve different sets of vocabularies.¶
+
+ Vocabularies are the primary unit of re-use in JSON Schema, as schema
+ authors can indicate what vocabularies are required or optional in
+ order to process the schema. Since vocabularies are identified by URIs
+ in the meta-schema, generic implementations can load extensions to support
+ previously unknown vocabularies. While keywords can be supported outside
+ of any vocabulary, there is no analogous mechanism to indicate individual
+ keyword usage.¶
+
+ A schema vocabulary can be defined by anything from an informal description
+ to a standards proposal, depending on the audience and interoperability
+ expectations. In particular, in order to facilitate vocabulary use within
+ non-public organizations, a vocabulary specification need not be published
+ outside of its scope of use.¶
+ A schema that itself describes a schema is called a meta-schema.
+ Meta-schemas are used to validate JSON Schemas and specify which vocabularies
+ they are using.¶
+
+ Typically, a meta-schema will specify a set of vocabularies, and validate
+ schemas that conform to the syntax of those vocabularies. However, meta-schemas
+ and vocabularies are separate in order to allow meta-schemas to validate
+ schema conformance more strictly or more loosely than the vocabularies'
+ specifications call for. Meta-schemas may also describe and validate
+ additional keywords that are not part of a formal vocabulary.¶
+ A JSON Schema resource is a schema which is
+ canonically [RFC6596] identified by an
+ absolute URI [RFC3986]. Schema resources MAY
+ also be identified by URIs, including URIs with fragments,
+ if the resulting secondary resource (as defined by
+ section 3.5 of RFC 3986 [RFC3986]) 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 the schema that comprises the entire JSON document
+ in question. The root schema is always a schema resource, where the
+ URI is determined as described in section
+ 9.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:¶
+ 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
+ 8.2.1, 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.¶
+ In accordance with section 3.1 of RFC 6839 [RFC6839],
+ the syntax and semantics of fragment identifiers specified for
+ any +json media type SHOULD be as specified for "application/json".
+ (At publication of this document, there is no fragment identification
+ syntax defined for "application/json".)¶
+
+ Additionally, the "application/schema+json" media type supports two
+ fragment identifier structures: plain names and JSON Pointers.
+ The "application/schema-instance+json" media type supports one
+ fragment identifier structure: JSON Pointers.¶
+
+ The use of JSON Pointers as URI fragment identifiers is described in
+ RFC 6901 [RFC6901].
+ For "application/schema+json", which supports two fragment identifier syntaxes,
+ fragment identifiers matching the JSON Pointer syntax, including the empty string,
+ MUST be interpreted as JSON Pointer fragment identifiers.¶
+
+ Per the W3C's
+ best practices for fragment identifiers [W3C.WD-fragid-best-practices-20121025],
+ plain name fragment identifiers in "application/schema+json" are reserved for referencing
+ locally named schemas. All fragment identifiers that do
+ not match the JSON Pointer syntax MUST be interpreted as
+ plain name fragment identifiers.¶
+
+ Defining and referencing a plain name fragment identifier within an
+ "application/schema+json" document are specified
+ in the "$anchor" keyword (Section 8.2.2) section.¶
+ 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.¶
+ JSON Schema is programming language agnostic, and supports the full range of
+ values described in the data model.
+ Be aware, however, that some languages and JSON parsers may not be able to
+ represent in memory the full range of values describable by JSON.¶
+ Keywords MAY use regular expressions to express constraints, or constrain
+ the instance value to be a regular expression.
+ These regular expressions SHOULD be valid according to the regular expression
+ dialect described in ECMA-262, section 21.2.1 [ecma262].¶
+
+ Regular expressions SHOULD be built with the "u" flag (or equivalent) to provide
+ Unicode support, or processed in such a way which provides Unicode support as
+ defined by ECMA-262.¶
+
+ Furthermore, given the high disparity in regular expression constructs support,
+ schema authors SHOULD limit themselves to the following regular expression
+ tokens:¶
simple character classes ([abc]), range character classes ([a-z]);¶
+
+
complemented character classes ([^abc], [^a-z]);¶
+
+
simple quantifiers: "+" (one or more), "*" (zero or more), "?" (zero or
+ one), and their lazy versions ("+?", "*?", "??");¶
+
+
range quantifiers: "{x}" (exactly x occurrences), "{x,y}" (at least x, at
+ most y, occurrences), {x,} (x occurrences or more), and their lazy
+ versions;¶
+
+
the beginning-of-input ("^") and end-of-input ("$") anchors;¶
+
+
simple grouping ("(...)") and alternation ("|").¶
+
+
+
+ Finally, implementations MUST NOT take regular expressions to be
+ anchored, neither at the beginning nor at the end. This means, for instance,
+ the pattern "es" matches "expression".¶
+ 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.¶
+ JSON Schema keywords fall into several general behavior categories.
+ Assertions validate that an instance satisfies constraints, producing
+ a boolean result. Annotations attach information that applications
+ may use in any way they see fit.
+ Applicators apply subschemas to parts of the instance and combine
+ their results.¶
+
+ Extension keywords SHOULD stay within these categories, keeping in mind
+ that annotations in particular are extremely flexible. Complex behavior
+ is usually better delegated to applications on the basis of annotation
+ data than implemented directly as schema keywords. However, extension
+ keywords MAY define other behaviors for specialized purposes.¶
+
+ Evaluating an instance against a schema involves processing all of the
+ keywords in the schema against the appropriate locations within the instance.
+ Typically, applicator keywords are processed until a schema object with no
+ applicators (and therefore no subschemas) is reached. The appropriate
+ location in the instance is evaluated against the assertion and
+ annotation keywords in the schema object, and their results are gathered
+ into the parent schema according to the rules of the applicator.¶
+
+ Evaluation of a parent schema object can complete once all of its
+ subschemas have been evaluated, although in some circumstances evaluation
+ may be short-circuited due to assertion results. When annotations are
+ being collected, some assertion result short-circuiting is not possible
+ due to the need to examine all subschemas for annotation collection, including
+ those that cannot further change the assertion result.¶
+ While most JSON Schema keywords can be evaluated on their own,
+ or at most need to take into account the values or results of
+ adjacent keywords in the same schema object, a few have more
+ complex behavior.¶
+
+ The lexical scope of a keyword is determined by the nested JSON
+ data structure of objects and arrays. The largest such scope
+ is an entire schema document. The smallest scope is a single
+ schema object with no subschemas.¶
+
+ Keywords MAY be defined with a partial value, such as a URI-reference,
+ which must be resolved against another value, such as another
+ URI-reference or a full URI, which is found through the lexical
+ structure of the JSON document. The "$id", "$ref", and
+ "$dynamicRef" core keywords, and the "base" JSON Hyper-Schema
+ keyword, are examples of this sort of behavior.¶
+
+ Note that some keywords, such as "$schema", apply to the lexical
+ scope of the entire schema resource, and therefore MUST only
+ appear in a schema resource's root schema.¶
+
+ Other keywords may take into account the dynamic scope that
+ exists during the evaluation of a schema, typically together
+ with an instance document.
+ The outermost dynamic scope is the schema object at
+ which processing begins, even if it is not a schema resource root.
+ The path from this root schema to any particular keyword (that
+ includes any "$ref" and "$dynamicRef" keywords that may have
+ been resolved) is considered the keyword's "validation path."¶
+
+ Lexical and dynamic scopes align until a reference keyword
+ is encountered. While following the reference keyword moves processing
+ from one lexical scope into a different one, from the perspective
+ of dynamic scope, following a reference is no different from descending
+ into a subschema present as a value. A keyword on the far side of
+ that reference that resolves information through the dynamic scope
+ will consider the originating side of the reference to be their
+ dynamic parent, rather than examining the local lexically enclosing parent.¶
+
+ The concept of dynamic scope is primarily used with "$dynamicRef" and
+ "$dynamicAnchor", and should be considered an advanced feature
+ and used with caution when defining additional keywords. It also appears
+ when reporting errors and collected annotations, as it may be possible
+ to revisit the same lexical scope repeatedly with different dynamic
+ scopes. In such cases, it is important to inform the user of the
+ dynamic path that produced the error or annotation.¶
+ Keyword behavior MAY be defined in terms of the annotation results
+ of subschemas (Section 4.3.5) and/or adjacent keywords
+ (keywords within the same schema object) and their subschemas.
+ Such keywords MUST NOT result in a circular dependency.
+ Keywords MAY modify their behavior based on the presence or absence
+ of another keyword in the same
+ schema object (Section 4.3).¶
+ A missing keyword MUST NOT produce a false assertion result, MUST
+ NOT produce annotation results, and MUST NOT cause any other schema
+ to be evaluated as part of its own behavioral definition.
+ However, given that missing keywords do not contribute annotations,
+ the lack of annotation results may indirectly change the behavior
+ of other keywords.¶
+
+ In some cases, the missing keyword assertion behavior of a keyword is
+ identical to that produced by a certain value, and keyword definitions
+ SHOULD note such values where known. However, even if the value which
+ produces the default behavior would produce annotation results if
+ present, the default behavior still MUST NOT result in annotations.¶
+
+ Because annotation collection can add significant cost in terms of both
+ computation and memory, implementations MAY opt out of this feature.
+ Keywords that are specified in terms of collected annotations SHOULD
+ describe reasonable alternate approaches when appropriate.
+ This approach is demonstrated by the
+ "items" and
+ "additionalProperties" keywords in this
+ document.¶
+
+ Note that when no such alternate approach is possible for a keyword,
+ implementations that do not support annotation collections will not
+ be able to support those keywords or vocabularies that contain them.¶
+ Identifiers define URIs for a schema, or affect how such URIs are
+ resolved in references (Section 8.2.3), or both.
+ The Core vocabulary defined in this document defines several
+ identifying keywords, most notably "$id".¶
+
+ Canonical schema URIs MUST NOT change while processing an instance, but
+ keywords that affect URI-reference resolution MAY have behavior that
+ is only fully determined at runtime.¶
+
+ While custom identifier keywords are possible, vocabulary designers should
+ take care not to disrupt the functioning of core keywords. For example,
+ the "$dynamicAnchor" keyword in this specification limits its URI resolution
+ effects to the matching "$dynamicRef" keyword, leaving the behavior
+ of "$ref" undisturbed.¶
+ Applicators allow for building more complex schemas than can be accomplished
+ with a single schema object. Evaluation of an instance against a
+ schema document (Section 4.3) begins by applying
+ the root schema (Section 4.3.5) to the complete instance
+ document. From there, keywords known as applicators are used to determine
+ which additional schemas are applied. Such schemas may be applied in-place
+ to the current location, or to a child location.¶
+
+ The schemas to be applied may be present as subschemas comprising all or
+ part of the keyword's value. Alternatively, an applicator may refer to
+ a schema elsewhere in the same schema document, or in a different one.
+ The mechanism for identifying such referenced schemas is defined by the
+ keyword.¶
+
+ Applicator keywords also define how subschema or referenced schema
+ boolean assertion (Section 7.6)
+ results are modified and/or combined to produce the boolean result
+ of the applicator. Applicators may apply any boolean logic operation
+ to the assertion results of subschemas, but MUST NOT introduce new
+ assertion conditions of their own.¶
+
+ Annotation (Section 7.7) results are
+ preserved along with the instance location and the location of
+ the schema keyword, so that applications can decide how to
+ interpret multiple values.¶
+ As noted in Section 7.5, 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 an instance against a schema.¶
+
+ For some by-reference applicators, such as
+ "$ref" (Section 8.2.3.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
+ the schema with an instance.¶
+ JSON Schema can be used to assert constraints on a JSON document, which
+ either passes or fails the assertions. This approach can be used to validate
+ conformance with the constraints, or document what is needed to satisfy them.¶
+
+ JSON Schema implementations produce a single boolean result when evaluating
+ an instance against schema assertions.¶
+
+ An instance can only fail an assertion that is present in the schema.¶
+ Most assertions only constrain values within a certain
+ primitive type. When the type of the instance is not of the type
+ targeted by the keyword, the instance is considered to conform
+ to the assertion.¶
+
+ For example, the "maxLength" keyword from the companion
+ validation vocabulary [json-schema-validation]:
+ will only restrict certain strings
+ (that are too long) from being valid. If the instance 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 instances
+ that can be of multiple primitive types. The companion validation
+ vocabulary also includes a "type" keyword which can independently
+ restrict the instance 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:¶
+ If "maxLength" also restricted the instance 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 instance to strings,
+ then including "null" in "type" would not have any useful effect.¶
+ JSON Schema can annotate an instance with information, whenever the instance
+ validates against the schema object containing the annotation, and all of its
+ parent schema objects. The information can be a simple value, or can be
+ calculated based on the instance contents.¶
+
+ Annotations are attached to specific locations in an instance.
+ Since many subschemas can be applied to any single
+ location, applications may need to decide how to handle differing
+ annotation values being attached to the same instance location by
+ the same schema keyword in different schema objects.¶
+
+ Unlike assertion results, annotation data can take a wide variety of forms,
+ which are provided to applications to use as they see fit. JSON Schema
+ implementations are not expected to make use of the collected information
+ on behalf of applications.¶
+
+ Unless otherwise specified, the value of an annotation keyword
+ is the keyword's value. However, other behaviors are possible.
+ For example, JSON Hyper-Schema's [json-hyper-schema]
+ "links" keyword is a complex annotation that produces a value based
+ in part on the instance data.¶
+
+ While "short-circuit" evaluation is possible for assertions, collecting
+ annotations requires examining all schemas that apply to an instance
+ location, even if they cannot change the overall assertion result.
+ The only exception is that subschemas of a schema object that has
+ failed validation MAY be skipped, as annotations are not retained
+ for failing schemas.¶
+ 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.¶
+
+ Applications MAY make decisions on which of multiple annotation values
+ to use based on the schema location that contributed the value.
+ This is intended to allow flexible usage. Collecting the schema location
+ facilitates such usage.¶
+ In this example, both Feature A and Feature B make use of the re-usable
+ "enabledToggle" schema. That schema uses the "title", "description",
+ and "default" annotations. Therefore the application has to decide how
+ to handle the additional "default" value for Feature A, and the additional
+ "description" value for Feature B.¶
+
+ The application programmer and the schema author need to agree on the
+ usage. For this example, let's assume that they agree that the most
+ specific "default" value will be used, and any additional, more generic
+ "default" values will be silently ignored. Let's also assume that they
+ agree that all "description" text is to be used, starting with the most
+ generic, and ending with the most specific. This requires the schema
+ author to write descriptions that work when combined in this way.¶
+
+ The application can use the schema location path to determine which
+ values are which. The values in the feature's immediate "enabled"
+ property schema are more specific, while the values under the re-usable
+ schema that is referenced to with "$ref" are more generic. The schema
+ location path will show whether each value was found by crossing a
+ "$ref" or not.¶
+
+ Feature A will therefore use a default value of true, while Feature B
+ will use the generic default value of null. Feature A will only
+ have the generic description from the "enabledToggle" schema, while
+ Feature B will use that description, and also append its locally
+ defined description that explains how to interpret a null value.¶
+
+ Note that there are other reasonable approaches that a different application
+ might take. For example, an application may consider the presence of
+ two different values for "default" to be an error, regardless of their
+ schema locations.¶
+ Schema objects that produce a false assertion result MUST NOT
+ produce any annotation results, whether from their own keywords
+ or from keywords in subschemas.¶
+
+ Note that the overall schema results may still include annotations
+ collected from other schema locations. Given this schema:¶
+ Against the instance "This is a string", the
+ title annotation "Integer Value" is discarded because the type assertion
+ in that schema object fails. The title annotation "String Value"
+ is kept, as the instance passes the string type assertions.¶
+ In addition to possibly defining annotation results of their own,
+ applicator keywords aggregate the annotations collected in their
+ subschema(s) or referenced schema(s).¶
+ A fourth category of keywords simply reserve a location to hold re-usable
+ components or data of interest to schema authors that is not suitable
+ for re-use. These keywords do not affect validation or annotation results.
+ Their purpose in the core vocabulary is to ensure that locations are
+ available for certain purposes and will not be redefined by extension
+ keywords.¶
+
+ While these keywords do not directly affect results, as explained in section
+ 9.4.2 unrecognized
+ extension keywords that reserve locations for re-usable schemas may have
+ undesirable interactions with references in certain circumstances.¶
+ While none of the vocabularies defined as part of this or the associated documents
+ define a keyword which may target and/or load instance data, it is possible that
+ other vocabularies may wish to do so.¶
+
+ Keywords MAY be defined to use JSON Pointers or Relative JSON Pointers to examine
+ parts of an instance outside the current evaluation location.¶
+
+ Keywords that allow adjusting the location using a Relative JSON Pointer SHOULD
+ default to using the current location if a default is desireable.¶
+ Keywords declared in this section, which all begin with "$", make up
+ the JSON Schema Core vocabulary. These keywords are either required in
+ order to process any schema or meta-schema, including those split across
+ multiple documents, or exist to reserve keywords for purposes that
+ require guaranteed interoperability.¶
+
+ The Core vocabulary MUST be considered mandatory at all times, in order
+ to bootstrap the processing of further vocabularies. Meta-schemas
+ that use the "$vocabulary" (Section 8.1) keyword
+ to declare the vocabularies in use MUST explicitly list the Core vocabulary,
+ which MUST have a value of true indicating that it is required.¶
+
+ The behavior of a false value for this vocabulary (and only this
+ vocabulary) is undefined, as is the behavior when "$vocabulary"
+ is present but the Core vocabulary is not included. However, it
+ is RECOMMENDED that implementations detect these cases and raise
+ an error when they occur. It is not meaningful to declare that
+ a meta-schema optionally uses Core.¶
+
+ Meta-schemas that do not use "$vocabulary" MUST be considered to
+ require the Core vocabulary as if its URI were present with a value of true.¶
+
+ The current URI for the Core vocabulary is:
+ <https://json-schema.org/draft/2020-12/vocab/core>.¶
+ While the "$" prefix is not formally reserved for the Core vocabulary,
+ it is RECOMMENDED that extension keywords (in vocabularies or otherwise)
+ begin with a character other than "$" to avoid possible future collisions.¶
+ Two concepts, meta-schemas and vocabularies, are used to inform an implementation
+ how to interpret a schema. Every schema has a meta-schema, which can be declared
+ using the "$schema" keyword.¶
+ The "$vocabulary" keyword, when it appears in a meta-schema, declares
+ which vocabularies are available to be used in schemas that refer
+ to that meta-schema. Vocabularies define keyword semantics,
+ as well as their general syntax.¶
+
+
+
Describing valid schema syntax
+
+ A schema MUST successfully validate against its meta-schema, which
+ constrains the syntax of the available keywords. The syntax described
+ is expected to be compatible with the vocabularies declared; while
+ it is possible to describe an incompatible syntax, such a meta-schema
+ would be unlikely to be useful.¶
+
+
+
+
+ Meta-schemas are separate from vocabularies to allow for
+ vocabularies to be combined in different ways, and for meta-schema authors
+ to impose additional constraints such as forbidding certain keywords, or
+ performing unusually strict syntactical validation, as might be done
+ during a development and testing cycle. Each vocabulary typically identifies
+ a meta-schema consisting only of the vocabulary's keywords.¶
+
+ Meta-schema authoring is an advanced usage of JSON Schema, so the design of
+ meta-schema features emphasizes flexibility over simplicity.¶
+ 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 URI [RFC3986]
+ (containing a scheme) 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.¶
+ 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 6.5, 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
+ document intended for use as a meta-schema. It MUST NOT appear in subschemas.¶
+
+ The "$vocabulary" keyword MUST be ignored in schema documents 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 validator to understand the vocabularies declared by M.¶
+ If "$vocabulary" is absent, an implementation MAY determine
+ behavior based on the meta-schema if it is recognized from the
+ URI value of the referring schema's "$schema" keyword.
+ This is how behavior (such as Hyper-Schema usage) has been
+ recognized prior to the existence of vocabularies.¶
+
+ If the meta-schema, as referenced by the schema, is not recognized,
+ or is missing, then the behavior is implementation-defined.
+ If the implementation
+ proceeds with processing the schema, it MUST assume the use of the
+ core vocabulary. If the implementation is built for a specific purpose,
+ then it SHOULD assume the use of all of the most relevant vocabularies
+ for that purpose.¶
+
+ For example, an implementation that is a validator
+ SHOULD assume the use of all vocabularies in this
+ specification and the companion Validation specification.¶
+ Note that the processing restrictions on "$vocabulary" mean that
+ meta-schemas that reference other meta-schemas using "$ref" or
+ similar keywords do not automatically inherit the vocabulary
+ declarations of those other meta-schemas. All such declarations
+ must be repeated in the root of each schema document intended
+ for use as a meta-schema. This is demonstrated in
+ the example meta-schema (Appendix D.2).
+
+ This requirement allows implementations to find all vocabulary
+ requirement information in a single place for each meta-schema.
+ As schema extensibility means that there are endless potential
+ ways to combine more fine-grained meta-schemas by reference,
+ requiring implementations to anticipate all possibilities and
+ search for vocabularies in referenced meta-schemas would
+ be overly burdensome.
+ ¶
+ Updated vocabulary and meta-schema URIs MAY be published between
+ specification drafts in order to correct errors. Implementations
+ SHOULD consider URIs dated after this specification draft and
+ before the next to indicate the same syntax and semantics
+ as those listed here.¶
+ To differentiate between schemas in a vast ecosystem, schemas are
+ identified by URI [RFC3986], and can embed references
+ to other schemas by specifying their URI.¶
+
+ Several keywords can accept a relative URI-reference [RFC3986],
+ or a value used to construct a relative URI-reference. For these keywords,
+ it is necessary to establish a base URI in order to resolve the reference.¶
+ The "$id" keyword identifies a schema resource with its
+ canonical [RFC6596] URI.¶
+
+ Note that this URI is an identifier and not necessarily a network locator.
+ In the case of a network-addressable URL, a schema need not be downloadable
+ from its canonical URI.¶
+
+ If present, the value for this keyword MUST be a string, and MUST represent a
+ valid URI-reference [RFC3986]. This URI-reference
+ SHOULD be normalized, and MUST resolve to an
+ absolute-URI [RFC3986] (without a fragment),
+ or to a URI with an empty fragment.¶
+
+ The empty fragment form is NOT RECOMMENDED and is retained only
+ for backwards compatibility, and because the
+ application/schema+json media type defines that a URI with an
+ empty fragment identifies the same resource as the same URI
+ with the fragment removed. However, since this equivalence is not
+ part of the RFC 3986 normalization process [RFC3986],
+ implementers and schema authors cannot rely on generic URI libraries
+ understanding it.¶
+
+ Therefore, "$id" MUST NOT contain a non-empty fragment, and SHOULD NOT
+ contain an empty fragment. The absolute-URI form MUST be considered
+ the canonical URI, regardless of the presence or absence of an empty fragment.
+
+ An empty fragment is currently allowed because older meta-schemas have
+ an empty fragment in their $id (or previously, id).
+ A future draft may outright forbid even empty fragments in "$id".
+ ¶
+
+ The absolute-URI also serves as the base URI for relative URI-references
+ in keywords within the schema resource, in accordance with
+ RFC 3986 section 5.1.1 [RFC3986] regarding base URIs
+ embedded in content.¶
+
+ The presence of "$id" in a subschema indicates that the subschema constitutes
+ a distinct schema resource within a single schema document. Furthermore,
+ in accordance with RFC 3986 section 5.1.2 [RFC3986]
+ regarding encapsulating entities, if an "$id" in a subschema is a relative
+ URI-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 the previous section. (Section 9.1.1)¶
+ The root schema of a JSON Schema document SHOULD contain an "$id" keyword
+ with an absolute-URI [RFC3986] (containing a scheme,
+ but no fragment).¶
+ 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, rather than absolute URIs as seen with "$id".¶
+
+ 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 8.2.3.2)
+ 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 [xml-names].
+
+ 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.¶
+ Several keywords can be used to reference a schema which is to be applied to the
+ current instance location. "$ref" and "$dynamicRef" are applicator
+ keywords, applying the referenced schema to the instance.¶
+
+ 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. A schema need not be downloadable from the
+ address if it is a network-addressable URL, and implementations SHOULD NOT
+ assume they should perform a network operation when they encounter
+ a network-addressable URI.¶
+ The "$ref" keyword is an applicator that is used to reference a statically
+ identified schema. Its 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.
+ ¶
+
+ 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 instance 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 instance.¶
+
+ 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 7.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.
+ ¶
+ 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":¶
+ This keyword reserves a location for comments from schema authors
+ to readers or maintainers of the schema.¶
+
+ The value of this keyword MUST be a string. Implementations MUST NOT present this
+ string to end users. Tools for editing schemas SHOULD support displaying and
+ editing this keyword. The value of this keyword MAY be used in debug or error
+ output which is intended for developers making use of schemas.¶
+
+ Schema vocabularies SHOULD allow "$comment" within any object containing
+ vocabulary keywords. Implementations MAY assume "$comment" is allowed
+ unless the vocabulary specifically forbids it. Vocabularies MUST NOT
+ specify any effect of "$comment" beyond what is described in this
+ specification.¶
+
+ Tools that translate other media types or programming languages
+ to and from application/schema+json MAY choose to convert that media type or
+ programming language's native comments to or from "$comment" values.
+ The behavior of such translation when both native comments and "$comment"
+ properties are present is implementation-dependent.¶
+
+ Implementations MAY strip "$comment" values at any point during processing.
+ In particular, this allows for shortening schemas when the size of deployed
+ schemas is a concern.¶
+
+ Implementations MUST NOT take any other action based on the presence, absence,
+ or contents of "$comment" properties. In particular, the value of "$comment"
+ MUST NOT be collected as an annotation result.¶
+ 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
+ RFC 3986 section 5 [RFC3986].¶
+
+ 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
+ RFC 3986 Section 5.1.4 [RFC3986]. 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.¶
+ The use of URIs to identify remote schemas does not necessarily mean anything is downloaded,
+ but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using,
+ and the URIs that identify them.¶
+
+ 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 9.5.1).¶
+
+ 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 validator 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, validators SHOULD raise an error condition.¶
+ 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.¶
+ Schemas can be identified by any URI that has been given to them, including
+ a JSON Pointer or their URI given directly by "$id". In all cases,
+ dereferencing a "$ref" reference involves first resolving its value as a
+ URI reference against the current base URI per
+ RFC 3986 [RFC3986].¶
+
+ If the resulting URI identifies a schema within the current document, or
+ within another schema document that has been made available to the implementation,
+ then that schema SHOULD be used automatically.¶
+ When an implementation encounters the <#/$defs/single> schema,
+ it resolves the "$anchor" value as a fragment name against the current
+ base URI to form <https://example.net/root.json#item>.¶
+
+ When an implementation then looks inside the <#/items> schema, it
+ encounters the <#item> reference, and resolves this to
+ <https://example.net/root.json#item>, which it has seen defined in
+ this same document and can therefore use automatically.¶
+
+ When an implementation encounters the reference to "other.json", it resolves
+ this to <https://example.net/other.json>, which is not defined in this
+ document. If a schema with that identifier has otherwise been supplied to
+ the implementation, it can also be used automatically.
+
+ What should implementations do when the referenced schema is not known?
+ Are there circumstances in which automatic network dereferencing is
+ allowed? A same origin policy? A user-configurable option? In the
+ case of an evolving API described by Hyper-Schema, it is expected that
+ new schemas will be added to the system dynamically, so placing an
+ absolute requirement of pre-loading schema documents is not feasible.
+ ¶
+ Since JSON Pointer URI fragments are constructed based on the structure
+ of the schema document, an embedded schema resource and its subschemas
+ can 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 8.2.3), 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:¶
+ 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":¶
+ 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.¶
+ A Compound Schema Document is defined as a JSON document (sometimes called a "bundled" schema)
+ which has multiple embedded JSON Schema Resources bundled into the same document to
+ ease transportation.¶
+
+ Each embedded Schema Resource MUST be treated as an individual Schema Resource, following standard
+ schema loading and processing requirements, including determining vocabulary support.¶
+ 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.¶
+ 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.¶
+ 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.¶
+ A schema MUST NOT be run into an infinite loop against an instance. For
+ example, if two schemas "#alice" and "#bob" both have an "allOf" property
+ that refers to the other, a naive validator might get stuck in an infinite
+ recursive loop trying to validate the instance. Schemas SHOULD NOT make
+ use of infinite recursive nesting like this; the behavior is undefined.¶
+ Subschema objects (or booleans) are recognized by their use with known
+ applicator keywords or with location-reserving keywords such as
+ "$defs" (Section 8.2.4) 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
+ implementation-specific and MUST NOT be relied upon for interoperability.¶
+ JSON has been adopted widely by HTTP servers for automated APIs and robots. This
+ section describes how to enhance processing of JSON documents in a more RESTful
+ manner when used with protocols that support media types and
+ Web linking [RFC8288].¶
+ When used for hypermedia systems over a network,
+ HTTP [RFC7231] 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:¶
+ These keywords apply subschemas to the same location in the instance
+ as the parent schema is being applied. They allow combining
+ or modifying the subschema results in various ways.¶
+
+ Subschemas of these keywords evaluate the instance completely independently
+ such that the results of one such subschema MUST NOT impact the results of sibling
+ subschemas. Therefore subschemas may be applied in
+ any order.¶
+ These keywords correspond to logical operators for combining or modifying
+ the boolean assertion results of the subschemas. They have no direct
+ impact on annotation collection, although they enable the same annotation
+ keyword to be applied to an instance location with different values.
+ Annotation keywords define their own rules for combining such values.¶
+ This keyword's value MUST be a non-empty array.
+ Each item of the array MUST be a valid JSON Schema.¶
+
+ An instance 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.¶
+ Three of these keywords work together to implement conditional
+ application of a subschema based on the outcome of another subschema.
+ The fourth is a shortcut for a specific conditional case.¶
+
+ "if", "then", and "else" MUST NOT interact with each other across
+ subschema boundaries. In other words, an "if" in one
+ branch of an "allOf" MUST NOT have an impact on a "then"
+ or "else" in another branch.¶
+
+ There is no default behavior for "if", "then", or "else"
+ when they are not present. In particular, they MUST NOT
+ be treated as if present with an empty schema, and when
+ "if" is not present, both "then" and "else" MUST be
+ entirely ignored.¶
+ 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.¶
+
+ Instances that successfully validate against this
+ keyword's subschema MUST also be valid against
+ the subschema value of the "then" keyword, if
+ present.¶
+
+ Instances that fail to validate against this
+ keyword's subschema MUST also be valid against
+ the subschema value of the "else" keyword, if
+ present.¶
+
+ If annotations (Section 7.7)
+ 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".¶
+ This keyword's value MUST be a valid JSON Schema.¶
+
+ When "if" is present, and the instance successfully
+ validates against its subschema, then validation
+ succeeds against this keyword if the instance also
+ successfully validates against this keyword's subschema.¶
+
+ This keyword has no effect when "if" is absent, or
+ when the instance fails to validate against its
+ subschema. Implementations MUST NOT evaluate
+ the instance against this keyword, for either validation
+ or annotation collection purposes, in such cases.¶
+ This keyword's value MUST be a valid JSON Schema.¶
+
+ When "if" is present, and the instance fails to
+ validate against its subschema, then validation
+ succeeds against this keyword if the instance
+ successfully validates against this keyword's subschema.¶
+
+ This keyword has no effect when "if" is absent, or
+ when the instance successfully validates against its
+ subschema. Implementations MUST NOT evaluate
+ the instance against this keyword, for either validation
+ or annotation collection purposes, in such cases.¶
+ This keyword specifies subschemas that are evaluated if the instance
+ 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.¶
+ Each of these keywords defines a rule for applying its
+ subschema(s) to child instances, specifically object
+ properties and array items, and combining their results.¶
+ The value of "prefixItems" MUST be a non-empty array of valid JSON Schemas.¶
+
+ Validation succeeds if each element of the instance 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.¶
+ The value of "items" MUST be a valid JSON Schema.¶
+
+ This keyword applies its subschema to all instance 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 instance
+ 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 instance 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.¶
+ The value of this keyword MUST be a valid JSON Schema.¶
+
+ An array instance is valid against "contains" if at least one of
+ its elements is valid against the given schema,
+ except when "minContains" is present and has a value of 0, in which
+ case an array instance MUST be considered valid against the "contains" keyword,
+ even if none of its elements is valid against the given schema.¶
+
+ 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 instance array to which
+ this keyword's schema applies is empty.¶
+
+ This annotation affects the behavior of "unevaluatedItems" in the
+ Unevaluated vocabulary, and MAY also be used to implement the
+ "minContains" and "maxContains" keywords in the Validation 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.¶
+ 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 instance and as a name within this keyword's value, the child
+ instance for that name successfully validates 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.¶
+ 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 instance name that matches any
+ regular expressions that appear as a property name in this keyword's value,
+ the child instance for that name successfully validates against each
+ schema that corresponds to a matching regular expression.¶
+
+ 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.¶
+ 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 instance names that do not appear in the annotation
+ results of either "properties" or "patternProperties".¶
+
+ For all such properties, validation succeeds if the child instance
+ validates against the "additionalProperties" schema.¶
+
+ The annotation result of this keyword is the set of instance
+ 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 instance 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](https://github.com/json-schema-org/json-schema-spec/tree/HEAD/adr/2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md)
+ for further details.
+ ¶
+ The value of "propertyNames" MUST be a valid JSON Schema.¶
+
+ If the instance is an object, this keyword validates if every property name in
+ the instance 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.¶
+ The purpose of these keywords is to enable schema authors to apply
+ subschemas to array items or object properties that have not been
+ successfully evaluated against any dynamic-scope subschema of any
+ adjacent keywords.¶
+
+ These instance items or properties may have been unsuccessfully evaluated
+ against one or more adjacent keyword subschemas, such as when an assertion
+ in a branch of an "anyOf" fails. Such failed evaluations are not considered
+ to contribute to whether or not the item or property has been evaluated.
+ Only successful evaluations are considered.¶
+
+ If an item in an array or an object property is "successfully evaluated", it
+ is logically considered to be valid in terms of the representation of the
+ object or array that's expected. For example if a subschema represents a car,
+ which requires between 2-4 wheels, and the value of "wheels" is 6, the instance
+ object is not "evaluated" to be a car, and the "wheels" property is considered
+ "unevaluated (successfully as a known thing)", and does not retain any annotations.¶
+
+ Recall that adjacent keywords are keywords within the same schema object,
+ and that the dynamic-scope subschemas include reference targets as well as
+ lexical subschemas.¶
+
+ The behavior of these keywords depend on the annotation results of
+ adjacent keywords that apply to the instance location being validated.¶
+
+ Meta-schemas that do not use "$vocabulary" SHOULD be considered to
+ require this vocabulary as if its URI were present with a value of true.¶
+
+ The current URI for this vocabulary, known as the Unevaluated Applicator
+ vocabulary, is:
+ <https://json-schema.org/draft/2020-12/vocab/unevaluated>.¶
+ Schema keywords typically operate independently, without
+ affecting each other's outcomes. However, the keywords in this
+ vocabulary are notable exceptions:¶
+
+
+ "unevaluatedItems", whose behavior is defined in terms of annotations
+ from "prefixItems", "items", "contains", and itself¶
+
+
+ "unevaluatedProperties", whose behavior is defined in terms of
+ annotations from "properties", "patternProperties",
+ "additionalProperties" and itself¶
+
+ The value of "unevaluatedItems" MUST be a valid JSON Schema.¶
+
+ The behavior of this keyword depends on the annotation results of
+ adjacent keywords that apply to the instance location being validated.
+ Specifically, the annotations from "prefixItems", "items", and "contains",
+ which can come from those keywords when they are adjacent to the
+ "unevaluatedItems" keyword. Those three annotations, as well as
+ "unevaluatedItems", can also result from any and all adjacent
+ in-place applicator (Section 10.2) keywords.
+ This includes but is not limited to the in-place applicators
+ defined in this document.¶
+
+ If no relevant annotations are present, the "unevaluatedItems"
+ subschema MUST be applied to all locations in the array.
+ If a boolean true value is present from any of the relevant annotations,
+ "unevaluatedItems" MUST be ignored. Otherwise, the subschema
+ MUST be applied to any index greater than the largest annotation
+ value for "prefixItems", which does not appear in any annotation
+ value for "contains".¶
+
+ This means that "prefixItems", "items", "contains", and all in-place
+ applicators MUST be evaluated before this keyword can be evaluated.
+ Authors of extension keywords MUST NOT define an in-place applicator
+ that would need to be evaluated after this keyword.¶
+
+ If the "unevaluatedItems" subschema is applied to any
+ positions within the instance array, it produces an
+ annotation result of boolean true, analogous to the
+ behavior of "items".
+ This annotation affects the behavior of "unevaluatedItems" in parent schemas.¶
+
+ Omitting this keyword has the same assertion behavior as
+ an empty schema.¶
+ The value of "unevaluatedProperties" MUST be a valid JSON Schema.¶
+
+ The behavior of this keyword depends on the annotation results of
+ adjacent keywords that apply to the instance location being validated.
+ Specifically, the annotations from "properties", "patternProperties",
+ and "additionalProperties", which can come from those keywords when
+ they are adjacent to the "unevaluatedProperties" keyword. Those
+ three annotations, as well as "unevaluatedProperties", can also
+ result from any and all adjacent
+ in-place applicator (Section 10.2) keywords.
+ This includes but is not limited to the in-place applicators
+ defined in this document.¶
+
+ Validation with "unevaluatedProperties" applies only to the child
+ values of instance names that do not appear in the "properties",
+ "patternProperties", "additionalProperties", or
+ "unevaluatedProperties" annotation results that apply to the
+ instance location being validated.¶
+
+ For all such properties, validation succeeds if the child instance
+ validates against the "unevaluatedProperties" schema.¶
+
+ This means that "properties", "patternProperties", "additionalProperties",
+ and all in-place applicators MUST be evaluated before this keyword can
+ be evaluated. Authors of extension keywords MUST NOT define an in-place
+ applicator that would need to be evaluated after this keyword.¶
+
+ The annotation result of this keyword is the set of instance
+ property names validated by this keyword's subschema.
+ This annotation affects the behavior of "unevaluatedProperties" in parent schemas.¶
+
+ Omitting this keyword has the same assertion behavior as
+ an empty schema.¶
+ JSON Schema is defined to be platform-independent. As such, to increase compatibility
+ across platforms, implementations SHOULD conform to a standard validation output
+ format. This section describes the minimum requirements that consumers will need to
+ properly interpret validation results.¶
+ JSON Schema output is defined using the JSON Schema data instance model as described
+ in section 4.2.1. Implementations MAY deviate from this as supported by their
+ specific languages and platforms, however it is RECOMMENDED that the output be
+ convertible to the JSON format defined herein via serialization or other means.¶
+ This specification defines four output formats. See the "Output Structure"
+ section for the requirements of each format.¶
+
+
+ Flag - A boolean which simply indicates the overall validation result
+ with no further details.¶
+
+
+ Basic - Provides validation information in a flat list structure.¶
+
+
+ Detailed - Provides validation information in a condensed hierarchical
+ structure based on the structure of the schema.¶
+
+
+ Verbose - Provides validation information in an uncondensed hierarchical
+ structure that matches the exact structure of the schema.¶
+
+
+
+ An implementation SHOULD provide at least one of the "flag", "basic", or "detailed"
+ format and MAY provide the "verbose" format. If it provides one or more of the
+ "detailed" or "verbose" formats, it MUST also provide the "flag" format.
+ Implementations SHOULD specify in their documentation which formats they support.¶
+ Beyond the simplistic "flag" output, additional information is useful to aid in
+ debugging a schema or instance. Each sub-result SHOULD contain the information
+ contained within this section at a minimum.¶
+
+ A single object that contains all of these components is considered an
+ output unit.¶
+
+ Implementations MAY elect to provide additional information.¶
+ 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".¶
+ 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.
+ ¶
+ 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".¶
+ 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.¶
+ The output MUST be an object containing a boolean property named "valid". When
+ additional information about the result is required, the output MUST also contain
+ "errors" or "annotations" as described below.¶
+
+
+ "valid" - a boolean value indicating the overall validation success or
+ failure¶
+
+
+ "errors" - the collection of errors or annotations produced by a failed
+ validation¶
+
+
+ "annotations" - the collection of errors or annotations produced by a
+ successful validation¶
+
+
+
+ For these examples, the following schema and instance will be used.¶
+ The second object has a disallowed "z" property.¶
+
+
+ There are only two objects, but three are required.¶
+
+
+
+ Note that the error message wording as depicted in these examples is not a
+ requirement of this specification. Implementations SHOULD craft error messages
+ tailored for their audience or provide a templating mechanism that allows their
+ users to craft their own messages.¶
+ 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.¶
+ 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.¶
+
+ 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.¶
+ Both schemas and instances are JSON values. As such, all security considerations
+ defined in RFC 8259 [RFC8259] apply.¶
+
+ Instances and schemas are both frequently written by untrusted third parties, to be
+ deployed on public Internet servers.
+ Validators should take care that the parsing and validating against schemas does not consume excessive
+ system resources.
+ Validators MUST NOT fall into an infinite loop.¶
+
+ A malicious party could cause an implementation to repeatedly collect a copy
+ of a very large value as an annotation. Implementations SHOULD guard against
+ excessive consumption of system resources in such a scenario.¶
+
+ Servers MUST ensure that malicious parties cannot change the functionality of
+ existing schemas by uploading a schema with a pre-existing or very similar "$id".¶
+
+ Individual JSON Schema vocabularies are liable to also have their own security
+ considerations. Consult the respective specifications for more information.¶
+
+ Schema authors should take care with "$comment" contents, as a malicious
+ implementation can display them to end-users in violation of a spec, or
+ fail to strip them if such behavior is expected.¶
+
+ A malicious schema author could place executable code or other dangerous
+ material within a "$comment". Implementations MUST NOT parse or otherwise
+ take action based on "$comment" contents.¶
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
+
+
[RFC3986]
+
+Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/info/rfc3986>.
+
+
[RFC6839]
+
+Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", RFC 6839, DOI 10.17487/RFC6839, , <https://www.rfc-editor.org/info/rfc6839>.
+
+
[RFC6901]
+
+Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, , <https://www.rfc-editor.org/info/rfc6901>.
+
+
[RFC8259]
+
+Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/info/rfc8259>.
+
+
[W3C.REC-ldp-20150226]
+
+Speicher, S., Arwe, J., and A. Malhotra, "Linked Data Platform 1.0", World Wide Web Consortium Recommendation REC-ldp-20150226, , <https://www.w3.org/TR/2015/REC-ldp-20150226>.
+Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, , <https://www.rfc-editor.org/info/rfc7231>.
+ Consider the following schema, which shows "$id" being used to identify
+ both the root schema and various subschemas, and "$anchor" being used
+ to define plain name fragment identifiers.¶
+ The schemas at the following URI-encoded JSON
+ Pointers [RFC6901] (relative to the root schema) have the following
+ base URIs, and are identifiable by any listed URI in accordance with
+ sections 5 and
+ 9.2.1 above.¶
+ Note: The fragment part of the URI does not make it canonical or non-canonical,
+ rather, the base URI used (as part of the full URI with any fragment) is what
+ determines the canonical nature of the resulting full URI.
+
+ Multiple "canonical" URIs? We Acknowledge this is potentially confusing, and
+ direct you to read the CREF located in the
+ JSON Pointer fragments and embedded schema resources (Section 9.2.1)
+ section for futher comments.
+ ¶
+ Various tools have been created to rearrange schema documents
+ based on how and where references ("$ref") appear. This appendix discusses
+ which use cases and actions are compliant with this specification.¶
+ A set of schema resources intended for use together can be organized
+ with each in its own schema document, all in the same schema document,
+ or any granularity of document grouping in between.¶
+
+ Numerous tools exist to perform various sorts of reference removal.
+ A common case of this is producing a single file where all references
+ can be resolved within that file. This is typically done to simplify
+ distribution, or to simplify coding so that various invocations
+ of JSON Schema libraries do not have to keep track of and load
+ a large number of resources.¶
+
+ This transformation can be safely and reversibly done as long as
+ all static references (e.g. "$ref") use URI-references that resolve
+ to URIs using the canonical resource URI as the base, and all schema
+ resources have an absolute-URI as the "$id" in their root schema.¶
+
+ With these conditions met, each external resource can be copied
+ under "$defs", without breaking any references among the resources'
+ schema objects, and without changing any aspect of validation or
+ annotation results. The names of the schemas under "$defs" do
+ not affect behavior, assuming they are each unique, as they
+ do not appear in the canonical URIs for the embedded resources.¶
+ Attempting to remove all references and produce a single schema document does not,
+ in all cases, produce a schema with identical behavior to the original form.¶
+
+ Since "$ref" is now treated like any other keyword, with other keywords allowed
+ in the same schema objects, fully supporting non-recursive "$ref" removal in
+ all cases can require relatively complex schema manipulations. It is beyond
+ the scope of this specification to determine or provide a set of safe "$ref"
+ removal transformations, as they depend not only on the schema structure
+ but also on the intended usage.¶
+ Consider the following two schemas describing a simple
+ recursive tree structure, where each node in the tree
+ can have a "data" field of any type. The first schema
+ allows and ignores other instance properties. The second is
+ more strict and only allows the "data" and "children" properties.
+ An example instance with "data" misspelled as "daat" is also shown.¶
+ When we load these two schemas, we will notice the "$dynamicAnchor"
+ named "node" (note the lack of "#" as this is just the name)
+ present in each, resulting in the following full schema URIs:¶
+ In addition, JSON Schema implementations keep track of the fact
+ that these fragments were created with "$dynamicAnchor".¶
+
+ If we apply the "strict-tree" schema to the instance, we will follow
+ the "$ref" to the "tree" schema, examine its "children" subschema,
+ and find the "$dynamicRef": to "#node" (note the "#" for URI fragment syntax)
+ in its "items" subschema. That reference resolves to
+ "https://example.com/tree#node", which is a URI with a fragment
+ created by "$dynamicAnchor". Therefore we must examine the dynamic
+ scope before following the reference.¶
+
+ At this point, the dynamic path is
+ "#/$ref/properties/children/items/$dynamicRef", with a dynamic scope
+ containing (from the outermost scope to the innermost):¶
+ Since we are looking for a plain name fragment, which can be
+ defined anywhere within a schema resource, the JSON Pointer fragments
+ are irrelevant to this check. That means that we can remove those
+ fragments and eliminate consecutive duplicates, producing:¶
+ In this case, the outermost resource also has a "node" fragment
+ defined by "$dynamicAnchor". Therefore instead of resolving the
+ "$dynamicRef" to "https://example.com/tree#node", we resolve it to
+ "https://example.com/strict-tree#node".¶
+
+ This way, the recursion in the "tree" schema recurses to the root
+ of "strict-tree", instead of only applying "strict-tree" to the
+ instance root, but applying "tree" to instance children.¶
+
+ This example shows both "$dynamicAnchor"s in the same place
+ in each schema, specifically the resource root schema.
+ Since plain-name fragments are independent of the JSON structure,
+ this would work just as well if one or both of the node schema objects
+ were moved under "$defs". It is the matching "$dynamicAnchor" values
+ which tell us how to resolve the dynamic reference, not any sort of
+ correlation in JSON structure.¶
+ Vocabulary authors should
+ take care to avoid keyword name collisions if the vocabulary is intended
+ for broad use, and potentially combined with other vocabularies. JSON
+ Schema does not provide any formal namespacing system, but also does
+ not constrain keyword names, allowing for any number of namespacing
+ approaches.¶
+
+ Vocabularies may build on each other, such as by defining the behavior
+ of their keywords with respect to the behavior of keywords from another
+ vocabulary, or by using a keyword from another vocabulary with
+ a restricted or expanded set of acceptable values. Not all such
+ vocabulary re-use will result in a new vocabulary that is compatible
+ with the vocabulary on which it is built. Vocabulary authors should
+ clearly document what level of compatibility, if any, is expected.¶
+
+ Meta-schema authors should not use "$vocabulary" to combine multiple
+ vocabularies that define conflicting syntax or semantics for the same
+ keyword. As semantic conflicts are not generally detectable through
+ schema validation, implementations are not expected to detect such
+ conflicts. If conflicting vocabularies are declared, the resulting
+ behavior is undefined.¶
+
+ Vocabulary authors SHOULD provide a meta-schema that validates the
+ expected usage of the vocabulary's keywords on their own. Such meta-schemas
+ SHOULD not forbid additional keywords, and MUST not forbid any
+ keywords from the Core vocabulary.¶
+
+ It is recommended that meta-schema authors reference each vocabulary's
+ meta-schema using the "allOf" (Section 10.2.1.1) keyword,
+ although other mechanisms for constructing the meta-schema may be
+ appropriate for certain use cases.¶
+
+ The recursive nature of meta-schemas makes the "$dynamicAnchor"
+ and "$dynamicRef" keywords particularly useful for extending
+ existing meta-schemas, as can be seen in the JSON Hyper-Schema meta-schema
+ which extends the Validation meta-schema.¶
+
+ Meta-schemas may impose additional constraints, including describing
+ keywords not present in any vocabulary, beyond what the meta-schemas
+ associated with the declared vocabularies describe. This allows for
+ restricting usage to a subset of a vocabulary, and for validating
+ locally defined keywords not intended for re-use.¶
+
+ However, meta-schemas should not contradict any vocabularies that
+ they declare, such as by requiring a different JSON type than
+ the vocabulary expects. The resulting behavior is undefined.¶
+
+ Meta-schemas intended for local use, with no need to test for
+ vocabulary support in arbitrary implementations, can safely omit
+ "$vocabulary" entirely.¶
+ This meta-schema explicitly declares both the Core and Applicator vocabularies,
+ together with an extension vocabulary, and combines their meta-schemas with
+ an "allOf". The extension vocabulary's meta-schema, which describes only the
+ keywords in that vocabulary, is shown after the main example meta-schema.¶
+
+ The main example meta-schema also restricts the usage of the Unevaluated
+ vocabulary by forbidding the keywords prefixed with "unevaluated", which
+ are particularly complex to implement. This does not change the semantics
+ or set of keywords defined by the other vocabularies. It just ensures
+ that schemas using this meta-schema that attempt to use the keywords
+ prefixed with "unevaluated" will fail validation against this meta-schema.¶
+
+ Finally, this meta-schema describes the syntax of a keyword, "localKeyword",
+ that is not part of any vocabulary. Presumably, the implementors and users
+ of this meta-schema will understand the semantics of "localKeyword".
+ JSON Schema does not define any mechanism for expressing keyword semantics
+ outside of vocabularies, making them unsuitable for use except in a
+ specific environment in which they are understood.¶
+
+ This meta-schema combines several vocabularies for general use.¶
+ As shown above, even though each of the single-vocabulary meta-schemas
+ referenced in the general-use meta-schema's "allOf" declares its
+ corresponding vocabulary, this new meta-schema must re-declare them.¶
+
+ The standard meta-schemas that combine all vocabularies defined by
+ the Core and Validation specification, and that combine all vocabularies
+ defined by those specifications as well as the Hyper-Schema specification,
+ demonstrate additional complex combinations. These URIs for these
+ meta-schemas may be found in the Validation and Hyper-Schema specifications,
+ respectively.¶
+
+ While the general-use meta-schema can validate the syntax of "minDate",
+ it is the vocabulary that defines the logic behind the semantic meaning
+ of "minDate". Without an understanding of the semantics (in this example,
+ that the instance value must be a date equal to or after the date
+ provided as the keyword's value in the schema), an implementation can
+ only validate the syntactic usage. In this case, that means validating
+ that it is a date-formatted string (using "pattern" to ensure that it is
+ validated even when "format" functions purely as an annotation, as explained
+ in the Validation specification [json-schema-validation].¶
+ While the presence of references is expected to be transparent
+ to validation results, generative use cases such as code generators
+ and UI renderers often consider references to be semantically significant.¶
+
+ To make such use case-specific semantics explicit, the best practice
+ is to create an annotation keyword for use in the same
+ schema object alongside of a reference keyword such as "$ref".¶
+
+ For example, here is a hypothetical keyword for determining
+ whether a code generator should consider the reference
+ target to be a distinct class, and how those classes are related.
+ Note that this example is solely for illustrative purposes, and is
+ not intended to propose a functional code generation keyword.¶
+ Here, this schema represents some sort of object-oriented class.
+ The first reference in the "allOf" is noted as the base class.
+ The second is not assigned a class relationship, meaning that the
+ code generator should combine the target's definition with this
+ one as if no reference were involved.¶
+
+ Looking at the properties, "foo" is flagged as object composition,
+ while the "date" property is not. It is simply a field with
+ sub-fields, rather than an instance of a distinct class.¶
+
+ This style of usage requires the annotation to be in the same object
+ as the reference, which must be recognizable as a reference.¶
+ Thanks to
+ Gary Court,
+ Francis Galiegue,
+ Kris Zyp,
+ and Geraint Luff
+ for their work on the initial drafts of JSON Schema.¶
+
+ Thanks to
+ Jason Desrosiers,
+ Daniel Perrett,
+ Erik Wilde,
+ Evgeny Poberezkin,
+ Brad Bowman,
+ Gowry Sankar,
+ Donald Pipowitch,
+ Dave Finlay,
+ Denis Laxalde,
+ Phil Sturgeon,
+ Shawn Silverman,
+ and Karen Etheridge
+ for their submissions and patches to the document.¶
+ JSON Schema (application/schema+json) has several purposes, one of which is JSON
+ instance validation.
+ This document specifies a vocabulary for JSON Schema to describe the meaning of JSON
+ documents, provide hints for user interfaces working with JSON data, and to make
+ assertions about what a valid document must look like.¶
+ This Internet-Draft is submitted in full conformance with the
+ provisions of BCP 78 and BCP 79.¶
+
+ Internet-Drafts are working documents of the Internet Engineering Task
+ Force (IETF). Note that other groups may also distribute working
+ documents as Internet-Drafts. The list of current Internet-Drafts is
+ at https://datatracker.ietf.org/drafts/current/.¶
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."¶
+
+ This Internet-Draft will expire on 30 October 2022.¶
+ Copyright (c) 2022 IETF Trust and the persons identified as the
+ document authors. All rights reserved.¶
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (https://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with
+ respect to this document. Code Components extracted from this
+ document must include Revised BSD License text as described in
+ Section 4.e of the Trust Legal Provisions and are provided without
+ warranty as described in the Revised BSD License.¶
+ JSON Schema can be used to require that a given JSON document (an instance)
+ satisfies a certain number of criteria. These criteria are asserted by using
+ keywords described in this specification. In addition, a set of keywords
+ is also defined to assist in interactive user interface instance generation.¶
+
+ This specification will use the concepts, syntax, and terminology defined
+ by the JSON Schema core [json-schema] specification.¶
+
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+ "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+ interpreted as described in RFC 2119 [RFC2119].¶
+
+ This specification uses the term "container instance" to refer to both array and
+ object instances. It uses the term "children instances" to refer to array elements
+ or object member values.¶
+
+ Elements in an array value are said to be unique if no two elements of this array
+ are equal [json-schema].¶
+ JSON Schema validation asserts constraints on the structure of instance data.
+ 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. If all locations within
+ the instance satisfy all asserted constraints, then the instance is
+ said to be valid against the schema.¶
+
+ Each schema object is independently evaluated against each instance location
+ to which it applies. This greatly simplifies the implementation requirements
+ for validators by ensuring that they 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 7 keyword is intended primarily
+ as an annotation, but can optionally be used as an assertion. The
+ Section 8 keywords are annotations for working with documents
+ embedded as JSON strings.¶
+ It should be noted that the nul character (\u0000) is valid in a JSON string. An
+ instance to validate may contain a string value with this character, regardless
+ of the ability of the underlying programming language to deal with such data.¶
+ The JSON specification allows numbers with arbitrary precision, and JSON Schema
+ does not add any such bounds.
+ This means that numeric instances processed by JSON Schema can be arbitrarily large and/or
+ have an arbitrarily long decimal part, regardless of the ability of the
+ underlying programming language to deal with such data.¶
+ Keywords that use regular expressions, or constrain the instance value
+ to be a regular expression, are subject to the interoperability
+ considerations for regular expressions in the
+ JSON Schema Core [json-schema] specification.¶
+ The current URI for the default JSON Schema dialect meta-schema is
+ https://json-schema.org/draft/2020-12/schema.
+ For schema author convenience, this meta-schema describes a dialect
+ consisting of all vocabularies
+ defined in this specification and the JSON Schema Core specification,
+ as well as two former keywords which are reserved for a transitional period.
+ Individual vocabulary and vocabulary meta-schema URIs are given for
+ each section below. Certain vocabularies are optional to support, which
+ is explained in detail in the relevant sections.¶
+
+ Updated vocabulary and meta-schema URIs MAY be published between
+ specification drafts in order to correct errors. Implementations
+ SHOULD consider URIs dated after this specification draft and
+ before the next to indicate the same syntax and semantics
+ as those listed here.¶
+ Validation keywords in a schema impose requirements for successful validation of an
+ instance. These keywords are all assertions without any annotation behavior.¶
+
+ Meta-schemas that do not use "$vocabulary" SHOULD be considered to
+ require this vocabulary as if its URI were present with a value of true.¶
+
+ The current URI for this vocabulary, known as the Validation vocabulary, is:
+ <https://json-schema.org/draft/2020-12/vocab/validation>.¶
+ 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 instance 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 instance validates successfully if
+ its type matches any of the types indicated by the strings in the array.¶
+ 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 instance is considered valid if the regular
+ expression matches the instance successfully. Recall: regular
+ expressions are not implicitly anchored.¶
+ If this keyword has boolean value false, the instance validates
+ successfully. If it has boolean value true, the instance validates
+ successfully if all of its elements are unique.¶
+
+ Omitting this keyword has the same behavior as a value of false.¶
+ The value of this keyword MUST be a non-negative integer.¶
+
+ If "contains" is not present within the same schema object,
+ then this keyword has no effect.¶
+
+ An instance array is valid against "maxContains" in two ways, depending on
+ the form of the annotation result of an adjacent
+ "contains" [json-schema] keyword. The first way is if
+ the annotation result is an array and the length of that array is less than
+ or equal to the "maxContains" value. The second way is if the annotation
+ result is a boolean "true" and the instance array length is less than or
+ equal to the "maxContains" value.¶
+ The value of this keyword MUST be a non-negative integer.¶
+
+ If "contains" is not present within the same schema object,
+ then this keyword has no effect.¶
+
+ An instance array is valid against "minContains" in two ways, depending on
+ the form of the annotation result of an adjacent
+ "contains" [json-schema] keyword. The first way is if
+ the annotation result is an array and the length of that array is greater
+ than or equal to the "minContains" value. The second way is if the
+ annotation result is a boolean "true" and the instance array length is
+ greater than or equal to the "minContains" value.¶
+
+ A value of 0 is allowed, but is only useful for setting a range
+ of occurrences from 0 to the value of "maxContains". A value of
+ 0 causes "minContains" to always pass validation (but validation can
+ still fail against a "maxContains" keyword).¶
+
+ Omitting this keyword has the same behavior as a value of 1.¶
+ 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 instance and as a name within this keyword's value, every
+ item in the corresponding array is also the name of a property
+ in the instance.¶
+
+ Omitting this keyword has the same behavior as an empty object.¶
+ Structural validation alone may be insufficient to allow an application to correctly
+ utilize certain values. The "format" annotation keyword is defined to allow schema
+ authors to convey semantic information for a fixed subset of values which are
+ accurately described by authoritative resources, be they RFCs or other external
+ specifications.¶
+
+ The value of this keyword is called a format attribute. It MUST be a string. A
+ format attribute can generally only validate a given set of instance types. If
+ the type of the instance to validate is not in this set, validation for this
+ format attribute and instance SHOULD succeed. All format attributes defined
+ in this section apply to strings, but a format attribute can be specified
+ to apply to any instance types defined in the data model defined in the
+ core JSON Schema. [json-schema]
+
+ Note that the "type" keyword in this specification defines an "integer" type
+ which is not part of the data model. Therefore a format attribute can be
+ limited to numbers, but not specifically to integers. However, a numeric
+ format can be used alongside the "type" keyword with a value of "integer",
+ or could be explicitly defined to always pass if the number is not an integer,
+ which produces essentially the same behavior as only applying to integers.
+ ¶
+
+ The current URI for this vocabulary, known as the Format-Annotation vocabulary, is:
+ <https://json-schema.org/draft/2020-12/vocab/format-annotation>. The current
+ URI for the corresponding meta-schema is:
+ https://json-schema.org/draft/2020-12/meta/format-annotation.
+ Implementing support for this vocabulary is REQUIRED.¶
+
+ In addition to the Format-Annotation vocabulary, a secondary vocabulary is available
+ for custom meta-schemas that defines "format" as an assertion. The URI for the
+ Format-Assertion vocabulary, is:
+ <https://json-schema.org/draft/2020-12/vocab/format-assertion>. The current
+ URI for the corresponding meta-schema is:
+ https://json-schema.org/draft/2020-12/meta/format-assertion.
+ Implementing support for the Format-Assertion vocabulary is OPTIONAL.¶
+
+ Specifying both the Format-Annotation and the Format-Assertion vocabularies is functionally
+ equivalent to specifying only the Format-Assertion vocabulary since its requirements
+ are a superset of the 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.
+ ¶
+ 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 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 instance 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 instance 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 (Section 5)
+ 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.¶
+ 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.¶
+ Date and time format names are derived from
+ RFC 3339, section 5.6 [RFC3339].
+ 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:¶
+
+
date-time:
+
+ A string instance is valid against this attribute if it is
+ a valid representation according to the "date-time' ABNF rule
+ (referenced above)¶
+
+
+
date:
+
+ A string instance is valid against this attribute if it is
+ a valid representation according to the "full-date" ABNF rule
+ (referenced above)¶
+
+
+
time:
+
+ A string instance is valid against this attribute if it is
+ a valid representation according to the "full-time" ABNF rule
+ (referenced above)¶
+
+
+
duration:
+
+ A string instance is valid against this attribute if it is
+ a valid representation according to the "duration" ABNF rule
+ (referenced above)¶
+
+
+
+
+ Implementations MAY support additional attributes using the other
+ format names defined anywhere in that RFC. If "full-date" or "full-time"
+ are implemented, the corresponding short form ("date" or "time"
+ respectively) MUST be implemented, and MUST behave identically.
+ Implementations SHOULD NOT define extension attributes
+ with any name matching an RFC 3339 format unless it validates
+ according to the rules of that format.
+
+ There is not currently consensus on the need for supporting
+ all RFC 3339 formats, so this approach of reserving the
+ namespace will encourage experimentation without committing
+ to the entire set. Either the format implementation requirements
+ will become more flexible in general, or these will likely
+ either be promoted to fully specified attributes or dropped.
+ ¶
+ A string instance is valid against this attribute if it is
+ a valid URI, according to [RFC3986].¶
+
+
+
uri-reference:
+
+ A string instance is valid against this attribute if it is a valid URI
+ Reference (either a URI or a relative-reference),
+ according to [RFC3986].¶
+
+
+
iri:
+
+ A string instance is valid against this attribute if it is
+ a valid IRI, according to [RFC3987].¶
+
+
+
iri-reference:
+
+ A string instance is valid against this attribute if it is a valid IRI
+ Reference (either an IRI or a relative-reference),
+ according to [RFC3987].¶
+
+
+
uuid:
+
+ A string instance is valid against this attribute if it is a valid
+ string representation of a UUID, according to [RFC4122].¶
+
+
+
+
+ Note that all valid URIs are valid IRIs, and all valid URI References are
+ also valid IRI References.¶
+
+ Note also that the "uuid" format is for plain UUIDs, not UUIDs in URNs. An example
+ is "f81d4fae-7dec-11d0-a765-00a0c91e6bf6". For UUIDs as URNs, use the "uri" format,
+ with a "pattern" regular expression of "^urn:uuid:" to indicate the URI scheme and
+ URN namespace.¶
+ A string instance is valid against this attribute if it
+ is a valid JSON string representation of a JSON Pointer,
+ according to RFC 6901, section 5 [RFC6901].¶
+
+ A regular expression, which SHOULD be valid according to the
+ ECMA-262 [ecma262] regular expression dialect.¶
+
+ Implementations that validate formats MUST accept at least the subset of
+ ECMA-262 defined in the Regular Expressions (Section 4.3)
+ section of this specification, and SHOULD accept all valid ECMA-262 expressions.¶
+ Annotations defined in this section indicate that an instance contains
+ non-JSON data encoded in a JSON string.¶
+
+ These properties provide additional information required to interpret JSON data
+ as rich multimedia documents. They describe the type of content, how it is encoded,
+ and/or how it may be validated. They do not function as validation assertions;
+ a malformed string-encoded document MUST NOT cause the containing instance
+ to be considered invalid.¶
+
+ Meta-schemas that do not use "$vocabulary" SHOULD be considered to
+ require this vocabulary as if its URI were present with a value of true.¶
+
+ The current URI for this vocabulary, known as the Content vocabulary, is:
+ <https://json-schema.org/draft/2020-12/vocab/content>.¶
+ Due to security and performance concerns, as well as the open-ended nature of
+ possible content types, implementations MUST NOT automatically decode, parse,
+ and/or validate the string contents by default. This additionally supports
+ the use case of embedded documents intended for processing by a different
+ consumer than that which processed the containing document.¶
+
+ All keywords in this section apply only to strings, and have no
+ effect on other data types.¶
+
+ Implementations MAY offer the ability to decode, parse, and/or validate
+ the string contents automatically. However, it MUST NOT perform these
+ operations by default, and MUST provide the validation result of each
+ string-encoded document separately from the enclosing document. This
+ process SHOULD be equivalent to fully evaluating the instance against
+ the original schema, followed by using the annotations to decode, parse,
+ and/or validate each string-encoded document.
+
+ For now, the exact mechanism of performing and returning parsed
+ data and/or validation results from such an automatic decoding, parsing,
+ and validating feature is left unspecified. Should such a feature
+ prove popular, it may be specified more thoroughly in a future draft.
+ ¶
+
+ See also the Security Considerations (Section 10)
+ sections for possible vulnerabilities introduced by automatically
+ processing the instance string according to these keywords.¶
+ If the instance value is a string, this property defines that the string
+ SHOULD be interpreted as encoded binary data and decoded using the encoding
+ named by this property.¶
+
+ Possible values indicating base 16, 32, and 64 encodings with several
+ variations are listed in RFC 4648 [RFC4648]. Additionally,
+ sections 6.7 and 6.8 of RFC 2045 [RFC2045] provide
+ encodings used in MIME. This keyword is derived from MIME's
+ Content-Transfer-Encoding header, which was designed to map binary data
+ into ASCII characters. It is not related to HTTP's Content-Encoding header,
+ which is used to encode (e.g. compress or encrypt)
+ the content of HTTP request and responses.¶
+
+ As "base64" is defined in both RFCs, the definition
+ from RFC 4648 SHOULD be assumed unless the string is specifically intended
+ for use in a MIME context. Note that all of these encodings result in
+ strings consisting only of 7-bit ASCII characters. Therefore, this keyword
+ has no meaning for strings containing characters outside of that range.¶
+
+ If this keyword is absent, but "contentMediaType" is present, this
+ indicates that the encoding is the identity encoding, meaning that
+ no transformation was needed in order to represent the content in
+ a UTF-8 string.¶
+ If the instance is a string, this property indicates the media type
+ of the contents of the string. If "contentEncoding" is present,
+ this property describes the decoded string.¶
+
+ The value of this property MUST be a string, which MUST be a media type,
+ as defined by RFC 2046 [RFC2046].¶
+ Instances described by this schema are expected to be strings containing HTML,
+ using whatever character set the JSON string was decoded into.
+ Per section 8.1 of
+ RFC 8259 [RFC8259], outside of an entirely closed
+ system, this MUST be UTF-8.¶
+
+ This example describes a JWT that is MACed using the HMAC SHA-256
+ algorithm, and requires the "iss" and "exp" fields in its claim set.¶
+ Note that "contentEncoding" does not appear. While the "application/jwt"
+ media type makes use of base64url encoding, that is defined by the media
+ type, which determines how the JWT string is decoded into a list of two
+ JSON data structures: first the header, and then the payload. Since the
+ JWT media type ensures that the JWT can be represented in a JSON string,
+ there is no need for further encoding or decoding.¶
+ These general-purpose annotation keywords provide commonly used information
+ for documentation and user interface display purposes. They are not intended
+ to form a comprehensive set of features. Rather, additional vocabularies
+ can be defined for more complex annotation-based applications.¶
+
+ Meta-schemas that do not use "$vocabulary" SHOULD be considered to
+ require this vocabulary as if its URI were present with a value of true.¶
+
+ The current URI for this vocabulary, known as the Meta-Data vocabulary, is:
+ <https://json-schema.org/draft/2020-12/vocab/meta-data>.¶
+ The value of both of these keywords MUST be a string.¶
+
+ Both of these keywords can be used to decorate a user interface with
+ information about the data produced by this user interface. A title will
+ preferably be short, whereas a description will provide explanation about
+ the purpose of the instance described by this schema.¶
+ There are no restrictions placed on the value of this keyword. When
+ multiple occurrences of this keyword are applicable to a single
+ sub-instance, implementations SHOULD remove duplicates.¶
+
+ This keyword can be used to supply a default JSON value associated with a
+ particular schema. It is RECOMMENDED that a default value be valid against
+ the associated schema.¶
+ The value of this keyword MUST be a boolean. When multiple occurrences
+ of this keyword are applicable to a single sub-instance, applications
+ SHOULD consider the instance location to be deprecated if any occurrence
+ specifies a true value.¶
+
+ If "deprecated" has a value of boolean true, it indicates that applications
+ SHOULD refrain from usage of the declared property. It MAY mean the property
+ is going to be removed in the future.¶
+
+ A root schema containing "deprecated" with a value of true indicates that
+ the entire resource being described MAY be removed in the future.¶
+
+ The "deprecated" keyword applies to each instance location to which the
+ schema object containing the keyword successfully applies. This can
+ result in scenarios where every array item or object property
+ is deprecated even though the containing array or object is not.¶
+
+ Omitting this keyword has the same behavior as a value of false.¶
+ The value of these keywords MUST be a boolean. When multiple occurrences
+ of these keywords are applicable to a single sub-instance, the resulting
+ behavior SHOULD be as for a true value if any occurrence specifies a true value,
+ and SHOULD be as for a false value otherwise.¶
+
+ If "readOnly" has a value of boolean true, it indicates that the value
+ of the instance is managed exclusively by the owning authority, and
+ attempts by an application to modify the value of this property are
+ expected to be ignored or rejected by that owning authority.¶
+
+ An instance document that is marked as "readOnly" for the entire document
+ MAY be ignored if sent to the owning authority, or MAY result in an
+ error, at the authority's discretion.¶
+
+ If "writeOnly" has a value of boolean true, it indicates that the value
+ is never present when the instance is retrieved from the owning authority.
+ It can be present when sent to the owning authority to update or create
+ the document (or the resource it represents), but it will not be included
+ in any updated or newly created version of the instance.¶
+
+ An instance document that is marked as "writeOnly" for the entire document
+ MAY be returned as a blank document of some sort, or MAY produce an error
+ upon retrieval, or have the retrieval request ignored, at the authority's
+ discretion.¶
+
+ For example, "readOnly" would be used to mark a database-generated serial
+ number as read-only, while "writeOnly" would be used to mark a password
+ input field.¶
+
+ These keywords can be used to assist in user interface instance generation.
+ In particular, an application MAY choose to use a widget that hides
+ input values as they are typed for write-only fields.¶
+
+ Omitting these keywords has the same behavior as values of false.¶
+ The value of this keyword MUST be an array.
+ There are no restrictions placed on the values within the array.
+ When multiple occurrences of this keyword are applicable to a single
+ sub-instance, implementations MUST provide a flat array of all
+ values rather than an array of arrays.¶
+
+ This keyword can be used to provide sample JSON values associated with a
+ particular schema, for the purpose of illustrating usage. It is
+ RECOMMENDED that these values be valid against the associated schema.¶
+
+ Implementations MAY use the value(s) of "default", if present, as
+ an additional example. If "examples" is absent, "default"
+ MAY still be used in this manner.¶
+ JSON Schema validation defines a vocabulary for JSON Schema core and concerns all
+ the security considerations listed there.¶
+
+ JSON Schema validation allows the use of Regular Expressions, which have numerous
+ different (often incompatible) implementations.
+ Some implementations allow the embedding of arbitrary code, which is outside the
+ scope of JSON Schema and MUST NOT be permitted.
+ Regular expressions can often also be crafted to be extremely expensive to compute
+ (with so-called "catastrophic backtracking"), resulting in a denial-of-service
+ attack.¶
+
+ Implementations that support validating or otherwise evaluating instance
+ string data based on "contentEncoding" and/or "contentMediaType" are at
+ risk of evaluating data in an unsafe way based on misleading information.
+ Applications can mitigate this risk by only performing such processing
+ when a relationship between the schema and instance is established
+ (e.g., they share the same authority).¶
+
+ Processing a media type or encoding is subject to the security considerations
+ of that media type or encoding. For example, the security considerations
+ of RFC 4329 Scripting Media Types [RFC4329] apply when
+ processing JavaScript or ECMAScript encoded within a JSON string.¶
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
+
+
[RFC1123]
+
+Braden, R., Ed., "Requirements for Internet Hosts - Application and Support", STD 3, RFC 1123, DOI 10.17487/RFC1123, , <https://www.rfc-editor.org/info/rfc1123>.
+
+
[RFC2045]
+
+Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, DOI 10.17487/RFC2045, , <https://www.rfc-editor.org/info/rfc2045>.
+
+
[RFC2046]
+
+Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, , <https://www.rfc-editor.org/info/rfc2046>.
+Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, , <https://www.rfc-editor.org/info/rfc4122>.
+Klensin, J., "Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework", RFC 5890, DOI 10.17487/RFC5890, , <https://www.rfc-editor.org/info/rfc5890>.
+
+
[RFC5891]
+
+Klensin, J., "Internationalized Domain Names in Applications (IDNA): Protocol", RFC 5891, DOI 10.17487/RFC5891, , <https://www.rfc-editor.org/info/rfc5891>.
+
+
[RFC6570]
+
+Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, , <https://www.rfc-editor.org/info/rfc6570>.
+Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, , <https://www.rfc-editor.org/info/rfc6901>.
+
+
[RFC8259]
+
+Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/info/rfc8259>.
+ Several keywords have been moved from this document into the
+ Core Specification [json-schema] as of this draft, in some
+ cases with re-naming or other changes. This affects the following former
+ validation keywords:¶
+
+
"definitions"
+
+ Renamed to "$defs" to match "$ref" and be shorter to type.
+ Schema vocabulary authors SHOULD NOT define a "definitions" keyword
+ with different behavior in order to avoid invalidating schemas that
+ still use the older name. While "definitions" is absent in the
+ single-vocabulary meta-schemas referenced by this document, it
+ remains present in the default meta-schema, and implementations
+ SHOULD assume that "$defs" and "definitions" have the same
+ behavior when that meta-schema is used.¶
+
+ All of these keywords apply subschemas to the instance and combine
+ their results, without asserting any conditions of their own.
+ Without assertion keywords, these applicators can only cause assertion
+ failures by using the false boolean schema, or by inverting the result
+ of the true boolean schema (or equivalent schema objects).
+ For this reason, they are better defined as a generic mechanism on which
+ validation, hyper-schema, and extension vocabularies can all be based.¶
+
+
+
"dependencies"
+
+ This keyword had two different modes of behavior, which made it
+ relatively challenging to implement and reason about.
+ The schema form has been moved to Core and renamed to
+ "dependentSchemas", as part of the applicator vocabulary.
+ It is analogous to "properties", except that instead of applying
+ its subschema to the property value, it applies it to the object
+ containing the property.
+ The property name array form is retained here and renamed to
+ "dependentRequired", as it is an assertion which is a shortcut
+ for the conditional use of the "required" assertion keyword.¶
+
+ Thanks to
+ Gary Court,
+ Francis Galiegue,
+ Kris Zyp,
+ and Geraint Luff
+ for their work on the initial drafts of JSON Schema.¶
+
+ Thanks to
+ Jason Desrosiers,
+ Daniel Perrett,
+ Erik Wilde,
+ Evgeny Poberezkin,
+ Brad Bowman,
+ Gowry Sankar,
+ Donald Pipowitch,
+ Dave Finlay,
+ Denis Laxalde,
+ Phil Sturgeon,
+ Shawn Silverman,
+ and Karen Etheridge
+ for their submissions and patches to the document.¶
+
+
+
diff --git a/work-in-progress/index.md b/work-in-progress/index.md
index f2cf1e87..30aaea9c 100644
--- a/work-in-progress/index.md
+++ b/work-in-progress/index.md
@@ -7,6 +7,44 @@ permalink: /work-in-progress
* TOC
{:toc}
-We're working towards draft 2021-NN.
+## Right now
+
+We're working towards JSON Schema 2022-NN.
+
+Additionally, we're working on draft 2020-12-patch-1 ([Associated GitHub milestone](https://github.com/json-schema-org/json-schema-spec/milestone/9))
+
+## Release latest news
+
+On 2022-04-29, we published Release Candiate 0 for this release.
+
+These documents will be given the IETF identifiers `draft-bhutton-*-01`.
+
+## RC-0 preview
+
+You can find RC-0 preview of the following documents:
+- [JSON Schema Core specificatoin](/draft/preview/2020-12-p1-rc-0/jsonschema-core.html)
+- [JSON Schema Validation specification](/draft/preview/2020-12-p1-rc-0/jsonschema-validation.html)
+
+There are no changes to the Relative JSON Pointer specification.
+
+View the git diff on GitHub for:
+- [draft 2020-12 release to 2020-12-patch-01-rc0](https://github.com/json-schema-org/json-schema-spec/compare/2020-12...draft-bhutton--01-rc0) (git tag `draft-bhutton--01-rc0)
+- [draft 2020-12 release to master](https://github.com/json-schema-org/json-schema-spec/compare/2020-12...master) (This may include changes based on Release Candidate feedback)
+
+This "work in progress" page will be updated as the release progress for 2020-12-patch-1 progresses.
+
+## How to provide feedback for RC-0
+Note, feedback for RC-0 closes on 2022-05-14.
+
+Please make use of the two week feedback window for RC-0 by either:
+- Filing issues on the [specification repository](https://github.com/json-schema-org/json-schema-spec/issues), making it clear the issue relates to 2020-12-patch-1-RC-0
+- Discuss in the [#specification channel on our Slack server](https://json-schema.slack.com/archives/CT7FF623C) - You will need to join if you haven't already
+
+**Please note, only feedback relating specifically to the changes found in the above diff are useful. This release is not making functional changes.**
+
+The previous `draft 2020-12` specification documents will become obsolete, as did draft-07 specification documents when they were patched.
+
+If you have suggestions for changes to the specification in general, we invite you to open a [Discussion on our GitHub organization](https://github.com/orgs/json-schema-org/discussions) and/or chat with us in the #general or #specificaiton channels on our [Slack server](/slack).
+
See the [GitHub repository](https://github.com/json-schema-org/json-schema-spec) for ongoing spec work.