-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathdraft-newton-json-content-rules-10-pjc.html
2379 lines (2240 loc) · 133 KB
/
draft-newton-json-content-rules-10-pjc.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>A Language for Rules Describing JSON Content</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.1.1" rel="Chapter" title="1.1 Requirements Language">
<link href="#rfc.section.2" rel="Chapter" title="2 Motivation">
<link href="#rfc.section.2.1" rel="Chapter" title="2.1 Format Translation">
<link href="#rfc.section.2.2" rel="Chapter" title="2.2 Abstraction Languages">
<link href="#rfc.section.2.3" rel="Chapter" title="2.3 JSON Schema vs JCR">
<link href="#rfc.section.3" rel="Chapter" title="3 Uses">
<link href="#rfc.section.4" rel="Chapter" title="4 JCR Examples">
<link href="#rfc.section.4.1" rel="Chapter" title="4.1 A First Example: Specifying Content">
<link href="#rfc.section.4.2" rel="Chapter" title="4.2 A Second Example: Testing Content">
<link href="#rfc.section.4.3" rel="Chapter" title="4.3 A Third Example: Combining Rulesets">
<link href="#rfc.section.5" rel="Chapter" title="5 Overview of the Language">
<link href="#rfc.section.6" rel="Chapter" title="6 Language Components">
<link href="#rfc.section.6.1" rel="Chapter" title="6.1 Character Encoding">
<link href="#rfc.section.6.2" rel="Chapter" title="6.2 Comments">
<link href="#rfc.section.6.3" rel="Chapter" title="6.3 Names and Identifiers">
<link href="#rfc.section.6.4" rel="Chapter" title="6.4 Directives">
<link href="#rfc.section.6.4.1" rel="Chapter" title="6.4.1 jcr-version">
<link href="#rfc.section.6.4.2" rel="Chapter" title="6.4.2 ruleset-id">
<link href="#rfc.section.6.4.3" rel="Chapter" title="6.4.3 import">
<link href="#rfc.section.6.5" rel="Chapter" title="6.5 Rules">
<link href="#rfc.section.6.6" rel="Chapter" title="6.6 Rule Names and Assignments">
<link href="#rfc.section.6.7" rel="Chapter" title="6.7 Annotations">
<link href="#rfc.section.6.7.1" rel="Chapter" title="6.7.1 @{not} - Negating Evaluation">
<link href="#rfc.section.6.8" rel="Chapter" title="6.8 Repetition">
<link href="#rfc.section.6.9" rel="Chapter" title="6.9 Combining Subordinate Components - Sequences and Choices">
<link href="#rfc.section.6.10" rel="Chapter" title="6.10 Type Specifications">
<link href="#rfc.section.6.11" rel="Chapter" title="6.11 Primitive Specifications">
<link href="#rfc.section.6.11.1" rel="Chapter" title="6.11.1 Null">
<link href="#rfc.section.6.11.2" rel="Chapter" title="6.11.2 Booleans">
<link href="#rfc.section.6.11.3" rel="Chapter" title="6.11.3 Numbers">
<link href="#rfc.section.6.11.4" rel="Chapter" title="6.11.4 Plain Strings">
<link href="#rfc.section.6.11.5" rel="Chapter" title="6.11.5 Strings with Additional Semantics">
<link href="#rfc.section.6.12" rel="Chapter" title="6.12 Member Specifications">
<link href="#rfc.section.6.13" rel="Chapter" title="6.13 Object Specifications">
<link href="#rfc.section.6.14" rel="Chapter" title="6.14 Array Specifications">
<link href="#rfc.section.6.14.1" rel="Chapter" title="6.14.1 Ordered Array Specifications">
<link href="#rfc.section.6.14.2" rel="Chapter" title="6.14.2 Unordered Array Specifications">
<link href="#rfc.section.6.15" rel="Chapter" title="6.15 Type Choices">
<link href="#rfc.section.6.16" rel="Chapter" title="6.16 Any Type">
<link href="#rfc.section.6.17" rel="Chapter" title="6.17 Group Specifications">
<link href="#rfc.section.6.18" rel="Chapter" title="6.18 Starting Points and Root Rules">
<link href="#rfc.section.7" rel="Chapter" title="7 Tips and Tricks">
<link href="#rfc.section.7.1" rel="Chapter" title="7.1 Any Member with Any Value">
<link href="#rfc.section.7.2" rel="Chapter" title="7.2 Lists of Values">
<link href="#rfc.section.7.3" rel="Chapter" title="7.3 Groups in Arrays">
<link href="#rfc.section.7.4" rel="Chapter" title="7.4 Groups in Objects">
<link href="#rfc.section.7.5" rel="Chapter" title="7.5 Group Rules as Macros">
<link href="#rfc.section.7.6" rel="Chapter" title="7.6 Object Mixins">
<link href="#rfc.section.7.7" rel="Chapter" title="7.7 Subordinate Dependencies">
<link href="#rfc.section.8" rel="Chapter" title="8 Legacy Features">
<link href="#rfc.section.9" rel="Chapter" title="9 Implementation Status">
<link href="#rfc.section.9.1" rel="Chapter" title="9.1 JCR Validator">
<link href="#rfc.section.9.2" rel="Chapter" title="9.2 Codalogic JCR Parser">
<link href="#rfc.section.9.3" rel="Chapter" title="9.3 JCR Java">
<link href="#rfc.section.10" rel="Chapter" title="10 ABNF Syntax">
<link href="#rfc.section.11" rel="Chapter" title="11 Security Considerations">
<link href="#rfc.section.12" rel="Chapter" title="12 Acknowledgements">
<link href="#rfc.references" rel="Chapter" title="13 References">
<link href="#rfc.references.1" rel="Chapter" title="13.1 Normative References">
<link href="#rfc.references.2" rel="Chapter" title="13.2 Infomative References">
<link href="#rfc.appendix.A" rel="Chapter" title="A Experimental Features">
<link href="#rfc.appendix.A.1" rel="Chapter" title="A.1 Augmented OR of Objects">
<link href="#rfc.appendix.A.2" rel="Chapter" title="A.2 New Data Types">
<link href="#rfc.appendix.A.3" rel="Chapter" title="A.3 New Annotations">
<link href="#rfc.appendix.B" rel="Chapter" title="B Co-Constraints">
<link href="#rfc.appendix.C" rel="Chapter" title="C Testing Against JSON Content Rules">
<link href="#rfc.appendix.C.1" rel="Chapter" title="C.1 Locally Overriding Rules">
<link href="#rfc.appendix.C.2" rel="Chapter" title="C.2 Rule Callbacks">
<link href="#rfc.appendix.D" rel="Chapter" title="D Changes from -09 and -10">
<link href="#rfc.authors" rel="Chapter">
<meta name="generator" content="xml2rfc version 2.9.6 - https://tools.ietf.org/tools/xml2rfc" />
<link rel="schema.dct" href="http://purl.org/dc/terms/" />
<meta name="dct.creator" content="Newton, A. and P. Cordell" />
<meta name="dct.identifier" content="urn:ietf:id:draft-newton-json-content-rules-10" />
<meta name="dct.issued" scheme="ISO8601" content="2018-11" />
<meta name="dct.abstract" content="This document describes a language for specifying and testing the expected content of JSON structures found in JSON-using protocols, software, and processes. " />
<meta name="description" content="This document describes a language for specifying and testing the expected content of JSON structures found in JSON-using protocols, software, and processes. " />
</head>
<body>
<table class="header">
<tbody>
<tr>
<td class="left">Network Working Group</td>
<td class="right">A. Newton</td>
</tr>
<tr>
<td class="left">Internet-Draft</td>
<td class="right">ARIN</td>
</tr>
<tr>
<td class="left">Intended status: Standards Track</td>
<td class="right">P. Cordell</td>
</tr>
<tr>
<td class="left">Expires: October 13, 2018</td>
<td class="right">Codalogic</td>
</tr>
<tr>
<td class="left"></td>
<td class="right">April 11, 2018</td>
</tr>
</tbody>
</table>
<p class="title">A Language for Rules Describing JSON Content<br />
<span class="filename">draft-newton-json-content-rules-10</span></p>
<h1 id="rfc.abstract"><a href="#rfc.abstract">Abstract</a></h1>
<p>This document describes a language for specifying and testing the expected content of JSON structures found in JSON-using protocols, software, and processes. </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 October 13, 2018.</p>
<h1 id="rfc.copyrightnotice"><a href="#rfc.copyrightnotice">Copyright Notice</a></h1>
<p>Copyright (c) 2018 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>
<ul><li>1.1. <a href="#rfc.section.1.1">Requirements Language</a>
</li>
</ul><li>2. <a href="#rfc.section.2">Motivation</a>
</li>
<ul><li>2.1. <a href="#rfc.section.2.1">Format Translation</a>
</li>
<li>2.2. <a href="#rfc.section.2.2">Abstraction Languages</a>
</li>
<li>2.3. <a href="#rfc.section.2.3">JSON Schema vs JCR</a>
</li>
</ul><li>3. <a href="#rfc.section.3">Uses</a>
</li>
<li>4. <a href="#rfc.section.4">JCR Examples</a>
</li>
<ul><li>4.1. <a href="#rfc.section.4.1">A First Example: Specifying Content</a>
</li>
<li>4.2. <a href="#rfc.section.4.2">A Second Example: Testing Content</a>
</li>
<li>4.3. <a href="#rfc.section.4.3">A Third Example: Combining Rulesets</a>
</li>
</ul><li>5. <a href="#rfc.section.5">Overview of the Language</a>
</li>
<li>6. <a href="#rfc.section.6">Language Components</a>
</li>
<ul><li>6.1. <a href="#rfc.section.6.1">Character Encoding</a>
</li>
<li>6.2. <a href="#rfc.section.6.2">Comments</a>
</li>
<li>6.3. <a href="#rfc.section.6.3">Names and Identifiers</a>
</li>
<li>6.4. <a href="#rfc.section.6.4">Directives</a>
</li>
<ul><li>6.4.1. <a href="#rfc.section.6.4.1">jcr-version</a>
</li>
<li>6.4.2. <a href="#rfc.section.6.4.2">ruleset-id</a>
</li>
<li>6.4.3. <a href="#rfc.section.6.4.3">import</a>
</li>
</ul><li>6.5. <a href="#rfc.section.6.5">Rules</a>
</li>
<li>6.6. <a href="#rfc.section.6.6">Rule Names and Assignments</a>
</li>
<li>6.7. <a href="#rfc.section.6.7">Annotations</a>
</li>
<ul><li>6.7.1. <a href="#rfc.section.6.7.1">@{not} - Negating Evaluation</a>
</li>
</ul><li>6.8. <a href="#rfc.section.6.8">Repetition</a>
</li>
<li>6.9. <a href="#rfc.section.6.9">Combining Subordinate Components - Sequences and Choices</a>
</li>
<li>6.10. <a href="#rfc.section.6.10">Type Specifications</a>
</li>
<li>6.11. <a href="#rfc.section.6.11">Primitive Specifications</a>
</li>
<ul><li>6.11.1. <a href="#rfc.section.6.11.1">Null</a>
</li>
<li>6.11.2. <a href="#rfc.section.6.11.2">Booleans</a>
</li>
<li>6.11.3. <a href="#rfc.section.6.11.3">Numbers</a>
</li>
<li>6.11.4. <a href="#rfc.section.6.11.4">Plain Strings</a>
</li>
<li>6.11.5. <a href="#rfc.section.6.11.5">Strings with Additional Semantics</a>
</li>
</ul><li>6.12. <a href="#rfc.section.6.12">Member Specifications</a>
</li>
<li>6.13. <a href="#rfc.section.6.13">Object Specifications</a>
</li>
<li>6.14. <a href="#rfc.section.6.14">Array Specifications</a>
</li>
<ul><li>6.14.1. <a href="#rfc.section.6.14.1">Ordered Array Specifications</a>
</li>
<li>6.14.2. <a href="#rfc.section.6.14.2">Unordered Array Specifications</a>
</li>
</ul><li>6.15. <a href="#rfc.section.6.15">Type Choices</a>
</li>
<li>6.16. <a href="#rfc.section.6.16">Any Type</a>
</li>
<li>6.17. <a href="#rfc.section.6.17">Group Specifications</a>
</li>
<li>6.18. <a href="#rfc.section.6.18">Starting Points and Root Rules</a>
</li>
</ul><li>7. <a href="#rfc.section.7">Tips and Tricks</a>
</li>
<ul><li>7.1. <a href="#rfc.section.7.1">Any Member with Any Value</a>
</li>
<li>7.2. <a href="#rfc.section.7.2">Lists of Values</a>
</li>
<li>7.3. <a href="#rfc.section.7.3">Groups in Arrays</a>
</li>
<li>7.4. <a href="#rfc.section.7.4">Groups in Objects</a>
</li>
<li>7.5. <a href="#rfc.section.7.5">Group Rules as Macros</a>
</li>
<li>7.6. <a href="#rfc.section.7.6">Object Mixins</a>
</li>
<li>7.7. <a href="#rfc.section.7.7">Subordinate Dependencies</a>
</li>
</ul><li>8. <a href="#rfc.section.8">Legacy Features</a>
</li>
<li>9. <a href="#rfc.section.9">Implementation Status</a>
</li>
<ul><li>9.1. <a href="#rfc.section.9.1">JCR Validator</a>
</li>
<li>9.2. <a href="#rfc.section.9.2">Codalogic JCR Parser</a>
</li>
<li>9.3. <a href="#rfc.section.9.3">JCR Java</a>
</li>
</ul><li>10. <a href="#rfc.section.10">ABNF Syntax</a>
</li>
<li>11. <a href="#rfc.section.11">Security Considerations</a>
</li>
<li>12. <a href="#rfc.section.12">Acknowledgements</a>
</li>
<li>13. <a href="#rfc.references">References</a>
</li>
<ul><li>13.1. <a href="#rfc.references.1">Normative References</a>
</li>
<li>13.2. <a href="#rfc.references.2">Infomative References</a>
</li>
</ul><li>Appendix A. <a href="#rfc.appendix.A">Experimental Features</a>
</li>
<ul><li>A.1. <a href="#rfc.appendix.A.1">Augmented OR of Objects</a>
</li>
<li>A.2. <a href="#rfc.appendix.A.2">New Data Types</a>
</li>
<li>A.3. <a href="#rfc.appendix.A.3">New Annotations</a>
</li>
</ul><li>Appendix B. <a href="#rfc.appendix.B">Co-Constraints</a>
</li>
<li>Appendix C. <a href="#rfc.appendix.C">Testing Against JSON Content Rules</a>
</li>
<ul><li>C.1. <a href="#rfc.appendix.C.1">Locally Overriding Rules</a>
</li>
<li>C.2. <a href="#rfc.appendix.C.2">Rule Callbacks</a>
</li>
</ul><li>Appendix D. <a href="#rfc.appendix.D">Changes from -09 and -10</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">This document describes JSON Content Rules (JCR), a language for specifying and testing the interchange of data in <a href="#RFC8259" class="xref">JSON</a> format used by computer protocols and processes. The syntax of JCR is not JSON but is "JSON-like", possessing the conciseness and utility that has made JSON popular. </p>
<h1 id="rfc.section.1.1">
<a href="#rfc.section.1.1">1.1.</a> Requirements Language</h1>
<p id="rfc.section.1.1.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.2">
<a href="#rfc.section.2">2.</a> Motivation</h1>
<p id="rfc.section.2.p.1">As a growing number of protocols use JSON, there is an increasing need to find better mechanisms to help define such protocols. </p>
<p id="rfc.section.2.p.2">In the past, protocols often used constrained grammar strings. Such strings could be defined by example, but it was found better to use Backus-Naur Form (BNF), or variants such as ABNF. The benefit of using ABNF over examples is that the full variation of what is allowed in a protocol can be expressed in a single location. This leads to easier implementation and better interoperability. </p>
<p id="rfc.section.2.p.3">As protocols migrate to being defined in JSON, the same need to define the valid set of JSON messages arises. It is conceivable to define the JSON-based message set by way of examples. But as with constrained grammar strings, this can be cumbersome, incomplete and easily misinterpreted, leading to the problems of implementation and interoperability mentioned earlier. </p>
<p id="rfc.section.2.p.4">It would be theoretically possible to express the valid set of a protocol’s JSON messages using ABNF. However, ABNF is difficult to get right at the best of times, and defining an ABNF that simultaneously interwove the constraints of JSON and the constraints of the protocol into a single ABNF definition would be a task few could, or would want to, achieve. Even if such were possible, much of what was intended to describe the protocol, would be obscured by the aspects describing the JSON constraints. Such an approach is likely to end up being only comprehendible by a machine, and be impenetrable to humans. As such, arguably, such a definition would not satisfy it primary target audience. </p>
<p id="rfc.section.2.p.5">The solution is to move up a level of abstraction. In the same way JSON is a level of abstraction above constrained grammar strings for representing protocols, a similar move up in abstraction level is needed for the mechanism used to define such protocols. </p>
<p id="rfc.section.2.p.6">JSON Content Rules (JCR) is such a step up in abstraction. It’s relation to JSON is that of ABNF to constrained string grammars. By ‘knowing’ about JSON it can more accurately and concisely define JSON messages than other methods that are less abstracted. In the same way that abstracted languages such as Java and Python enable a programmer to work more efficiently than they can with assembler, protocol developers can work more efficiently using JCR than they can with ABNF. </p>
<p id="rfc.section.2.p.7">That said, JCR is not the only language in this space nor the only solution, beyond ABNF, to this problem. Of the various method and languages that the authors know about, in addition to JCR, there are format translators which algorithmically convert a specification from one format to another (e.g. XML to JSON), abstraction languages such as Yang and CDDL, and at least one other JSON specific language: JSON Schema. </p>
<h1 id="rfc.section.2.1">
<a href="#rfc.section.2.1">2.1.</a> Format Translation</h1>
<p id="rfc.section.2.1.p.1">Format translation is an algorithmic approach to specifying protocol messages in multiple formats by using one format as the base specification and an algorithm for translating that format into another. One example would be the translation of XML into JSON using the BadgerFish algorithm and software. </p>
<p id="rfc.section.2.1.p.2">This approach often creates difficult protocol messages in the destination format (i.e. JSON in the case of XML to JSON) which are hard to implement towards or debug. Additionally, while it be fashionable to have multiple formats, most software implementations of protocols work best with one format and often not well with others, if at all. </p>
<p id="rfc.section.2.1.p.3">vCard and jCard are good examples of this. The original format and data model for vCard are specified in MIME. jCard is an algorithmic conversion of vCard to jCard. Consequently, writing software implementations of jCard requires software developers to have an intimate knowledge of MIME, saving them little in the way of time or effort. </p>
<h1 id="rfc.section.2.2">
<a href="#rfc.section.2.2">2.2.</a> Abstraction Languages</h1>
<p id="rfc.section.2.2.p.1">Abstraction languages are nothing new to the schema and data definition language space, with ASN.1 being a classic example of specifying a data model in a higher-level syntax and defined algorithms for multiple data formats. ASN.1 supports many data formats, such as BER and DER and XER (XML Encoding Rules). Yang is a more modern and popular abstraction language. </p>
<p id="rfc.section.2.2.p.2">These languages have their place but suffer the same issues as format translators as they require software implementors to spend valuable energy on a syntax that is not specific to the software being implemented. Additionally, abstraction languages have, in many instances, specified features in the data model that do not translate well to all data formats or may lack compelling features because the language must cater to multiple formats. </p>
<p id="rfc.section.2.2.p.3">With respect to JSON, CDDL is an abstraction language as it's data model is a superset of the data model of JSON. In other words, it is possible to specify protocol messages in CDDL that are not applicable to JSON. And because CDDL targets CBOR specifically, it does not benefit from being JSON-like, as is the case of JCR, or specified in JSON, as is the case of JSON Schema. </p>
<h1 id="rfc.section.2.3">
<a href="#rfc.section.2.3">2.3.</a> JSON Schema vs JCR</h1>
<p id="rfc.section.2.3.p.1">JSON Schema, like JCR, is a data definition language designed specifically for JSON. While JCR is more tightly scoped to defining JSON protocol messages and content, JSON Schema is more broadly scoped in its goals, including deeper aspects of data set linking and the semantic web. </p>
<p id="rfc.section.2.3.p.2">JSON Schema benefits from being defined in JSON (as this makes implementations of JSON Schema tools easier), but this benefit impacts readability of specifications defining content using it. To demonstrate, the following examples define JSON using the classic example of a catalog object. </p>
<div id="rfc.figure.1"></div>
<div id="example_catalog_json_schema"></div>
<p>In this example, the catalog entry is defined in JSON Schema. </p>
<pre>
{
"$schema": "http://json-schema.org/draft-06/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "integer"
},
"name": {
"description": "Name of the product",
"type": "string"
},
"price": {
"type": "number",
"exclusiveMinimum": 0
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"required": ["id", "name", "price"]
}
</pre>
<p class="figure">Figure 1</p>
<div id="rfc.figure.2"></div>
<div id="example_catalog_jcr"></div>
<p>For comparison, this example demonstrates the same catalog entry as described in <a href="#example_catalog_json_schema" class="xref">Figure 1</a> but in JCR. </p>
<pre>
#jcr-version 0.9
; Product – A Product for Acme’s catalog
{
"id" : integer, ; Unique identifier for the product
"name" : string, ; Name of the product
"price" : @{min-exclusive} 0.0..,
"tags" : [ string + ] ?
}
</pre>
<p class="figure">Figure 2</p>
<p id="rfc.section.2.3.p.3">The above examples demonstrate that the JCR is more concise and conveys the same information but in fewer lines in a syntax familiar with a JSON-aware software implementor. </p>
<p id="rfc.section.2.3.p.4">From a high-level view point, it could be said that JSON Schema is like XML Schema whereas JCR is more like Compact RelaxNG. </p>
<p id="rfc.section.2.3.p.5">Additionally, JCR syntax is a superset of JSON syntax, whereby specification authors may use example JSON protocol messages as a starting point for defining JCR rules (as is described in <a href="#a_first_example" class="xref">Section 4.1</a>). Consequently, the effort required to turn JSON examples into JCR specifications is minimal compared to that required to create an equivalent JSON Schema. This, combined with the brevity of describing rules and the ability to name rules, allows specification authors to interleave their prose with JCR rules in their specifications, facilitating describing semantics in close proximity to syntax. </p>
<h1 id="rfc.section.3">
<a href="#rfc.section.3">3.</a> Uses</h1>
<p id="rfc.section.3.p.1">JCR's primary focus is to help specification authors concisely and clearly describe complex JSON data structures. </p>
<p id="rfc.section.3.p.2">Being a precise, defined format reduces the potential for misunderstanding between what specification authors intended and what software developers implement. </p>
<p id="rfc.section.3.p.3">Being a machine-readable format, the examples in a specification can be validated by the specified JCR, and it can be verified that the JCR represents the examples. This acts like unit testing in software development, and has been done in the authoring of this document. </p>
<p id="rfc.section.3.p.4">JCR aids software developers to verify that their implementations conform to specifications by validating any generated JSON against the specified JCR. This can be used to highlight bugs in their code, or possibly identify where a specification has omissions and requires further work. </p>
<p id="rfc.section.3.p.5">Specific examples of JCR and JSON can be included as part of conformance test vector sets to give confidence that an implementation meets a specification. JCR's ability to be specific in some locations, and loose in others, allows such tests to be run on a repeatable, automated basis without requiring detailed human involvement to check the results. </p>
<p id="rfc.section.3.p.6">JCR can help resolve interoperability issues by acting as an independent arbiter between parties experiencing interoperability issues. Appealing to a JCR opinion offers the potential for a quick and cheap resolution to a disagreement. (Naturally, either party may disagree with the JCR result and take the matter further.) </p>
<p id="rfc.section.3.p.7">Once software has been developed and deployed, JCR offers the potential for day-one in-the-field monitoring of JSON message exchanges in order to highlight conformance issues that may have slipped through the development phase. </p>
<p id="rfc.section.3.p.8">Being a simple, defined language, JCR can also be used on an ad-hoc basis by developers as part of the design process, such as during brainstorming and whiteboarding sessions, without risking confusion over notation that may occur if an un-documented notation is used. </p>
<h1 id="rfc.section.4">
<a href="#rfc.section.4">4.</a> JCR Examples</h1>
<p id="rfc.section.4.p.1">Being a superset of JSON syntax, those familiar with JSON will likely have an intuitive understanding of many aspects of JCR. This section offers some JCR examples to give such readers a feel for JCR before going into the detail. </p>
<h1 id="rfc.section.4.1">
<a href="#rfc.section.4.1">4.1.</a> <a href="#a_first_example" id="a_first_example">A First Example: Specifying Content</a>
</h1>
<p id="rfc.section.4.1.p.1">The following JSON data describes a JSON object with two members, "line-count" and "word-count", each containing an integer. </p>
<div id="rfc.figure.3"></div>
<div id="first_example.json"></div>
<pre>{ "line-count" : 3426, "word-count" : 27886 }
</pre>
<p class="figure">Figure 3</p>
<p id="rfc.section.4.1.p.2">This is also JCR that describes a JSON object with a member named "line-count" that is an integer that is exactly 3426 and a member named "word-count" that is an integer that is exactly 27886. </p>
<p id="rfc.section.4.1.p.3">For a protocol specification, it is probably more useful to specify that each member is any integer and not specific, exact integers. Thus, a more practical JCR description would be: </p>
<div id="rfc.figure.4"></div>
<div id="first_example.jcr"></div>
<pre>{ "line-count" : integer, "word-count" : integer }
</pre>
<p class="figure">Figure 4</p>
<p id="rfc.section.4.1.p.4">Since line counts and word counts should be either zero or a positive integer, the specification may be further narrowed: </p>
<div id="rfc.figure.5"></div>
<div id="first_example2.jcr"></div>
<pre>{ "line-count" : 0.. , "word-count" : 0.. }
</pre>
<p class="figure">Figure 5</p>
<h1 id="rfc.section.4.2">
<a href="#rfc.section.4.2">4.2.</a> A Second Example: Testing Content</h1>
<p id="rfc.section.4.2.p.1">Building on the first example, this second example describes the same object but with the addition of another member, "file-name". An example JSON instance is: </p>
<div id="rfc.figure.6"></div>
<div id="second_example.json"></div>
<pre>{
"file-name" : "rfc7159.txt",
"line-count" : 3426,
"word-count" : 27886
}
</pre>
<p class="figure">Figure 6</p>
<p id="rfc.section.4.2.p.2">The following JCR describes such objects: </p>
<div id="rfc.figure.7"></div>
<div id="second_example.jcr"></div>
<pre>{
"file-name" : string,
"line-count" : 0..,
"word-count" : 0..
}
</pre>
<p class="figure">Figure 7</p>
<p id="rfc.section.4.2.p.3">For the purposes of writing a protocol specification, JCR may be broken down into named rules to reduce complexity and to enable re-use. The following example takes the JCR from above and rewrites the members as named rules: </p>
<div id="rfc.figure.8"></div>
<div id="second_example2.jcr"></div>
<pre>{
$fn,
$lc,
$wc
}
$fn = "file-name" : string
$lc = "line-count" : 0..
$wc = "word-count" : 0..
</pre>
<p class="figure">Figure 8</p>
<p id="rfc.section.4.2.p.4">With each member specified as a named rule, software testers can override them locally for specific test cases. In the following example, the named rules are locally overridden for the test case where the file name is "rfc4627.txt": </p>
<div id="rfc.figure.9"></div>
<div id="second_example_override.jcr"></div>
<pre>$fn = "file-name" : "rfc4627.txt"
$lc = "line-count" : 2102
$wc = "word-count" : 16714
</pre>
<p class="figure">Figure 9</p>
<p id="rfc.section.4.2.p.5">This example shows how a protocol specification can describe a JSON object in general and a test environment can override the rules for testing specific cases. </p>
<p id="rfc.section.4.2.p.6">All figures used in this specification are available <a href="https://github.com/arineng/jcr/tree/master/figs">here</a>. </p>
<h1 id="rfc.section.4.3">
<a href="#rfc.section.4.3">4.3.</a> A Third Example: Combining Rulesets</h1>
<p id="rfc.section.4.3.p.1">In addition to defining rules, which relate to individual JSON values, JCR also has directives, which have a more ruleset-wide effect. </p>
<p id="rfc.section.4.3.p.2">Currently defined directives include jcr-version, ruleset-id and import. jcr-version specifies the version of JCR used by a ruleset, and allows future versions of JCR. ruleset-id and import support combining rules from multiple rulesets. </p>
<p id="rfc.section.4.3.p.3">Extending the previous example, it might be decided that the unsigned integer type associated with the $lc and $wc is so useful that it should be extracted into a ruleset of common utility types so that it can be used in other rulesets. Such a ruleset may look like: </p>
<div id="rfc.figure.10"></div>
<div id="thrid_example2.jcr"></div>
<pre>#jcr-version 1.0
#ruleset-id com.example.common-types
$count = 0..
</pre>
<p class="figure">Figure 10</p>
<p id="rfc.section.4.3.p.4">As this may be a long-lived ruleset, the jcr-version directive make it clear that JCR version 1.0 is being used. The ruleset is given the identity 'com.example.common-types' using the ruleset-id directive. The rule for the type is assigned the rule name 'count'. </p>
<p id="rfc.section.4.3.p.5">A ruleset that makes use of the count type, may look as follows: </p>
<div id="rfc.figure.11"></div>
<div id="thrid_example1.jcr"></div>
<pre>#import com.example.common-types as ct
{
$fn,
$lc,
$wc
}
$fn = "file-name" : string
$lc = "line-count" : $ct.count
$wc = "word-count" : $ct.count
</pre>
<p class="figure">Figure 11</p>
<p id="rfc.section.4.3.p.6">To make use of the count type, it is first necessary to import the 'com.example.common-types' ruleset, using the import directive. As part of the import, the 'com.example.common-types' ruleset is given an alias, 'ct', with which to refer to it. It is then possible to use the imported count type as '$ct.count'. </p>
<h1 id="rfc.section.5">
<a href="#rfc.section.5">5.</a> Overview of the Language</h1>
<p id="rfc.section.5.p.1">JCR is composed of rules (as the name suggests). A collection of rules that is processed together is a ruleset. Rulesets may also contain comments, blank lines, and directives that apply to the processing of a ruleset. </p>
<p id="rfc.section.5.p.2">Rules are composed of two parts, an optional rule name and a rule specification. A rule specification can be either a type specification or a member specification. A member specification consists of a member name specification and a type specification. </p>
<p id="rfc.section.5.p.3">A type specification is used to specify constraints on a superset of JSON values (e.g. number / string / object / array etc.). In addition to defining primitive types (such as string and integer), array and object types, type specifications may define the JCR specific concept of group types. </p>
<p id="rfc.section.5.p.4">Type specifications corresponding to arrays, objects and groups may be composed of other rule specifications. </p>
<p id="rfc.section.5.p.5">A member specification is used to specify constraints on members of a JSON object. </p>
<p id="rfc.section.5.p.6">Rules that have a rule name may be referenced in place of rule specifications. </p>
<p id="rfc.section.5.p.7">Rules may be defined across line boundaries and there is no line continuation syntax. </p>
<p id="rfc.section.5.p.8">Any rule without a rule name is considered a root rule. Such a rule MUST be a type specification. Unless otherwise specified, all the root rules of a ruleset are evaluated against a JSON instance or document. </p>
<p id="rfc.section.5.p.9">Rule specifications may be augmented with annotations to specify additional constraints and properties. For example, arrays can be augmented with an 'unordered' annotation to indicate that the order of its members isn't significant. </p>
<p id="rfc.section.5.p.10">The syntax for each form of type specification varies depending on the type. For example: </p>
<div id="rfc.figure.12"></div>
<div id="primitive_overview.jcr"></div>
<pre>; primitive types can be string
; or number literals
; or number ranges
"foo"
2
1..10
; primitive types can also be more generalized types
string
integer
; primitive type rules may be named
$my_int = 12
; member specifications consist of a member name
; followed by a colon and then followed by another
; type specification or a rule name
; (example shown with a rule name assignment)
$mem1 = "bar" : "baz"
$mem2 = "fizz" : $my_int
; member names may either be quoted strings
; or regular expressions
; (example shown with a rule name assignment)
$mem3 = /^dev[0-9]$/ : 0..4096
; object specifications start and end with "curly braces"
; object specifications contain zero
; or more member specifications
; or rule names which reference a member specification
{ $mem1, "foo" : "fuzz", "fizz" : $my_int }
; array specifications start and end with square brackets
; array specifications contain zero
; or more non-member type specifications
[ 1, 2, 3, $my_int ]
; finally, group specifications start and end with parenthesis
; groups contain other type specifications
( [ integer, integer], $rule1 )
$rule1 = [ string, string ]
</pre>
<p class="figure">Figure 12</p>
<p id="rfc.section.5.p.11">Putting it all together, the JSON in <a href="#rfc4627-example-1" class="xref">Figure 13</a> is described by the JCR in <a href="#rfc4627-example-1-compact-rules" class="xref">Figure 14</a>. </p>
<div id="rfc.figure.13"></div>
<div id="rfc4627-example-1"></div>
<pre>{
"Image": {
"Width": 800,
"Height": 600,
"Title": "View from 15th Floor",
"Thumbnail": {
"Url": "http://www.example.com/image/481989943",
"Height": 125,
"Width": 100
},
"IDs": [116, 943, 234, 38793]
}
}
</pre>
<p class="figure">Figure 13: Example JSON shamelessly lifted from RFC 8259</p>
<div id="rfc.figure.14"></div>
<div id="rfc4627-example-1-compact-rules"></div>
<pre>; the root of the JSON instance is an object
; this root rule describes that object
{
; the object specification contains
; one member specification
"Image" : {
; $width and $height are defined below
$width,
$height,
; "Title" member specification
"Title" :string,
; "Thumbnail" member specification, which
; defines an object
"Thumbnail": {
; $width and $height are re-used again
$width, $height,
"Url" :uri
},
; "IDs" member that is an array of
; one ore more integers
"IDs" : [ integer * ]
}
}
; The definitions of the rules $width and $height
$width = "Width" : 0..1280
$height = "Height" : 0..1024
</pre>
<p class="figure">Figure 14: JCR for JSON example from RFC 8259</p>
<p id="rfc.section.5.p.12">In addition to defining rules, JCR also has directives. These have a more ruleset-wide effect. Simple uses of JCR will likely not use directives. </p>
<h1 id="rfc.section.6">
<a href="#rfc.section.6">6.</a> Language Components</h1>
<p id="rfc.section.6.p.1">This section describes each component of the JCR language in detail. </p>
<h1 id="rfc.section.6.1">
<a href="#rfc.section.6.1">6.1.</a> Character Encoding</h1>
<p id="rfc.section.6.1.p.1">Like JSON, JCR rulesets MUST be encoded using UTF-8 <a href="#RFC3629" class="xref">RFC 3629</a> unless used entirely within a private, closed ecosystem. </p>
<p id="rfc.section.6.1.p.2">This document assumes that both JCR rulesets, and JSON instances being validated are encoded using UTF-8. Issues related to handling JCR rulesets or JSON instances that are not encoded using UTF-8 are outside the scope of this document. </p>
<h1 id="rfc.section.6.2">
<a href="#rfc.section.6.2">6.2.</a> Comments</h1>
<p id="rfc.section.6.2.p.1">Comments are the same as comments in <a href="#RFC4234" class="xref">ABNF</a>. They start with a semi-colon (';') and continue to the end of the line. </p>
<p id="rfc.section.6.2.p.2">Blank lines are allowed. These can be used, for example, to further aid readability. </p>
<h1 id="rfc.section.6.3">
<a href="#rfc.section.6.3">6.3.</a> <a href="#names-and-identifiers" id="names-and-identifiers">Names and Identifiers</a>
</h1>
<p id="rfc.section.6.3.p.1">JCR uses names and identifiers to enable cross-referencing one part of a ruleset with another, or from one ruleset to another. There are different types of names and different type of identifiers. For example, a local rule name is a name, and a ruleset-id is an identifier. </p>
<p id="rfc.section.6.3.p.2">A name must start with an ASCII alphabetic character (a-z,A-Z) and must contain only ASCII alphabetic characters, numeric characters, the hyphen character ('-') and the underscore character ('_'). Names are case sensitive. </p>
<p id="rfc.section.6.3.p.3">An identifier must start with an ASCII alphabetic character (a-z,A-Z) and can be followed by any character other than whitespace and the closing brace ('}'). Identifiers are treated as opaque strings, and therefore case-sensitive. </p>
<h1 id="rfc.section.6.4">
<a href="#rfc.section.6.4">6.4.</a> Directives</h1>
<p id="rfc.section.6.4.p.1">Directives modify the processing of a ruleset. If present, they typically appear at the start of a ruleset, before any rules are defined, but they can be placed in other parts of the ruleset if necessary. Simpler rulesets need not include any directives. </p>
<p id="rfc.section.6.4.p.2">There are two forms of the directive, the single line directive and the multi-line directive. </p>
<p id="rfc.section.6.4.p.3">Single line directives appear on their own line in a ruleset, begin with a hash character ('#') and are terminated by the end of the line. They take the following form: </p>
<div id="rfc.figure.15"></div>
<div id="single_line_directive_example.jcr"></div>
<pre># directive_name parameter_1 parameter_2 ...
</pre>
<p class="figure">Figure 15</p>
<p id="rfc.section.6.4.p.4">Multi-line directives also appear on their own lines, but may span multiple lines. They begin with the character sequence "#{" and end with "}". The take the following form: </p>
<div id="rfc.figure.16"></div>
<div id="multi_line_directive_example.jcr"></div>
<pre>#{ directive_name
parameter_1 paramter_2
parameter_3
...
}
</pre>
<p class="figure">Figure 16</p>
<p id="rfc.section.6.4.p.5">This specification defines the directives "jcr-version", "ruleset-id", and "import", but other directives may be defined in future. </p>