forked from json-schema-org/json-schema-org.github.io
-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathjson-schema-hypermedia.html
2008 lines (1919 loc) · 138 KB
/
json-schema-hypermedia.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 XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head profile="http://www.w3.org/2006/03/hcard http://dublincore.org/documents/2008/08/04/dc-html/">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<title>JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON </title>
<style type="text/css" title="Xml2Rfc (sans serif)">
/*<![CDATA[*/
a {
text-decoration: none;
}
/* 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.smpl {
color: black;
}
a:hover {
text-decoration: underline;
}
a:active {
text-decoration: underline;
}
address {
margin-top: 1em;
margin-left: 2em;
font-style: normal;
}
body {
color: black;
font-family: verdana, helvetica, arial, sans-serif;
font-size: 10pt;
max-width: 55em;
}
cite {
font-style: normal;
}
dd {
margin-right: 2em;
}
dl {
margin-left: 2em;
}
ul.empty {
list-style-type: none;
}
ul.empty li {
margin-top: .5em;
}
dl p {
margin-left: 0em;
}
dt {
margin-top: .5em;
}
h1 {
font-size: 14pt;
line-height: 21pt;
page-break-after: avoid;
}
h1.np {
page-break-before: always;
}
h1 a {
color: #333333;
}
h2 {
font-size: 12pt;
line-height: 15pt;
page-break-after: avoid;
}
h3, h4, h5, h6 {
font-size: 10pt;
page-break-after: avoid;
}
h2 a, h3 a, h4 a, h5 a, h6 a {
color: black;
}
img {
margin-left: 3em;
}
li {
margin-left: 2em;
margin-right: 2em;
}
ol {
margin-left: 2em;
margin-right: 2em;
}
ol p {
margin-left: 0em;
}
p {
margin-left: 2em;
margin-right: 2em;
}
pre {
margin-left: 3em;
background-color: lightyellow;
padding: .25em;
}
pre.text2 {
border-style: dotted;
border-width: 1px;
background-color: #f0f0f0;
width: 69em;
}
pre.inline {
background-color: white;
padding: 0em;
}
pre.text {
border-style: dotted;
border-width: 1px;
background-color: #f8f8f8;
width: 69em;
}
pre.drawing {
border-style: solid;
border-width: 1px;
background-color: #f8f8f8;
padding: 2em;
}
table {
margin-left: 2em;
}
table.tt {
vertical-align: top;
}
table.full {
border-style: outset;
border-width: 1px;
}
table.headers {
border-style: outset;
border-width: 1px;
}
table.tt td {
vertical-align: top;
}
table.full td {
border-style: inset;
border-width: 1px;
}
table.tt th {
vertical-align: top;
}
table.full th {
border-style: inset;
border-width: 1px;
}
table.headers th {
border-style: none none inset none;
border-width: 1px;
}
table.left {
margin-right: auto;
}
table.right {
margin-left: auto;
}
table.center {
margin-left: auto;
margin-right: auto;
}
caption {
caption-side: bottom;
font-weight: bold;
font-size: 9pt;
margin-top: .5em;
}
table.header {
border-spacing: 1px;
width: 95%;
font-size: 10pt;
color: white;
}
td.top {
vertical-align: top;
}
td.topnowrap {
vertical-align: top;
white-space: nowrap;
}
table.header td {
background-color: gray;
width: 50%;
}
table.header a {
color: white;
}
td.reference {
vertical-align: top;
white-space: nowrap;
padding-right: 1em;
}
thead {
display:table-header-group;
}
ul.toc, ul.toc ul {
list-style: none;
margin-left: 1.5em;
margin-right: 0em;
padding-left: 0em;
}
ul.toc li {
line-height: 150%;
font-weight: bold;
font-size: 10pt;
margin-left: 0em;
margin-right: 0em;
}
ul.toc li li {
line-height: normal;
font-weight: normal;
font-size: 9pt;
margin-left: 0em;
margin-right: 0em;
}
li.excluded {
font-size: 0pt;
}
ul p {
margin-left: 0em;
}
.comment {
background-color: yellow;
}
.center {
text-align: center;
}
.error {
color: red;
font-style: italic;
font-weight: bold;
}
.figure {
font-weight: bold;
text-align: center;
font-size: 9pt;
}
.filename {
color: #333333;
font-weight: bold;
font-size: 12pt;
line-height: 21pt;
text-align: center;
}
.fn {
font-weight: bold;
}
.hidden {
display: none;
}
.left {
text-align: left;
}
.right {
text-align: right;
}
.title {
color: #990000;
font-size: 18pt;
line-height: 18pt;
font-weight: bold;
text-align: center;
margin-top: 36pt;
}
.vcardline {
display: block;
}
.warning {
font-size: 14pt;
background-color: yellow;
}
@media print {
.noprint {
display: none;
}
a {
color: black;
text-decoration: none;
}
table.header {
width: 90%;
}
td.header {
width: 50%;
color: black;
background-color: white;
vertical-align: top;
font-size: 12pt;
}
ul.toc a::after {
content: leader('.') target-counter(attr(href), page);
}
ul.ind li li a {
content: target-counter(attr(href), page);
}
.print2col {
column-count: 2;
-moz-column-count: 2;
column-fill: auto;
}
}
@page {
@top-left {
content: "Internet-Draft";
}
@top-right {
content: "December 2010";
}
@top-center {
content: "Abbreviated Title";
}
@bottom-left {
content: "Doe";
}
@bottom-center {
content: "Expires June 2011";
}
@bottom-right {
content: "[Page " counter(page) "]";
}
}
@page:first {
@top-left {
content: normal;
}
@top-right {
content: normal;
}
@top-center {
content: normal;
}
}
/*]]>*/
</style>
<link href="#rfc.toc" rel="Contents">
<link href="#rfc.section.1" rel="Chapter" title="1 Introduction">
<link href="#rfc.section.2" rel="Chapter" title="2 Notational Conventions">
<link href="#rfc.section.3" rel="Chapter" title="3 Overview">
<link href="#rfc.section.3.1" rel="Chapter" title="3.1 Terminology">
<link href="#rfc.section.3.2" rel="Chapter" title="3.2 Functionality">
<link href="#rfc.section.4" rel="Chapter" title="4 Meta-Schemas and Output Schema">
<link href="#rfc.section.5" rel="Chapter" title="5 Schema Keywords">
<link href="#rfc.section.5.1" rel="Chapter" title="5.1 base">
<link href="#rfc.section.5.2" rel="Chapter" title="5.2 links">
<link href="#rfc.section.6" rel="Chapter" title="6 Link Description Object">
<link href="#rfc.section.6.1" rel="Chapter" title="6.1 Link Context">
<link href="#rfc.section.6.1.1" rel="Chapter" title="6.1.1 anchor">
<link href="#rfc.section.6.1.2" rel="Chapter" title="6.1.2 anchorPointer">
<link href="#rfc.section.6.2" rel="Chapter" title="6.2 Link Relation Type">
<link href="#rfc.section.6.2.1" rel="Chapter" title="6.2.1 rel">
<link href="#rfc.section.6.2.2" rel="Chapter" title='6.2.2 "self" Links'>
<link href="#rfc.section.6.2.3" rel="Chapter" title='6.2.3 "collection" and "item" Links'>
<link href="#rfc.section.6.2.4" rel="Chapter" title="6.2.4 Using Extension Relation Types">
<link href="#rfc.section.6.3" rel="Chapter" title="6.3 Link Target">
<link href="#rfc.section.6.3.1" rel="Chapter" title="6.3.1 href">
<link href="#rfc.section.6.4" rel="Chapter" title="6.4 Adjusting URI Template Resolution">
<link href="#rfc.section.6.4.1" rel="Chapter" title="6.4.1 templatePointers">
<link href="#rfc.section.6.4.2" rel="Chapter" title="6.4.2 templateRequired">
<link href="#rfc.section.6.5" rel="Chapter" title="6.5 Link Target Attributes">
<link href="#rfc.section.6.5.1" rel="Chapter" title="6.5.1 title">
<link href="#rfc.section.6.5.2" rel="Chapter" title="6.5.2 description">
<link href="#rfc.section.6.5.3" rel="Chapter" title="6.5.3 targetMediaType">
<link href="#rfc.section.6.5.4" rel="Chapter" title="6.5.4 targetSchema">
<link href="#rfc.section.6.5.5" rel="Chapter" title="6.5.5 targetHints">
<link href="#rfc.section.6.6" rel="Chapter" title="6.6 Link Input">
<link href="#rfc.section.6.6.1" rel="Chapter" title="6.6.1 hrefSchema">
<link href="#rfc.section.6.6.2" rel="Chapter" title="6.6.2 headerSchema">
<link href="#rfc.section.6.6.3" rel="Chapter" title="6.6.3 Manipulating the Target Resource Representation">
<link href="#rfc.section.6.6.4" rel="Chapter" title="6.6.4 Submitting Data for Processing">
<link href="#rfc.section.7" rel="Chapter" title="7 Implementation Requirements">
<link href="#rfc.section.7.1" rel="Chapter" title="7.1 Link Discovery and Look-Up">
<link href="#rfc.section.7.2" rel="Chapter" title="7.2 URI Templating">
<link href="#rfc.section.7.2.1" rel="Chapter" title="7.2.1 Populating Template Data From the Instance">
<link href="#rfc.section.7.2.2" rel="Chapter" title="7.2.2 Accepting Input for Template Data">
<link href="#rfc.section.7.2.3" rel="Chapter" title="7.2.3 Encoding Data as Strings">
<link href="#rfc.section.7.3" rel="Chapter" title="7.3 Providing Access to LDO Keywords">
<link href="#rfc.section.7.4" rel="Chapter" title="7.4 Requests">
<link href="#rfc.section.7.5" rel="Chapter" title="7.5 Responses">
<link href="#rfc.section.7.6" rel="Chapter" title="7.6 Streaming Parsers">
<link href="#rfc.section.8" rel="Chapter" title="8 JSON Hyper-Schema and HTTP">
<link href="#rfc.section.8.1" rel="Chapter" title="8.1 One Link Per Target and Relation Type">
<link href="#rfc.section.8.2" rel="Chapter" title='8.2 "targetSchema" and HTTP'>
<link href="#rfc.section.8.3" rel="Chapter" title='8.3 HTTP POST and the "submission*" keywords'>
<link href="#rfc.section.8.4" rel="Chapter" title='8.4 Optimizing HTTP Discoverability With "targetHints"'>
<link href="#rfc.section.8.5" rel="Chapter" title='8.5 Advertising HTTP Features With "headerSchema"'>
<link href="#rfc.section.8.6" rel="Chapter" title="8.6 Creating Resources Through Collections">
<link href="#rfc.section.8.7" rel="Chapter" title="8.7 Content Negotiation and Schema Evolution">
<link href="#rfc.section.9" rel="Chapter" title="9 Examples">
<link href="#rfc.section.9.1" rel="Chapter" title="9.1 Entry Point Links, No Templates">
<link href="#rfc.section.9.2" rel="Chapter" title="9.2 Individually Identified Resources">
<link href="#rfc.section.9.3" rel="Chapter" title="9.3 Submitting a Payload and Accepting URI Input">
<link href="#rfc.section.9.4" rel="Chapter" title='9.4 "anchor", "base" and URI Template Resolution'>
<link href="#rfc.section.9.5" rel="Chapter" title="9.5 Collections">
<link href="#rfc.section.9.5.1" rel="Chapter" title="9.5.1 Pagination">
<link href="#rfc.section.9.5.2" rel="Chapter" title="9.5.2 Creating the First Item">
<link href="#rfc.section.10" rel="Chapter" title="10 Security Considerations">
<link href="#rfc.section.10.1" rel="Chapter" title="10.1 Target Attributes">
<link href="#rfc.section.10.2" rel="Chapter" title='10.2 "self" Links'>
<link href="#rfc.section.11" rel="Chapter" title="11 Acknowledgments">
<link href="#rfc.references" rel="Chapter" title="12 References">
<link href="#rfc.references.1" rel="Chapter" title="12.1 Normative References">
<link href="#rfc.references.2" rel="Chapter" title="12.2 Informative References">
<link href="#rfc.appendix.A" rel="Chapter" title="A Using JSON Hyper-Schema in APIs">
<link href="#rfc.appendix.A.1" rel="Chapter" title="A.1 Resource Evolution With Hyper-Schema">
<link href="#rfc.appendix.A.2" rel="Chapter" title="A.2 Responses and Errors">
<link href="#rfc.appendix.A.3" rel="Chapter" title="A.3 Static Analysis of an API's Hyper-Schemas">
<link href="#rfc.appendix.B" rel="Chapter" title="B ChangeLog">
<link href="#rfc.authors" rel="Chapter">
<meta name="generator" content="xml2rfc version 2.20.1 - https://tools.ietf.org/tools/xml2rfc" />
<link rel="schema.dct" href="http://purl.org/dc/terms/" />
<meta name="dct.creator" content="Andrews, H., Ed. and A. Wright, Ed." />
<meta name="dct.identifier" content="urn:ietf:id:draft-handrews-json-schema-hyperschema-02" />
<meta name="dct.issued" scheme="ISO8601" content="2019-17" />
<meta name="dct.abstract" content="JSON Schema is a JSON-based format for describing JSON data using various vocabularies. This document specifies a vocabulary for annotating JSON documents with hyperlinks. These hyperlinks include attributes describing how to manipulate and interact with remote resources through hypermedia environments such as HTTP, as well as determining whether the link is usable based on the instance value. The hyperlink serialization format described in this document is also usable independent of JSON Schema. " />
<meta name="description" content="JSON Schema is a JSON-based format for describing JSON data using various vocabularies. This document specifies a vocabulary for annotating JSON documents with hyperlinks. These hyperlinks include attributes describing how to manipulate and interact with remote resources through hypermedia environments such as HTTP, as well as determining whether the link is usable based on the instance value. The hyperlink serialization format described in this document is also usable independent of JSON Schema. " />
</head>
<body>
<table class="header">
<tbody>
<tr>
<td class="left">Internet Engineering Task Force</td>
<td class="right">H. Andrews, Ed.</td>
</tr>
<tr>
<td class="left">Internet-Draft</td>
<td class="right"></td>
</tr>
<tr>
<td class="left">Intended status: Informational</td>
<td class="right">A. Wright, Ed.</td>
</tr>
<tr>
<td class="left">Expires: March 20, 2020</td>
<td class="right">September 17, 2019</td>
</tr>
</tbody>
</table>
<p class="title">JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON <br />
<span class="filename">draft-handrews-json-schema-hyperschema-02</span></p>
<h1 id="rfc.abstract"><a href="#rfc.abstract">Abstract</a></h1>
<p>JSON Schema is a JSON-based format for describing JSON data using various vocabularies. This document specifies a vocabulary for annotating JSON documents with hyperlinks. These hyperlinks include attributes describing how to manipulate and interact with remote resources through hypermedia environments such as HTTP, as well as determining whether the link is usable based on the instance value. The hyperlink serialization format described in this document is also usable independent of JSON Schema. </p>
<h1><a>Note to Readers</a></h1>
<p>The issues list for this draft can be found at <span><</span><a href="https://github.com/json-schema-org/json-schema-spec/issues">https://github.com/json-schema-org/json-schema-spec/issues</a><span>></span>. </p>
<p>For additional information, see <span><</span><a href="https://json-schema.org/">https://json-schema.org/</a><span>></span>. </p>
<p>To provide feedback, use this issue tracker, the communication methods listed on the homepage, or email the document editors. </p>
<h1 id="rfc.status"><a href="#rfc.status">Status of This Memo</a></h1>
<p>This Internet-Draft is submitted 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). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.</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>This Internet-Draft will expire on March 20, 2020.</p>
<h1 id="rfc.copyrightnotice"><a href="#rfc.copyrightnotice">Copyright Notice</a></h1>
<p>Copyright (c) 2019 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 (https://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 Simplified BSD License.</p>
<hr class="noprint" />
<h1 class="np" id="rfc.toc"><a href="#rfc.toc">Table of Contents</a></h1>
<ul class="toc">
<li>1. <a href="#rfc.section.1">Introduction</a>
</li>
<li>2. <a href="#rfc.section.2">Notational Conventions</a>
</li>
<li>3. <a href="#rfc.section.3">Overview</a>
</li>
<ul><li>3.1. <a href="#rfc.section.3.1">Terminology</a>
</li>
<li>3.2. <a href="#rfc.section.3.2">Functionality</a>
</li>
</ul><li>4. <a href="#rfc.section.4">Meta-Schemas and Output Schema</a>
</li>
<li>5. <a href="#rfc.section.5">Schema Keywords</a>
</li>
<ul><li>5.1. <a href="#rfc.section.5.1">base</a>
</li>
<li>5.2. <a href="#rfc.section.5.2">links</a>
</li>
</ul><li>6. <a href="#rfc.section.6">Link Description Object</a>
</li>
<ul><li>6.1. <a href="#rfc.section.6.1">Link Context</a>
</li>
<ul><li>6.1.1. <a href="#rfc.section.6.1.1">anchor</a>
</li>
<li>6.1.2. <a href="#rfc.section.6.1.2">anchorPointer</a>
</li>
</ul><li>6.2. <a href="#rfc.section.6.2">Link Relation Type</a>
</li>
<ul><li>6.2.1. <a href="#rfc.section.6.2.1">rel</a>
</li>
<li>6.2.2. <a href="#rfc.section.6.2.2">"self" Links</a>
</li>
<li>6.2.3. <a href="#rfc.section.6.2.3">"collection" and "item" Links</a>
</li>
<li>6.2.4. <a href="#rfc.section.6.2.4">Using Extension Relation Types</a>
</li>
</ul><li>6.3. <a href="#rfc.section.6.3">Link Target</a>
</li>
<ul><li>6.3.1. <a href="#rfc.section.6.3.1">href</a>
</li>
</ul><li>6.4. <a href="#rfc.section.6.4">Adjusting URI Template Resolution</a>
</li>
<ul><li>6.4.1. <a href="#rfc.section.6.4.1">templatePointers</a>
</li>
<li>6.4.2. <a href="#rfc.section.6.4.2">templateRequired</a>
</li>
</ul><li>6.5. <a href="#rfc.section.6.5">Link Target Attributes</a>
</li>
<ul><li>6.5.1. <a href="#rfc.section.6.5.1">title</a>
</li>
<li>6.5.2. <a href="#rfc.section.6.5.2">description</a>
</li>
<li>6.5.3. <a href="#rfc.section.6.5.3">targetMediaType</a>
</li>
<li>6.5.4. <a href="#rfc.section.6.5.4">targetSchema</a>
</li>
<li>6.5.5. <a href="#rfc.section.6.5.5">targetHints</a>
</li>
</ul><li>6.6. <a href="#rfc.section.6.6">Link Input</a>
</li>
<ul><li>6.6.1. <a href="#rfc.section.6.6.1">hrefSchema</a>
</li>
<li>6.6.2. <a href="#rfc.section.6.6.2">headerSchema</a>
</li>
<li>6.6.3. <a href="#rfc.section.6.6.3">Manipulating the Target Resource Representation</a>
</li>
<li>6.6.4. <a href="#rfc.section.6.6.4">Submitting Data for Processing</a>
</li>
</ul></ul><li>7. <a href="#rfc.section.7">Implementation Requirements</a>
</li>
<ul><li>7.1. <a href="#rfc.section.7.1">Link Discovery and Look-Up</a>
</li>
<li>7.2. <a href="#rfc.section.7.2">URI Templating</a>
</li>
<ul><li>7.2.1. <a href="#rfc.section.7.2.1">Populating Template Data From the Instance</a>
</li>
<li>7.2.2. <a href="#rfc.section.7.2.2">Accepting Input for Template Data</a>
</li>
<li>7.2.3. <a href="#rfc.section.7.2.3">Encoding Data as Strings</a>
</li>
</ul><li>7.3. <a href="#rfc.section.7.3">Providing Access to LDO Keywords</a>
</li>
<li>7.4. <a href="#rfc.section.7.4">Requests</a>
</li>
<li>7.5. <a href="#rfc.section.7.5">Responses</a>
</li>
<li>7.6. <a href="#rfc.section.7.6">Streaming Parsers</a>
</li>
</ul><li>8. <a href="#rfc.section.8">JSON Hyper-Schema and HTTP</a>
</li>
<ul><li>8.1. <a href="#rfc.section.8.1">One Link Per Target and Relation Type</a>
</li>
<li>8.2. <a href="#rfc.section.8.2">"targetSchema" and HTTP</a>
</li>
<li>8.3. <a href="#rfc.section.8.3">HTTP POST and the "submission*" keywords</a>
</li>
<li>8.4. <a href="#rfc.section.8.4">Optimizing HTTP Discoverability With "targetHints"</a>
</li>
<li>8.5. <a href="#rfc.section.8.5">Advertising HTTP Features With "headerSchema"</a>
</li>
<li>8.6. <a href="#rfc.section.8.6">Creating Resources Through Collections</a>
</li>
<li>8.7. <a href="#rfc.section.8.7">Content Negotiation and Schema Evolution</a>
</li>
</ul><li>9. <a href="#rfc.section.9">Examples</a>
</li>
<ul><li>9.1. <a href="#rfc.section.9.1">Entry Point Links, No Templates</a>
</li>
<li>9.2. <a href="#rfc.section.9.2">Individually Identified Resources</a>
</li>
<li>9.3. <a href="#rfc.section.9.3">Submitting a Payload and Accepting URI Input</a>
</li>
<li>9.4. <a href="#rfc.section.9.4">"anchor", "base" and URI Template Resolution</a>
</li>
<li>9.5. <a href="#rfc.section.9.5">Collections</a>
</li>
<ul><li>9.5.1. <a href="#rfc.section.9.5.1">Pagination</a>
</li>
<li>9.5.2. <a href="#rfc.section.9.5.2">Creating the First Item</a>
</li>
</ul></ul><li>10. <a href="#rfc.section.10">Security Considerations</a>
</li>
<ul><li>10.1. <a href="#rfc.section.10.1">Target Attributes</a>
</li>
<li>10.2. <a href="#rfc.section.10.2">"self" Links</a>
</li>
</ul><li>11. <a href="#rfc.section.11">Acknowledgments</a>
</li>
<li>12. <a href="#rfc.references">References</a>
</li>
<ul><li>12.1. <a href="#rfc.references.1">Normative References</a>
</li>
<li>12.2. <a href="#rfc.references.2">Informative References</a>
</li>
</ul><li>Appendix A. <a href="#rfc.appendix.A">Using JSON Hyper-Schema in APIs</a>
</li>
<ul><li>A.1. <a href="#rfc.appendix.A.1">Resource Evolution With Hyper-Schema</a>
</li>
<li>A.2. <a href="#rfc.appendix.A.2">Responses and Errors</a>
</li>
<li>A.3. <a href="#rfc.appendix.A.3">Static Analysis of an API's Hyper-Schemas</a>
</li>
</ul><li>Appendix B. <a href="#rfc.appendix.B">ChangeLog</a>
</li>
<li><a href="#rfc.authors">Authors' Addresses</a>
</li>
</ul>
<h1 id="rfc.section.1">
<a href="#rfc.section.1">1.</a> Introduction</h1>
<p id="rfc.section.1.p.1">JSON Hyper-Schema is a JSON Schema vocabulary for annotating JSON documents with hyperlinks and instructions for processing and manipulating remote JSON resources through hypermedia environments such as HTTP. </p>
<p id="rfc.section.1.p.2">The term JSON Hyper-Schema is used to refer to a JSON Schema that uses these keywords. The term "hyper-schema" on its own refers to a JSON Hyper-Schema within the scope of this specification. </p>
<p id="rfc.section.1.p.3">The primary mechanism introduced for specifying links is the Link Description Object (LDO), which is a serialization of the abstract link model defined in <a href="#RFC8288" class="xref">RFC 8288, section 2</a>. </p>
<p id="rfc.section.1.p.4">This specification will use the concepts, syntax, and terminology defined by the <a href="#json-schema" class="xref">JSON Schema core</a> and <a href="#json-schema-validation" class="xref">JSON Schema validation</a> specifications. It is advised that readers have a copy of these specifications. </p>
<h1 id="rfc.section.2">
<a href="#rfc.section.2">2.</a> Notational Conventions</h1>
<p id="rfc.section.2.p.1">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 <a href="#RFC2119" class="xref">RFC 2119</a>. </p>
<h1 id="rfc.section.3">
<a href="#rfc.section.3">3.</a> Overview</h1>
<p id="rfc.section.3.p.1">JSON Hyper-Schema makes it possible to build hypermedia systems from JSON documents by describing how to construct hyperlinks from instance data. </p>
<p id="rfc.section.3.p.2">The combination of a JSON instance document and a valid application/schema+json hyper-schema for that instance behaves as a single hypermedia representation. By allowing this separation, hyper-schema-based systems can gracefully support applications that expect plain JSON, while providing full hypermedia capabilities for hyper-schema-aware applications and user agents. </p>
<p id="rfc.section.3.p.3">User agents can detect the presence of hyper-schema by looking for the application/schema+json media type and a "$schema" value that indicates the presence of the hyper-schema vocabulary. A user agent can then use an implementation of JSON Hyper-Schema to provide an interface to the combination of the schema and instance documents as a single logical representation of a resource, just as with any single-document hypermedia representation format. </p>
<p id="rfc.section.3.p.4">Hyper-schemas allow representations to take up fewer bytes on the wire, and distribute the burden of link construction from the server to each client. A user agent need not construct a link unless a client application requests that link. JSON Hyper-Schema can also be used on the server side to generate other link serializations or representation formats at runtime, or pre-emptively follow links to facilitate server push usage. </p>
<p>Here is an example hyper-schema that adds a single link, with the IANA-registered link relation type "self", that is built from an instance with one known object field named "id": </p>
<pre>
{
"type": "object",
"properties": {
"id": {
"type": "number",
"readOnly": true
}
},
"links": [
{
"rel": "self",
"href": "thing/{id}"
}
]
}
</pre>
<p>If the instance is {"id": 1234}, and its base URI according to <a href="#RFC3986" class="xref">RFC 3986 section 5.1</a>, is "https://example.com/api/", then "https://example.com/api/thing/1234" is the resulting link's target URI. </p>
<h1 id="rfc.section.3.1">
<a href="#rfc.section.3.1">3.1.</a> Terminology</h1>
<p id="rfc.section.3.1.p.1">The terms "schema", "instance", and "meta-schema" are to be interpreted as defined in the <a href="#json-schema" class="xref">JSON Schema core specification</a>. </p>
<p id="rfc.section.3.1.p.2">The terms "applicable" and "attached" are to be interpreted as defined in <a href="#json-schema" class="xref">Section 3.1 of the JSON Schema core specification</a>. </p>
<p id="rfc.section.3.1.p.3">The terms "link", "link context" (or "context"), "link target" (or "target"), and "target attributes" are to be interpreted as defined in <a href="#RFC8288" class="xref">Section 2 of RFC 8288</a>. </p>
<p id="rfc.section.3.1.p.4">The term "user agent" is to be interpreted as defined in <a href="#RFC7230" class="xref">Section 2.1 of RFC 7230</a>, generalized to apply to any protocol that may be used in a hypermedia system rather than specifically being an HTTP client. </p>
<p id="rfc.section.3.1.p.5">This specification defines the following terms: </p>
<dl>
<dt>JSON Hyper-Schema</dt>
<dd style="margin-left: 8">A JSON Schema using the keywords defined by this specification. </dd>
<dt>hyper-schema</dt>
<dd style="margin-left: 8">Within this document, the term "hyper-schema" always refers to a JSON Hyper-Schema </dd>
<dt>link validity</dt>
<dd style="margin-left: 8">A valid link for an instance is one that is applicable to that instance and does not fail any requirement imposed by the keywords in the Link Description Object. Note that invalid links can occur when using keywords such as "if" or "oneOf" (from the Core specification) to describe links that are conditional on the representation's structure or value. </dd>
<dt>generic user agent</dt>
<dd style="margin-left: 8">A user agent which can be used to interact with any resource, from any server, from among the standardized link relations, media types, URI schemes, and protocols that it supports; though it may be extendible to specially handle particular profiles of media types. </dd>
<dt>client application</dt>
<dd style="margin-left: 8">An application which uses a hypermedia system for a specific purpose. Such an application may also be its own user agent, or it may be built on top of a generic user agent. A client application is programmed with knowledge of link relations, media types, URI schemes, protocols, and data structures that are specific to the application's domain. </dd>
<dt>client input</dt>
<dd style="margin-left: 8">Data provided through a user agent, and most often also through a client application. Such data may be requested from a user interactively, or provided before interaction in forms such as command-line arguments, configuration files, or hardcoded values in source code. </dd>
<dt>operation</dt>
<dd style="margin-left: 8">A specific use of a hyperlink, such as making a network request (for a URI with a scheme such as "http://" that indicates a protocol) or otherwise taking action based on a link (reading data from a "data:" URI, or constructing an email message based on a "mailto:" link). For protocols such as HTTP that support multiple methods, each method is considered to be a separate operation on the same link. </dd>
</dl>
<p> </p>
<h1 id="rfc.section.3.2">
<a href="#rfc.section.3.2">3.2.</a> Functionality</h1>
<p id="rfc.section.3.2.p.1">A JSON Hyper-Schema implementation is able to take a hyper-schema, an instance, and in some cases client input, and produce a set of fully resolved valid links. As defined by <a href="#RFC8288" class="xref">RFC 8288, section 2</a>, a link consists of a context, a typed relation, a target, and optionally additional target attributes. </p>
<p id="rfc.section.3.2.p.2">The relation type and target attributes are taken directly from each link's Link Description Object. The context and target identifiers are constructed from some combination of URI Templates, instance data, and (in the case of the target identifier) client input. </p>
<p id="rfc.section.3.2.p.3">The target is always fully identified by a URI. Due to the lack of a URI fragment identifier syntax for application/json and many other media types that can be used with JSON Hyper-Schema, the context may be only partially identified by a URI. In such cases, the remaining identification will be provided as a JSON Pointer. </p>
<p id="rfc.section.3.2.p.4">A few IANA-registered link relation types are given specific semantics in a JSON Hyper-Schema document. A "self" link is used to interact with the resource that the instance document represents, while "collection" and "item" links identify resources for which collection-specific semantics can be assumed. </p>
<h1 id="rfc.section.4">
<a href="#rfc.section.4">4.</a> Meta-Schemas and Output Schema</h1>
<p id="rfc.section.4.p.1">The current URI for the JSON Hyper-Schema meta-schema is <span><</span><a href="https://json-schema.org/draft/2019-09/hyper-schema#">https://json-schema.org/draft/2019-09/hyper-schema#</a><span>></span>. </p>
<p id="rfc.section.4.p.2">The current URI for this vocabulary, known as the Hyper-Schema vocabulary, is: <span><</span><a href="https://json-schema.org/draft/2019-09/vocab/hyper-schema">https://json-schema.org/draft/2019-09/vocab/hyper-schema</a><span>></span>. </p>
<p id="rfc.section.4.p.3">The current URI for the corresponding meta-schema, which differs from the convenience meta-schema above in that it describes only the hyper-schema keywords ("base" and "link") is: <span><</span><a href="https://json-schema.org/draft/2019-09/meta/hyper-schema">https://json-schema.org/draft/2019-09/meta/hyper-schema</a><span>></span>. </p>
<p id="rfc.section.4.p.4">The <a href="#ldo" class="xref">link description format</a> can be used without JSON Schema, and use of this format can be declared by referencing the normative link description schema as the schema for the data structure that uses the links. The URI of the normative link description schema is: <span><</span><a href="https://json-schema.org/draft/2019-09/links#">https://json-schema.org/draft/2019-09/links#</a><span>></span>. </p>
<p id="rfc.section.4.p.5">JSON Hyper-Schema implementations are free to provide output in any format. However, a specific format is defined for use in the conformance test suite, which is also used to illustrate points in the <a href="#implementation" class="xref">"Implementation Requirements"</a>, and to show the output generated by <a href="#examples" class="xref">examples</a>. It is RECOMMENDED that implementations be capable of producing output in this format to facilitated testing. The URI of the JSON Schema describing the recommended output format is <span><</span><a href="https://json-schema.org/draft/2019-09/output/hyper-schema#">https://json-schema.org/draft/2019-09/output/hyper-schema#</a><span>></span>. </p>
<p id="rfc.section.4.p.6">Updated vocabulary and meta-schema URIs MAY be published between specification drafts in order to correct errors. Implementations SHOULD consider URIs dated after this specification draft and before the next to indicate the same syntax and semantics as those listed here. </p>
<h1 id="rfc.section.5">
<a href="#rfc.section.5">5.</a> Schema Keywords</h1>
<p id="rfc.section.5.p.1">Hyper-schema keywords from all schemas that are applicable to a position in an instance, as defined by <a href="#json-schema" class="xref">Section 3.1 of JSON Schema core</a>, can be used with that instance. </p>
<p id="rfc.section.5.p.2">When multiple subschemas are applicable to a given sub-instance, all "link" arrays MUST be combined, in any order, into a single set. Each object in the resulting set MUST retain its own list of applicable "base" values, in resolution order, from the same schema and any parent schemas. </p>
<p id="rfc.section.5.p.3">As with all JSON Schema keywords, all keywords described in this section are optional. The minimal valid JSON Hyper-schema is the blank object. </p>
<h1 id="rfc.section.5.1">
<a href="#rfc.section.5.1">5.1.</a> <a href="#base" id="base">base</a>
</h1>
<p id="rfc.section.5.1.p.1">If present, this keyword MUST be first <a href="#uriTemplating" class="xref">resolved as a URI Template</a>, and then MUST be resolved as a URI Reference against the current URI base of the instance. The result MUST be set as the new URI base for the instance while processing the sub-schema containing "base" and all sub-schemas within it. </p>
<p id="rfc.section.5.1.p.2">The process for resolving the "base" template can be different when being resolved for use with "anchor" than when being resolved for use with "href", which is explained in detail in the URI Templating section. </p>
<h1 id="rfc.section.5.2">
<a href="#rfc.section.5.2">5.2.</a> links</h1>
<p id="rfc.section.5.2.p.1">The "links" property of schemas is used to associate Link Description Objects with instances. The value of this property MUST be an array, and the items in the array must be Link Description Objects, as defined below. </p>
<h1 id="rfc.section.6">
<a href="#rfc.section.6">6.</a> <a href="#ldo" id="ldo">Link Description Object</a>
</h1>
<p id="rfc.section.6.p.1">A Link Description Object (LDO) is a serialization of the abstract link model defined in <a href="#RFC8288" class="xref">RFC 8288, section 2</a>. As described in that document, a link consists of a context, a relation type, a target, and optionally target attributes. JSON Hyper-Schema's LDO provides all of these, along with additional features using JSON Schema to describe input for use with the links in various ways. </p>
<p id="rfc.section.6.p.2">Due to the use of URI Templates to identify link contexts and targets, as well as optional further use of client input when identifying targets, an LDO is a link template that may resolve to multiple links when used with a JSON instance document. </p>
<p id="rfc.section.6.p.3">A specific use of an LDO, typically involving a request and response across a protocol, is referred to as an operation. For many protocols, multiple operations are possible on any given link. The protocol is indicated by the target's URI scheme. Note that not all URI schemes indicate a protocol that can be used for communications, and even resources with URI schemes that do indicate such protocols need not be available over that protocol. </p>
<p id="rfc.section.6.p.4">A Link Description Object MUST be an object, and the <a href="#href" class="xref">"href"</a> and <a href="#rel" class="xref">"rel"</a> properties MUST be present. Each keyword is covered briefly in this section, with additional usage explanation and comprehensive examples given later in the document. </p>
<h1 id="rfc.section.6.1">
<a href="#rfc.section.6.1">6.1.</a> <a href="#context" id="context">Link Context</a>
</h1>
<p id="rfc.section.6.1.p.1">In JSON Hyper-Schema, the link's context resource is, by default, the sub-instance to which it is attached (as defined by <a href="#json-schema" class="xref">Section 3.1 of the JSON Schema core specification</a>). This is often not the entire instance document. This default context can be changed using the keywords in this section. </p>
<p id="rfc.section.6.1.p.2">Depending on the media type of the instance, it may or may not be possible to assign a URI to the exact default context resource. In particular, application/json does not define a URI fragment resolution syntax, so properties or array elements within a plain JSON document cannot be fully identified by a URI. When it is not possible to produce a complete URI, the position of the context SHOULD be conveyed by the URI of the instance document, together with a separate plain-string JSON Pointer. </p>
<p id="rfc.section.6.1.p.3">Implementations MUST be able to construct the link context's URI, and (if necessary for full identification), a JSON Pointer in string representation form as per <a href="#RFC6901" class="xref">RFC 6901, section 5</a> in place of a URI fragment. The process for constructing a URI based on a URI template is given in the <a href="#uriTemplating" class="xref">URI Templating</a> section. </p>
<h1 id="rfc.section.6.1.1">
<a href="#rfc.section.6.1.1">6.1.1.</a> <a href="#anchor" id="anchor">anchor</a>
</h1>
<p id="rfc.section.6.1.1.p.1">This property sets the context URI of the link. The value of the property is a <a href="#RFC6570" class="xref">URI Template</a>, and the resulting <a href="#RFC3986" class="xref">URI-reference</a> MUST be resolved against the base URI of the instance. </p>
<p id="rfc.section.6.1.1.p.2">The URI is computed from the provided URI template using the same process described for the <a href="#href" class="xref">"href"</a> property, with the exception that <a href="#hrefSchema" class="xref">"hrefSchema"</a> MUST NOT be applied. Unlike target URIs, context URIs do not accept user input. </p>
<h1 id="rfc.section.6.1.2">
<a href="#rfc.section.6.1.2">6.1.2.</a> <a href="#anchorPointer" id="anchorPointer">anchorPointer</a>
</h1>
<p id="rfc.section.6.1.2.p.1">This property changes the point within the instance that is considered to be the context resource of the link. The value of the property MUST be a valid JSON Pointer in JSON String representation form, or a valid <a href="#relative-json-pointer" class="xref">Relative JSON Pointer</a> which is evaluated relative to the default context. </p>
<p id="rfc.section.6.1.2.p.2">While an alternate context with a known URI is best set with the <a href="#anchor" class="xref">"anchor"</a> keyword, the lack of a fragment identifier syntax for application/json means that it is usually not possible to change the context within a JSON instance using a URI. </p>
<p id="rfc.section.6.1.2.p.3">Even in "+json" media types that define JSON Pointer as a fragment identifier syntax, if the default context is nested within an array, it is not possible to obtain the index of the default context's position in that array in order to construct a pointer to another property in that same nested JSON object. This will be demonstrated in the examples. </p>
<p id="rfc.section.6.1.2.p.4">The result of processing this keyword SHOULD be a URI fragment if the media type of the instance allows for such a fragment. Otherwise it MUST be a string-encoded JSON Pointer. </p>
<h1 id="rfc.section.6.2">
<a href="#rfc.section.6.2">6.2.</a> <a href="#relationType" id="relationType">Link Relation Type</a>
</h1>
<p id="rfc.section.6.2.p.1">The link's relation type identifies its semantics. It is the primary means of conveying how an application can interact with a resource. </p>
<p id="rfc.section.6.2.p.2">Relationship definitions are not normally media type dependent, and users are encouraged to utilize the most suitable existing accepted relation definitions. </p>
<h1 id="rfc.section.6.2.1">
<a href="#rfc.section.6.2.1">6.2.1.</a> <a href="#rel" id="rel">rel</a>
</h1>
<p id="rfc.section.6.2.1.p.1">The value of this property MUST be either a string or an array of strings. If the value is an array, it MUST contain at least one string. </p>
<p id="rfc.section.6.2.1.p.2">Each string MUST be a single Link Relation Type as defined in RFC 8288, Section 2.1, including the restriction that additional semantics SHOULD NOT be inferred based upon the presence or absence of another link relation type. </p>
<p id="rfc.section.6.2.1.p.3">This property is required. </p>
<h1 id="rfc.section.6.2.2">
<a href="#rfc.section.6.2.2">6.2.2.</a> <a href="#self" id="self">"self" Links</a>
</h1>
<p id="rfc.section.6.2.2.p.1">A "self" link, as originally defined by <a href="#RFC4287" class="xref">Section 4.2.7.2 of RFC 4287</a>, indicates that the target URI identifies a resource equivalent to the link context. In JSON Hyper-Schema, a "self" link MUST be resolvable from the instance, and therefore "hrefSchema" MUST NOT be present. </p>
<p id="rfc.section.6.2.2.p.2">Hyper-schema authors SHOULD use "templateRequired" to ensure that the "self" link has all instance data that is needed for use. </p>
<p id="rfc.section.6.2.2.p.3">A hyper-schema implementation MUST recognize that a link with relation type "self" that has the entire current instance document as its context describes how a user agent can interact with the resource represented by that instance document. </p>
<h1 id="rfc.section.6.2.3">
<a href="#rfc.section.6.2.3">6.2.3.</a> <a href="#collectionAndItem" id="collectionAndItem">"collection" and "item" Links</a>
</h1>
<p><a href="#RFC6573" class="xref">RFC 6573</a> defines and registers the "item" and "collection" link relation types. JSON Hyper-Schema imposes additional semantics on collection resources indicated by these types. </p>
<p id="rfc.section.6.2.3.p.2">Implementations MUST recognize the target of a "collection" link and the context of an "item" link as collections. </p>
<p id="rfc.section.6.2.3.p.3">A well-known design pattern in hypermedia is to use a collection resource to create a member of the collection and give it a server-assigned URI. If the protocol indicated by the URI scheme defines a specific method that is suited to creating a resource with a server-assigned URI, then a collection resource, as identified by these link relation types, MUST NOT define semantics for that method that conflict with the semantics of creating a collection member. Collection resources MAY implement item creation via such a protocol method, and user agents MAY assume that any such operation, if it exists, has item creation semantics. </p>
<p id="rfc.section.6.2.3.p.4">As such a method would correspond to JSON Hyper-Schema's data submission concept, the <a href="#submissionSchema" class="xref">"submissionSchema"</a> field for the link SHOULD be compatible with the schema of the representation of the collection's items, as indicated by the "item" link's target resource or the "self" link of the "collection" link's context resource. </p>
<h1 id="rfc.section.6.2.4">
<a href="#rfc.section.6.2.4">6.2.4.</a> <a href="#extensionRelationTypes" id="extensionRelationTypes">Using Extension Relation Types</a>
</h1>
<p id="rfc.section.6.2.4.p.1">When no registered relation (aside from "related") applies, users are encouraged to mint their own extension relation types, as described in <a href="#RFC8288" class="xref">section 2.1.2 of RFC 8288</a>. The simplest approaches for choosing link relation type URIs are to either use a URI scheme that is already in use to identify the system's primary resources, or to use a human-readable, non-dereferenceable URI scheme such as <a href="#RFC4151" class="xref">"tag", defined by RFC 4151</a>. </p>
<p id="rfc.section.6.2.4.p.2">Extension relation type URIs need not be dereferenceable, even when using a scheme that allows it. </p>
<h1 id="rfc.section.6.3">
<a href="#rfc.section.6.3">6.3.</a> <a href="#target" id="target">Link Target</a>
</h1>
<p id="rfc.section.6.3.p.1">The target URI template is used to identify the link's target, potentially making use of instance data. Additionally, with <a href="#hrefSchema" class="xref">"hrefSchema"</a>, this template can identify a set of possible target resources to use based on client input. The full process of resolving the URI template, with or without client input, is covered in the <a href="#uriTemplating" class="xref">URI Templating</a> section. </p>
<h1 id="rfc.section.6.3.1">
<a href="#rfc.section.6.3.1">6.3.1.</a> <a href="#href" id="href">href</a>
</h1>
<p id="rfc.section.6.3.1.p.1">The value of the "href" link description property is a template used to determine the target URI of the related resource. The value of the instance property MUST be resolved as a <a href="#RFC3986" class="xref">URI-reference</a> against the base URI of the instance. </p>
<p id="rfc.section.6.3.1.p.2">This property is REQUIRED. </p>
<h1 id="rfc.section.6.4">
<a href="#rfc.section.6.4">6.4.</a> Adjusting URI Template Resolution</h1>
<p id="rfc.section.6.4.p.1">The keywords in this section are used when resolving all URI Templates involved in hyper-schema: "base", "anchor", and "href". See the <a href="#uriTemplating" class="xref">URI Templating</a> section for the complete template resolution algorithm. </p>
<p id="rfc.section.6.4.p.2">Note that when resolving a "base" template, the attachment point from which resolution begins is the attachment point of the "href" or "anchor" keyword being resolved which requires "base" templates to be resolved, not the attachment point of the "base" keyword itself. </p>
<h1 id="rfc.section.6.4.1">
<a href="#rfc.section.6.4.1">6.4.1.</a> <a href="#templatePointers" id="templatePointers">templatePointers</a>
</h1>
<p id="rfc.section.6.4.1.p.1">The value of the "templatePointers" link description property MUST be an object. Each property value in the object MUST be a valid <a href="#RFC6901" class="xref">JSON Pointer</a>, or a valid <a href="#relative-json-pointer" class="xref">Relative JSON Pointer</a> which is evaluated relative to the attachment point of the link for which the template is being resolved. </p>
<p id="rfc.section.6.4.1.p.2">For each property name in the object that matches a variable name in the template being resolved, the value of that property adjusts the starting position of variable resolution for that variable. Properties which do not match template variable names in the template being resolved MUST be ignored. </p>
<h1 id="rfc.section.6.4.2">
<a href="#rfc.section.6.4.2">6.4.2.</a> <a href="#templateRequired" id="templateRequired">templateRequired</a>
</h1>
<p id="rfc.section.6.4.2.p.1">The value of this keyword MUST be an array, and the elements MUST be unique. Each element SHOULD match a variable in the link's URI Template, without percent-encoding. After completing the entire URI Template resolution process, if any variable that is present in this array does not have a value, the link MUST NOT be used. </p>
<h1 id="rfc.section.6.5">
<a href="#rfc.section.6.5">6.5.</a> <a href="#targetAttributes" id="targetAttributes">Link Target Attributes</a>
</h1>
<p id="rfc.section.6.5.p.1">All properties in this section are advisory only. While keywords such as "title" and "description" are used primarily to present the link to users, those keywords that predict the nature of a link interaction or response MUST NOT be considered authoritative. The runtime behavior of the target resource MUST be respected whenever it conflicts with the target attributes in the LDO. </p>
<h1 id="rfc.section.6.5.1">
<a href="#rfc.section.6.5.1">6.5.1.</a> title</h1>
<p id="rfc.section.6.5.1.p.1">This property defines a title for the link. The value MUST be a string. </p>
<p id="rfc.section.6.5.1.p.2">User agents MAY use this title when presenting the link to the user. </p>
<h1 id="rfc.section.6.5.2">
<a href="#rfc.section.6.5.2">6.5.2.</a> description</h1>
<p id="rfc.section.6.5.2.p.1">This property provides additional information beyond what is present in the title. The value MUST be a string. While a title is preferably short, a description can be used to go into more detail about the purpose and usage of the link. </p>
<p id="rfc.section.6.5.2.p.2">User agents MAY use this description when presenting the link to the user. </p>
<h1 id="rfc.section.6.5.3">
<a href="#rfc.section.6.5.3">6.5.3.</a> targetMediaType</h1>
<p id="rfc.section.6.5.3.p.1">The value of this property represents the media type <a href="#RFC2046" class="xref">RFC 2046</a>, that is expected to be returned when fetching this resource. This property value MAY be a media range instead, using the same pattern defined in <a href="#RFC7231" class="xref">RFC 7231, section 5.3.2 - HTTP "Accept" header</a>. </p>
<p id="rfc.section.6.5.3.p.2">This property is analogous to the "type" property of other link serialization formats. User agents MAY use this information to inform the interface they present to the user before the link is followed, but MUST NOT use this information in the interpretation of the resulting data. Instead, a user agent MUST use the media type given by the response for run-time interpretation. See the section on <a href="#security" class="xref">"Security Concerns"</a> for a detailed examination of mis-use of "targetMediaType". </p>
<p id="rfc.section.6.5.3.p.3">For protocols supporting content-negotiation, implementations MAY choose to describe possible target media types using protocol-specific information in <a href="#headerSchema" class="xref">"headerSchema"</a>. If both protocol-specific information and "targetMediaType" are present, then the value of "targetMediaType" MUST be compatible with the protocol-specific information, and SHOULD indicate the media type that will be returned in the absence of content negotiation. </p>
<p id="rfc.section.6.5.3.p.4">When no such protocol-specific information is available, or when the implementation does not recognize the protocol involved, then the value SHOULD be taken to be "application/json". </p>
<h1 id="rfc.section.6.5.4">
<a href="#rfc.section.6.5.4">6.5.4.</a> <a href="#targetSchema" id="targetSchema">targetSchema</a>
</h1>
<p id="rfc.section.6.5.4.p.1">This property provides a schema that is expected to describe the link target's representation. Depending on the protocol, the schema may or may not describe the request or response to any particular operation performed with the link. See the <a href="#HTTP" class="xref">JSON Hyper-Schema and HTTP</a> section for an in-depth discussion of how this keyword is used with HTTP. </p>
<h1 id="rfc.section.6.5.5">
<a href="#rfc.section.6.5.5">6.5.5.</a> <a href="#targetHints" id="targetHints">targetHints</a>
</h1>
<p><a id="CREF1" class="info">[CREF1]<span class="info">This section attempts to strike a balance between comprehensiveness and flexibility by deferring most of its structure to the protocol indicated by the URI scheme. Note that a resource can be identified by a URI with a dereferenceable scheme, yet not be accessible over that protocol. While currently very loose, this section is expected to become more well-defined based on draft feedback, and may change significantly in future drafts. </span></a> </p>
<p id="rfc.section.6.5.5.p.2">The value of this property is advisory only. It represents information that is expected to be discoverable through interacting with the target resource, typically in the form of protocol-specific control information or meta-data such as headers returned in response to an HTTP HEAD or OPTIONS request. The protocol is determined by the "href" URI scheme, although note that resources are not guaranteed to be accessible over such a protocol. </p>
<p id="rfc.section.6.5.5.p.3">The value of this property SHOULD be an object. The keys to this object SHOULD be lower-cased forms of the control data field names. Each value SHOULD be an array, in order to uniformly handle multi-valued fields. Multiple values MUST be presented as an array, and not as a single string. </p>
<p id="rfc.section.6.5.5.p.4">Protocols with control information not suitable for representation as a JSON object MAY be represented by another data type, such as an array. </p>
<p id="rfc.section.6.5.5.p.5">Values that cannot be understood as part of the indicated protocol MUST be ignored by a JSON Hyper-Schema implementation. Applications MAY make use of such values, but MUST NOT assume interoperability with other implementations. </p>
<p id="rfc.section.6.5.5.p.6">Implementations MUST NOT assume that all discoverable information is accounted for in this object. Client applications MUST properly handle run-time responses that contradict this property's values. </p>
<p id="rfc.section.6.5.5.p.7">Client applications MUST NOT assume that an implementation will automatically take any action based on the value of this property. </p>
<p id="rfc.section.6.5.5.p.8">See <a href="#HTTP" class="xref">"JSON Hyper-Schema and HTTP"</a> for guidance on using this keyword with HTTP and analogous protocols. </p>
<h1 id="rfc.section.6.6">
<a href="#rfc.section.6.6">6.6.</a> <a href="#input" id="input">Link Input</a>
</h1>
<p id="rfc.section.6.6.p.1">There are four ways to use client input with a link, and each is addressed by a separate link description object keyword. When performing operations, user agents SHOULD ignore schemas that are not relevant to their semantics. </p>
<h1 id="rfc.section.6.6.1">
<a href="#rfc.section.6.6.1">6.6.1.</a> <a href="#hrefSchema" id="hrefSchema">hrefSchema</a>
</h1>
<p id="rfc.section.6.6.1.p.1">The value of the "hrefSchema" link description property MUST be a valid JSON Schema. This schema is used to validate user input or other user agent data for filling out the URI Template in <a href="#href" class="xref">"href"</a>. </p>
<p id="rfc.section.6.6.1.p.2">Omitting "hrefSchema" or setting the entire schema to "false" prevents any user agent data from being accepted. </p>
<p id="rfc.section.6.6.1.p.3">Setting any subschema that applies to a particular variable to the JSON literal value "false" prevents any user agent data from being accepted for that single variable. </p>
<p id="rfc.section.6.6.1.p.4">For template variables that can be resolved from the instance data, if the instance data is valid against all applicable subschemas in "hrefSchema", then it MUST be used to pre-populate the input data set for that variable. </p>
<p id="rfc.section.6.6.1.p.5">Note that even when data is pre-populated from the instance, the validation schema for that variable in "hrefSchema" need not be identical to the validation schema(s) that apply to the instance data's location. This allows for different validation rules for user agent data, such as supporting spelled-out months for date-time input, but using the standard date-time format for storage. </p>
<p id="rfc.section.6.6.1.p.6">After input is accepted, potentially overriding the pre-populated instance data, the resulting data set MUST successfully validate against the value of "hrefSchema". If it does not then the link MUST NOT be used. If it is valid, then the process given in the "URI Templating" section continues with this updated data set. </p>
<h1 id="rfc.section.6.6.2">
<a href="#rfc.section.6.6.2">6.6.2.</a> <a href="#headerSchema" id="headerSchema">headerSchema</a>
</h1>
<p><a id="CREF2" class="info">[CREF2]<span class="info">As with "targetHints", this keyword is somewhat under-specified to encourage experimentation and feedback as we try to balance flexibility and clarity. </span></a> </p>
<p id="rfc.section.6.6.2.p.2">If present, this property is a schema for protocol-specific request headers or analogous control and meta-data. The value of this object MUST be a valid JSON Schema. The protocol is determined by the "href" URI scheme, although note that resources are not guaranteed to be accessible over such a protocol. The schema is advisory only; the target resource's behavior is not constrained by its presence. </p>
<p id="rfc.section.6.6.2.p.3">The purpose of this keyword is to advertise target resource interaction features, and indicate to user agents and client applications what headers and header values are likely to be useful. User agents and client applications MAY use the schema to validate relevant headers, but MUST NOT assume that missing headers or values are forbidden from use. While schema authors MAY set "additionalProperties" to false, this is NOT RECOMMENDED and MUST NOT prevent client applications or user agents from supplying additional headers when requests are made. </p>
<p id="rfc.section.6.6.2.p.4">The exact mapping of the JSON data model into the headers is protocol-dependent. However, in most cases this schema SHOULD specify a type of "object", and the property names SHOULD be lower-cased forms of the control data field names. As with "targetHints", the values SHOULD be described as arrays to allow for multiple values, even if only one value is expected. </p>
<p id="rfc.section.6.6.2.p.5">See the <a href="#HTTP" class="xref">"JSON Hyper-Schema and HTTP"</a> section for detailed guidance on using this keyword with HTTP and analogous protocols. </p>
<p id="rfc.section.6.6.2.p.6">"headerSchema" is applicable to any request method or command that the protocol supports. When generating a request, user agents and client applications SHOULD ignore schemas for headers that are not relevant to that request. </p>
<h1 id="rfc.section.6.6.3">
<a href="#rfc.section.6.6.3">6.6.3.</a> Manipulating the Target Resource Representation</h1>
<p id="rfc.section.6.6.3.p.1">In JSON Hyper-Schema, <a href="#targetSchema" class="xref">"targetSchema"</a> supplies a non-authoritative description of the target resource's representation. A client application can use "targetSchema" to structure input for replacing or modifying the representation, or as the base representation for building a patch document based on a patch media type. </p>
<p id="rfc.section.6.6.3.p.2">Alternatively, if "targetSchema" is absent or if the client application prefers to only use authoritative information, it can interact with the target resource to confirm or discover its representation structure. </p>
<p id="rfc.section.6.6.3.p.3">"targetSchema" is not intended to describe link operation responses, except when the response semantics indicate that it is a representation of the target resource. In all cases, the schema indicated by the response itself is authoritative. See <a href="#HTTP" class="xref">"JSON Hyper-Schema and HTTP"</a> for detailed examples. </p>
<h1 id="rfc.section.6.6.4">
<a href="#rfc.section.6.6.4">6.6.4.</a> Submitting Data for Processing</h1>
<p id="rfc.section.6.6.4.p.1">The <a href="#submissionSchema" class="xref">"submissionSchema"</a> and <a href="#submissionMediaType" class="xref">"submissionMediaType"</a> keywords describe the domain of the processing function implemented by the target resource. Otherwise, as noted above, the submission schema and media type are ignored for operations to which they are not relevant. </p>
<h1 id="rfc.section.6.6.4.1">
<a href="#rfc.section.6.6.4.1">6.6.4.1.</a> <a href="#submissionMediaType" id="submissionMediaType">submissionMediaType</a>
</h1>
<p id="rfc.section.6.6.4.1.p.1">If present, this property indicates the media type format the client application and user agent should use for the request payload described by <a href="#submissionSchema" class="xref">"submissionSchema"</a>. </p>
<p id="rfc.section.6.6.4.1.p.2">Omitting this keyword has the same behavior as a value of application/json. </p>
<p id="rfc.section.6.6.4.1.p.3">Note that "submissionMediaType" and "submissionSchema" are not restricted to HTTP URIs. <a id="CREF3" class="info">[CREF3]<span class="info">This statement might move to wherever the example ends up.</span></a> </p>
<h1 id="rfc.section.6.6.4.2">
<a href="#rfc.section.6.6.4.2">6.6.4.2.</a> <a href="#submissionSchema" id="submissionSchema">submissionSchema</a>
</h1>
<p id="rfc.section.6.6.4.2.p.1">This property contains a schema which defines the acceptable structure of the document to be encoded according to the "submissionMediaType" property and sent to the target resource for processing. This can be viewed as describing the domain of the processing function implemented by the target resource. </p>
<p id="rfc.section.6.6.4.2.p.2">This is a separate concept from the <a href="#targetSchema" class="xref">"targetSchema"</a> property, which describes the target information resource (including for replacing the contents of the resource in a PUT request), unlike "submissionSchema" which describes the user-submitted request data to be evaluated by the resource. "submissionSchema" is intended for use with requests that have payloads that are not necessarily defined in terms of the target representation. </p>
<p id="rfc.section.6.6.4.2.p.3">Omitting "submissionSchema" has the same behavior as a value of "true". </p>
<h1 id="rfc.section.7">
<a href="#rfc.section.7">7.</a> <a href="#implementation" id="implementation">Implementation Requirements</a>
</h1>
<p id="rfc.section.7.p.1">At a high level, a conforming implementation will meet the following requirements. Each of these requirements is covered in more detail in the individual keyword sections and keyword group overviews. </p>
<p id="rfc.section.7.p.2">Note that the requirements around how an implementation MUST recognize "self", "collection", and "item" links are thoroughly covered in the <a href="#relationType" class="xref">link relation type</a> section and are not repeated here. </p>
<p id="rfc.section.7.p.3">While it is not a mandatory format for implementations, the output format used in the test suite summarizes what needs to be computed for each link before it can be used: </p>
<dl>
<dt>contextUri</dt>
<dd style="margin-left: 8">The fully resolved URI (with scheme) of the context resource. If the context is not the entire resource and there is a usable fragment identifier syntax, then the URI includes a fragment. Note that there is no such syntax for application/json. </dd>
<dt>contextPointer</dt>
<dd style="margin-left: 8">The JSON Pointer for the location within the instance of the context resource. If the instance media type supports JSON Pointers as fragment identifiers, this pointer will be the same as the one encoded in the fragment of the "contextUri" field. </dd>
<dt>rel</dt>
<dd style="margin-left: 8">The link relation type. When multiple link relation types appear in the LDO, for the purpose of producing output, they are to be treated as multiple LDOs, each with a single link relation type but otherwise identical. </dd>
<dt>targetUri</dt>
<dd style="margin-left: 8">The fully resolved URI (with a scheme) of the target resource. If the link accepts input, this can only be produced once the input has been supplied. </dd>
<dt>hrefInputTemplates</dt>
<dd style="margin-left: 8">The list of partially resolved URI references for a link that accepts input. The first entry in the list is the partially resolved "href". The additional entries, if any, are the partially resolved "base" values ordered from the most immediate out to the root of the schema. Template variables that are pre-populated in the input are not resolved at this stage, as the pre-populated value can be overridden. </dd>
<dt>hrefPrepopulatedInput</dt>
<dd style="margin-left: 8">The data set that the user agent should use to prepopulate any input mechanism before accepting client input. If input is to be accepted but no fields are to be pre-populated, then this will be an empty object. </dd>
<dt>attachmentPointer</dt>
<dd style="margin-left: 8">The JSON Pointer for the location within the instance to which the link is attached. By default, "contextUri" and "attachmentPointer" are the same, but "contextUri" can be changed by LDO keywords, while "attachmentPointer" cannot. </dd>
</dl>
<p> Other LDO keywords that are not involved in producing the above information are included exactly as they appear when producing output for the test suite. Those fields will not be further discussed here unless specifically relevant. </p>
<h1 id="rfc.section.7.1">
<a href="#rfc.section.7.1">7.1.</a> Link Discovery and Look-Up</h1>
<p id="rfc.section.7.1.p.1">Before links can be used, they must be discovered by applying the hyper-schema to the instance and finding all applicable and valid links. Note that in addition to collecting valid links, any <a href="#base" class="xref">"base"</a> values necessary to resolve each LDO's URI Templates must also be located and associated with the LDO through whatever mechanism is most useful for the implementation's URI Template resolution process. </p>
<p id="rfc.section.7.1.p.2">And implementation MUST support looking up links by either their attachment pointer or context pointer, either by performing the look-up or by providing the set of all links with both pointers determined so that user agents can implement the look-up themselves. </p>
<p id="rfc.section.7.1.p.3">When performing look-ups by context pointer, links that are attached to elements of the same array MUST be returned in the same order as the array elements to which they are attached. </p>
<h1 id="rfc.section.7.2">
<a href="#rfc.section.7.2">7.2.</a> <a href="#uriTemplating" id="uriTemplating">URI Templating</a>
</h1>
<p id="rfc.section.7.2.p.1">Three hyper-schema keywords are <a href="#RFC6570" class="xref">URI Templates</a>: "base", "anchor", and "href". Each are resolved separately to URI-references, and then the anchor or href URI-reference is resolved against the base (which is itself resolved against earlier bases as needed, each of which was first resolved from a URI Template to a URI-reference). </p>
<p id="rfc.section.7.2.p.2">All three keywords share the same algorithm for resolving variables from instance data, which makes use of the "templatePointers" and "templateRequired" keywords. When resolving "href", both it and any "base" templates needed for resolution to an absolute URI, the algorithm is modified to optionally accept user input based on the "hrefSchema" keyword. </p>
<p id="rfc.section.7.2.p.3">For each URI Template (T), the following pseudocode describes an algorithm for resolving T into a URI-reference (R). For the purpose of this algorithm: </p>
<ul>
<li>"ldo.templatePointers" is an empty object if the keyword was not present and "ldo.templateRequired" is likewise an empty array. </li>
<li>"attachmentPointer" is the absolute JSON Pointer for the attachment location of the LDO. </li>
<li>"getApplicableSchemas()" returns an iterable set of all (sub)schemas that apply to the attachment point in the instance. </li>
</ul>
<p> </p>
<p id="rfc.section.7.2.p.4">This algorithm should be applied first to either "href" or "anchor", and then as needed to each successive "base". The order is important, as it is not always possible to tell whether a template will resolve to a full URI or a URI-reference. </p>
<p id="rfc.section.7.2.p.5">In English, the high-level algorithm is: </p>
<ol>
<li>Populate template variable data from the instance</li>
<li>If input is desired, accept input</li>
<li>Check that all required variables have a value</li>
<li>Encode values into strings and fill out the template</li>
</ol>
<p> </p>
<p>This is the high-level algorithm as pseudocode. "T" comes from either "href" or "anchor" within the LDO, or from "base" in a containing schema. Pseudocode for each step follows. "initialTemplateKeyword" indicates which of the two started the process (since "base" is always resolved in order to finish resolving one or the other of those keywords). </p>
<pre>
templateData = populateDataFromInstance(T, ldo, instance)
if initialTemplateKeyword == "href" and ldo.hrefSchema exists:
inputData = acceptInput(ldo, instance, templateData)
for varname in inputData:
templateData[varname] = inputData[varname]
for varname in ldo.templateRequired:
if not exists templateData[varname]
fatal("Missing required variable(s)")
templateData = stringEncode(templateData)
R = rfc6570ResolutionAlgorithm(T, templateData)
</pre>
<h1 id="rfc.section.7.2.1">
<a href="#rfc.section.7.2.1">7.2.1.</a> Populating Template Data From the Instance</h1>
<p id="rfc.section.7.2.1.p.1">This step looks at various locations in the instance for variable values. For each variable: </p>
<ol>
<li>Use "templatePointers" to find a value if the variable appears in that keyword's value </li>
<li>Otherwise, look for a property name matching the variable in the instance location to which the link is attached </li>
<li>In either case, if there is a value at the location, put it in the template resolution data set </li>
</ol>
<p> </p>
<pre>
for varname in T:
varname = rfc3986PercentDecode(varname)
if varname in ldo.templatePointers:
valuePointer = templatePointers[varname]
if valuePointer is relative:
valuePointer = resolveRelative(attachmentPointer,
valuePointer)
else
valuePointer = attachmentPointer + "/" + varname
value = instance.valueAt(valuePointer)
if value is defined:
templateData[varname] = value
</pre>