Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move hypermedia to loading section #860

Merged
merged 1 commit into from
Feb 21, 2020
Merged

Move hypermedia to loading section #860

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
356 changes: 180 additions & 176 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1619,7 +1619,7 @@
</section>
</section>

<section title="Loading Schemas and Instance Data">
<section title="Loading and Processing Schemas">
<t>
</t>
<section title="Loading a Schema">
Expand Down Expand Up @@ -1917,6 +1917,185 @@
</section>
</section>

<section title="Associating Instances and Schemas">

<section title="Usage for Hypermedia" anchor="hypermedia">

<t>
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
<xref target="RFC8288">Web linking</xref>.
</t>

<section title='Linking to a Schema'>
<t>
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
<xref target="W3C.REC-ldp-20150226">Linked Data Protocol 1.0, section 8.1</xref>.
</t>

<t>
In HTTP, such links can be attached to any response using the
<xref target="RFC8288">Link header</xref>. An example of such a header would be:
</t>

<figure>
<artwork>
<![CDATA[
Link: <https://example.com/my-hyper-schema#>; rel="describedby"
]]>
</artwork>
</figure>

</section>


<section title='Identifying a Schema via a Media Type Parameter' anchor="parameter">
<t>
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).
</t>
<t>
When using the media type application/schema-instance+json, the "schema"
parameter MUST be supplied.
</t>
<t>
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.
</t>
<t>
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.
</t>

<t>
In HTTP, the media-type parameter would be sent inside the Content-Type header:
</t>

<figure>
<artwork>
<![CDATA[
Content-Type: application/json;
schema="https://example.com/my-hyper-schema#"
]]>
</artwork>
</figure>

<t>
Multiple schemas are whitespace separated, and indicate that the
instance conforms to all of the listed schemas:
</t>

<figure>
<artwork>
<![CDATA[
Content-Type: application/json;
schema="https://example.com/alice https://example.com/bob"
]]>
</artwork>
</figure>

<t>
Media type parameters are also used in HTTP's Accept request header:
</t>

<figure>
<artwork>
<![CDATA[
Accept: application/json;
schema="https://example.com/qiang https://example.com/li",
application/json;
schema="https://example.com/kumar"
]]>
</artwork>
</figure>

<t>
As with Content-Type, multiple schema parameters in the same string
requests an instance that conforms to all of the listed schemas.
</t>

<t>
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.
</t>

<t>
<cref>
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?
</cref>
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:
</t>

<figure>
<artwork>
<![CDATA[
Link: </alice>;rel="schema", </bob>;rel="schema"
]]>
</artwork>
</figure>

</section>

<section title="Usage Over HTTP">
<t>
When used for hypermedia systems over a network,
<xref target="RFC7231">HTTP</xref> 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.
</t>
<t>
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.
</t>
<t>
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:
</t>
<figure>
<artwork>
<![CDATA[
User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
]]>
</artwork>
</figure>
<t>
Clients SHOULD be able to make requests with a "From" header so that server
operators can contact the owner of a potentially misbehaving script.
</t>
</section>

</section>

</section>

</section>

<section title="A Vocabulary for Applying Subschemas">
Expand Down Expand Up @@ -2893,181 +3072,6 @@ https://example.com/schemas/common#/$defs/count/minimum

</section>

<section title="Usage for Hypermedia" anchor="hypermedia">

<t>
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
<xref target="RFC8288">Web linking</xref>.
</t>

<section title='Linking to a Schema'>
<t>
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
<xref target="W3C.REC-ldp-20150226">Linked Data Protocol 1.0, section 8.1</xref>.
</t>

<t>
In HTTP, such links can be attached to any response using the
<xref target="RFC8288">Link header</xref>. An example of such a header would be:
</t>

<figure>
<artwork>
<![CDATA[
Link: <https://example.com/my-hyper-schema#>; rel="describedby"
]]>
</artwork>
</figure>

</section>


<section title='Identifying a Schema via a Media Type Parameter' anchor="parameter">
<t>
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).
</t>
<t>
When using the media type application/schema-instance+json, the "schema"
parameter MUST be supplied.
</t>
<t>
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.
</t>
<t>
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.
</t>

<t>
In HTTP, the media-type parameter would be sent inside the Content-Type header:
</t>

<figure>
<artwork>
<![CDATA[
Content-Type: application/json;
schema="https://example.com/my-hyper-schema#"
]]>
</artwork>
</figure>

<t>
Multiple schemas are whitespace separated, and indicate that the
instance conforms to all of the listed schemas:
</t>

<figure>
<artwork>
<![CDATA[
Content-Type: application/json;
schema="https://example.com/alice https://example.com/bob"
]]>
</artwork>
</figure>

<t>
Media type parameters are also used in HTTP's Accept request header:
</t>

<figure>
<artwork>
<![CDATA[
Accept: application/json;
schema="https://example.com/qiang https://example.com/li",
application/json;
schema="https://example.com/kumar"
]]>
</artwork>
</figure>

<t>
As with Content-Type, multiple schema parameters in the same string
requests an instance that conforms to all of the listed schemas.
</t>

<t>
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.
</t>

<t>
<cref>
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?
</cref>
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:
</t>

<figure>
<artwork>
<![CDATA[
Link: </alice>;rel="schema", </bob>;rel="schema"
]]>
</artwork>
</figure>

</section>

<section title="Usage Over HTTP">
<t>
When used for hypermedia systems over a network,
<xref target="RFC7231">HTTP</xref> 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.
</t>
<t>
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.
</t>
<t>
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:
</t>
<figure>
<artwork>
<![CDATA[
User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
]]>
</artwork>
</figure>
<t>
Clients SHOULD be able to make requests with a "From" header so that server
operators can contact the owner of a potentially misbehaving script.
</t>
</section>

</section>

<section title="Security Considerations" anchor="security">
<t>
Both schemas and instances are JSON values. As such, all security considerations
Expand Down