Skip to content

Commit f64dbb4

Browse files
RelequestualRelequestual
authored
Merge pull request #860 from handrews/hypermedia
Move hypermedia to loading section
2 parents 56b45de + da5a29c commit f64dbb4

File tree

1 file changed

+180
-176
lines changed

1 file changed

+180
-176
lines changed

Diff for: ‎jsonschema-core.xml

+180-176
Original file line numberDiff line numberDiff line change
@@ -1619,7 +1619,7 @@
16191619
</section>
16201620
</section>
16211621

1622-
<section title="Loading Schemas and Instance Data">
1622+
<section title="Loading and Processing Schemas">
16231623
<t>
16241624
</t>
16251625
<section title="Loading a Schema">
@@ -1917,6 +1917,185 @@
19171917
</section>
19181918
</section>
19191919

1920+
<section title="Associating Instances and Schemas">
1921+
1922+
<section title="Usage for Hypermedia" anchor="hypermedia">
1923+
1924+
<t>
1925+
JSON has been adopted widely by HTTP servers for automated APIs and robots. This
1926+
section describes how to enhance processing of JSON documents in a more RESTful
1927+
manner when used with protocols that support media types and
1928+
<xref target="RFC8288">Web linking</xref>.
1929+
</t>
1930+
1931+
<section title='Linking to a Schema'>
1932+
<t>
1933+
It is RECOMMENDED that instances described by a schema provide a link to
1934+
a downloadable JSON Schema using the link relation "describedby", as defined by
1935+
<xref target="W3C.REC-ldp-20150226">Linked Data Protocol 1.0, section 8.1</xref>.
1936+
</t>
1937+
1938+
<t>
1939+
In HTTP, such links can be attached to any response using the
1940+
<xref target="RFC8288">Link header</xref>. An example of such a header would be:
1941+
</t>
1942+
1943+
<figure>
1944+
<artwork>
1945+
<![CDATA[
1946+
Link: <https://example.com/my-hyper-schema#>; rel="describedby"
1947+
]]>
1948+
</artwork>
1949+
</figure>
1950+
1951+
</section>
1952+
1953+
1954+
<section title='Identifying a Schema via a Media Type Parameter' anchor="parameter">
1955+
<t>
1956+
Media types MAY allow for a "schema" media type parameter, which gives
1957+
HTTP servers the ability to perform Content-Type Negotiation based on schema.
1958+
The media-type parameter MUST be a whitespace-separated list of URIs
1959+
(i.e. relative references are invalid).
1960+
</t>
1961+
<t>
1962+
When using the media type application/schema-instance+json, the "schema"
1963+
parameter MUST be supplied.
1964+
</t>
1965+
<t>
1966+
When using the media type application/schema+json, the "schema" parameter
1967+
MAY be supplied. If supplied, it SHOULD contain the same URI as identified
1968+
by the "$schema" keyword, and MAY contain additional URIs. The "$schema"
1969+
URI MUST be considered the schema's canonical meta-schema, regardless
1970+
of the presence of alternative or additional meta-schemas as a media type
1971+
parameter.
1972+
</t>
1973+
<t>
1974+
The schema URI is opaque and SHOULD NOT automatically be dereferenced.
1975+
If the implementation does not understand the semantics of the provided schema,
1976+
the implementation can instead follow the "describedby" links, if any, which may
1977+
provide information on how to handle the schema.
1978+
Since "schema" doesn't necessarily point to a network location, the
1979+
"describedby" relation is used for linking to a downloadable schema.
1980+
However, for simplicity, schema authors should make these URIs point to the same
1981+
resource when possible.
1982+
</t>
1983+
1984+
<t>
1985+
In HTTP, the media-type parameter would be sent inside the Content-Type header:
1986+
</t>
1987+
1988+
<figure>
1989+
<artwork>
1990+
<![CDATA[
1991+
Content-Type: application/json;
1992+
schema="https://example.com/my-hyper-schema#"
1993+
]]>
1994+
</artwork>
1995+
</figure>
1996+
1997+
<t>
1998+
Multiple schemas are whitespace separated, and indicate that the
1999+
instance conforms to all of the listed schemas:
2000+
</t>
2001+
2002+
<figure>
2003+
<artwork>
2004+
<![CDATA[
2005+
Content-Type: application/json;
2006+
schema="https://example.com/alice https://example.com/bob"
2007+
]]>
2008+
</artwork>
2009+
</figure>
2010+
2011+
<t>
2012+
Media type parameters are also used in HTTP's Accept request header:
2013+
</t>
2014+
2015+
<figure>
2016+
<artwork>
2017+
<![CDATA[
2018+
Accept: application/json;
2019+
schema="https://example.com/qiang https://example.com/li",
2020+
application/json;
2021+
schema="https://example.com/kumar"
2022+
]]>
2023+
</artwork>
2024+
</figure>
2025+
2026+
<t>
2027+
As with Content-Type, multiple schema parameters in the same string
2028+
requests an instance that conforms to all of the listed schemas.
2029+
</t>
2030+
2031+
<t>
2032+
Unlike Content-Type, Accept can contain multiple values to
2033+
indicate that the client can accept several media types.
2034+
In the above example, note that the two media types differ
2035+
only by their schema parameter values. This requests an
2036+
application/json representation that conforms to at least one
2037+
of the identified schemas.
2038+
</t>
2039+
2040+
<t>
2041+
<cref>
2042+
This paragraph assumes that we can register a "schema" link relation.
2043+
Should we instead specify something like "tag:json-schema.org,2017:schema"
2044+
for now?
2045+
</cref>
2046+
HTTP can also send the "schema" in a Link, though this may impact media-type
2047+
semantics and Content-Type negotiation if this replaces the media-type parameter
2048+
entirely:
2049+
</t>
2050+
2051+
<figure>
2052+
<artwork>
2053+
<![CDATA[
2054+
Link: </alice>;rel="schema", </bob>;rel="schema"
2055+
]]>
2056+
</artwork>
2057+
</figure>
2058+
2059+
</section>
2060+
2061+
<section title="Usage Over HTTP">
2062+
<t>
2063+
When used for hypermedia systems over a network,
2064+
<xref target="RFC7231">HTTP</xref> is frequently the protocol of choice for
2065+
distributing schemas. Misbehaving clients can pose problems for server
2066+
maintainers if they pull a schema over the network more frequently than
2067+
necessary, when it's instead possible to cache a schema for a long period of
2068+
time.
2069+
</t>
2070+
<t>
2071+
HTTP servers SHOULD set long-lived caching headers on JSON Schemas.
2072+
HTTP clients SHOULD observe caching headers and not re-request documents within
2073+
their freshness period.
2074+
Distributed systems SHOULD make use of a shared cache and/or caching proxy.
2075+
</t>
2076+
<t>
2077+
Clients SHOULD set or prepend a User-Agent header specific to the JSON Schema
2078+
implementation or software product. Since symbols are listed in decreasing order
2079+
of significance, the JSON Schema library name/version should precede the more
2080+
generic HTTP library name (if any). For example:
2081+
</t>
2082+
<figure>
2083+
<artwork>
2084+
<![CDATA[
2085+
User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
2086+
]]>
2087+
</artwork>
2088+
</figure>
2089+
<t>
2090+
Clients SHOULD be able to make requests with a "From" header so that server
2091+
operators can contact the owner of a potentially misbehaving script.
2092+
</t>
2093+
</section>
2094+
2095+
</section>
2096+
2097+
</section>
2098+
19202099
</section>
19212100

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

