source: trip-planner-front/node_modules/json-schema/draft-zyp-json-schema-04.xml@ e29cc2e

Last change on this file since e29cc2e was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit
  • Property mode set to 100644
File size: 46.1 KB
Line 
1<?xml version="1.0" encoding="US-ASCII"?>
2<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
3<!ENTITY rfc4627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
4<!ENTITY rfc3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
5<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
6<!ENTITY rfc4287 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml">
7<!ENTITY rfc2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
8<!ENTITY rfc3339 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">
9<!ENTITY rfc2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
10<!ENTITY rfc5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">
11<!ENTITY iddiscovery SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.hammer-discovery.xml">
12<!ENTITY uritemplate SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.gregorio-uritemplate.xml">
13<!ENTITY linkheader SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.nottingham-http-link-header.xml">
14<!ENTITY html401 SYSTEM "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-html401-19991224.xml">
15<!ENTITY css21 SYSTEM "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.CR-CSS21-20070719.xml">
16]>
17<?rfc toc="yes"?>
18<?rfc symrefs="yes"?>
19<?rfc compact="yes"?>
20<?rfc subcompact="no"?>
21<?rfc strict="no"?>
22<?rfc rfcedstyle="yes"?>
23<rfc category="info" docName="draft-zyp-json-schema-04" ipr="trust200902">
24 <front>
25 <title abbrev="JSON Schema Media Type">A JSON Media Type for Describing the Structure and Meaning of JSON Documents</title>
26
27 <author fullname="Kris Zyp" initials="K" role="editor" surname="Zyp">
28 <organization>SitePen (USA)</organization>
29 <address>
30 <postal>
31 <street>530 Lytton Avenue</street>
32 <city>Palo Alto, CA 94301</city>
33 <country>USA</country>
34 </postal>
35 <phone>+1 650 968 8787</phone>
36 <email>kris@sitepen.com</email>
37 </address>
38 </author>
39
40 <author fullname="Gary Court" initials="G" surname="Court">
41 <address>
42 <postal>
43 <street></street>
44 <city>Calgary, AB</city>
45 <country>Canada</country>
46 </postal>
47 <email>gary.court@gmail.com</email>
48 </address>
49 </author>
50
51 <date year="2011" />
52 <workgroup>Internet Engineering Task Force</workgroup>
53 <keyword>JSON</keyword>
54 <keyword>Schema</keyword>
55 <keyword>JavaScript</keyword>
56 <keyword>Object</keyword>
57 <keyword>Notation</keyword>
58 <keyword>Hyper Schema</keyword>
59 <keyword>Hypermedia</keyword>
60
61 <abstract>
62 <t>
63 JSON (JavaScript Object Notation) Schema defines the media type "application/schema+json",
64 a JSON based format for defining the structure of JSON data. JSON Schema provides a contract for what JSON
65 data is required for a given application and how to interact with it. JSON
66 Schema is intended to define validation, documentation, hyperlink
67 navigation, and interaction control of JSON data.
68 </t>
69 </abstract>
70 </front>
71
72 <middle>
73 <section title="Introduction">
74 <t>
75 JSON (JavaScript Object Notation) Schema is a JSON media type for defining
76 the structure of JSON data. JSON Schema provides a contract for what JSON
77 data is required for a given application and how to interact with it. JSON
78 Schema is intended to define validation, documentation, hyperlink
79 navigation, and interaction control of JSON data.
80 </t>
81 </section>
82
83 <section title="Conventions and Terminology">
84 <t>
85 <!-- The text in this section has been copied from the official boilerplate,
86 and should not be modified.-->
87
88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
89 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
90 interpreted as described in <xref target="RFC2119">RFC 2119</xref>.
91 </t>
92
93 <t>
94 The terms "JSON", "JSON text", "JSON value", "member", "element", "object",
95 "array", "number", "string", "boolean", "true", "false", and "null" in this
96 document are to be interpreted as defined in <xref target="RFC4627">RFC 4627</xref>.
97 </t>
98
99 <t>
100 This specification also uses the following defined terms:
101
102 <list style="hanging">
103 <t hangText="schema">A JSON Schema object.</t>
104 <t hangText="instance">Equivalent to "JSON value" as defined in <xref target="RFC4627">RFC 4627</xref>.</t>
105 <t hangText="property">Equivalent to "member" as defined in <xref target="RFC4627">RFC 4627</xref>.</t>
106 <t hangText="item">Equivalent to "element" as defined in <xref target="RFC4627">RFC 4627</xref>.</t>
107 <t hangText="attribute">A property of a JSON Schema object.</t>
108 </list>
109 </t>
110 </section>
111
112 <section title="Overview">
113 <t>
114 JSON Schema defines the media type "application/schema+json" for
115 describing the structure of JSON text. JSON Schemas are also written in JSON and includes facilities
116 for describing the structure of JSON in terms of
117 allowable values, descriptions, and interpreting relations with other resources.
118 </t>
119 <t>
120 This document is organized into several separate definitions. The first
121 definition is the core schema specification. This definition is primary
122 concerned with describing a JSON structure and specifying valid elements
123 in the structure. The second definition is the Hyper Schema specification
124 which is intended to define elements in a structure that can be interpreted as
125 hyperlinks.
126 Hyper Schema builds on JSON Schema to describe the hyperlink structure of
127 JSON values. This allows user agents to be able to successfully navigate
128 documents containing JSON based on their schemas.
129 </t>
130 <t>
131 Cumulatively JSON Schema acts as meta-JSON that can be used to define the
132 required type and constraints on JSON values, as well as define the meaning
133 of the JSON values for the purpose of describing a resource and determining
134 hyperlinks within the representation.
135 </t>
136 <figure>
137 <preamble>An example JSON Schema that describes products might look like:</preamble>
138 <artwork>
139<![CDATA[
140{
141 "title": "Product",
142 "properties": {
143 "id": {
144 "title": "Product Identifier",
145 "type": "number"
146 },
147 "name": {
148 "title": "Product Name",
149 "type": "string"
150 },
151 "price": {
152 "type": "number",
153 "minimum": 0
154 },
155 "tags": {
156 "type": "array",
157 "items": {
158 "type": "string"
159 }
160 }
161 },
162 "required" : ["id", "name", "price"],
163 "links": [{
164 "rel": "full",
165 "href": "{id}"
166 }, {
167 "rel": "comments",
168 "href": "comments/?id={id}"
169 }]
170}
171]]>
172 </artwork>
173 <postamble>
174 This schema defines the properties of the instance,
175 the required properties (id, name, and price), as well as an optional
176 property (tags). This also defines the link relations of the instance.
177 </postamble>
178 </figure>
179
180 <section title="Design Considerations">
181 <t>
182 The JSON Schema media type does not attempt to dictate the structure of JSON
183 values that contain data, but rather provides a separate format
184 for flexibly communicating how a JSON value should be
185 interpreted and validated, such that user agents can properly understand
186 acceptable structures and extrapolate hyperlink information
187 from the JSON. It is acknowledged that JSON values come
188 in a variety of structures, and JSON is unique in that the structure
189 of stored data structures often prescribes a non-ambiguous definite
190 JSON representation. Attempting to force a specific structure is generally
191 not viable, and therefore JSON Schema allows for a great flexibility
192 in the structure of the JSON data that it describes.
193 </t>
194 <t>
195 This specification is protocol agnostic.
196 The underlying protocol (such as HTTP) should sufficiently define the
197 semantics of the client-server interface, the retrieval of resource
198 representations linked to by JSON representations, and modification of
199 those resources. The goal of this
200 format is to sufficiently describe JSON structures such that one can
201 utilize existing information available in existing JSON
202 representations from a large variety of services that leverage a representational state transfer
203 architecture using existing protocols.
204 </t>
205 </section>
206 </section>
207
208 <section title="Schema/Instance Association">
209 <t>
210 JSON values are correlated to their schema by the "describedby"
211 relation, where the schema is the target of the relation.
212 JSON values MUST be of the "application/json" media type or
213 any other subtype. Consequently, dictating how a JSON value should
214 specify the relation to the schema is beyond the normative scope
215 of this document since this document specifically defines the JSON
216 Schema media type, and no other. It is RECOMMNENDED that JSON values
217 specify their schema so that user agents can interpret the instance
218 and retain the self-descriptive characteristics. This avoides the need for out-of-band information about
219 instance data. Two approaches are recommended for declaring the
220 relation to the schema that describes the meaning of a JSON instance's (or collection
221 of instances) structure. A MIME type parameter named
222 "profile" or a relation of "describedby" (which could be specified by a Link header) may be used:
223
224 <figure>
225 <artwork>
226<![CDATA[
227Content-Type: application/my-media-type+json;
228 profile=http://example.com/my-hyper-schema
229]]>
230 </artwork>
231 </figure>
232
233 or if the content is being transferred by a protocol (such as HTTP) that
234 provides headers, a Link header can be used:
235
236 <figure>
237 <artwork>
238<![CDATA[
239Link: <http://example.com/my-hyper-schema>; rel="describedby"
240]]>
241 </artwork>
242 </figure>
243
244 Instances MAY specify multiple schemas, to indicate all the schemas that
245 are applicable to the data, and the data SHOULD be valid by all the schemas.
246 The instance data MAY have multiple schemas
247 that it is described by (the instance data SHOULD be valid for those schemas).
248 Or if the document is a collection of instances, the collection MAY contain
249 instances from different schemas. The mechanism for referencing a schema is
250 determined by the media type of the instance (if it provides a method for
251 referencing schemas).
252 </t>
253
254 <section title="Self-Descriptive Schema">
255 <t>
256 JSON Schemas can themselves be described using JSON Schemas.
257 A self-describing JSON Schema for the core JSON Schema can
258 be found at <eref target="http://json-schema.org/schema">http://json-schema.org/schema</eref> for the latest version or
259 <eref target="http://json-schema.org/draft-04/schema">http://json-schema.org/draft-04/schema</eref> for the draft-04 version. The hyper schema
260 self-description can be found at <eref target="http://json-schema.org/hyper-schema">http://json-schema.org/hyper-schema</eref>
261 or <eref target="http://json-schema.org/draft-04/hyper-schema">http://json-schema.org/draft-04/hyper-schema</eref>. All schemas
262 used within a protocol with a media type specified SHOULD include a MIME parameter that refers to the self-descriptive
263 hyper schema or another schema that extends this hyper schema:
264
265 <figure>
266 <artwork>
267<![CDATA[
268Content-Type: application/json;
269 profile=http://json-schema.org/draft-04/hyper-schema
270]]>
271 </artwork>
272 </figure>
273 </t>
274 </section>
275 </section>
276
277 <section title="Core Schema Definition">
278 <t>
279 A JSON Schema is a JSON object that defines various attributes
280 (including usage and valid values) of a JSON value. JSON
281 Schema has recursive capabilities; there are a number of elements
282 in the structure that allow for nested JSON Schemas.
283 </t>
284
285 <figure>
286 <preamble>An example JSON Schema could look like:</preamble>
287 <artwork>
288<![CDATA[
289{
290 "description": "A person",
291 "type": "object",
292
293 "properties": {
294 "name": {
295 "type": "string"
296 },
297 "age": {
298 "type": "number",
299 "divisibleBy": 1,
300 "minimum": 0,
301 "maximum": 125
302 }
303 }
304}
305]]>
306 </artwork>
307 </figure>
308
309 <t>
310 A JSON Schema object MAY have any of the following optional properties:
311 </t>
312
313 <!-- TODO: Break attributes up into type sections -->
314 <!-- TODO: Add examples for (almost) every attribute -->
315
316 <section title="type" anchor="type">
317 <t>
318 This attribute defines what the primitive type or the schema of the instance MUST be in order to validate.
319 This attribute can take one of two forms:
320
321 <list style="hanging">
322 <t hangText="Simple Types">
323 A string indicating a primitive or simple type. The string MUST be one of the following values:
324
325 <list style="hanging">
326 <t hangText="object">Instance MUST be an object.</t>
327 <t hangText="array">Instance MUST be an array.</t>
328 <t hangText="string">Instance MUST be a string.</t>
329 <t hangText="number">Instance MUST be a number, including floating point numbers.</t>
330 <t hangText="boolean">Instance MUST be the JSON literal "true" or "false".</t>
331 <t hangText="null">Instance MUST be the JSON literal "null". Note that without this type, null values are not allowed.</t>
332 <t hangText="any">Instance MAY be of any type, including null.</t>
333 </list>
334 </t>
335
336 <t hangText="Union Types">
337 An array of one or more simple or schema types.
338 The instance value is valid if it is of the same type as one of the simple types, or valid by one of the schemas, in the array.
339 </t>
340 </list>
341
342 If this attribute is not specified, then all value types are accepted.
343 </t>
344
345 <figure>
346 <preamble>For example, a schema that defines if an instance can be a string or a number would be:</preamble>
347 <artwork>
348<![CDATA[
349{
350 "type": ["string", "number"]
351}
352]]></artwork>
353 </figure>
354 </section>
355
356 <section title="properties" anchor="properties">
357 <t>
358 This attribute is an object with properties that specify the schemas for the properties of the instance object.
359 In this attribute's object, each property value MUST be a schema.
360 When the instance value is an object, the value of the instance's properties MUST be valid according to the schemas with the same property names specified in this attribute.
361 Objects are unordered, so therefore the order of the instance properties or attribute properties MUST NOT determine validation success.
362 </t>
363 </section>
364
365 <section title="patternProperties" anchor="patternProperties">
366 <t>
367 This attribute is an object that defines the schema for a set of property names of an object instance.
368 The name of each property of this attribute's object is a regular expression pattern in the ECMA 262/Perl 5 format, while the value is a schema.
369 If the pattern matches the name of a property on the instance object, the value of the instance's property MUST be valid against the pattern name's schema value.
370 </t>
371 </section>
372
373 <section title="additionalProperties" anchor="additionalProperties">
374 <t>This attribute specifies how any instance property that is not explicitly defined by either the <xref target="properties">"properties"</xref> or <xref target="patternProperties">"patternProperties"</xref> attributes (hereafter referred to as "additional properties") is handled. If specified, the value MUST be a schema or a boolean.</t>
375 <t>If a schema is provided, then all additional properties MUST be valid according to the schema.</t>
376 <t>If false is provided, then no additional properties are allowed.</t>
377 <t>The default value is an empty schema, which allows any value for additional properties.</t>
378 </section>
379
380 <section title="items" anchor="items">
381 <t>This attribute provides the allowed items in an array instance. If specified, this attribute MUST be a schema or an array of schemas.</t>
382 <t>When this attribute value is a schema and the instance value is an array, then all the items in the array MUST be valid according to the schema.</t>
383 <t>When this attribute value is an array of schemas and the instance value is an array, each position in the instance array MUST be valid according to the schema in the corresponding position for this array. This called tuple typing. When tuple typing is used, additional items are allowed, disallowed, or constrained by the <xref target="additionalItems">"additionalItems"</xref> attribute the same way as <xref target="additionalProperties">"additionalProperties"</xref> for objects is.</t>
384 </section>
385
386 <section title="additionalItems" anchor="additionalItems">
387 <t>This attribute specifies how any item in the array instance that is not explicitly defined by <xref target="items">"items"</xref> (hereafter referred to as "additional items") is handled. If specified, the value MUST be a schema or a boolean.</t>
388 <t>If a schema is provided:
389 <list>
390 <t>If the <xref target="items">"items"</xref> attribute is unspecified, then all items in the array instance must be valid against this schema.</t>
391 <t>If the <xref target="items">"items"</xref> attribute is a schema, then this attribute is ignored.</t>
392 <t>If the <xref target="items">"items"</xref> attribute is an array (during tuple typing), then any additional items MUST be valid against this schema.</t>
393 </list>
394 </t>
395 <t>If false is provided, then any additional items in the array are not allowed.</t>
396 <t>The default value is an empty schema, which allows any value for additional items.</t>
397 </section>
398
399 <section title="required" anchor="required">
400 <t>This attribute is an array of strings that defines all the property names that must exist on the object instance.</t>
401 </section>
402
403 <section title="dependencies" anchor="dependencies">
404 <t>This attribute is an object that specifies the requirements of a property on an object instance. If an object instance has a property with the same name as a property in this attribute's object, then the instance must be valid against the attribute's property value (hereafter referred to as the "dependency value").</t>
405 <t>
406 The dependency value can take one of two forms:
407
408 <list style="hanging">
409 <t hangText="Simple Dependency">
410 If the dependency value is a string, then the instance object MUST have a property with the same name as the dependency value.
411 If the dependency value is an array of strings, then the instance object MUST have a property with the same name as each string in the dependency value's array.
412 </t>
413 <t hangText="Schema Dependency">
414 If the dependency value is a schema, then the instance object MUST be valid against the schema.
415 </t>
416 </list>
417 </t>
418 </section>
419
420 <section title="minimum" anchor="minimum">
421 <t>This attribute defines the minimum value of the instance property when the type of the instance value is a number.</t>
422 </section>
423
424 <section title="maximum" anchor="maximum">
425 <t>This attribute defines the maximum value of the instance property when the type of the instance value is a number.</t>
426 </section>
427
428 <section title="exclusiveMinimum" anchor="exclusiveMinimum">
429 <t>This attribute indicates if the value of the instance (if the instance is a number) can not equal the number defined by the "minimum" attribute. This is false by default, meaning the instance value can be greater then or equal to the minimum value.</t>
430 </section>
431
432 <section title="exclusiveMaximum" anchor="exclusiveMaximum">
433 <t>This attribute indicates if the value of the instance (if the instance is a number) can not equal the number defined by the "maximum" attribute. This is false by default, meaning the instance value can be less then or equal to the maximum value.</t>
434 </section>
435
436 <section title="minItems" anchor="minItems">
437 <t>This attribute defines the minimum number of values in an array when the array is the instance value.</t>
438 </section>
439
440 <section title="maxItems" anchor="maxItems">
441 <t>This attribute defines the maximum number of values in an array when the array is the instance value.</t>
442 </section>
443
444 <section title="minProperties" anchor="minProperties">
445 <t>This attribute defines the minimum number of properties required on an object instance.</t>
446 </section>
447
448 <section title="maxProperties" anchor="maxProperties">
449 <t>This attribute defines the maximum number of properties the object instance can have.</t>
450 </section>
451
452 <section title="uniqueItems" anchor="uniqueItems">
453 <t>This attribute indicates that all items in an array instance MUST be unique (contains no two identical values).</t>
454 <t>
455 Two instance are consider equal if they are both of the same type and:
456
457 <list>
458 <t>are null; or</t>
459 <t>are booleans/numbers/strings and have the same value; or</t>
460 <t>are arrays, contains the same number of items, and each item in the array is equal to the item at the corresponding index in the other array; or</t>
461 <t>are objects, contains the same property names, and each property in the object is equal to the corresponding property in the other object.</t>
462 </list>
463 </t>
464 </section>
465
466 <section title="pattern" anchor="pattern">
467 <t>When the instance value is a string, this provides a regular expression that a string instance MUST match in order to be valid. Regular expressions SHOULD follow the regular expression specification from ECMA 262/Perl 5</t>
468 </section>
469
470 <section title="minLength" anchor="minLength">
471 <t>When the instance value is a string, this defines the minimum length of the string.</t>
472 </section>
473
474 <section title="maxLength" anchor="maxLength">
475 <t>When the instance value is a string, this defines the maximum length of the string.</t>
476 </section>
477
478 <section title="enum" anchor="enum">
479 <t>This provides an enumeration of all possible values that are valid for the instance property. This MUST be an array, and each item in the array represents a possible value for the instance value. If this attribute is defined, the instance value MUST be one of the values in the array in order for the schema to be valid. Comparison of enum values uses the same algorithm as defined in <xref target="uniqueItems">"uniqueItems"</xref>.</t>
480 </section>
481
482 <section title="default" anchor="default">
483 <t>This attribute defines the default value of the instance when the instance is undefined.</t>
484 </section>
485
486 <section title="title" anchor="title">
487 <t>This attribute is a string that provides a short description of the instance property.</t>
488 </section>
489
490 <section title="description" anchor="description">
491 <t>This attribute is a string that provides a full description of the of purpose the instance property.</t>
492 </section>
493
494 <section title="divisibleBy" anchor="divisibleBy">
495 <t>This attribute defines what value the number instance must be divisible by with no remainder (the result of the division must be an integer.) The value of this attribute SHOULD NOT be 0.</t>
496 </section>
497
498 <section title="disallow" anchor="disallow">
499 <t>This attribute takes the same values as the "type" attribute, however if the instance matches the type or if this value is an array and the instance matches any type or schema in the array, then this instance is not valid.</t>
500 </section>
501
502 <section title="extends" anchor="extends">
503 <t>The value of this property MUST be another schema which will provide a base schema which the current schema will inherit from. The inheritance rules are such that any instance that is valid according to the current schema MUST be valid according to the referenced schema. This MAY also be an array, in which case, the instance MUST be valid for all the schemas in the array. A schema that extends another schema MAY define additional attributes, constrain existing attributes, or add other constraints.</t>
504 <t>
505 Conceptually, the behavior of extends can be seen as validating an
506 instance against all constraints in the extending schema as well as
507 the extended schema(s). More optimized implementations that merge
508 schemas are possible, but are not required. Some examples of using "extends":
509
510 <figure>
511 <artwork>
512<![CDATA[
513{
514 "description": "An adult",
515 "properties": {
516 "age": {
517 "minimum": 21
518 }
519 },
520 "extends": {"$ref": "person"}
521}
522]]>
523 </artwork>
524 </figure>
525
526 <figure>
527 <artwork>
528<![CDATA[
529{
530 "description": "Extended schema",
531 "properties": {
532 "deprecated": {
533 "type": "boolean"
534 }
535 },
536 "extends": {"$ref": "http://json-schema.org/draft-04/schema"}
537}
538]]>
539 </artwork>
540 </figure>
541 </t>
542 </section>
543
544 <section title="id" anchor="id">
545 <t>
546 This attribute defines the current URI of this schema (this attribute is
547 effectively a "self" link). This URI MAY be relative or absolute. If
548 the URI is relative it is resolved against the current URI of the parent
549 schema it is contained in. If this schema is not contained in any
550 parent schema, the current URI of the parent schema is held to be the
551 URI under which this schema was addressed. If id is missing, the current URI of a schema is
552 defined to be that of the parent schema. The current URI of the schema
553 is also used to construct relative references such as for $ref.
554 </t>
555 </section>
556
557 <section title="$ref" anchor="ref">
558 <t>
559 This attribute defines a URI of a schema that contains the full representation of this schema.
560 When a validator encounters this attribute, it SHOULD replace the current schema with the schema referenced by the value's URI (if known and available) and re-validate the instance.
561 This URI MAY be relative or absolute, and relative URIs SHOULD be resolved against the URI of the current schema.
562 </t>
563 </section>
564
565 <section title="$schema" anchor="schema">
566 <t>
567 This attribute defines a URI of a JSON Schema that is the schema of the current schema.
568 When this attribute is defined, a validator SHOULD use the schema referenced by the value's URI (if known and available) when resolving <xref target="hyper-schema">Hyper Schema</xref><xref target="links">links</xref>.
569 </t>
570
571 <t>
572 A validator MAY use this attribute's value to determine which version of JSON Schema the current schema is written in, and provide the appropriate validation features and behavior.
573 Therefore, it is RECOMMENDED that all schema authors include this attribute in their schemas to prevent conflicts with future JSON Schema specification changes.
574 </t>
575 </section>
576 </section>
577
578 <section title="Hyper Schema" anchor="hyper-schema">
579 <t>
580 The following attributes are specified in addition to those
581 attributes that already provided by the core schema with the specific
582 purpose of informing user agents of relations between resources based
583 on JSON data. Just as with JSON
584 schema attributes, all the attributes in hyper schemas are optional.
585 Therefore, an empty object is a valid (non-informative) schema, and
586 essentially describes plain JSON (no constraints on the structures).
587 Addition of attributes provides additive information for user agents.
588 </t>
589
590 <section title="links" anchor="links">
591 <t>
592 The value of the links property MUST be an array, where each item
593 in the array is a link description object which describes the link
594 relations of the instances.
595 </t>
596
597 <!-- TODO: Needs more clarification and examples -->
598
599 <section title="Link Description Object">
600 <t>
601 A link description object is used to describe link relations. In
602 the context of a schema, it defines the link relations of the
603 instances of the schema, and can be parameterized by the instance
604 values. The link description format can be used without JSON Schema,
605 and use of this format can
606 be declared by referencing the normative link description
607 schema as the the schema for the data structure that uses the
608 links. The URI of the normative link description schema is:
609 <eref target="http://json-schema.org/links">http://json-schema.org/links</eref> (latest version) or
610 <eref target="http://json-schema.org/draft-04/links">http://json-schema.org/draft-04/links</eref> (draft-04 version).
611 </t>
612
613 <section title="href" anchor="href">
614 <t>
615 The value of the "href" link description property
616 indicates the target URI of the related resource. The value
617 of the instance property SHOULD be resolved as a URI-Reference per <xref target="RFC3986">RFC 3986</xref>
618 and MAY be a relative URI. The base URI to be used for relative resolution
619 SHOULD be the URI used to retrieve the instance object (not the schema)
620 when used within a schema. Also, when links are used within a schema, the URI
621 SHOULD be parametrized by the property values of the instance
622 object, if property values exist for the corresponding variables
623 in the template (otherwise they MAY be provided from alternate sources, like user input).
624 </t>
625
626 <t>
627 Instance property values SHOULD be substituted into the URIs where
628 matching braces ('{', '}') are found surrounding zero or more characters,
629 creating an expanded URI. Instance property value substitutions are resolved
630 by using the text between the braces to denote the property name
631 from the instance to get the value to substitute.
632
633 <figure>
634 <preamble>For example, if an href value is defined:</preamble>
635 <artwork>
636<![CDATA[
637http://somesite.com/{id}
638]]>
639 </artwork>
640 <postamble>Then it would be resolved by replace the value of the "id" property value from the instance object.</postamble>
641 </figure>
642
643 <figure>
644 <preamble>If the value of the "id" property was "45", the expanded URI would be:</preamble>
645 <artwork>
646<![CDATA[
647http://somesite.com/45
648]]>
649 </artwork>
650 </figure>
651
652 If matching braces are found with the string "@" (no quotes) between the braces, then the
653 actual instance value SHOULD be used to replace the braces, rather than a property value.
654 This should only be used in situations where the instance is a scalar (string,
655 boolean, or number), and not for objects or arrays.
656 </t>
657 </section>
658
659 <section title="rel">
660 <t>
661 The value of the "rel" property indicates the name of the
662 relation to the target resource. The relation to the target SHOULD be interpreted as specifically from the instance object that the schema (or sub-schema) applies to, not just the top level resource that contains the object within its hierarchy. If a resource JSON representation contains a sub object with a property interpreted as a link, that sub-object holds the relation with the target. A relation to target from the top level resource MUST be indicated with the schema describing the top level JSON representation.
663 </t>
664
665 <t>
666 Relationship definitions SHOULD NOT be media type dependent, and users are encouraged to utilize existing accepted relation definitions, including those in existing relation registries (see <xref target="RFC4287">RFC 4287</xref>). However, we define these relations here for clarity of normative interpretation within the context of JSON hyper schema defined relations:
667
668 <list style="hanging">
669 <t hangText="self">
670 If the relation value is "self", when this property is encountered in
671 the instance object, the object represents a resource and the instance object is
672 treated as a full representation of the target resource identified by
673 the specified URI.
674 </t>
675
676 <t hangText="full">
677 This indicates that the target of the link is the full representation for the instance object. The object that contains this link possibly may not be the full representation.
678 </t>
679
680 <t hangText="describedby">
681 This indicates the target of the link is the schema for the instance object. This MAY be used to specifically denote the schemas of objects within a JSON object hierarchy, facilitating polymorphic type data structures.
682 </t>
683
684 <t hangText="root">
685 This relation indicates that the target of the link
686 SHOULD be treated as the root or the body of the representation for the
687 purposes of user agent interaction or fragment resolution. All other
688 properties of the instance objects can be regarded as meta-data
689 descriptions for the data.
690 </t>
691 </list>
692 </t>
693
694 <t>
695 The following relations are applicable for schemas (the schema as the "from" resource in the relation):
696
697 <list style="hanging">
698 <t hangText="instances">This indicates the target resource that represents collection of instances of a schema.</t>
699 <t hangText="create">This indicates a target to use for creating new instances of a schema. This link definition SHOULD be a submission link with a non-safe method (like POST).</t>
700 </list>
701 </t>
702
703 <t>
704 <figure>
705 <preamble>For example, if a schema is defined:</preamble>
706 <artwork>
707<![CDATA[
708{
709 "links": [{
710 "rel": "self",
711 "href": "{id}"
712 }, {
713 "rel": "up",
714 "href": "{upId}"
715 }, {
716 "rel": "children",
717 "href": "?upId={id}"
718 }]
719}
720]]>
721 </artwork>
722 </figure>
723
724 <figure>
725 <preamble>And if a collection of instance resource's JSON representation was retrieved:</preamble>
726 <artwork>
727<![CDATA[
728GET /Resource/
729
730[{
731 "id": "thing",
732 "upId": "parent"
733}, {
734 "id": "thing2",
735 "upId": "parent"
736}]
737]]>
738 </artwork>
739 </figure>
740
741 This would indicate that for the first item in the collection, its own
742 (self) URI would resolve to "/Resource/thing" and the first item's "up"
743 relation SHOULD be resolved to the resource at "/Resource/parent".
744 The "children" collection would be located at "/Resource/?upId=thing".
745 </t>
746 </section>
747
748 <section title="template">
749 <t>This property value is a string that defines the templating language used in the <xref target="href">"href"</xref> attribute. If no templating language is defined, then the default <xref target="href">Link Description Object templating langauge</xref> is used.</t>
750 </section>
751
752 <section title="targetSchema">
753 <t>This property value is a schema that defines the expected structure of the JSON representation of the target of the link.</t>
754 </section>
755
756 <section title="Submission Link Properties">
757 <t>
758 The following properties also apply to link definition objects, and
759 provide functionality analogous to HTML forms, in providing a
760 means for submitting extra (often user supplied) information to send to a server.
761 </t>
762
763 <section title="method">
764 <t>
765 This attribute defines which method can be used to access the target resource.
766 In an HTTP environment, this would be "GET" or "POST" (other HTTP methods
767 such as "PUT" and "DELETE" have semantics that are clearly implied by
768 accessed resources, and do not need to be defined here).
769 This defaults to "GET".
770 </t>
771 </section>
772
773 <section title="enctype">
774 <t>
775 If present, this property indicates a query media type format that the server
776 supports for querying or posting to the collection of instances at the target
777 resource. The query can be
778 suffixed to the target URI to query the collection with
779 property-based constraints on the resources that SHOULD be returned from
780 the server or used to post data to the resource (depending on the method).
781
782 <figure>
783 <preamble>For example, with the following schema:</preamble>
784 <artwork>
785<![CDATA[
786{
787 "links": [{
788 "enctype": "application/x-www-form-urlencoded",
789 "method": "GET",
790 "href": "/Product/",
791 "properties": {
792 "name": {
793 "description": "name of the product"
794 }
795 }
796 }]
797}
798]]>
799 </artwork>
800 <postamble>This indicates that the client can query the server for instances that have a specific name.</postamble>
801 </figure>
802
803 <figure>
804 <preamble>For example:</preamble>
805 <artwork>
806<![CDATA[
807/Product/?name=Slinky
808]]>
809 </artwork>
810 </figure>
811
812 If no enctype or method is specified, only the single URI specified by
813 the href property is defined. If the method is POST, "application/json" is
814 the default media type.
815 </t>
816 </section>
817
818 <section title="schema">
819 <t>
820 This attribute contains a schema which defines the acceptable structure of the submitted
821 request (for a GET request, this schema would define the properties for the query string
822 and for a POST request, this would define the body).
823 </t>
824 </section>
825 </section>
826 </section>
827 </section>
828
829 <section title="fragmentResolution">
830 <t>
831 This property indicates the fragment resolution protocol to use for
832 resolving fragment identifiers in URIs within the instance
833 representations. This applies to the instance object URIs and all
834 children of the instance object's URIs. The default fragment resolution
835 protocol is "json-pointer", which is defined below. Other fragment
836 resolution protocols MAY be used, but are not defined in this document.
837 </t>
838
839 <t>
840 The fragment identifier is based on <xref target="RFC3986">RFC 3986, Sec 5</xref>, and defines the
841 mechanism for resolving references to entities within a document.
842 </t>
843
844 <section title="json-pointer fragment resolution">
845 <t>The "json-pointer" fragment resolution protocol uses a <xref target="json-pointer">JSON Pointer</xref> to resolve fragment identifiers in URIs within instance representations.</t>
846 </section>
847 </section>
848
849 <!-- TODO: Remove this? -->
850
851 <section title="readonly">
852 <t>This attribute indicates that the instance value SHOULD NOT be changed. Attempts by a user agent to modify the value of this property are expected to be rejected by a server.</t>
853 </section>
854
855 <section title="contentEncoding">
856 <t>If the instance property value is a string, this attribute defines that the string SHOULD be interpreted as binary data and decoded using the encoding named by this schema property. <xref target="RFC2045">RFC 2045, Sec 6.1</xref> lists the possible values for this property.</t>
857 </section>
858
859 <section title="pathStart">
860 <t>
861 This attribute is a URI that defines what the instance's URI MUST start with in order to validate.
862 The value of the "pathStart" attribute MUST be resolved as per <xref target="RFC3986">RFC 3986, Sec 5</xref>,
863 and is relative to the instance's URI.
864 </t>
865
866 <t>
867 When multiple schemas have been referenced for an instance, the user agent
868 can determine if this schema is applicable for a particular instance by
869 determining if the URI of the instance begins with the the value of the "pathStart"
870 attribute. If the URI of the instance does not start with this URI,
871 or if another schema specifies a starting URI that is longer and also matches the
872 instance, this schema SHOULD NOT be applied to the instance. Any schema
873 that does not have a pathStart attribute SHOULD be considered applicable
874 to all the instances for which it is referenced.
875 </t>
876 </section>
877
878 <section title="mediaType">
879 <t>This attribute defines the media type of the instance representations that this schema is defining.</t>
880 </section>
881 </section>
882
883 <section title="Security Considerations">
884 <t>
885 This specification is a sub-type of the JSON format, and
886 consequently the security considerations are generally the same as <xref target="RFC4627">RFC 4627</xref>.
887 However, an additional issue is that when link relation of "self"
888 is used to denote a full representation of an object, the user agent
889 SHOULD NOT consider the representation to be the authoritative representation
890 of the resource denoted by the target URI if the target URI is not
891 equivalent to or a sub-path of the the URI used to request the resource
892 representation which contains the target URI with the "self" link.
893
894 <figure>
895 <preamble>For example, if a hyper schema was defined:</preamble>
896 <artwork>
897<![CDATA[
898{
899 "links": [{
900 "rel": "self",
901 "href": "{id}"
902 }]
903}
904]]>
905 </artwork>
906 </figure>
907
908 <figure>
909 <preamble>And a resource was requested from somesite.com:</preamble>
910 <artwork>
911<![CDATA[
912GET /foo/
913]]>
914 </artwork>
915 </figure>
916
917 <figure>
918 <preamble>With a response of:</preamble>
919 <artwork>
920<![CDATA[
921Content-Type: application/json; profile=/schema-for-this-data
922
923[{
924 "id": "bar",
925 "name": "This representation can be safely treated \
926 as authoritative "
927}, {
928 "id": "/baz",
929 "name": "This representation should not be treated as \
930 authoritative the user agent should make request the resource\
931 from '/baz' to ensure it has the authoritative representation"
932}, {
933 "id": "http://othersite.com/something",
934 "name": "This representation\
935 should also not be treated as authoritative and the target\
936 resource representation should be retrieved for the\
937 authoritative representation"
938}]
939]]>
940 </artwork>
941 </figure>
942 </t>
943 </section>
944
945 <section title="IANA Considerations">
946 <t>The proposed MIME media type for JSON Schema is "application/schema+json".</t>
947 <t>Type name: application</t>
948 <t>Subtype name: schema+json</t>
949 <t>Required parameters: profile</t>
950 <t>
951 The value of the profile parameter SHOULD be a URI (relative or absolute) that
952 refers to the schema used to define the structure of this structure (the
953 meta-schema). Normally the value would be http://json-schema.org/draft-04/hyper-schema,
954 but it is allowable to use other schemas that extend the hyper schema's meta-
955 schema.
956 </t>
957 <t>Optional parameters: pretty</t>
958 <t>The value of the pretty parameter MAY be true or false to indicate if additional whitespace has been included to make the JSON representation easier to read.</t>
959
960 <section title="Registry of Link Relations">
961 <t>
962 This registry is maintained by IANA per <xref target="RFC4287">RFC 4287</xref> and this specification adds
963 four values: "full", "create", "instances", "root". New
964 assignments are subject to IESG Approval, as outlined in <xref target="RFC5226">RFC 5226</xref>.
965 Requests should be made by email to IANA, which will then forward the
966 request to the IESG, requesting approval.
967 </t>
968 </section>
969 </section>
970 </middle>
971
972 <back>
973 <!-- References Section -->
974 <references title="Normative References">
975 &rfc2045;
976 &rfc2119;
977 &rfc3339;
978 &rfc3986;
979 &rfc4287;
980 <reference anchor="json-pointer" target="http://tools.ietf.org/html/draft-pbryan-zyp-json-pointer-02">
981 <front>
982 <title>JSON Pointer</title>
983 <author initials="P." surname="Bryan">
984 <organization>ForgeRock US, Inc.</organization>
985 </author>
986 <author initials="K." surname="Zyp">
987 <organization>SitePen (USA)</organization>
988 </author>
989 <date year="2011" month="October" />
990 </front>
991 </reference>
992 </references>
993 <references title="Informative References">
994 &rfc2616;
995 &rfc4627;
996 &rfc5226;
997 &iddiscovery;
998 &uritemplate;
999 &linkheader;
1000 &html401;
1001 &css21;
1002 </references>
1003
1004 <section title="Change Log">
1005 <t>
1006 <list style="hanging">
1007 <t hangText="draft-04">
1008 <list style="symbols">
1009 <t>Changed "required" attribute to an array of strings.</t>
1010 <t>Removed "format" attribute.</t>
1011 <t>Added "minProperties" and "maxProperties" attributes.</t>
1012 <t>Replaced "slash-delimited" fragment resolution with "json-pointer".</t>
1013 <t>Added "template" LDO attribute.</t>
1014 <t>Removed irrelevant "Open Issues" section.</t>
1015 <t>Merged Conventions and Terminology sections.</t>
1016 <t>Defined terms used in specification.</t>
1017 <t>Removed "integer" type in favor of {"type":"number", "divisibleBy":1}.</t>
1018 <t>Restricted "type" to only the core JSON types.</t>
1019 <t>Improved wording of many sections.</t>
1020 </list>
1021 </t>
1022
1023 <t hangText="draft-03">
1024 <list style="symbols">
1025 <t>Added example and verbiage to "extends" attribute.</t>
1026 <t>Defined slash-delimited to use a leading slash.</t>
1027 <t>Made "root" a relation instead of an attribute.</t>
1028 <t>Removed address values, and MIME media type from format to reduce confusion (mediaType already exists, so it can be used for MIME types).</t>
1029 <t>Added more explanation of nullability.</t>
1030 <t>Removed "alternate" attribute.</t>
1031 <t>Upper cased many normative usages of must, may, and should.</t>
1032 <t>Replaced the link submission "properties" attribute to "schema" attribute.</t>
1033 <t>Replaced "optional" attribute with "required" attribute.</t>
1034 <t>Replaced "maximumCanEqual" attribute with "exclusiveMaximum" attribute.</t>
1035 <t>Replaced "minimumCanEqual" attribute with "exclusiveMinimum" attribute.</t>
1036 <t>Replaced "requires" attribute with "dependencies" attribute.</t>
1037 <t>Moved "contentEncoding" attribute to hyper schema.</t>
1038 <t>Added "additionalItems" attribute.</t>
1039 <t>Added "id" attribute.</t>
1040 <t>Switched self-referencing variable substitution from "-this" to "@" to align with reserved characters in URI template.</t>
1041 <t>Added "patternProperties" attribute.</t>
1042 <t>Schema URIs are now namespace versioned.</t>
1043 <t>Added "$ref" and "$schema" attributes.</t>
1044 </list>
1045 </t>
1046
1047 <t hangText="draft-02">
1048 <list style="symbols">
1049 <t>Replaced "maxDecimal" attribute with "divisibleBy" attribute.</t>
1050 <t>Added slash-delimited fragment resolution protocol and made it the default.</t>
1051 <t>Added language about using links outside of schemas by referencing its normative URI.</t>
1052 <t>Added "uniqueItems" attribute.</t>
1053 <t>Added "targetSchema" attribute to link description object.</t>
1054 </list>
1055 </t>
1056
1057 <t hangText="draft-01">
1058 <list style="symbols">
1059 <t>Fixed category and updates from template.</t>
1060 </list>
1061 </t>
1062
1063 <t hangText="draft-00">
1064 <list style="symbols">
1065 <t>Initial draft.</t>
1066 </list>
1067 </t>
1068 </list>
1069 </t>
1070 </section>
1071 </back>
1072</rfc>
Note: See TracBrowser for help on using the repository browser.