Skip to content

Commit e53bb44

Browse files
handrewshandrews
authored
Merge pull request #405 from handrews/instance
Describe application/schema-instance+json
2 parents 029de3f + 7dc6b34 commit e53bb44

File tree

1 file changed

+189
-101
lines changed

1 file changed

+189
-101
lines changed

‎jsonschema-core.xml

Lines changed: 189 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,10 @@
5050
for describing the structure of JSON data.
5151
JSON Schema asserts what a JSON document must look like,
5252
ways to extract information from it,
53-
and how to interact with it,
54-
ideal for annotating existing JSON APIs that would not otherwise have hypermedia
55-
controls or be machine-readable.
53+
and how to interact with it.
54+
The "application/schema-instance+json" media type provides additional
55+
feature-rich integration with "application/schema+json" beyond what can be offered
56+
for "application/json" documents.
5657
</t>
5758
</abstract>
5859
<note title="Note to Readers">
@@ -110,6 +111,8 @@
110111
<t>
111112
This document proposes a new media type "application/schema+json" to identify a JSON
112113
Schema for describing JSON data.
114+
It also proposes a further optional media type, "application/schema-instance+json",
115+
to provide additional integration features.
113116
JSON Schemas are themselves JSON documents.
114117
This, and related specifications, define keywords allowing authors to describe JSON
115118
data in several ways.
@@ -164,64 +167,96 @@
164167

165168
<section title="Instance">
166169
<t>
167-
JSON Schema interprets documents according to a data model. A JSON value
168-
interpreted according to this data model is called an "instance".
170+
A JSON document to which a schema is applied is known as an "instance".
169171
</t>
170-
<t>
171-
An instance has one of six primitive types, and a range of possible values
172-
depending on the type:
173172

174-
<list style="hanging">
175-
<t hangText="null">A JSON "null" production</t>
176-
<t hangText="boolean">A "true" or "false" value, from the JSON "true" or "false" productions</t>
177-
<t hangText="object">An unordered set of properties mapping a string to an instance, from the JSON "object" production</t>
178-
<t hangText="array">An ordered list of instances, from the JSON "array" production</t>
179-
<t hangText="number">An arbitrary-precision, base-10 decimal number value, from the JSON "number" production</t>
180-
<t hangText="string">A string of Unicode code points, from the JSON "string" production</t>
181-
</list>
182-
</t>
183-
<t>
184-
Whitespace and formatting concerns are thus outside the scope of JSON Schema.
185-
</t>
186-
<t>
187-
Since an object cannot have two properties with the same key, behavior for a
188-
JSON document that tries to define two properties (the "member" production) with
189-
the same key (the "string" production) in a single object is undefined.
190-
</t>
191-
</section>
173+
<section title="Instance data model">
174+
<t>
175+
JSON Schema interprets documents according to a data model. A JSON value
176+
interpreted according to this data model is called an "instance".
177+
</t>
178+
<t>
179+
An instance has one of six primitive types, and a range of possible values
180+
depending on the type:
181+
182+
<list style="hanging">
183+
<t hangText="null">A JSON "null" production</t>
184+
<t hangText="boolean">A "true" or "false" value, from the JSON "true" or "false" productions</t>
185+
<t hangText="object">An unordered set of properties mapping a string to an instance, from the JSON "object" production</t>
186+
<t hangText="array">An ordered list of instances, from the JSON "array" production</t>
187+
<t hangText="number">An arbitrary-precision, base-10 decimal number value, from the JSON "number" production</t>
188+
<t hangText="string">A string of Unicode code points, from the JSON "string" production</t>
189+
</list>
190+
</t>
191+
<t>
192+
Whitespace and formatting concerns are thus outside the scope of JSON Schema.
193+
</t>
194+
<t>
195+
Since an object cannot have two properties with the same key, behavior for a
196+
JSON document that tries to define two properties (the "member" production) with
197+
the same key (the "string" production) in a single object is undefined.
198+
</t>
199+
</section>
192200

193-
<section title="Instance equality">
194-
<t>
195-
Two JSON instances are said to be equal if and only if they are of the same type
196-
and have the same value according to the data model. Specifically, this means:
201+
<section title="Instance media types">
202+
<t>
203+
JSON Schema is designed to fully work with "application/json" documents,
204+
as well as media types using the "+json" structured syntax suffix.
205+
</t>
206+
<t>
207+
Some functionality that is useful for working with schemas is
208+
defined by each media type, namely media type parameters and
209+
URI fragment identifier syntax and semantics. These features are
210+
useful in content negotiation and in caclulating URIs for specific
211+
locations within an instance, respectively.
212+
</t>
213+
<t>
214+
This specification defines the "application/schema-instance+json"
215+
media type in order to allow instance authors to take full advantage
216+
of parameters and fragment identifiers for these purposes.
217+
</t>
218+
</section>
197219

