diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index e5ddec9d..089085bb 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -1619,7 +1619,7 @@
-
+
@@ -1917,6 +1917,185 @@
+
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+ In HTTP, such links can be attached to any response using the
+ Link header. An example of such a header would be:
+
+
+
+
+ ; rel="describedby"
+ ]]>
+
+
+
+
+
+
+
+
+ Media types MAY allow for a "schema" media type parameter, which gives
+ HTTP servers the ability to perform Content-Type Negotiation based on schema.
+ The media-type parameter MUST be a whitespace-separated list of URIs
+ (i.e. relative references are invalid).
+
+
+ When using the media type application/schema-instance+json, the "schema"
+ parameter MUST be supplied.
+
+
+ When using the media type application/schema+json, the "schema" parameter
+ MAY be supplied. If supplied, it SHOULD contain the same URI as identified
+ by the "$schema" keyword, and MAY contain additional URIs. The "$schema"
+ URI MUST be considered the schema's canonical meta-schema, regardless
+ of the presence of alternative or additional meta-schemas as a media type
+ parameter.
+
+
+ The schema URI is opaque and SHOULD NOT automatically be dereferenced.
+ If the implementation does not understand the semantics of the provided schema,
+ the implementation can instead follow the "describedby" links, if any, which may
+ provide information on how to handle the schema.
+ Since "schema" doesn't necessarily point to a network location, the
+ "describedby" relation is used for linking to a downloadable schema.
+ However, for simplicity, schema authors should make these URIs point to the same
+ resource when possible.
+
+
+
+ In HTTP, the media-type parameter would be sent inside the Content-Type header:
+
+
+
+
+
+
+
+
+
+ Multiple schemas are whitespace separated, and indicate that the
+ instance conforms to all of the listed schemas:
+
+
+
+
+
+
+
+
+
+ Media type parameters are also used in HTTP's Accept request header:
+
+
+
+
+
+
+
+
+
+ As with Content-Type, multiple schema parameters in the same string
+ requests an instance that conforms to all of the listed schemas.
+
+
+
+ Unlike Content-Type, Accept can contain multiple values to
+ indicate that the client can accept several media types.
+ In the above example, note that the two media types differ
+ only by their schema parameter values. This requests an
+ application/json representation that conforms to at least one
+ of the identified schemas.
+
+
+
+
+ This paragraph assumes that we can register a "schema" link relation.
+ Should we instead specify something like "tag:json-schema.org,2017:schema"
+ for now?
+
+ HTTP can also send the "schema" in a Link, though this may impact media-type
+ semantics and Content-Type negotiation if this replaces the media-type parameter
+ entirely:
+
+
+
+
+ ;rel="schema", ;rel="schema"
+ ]]>
+
+
+
+
+
+
+
+ When used for hypermedia systems over a network,
+ HTTP 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:
+
+
+
+
+
+
+
+ Clients SHOULD be able to make requests with a "From" header so that server
+ operators can contact the owner of a potentially misbehaving script.
+
+
+
+
+
+
+
@@ -2893,181 +3072,6 @@ https://example.com/schemas/common#/$defs/count/minimum
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
- In HTTP, such links can be attached to any response using the
- Link header. An example of such a header would be:
-
-
-
-
-; rel="describedby"
-]]>
-
-
-
-
-
-
-
-
- Media types MAY allow for a "schema" media type parameter, which gives
- HTTP servers the ability to perform Content-Type Negotiation based on schema.
- The media-type parameter MUST be a whitespace-separated list of URIs
- (i.e. relative references are invalid).
-
-
- When using the media type application/schema-instance+json, the "schema"
- parameter MUST be supplied.
-
-
- When using the media type application/schema+json, the "schema" parameter
- MAY be supplied. If supplied, it SHOULD contain the same URI as identified
- by the "$schema" keyword, and MAY contain additional URIs. The "$schema"
- URI MUST be considered the schema's canonical meta-schema, regardless
- of the presence of alternative or additional meta-schemas as a media type
- parameter.
-
-
- The schema URI is opaque and SHOULD NOT automatically be dereferenced.
- If the implementation does not understand the semantics of the provided schema,
- the implementation can instead follow the "describedby" links, if any, which may
- provide information on how to handle the schema.
- Since "schema" doesn't necessarily point to a network location, the
- "describedby" relation is used for linking to a downloadable schema.
- However, for simplicity, schema authors should make these URIs point to the same
- resource when possible.
-
-
-
- In HTTP, the media-type parameter would be sent inside the Content-Type header:
-
-
-
-
-
-
-
-
-
- Multiple schemas are whitespace separated, and indicate that the
- instance conforms to all of the listed schemas:
-
-
-
-
-
-
-
-
-
- Media type parameters are also used in HTTP's Accept request header:
-
-
-
-
-
-
-
-
-
- As with Content-Type, multiple schema parameters in the same string
- requests an instance that conforms to all of the listed schemas.
-
-
-
- Unlike Content-Type, Accept can contain multiple values to
- indicate that the client can accept several media types.
- In the above example, note that the two media types differ
- only by their schema parameter values. This requests an
- application/json representation that conforms to at least one
- of the identified schemas.
-
-
-
-
- This paragraph assumes that we can register a "schema" link relation.
- Should we instead specify something like "tag:json-schema.org,2017:schema"
- for now?
-
- HTTP can also send the "schema" in a Link, though this may impact media-type
- semantics and Content-Type negotiation if this replaces the media-type parameter
- entirely:
-
-
-
-
-;rel="schema", ;rel="schema"
-]]>
-
-
-
-
-
-
-
- When used for hypermedia systems over a network,
- HTTP 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:
-
-
-
-
-
-
-
- Clients SHOULD be able to make requests with a "From" header so that server
- operators can contact the owner of a potentially misbehaving script.
-
-
-
-
-
Both schemas and instances are JSON values. As such, all security considerations