28943073
</section>
28953074

2896-
<section title="Usage for Hypermedia" anchor="hypermedia">
2897-
2898-
<t>
2899-
JSON has been adopted widely by HTTP servers for automated APIs and robots. This
2900-
section describes how to enhance processing of JSON documents in a more RESTful
2901-
manner when used with protocols that support media types and
2902-
<xref target="RFC8288">Web linking</xref>.
2903-
</t>
2904-
2905-
<section title='Linking to a Schema'>
2906-
<t>
2907-
It is RECOMMENDED that instances described by a schema provide a link to
2908-
a downloadable JSON Schema using the link relation "describedby", as defined by
2909-
<xref target="W3C.REC-ldp-20150226">Linked Data Protocol 1.0, section 8.1</xref>.
2910-
</t>
2911-
2912-
<t>
2913-
In HTTP, such links can be attached to any response using the
2914-
<xref target="RFC8288">Link header</xref>. An example of such a header would be:
2915-
</t>
2916-
2917-
<figure>
2918-
<artwork>
2919-
<![CDATA[
2920-
Link: <https://example.com/my-hyper-schema#>; rel="describedby"
2921-
]]>
2922-
</artwork>
2923-
</figure>
2924-
2925-
</section>
2926-
2927-
2928-
<section title='Identifying a Schema via a Media Type Parameter' anchor="parameter">
2929-
<t>
2930-
Media types MAY allow for a "schema" media type parameter, which gives
2931-
HTTP servers the ability to perform Content-Type Negotiation based on schema.
2932-
The media-type parameter MUST be a whitespace-separated list of URIs
2933-
(i.e. relative references are invalid).
2934-
</t>
2935-
<t>
2936-
When using the media type application/schema-instance+json, the "schema"
2937-
parameter MUST be supplied.
2938-
</t>
2939-
<t>
2940-
When using the media type application/schema+json, the "schema" parameter
2941-
MAY be supplied. If supplied, it SHOULD contain the same URI as identified
2942-
by the "$schema" keyword, and MAY contain additional URIs. The "$schema"
2943-
URI MUST be considered the schema's canonical meta-schema, regardless
2944-
of the presence of alternative or additional meta-schemas as a media type
2945-
parameter.
2946-
</t>
2947-
<t>
2948-
The schema URI is opaque and SHOULD NOT automatically be dereferenced.
2949-
If the implementation does not understand the semantics of the provided schema,
2950-
the implementation can instead follow the "describedby" links, if any, which may
2951-
provide information on how to handle the schema.
2952-
Since "schema" doesn't necessarily point to a network location, the
2953-
"describedby" relation is used for linking to a downloadable schema.
2954-
However, for simplicity, schema authors should make these URIs point to the same
2955-
resource when possible.
2956-
</t>
2957-
2958-
<t>
2959-
In HTTP, the media-type parameter would be sent inside the Content-Type header:
2960-
</t>
2961-
2962-
<figure>
2963-
<artwork>
2964-
<![CDATA[
2965-
Content-Type: application/json;
2966-
schema="https://example.com/my-hyper-schema#"
2967-
]]>
2968-
</artwork>
2969-
</figure>
2970-
2971-
<t>
2972-
Multiple schemas are whitespace separated, and indicate that the
2973-
instance conforms to all of the listed schemas:
2974-
</t>
2975-
2976-
<figure>
2977-
<artwork>
2978-
<![CDATA[
2979-
Content-Type: application/json;
2980-
schema="https://example.com/alice https://example.com/bob"
2981-
]]>
2982-
</artwork>
2983-
</figure>
2984-
2985-
<t>
2986-
Media type parameters are also used in HTTP's Accept request header:
2987-
</t>
2988-
2989-
<figure>
2990-
<artwork>
2991-
<![CDATA[
2992-
Accept: application/json;
2993-
schema="https://example.com/qiang https://example.com/li",
2994-
application/json;
2995-
schema="https://example.com/kumar"
2996-
]]>
2997-
</artwork>
2998-
</figure>
2999-
3000-
<t>
3001-
As with Content-Type, multiple schema parameters in the same string
3002-
requests an instance that conforms to all of the listed schemas.
3003-
</t>
3004-
3005-
<t>
3006-
Unlike Content-Type, Accept can contain multiple values to
3007-
indicate that the client can accept several media types.
3008-
In the above example, note that the two media types differ
3009-
only by their schema parameter values. This requests an
3010-
application/json representation that conforms to at least one
3011-
of the identified schemas.
3012-
</t>
3013-
3014-
<t>
3015-
<cref>
3016-
This paragraph assumes that we can register a "schema" link relation.
3017-
Should we instead specify something like "tag:json-schema.org,2017:schema"
3018-
for now?
3019-
</cref>
3020-
HTTP can also send the "schema" in a Link, though this may impact media-type
3021-
semantics and Content-Type negotiation if this replaces the media-type parameter
3022-
entirely:
3023-
</t>
3024-
3025-
<figure>
3026-
<artwork>
3027-
<![CDATA[
3028-
Link: </alice>;rel="schema", </bob>;rel="schema"
3029-
]]>
3030-
</artwork>
3031-
</figure>
3032-
3033-
</section>
3034-
3035-
<section title="Usage Over HTTP">
3036-
<t>
3037-
When used for hypermedia systems over a network,
3038-
<xref target="RFC7231">HTTP</xref> is frequently the protocol of choice for
3039-
distributing schemas. Misbehaving clients can pose problems for server
3040-
maintainers if they pull a schema over the network more frequently than
3041-
necessary, when it's instead possible to cache a schema for a long period of
3042-
time.
3043-
</t>
3044-
<t>
3045-
HTTP servers SHOULD set long-lived caching headers on JSON Schemas.
3046-
HTTP clients SHOULD observe caching headers and not re-request documents within
3047-
their freshness period.
3048-
Distributed systems SHOULD make use of a shared cache and/or caching proxy.
3049-
</t>
3050-
<t>
3051-
Clients SHOULD set or prepend a User-Agent header specific to the JSON Schema
3052-
implementation or software product. Since symbols are listed in decreasing order
3053-
of significance, the JSON Schema library name/version should precede the more
3054-
generic HTTP library name (if any). For example:
3055-
</t>
3056-
<figure>
3057-
<artwork>
3058-
<![CDATA[
3059-
User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
3060-
]]>
3061-
</artwork>
3062-
</figure>
3063-
<t>
3064-
Clients SHOULD be able to make requests with a "From" header so that server
3065-
operators can contact the owner of a potentially misbehaving script.
3066-
</t>
3067-
</section>
3068-
3069-
</section>
3070-
30713075
<section title="Security Considerations" anchor="security">
30723076
<t>
30733077
Both schemas and instances are JSON values. As such, all security considerations

0 commit comments

Comments
 (0)