forked from json-schema-org/json-schema-org.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-zyp-json-schema-01.html
1400 lines (1224 loc) · 64.8 KB
/
draft-zyp-json-schema-01.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><title>A JSON Media Type for Describing the Structure and Meaning of JSON Documents</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="A JSON Media Type for Describing the Structure and Meaning of JSON Documents">
<meta name="keywords" content="JSON, Schema, Hyper Schema, Hypermedia">
<meta name="generator" content="xml2rfc v1.35pre1 (http://xml.resource.org/)">
<style type='text/css'><!--
body {
font-family: verdana, charcoal, helvetica, arial, sans-serif;
font-size: small; color: #000; background-color: #FFF;
margin: 2em;
}
h1, h2, h3, h4, h5, h6 {
font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
font-weight: bold; font-style: normal;
}
h1 { color: #900; background-color: transparent; text-align: right; }
h3 { color: #333; background-color: transparent; }
td.RFCbug {
font-size: x-small; text-decoration: none;
width: 30px; height: 30px; padding-top: 2px;
text-align: justify; vertical-align: middle;
background-color: #000;
}
td.RFCbug span.RFC {
font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
font-weight: bold; color: #666;
}
td.RFCbug span.hotText {
font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
font-weight: normal; text-align: center; color: #FFF;
}
table.TOCbug { width: 30px; height: 15px; }
td.TOCbug {
text-align: center; width: 30px; height: 15px;
color: #FFF; background-color: #900;
}
td.TOCbug a {
font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
font-weight: bold; font-size: x-small; text-decoration: none;
color: #FFF; background-color: transparent;
}
td.header {
font-family: arial, helvetica, sans-serif; font-size: x-small;
vertical-align: top; width: 33%;
color: #FFF; background-color: #666;
}
td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
td.author-text { font-size: x-small; }
/* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
a.info {
/* This is the key. */
position: relative;
z-index: 24;
text-decoration: none;
}
a.info:hover {
z-index: 25;
color: #FFF; background-color: #900;
}
a.info span { display: none; }
a.info:hover span.info {
/* The span will display just on :hover state. */
display: block;
position: absolute;
font-size: smaller;
top: 2em; left: -5em; width: 15em;
padding: 2px; border: 1px solid #333;
color: #900; background-color: #EEE;
text-align: left;
}
a { font-weight: bold; }
a:link { color: #900; background-color: transparent; }
a:visited { color: #633; background-color: transparent; }
a:active { color: #633; background-color: transparent; }
p { margin-left: 2em; margin-right: 2em; }
p.copyright { font-size: x-small; }
p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
ol.text { margin-left: 2em; margin-right: 2em; }
ul.text { margin-left: 2em; margin-right: 2em; }
li { margin-left: 3em; }
/* RFC-2629 <spanx>s and <artwork>s. */
em { font-style: italic; }
strong { font-weight: bold; }
dfn { font-weight: bold; font-style: normal; }
cite { font-weight: normal; font-style: normal; }
tt { color: #036; }
tt, pre, pre dfn, pre em, pre cite, pre span {
font-family: "Courier New", Courier, monospace; font-size: small;
}
pre {
text-align: left; padding: 4px;
color: #000; background-color: #CCC;
}
pre dfn { color: #900; }
pre em { color: #66F; background-color: #FFC; font-weight: normal; }
pre .key { color: #33C; font-weight: bold; }
pre .id { color: #900; }
pre .str { color: #000; background-color: #CFF; }
pre .val { color: #066; }
pre .rep { color: #909; }
pre .oth { color: #000; background-color: #FCF; }
pre .err { background-color: #FCC; }
/* RFC-2629 <texttable>s. */
table.all, table.full, table.headers, table.none {
font-size: small; text-align: center; border-width: 2px;
vertical-align: top; border-collapse: collapse;
}
table.all, table.full { border-style: solid; border-color: black; }
table.headers, table.none { border-style: none; }
th {
font-weight: bold; border-color: black;
border-width: 2px 2px 3px 2px;
}
table.all th, table.full th { border-style: solid; }
table.headers th { border-style: none none solid none; }
table.none th { border-style: none; }
table.all td {
border-style: solid; border-color: #333;
border-width: 1px 2px;
}
table.full td, table.headers td, table.none td { border-style: none; }
hr { height: 1px; }
hr.insert {
width: 80%; border-style: none; border-width: 0;
color: #CCC; background-color: #CCC;
}
--></style>
</head>
<body>
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
<tr><td class="header">Internet Engineering Task Force</td><td class="header">K. Zyp, Ed.</td></tr>
<tr><td class="header">Internet-Draft</td><td class="header">SitePen (USA)</td></tr>
<tr><td class="header">Intended status: Informational</td><td class="header">December 5, 2009</td></tr>
<tr><td class="header">Expires: June 8, 2010</td><td class="header"> </td></tr>
</table></td></tr></table>
<h1><br />A JSON Media Type for Describing the Structure and Meaning of JSON Documents<br />draft-zyp-json-schema-01</h1>
<h3>Abstract</h3>
<p>JSON (JavaScript Object Notation) Schema defines the media type application/schema+json,
a JSON based format for defining
the structure of JSON data. JSON Schema provides a contract for what JSON
data is required for a given application and how to interact with it. JSON
Schema is intended to define validation, documentation, hyperlink
navigation, and interaction control of JSON data.
</p>
<h3>Status of This Memo</h3>
<p>
This Internet-Draft is submitted to IETF in full
conformance with the provisions of BCP 78 and BCP 79.</p>
<p>
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups.
Note that other groups may also distribute working documents as
Internet-Drafts.</p>
<p>
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any time.
It is inappropriate to use Internet-Drafts as reference material or to cite
them other than as “work in progress.”</p>
<p>
The list of current Internet-Drafts can be accessed at
<a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p>
<p>
The list of Internet-Draft Shadow Directories can be accessed at
<a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p>
<p>
This Internet-Draft will expire on June 8, 2010.</p>
<h3>Copyright Notice</h3>
<p>
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.</p>
<p>
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the BSD License.</p>
<a name="toc"></a><br /><hr />
<h3>Table of Contents</h3>
<p class="toc">
<a href="#anchor1">1.</a>
Introduction<br />
<a href="#anchor2">2.</a>
Conventions<br />
<a href="#anchor3">3.</a>
Overview<br />
<a href="#anchor4">3.1.</a>
Terminology<br />
<a href="#anchor5">3.2.</a>
Design Considerations<br />
<a href="#anchor6">4.</a>
Schema/Instance Association<br />
<a href="#anchor7">4.1.</a>
Self-Descriptive Schema<br />
<a href="#anchor8">5.</a>
Core Schema Definition<br />
<a href="#anchor9">5.1.</a>
type<br />
<a href="#anchor10">5.2.</a>
properties<br />
<a href="#anchor11">5.3.</a>
items<br />
<a href="#anchor12">5.4.</a>
optional<br />
<a href="#anchor13">5.5.</a>
additionalProperties<br />
<a href="#anchor14">5.6.</a>
requires<br />
<a href="#anchor15">5.7.</a>
minimum<br />
<a href="#anchor16">5.8.</a>
maximum<br />
<a href="#anchor17">5.9.</a>
minimumCanEqual<br />
<a href="#anchor18">5.10.</a>
maximumCanEqual<br />
<a href="#anchor19">5.11.</a>
minItems<br />
<a href="#anchor20">5.12.</a>
maxItems<br />
<a href="#anchor21">5.13.</a>
pattern<br />
<a href="#anchor22">5.14.</a>
maxLength<br />
<a href="#anchor23">5.15.</a>
minLength<br />
<a href="#anchor24">5.16.</a>
enum<br />
<a href="#anchor25">5.17.</a>
title<br />
<a href="#anchor26">5.18.</a>
description<br />
<a href="#anchor27">5.19.</a>
format<br />
<a href="#anchor28">5.20.</a>
contentEncoding<br />
<a href="#anchor29">5.21.</a>
default<br />
<a href="#anchor30">5.22.</a>
maxDecimal<br />
<a href="#anchor31">5.23.</a>
disallow<br />
<a href="#anchor32">5.24.</a>
extends<br />
<a href="#anchor33">6.</a>
Hyper Schema<br />
<a href="#anchor34">6.1.</a>
links<br />
<a href="#anchor35">6.1.1.</a>
Link Description Object<br />
<a href="#anchor42">6.2.</a>
fragmentResolution<br />
<a href="#anchor43">6.2.1.</a>
dot-delimited fragment resolution<br />
<a href="#anchor44">6.3.</a>
root<br />
<a href="#anchor45">6.4.</a>
readonly<br />
<a href="#anchor46">6.5.</a>
pathStart<br />
<a href="#anchor47">6.6.</a>
mediaType<br />
<a href="#anchor48">6.7.</a>
alternate<br />
<a href="#anchor49">7.</a>
Security Considerations<br />
<a href="#anchor50">8.</a>
IANA Considerations<br />
<a href="#anchor51">8.1.</a>
Registry of Link Relations<br />
<a href="#rfc.references1">9.</a>
References<br />
<a href="#rfc.references1">9.1.</a>
Normative References<br />
<a href="#rfc.references2">9.2.</a>
Informative References<br />
<a href="#anchor54">Appendix A.</a>
Change Log <br />
<a href="#anchor55">Appendix B.</a>
Open Issues<br />
</p>
<br clear="all" />
<a name="anchor1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1"></a><h3>1.
Introduction</h3>
<p>JSON (JavaScript Object Notation) Schema is a JSON media type for defining
the structure of JSON data. JSON Schema provides a contract for what JSON
data is required for a given application and how to interact with it. JSON
Schema is intended to define validation, documentation, hyperlink
navigation, and interaction control of JSON data.
</p>
<a name="anchor2"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2"></a><h3>2.
Conventions</h3>
<p>The key words "MUST", "MUST
NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119.
</p>
<a name="anchor3"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3"></a><h3>3.
Overview</h3>
<p>JSON Schema defines the media type application/schema+json for
describing the structure of other
JSON documents. JSON Schema is JSON-based and includes facilities
for describing the structure of JSON documents in terms of
allowable values, descriptions, and interpreting relations with other resources.
</p>
<p>JSON Schema format is organized into several separate definitions. The first
definition is the core schema specification. This definition is primary
concerned with describing a JSON structure and specifying valid elements
in the structure. The second definition is the Hyper Schema specification
which is intended define elements in a structure that can be interpreted as
hyperlinks.
Hyper Schema builds on JSON Schema to describe the hyperlink structure of
other JSON documents. This allows user agents to be able to successfully navigate
JSON documents based on their schemas.
</p>
<p>
Cumulatively JSON Schema acts as a meta-document that can be used to define the required type and constraints on
property values, as well as define the meaning of the property values
for the purpose of describing a resource and determining hyperlinks
within the representation.
</p>
<p>
An example JSON Schema that describes products might look like:
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
{
"name":"Product",
"properties":{
"id":{
"type":"number",
"description":"Product identifier"
},
"name":{
"description":"Name of the product",
"type":"string"
},
"price":{
"type": "number",
"minimum":0
},
"tags":{
"optional":true,
"type":"array",
"items":{
"type":"string"
}
}
},
"links":[
{
"rel":"full",
"href":"{id}"
},
{
"rel":"comments",
"href":"comments/?id={id}"
}
]
}
</pre></div><p>
This schema defines the properties of the instance JSON documents and
their required properties (id, name, and price) as well as an optional
property (tags). This also defines the link relations of the instance
JSON documents.
</p>
<a name="anchor4"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3.1"></a><h3>3.1.
Terminology</h3>
<p>For this specification, a schema will be used to denote a JSON Schema
definition, and an instance refers to the JSON object or array that the schema
will be describing and validating
</p>
<a name="anchor5"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3.2"></a><h3>3.2.
Design Considerations</h3>
<p>
The JSON Schema media type does not attempt to dictate the structure of JSON
representations that contain data, but rather provides a separate format
for flexibly communicating how a JSON representation should be
interpreted and validated, such that user agents can properly understand
acceptable structures and extrapolate hyperlink information
with the JSON document. This specification does not define a protocol.
The underlying protocol (such as HTTP) should sufficiently define the
semantics of the client-server interface, the retrieval of resource
representations linked to by JSON representations, and modification of
those resources. The goal of this
format is to sufficiently describe JSON structures such that one can
utilize existing information available in existing JSON
representations from a large variety of services that leverage a REST
architecture using existing protocols.
</p>
<a name="anchor6"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.4"></a><h3>4.
Schema/Instance Association</h3>
<p>
JSON Schema instances are correlated to their schema by the "describedby"
relation, where the schema is defined to be the target of the relation.
Instance representations may be of the application/json media type or
any other subtype. Consequently, dictating how an instance
representation should specify the relation to the schema is beyond the normative scope
of this document (since this document specifically defines the JSON
Schema media type, and no other), but it is recommended that instances
specify their schema so that user agents can interpret the instance
representation and messages may retain the self-descriptive
characteristic, avoiding the need for out-of-band information about
instance data. Two approaches are recommended for declaring the
relation to the schema that describes the meaning of a JSON instance's (or collection
of instances) structure. A MIME type parameter named
"describedby" or a Link header with a relation of "describedby" SHOULD be used:
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
Content-Type: application/json;
describedby=http://json.com/my-hyper-schema
</pre></div><p>
or if the content is being transferred by a protocol (such as HTTP) that
provides headers, a Link header can be used:
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
Link: <http://json.com/my-hyper-schema>; rel="describedby"
</pre></div><p>
Instances MAY specify multiple schemas, to indicate all the schemas that
are applicable to the data. The instance data may have multiple schemas
that it is defined by (the instance data should be valid for those schemas).
Or if the document is a collection of instances, the collection may contain
instances from different schemas. When collections contain heterogeneous
instances, the pathStart attribute MAY be specified in the
schema to disambiguate which schema should be applied for each item in the
collection.
</p>
<a name="anchor7"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.4.1"></a><h3>4.1.
Self-Descriptive Schema</h3>
<p>
JSON Schemas are themselves instances for the schema
schemas. A self-describing JSON Schema for the core JSON Schema can
be found at http://json-schema.org/schema and the hyper schema
self-description can be found at: http://json-schema.org/hyper-schema. All schemas
used within a protocol with media type definitions
SHOULD include a MIME parameter that refers to the self-descriptive
hyper schema or another schema that extends this hyper schema:
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
Content-Type: application/json;
describedby=http://www.json-schema.org/hyper-schema
</pre></div><p>
</p>
<a name="anchor8"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5"></a><h3>5.
Core Schema Definition</h3>
<p>A JSON Schema is a JSON Object that defines various attributes
of the instance and defines it's usage and valid values. A JSON
Schema is a JSON Object with schema attribute properties.
The following is the grammar of a JSON Schema:
</p>
<p>And an example JSON Schema definition could look like:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
{"description":"A person",
"type":"object",
"properties":
{"name": {"type":"string"},
"age" : {"type":"integer",
"maximum":125}}
}
</pre></div>
<p>A JSON Schema object may have any of the following properties, called schema
attributes (all attributes are optional):
</p>
<a name="anchor9"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.1"></a><h3>5.1.
type</h3>
<p>
</p>
<blockquote class="text">
<p>Union type definition - An array with two or more items which indicates a union of type definitions. Each item in the array may be a simple type definition or a schema. The instance value is valid if it is of the same type as one the type definitions in the array or if it is valid by one of the schemas in the array. For example to indicate that a string or number is a valid:
{"type":["string","number"]}
</p>
<p>Simple type definition - A string indicating a primitive or simple type. The following are acceptable strings:
</p>
<blockquote class="text">
<p>string - Value must be a string.
</p>
<p>number - Value must be a number, floating point numbers are allowed.
</p>
<p>integer - Value must be an integer, no floating point numbers are allowed. This is a subset of the number type.
</p>
<p>boolean - Value must be a boolean.
</p>
<p>object - Value must be an object.
</p>
<p>array - Value must be an array.
</p>
<p>null - Value must be null. Note this is mainly for purpose of being able use union types to define nullability.
</p>
<p>any - Value may be of any type including null.
If the property is not defined or is not in this list, than any type of value is acceptable. Other type values may be used for custom purposes, but minimal validators of the specification implementation can allow any instance value on unknown type values.
</p>
</blockquote>
</blockquote><p>
</p>
<a name="anchor10"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.2"></a><h3>5.2.
properties</h3>
<p>This should be an object type definition, which is an object with property definitions that correspond to instance object properties. When the instance value is an object, the property values of the instance object must conform to the property definitions in this object. In this object, each property definition's value should be a schema, and the property's name should be the name of the instance property that it defines.
</p>
<a name="anchor11"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.3"></a><h3>5.3.
items</h3>
<p>This should be a schema or an array of schemas. When this is an object/schema and the instance value is an array, all the items in the array must conform to this schema. When this is an array of schemas and the instance value is an array, each position in the instance array must conform 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 additionalProperties attribute using the same rules as extra properties for objects..
</p>
<a name="anchor12"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.4"></a><h3>5.4.
optional</h3>
<p>This indicates that the instance property in the instance object is optional. This is false by default.
</p>
<a name="anchor13"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.5"></a><h3>5.5.
additionalProperties</h3>
<p>This provides a default property definition for all properties that are not explicitly defined in an object type definition. The value must be a schema. If false is provided, no additional properties are allowed, and the schema can not be extended. The default value is an empty schema which allows any value for additional properties.
</p>
<a name="anchor14"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.6"></a><h3>5.6.
requires</h3>
<p>This indicates that if this property is present in the containing instance object, the property given by requires attribute must also be present in the containing instance object. The value
of this property may be a string, indicating the require property name. Or the value may be a schema, in which case the containing instance must be valid by the schema if the property is present. For example if a object type definition is defined:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
{
"state":
{
"optional":true
},
"town":
{
"requires":"state",
"optional":true
}
}
</pre></div>
<p>An instance must include a state property if a town property is included. If a town property is not included, the state property is optional.
</p>
<a name="anchor15"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.7"></a><h3>5.7.
minimum</h3>
<p>This indicates the minimum value for the instance property when the type of the instance value is a number.
</p>
<a name="anchor16"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.8"></a><h3>5.8.
maximum</h3>
<p>This indicates the minimum value for the instance property when the type of the instance value is a number.
</p>
<a name="anchor17"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.9"></a><h3>5.9.
minimumCanEqual</h3>
<p>If the minimum is defined, this indicates whether or not the instance property value can equal the minimum.
</p>
<a name="anchor18"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.10"></a><h3>5.10.
maximumCanEqual</h3>
<p>If the maximum is defined, this indicates whether or not the instance property value can equal the maximum.
</p>
<a name="anchor19"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.11"></a><h3>5.11.
minItems</h3>
<p>This indicates the minimum number of values in an array when an array is the instance value.
</p>
<a name="anchor20"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.12"></a><h3>5.12.
maxItems</h3>
<p>This indicates the maximum number of values in an array when an array is the instance value.
</p>
<a name="anchor21"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.13"></a><h3>5.13.
pattern</h3>
<p>When the instance value is a string, this provides a regular expression that a instance string value should match in order to be valid. Regular expressions should follow the regular expression specification from ECMA 262/Perl 5
</p>
<a name="anchor22"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.14"></a><h3>5.14.
maxLength</h3>
<p>When the instance value is a string, this indicates maximum length of the string.
</p>
<a name="anchor23"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.15"></a><h3>5.15.
minLength</h3>
<p>When the instance value is a string, this indicates minimum length of the string.
</p>
<a name="anchor24"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.16"></a><h3>5.16.
enum</h3>
<p>This provides an enumeration of possible values that are valid for the instance property. This should be an array, and each item in the array represents a possible value for the instance value. If "enum" is included, the instance value must be one of the values in enum array in order for the schema to be valid.
</p>
<a name="anchor25"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.17"></a><h3>5.17.
title</h3>
<p>This provides a short description of the instance property. The value must be a string.
</p>
<a name="anchor26"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.18"></a><h3>5.18.
description</h3>
<p>This provides a full description of the of purpose the instance property. The value must be a string.
</p>
<a name="anchor27"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.19"></a><h3>5.19.
format</h3>
<p>This property indicates the type of data, content type, or microformat to be expected in the instance property values. A format attribute may be one of the values listed below, and if so, should adhere to the semantics describing for the format. A format should only be used give meaning to primitive types (string, integer, number, or boolean). Validators are not required to validate that the instance values conform to a format. The following formats are defined:
</p>
<blockquote class="text">
<p>Any valid MIME media type may be used as a format value, in which case the instance property value must be a string, representing the contents of the MIME file.
</p>
<p>date-time - This should be a date in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time. This is the recommended form of date/timestamp.
</p>
<p>date - This should be a date in the format of YYYY-MM-DD. It is recommended that you use the "date-time" format instead of "date" unless you need to transfer only the date part.
</p>
<p>time - This should be a time in the format of hh:mm:ss. It is recommended that you use the "date-time" format instead of "time" unless you need to transfer only the time part.
</p>
<p>utc-millisec - This should be the difference, measured in milliseconds, between the specified time and midnight, January 1, 1970 UTC. The value should be a number (integer or float).
</p>
<p>regex - A regular expression.
</p>
<p>color - This is a CSS color (like "#FF0000" or "red").
</p>
<p>style - This is a CSS style definition (like "color: red; background-color:#FFF").
</p>
<p>phone - This should be a phone number (format may follow E.123).
</p>
<p>uri - This value should be a URI..
</p>
<p>email - This should be an email address.
</p>
<p>ip-address - This should be an ip version 4 address.
</p>
<p>ipv6 - This should be an ip version 6 address.
</p>
<p>street-address - This should be a street address.
</p>
<p>locality - This should be a city or town.
</p>
<p>region - This should be a region (a state in the US, province in Canada, etc.)
</p>
<p>postal-code - This should be a postal code (AKA zip code).
</p>
<p>country - This should be the name of a country.
</p>
<p>Additional custom formats may be defined with a URL to a definition of the format.
</p>
</blockquote>
<a name="anchor28"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.20"></a><h3>5.20.
contentEncoding</h3>
<p>
If the instance property value is a string, this indicates that the string should be interpreted as binary data and decoded using the encoding named by this schema property. RFC 2045, Sec 6.1 lists possible values.
</p>
<a name="anchor29"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.21"></a><h3>5.21.
default</h3>
<p>This indicates the default for the instance property.
</p>
<a name="anchor30"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.22"></a><h3>5.22.
maxDecimal</h3>
<p>This indicates the maximum number of decimal places in a floating point number. By default there is no maximum.
</p>
<a name="anchor31"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.23"></a><h3>5.23.
disallow</h3>
<p>This attribute may take 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, than this instance is not valid.
</p>
<a name="anchor32"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5.24"></a><h3>5.24.
extends</h3>
<p>The value of this property should 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.
</p>
<a name="anchor33"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6"></a><h3>6.
Hyper Schema</h3>
<p>This section defines hypermedia definitions of JSON schema.
The following attributes are specified in addition to those
attributes that already provided by JSON schema with the specific
purpose of informing user agents of relations between resources based
on JSON data. Just as with JSON
schema attributes, all the attributes in hyper-schema are optional.
Therefore an empty object is a valid (non-informative) schema, and
essentially describes plain JSON (no constraints on the structures).
Addition of attributes provides additive information for user agents.
</p>
<a name="anchor34"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1"></a><h3>6.1.
links</h3>
<p>
The value of the links property should be an array, where each item
in the array is a link description object which describes the link
relations of the instances.
</p>
<a name="anchor35"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1.1"></a><h3>6.1.1.
Link Description Object</h3>
<p>
A link description object is used to describe the link relations
of instances of a schema.
</p>
<a name="anchor36"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1.1.1"></a><h3>6.1.1.1.
href</h3>
<p>
The value of the "href" link description property
indicates the target URI of the related resource. The value
of the instance property should be resolved as a URI-Reference per [RFC3986]
and may be a relative URI. The base URI to be used for relative resolution
should be the URI used to retrieve the instance object (not the schema).
Also, the URI may be parametrized by the property values of the instance
object.
</p>
<p>
Instance property values should be substituted into the URIs where
matching braces ('{', '}') are found surrounding zero or more characters,
creating an expanded URI. Instance property value substitutions are resolved
by using the text between the braces to denote the property name
from the instance to get the value to substitute. For example,
if an href value is defined:
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
http://somesite.com/{id}
</pre></div><p>
Then it would be resolved by replace the value of the "id" property value from
the instance object. If the value of the "id" property was "45", the expanded
URI would be:
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
http://somesite.com/45
</pre></div><p>
If matching braces are found with the string "-this" (no quotes) between the braces, than the
actual instance value should be used to replace the braces, rather than a property value.
This should only be used in situations where the instance is a scalar (string,
boolean, or number), and not for objects or arrays.
</p>
<a name="anchor37"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1.1.2"></a><h3>6.1.1.2.
rel</h3>
<p>
The value of the "rel" property indicates the name of the
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.
</p>
<p>
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 &rfc4287). However, we define these relation here for clarity of normative interpretation within the context of JSON hyper schema defined relations:
</p>
<blockquote class="text">
<p>
self - If the relation value is "self", when this property is encountered in
the instance object, the object represents a resource and the instance object is
treated as a full representation of the target resource identified by
the specified URI.
</p>
<p>
full - This indicates that the target of the link is the full representation for the instance object. The object that contains this link may not be the full representation.
</p>
<p>
describedby - 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.
</p>
<p>
The following relations are applicable for schemas (the schema as the "from" resource in the relation).
</p>
<p>
instances - This indicates the target resource that represents collection of instances of a schema.
</p>
<p>
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).
</p>
</blockquote><p>
For example, if a schema is defined:
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
{
"links": [
{
"rel": "self"
"href": "{id}"
},
{
"rel": "up"
"href": "{upId}"
},
{
"rel": "children"
"href": "?upId={id}"
}
]
}
</pre></div><p>
And if a collection of instance resource's JSON representation was
retrieved:
</p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
GET /Resource/
[
{
"id": "thing",
"upId": "parent"
},
{
"id": "thing2",
"upId": "parent"
}
]
</pre></div><p>
This would indicate that for the first item in the collection, it's own
(self) URI would resolve to "/Resource/thing" and the first item's "up"
relation should be resolved to the resource at "/Resource/parent".
The "children" collection would be located at "/Resource/?upId=thing".
</p>
<a name="anchor38"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1.1.3"></a><h3>6.1.1.3.
Submission Link Properties</h3>
<p>
The following properties also apply to link definition objects, and
provide functionality analogous to HTML forms, in providing a
means for submitting extra (often user supplied) information to send to a server.
</p>
<a name="anchor39"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1.1.3.1"></a><h3>6.1.1.3.1.
method</h3>
<p>
This indicates which method should be used to access the target resource.
In an HTTP environment, this would be "GET" or "POST" (other HTTP methods
such as "PUT" and "DELETE" have semantics that are clearly implied by
accessed resources, and do not need to be defined here).
This defaults to "GET".
</p>
<a name="anchor40"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1.1.3.2"></a><h3>6.1.1.3.2.
enctype</h3>
<p>
If present, this property indicates a query media type format that the server
supports for querying or posting to the collection of instances at the target
resource. The query can be
suffixed to the target URI to query the collection with
property-based constraints on the resources that SHOULD be returned from