198-
<list>
199-
<t>both are null; or</t>
200-
<t>both are true; or</t>
201-
<t>both are false; or</t>
202-
<t>both are strings, and are the same codepoint-for-codepoint; or</t>
203-
<t>both are numbers, and have the same mathematical value; or</t>
204-
<t>both are arrays, and have an equal value item-for-item; or</t>
205-
<t>both are objects, and each property in one has exactly one property with
206-
a key equal to the other's, and that other property has an equal
207-
value.</t>
208-
</list>
209-
</t>
210-
<t>
211-
Implied in this definition is that arrays must be the same length,
212-
objects must have the same number of members,
213-
properties in objects are unordered,
214-
there is no way to define multiple properties with the same key,
215-
and mere formatting differences (indentation, placement of commas, trailing
216-
zeros) are insignificant.
217-
</t>
220+
<section title="Instance equality">
221+
<t>
222+
Two JSON instances are said to be equal if and only if they are of the same type
223+
and have the same value according to the data model. Specifically, this means:
224+
225+
<list>
226+
<t>both are null; or</t>
227+
<t>both are true; or</t>
228+
<t>both are false; or</t>
229+
<t>both are strings, and are the same codepoint-for-codepoint; or</t>
230+
<t>both are numbers, and have the same mathematical value; or</t>
231+
<t>both are arrays, and have an equal value item-for-item; or</t>
232+
<t>both are objects, and each property in one has exactly one property with
233+
a key equal to the other's, and that other property has an equal
234+
value.</t>
235+
</list>
236+
</t>
237+
<t>
238+
Implied in this definition is that arrays must be the same length,
239+
objects must have the same number of members,
240+
properties in objects are unordered,
241+
there is no way to define multiple properties with the same key,
242+
and mere formatting differences (indentation, placement of commas, trailing
243+
zeros) are insignificant.
244+
</t>
245+
</section>
218246
</section>
219247

220248
<section title="JSON Schema documents">
221249
<t>
222250
A JSON Schema document, or simply a schema, is a JSON document used to describe
223251
an instance.
224-
A schema is itself interpreted as an instance.
252+
A schema is itself interpreted as an instance, but SHOULD always be given
253+
the media type "application/schema+json" rather than
254+
"application/schema-instance+json". The "application/schema+json" media
255+
type is defined to offer a superset of the media type parameter and
256+
fragment identifier syntax and semantics provided by
257+
"application/schema-instance+json".
258+
</t>
259+
<t>
225260
A JSON Schema MUST be an object or a boolean.
226261
</t>
227262
<t>
@@ -248,17 +283,16 @@
248283
<t>
249284
An empty schema is a JSON Schema with no properties, or only unknown properties.
250285
</t>
251-
</section>
252286

253-
<section title="Root schema and subschemas">
254-
<t>
255-
The root schema is the schema that comprises the entire JSON document in question.
256-
</t>
257-
<t>
258-
Some keywords take schemas themselves, allowing JSON Schemas to be nested:
259-
</t>
260-
<figure>
261-
<artwork>
287+
<section title="Root schema and subschemas">
288+
<t>
289+
The root schema is the schema that comprises the entire JSON document in question.
290+
</t>
291+
<t>
292+
Some keywords take schemas themselves, allowing JSON Schemas to be nested:
293+
</t>
294+
<figure>
295+
<artwork>
262296
<![CDATA[
263297
{
264298
"title": "root",
@@ -267,15 +301,16 @@
267301
}
268302
}
269303
]]>
270-
</artwork>
271-
</figure>
272-
<t>
273-
In this example document, the schema titled "array item" is a subschema,
274-
and the schema titled "root" is the root schema.
275-
</t>
276-
<t>
277-
As with the root schema, a subschema is either an object or a boolean.
278-
</t>
304+
</artwork>
305+
</figure>
306+
<t>
307+
In this example document, the schema titled "array item" is a subschema,
308+
and the schema titled "root" is the root schema.
309+
</t>
310+
<t>
311+
As with the root schema, a subschema is either an object or a boolean.
312+
</t>
313+
</section>
279314
</section>
280315

