diff --git a/remark/rehype-link-transformer.js b/remark/rehype-link-transformer.js new file mode 100644 index 00000000..224667d1 --- /dev/null +++ b/remark/rehype-link-transformer.js @@ -0,0 +1,18 @@ +import { existsSync } from "fs"; +import { visit } from "unist-util-visit"; +import url from "url"; + + +const rehypeLinkTransformer = () => (tree, vfile) => { + visit(tree, "element", (node) => { + if (node.tagName === "a") { + const href = url.parse(node.properties.href); + if (href.hostname === null && href.pathname?.endsWith(".md") && existsSync(vfile.history[0])) { + href.pathname = href.pathname.replace(/.md$/, ".html"); + node.properties.href = url.format(href); + } + } + }); +}; + +export default rehypeLinkTransformer; diff --git a/specs/.remarkrc-build.js b/specs/.remarkrc-build.js index 89ca8695..e73b10ad 100644 --- a/specs/.remarkrc-build.js +++ b/specs/.remarkrc-build.js @@ -6,6 +6,7 @@ import remarkRehype from "remark-rehype"; import rehypeStringify from "rehype-stringify"; import rehypeDocument from "rehype-document"; import specsPreset from "./.remarkrc-specs.js"; +import rehypeLinkTransformer from "../remark/rehype-link-transformer.js"; dotenv.config(); @@ -15,6 +16,7 @@ export default { specsPreset, remarkTorchLight, remarkRehype, + rehypeLinkTransformer, [rehypeDocument, { css: ["https://cdn.jsdelivr.net/npm/water.css@2/out/dark.css"], style: readFileSync(resolve(import.meta.dirname, "spec.css"), "utf8") diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 0670e2a7..f50726d3 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -39,11 +39,11 @@ such as output formats. 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). +interpreted as described in [RFC 2119](https://www.rfc-editor.org/info/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). +document are to be interpreted as defined in [RFC 8259][rfc8259]. ## Overview @@ -242,12 +242,15 @@ are using. #### Root Schema and Subschemas and Resources {#root} -A JSON Schema resource is a schema which is [canonically](#rfc6596) identified -by an [absolute IRI](#rfc3987). Schema resources MAY also be identified by IRIs, -including IRIs 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 IRIs with fragments are considered to be non-canonical. +A JSON Schema resource is a schema which is +[canonically](https://www.rfc-editor.org/info/rfc6596) identified by an +[absolute IRI](https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2). Schema +resources MAY also be identified by IRIs, including IRIs with fragments, if the +resulting secondary resource (as defined by +[section 3.5 of RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.5)) +is identical to the primary resource. This can occur with the empty fragment, or +when one schema resource is embedded in another. Any such IRIs 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 IRI is @@ -285,10 +288,12 @@ are processed in the same way, with the same available behaviors. ## Fragment Identifiers {#fragments} -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`.) +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 @@ -296,21 +301,22 @@ identifier structures: plain names and JSON Pointers. The structure: JSON Pointers. The use of JSON Pointers as IRI fragment identifiers is described in [RFC -6901](#rfc6901). For `application/schema+json`, which supports two fragment +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](#w3cwd-fragid-best-practices-20121025), plain name fragment -identifiers in `application/schema+json` are reserved for referencing locally -named schemas. +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](#xml-names), which -allows for compatibility with the recommended plain name -[syntax](#w3crec-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: +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: ```abnf NCName = NCNameStartChar *NCNameChar @@ -336,7 +342,7 @@ keyword](#anchors) section. ### Range of JSON Values -An instance may be any valid JSON value as defined by [JSON](#rfc8259). JSON +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. @@ -352,7 +358,7 @@ 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). +section 21.2.1](https://www.ecma-international.org/ecma-262/11.0/index.html). Unless otherwise specified by a keyword, regular expressions MUST NOT be considered to be implicitly anchored at either end. All regular expression @@ -367,7 +373,7 @@ schema authors SHOULD limit themselves to the following regular expression tokens: - individual Unicode characters, as defined by the [JSON - specification](#rfc8259); + specification][rfc8259]; - simple atoms: `.` (any character except line terminator); - simple character classes (`[abc]`), range character classes (`[a-z]`); - complemented simple character classes (`[^abc]`); @@ -653,8 +659,9 @@ 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. +Hyper-Schema's](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02) +`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, @@ -685,7 +692,7 @@ based on the schema location that contributed the value. This is intended to allow flexible usage. Collecting the schema location facilitates such usage. For example, consider this schema, which uses annotations and assertions from -the [Validation specification](#json-schema-validation): +the [Validation specification](./jsonschema-validation.md): Note that some lines are wrapped for clarity. @@ -880,8 +887,9 @@ applies to the resource in which it is declared as well as any embedded schema resources, unless such a resource itself declares a different dialect by including the `$schema` keyword with a different value. -The value of this keyword MUST be an [IRI](#rfc3987) (containing a scheme) and -this IRI MUST be normalized. +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`. @@ -896,12 +904,14 @@ by other parties. ### Base IRI, Anchors, and Dereferencing To differentiate between schemas in a vast ecosystem, schema resources are -identified by [absolute IRIs](#rfc3987) (without fragments). These identifiers -are used to create references between schema resources. When comparing IRIs for -the purposes of resource identification, implementations SHOULD first follow the -IRI normalization procedures defined in [RFC 3987](#rfc3987), section 5.3. - -Several keywords can accept a relative [IRI reference](#rfc3987), or a value +identified by +[absolute IRIs](https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2) +(without fragments). These identifiers are used to create references between +schema resources. When comparing IRIs for the purposes of resource +identification, implementations SHOULD first follow the IRI normalization +procedures defined in [RFC 3987][rfc3987], section 5.3. + +Several keywords can accept a relative IRI reference, or a value used to construct a relative IRI reference. For these keywords, it is necessary to establish a base IRI in order to resolve the reference. @@ -909,14 +919,16 @@ to establish a base IRI in order to resolve the reference. An `$id` keyword in a schema or subschema identifies that schema or subschema as a distinct schema resource. The value for this keyword MUST be a string, and -MUST represent a valid [IRI reference](#rfc3987) without a fragment. +MUST represent a valid IRI reference without a fragment. When the value of this keyword is resolved against the current base IRI, the resulting absolute IRI then serves as the identifier for the schema resource and as a base IRI for relative IRI references in keywords within that schema resource and for embedded schema resources, in accordance with [RFC 3987 section -6.5](#rfc3987) and [RFC 3986 section 5.1.1](#rfc3986) regarding base IRIs -embedded in content and RFC 3986 section 5.1.2 regarding encapsulating entities. +6.5](https://www.rfc-editor.org/rfc/rfc3987.html#section-6.5) and +[RFC 3986 section 5.1.1](https://www.rfc-editor.org/rfc/rfc3986.html#section-5.1.1) +regarding base IRIs embedded in content and RFC 3986 section 5.1.2 regarding +encapsulating entities. Note that this IRI is an identifier and not necessarily a network locator. In the case of a network-addressable URL, a schema need not be downloadable from @@ -933,7 +945,8 @@ given in {{initial-base}}. ##### Identifying the root schema The root schema of a JSON Schema document SHOULD contain an `$id` keyword with -an [absolute IRI](#rfc3987) (containing a scheme, but no fragment). +an [absolute IRI](https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2) +(containing a scheme, but no fragment). #### Defining location-independent identifiers {#anchors} @@ -951,7 +964,8 @@ fragments, rather than absolute IRIs as seen with `$id`. keyword is appended to the IRI of the schema resource containing it. As discussed in {{id-keyword}}, this is either the nearest `$id` in the same or an ancestor schema object, or the base IRI for the document as determined according -to [RFC 3987](#rfc3987) and [RFC 3986](#rfc3986). +to [RFC 3987][rfc3987] and +[RFC 3986][rfc3986]. In contrast, `$dynamicAnchor` operates independently of resource IRIs and is instead dependent on the dynamic scope of the evaluation. `$dynamicAnchor` @@ -998,10 +1012,10 @@ Resolved against the current IRI base, it produces the IRI 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 resolved IRI produced by `$ref` 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. Implementations which can access the network -SHOULD default to operating offline. +The resolved IRI produced by `$ref` 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. Implementations which can access the network SHOULD +default to operating offline. ##### Dynamic References with `$dynamicRef` {#dynamic-ref} @@ -1086,21 +1100,23 @@ MUST NOT be collected as an annotation result. #### Initial Base IRI {#initial-base} -[RFC 3987 Section 6.5](#rfc3987) and [RFC 3986 Section 5.1](#rfc3986) defines -how to determine the default base IRI of a document. +[RFC 3987 Section 6.5](https://www.rfc-editor.org/rfc/rfc3987.html#section-6.5) +and +[RFC 3986 Section 5.1](https://www.rfc-editor.org/rfc/rfc3986.html#section-5.1) +defines how to determine the default base IRI of a document. Informatively, the initial base IRI of a schema is the IRI at which it was found, whether that was a network location, a local filesystem, or any other situation identifiable by a IRI of any known scheme. If a schema document defines no explicit base IRI with `$id` (embedded in -content), the base IRI is that determined per [RFC 3987 Section 6.5](#rfc3987) -and [RFC 3986 section 5](#rfc3986). +content), the base IRI is that determined per RFC 3987 Section 6.5 +and RFC 3986 section 5. If no source is known, or no IRI scheme is known for the source, a suitable -implementation-specific default IRI MAY be used as described in [RFC 3987 -Section 6.5](#rfc3987) and [RFC 3986 Section 5.1.4](#rfc3986). It is RECOMMENDED -that implementations document any default base IRI that they assume. +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. @@ -1151,7 +1167,7 @@ expect such features to be interoperable across implementations. Schemas can be identified by any IRI that has been given to them, including a JSON Pointer or their IRI given directly by `$id`. In all cases, dereferencing a `$ref` reference involves first resolving its value as a IRI reference against -the current base IRI per [RFC 3986](#rfc3986). +the current base IRI per [RFC 3986][rfc3986]. If the resulting IRI identifies a schema within the current document, or within another schema document that has been made available to the implementation, then @@ -1423,16 +1439,16 @@ all annotation results), would result in a resolution failure. 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). +linking][rfc8288]. ##### Linking to a Schema It is RECOMMENDED that instances described by a schema provide a link to a downloadable JSON Schema using the link relation "describedby", as defined by -[Linked Data Protocol 1.0, section 8.1](#w3crec-ldp-20150226). +[Linked Data Protocol 1.0, section 8.1](https://www.w3.org/TR/2015/REC-ldp-20150226/#link-relation-describedby). In HTTP, such links can be attached to any response using the [Link -header](#rfc8288). An example of such a header would be: +header][rfc8288]. An example of such a header would be: ``` Link: ; rel="describedby" @@ -1440,11 +1456,12 @@ Link: ; rel="describedby" ##### Usage Over HTTP -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. +When used for hypermedia systems over a network, +[HTTP](https://www.rfc-editor.org/info/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 @@ -1845,9 +1862,9 @@ property values. The behavior of this keyword depends on all adjacent keywords as well as keywords in successfully validated subschemas that apply to the same instance -location by evaluating the instance's property values. This includes, but is not limited -to, `properties`, `patternProperties`, and `additionalProperties`, itself, and -all [in-place applicators](#in-place) defined in this document. +location by evaluating the instance's property values. This includes, but is not +limited to, `properties`, `patternProperties`, and `additionalProperties`, +itself, and all [in-place applicators](#in-place) defined in this document. This keyword applies its subschema to any property values which have not been deemed "evaluated" per {{unevaluated}}. Validation passes if the keyword's @@ -1954,7 +1971,7 @@ SHOULD use the terms defined by this document to do so. ## Security Considerations {#security} Both schemas and instances are JSON values. As such, all security considerations -defined in [RFC 8259](#rfc8259) apply. +defined in [RFC 8259][rfc8259] apply. Instances and schemas are both frequently written by untrusted third parties, to be deployed on public Internet servers. Implementations should take care that @@ -1993,7 +2010,7 @@ 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). +specified for the `application/json` media type. See [JSON][rfc8259]. Security considerations:: See {{security}} above. @@ -2014,7 +2031,7 @@ 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). +specified for the `application/json` media type. See [JSON][rfc8259]. Security considerations:: See {{security}} above. @@ -2023,116 +2040,6 @@ Interoperability considerations:: See Sections [6.2](#language), Fragment identifier considerations:: See {{fragments}} -## References - -### Normative References - -#### [RFC2119] {#rfc2119} - -Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, -RFC 2119, DOI 10.17487/RFC2119, March 1997, -<>. - -#### [RFC3986] {#rfc3986} - -Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier -(URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, -<>. - -#### [RFC3987] {#rfc3987} - -Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC -3987, DOI 10.17487/RFC3987, January 2005, -<>. - -#### [RFC6839] {#rfc6839} - -Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", -RFC 6839, DOI 10.17487/RFC6839, January 2013, -<>. - -#### [RFC6901] {#rfc6901} - -Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation -(JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, -<>. - -#### [RFC8259] {#rfc8259} - -Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", -STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, -<>. - -#### [W3C.REC-ldp-20150226] {#w3crec-ldp-20150226} - -Malhotra, A., Ed., Arwe, J., Ed., and S. Speicher, Ed., "Linked Data Platform -1.0", W3C REC REC-ldp-20150226, W3C REC-ldp-20150226, 26 February 2015, -<>. - -#### [ecma262] {#ecma262} - -"ECMA-262, 11th edition specification", June 2020, -<>. - -### Informative References - -#### [RFC6596] {#rfc6596} - -Ohye, M. and J. Kupke, "The Canonical Link Relation", RFC 6596, DOI -10.17487/RFC6596, April 2012, <>. - -#### [RFC7049] {#rfc7049} - -Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC -7049, DOI 10.17487/RFC7049, October 2013, -<>. - -#### [RFC7231] {#rfc7231} - -Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): -Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, -<>. - -#### [RFC8288] {#rfc8288} - -Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, -<>. - -#### [W3C.WD-fragid-best-practices-20121025] -{#w3cwd-fragid-best-practices-20121025} - -Tennison, J., Ed., "Best Practices for Fragment Identifiers and Media Type -Definitions", W3C WD WD-fragid-best-practices-20121025, W3C -WD-fragid-best-practices-20121025, 25 October 2012, -<>. - -#### [W3C.REC-xptr-framework-20030325] {#w3crec-xptr-framework-20030325} - -Maler, E., Ed., Marsh, J., Ed., Walsh, N., Ed., and P. Grosso, Ed., "XPointer -Framework", W3C REC REC-xptr-framework-20030325, W3C -REC-xptr-framework-20030325, 25 March 2003, -<>. - -#### [json-schema-validation] {#json-schema-validation} - -Wright, A., Andrews, H., and B. Hutton, "JSON Schema Validation: A Vocabulary -for Structural Validation of JSON", Work in Progress, Internet-Draft, -draft-bhutton-json-schema-validation-01, June 2022, -<>. - -#### [json-hyper-schema] {#json-hyper-schema} - -Andrews, H. and A. Wright, "JSON Hyper-Schema: A Vocabulary for Hypermedia -Annotation of JSON", Work in Progress, Internet-Draft, -draft-handrews-json-schema-hyperschema-02, November 2017, -<>. - -#### [xml-names] {#xml-names} - -Bray, T., Ed., Hollander, D., Ed., Layman, A., Ed., and R. Tobin, Ed., -"Namespaces in XML 1.1 (Second Edition)", August 2006, -<>. - ## %appendix% Schema identification examples {#idexamples} Consider the following schema, which shows `$id` being used to identify both the @@ -2162,7 +2069,7 @@ name fragment identifiers. ``` The schemas at the following locations (indicated by plain -[JSON Pointers](#rfc6901) relative to the root document) have the following base +[JSON Pointers][rfc6901] relative to the root document) have the following base IRIs, and are identifiable by any listed IRI in accordance with {{fragments}} and {{embedded}} above. @@ -2600,3 +2507,9 @@ to the document. | Greg Dennis | | | | [^19]: This section to be removed before leaving Internet-Draft status. + +[rfc3986]: https://www.rfc-editor.org/info/rfc3986 +[rfc3987]: https://www.rfc-editor.org/info/rfc3987 +[rfc6901]: https://www.rfc-editor.org/info/rfc6901 +[rfc8259]: https://www.rfc-editor.org/info/rfc8259 +[rfc8288]: https://www.rfc-editor.org/info/rfc8288 diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index f20f64b2..0151a2ad 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -29,19 +29,19 @@ 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. +[JSON Schema core](./jsonschema-core.md) specification. ## Conventions and Terminology 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). +interpreted as described in [RFC 2119](https://www.rfc-editor.org/info/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). +array are [equal](./jsonschema-core.md). ## Overview @@ -82,7 +82,8 @@ 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. +regular expressions in the [JSON Schema Core](./jsonschema-core.md) +specification. ## Meta-Schema {#meta-schema} @@ -192,7 +193,7 @@ A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword. The length of a string instance is defined as the number of its characters as -defined by [RFC 8259](#rfc8259). +defined by [RFC 8259][rfc8259]. #### `minLength` @@ -202,7 +203,7 @@ A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword. The length of a string instance is defined as the number of its characters as -defined by [RFC 8259](#rfc8259). +defined by [RFC 8259][rfc8259]. Omitting this keyword has the same behavior as a value of 0. @@ -303,7 +304,8 @@ type, each distinct value will 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 keyword SHOULD succeed. All format values defined in this section apply to strings, but a format value can be specified to apply to any instance types -defined in the data model defined in the [core JSON Schema](#json-schema) specification[^1]. +defined in the data model defined in the [core JSON +Schema](./jsonschema-core.md) specification[^1]. [^1]: 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 @@ -321,7 +323,9 @@ from previous iterations of this specification. Previously, `format` was an annotation-only keyword by default and implementations that supported assertion were required to offer some configuration that allowed users to explicitly enable assertion. Assertion is now a requirement in order to meet user -expectations. See [json-schema-org/json-schema-spec #1520](https://github.com/json-schema-org/json-schema-spec/issues/1520) for more. +expectations. See [json-schema-org/json-schema-spec +#1520](https://github.com/json-schema-org/json-schema-spec/issues/1520) for +more. In addition to the assertion behavior, this keyword also produces its value as an annotation. @@ -354,9 +358,9 @@ custom format values. These attributes apply to string instances. -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. +Date and time format names are derived from +[RFC 3339, section 5.6](https://www.rfc-editor.org/info/rfc3339). The duration +format is from the ISO 8601 ABNF as given in Appendix A of RFC 3339. - *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) @@ -386,10 +390,11 @@ A string instance is valid against these format values if it is a valid Internet email address as follows: - *email:* As defined by the "Mailbox" ABNF rule in [RFC 5321, section - 4.1.2](#rfc5321). + 4.1.2](https://www.rfc-editor.org/info/rfc5321). - *idn-email:* As defined by the extended "Mailbox" ABNF rule in [RFC 6531, - section 3.3](#rfc6531). Note that all strings valid against the "email" - attribute are also valid against the "idn-email" attribute. + section 3.3](https://www.rfc-editor.org/info/rfc6531). Note that all strings + valid against the "email" attribute are also valid against the "idn-email" + attribute. #### Hostnames @@ -398,13 +403,15 @@ These attributes apply to string instances. A string instance is valid against these attributes if it is a valid representation for an Internet hostname as follows: -- *hostname:* As defined by [RFC 1123, section 2.1](#rfc1123), including host - names produced using the Punycode algorithm specified in [RFC 5891, section - 4.4](#rfc5891). +- *hostname:* As defined by + [RFC 1123, section 2.1](https://www.rfc-editor.org/info/rfc1123), including + host names produced using the Punycode algorithm specified in [RFC 5891, + section 4.4](https://www.rfc-editor.org/info/rfc5891). - *idn-hostname:* As defined by either RFC 1123 as for hostname, or an internationalized hostname as defined by [RFC 5890, section - 2.3.2.3](#rfc5890). Note that all strings valid against the "hostname" - attribute are also valid against the "idn-hostname" attribute. + 2.3.2.3](https://www.rfc-editor.org/info/rfc5890). Note that all strings valid + against the "hostname" attribute are also valid against the "idn-hostname" + attribute. #### IP Addresses @@ -414,23 +421,25 @@ A string instance is valid against these attributes if it is a valid representation of an IP address as follows: - *ipv4:* An IPv4 address according to the "dotted-quad" ABNF syntax as defined - in [RFC 2673, section 3.2](#rfc2673). -- *ipv6:* An IPv6 address as defined in [RFC 4291, section 2.2](#rfc4291). + in [RFC 2673, section 3.2](https://www.rfc-editor.org/info/rfc2673). +- *ipv6:* An IPv6 address as defined in + [RFC 4291, section 2.2](https://www.rfc-editor.org/info/rfc4291). #### Resource Identifiers These attributes apply to string instances. - *uri:* A string instance is valid against this attribute if it is a valid IRI, - according to [RFC3987](#rfc3987). + according to [RFC 3987][rfc3987]. - *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](#rfc3986). + [RFC 3986](https://www.rfc-editor.org/info/rfc3986). - *iri:* A string instance is valid against this attribute if it is a valid IRI, - according to [RFC3987](#rfc3987). + according to [RFC 3987][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](#rfc3987). + [RFC 3987][rfc3987]. - *uuid:* A string instance is valid against this attribute if it is a valid - string representation of a UUID, according to [RFC4122](#rfc4122). + string representation of a UUID, according to + [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Note that all valid URIs are valid IRIs, and all valid URI References are also valid IRI References. @@ -445,7 +454,8 @@ the URI scheme and URN namespace. This attribute applies to string instances. A string instance is valid against this attribute if it is a valid URI Template -(of any level), according to [RFC6570](#rfc6570). +(of any level), according to +[RFC 6570](https://www.rfc-editor.org/info/rfc6570). Note that URI Templates may be used for IRIs; there is no separate IRI Template specification. @@ -456,18 +466,20 @@ These attributes apply to string instances. - *json-pointer:* 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). + section 5](https://www.rfc-editor.org/info/rfc6901). - *relative-json-pointer:* A string instance is valid against this attribute if - it is a valid [Relative JSON Pointer](#relative-json-pointer). To allow for - both absolute and relative JSON Pointers, use `anyOf` or `oneOf` to indicate - support for either format. + it is a valid + [Relative JSON Pointer](https://datatracker.ietf.org/doc/html/draft-handrews-relative-json-pointer-01). + To allow for both absolute and relative JSON Pointers, use `anyOf` or `oneOf` + to indicate support for either format. #### regex This attribute applies to string instances. A regular expression, which SHOULD be valid according to the -[ECMA-262](#ecma262) regular expression dialect. +[ECMA-262](https://www.ecma-international.org/ecma-262/11.0/index.html) regular +expression dialect. Implementations that validate formats MUST accept at least the subset of ECMA-262 defined in {{regexinterop}}, and SHOULD accept all valid ECMA-262 @@ -503,12 +515,13 @@ be interpreted as encoded binary data and applications wishing to decode it SHOULD do so 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. +are listed in [RFC 4648](https://www.rfc-editor.org/info/rfc4648). Additionally, +sections 6.7 and 6.8 of [RFC 2045](https://www.rfc-editor.org/info/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. @@ -529,7 +542,7 @@ 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). +defined by [RFC 2046](https://www.rfc-editor.org/info/rfc2046). ### `contentSchema` @@ -574,7 +587,7 @@ Another example: 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 +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 @@ -732,140 +745,8 @@ 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. - -## References - -### Normative References - -#### [RFC2119] {#rfc2119} - -Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, -RFC 2119, DOI 10.17487/RFC2119, March 1997, -<>. - -#### [RFC1123] {#rfc1123} - -Braden, R., Ed., "Requirements for Internet Hosts - Application and Support", -STD 3, RFC 1123, DOI 10.17487/RFC1123, October 1989, -<>. - -#### [RFC2045] {#rfc2045} - -Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part -One: Format of Internet Message Bodies", RFC 2045, DOI 10.17487/RFC2045, -November 1996, <>. - -#### [RFC2046] {#rfc2046} - -Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part -Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, November 1996, -<>. - -#### [RFC2673] {#rfc2673} - -Crawford, M., "Binary Labels in the Domain Name System", RFC 2673, DOI -10.17487/RFC2673, August 1999, <>. - -#### [RFC3339] {#rfc3339} - -Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, -DOI 10.17487/RFC3339, July 2002, <>. - -#### [RFC3986] {#rfc3986} - -Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier -(URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, -<>. - -#### [RFC3987] {#rfc3987} - -Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC -3987, DOI 10.17487/RFC3987, January 2005, -<>. - -#### [RFC4122] {#rfc4122} - -Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) -URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005, -<>. - -#### [RFC4291] {#rfc4291} - -Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 4291, DOI -10.17487/RFC4291, February 2006, <>. - -#### [RFC4648] {#rfc4648} - -Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI -10.17487/RFC4648, October 2006, <>. - -#### [RFC5321] {#rfc5321} - -Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, DOI 10.17487/RFC5321, -October 2008, <>. - -#### [RFC5890] {#rfc5890} - -Klensin, J., "Internationalized Domain Names for Applications (IDNA): -Definitions and Document Framework", RFC 5890, DOI 10.17487/RFC5890, August -2010, <>. - -#### [RFC5891] {#rfc5891} - -Klensin, J., "Internationalized Domain Names in Applications (IDNA): Protocol", -RFC 5891, DOI 10.17487/RFC5891, August 2010, -<>. - -#### [RFC6570] {#rfc6570} - -Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI -Template", RFC 6570, DOI 10.17487/RFC6570, March 2012, -<>. - -#### [RFC6531] {#rfc6531} - -Yao, J. and W. Mao, "SMTP Extension for Internationalized Email", RFC 6531, DOI -10.17487/RFC6531, February 2012, <>. - -#### [RFC6901] {#rfc6901} - -Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation -(JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, -<>. - -#### [RFC8259] {#rfc8259} - -Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", -STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, -<>. - -#### [ecma262] {#ecma262} - -ECMA-262, 11th edition specification", June 2020, -<>. - -#### [relative-json-pointer] {#relative-json-pointer} - -Luff, G., Andrews, H., and B. Hutton, Ed., "Relative JSON Pointers", Work in -Progress, Internet-Draft, draft-handrews-relative-json-pointer-01, December -2020, -<>. - -#### [json-schema] {#json-schema} - -Wright, A., Andrews, H., Hutton, B., and G. Dennis, "JSON Schema: A Media Type -for Describing JSON Documents", Work in Progress, Internet-Draft, -draft-bhutton-json-schema-01, June 2022, -<>. - -### Informative References - -#### \[RFC4329\] {#rfc4329} - -Hoehrmann, B., "Scripting Media Types", RFC 4329, DOI 10.17487/RFC4329, April -2006, <>. +4329 Scripting Media Types](https://www.rfc-editor.org/info/rfc4329) apply when +processing JavaScript or ECMAScript encoded within a JSON string. ## %appendix% Acknowledgments @@ -981,3 +862,6 @@ to the document. | Ben Hutton (*editor*) | Postman | | | [^6]: This section to be removed before leaving Internet-Draft status. + +[rfc3987]: https://www.rfc-editor.org/info/rfc3987 +[rfc8259]: https://www.rfc-editor.org/info/rfc8259 diff --git a/specs/output/jsonschema-validation-output-machines.md b/specs/output/jsonschema-validation-output-machines.md index b9d1787d..2043b7a4 100644 --- a/specs/output/jsonschema-validation-output-machines.md +++ b/specs/output/jsonschema-validation-output-machines.md @@ -20,10 +20,11 @@ absolute. ## Textual Format and Encoding JSON Schema output is defined using the JSON Schema data instance model as -described in [JSON Schema](#json-schema) "Instance Data Model". Implementations -MAY deviate from this in their internal modelling, 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. +described in [JSON Schema](../jsonschema-core.md) "Instance Data Model". +Implementations MAY deviate from this in their internal modelling, 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. ## Minimum Information @@ -35,7 +36,7 @@ contents of each output unit is specified by this section. Each output unit MUST contain the [validation result](#validation-result) for the associated subschema as well as the following information defined by -[JSON Schema](#json-schema) "Output Formatting": +[JSON Schema](../jsonschema-core.md) "Output Formatting": - Evaluation Path - Schema Location @@ -617,44 +618,3 @@ Output units which include annotations MUST NOT be pruned. Implementations which provide this behavior SHOULD provide configuration mechanisms appropriate for their users' needs. - -## References - -### Normative References - -#### \[RFC2119\] {#rfc2119} - -Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, -RFC 2119, DOI 10.17487/RFC2119, March 1997, -<>. - -#### \[RFC3986\] {#rfc3986} - -Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier -(URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, -<>. - -#### \[RFC3987\] {#rfc3987} - -Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC -3987, DOI 10.17487/RFC3987, January 2005, -<>. - -#### \[RFC6901\] {#rfc6901} - -Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation -(JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, -<>. - -#### \[RFC8259\] {#rfc8259} - -Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", -STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, -<>. - -#### \[json-schema\] {#json-schema} - -Wright, A., Andrews, H., Hutton, B., and G. Dennis, "JSON Schema: A Media Type -for Describing JSON Documents", Work in Progress, Internet-Draft, -draft-bhutton-json-schema-01, June 2022, -<>.