From 0d4d5dbbeb1c35c01f37e8d4f4bd2437962a49aa Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Fri, 5 Sep 2025 14:02:13 -0700 Subject: [PATCH 1/4] Rewrite the the Abstract, Introduction, and Overview Once I removed the language about media types (as well as some language about vocabularies that should have already been removed) there was little difference between these sections. I rewrote them to be more distinct and serve separate purposes. I'm pretty happy with the Abstract and Introduction, but wasn't quite sure what to put in the Overview. I chose to make it a general overview of how JSON Schema works. I think it works, but let me know if you're thoughts. --- specs/jsonschema-core.md | 123 ++++++++++++++++++++++----------------- 1 file changed, 69 insertions(+), 54 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 510300b8..263d6f8f 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -1,13 +1,13 @@ -# JSON Schema: A Media Type for Describing JSON Documents +# JSON Schema: A Language for Validating and Annotating JSON ## Abstract -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 document specifies JSON Schema, a domain-specific, declarative language for +validating and annotating JSON documents. It defines a vocabulary for creating +schemas that describe the structure, constraints, and meta-data associated with +a JSON document. JSON Schema provides a standardized way to define the contracts +for JSON-based APIs and data formats, facilitating automated validation, +documentation, and other related tooling. ## Note to Readers @@ -23,17 +23,54 @@ the homepage, or email the document editors. ## Introduction -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. +JSON is a widely used, language-independent data format. While it is excellent +for data exchange, JSON itself lacks a native mechanism for formally describing +its structure and constraints. This absence can lead to ambiguity and errors in +data interchange, particularly in contexts such as API development, +configuration files, and data storage. + +This document defines JSON Schema, a domain-specific, declarative language for +validating and annotating JSON documents. JSON Schema can be represented as a +JSON document itself, which makes it easily portable and machine-readable. + +JSON Schema draws inspiration from the architecture of the World Wide Web, +including concepts such as URIs for identifying and linking schemas. While it +can be applied in many domains, those qualities make it especially well-suited +for describing and validating data exchanged in web APIs. + +A JSON Schema serves as a contract for data. It is primarily designed for two +purposes: validation and annotation. Validation ensures that a JSON instance +conforms to a specific structure and set of constraints. Annotation attaches +metadata to values in a JSON document, which can be used by applications in a +variety of ways. + +JSON Schema can also be used for a variety of other use cases, including +documentation generation, HTML form builders, and type code generation. Although +it is not specifically designed for those tasks, JSON Schema can be extended to +fill any gaps required to support these secondary uses. + +The JSON Schema specification is defined in a series of documents, each +addressing a different aspect of the language. This document, the Core +specification, defines the fundamental keywords and concepts. It is intended to +be implemented as the foundational layer upon which other related specifications +can build to define additional vocabularies or features for specific use cases. -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, and defining terms. +This document defines a set of core keywords that MUST be supported by any +implementation, and cannot be disabled. These keywords are each prefixed with a +"$" character to emphasize their required nature. These keywords are considered +essential to the functioning of JSON Schema. + +Additionally, this document defines a RECOMMENDED set of keywords for +conditionally applying subschemas and for applying subschemas to the contents of +objects and arrays. These keywords, or a set very much like them, are necessary +to write schemas for non-trivial JSON instances, whether those schemas are +intended for validation, annotation, or both. For maximum interoperability, this +additional set is included in this document and its use is strongly encouraged. -Other specifications define keywords that perform assertions about validation, -linking, annotation, navigation, interaction, as well as other related concepts -such as output formats. +This document obsoletes the previous "draft" releases for JSON Schema and +provides the basis for a stable, standardized version. Implementations MAY +continue to support "draft" releases in order to facilitate the transition, +typically by inspecting the value of the `$schema` keyword. ## Conventions and Terminology @@ -47,44 +84,22 @@ document are to be interpreted as defined in [RFC 8259][rfc8259]. ## Overview -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 are not supported. - -This document defines a set of core keywords that MUST be supported by any -implementation, and cannot be disabled. These keywords are each prefixed with a -"$" character to emphasize their required nature. These keywords are essential -to the functioning of the `application/schema+json` media type. - -Additionally, this document defines a RECOMMENDED set of keywords for -applying subschemas conditionally, and for applying subschemas to the contents -of objects and arrays. These keywords, or a set very much like them, are -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 set, for maximum interoperability this additional -set is included in this document and its use is strongly encouraged. - -Further keywords 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 keywords needed to write schemas for -that document's purpose. +A JSON Schema represents a set of constraints and annotations that are applied +to a JSON value. These constraints and annotations are declared using +"keywords". A JSON value is considered valid against a schema if, and only if, +it satisfies the constraint defined by every keyword in that schema. + +Schema evaluation is a recursive process. Some keywords contain one or more +subschemas. These keywords can be used to create complex constraints or to +describe compound values like arrays and objects. For example, to describe a +JSON object, a schema can use the `type` keyword to declare that the value MUST +be an object, and the `properties` keyword to apply separate schemas to each of +the object's properties. This allows for the evaluation of a complex JSON +document using a uniform recursive algorithm. + +JSON Schema defines an official collection of keywords (called a dialect), but +it also includes a flexible extension model that allows for third-parties to +define their own dialects of JSON Schema. ## Definitions From f1a3de3e6012ff9a07be81fa9a696e813ac364ea Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 6 Sep 2025 21:33:55 -0700 Subject: [PATCH 2/4] Updates for fragment identifiers --- specs/jsonschema-core.md | 72 ++++++++++++++++------------------------ 1 file changed, 28 insertions(+), 44 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 263d6f8f..8bc341dd 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -303,54 +303,19 @@ are processed in the same way, with the same available behaviors. ## Fragment Identifiers {#fragments} -In accordance with -[section 3.1 of RFC 6839](https://www.rfc-editor.org/rfc/rfc6839.html#section-3.1), -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. +JSON Schema uses two fragment identifier structures: plain names and JSON +Pointers. Any media types defined for JSON Schema MUST support these structures. The use of JSON Pointers as IRI 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](https://www.w3.org/TR/2012/WD-fragid-best-practices-20121025), -plain name fragment identifiers in `application/schema+json` are reserved for -referencing locally named schemas. - -Plain name fragments MUST follow XML's -[`NCName` production](https://www.w3.org/TR/2006/REC-xml-names11-20060816/#NT-NCName), -which allows for compatibility with the recommended [plain name -syntax](https://www.w3.org/TR/2003/REC-xptr-framework-20030325/) for XML-based -media types. For convenience, the `NCName` syntax is reproduced here in ABNF -form, using a minimal set of rules: +6901][rfc6901]. Fragment identifiers that start with `/` or are the empty +string, MUST be interpreted as JSON Pointer fragment identifiers. -```abnf -NCName = NCNameStartChar *NCNameChar -NCNameStartChar = "_" / ALPHA - / %xC0-D6 / %xD8-F6 / %xF8-2FF - / %x370-37D / %x37F-1FFF - / %x200C-200D / %x2070-218F - / %x2C00-2FEF / %x3001-D7FF - / %xF900-FDCF / %xFDF0-FFFD - / %x10000-EFFFF -NCNameChar = NCNameStartChar / "-" / "." / DIGIT - / %xB7 / %x0300-036F / %x203F-2040 -``` - -All fragment identifiers that do not match the JSON Pointer syntax MUST be -interpreted as plain name fragment identifiers. +Plain name fragment identifiers are reserved for referencing locally named +schemas. All fragment identifiers that are not interpreted as JSON Pointers MUST +be interpreted as plain name fragment identifiers. -Defining a plain name fragment identifier within an `application/schema+json` -document is specified in the [`$anchor` keyword](#anchors) section. +Defining a plain name fragment identifier within a schema resource is specified +in the [`$anchor` keyword](#anchors) section. ## General Considerations @@ -1067,6 +1032,25 @@ details. If present, the value of these keywords MUST be a string and MUST conform to the plain name fragment identifier syntax defined in {{fragments}}. +`$anchor`, `$dynamicAnchor`, and any extensions that define a plain name +fragment identifiers MUST match XML's [`NCName` +production](https://www.w3.org/TR/2006/REC-xml-names11-20060816/#NT-NCName). For +convenience, the `NCName` syntax is reproduced here in ABNF form, using a +minimal set of rules: + +```abnf +NCName = NCNameStartChar *NCNameChar +NCNameStartChar = "_" / ALPHA + / %xC0-D6 / %xD8-F6 / %xF8-2FF + / %x370-37D / %x37F-1FFF + / %x200C-200D / %x2070-218F + / %x2C00-2FEF / %x3001-D7FF + / %xF900-FDCF / %xFDF0-FFFD + / %x10000-EFFFF +NCNameChar = NCNameStartChar / "-" / "." / DIGIT + / %xB7 / %x0300-036F / %x203F-2040 +``` + #### Duplicate schema identifiers {#duplicate-iris} A schema MAY (and likely will) have multiple IRIs, but there is no way for an From bcfa39610d23972a00ee79dba61562e170c5aa18 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 6 Sep 2025 20:56:40 -0700 Subject: [PATCH 3/4] Remove references to JSON Schema media types --- .remarkrc-lint.js | 2 + specs/jsonschema-core.md | 126 ++++++++++++--------------------------- 2 files changed, 41 insertions(+), 87 deletions(-) diff --git a/.remarkrc-lint.js b/.remarkrc-lint.js index 1e60073f..466594c1 100644 --- a/.remarkrc-lint.js +++ b/.remarkrc-lint.js @@ -2,6 +2,7 @@ import remarkValidateLinks from "remark-validate-links"; import remarkPresetLintConsistent from "remark-preset-lint-consistent"; import remarkPresetLintRecommended from "remark-preset-lint-recommended"; import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-style-guide"; +import remarkLintDefinitionCase from "remark-lint-definition-case"; import remarkLintListItemIndent from "remark-lint-list-item-indent"; import remarkLintListItemSpacing from "remark-lint-list-item-spacing"; import remarkLintNoFileNameMixedCase from "remark-lint-no-file-name-mixed-case"; @@ -14,6 +15,7 @@ export default { remarkPresetLintConsistent, remarkPresetLintRecommended, remarkPresetLintMarkdownStyleGuide, + [remarkLintDefinitionCase, false], [remarkLintListItemIndent, "one"], [remarkLintListItemSpacing, { checkBlanks: true }], [remarkLintNoFileNameMixedCase, false], diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 8bc341dd..e4886fd5 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -105,8 +105,8 @@ define their own dialects of JSON Schema. ### JSON Document -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 data", and "JSON value" are +interchangeable and refer to the data model defined in {{data-model}}. In JSON Schema, the terms "JSON document", "JSON text", and "JSON value" are interchangeable because of the data model it defines in {{data-model}}. @@ -117,13 +117,8 @@ model can be interpreted against a JSON Schema. ### Instance -A JSON document to which a schema is applied is known as an "instance". - -JSON Schema is defined over `application/json` or compatible documents, -including media types with the `+json` structured syntax suffix. - -Among these, this specification defines the `application/schema-instance+json` -media type which defines handling for fragments in the IRI. +A JSON document to which a schema is applied is known as a "JSON instance" or +just an "instance". #### Instance Data Model {#data-model} @@ -193,12 +188,8 @@ use of the `const` keyword. ### JSON Schema Documents {#schema-document} -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`. +A JSON Schema document, or simply a schema, is used to describe an instance. A +schema can itself be interpreted as an instance. A JSON Schema MUST be an object or a boolean. @@ -909,21 +900,25 @@ steps. 1. The `$schema` keyword - Implementations MUST process the schema according to the dialect it declares. -2. `application/schema+json` media type with a `schema` parameter - - Implementations which support media type parameter inputs MUST process the - schema according to the dialect the parameter declares. A media type will - generally only be available if the schema has been retrieved from an external - source and only applies to the document root. -3. Parent dialect - An embedded schema resource which does not itself contain a - `$schema` keyword MUST be processed using the same dialect as the schema - which contains it. If the schema is embedded in a non-schema document, the - semantics for determining the dialect MAY be determined by any specification - which applies to that document. +2. Parent schema dialect - A schema resource embedded within another schema + resource which does not itself contain a `$schema` keyword MUST be processed + using the same dialect as the schema which contains it. +3. External context - In some contexts, there is a default dialect or a way to + declare the dialect external from the schema resource in question. Examples + include the following. + - If the schema is embedded in a non-schema document (such as an OpenAPI + Document), the semantics for determining the dialect MUST be determined by + the specification that applies to that document. + - If the media type of the schema is known and the media type defines a + default dialect or a way to declare a dialect, the dialect MUST be + determined by the rules of that media types. For example, the + [application/schema+json] media type includes a `schema` parameter that + can be used to declare the dialect. A media type will generally only be + available if the schema has been retrieved from an external source and + only applies to the document root. 4. User configuration - Implementations MAY provide means for the user to configure the dialect under which a schema should be processed. -(Note that steps 2 and 3 are mutually exclusive.) - If the dialect is not specified through one of these methods, the implementation MUST refuse to process the schema. @@ -940,9 +935,6 @@ The value of this keyword MUST be an [IRI](https://www.rfc-editor.org/info/rfc3987) (containing a scheme) and this IRI MUST be normalized. -If this IRI 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. This keyword MUST NOT appear in a subschema that is not also the root object of a schema @@ -1143,11 +1135,10 @@ 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. -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. +Tools that translate schemas between media types or programming languages 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 @@ -1181,8 +1172,8 @@ implementation-specific default IRI MAY be used as described in RFC 3987 Section 6.5 and RFC 3986 Section 5.1.4. It is RECOMMENDED that implementations document any default base IRI that they assume. -If a schema object is embedded in a document of another media type, then the -initial base IRI is determined according to the rules of that media type. +If a schema object is embedded in a document that is not a schema, then the +initial base IRI is determined according to the rules of that document. Unless the `$id` keyword described in an earlier section is present in the root schema, this base IRI SHOULD be considered the canonical IRI of the schema @@ -1460,14 +1451,17 @@ custom keywords. A reference target under a keyword for which the value is not explicitly known to be a schema results in undefined behavior. Implementations MAY support references to these locations, however such behavior is not considered -interoperable and should not be relied upon.[^10] +interoperable and should not be relied upon. -[^10]: 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 implication and may produce unpredictable -results. +When a schema is resolved over HTTP or another protocol that declares the media +type of the response, implementations SHOULD refuse to evaluate schemas whose +declared media type is not a known and supported JSON Schema media type such as +[application/schema+json].[^10] + +[^10]: An implementation can certainly try to interpret it as a schema, but +there's no guarantee that it can be parsed and evaluated as a schema. Therefore, +interpreting it as such has security implications and may produce unpredictable +or malicious results. #### Failure to resolve references {#failed-refs} @@ -2159,49 +2153,6 @@ Third-party JSON Schema extensions may introduce additional risks. Implementers are advised to consult the specifications of any extensions they support and take into account their security considerations as well. -## IANA Considerations - -### `application/schema+json` - -The proposed MIME media type for JSON Schema is defined as follows: - -Type name:: application - -Subtype name:: schema+json - -Required parameters:: N/A - -Encoding considerations:: Encoding considerations are identical to those -specified for the `application/json` media type. See [JSON][rfc8259]. - -Security considerations:: See {{security}} above. - -Interoperability considerations:: See Sections [6.2](#language), -[6.3](#data-model), and [6.4](#regex) above. - -Fragment identifier considerations:: See {{fragments}} - -### `application/schema-instance+json` - -The proposed MIME media type for JSON Schema Instances that require a JSON -Schema-specific media type is defined as follows: - -Type name:: application - -Subtype name:: schema-instance+json - -Required parameters:: N/A - -Encoding considerations:: Encoding considerations are identical to those -specified for the `application/json` media type. See [JSON][rfc8259]. - -Security considerations:: See {{security}} above. - -Interoperability considerations:: See Sections [6.2](#language), -[6.3](#data-model), and [6.4](#regex) above. - -Fragment identifier considerations:: See {{fragments}} - ## %appendix% Schema identification examples {#idexamples} Consider the following schema, which shows `$id` being used to identify both the @@ -2676,3 +2627,4 @@ to the document. [rfc6901]: https://www.rfc-editor.org/info/rfc6901 [rfc8259]: https://www.rfc-editor.org/info/rfc8259 [rfc8288]: https://www.rfc-editor.org/info/rfc8288 +[application/schema+json]: ../ietf/json-schema-media-types.md From 36390a7a9bf4e8a7805d789145c469a446476e22 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 6 Sep 2025 21:38:29 -0700 Subject: [PATCH 4/4] Add JSON Schema media types I-D --- .gitignore | 1 + ietf/example.md | 32 --- ietf/json-schema-media-types.md | 420 ++++++++++++++++++++++++++++++++ 3 files changed, 421 insertions(+), 32 deletions(-) delete mode 100644 ietf/example.md create mode 100644 ietf/json-schema-media-types.md diff --git a/.gitignore b/.gitignore index 0cb023a3..fa68e22d 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ web/ # IETF builds .refcache/ +ietf/json-schema-media-types.xml # For the node-based build tools node_modules/ diff --git a/ietf/example.md b/ietf/example.md deleted file mode 100644 index 9615bdc4..00000000 --- a/ietf/example.md +++ /dev/null @@ -1,32 +0,0 @@ ---- - -stand_alone: true -ipr: trust200902 -submissiontype: independent -category: info - -author: -- name: Jason Desrosiers - email: jdesrosi@gmail.com - role: editor - -title: Example - ---- abstract - -An example of an I-D in markdown - ---- middle - -# Introduction - -## Notational Conventions - -{::boilerplate bcp14+} - -# Security Considerations - -TODO: Required section - ---- back - diff --git a/ietf/json-schema-media-types.md b/ietf/json-schema-media-types.md new file mode 100644 index 00000000..f55ea2d6 --- /dev/null +++ b/ietf/json-schema-media-types.md @@ -0,0 +1,420 @@ +--- + +stand_alone: true +ipr: trust200902 +submissiontype: independent +category: info + +title: JSON Schema Media Types +author: +- name: Jason Desrosiers + email: jdesrosi@gmail.com + role: editor + +normative: + # TODO: Update to the stable release + JSON-Schema: + title: JSON Schema Core + target: "https://json-schema.org/specification.html" + HTTP: RFC9110 + JSON: RFC8259 + JSON-Pointer: RFC6901 + IRI: RFC3987 + +informative: + draft-2020-12: + title: JSON Schema - draft-2020-12 + date: 2022-06-16 + target: "https://json-schema.org/draft/2020-12" + author: + - ins: A. Wright + - ins: H. Andrews + - ins: B. Hutton + - ins: G. Dennis + draft-2019-09: + title: JSON Schema - draft-2019-09 + date: 2019-09-17 + target: "https://json-schema.org/draft/2019-09" + author: + - ins: A. Wright + - ins: H. Andrews + - ins: B. Hutton + - ins: G. Dennis + draft-07: + title: JSON Schema - draft-07 + date: 2018-03-19 + target: "https://json-schema.org/draft-07" + author: + - ins: A. Wright + - ins: H. Andrews + draft-03: + title: JSON Schema - draft-03 + date: 2018-03-19 + target: "https://json-schema.org/draft-03/draft-zyp-json-schema-03.pdf" + author: + - ins: K. Zyp + - ins: G. Court + profile: RFC6906 + +--- abstract + +This document registers the following media types associated with +{{JSON-Schema}} to the IANA Media Types registry: `application/schema+json` and +`application/schema-instance+json`. + +--- middle + +# Introduction + +{{JSON-Schema}} is a declarative domain-specific language for validating and +annotating {{JSON}} documents. This document registers media types that can be +used with schemas (`application/schema+json`) and instances +(`application/schema-instance+json`) that are represented as JSON. + +Although there is now a stable version of {{JSON-Schema}}, there are still many +dialects of JSON Schema in wide use today including {{draft-07}} and +{{draft-2020-12}}. There are also several third-party JSON Schema dialects as +well including the ones defined for use in +[OpenAPI](https://spec.openapis.org/oas/latest.html#schema-object) and +[MongoDB](https://www.mongodb.com/docs/manual/core/schema-validation). + +The media types defined in this document can be used with any dialect of JSON +Schema including obsolete draft dialects and third-party dialects. The draft +dialects include media type definitions in their specification. This document +obsoletes those definitions while remaining compatible as much as is possible +and reasonable. + +## Notational Conventions + +{::boilerplate bcp14+} + +The terms "content", "content negotiation", "resource", and "user agent" in this +document are to be interpreted as in {{HTTP}}. + +# Media Type application/schema+json {#schema-json} + +The `application/schema+json` media type is an extension of the JSON {{JSON}} +media type and is used for JSON Schemas represented as JSON. It defines two +types of fragment identifiers as well as a media type parameter that can be used +for content negotiation or as a fallback mechanism for identifying the dialect +of the schema. + +The following information serves as the registration form for the +`application/schema+json` media type. + +Type name: +: application + +Subtype name: +: schema+json + +Required parameters: +: N/A + +Optional parameters: + +- schema: An {{IRI}} identifying the JSON Schema dialect the schema was written + for. If this value conflicts with the value of the `$schema` keyword in the + schema, the `$schema` keyword takes precedence. +- profile: **(deprecated)** An alias of the `schema` parameter included for + compatibility with older versions of JSON Schema. + +Encoding considerations: +: Same as "application/json" + +Security considerations: +: See the "Security Considerations" section of {{JSON-Schema}} + +Interoperability considerations: +: See the "General Considerations" section of {{JSON-Schema}} + +Published specification: +: this document + +Applications that use this media type: +: JSON Schema is used in a variety of applications including API servers and + clients that validate JSON requests and responses, IDEs that valid + configuration files, and databases that store JSON. + +Fragment identifier considerations: +: This media type uses the JSON Pointer and plain-name fragment identifier + structures defined in the "Fragment Identifiers" section of {{JSON-Schema}}. + +Additional information: + +- Deprecated alias names for this type: N/A +- Magic number(s): N/A +- File extension(s): json, schema.json +- Macintosh file type code(s): N/A + +Person and email address to contact for further information: +: See Authors' Addresses section. + +Intended usage: +: COMMON + +Restrictions on usage: +: N/A. + +Author: +: See Authors' Addresses section. + +Change controller: +: N/A + +## Identifying the dialect + +If the resource includes the `$schema` keyword, the value of that keyword +determines the dialect of the schema. As a fallback, the `schema` media type +parameter can be used to determine the dialect of the schema. + +## Content negotiation based on dialect + +The `schema` media type parameter can also be used for content negotiation (see +{{Section 12 of HTTP}}). In the following example, the user agent is able to +accept two possible dialects of JSON Schema and the server replies with the +latest one it supports. + +Request: + +~~~ http-message +NOTE: '\' line wrapping per RFC 8792 + +GET /schemas/v2/pet HTTP/1.1 +Host: foo.example +Accept: application/schema+json; \ + schema="https://json-schema.org/v1/2025", \ + application/schema+json; \ + schema="http://json-schema.org/draft-07/schema#" +~~~ + +Response: + +~~~ http-message +NOTE: '\' line wrapping per RFC 8792 + +HTTP/1.1 200 OK +Content-Type: \ + application/schema+json; schema="https://json-schema.org/v1/2025" + +{ + "$id": "https://json-schema.org/v1/2025", + "$schema": "https://json-schema.org/v1/2025", + ... +} +~~~ + + +# Media Type application/schema-instance+json {#schema-instance-json} + +The `application/schema-instance+json` media type is an extension of the +{{JSON}} media type and is used for instances represented as JSON. It defines a +fragment identifier and a media type parameter that can be used for content +negotiation or as a way to declare a schema the instance conforms to. + +The following information serves as the registration form for the +`application/schema-instance+json` media type. + +Type name: +: application + +Subtype name: +: schema-instance+json + +Required parameters: +: N/A + +Optional parameters: + +- schema: + : An IRI-reference {{IRI}} identifying a JSON Schema that the resource + conforms to. If the IRIs is relative, the base URI is the retrieval URI of the + retrieved resource. **(deprecated)** A whitespace-separated list of IRIs is + also allowed, but discouraged due to conflicting semantics in different + dialects of JSON Schema (see {{multiple-schemas}}). If multiple IRIs are + given, the resource conforms to all of the schemas listed. + +Encoding considerations: +: Same as {{JSON}} + +Security considerations: +: Same as {{JSON}} + +Interoperability considerations: +: Same as {{JSON}} + +Published specification: +: this document + +Applications that use this media type: +: JSON Schema is used in a variety of applications including API servers and + clients that validate JSON requests and responses, IDEs that valid + configuration files, databases that store JSON, and more. + +Fragment identifier considerations: +: Fragment identifiers MUST be interpreted as JSON Pointers. The use of JSON + Pointers as URI fragment identifiers is described in {{JSON-Pointer}}. + +Additional information: + +- Deprecated alias names for this type: N/A +- Magic number(s): N/A +- File extension(s): json +- Macintosh file type code(s): N/A + +Person and email address to contact for further information: +: See Authors' Addresses section. + +Intended usage: +: COMMON + +Restrictions on usage: +: N/A + +Author: +: See Authors' Addresses section. + +Change controller: +: N/A + +## Identifying a schema + +It is a common convention for schemas to use `$schema` in an instance to declare +the schema the instance conforms to. However, this is not an official behavior +defined for JSON Schema and has limitations such the inability to declare the +schema of an instance that isn't an object. + +The `schema` media type parameter serves the same purpose of declaring the +instance's schema without the limitations. It also allows for content +negotiation (see {{Section 12 of HTTP}}). + +The following is an example of content negotiation where a user agent can accept +two different versions of a "pet" resource. Each resource version is identified +by a unique JSON Schema. + +Request: + +~~~ http-message +NOTE: '\' line wrapping per RFC 8792 + +GET /pet/1234 HTTP/1.1 +Host: foo.example +Accept: \ + application/schema-instance+json; schema="/schemas/v2/pet"; q=0.2, \ + application/schema-instance+json; schema="/schemas/v1/pet"; q=0.1 +~~~ + +Response: + +~~~ http-message +NOTE: '\' line wrapping per RFC 8792 + +HTTP/1.1 200 Ok +Content-Type: \ + application/schema-instance+json; schema="/schemas/v2/pet" + +{ + "petId": "1234", + "name": "Pluto", + ... +} +~~~ + +# Interoperability Considerations + +In its various iterations, JSON Schema has made several changes to how it +defines its media types and how it recommends the use of media types. This has +led to some differences in how these media types have been used in the wild. + +The media types defined in this document are designed to be compatible with as +many of those iterations as possible with special consideration for what has +been seen in use in the wild. However, there are some things that couldn't be +included. Implementations MAY consider supporting a "compatibility mode" to +support behaviors that aren't officially supported yet might be encountered in +the wild. + +## The `profile` parameter {#profile-parameter} + +Earlier drafts of JSON Schema suggest the use of the `profile` media type +parameter as defined by {{profile}} to associate an instance with a schema or a +schema with a meta-schema. There was some debate about whether a schema can be +considered a profile, so the parameter was renamed to `schema`. + +The `profile` parameter is included for the `application/schema+json` media type +for compatibility with older systems. It's not included for the +`application/schema-instance+json` media type because there was never a time +where the `profile` parameter was defined for that media type. + +## A Media Type for Instances + +Earlier drafts of JSON Schema suggest the use of `application/json` with the +{{profile-parameter}} to associate an instance with a schema. However, it isn't +allowed to use media type parameters that aren't defined to be used by the media +type. The `application/schema-instance+json` media type was introduced to +address that problem. In {{draft-07}}, the specification started suggesting the +new media type be used instead of `application/json` for instances so a media +type parameter can be used correctly. + +Implementations MAY consider supporting the `profile` parameter with +`application/json` if compatibility with older systems is necessary. Supporting +the `schema` parameter with `application/json` should not be necessary because +that parameter was not introduced before the `application/schema-instance+json` +media type was introduced. + +## Multiple `schema` IRIs {#multiple-schemas} + +The semantics of the `schema` parameter when it contains multiple IRIs has +conflicting definitions in different releases of JSON Schema. {{draft-07}} +defines that the instance conforms to at least one of the schemas. +{{draft-2019-09}} contradicts itself saying in different places that the +instance conforms to all of the schemas and that it conforms to at least one of +the schemas. The `schema` parameter was removed entirely for {{draft-2020-12}} +with the intention of sorting out the contradiction later. + +The `application/schema-instance+json` media type uses the "all of" semantics as +that was the most recent intention. It's also more logical, more useful, and in +alignment with how `profile` is defined. However, due to the contradicting +definitions and unclear use case, using multiple IRIs is considered deprecated +going forward. + +Implementations MAY consider supporting the "any of" definition through +configuration of some kind to switch between the "all of" and "any of" +definitions if they think their users might depend on the "any of" definition. + +The `application/schema+json` media type doesn't allow for multiple IRIs because +a schema can only have one dialect. Technically the {{draft-2019-09}} +specification allows the `schema` parameter to have multiple values, but since +that doesn't make sense, it was considered safe to leave that option out. + +Implementations MAY consider supporting the "any of" definition for multiple +values in `schema` if they think their users might depend on it. + +## The `schema` Link Relation + +{{draft-07}} and {{draft-2019-09}} specify that the `schema` media type +parameter can also be used as a link relation. However, there's no mention of +registering the relation or any evidence that anyone has used it in this way. +Therefore, it was decided not to register `schema` as a link relation. + +Implementations MAY consider supporting the `schema` link relation if they think +their users might depend on it. + +## Fragment Identifiers + +Through {{draft-03}}, JSON Schema defined a dot-notation alternative to JSON +Pointer fragment identifiers. Implementations MAY consider supporting the +dot-notation syntax if they think their users might depend on it. + +# Security Considerations + +See the "Security Considerations" for each registered media type. + +# IANA Considerations + + IANA is asked to update the ["Media Types" + registry](https://www.iana.org/assignments/media-types) with the registration + information in {{schema-json}} for the media types `application/schema+json` + and `application/schema-instance+json`. + +--- back +