281316
</section>
@@ -291,22 +326,27 @@
291326
<t>
292327
Additionally, the "application/schema+json" media type supports two
293328
fragment identifier structures: plain names and JSON Pointers.
329+
The "application/schema-instance+json" media type supports one
330+
fragment identifier structure: JSON Pointers.
331+
</t>
332+
<t>
294333
The use of JSON Pointers as URI fragment identifiers is described in
295334
<xref target="RFC6901">RFC 6901</xref>.
296-
Fragment identifiers matching the JSON Pointer syntax, including
297-
the empty string, MUST be interpreted as JSON Pointer fragment
298-
identifiers.
335+
For "application/schema+json", which supports two fragment identifier syntaxes,
336+
fragment identifiers matching the JSON Pointer syntax, including the empty string,
337+
MUST be interpreted as JSON Pointer fragment identifiers.
299338
</t>
300339
<t>
301340
Per the W3C's
302341
<xref target="W3C.WD-fragid-best-practices-20121025">best practices for fragment identifiers</xref>,
303-
plain name fragment identifiers are reserved for referencing
342+
plain name fragment identifiers in "application/schema+json" are reserved for referencing
304343
locally named schemas. All fragment identifiers that do
305344
not match the JSON Pointer syntax MUST be interpreted as
306345
plain name fragment identifiers.
307346
</t>
308347
<t>
309-
Defining and referencing a plain name fragment identifier are specified
348+
Defining and referencing a plain name fragment identifier within an
349+
"application/schema+json" document are specified
310350
in the <xref target="id-keyword">"$id" keyword</xref> section.
311351
</t>
312352
<t>
@@ -377,6 +417,10 @@
377417
(containing a scheme) and this URI MUST be normalized.
378418
The current schema MUST be valid against the meta-schema identified by this URI.
379419
</t>
420+
<t>
421+
If this URI identifies a retrievable resource, that resource SHOULD be of
422+
media type "application/schema+json".
423+
</t>
380424
<t>
381425
The "$schema" keyword SHOULD be used in a root schema.
382426
It MUST NOT appear in subschemas.
@@ -783,34 +827,78 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
783827
</section>
784828

785829
<section title="IANA Considerations">
786-
<t>
787-
The proposed MIME media type for JSON Schema is defined as follows:
830+
<section title="application/schema+json">
831+
<t>
832+
The proposed MIME media type for JSON Schema is defined as follows:
788833

789-
<list>
790-
<t>Type name: application</t>
791-
<t>Subtype name: schema+json</t>
792-
<t>Required parameters: N/A</t>
793-
<t>
794-
Encoding considerations: Encoding considerations are
795-
identical to those specified for the "application/json"
796-
media type. See <xref target="RFC7159">JSON</xref>.
797-
</t>
798-
<t>
799-
Security considerations: See Section
800-
<xref target="security" format="counter"></xref> above.
801-
</t>
802-
<t>
803-
Interoperability considerations: See Sections
804-
<xref target="language" format="counter"></xref> and
805-
<xref target="integers" format="counter"></xref> above.
806-
</t>
807-
<t>
808-
Fragment identifier considerations: See Section
809-
<xref target="fragments" format="counter"></xref>
810-
</t>
811-
</list>
812-
</t>
834+
<list>
835+
<t>Type name: application</t>
836+
<t>Subtype name: schema+json</t>
837+
<t>Required parameters: N/A</t>
838+
<t>
839+
Encoding considerations: Encoding considerations are
840+
identical to those specified for the "application/json"
841+
media type. See <xref target="RFC7159">JSON</xref>.
842+
</t>
843+
<t>
844+
Security considerations: See Section
845+
<xref target="security" format="counter"></xref> above.
846+
</t>
847+
<t>
848+
Interoperability considerations: See Sections
849+
<xref target="language" format="counter"></xref> and
850+
<xref target="integers" format="counter"></xref> above.
851+
</t>
852+
<t>
853+
Fragment identifier considerations: See Section
854+
<xref target="fragments" format="counter"></xref>
855+
</t>
856+
</list>
857+
</t>
858+
</section>
859+
<section title="application/schema-instance+json">
860+
<t>
861+
The proposed MIME media type for JSON Schema Instances that require
862+
a JSON Schema-specific media type is defined as follows:
813863

864+
<list>
865+
<t>Type name: application</t>
866+
<t>Subtype name: schema-instance+json</t>
867+
<t>
868+
Required parameters:
869+
<list style="hanging">
870+
<t hangText="schema">
871+
A non-empty list of space-separated URIs, each identifying
872+
a JSON Schema resource. The instance SHOULD successfully
873+
validate against at least one of these schemas.
874+
Non-validating schemas MAY be included for purposes such
875+
as allowing clients to make use of older versions of a schema
876+
as long as the runtime instance validates against that
877+
older version.
878+
</t>
879+
</list>
880+
</t>
881+
<t>
882+
Encoding considerations: Encoding considerations are
883+
identical to those specified for the "application/json"
884+
media type. See <xref target="RFC7159">JSON</xref>.
885+
</t>
886+
<t>
887+
Security considerations: See Section
888+
<xref target="security" format="counter"></xref> above.
889+
</t>
890+
<t>
891+
Interoperability considerations: See Sections
892+
<xref target="language" format="counter"></xref> and
893+
<xref target="integers" format="counter"></xref> above.
894+
</t>
895+
<t>
896+
Fragment identifier considerations: See Section
897+
<xref target="fragments" format="counter"></xref>
898+
</t>
899+
</list>
900+
</t>
901+
</section>
814902
</section>
815903
</middle>
816904

0 commit comments

Comments
 (0)