summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc8610.txt
blob: bec963a8c1f70b60e0d5356e20ca301eef4bfca7 (plain) (blame)
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
Internet Engineering Task Force (IETF)                       H. Birkholz
Request for Comments: 8610                                Fraunhofer SIT
Category: Standards Track                                      C. Vigano
ISSN: 2070-1721                                      Universitaet Bremen
                                                              C. Bormann
                                                 Universitaet Bremen TZI
                                                               June 2019


    Concise Data Definition Language (CDDL): A Notational Convention
         to Express Concise Binary Object Representation (CBOR)
                        and JSON Data Structures

Abstract

   This document proposes a notational convention to express Concise
   Binary Object Representation (CBOR) data structures (RFC 7049).  Its
   main goal is to provide an easy and unambiguous way to express
   structures for protocol messages and data formats that use CBOR or
   JSON.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   https://www.rfc-editor.org/info/rfc8610.

















Birkholz, et al.             Standards Track                    [Page 1]
^L
RFC 8610                          CDDL                         June 2019


Copyright Notice

   Copyright (c) 2019 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   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.

Table of Contents

   1. Introduction ....................................................4
      1.1. Requirements Notation ......................................5
      1.2. Terminology ................................................5
   2. The Style of Data Structure Specification .......................5
      2.1. Groups and Composition in CDDL .............................7
           2.1.1. Usage ..............................................10
           2.1.2. Syntax .............................................10
      2.2. Types .....................................................11
           2.2.1. Values .............................................11
           2.2.2. Choices ............................................11
           2.2.3. Representation Types ...............................13
           2.2.4. Root Type ..........................................14
   3. Syntax .........................................................15
      3.1. General Conventions .......................................15
      3.2. Occurrence ................................................16
      3.3. Predefined Names for Types ................................17
      3.4. Arrays ....................................................18
      3.5. Maps ......................................................19
           3.5.1. Structs ............................................19
           3.5.2. Tables .............................................22
           3.5.3. Non-deterministic Order ............................23
           3.5.4. Cuts in Maps .......................................24
      3.6. Tags ......................................................25
      3.7. Unwrapping ................................................26
      3.8. Controls ..................................................27
           3.8.1. Control Operator .size .............................27
           3.8.2. Control Operator .bits .............................28
           3.8.3. Control Operator .regexp ...........................29






Birkholz, et al.             Standards Track                    [Page 2]
^L
RFC 8610                          CDDL                         June 2019


           3.8.4. Control Operators .cbor and .cborseq ...............30
           3.8.5. Control Operators .within and .and .................30
           3.8.6. Control Operators .lt, .le, .gt, .ge, .eq,
                  .ne, and .default ..................................31
      3.9. Socket/Plug ...............................................32
      3.10. Generics .................................................33
      3.11. Operator Precedence ......................................34
   4. Making Use of CDDL .............................................36
      4.1. As a Guide for a Human User ...............................36
      4.2. For Automated Checking of CBOR Data Structures ............36
      4.3. For Data Analysis Tools ...................................37
   5. Security Considerations ........................................37
   6. IANA Considerations ............................................38
      6.1. CDDL Control Operators Registry ...........................38
   7. References .....................................................40
      7.1. Normative References ......................................40
      7.2. Informative References ....................................41
   Appendix A. Parsing Expression Grammars (PEGs) ....................43
   Appendix B. ABNF Grammar ..........................................45
   Appendix C. Matching Rules ........................................47
   Appendix D. Standard Prelude ......................................52
   Appendix E. Use with JSON .........................................53
   Appendix F. A CDDL Tool ...........................................56
   Appendix G. Extended Diagnostic Notation ..........................56
     G.1. Whitespace in Byte String Notation .........................57
     G.2. Text in Byte String Notation ...............................57
     G.3. Embedded CBOR and CBOR Sequences in Byte Strings ...........57
     G.4. Concatenated Strings .......................................58
     G.5. Hexadecimal, Octal, and Binary Numbers .....................59
     G.6. Comments ...................................................59
   Appendix H. Examples ..............................................60
   Acknowledgements ..................................................63
   Contributors ......................................................63
   Authors' Addresses ................................................64

















Birkholz, et al.             Standards Track                    [Page 3]
^L
RFC 8610                          CDDL                         June 2019


1.  Introduction

   In this document, a notational convention to express Concise Binary
   Object Representation (CBOR) data structures [RFC7049] is defined.

   The main goal for the convention is to provide a unified notation
   that can be used when defining protocols that use CBOR.  We term the
   convention "Concise Data Definition Language", or CDDL.

   The CBOR notational convention has the following goals:

   (G1)  Provide an unambiguous description of the overall structure of
         a CBOR data item.

   (G2)  Be flexible in expressing the multiple ways in which data can
         be represented in the CBOR data format.

   (G3)  Be able to express common CBOR datatypes and structures.

   (G4)  Provide a single format that is both readable and editable for
         humans and processable by a machine.

   (G5)  Enable automatic checking of CBOR data items for data format
         compliance.

   (G6)  Enable extraction of specific elements from CBOR data for
         further processing.

   Not an original goal per se, but a convenient side effect of the JSON
   generic data model being a subset of the CBOR generic data model, is
   the fact that CDDL can also be used for describing JSON data
   structures (see Appendix E).

   This document has the following structure:

   The syntax of CDDL is defined in Section 3.  Examples of CDDL and a
   related CBOR data item ("instance"), some of which use the JSON form,
   are described in Appendix H.  Section 4 discusses usage of CDDL.
   Examples are provided throughout the text to better illustrate
   concept definitions.  A formal definition of CDDL using ABNF grammar
   [RFC5234] is provided in Appendix B.  Finally, a _prelude_ of
   standard CDDL definitions that is automatically prepended to, and
   thus available in, every CDDL specification is listed in Appendix D.








Birkholz, et al.             Standards Track                    [Page 4]
^L
RFC 8610                          CDDL                         June 2019


1.1.  Requirements Notation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

1.2.  Terminology

   New terms are introduced in _cursive_, which is rendered in plain
   text as the new term surrounded by underscores.  CDDL text in the
   running text is in "typewriter", which is rendered in plain text as
   the CDDL text in double quotes (double quotes are also used in the
   usual English sense; the reader is expected to disambiguate this by
   context).

   In this specification, the term "byte" is used in its now-customary
   sense as a synonym for "octet".

2.  The Style of Data Structure Specification

   CDDL focuses on styles of specification that are in use in the
   community employing the data model as pioneered by JSON and now
   refined in CBOR.

   There are a number of more or less atomic elements of a CBOR data
   model, such as numbers, simple values (false, true, nil), text
   strings, and byte strings; CDDL does not focus on specifying their
   structure.  CDDL of course also allows adding a CBOR tag to a
   data item.

   Beyond those atomic elements, further components of a data structure
   definition language are the datatypes used for composition: arrays
   and maps in CBOR (called "arrays" and "objects" in JSON).  While
   these are only two representation formats, they are used to specify
   four loosely distinguishable styles of composition:

   o  A _vector_: an array of elements that are mostly of the same
      semantics.  The set of signatures associated with a signed data
      item is a typical application of a vector.

   o  A _record_: an array the elements of which have different,
      positionally defined semantics, as detailed in the data structure
      definition.  A 2D point, specified as an array of an x coordinate
      (which comes first) and a y coordinate (coming second), is an
      example of a record, as is the pair of exponent (first) and
      mantissa (second) in a CBOR decimal fraction.



Birkholz, et al.             Standards Track                    [Page 5]
^L
RFC 8610                          CDDL                         June 2019


   o  A _table_: a map from a domain of map keys to a domain of map
      values, that are mostly of the same semantics.  A set of language
      tags, each mapped to a text string translated to that specific
      language, is an example of a table.  The key domain is usually not
      limited to a specific set by the specification but is open for the
      application, e.g., in a table mapping IP addresses to Media Access
      Control (MAC) addresses, the specification does not attempt to
      foresee all possible IP addresses.  In a language such as
      JavaScript, a "Map" (as opposed to a plain "Object") would often
      be employed to achieve the generality of the key domain.

   o  A _struct_: a map from a domain of map keys as defined by the
      specification to a domain of map values the semantics of each of
      which is bound to a specific map key.  This is what many people
      have in mind when they think about JSON objects; CBOR adds the
      ability to use map keys that are not just text strings.  Structs
      can be used to solve problems similar to those records are used
      for; the use of explicit map keys facilitates optionality and
      extensibility.

   Two important concepts provide the foundation for CDDL:

   1.  Instead of defining all four types of composition in CDDL
       separately, or even defining one kind for arrays (vectors and
       records) and one kind for maps (tables and structs), there is
       only one kind of composition in CDDL: the _group_ (Section 2.1).

   2.  The other important concept is that of a _type_.  The entire CDDL
       specification defines a type (the one defined by its first
       _rule_), which formally is the set of CBOR data items that are
       acceptable as "instances" for this specification.  CDDL
       predefines a number of basic types such as "uint" (unsigned
       integer) or "tstr" (text string), often making use of a simple
       formal notation for CBOR data items.  Each value that can be
       expressed as a CBOR data item is also a type in its own right,
       e.g., "1".  A type can be built as a _choice_ of other types,
       e.g., an "int" is either a "uint" or a "nint" (negative integer).
       Finally, a type can be built as an array or a map from a group.

   The rest of this section introduces a number of basic concepts of
   CDDL, and Section 3 defines additional syntax.  Appendix C gives a
   concise summary of the semantics of CDDL.









Birkholz, et al.             Standards Track                    [Page 6]
^L
RFC 8610                          CDDL                         June 2019


2.1.  Groups and Composition in CDDL

   CDDL groups are lists of group _entries_, each of which can be a
   name/value pair or a more complex group expression (which then in
   turn stands for a sequence of name/value pairs).  A CDDL group is a
   production in a grammar that matches certain sequences of name/value
   pairs but not others.  The grammar is based on the concepts of
   Parsing Expression Grammars (PEGs) (see Appendix A).

   In an array context, only the value of the name/value pair is
   represented; the name is annotation only (and can be left off from
   the group specification if not needed).  In a map context, the names
   become the map keys ("member keys").

   In an array context, the actual sequence of elements in the group is
   important, as that sequence is the information that allows
   associating actual array elements with entries in the group.  In a
   map context, the sequence of entries in a group is not relevant (but
   there is still a need to write down group entries in a sequence).

   An array matches a specification given as a group when the group
   matches a sequence of name/value pairs the value parts of which
   exactly match the elements of the array in order.

   A map matches a specification given as a group when the group matches
   a sequence of name/value pairs such that all of these name/value
   pairs are present in the map and the map has no name/value pair that
   is not covered by the group.

   A simple example of using a group directly in a map definition is:

                             person = {
                               age: int,
                               name: tstr,
                               employer: tstr,
                             }

                 Figure 1: Using a Group Directly in a Map

   The three entries of the group are written between the curly braces
   that create the map: here, "age", "name", and "employer" are the
   names that turn into the map key text strings, and "int" and "tstr"
   (text string) are the types of the map values under these keys.








Birkholz, et al.             Standards Track                    [Page 7]
^L
RFC 8610                          CDDL                         June 2019


   A group by itself (without creating a map around it) can be placed in
   (round) parentheses and given a name by using it in a rule:

                             pii = (
                               age: int,
                               name: tstr,
                               employer: tstr,
                             )

                          Figure 2: A Basic Group

   This separate, named group definition allows us to rephrase
   Figure 1 as:

                                person = {
                                  pii
                                }

                      Figure 3: Using a Group by Name

   Note that the (curly) braces signify the creation of a map; the
   groups themselves are neutral as to whether they will be used in a
   map or an array.

   As shown in Figure 1, the parentheses for groups are optional when
   there is some other set of brackets present.  Note that they can
   still be used, leading to this not-so-realistic, but perfectly valid,
   example:

                             person = {(
                               age: int,
                               name: tstr,
                               employer: tstr,
                             )}

              Figure 4: Using a Parenthesized Group in a Map















Birkholz, et al.             Standards Track                    [Page 8]
^L
RFC 8610                          CDDL                         June 2019


   Groups can be used to factor out common parts of structs, e.g.,
   instead of writing specifications in copy/paste style, such as in
   Figure 5, one can factor out the common subgroup, choose a name for
   it, and write only the specific parts into the individual maps
   (Figure 6).

                          person = {
                            age: int,
                            name: tstr,
                            employer: tstr,
                          }

                          dog = {
                            age: int,
                            name: tstr,
                            leash-length: float,
                          }

                      Figure 5: Maps with Copy/Paste

                          person = {
                            identity,
                            employer: tstr,
                          }

                          dog = {
                            identity,
                            leash-length: float,
                          }

                          identity = (
                            age: int,
                            name: tstr,
                          )

                 Figure 6: Using a Group for Factorization

   Note that the lists inside the braces in the above definitions
   constitute (anonymous) groups, while "identity" is a named group,
   which can then be included as part of other groups (anonymous as in
   the example, or themselves named).










Birkholz, et al.             Standards Track                    [Page 9]
^L
RFC 8610                          CDDL                         June 2019


2.1.1.  Usage

   Groups are the instrument used in composing data structures with
   CDDL.  It is a matter of style in defining those structures whether
   to define groups (anonymously) right in their contexts or whether to
   define them in a separate rule and to reference them with their
   respective name (possibly more than once).

   With this, one is allowed to define all small parts of their data
   structures and compose bigger protocol data units with those or to
   have only one big protocol data unit that has all definitions ad hoc
   where needed.

2.1.2.  Syntax

   The composition syntax is intended to be concise and easy to read:

   o  The start and end of a group can be marked by "(" and ")".

   o  Definitions of entries inside of a group are noted as follows:
      _keytype => valuetype,_ (read "keytype maps to valuetype").  The
      comma is actually optional (not just in the final entry), but it
      is considered good style to set it.  The double arrow can be
      replaced by a colon in the common case of directly using a text
      string or integer literal as a key; see Section 3.5.1.  This is
      also the common way of naming elements of an array just for
      documentation; see Section 3.4.

   A basic entry consists of a _keytype_ and a _valuetype_, both of
   which are types (Section 2.2); this entry matches any name/value pair
   the name of which is in the keytype and the value of which is in the
   valuetype.

   A group defined as a sequence of group entries matches any sequence
   of name/value pairs that is composed by concatenation in order of
   what the entries match.

   A group definition can also contain choices between groups; see
   Section 2.2.2.












Birkholz, et al.             Standards Track                   [Page 10]
^L
RFC 8610                          CDDL                         June 2019


2.2.  Types

2.2.1.  Values

   Values such as numbers and strings can be used in place of a type.
   (For instance, this is a very common thing to do for a key type,
   common enough that CDDL provides additional convenience syntax
   for this.)

   The value notation is based on the C language, but does not offer all
   the syntactic variations (see Appendix B for details).  The value
   notation for numbers inherits from C the distinction between integer
   values (no fractional part or exponent given -- NR1 [ISO6093];
   "NR" stands for "numerical representation") and floating-point values
   (where a fractional part, an exponent, or both are present -- NR2 or
   NR3), so the type "1" does not include any floating-point numbers
   while the types "1e3" and "1.5" are both floating-point numbers and
   do not include any integer numbers.

2.2.2.  Choices

   Many places that allow a type also allow a choice between types,
   delimited by a "/" (slash).  The entire choice construct can be put
   into parentheses if this is required to make the construction
   unambiguous (please see Appendix B for details of the CDDL grammar).

   Choices of values can be used to express enumerations:

            attire = "bow tie" / "necktie" / "Internet attire"
            protocol = 6 / 17

   Analogous to types, CDDL also allows choices between groups,
   delimited by a "//" (double slash).  Note that the "//" operator
   binds much more weakly than the other CDDL operators, so each line
   within "delivery" in the following example is its own alternative in
   the group choice:

                   address = { delivery }

                   delivery = (
                   street: tstr, ? number: uint, city //
                   po-box: uint, city //
                   per-pickup: true )

                   city = (
                   name: tstr, zip-code: uint
                   )




Birkholz, et al.             Standards Track                   [Page 11]
^L
RFC 8610                          CDDL                         June 2019


   A group choice matches the union of the sets of name/value pair
   sequences that the alternatives in the choice can.

   For both type choices and group choices, additional alternatives can
   be added to a rule later in separate rules by using "/=" and "//=",
   respectively, instead of "=":

                 attire /= "swimwear"

                 delivery //= (
                 lat: float, long: float, drone-type: tstr
                 )

   It is not an error if a name is first used with a "/=" or "//="
   (there is no need to "create it" with "=").

2.2.2.1.  Ranges

   Instead of naming all the values that make up a choice, CDDL allows
   building a _range_ out of two values that are in an ordering
   relationship: a lower bound (first value) and an upper bound (second
   value).  A range can be inclusive of both bounds given (denoted by
   joining two values by ".."), or it can include the lower bound and
   exclude the upper bound (denoted by instead using "...").  If the
   lower bound exceeds the upper bound, the resulting type is the empty
   set (this behavior can be desirable when generics (Section 3.10) are
   being used).

         device-address = byte
         max-byte = 255
         byte = 0..max-byte ; inclusive range
         first-non-byte = 256
         byte1 = 0...first-non-byte ; byte1 is equivalent to byte

   CDDL currently only allows ranges between integers (matching integer
   values) or between floating-point values (matching floating-point
   values).  If both are needed in a type, a type choice between the two
   kinds of ranges can be (clumsily) used:

                int-range = 0..10 ; only integers match
                float-range = 0.0..10.0 ; only floats match
                BAD-range1 = 0..10.0 ; NOT DEFINED
                BAD-range2 = 0.0..10 ; NOT DEFINED
                numeric-range = int-range / float-range

   (See also the control operators .lt/.ge and .le/.gt in
   Section 3.8.6.)




Birkholz, et al.             Standards Track                   [Page 12]
^L
RFC 8610                          CDDL                         June 2019


   Note that the dot is a valid name continuation character in CDDL, so

      min..max

   is not a range expression but a single name.  When using a name as
   the left-hand side of a range operator, use spacing as in

      min .. max

   to separate off the range operator.

2.2.2.2.  Turning a Group into a Choice

   Some choices are built out of large numbers of values, often
   integers, each of which is best given a semantic name in the
   specification.  Instead of naming each of these integers and then
   accumulating them into a choice, CDDL allows building a choice from a
   group by prefixing it with an "&" character:

              terminal-color = &basecolors
              basecolors = (
                black: 0,  red: 1,  green: 2,  yellow: 3,
                blue: 4,  magenta: 5,  cyan: 6,  white: 7,
              )
              extended-color = &(
                basecolors,
                orange: 8,  pink: 9,  purple: 10,  brown: 11,
              )

   As with the use of groups in arrays (Section 3.4), the member names
   have only documentary value (in particular, they might be used by a
   tool when displaying integers that are taken from that choice).

2.2.3.  Representation Types

   CDDL allows the specification of a data item type by referring to the
   CBOR representation (specifically, to major types and additional
   information; see Section 2 of [RFC7049]).  How this is used should be
   evident from the prelude (Appendix D): a hash mark ("#") optionally
   followed by a number from 0 to 7 identifying the major type, which
   then can be followed by a dot and a number specifying the additional
   information.  This construction specifies the set of values that can
   be serialized in CBOR (i.e., "any"), by the given major type if one
   is given, or by the given major type with the additional information
   if both are given.  Where a major type of 6 (Tag) is used, the type
   of the tagged item can be specified by appending it in parentheses.





Birkholz, et al.             Standards Track                   [Page 13]
^L
RFC 8610                          CDDL                         June 2019


   Note that although this notation is based on the CBOR serialization,
   it is about a set of values at the data model level, e.g., "#7.25"
   specifies the set of values that can be represented as half-precision
   floats; it does not mandate that these values also do have to be
   serialized as half-precision floats: CDDL does not provide any
   language means to restrict the choice of serialization variants.
   This also enables the use of CDDL with JSON, which uses a
   fundamentally different way of serializing (some of) the same values.

   It may be necessary to make use of representation types outside the
   prelude, e.g., a specification could start by making use of an
   existing tag in a more specific way or could define a new tag not
   defined in the prelude:

      my_breakfast = #6.55799(breakfast)   ; cbor-any is too general!
      breakfast = cereal / porridge
      cereal = #6.998(tstr)
      porridge = #6.999([liquid, solid])
      liquid = milk / water
      milk = 0
      water = 1
      solid = tstr

2.2.4.  Root Type

   There is no special syntax to identify the root of a CDDL data
   structure definition: that role is simply taken by the first rule
   defined in the file.

   This is motivated by the usual top-down approach for defining data
   structures, decomposing a big data structure unit into smaller parts;
   however, except for the root type, there is no need to strictly
   follow this sequence.

   (Note that there is no way to use a group as a root -- it must be
   a type.)















Birkholz, et al.             Standards Track                   [Page 14]
^L
RFC 8610                          CDDL                         June 2019


3.  Syntax

   In this section, the overall syntax of CDDL is shown, alongside some
   examples just illustrating syntax.  (The definition does not attempt
   to be overly formal; refer to Appendix B for details.)

3.1.  General Conventions

   The basic syntax is inspired by ABNF [RFC5234], with the following:

   o  Rules, whether they define groups or types, are defined with a
      name, followed by an equals sign "=" and the actual definition
      according to the respective syntactic rules of that definition.

   o  A name can consist of any of the characters from the set {"A" to
      "Z", "a" to "z", "0" to "9", "_", "-", "@", ".", "$"}, starting
      with an alphabetic character (including "@", "_", "$") and ending
      in such a character or a digit.

      *  Names are case sensitive.

      *  It is preferred style to start a name with a lowercase letter.

      *  The hyphen is preferred over the underscore (except in a
         "bareword" (Section 3.5.1), where the semantics may actually
         require an underscore).

      *  The period may be useful for larger specifications, to express
         some module structure (as in "tcp.throughput" vs.
         "udp.throughput").

      *  A number of names are predefined in the CDDL prelude, as listed
         in Appendix D.

      *  Rule names (types or groups) do not appear in the actual CBOR
         encoding, but names used as "barewords" in member keys do.

   o  Comments are started by a ";" (semicolon) character and finish at
      the end of a line (LF or CRLF).

   o  Except within strings, whitespace (spaces, newlines, and comments)
      is used to separate syntactic elements for readability (and to
      separate identifiers, range operators, or numbers that follow each
      other); it is otherwise completely optional.

   o  Hexadecimal numbers are preceded by "0x" (without quotes) and are
      case insensitive.  Similarly, binary numbers are preceded by "0b".




Birkholz, et al.             Standards Track                   [Page 15]
^L
RFC 8610                          CDDL                         June 2019


   o  Text strings are enclosed by double quotation '"' characters.
      They follow the conventions for strings as defined in Section 7 of
      [RFC8259].  (ABNF users may want to note that there is no support
      in CDDL for the concept of case insensitivity in text strings; if
      necessary, regular expressions can be used (Section 3.8.3).)

   o  Byte strings are enclosed by single quotation "'" characters and
      may be prefixed by "h" or "b64".  If unprefixed, the string is
      interpreted as with a text string, except that single quotes must
      be escaped and that the resulting UTF-8 bytes are marked as a byte
      string (major type 2).  If prefixed as "h" or "b64", the string is
      interpreted as a sequence of pairs of hex digits (base16; see
      Section 8 of [RFC4648]) or a base64(url) string (Section 4 or
      Section 5 of [RFC4648]), respectively (as with the diagnostic
      notation in Section 6 of [RFC7049]; cf. Appendix G.2); any
      whitespace present within the string (including comments) is
      ignored in the prefixed case.

   o  CDDL uses UTF-8 [RFC3629] for its encoding.  Processing of CDDL
      does not involve Unicode normalization processes.

   Example:

                    ; This is a comment
                    person = { g }

                    g = (
                      "name": tstr,
                      age: int,  ; "age" is a bareword
                    )

3.2.  Occurrence

   An optional _occurrence_ indicator can be given in front of a group
   entry.  It is either (1) one of the characters "?" (optional), "*"
   (zero or more), or "+" (one or more) or (2) of the form n*m, where n
   and m are optional unsigned integers and n is the lower limit
   (default 0) and m is the upper limit (default no limit) of
   occurrences.

   If no occurrence indicator is specified, the group entry is to occur
   exactly once (as if 1*1 were specified).  A group entry with an
   occurrence indicator matches sequences of name/value pairs that are
   composed by concatenating a number of sequences that the basic group
   entry matches, where the number needs to be allowed by the occurrence
   indicator.





Birkholz, et al.             Standards Track                   [Page 16]
^L
RFC 8610                          CDDL                         June 2019


   Note that CDDL, outside any directives/annotations that could
   possibly be defined, does not make any prescription as to whether
   arrays or maps use definite-length or indefinite-length encoding.
   That is, there is no correlation between leaving the size of an array
   "open" in the spec and the fact that it is then interchanged with
   definite or indefinite length.

   Please also note that CDDL can describe flexibility that the data
   model of the target representation does not have.  This is rather
   obvious for JSON but is also relevant for CBOR:

                           apartment = {
                             kitchen: size,
                             * bedroom: size,
                           }
                           size = float ; in m2

   The previous specification does not mean that CBOR is changed to
   allow using the key "bedroom" more than once.  In other words, due to
   the restrictions imposed by the data model, the third line pretty
   much turns into:

                             ? bedroom: size,

   (Occurrence indicators beyond one are still useful in maps for groups
   that allow a variety of keys.)

3.3.  Predefined Names for Types

   CDDL predefines a number of names.  This subsection summarizes these
   names, but please see Appendix D for the exact definitions.

   The following keywords for primitive datatypes are defined:

   "bool"  Boolean value (major type 7, additional information 20
      or 21).

   "uint"  An unsigned integer (major type 0).

   "nint"  A negative integer (major type 1).

   "int"  An unsigned integer or a negative integer.

   "float16"  A number representable as a half-precision float [IEEE754]
      (major type 7, additional information 25).

   "float32"  A number representable as a single-precision float
      [IEEE754] (major type 7, additional information 26).



Birkholz, et al.             Standards Track                   [Page 17]
^L
RFC 8610                          CDDL                         June 2019


   "float64"  A number representable as a double-precision float
      [IEEE754] (major type 7, additional information 27).

   "float"  One of float16, float32, or float64.

   "bstr" or "bytes"  A byte string (major type 2).

   "tstr" or "text"  Text string (major type 3).

   (Note that there are no predefined names for arrays or maps; these
   are defined with the syntax given below.)

   In addition, a number of types are defined in the prelude that are
   associated with CBOR tags, such as "tdate", "bigint", "regexp", etc.

3.4.  Arrays

   Array definitions surround a group with square brackets.

   For each entry, an occurrence indicator as specified in Section 3.2
   is permitted.

   For example:

                     unlimited-people = [* person]
                     one-or-two-people = [1*2 person]
                     at-least-two-people = [2* person]
                     person = (
                         name: tstr,
                         age: uint,
                     )

   The group "person" is defined in such a way that repeating it in the
   array each time generates alternating names and ages, so these are
   four valid values for a data item of type "unlimited-people":

      ["roundlet", 1047, "psychurgy", 2204, "extrarhythmical", 2231]
      []
      ["aluminize", 212, "climograph", 4124]
      ["penintime", 1513, "endocarditis", 4084, "impermeator", 1669,
       "coextension", 865]










Birkholz, et al.             Standards Track                   [Page 18]
^L
RFC 8610                          CDDL                         June 2019


3.5.  Maps

   The syntax for specifying maps merits special attention, as well as a
   number of optimizations and conveniences, as it is likely to be the
   focal point of many specifications employing CDDL.  While the syntax
   does not strictly distinguish struct and table usage of maps, it
   caters specifically to each of them.

   But first, let's reiterate a feature of CBOR that it has inherited
   from JSON: the key/value pairs in CBOR maps have no fixed ordering.
   (One could imagine situations where fixing the ordering may be of
   use.  For example, a decoder could look for values related with
   integer keys 1, 3, and 7.  If the order were fixed and the decoder
   encounters the key 4 without having encountered key 3, it could
   conclude that key 3 is not available without doing more complicated
   bookkeeping.  Unfortunately, neither JSON nor CBOR supports this, so
   no attempt was made to support this in CDDL either.)

3.5.1.  Structs

   The "struct" usage of maps is similar to the way JSON objects are
   used in many JSON applications.

   A map is defined in the same way as that for defining an array (see
   Section 3.4), except for using curly braces "{}" instead of square
   brackets "[]".

   An occurrence indicator as specified in Section 3.2 is permitted for
   each group entry.

   The following is an example of a record with a structure embedded:

       Geography = [
         city           : tstr,
         gpsCoordinates : GpsCoordinates,
       ]

       GpsCoordinates = {
         longitude      : uint,            ; degrees, scaled by 10^7
         latitude       : uint,            ; degrees, scaled by 10^7
       }

   When encoding, the Geography record is encoded using a CBOR array
   with two members (the keys for the group entries are ignored),
   whereas the GpsCoordinates structure is encoded as a CBOR map with
   two key/value pairs.





Birkholz, et al.             Standards Track                   [Page 19]
^L
RFC 8610                          CDDL                         June 2019


   Types used in a structure can be defined in separate rules or just in
   place (potentially placed inside parentheses, such as for choices).
   For example:

                           located-samples = {
                             sample-point: int,
                             samples: [+ float],
                           }

   where "located-samples" is the datatype to be used when referring to
   the struct, and "sample-point" and "samples" are the keys to be used.
   This is actually a complete example: an identifier that is followed
   by a colon can be directly used as the text string for a member key
   (we speak of a "bareword" member key), as can a double-quoted string
   or a number.  (When other types -- in particular, types that contain
   more than one value -- are used as the types of keys, they are
   followed by a double arrow; see below.)

   If a text string key does not match the syntax for an identifier (or
   if the specifier just happens to prefer using double quotes), the
   text string syntax can also be used in the member key position,
   followed by a colon.  The above example could therefore have been
   written with quoted strings in the member key positions.

   More generally, types specified in ways other than those listed for
   the cases described above can be used in a key-type position by
   following them with a double arrow -- in particular, the double arrow
   is necessary if a type is named by an identifier (which, when
   followed by a colon, would be interpreted as a "bareword" and turned
   into a text string).  A literal text string also gives rise to a type
   (which contains a single value only -- the given string), so another
   form for this example is:

                         located-samples = {
                           "sample-point" => int,
                           "samples" => [+ float],
                         }














Birkholz, et al.             Standards Track                   [Page 20]
^L
RFC 8610                          CDDL                         June 2019


   See Section 3.5.4 below for how the colon (":") shortcut described
   here also adds some implied semantics.

   A better way to demonstrate the use of the double arrow may be:

             located-samples = {
               sample-point: int,
               samples: [+ float],
               * equipment-type => equipment-tolerances,
             }
             equipment-type = [name: tstr, manufacturer: tstr]
             equipment-tolerances = [+ [float, float]]

   The example below defines a struct with optional entries: display
   name (as a text string), the name components first name and family
   name (as text strings), and age information (as an unsigned integer).

                          PersonalData = {
                            ? displayName: tstr,
                            NameComponents,
                            ? age: uint,
                          }

                          NameComponents = (
                            ? firstName: tstr,
                            ? familyName: tstr,
                          )

   Note that the group definition for NameComponents does not generate
   another map; instead, all four keys are directly in the struct built
   by PersonalData.

   In this example, all key/value pairs are optional from the
   perspective of CDDL.  With no occurrence indicator, an entry is
   mandatory.
















Birkholz, et al.             Standards Track                   [Page 21]
^L
RFC 8610                          CDDL                         June 2019


   If the addition of more entries not specified by the current
   specification is desired, one can add this possibility explicitly:

                          PersonalData = {
                            ? displayName: tstr,
                            NameComponents,
                            ? age: uint,
                            * tstr => any
                          }

                          NameComponents = (
                            ? firstName: tstr,
                            ? familyName: tstr,
                          )

            Figure 7: Personal Data: Example for Extensibility

   The CDDL tool described in Appendix F generated the following as one
   acceptable instance for this specification:

         {"familyName": "agust", "antiforeignism": "pretzel",
          "springbuck": "illuminatingly", "exuviae": "ephemeris",
          "kilometrage": "frogfish"}

   (See Section 3.9 for one way to explicitly identify an extension
   point.)

3.5.2.  Tables

   A table can be specified by defining a map with entries where the
   key type allows more than just a single value; for example:

                         square-roots = {* x => y}
                         x = int
                         y = float

   Here, the key in each key/value pair has datatype x (defined as int),
   and the value has datatype y (defined as float).

   If the specification does not need to restrict one of x or y (i.e.,
   the application is free to choose per entry), it can be replaced by
   the predefined name "any".









Birkholz, et al.             Standards Track                   [Page 22]
^L
RFC 8610                          CDDL                         June 2019


   As another example, the following could be used as a conversion table
   converting from an integer or float to a string:

                      tostring = {* mynumber => tstr}
                      mynumber = int / float

3.5.3.  Non-deterministic Order

   While the way arrays are matched is fully determined by the PEG
   formalism (see Appendix A), matching is more complicated for maps, as
   maps do not have an inherent order.  For each candidate name/value
   pair that the PEG algorithm would try, a matching member is picked
   out of the entire map.  For certain group expressions, more than one
   member in the map may match.  Most often, this is inconsequential, as
   the group expression tends to consume all matches:

                            labeled-values = {
                              ? fritz: number,
                              * label => value
                            }
                            label = text
                            value = number

   Here, if any member with the key "fritz" is present, this will be
   picked by the first entry of the group; all remaining text/number
   members will be picked by the second entry (and if anything remains
   unpicked, the map does not match).

   However, it is possible to construct group expressions where what is
   actually picked is indeterminate, but does matter:

                            do-not-do-this = {
                              int => int,
                              int => 6,
                            }

   When this expression is matched against "{3: 5, 4: 6}", the first
   group entry might pick off the "3: 5", leaving "4: 6" for matching
   the second one.  Or it might pick off "4: 6", leaving nothing for the
   second entry.  This pathological non-determinism is caused by
   specifying "more general" before "more specific" and by having a
   general rule that only consumes a subset of the map key/value pairs
   that it is able to match -- both tend not to occur in real-world
   specifications of maps.  At the time of writing, CDDL tools cannot
   detect such cases automatically, and for the present version of the
   CDDL specification, the specification writer is simply urged to not
   write pathologically non-deterministic specifications.




Birkholz, et al.             Standards Track                   [Page 23]
^L
RFC 8610                          CDDL                         June 2019


   (The astute reader will be reminded of what was called "ambiguous
   content models" in the Standard Generalized Markup Language (SGML)
   and "non-deterministic content models" in XML.  That problem is
   related to the one described here, but the problem here is
   specifically caused by the lack of order in maps, something that the
   XML schema languages do not have to contend with.  Note that
   RELAX NG's "interleave" pattern handles lack of order explicitly on
   the specification side, while the instances in XML always have
   determinate order.)

3.5.4.  Cuts in Maps

   The extensibility idiom discussed above for structs has one problem:

                        extensible-map-example = {
                          ? "optional-key" => int,
                          * tstr => any
                        }

   In this example, there is one optional key "optional-key", which,
   when present, maps to an integer.  There is also a wildcard for any
   future additions.

   Unfortunately, the data item

                      { "optional-key": "nonsense" }

   does match this specification: while the first entry of the group
   does not match, the second one (the wildcard) does.  This may very
   well be desirable (e.g., if a future extension is to be allowed to
   extend the type of "optional-key"), but in many cases it isn't.

   In anticipation of a more general potential feature called "cuts",
   CDDL allows inserting a cut "^" into the definition of the map entry:

                       extensible-map-example = {
                         ? "optional-key" ^ => int,
                         * tstr => any
                       }

   A cut in this position means that once the member key matches the
   name part of an entry that carries a cut, other potential matches for
   the key of the member that occur in later entries in the group of the
   map are no longer allowed.  In other words, when a group entry would
   pick a key/value pair based on just a matching key, it "locks in" the
   pick -- this rule applies, independently of whether the value matches





Birkholz, et al.             Standards Track                   [Page 24]
^L
RFC 8610                          CDDL                         June 2019


   as well, so when it does not, the entire map fails to match.  In
   summary, the example above no longer matches the specification as
   modified with the cut.

   Since the desire for this kind of exclusive matching is so frequent,
   the ":" shortcut is actually defined to include the cut semantics.
   So, the preceding example (including the cut) can be written more
   simply as:

                        extensible-map-example = {
                          ? "optional-key": int,
                          * tstr => any
                        }

   or even shorter, using a bareword for the key:

                        extensible-map-example = {
                          ? optional-key: int,
                          * tstr => any
                        }

3.6.  Tags

   A type can make use of a CBOR tag (major type 6) by using the
   representation type notation, giving #6.nnn(type) where nnn is an
   unsigned integer giving the tag number and "type" is the type of the
   data item being tagged.

   For example, the following line from the CDDL prelude (Appendix D)
   defines "biguint" as a type name for an unsigned bignum N:

                           biguint = #6.2(bstr)

   The tags defined by [RFC7049] are included in the prelude.
   Additional tags registered since [RFC7049] was written need to be
   added to a CDDL specification as needed; e.g., a binary Universally
   Unique Identifier (UUID) tag could be referenced as "buuid" in a
   specification after defining

                            buuid = #6.37(bstr)

   In the following example, usage of tag 32 for URIs is optional:

                        my_uri = #6.32(tstr) / tstr







Birkholz, et al.             Standards Track                   [Page 25]
^L
RFC 8610                          CDDL                         June 2019


3.7.  Unwrapping

   The group that is used to define a map or an array can often be
   reused in the definition of another map or array.  Similarly, a type
   defined as a tag carries an internal data item that one would like to
   refer to.  In these cases, it is expedient to simply use the name of
   the map, array, or tag type as a handle for the group or type defined
   inside it.

   The "unwrap" operator (written by preceding a name by a tilde
   character "~") can be used to strip the type defined for a name by
   one layer, exposing the underlying group (for maps and arrays) or
   type (for tags).

   For example, an application might want to define a basic header and
   an advanced header.  Without unwrapping, this might be done as
   follows:

             basic-header-group = (
               field1: int,
               field2: text,
             )

             basic-header = [ basic-header-group ]

             advanced-header = [
               basic-header-group,
               field3: bytes,
               field4: number, ; as in the tagged type "time"
             ]

   Unwrapping simplifies this to:

                            basic-header = [
                              field1: int,
                              field2: text,
                            ]

                            advanced-header = [
                              ~basic-header,
                              field3: bytes,
                              field4: ~time,
                            ]

   (Note that leaving out the first unwrap operator in the latter
   example would lead to nesting the basic-header in its own array
   inside the advanced-header, while, with the unwrapped basic-header,
   the definition of the group inside basic-header is essentially



Birkholz, et al.             Standards Track                   [Page 26]
^L
RFC 8610                          CDDL                         June 2019


   repeated inside advanced-header, leading to a single array.  This can
   be used for various applications often solved by inheritance in
   programming languages.  The effect of unwrapping can also be
   described as "threading in" the group or type inside the referenced
   type, which suggested the thread-like "~" character.)

3.8.  Controls

   A _control_ allows relating a _target_ type with a _controller_ type
   via a _control operator_.

   The syntax for a control type is "target .control-operator
   controller", where control operators are special identifiers prefixed
   by a dot.  (Note that _target_ or _controller_ might need to be
   parenthesized.)

   A number of control operators are defined at this point.  Further
   control operators may be defined by new versions of this
   specification or by registering them according to the procedures in
   Section 6.1.

3.8.1.  Control Operator .size

   A ".size" control controls the size of the target in bytes by the
   control type.  The control is defined for text and byte strings,
   where it directly controls the number of bytes in the string.  It is
   also defined for unsigned integers (see below).  Figure 8 shows
   example usage for byte strings.

                   full-address = [[+ label], ip4, ip6]
                   ip4 = bstr .size 4
                   ip6 = bstr .size 16
                   label = bstr .size (1..63)

                    Figure 8: Control for Size in Bytes

   When applied to an unsigned integer, the ".size" control restricts
   the range of that integer by giving a maximum number of bytes that
   should be needed in a computer representation of that unsigned
   integer.  In other words, "uint .size N" is equivalent to
   "0...BYTES_N", where BYTES_N == 256**N.

     audio_sample = uint .size 3 ; 24-bit, equivalent to 0...16777216

                Figure 9: Control for Integer Size in Bytes






Birkholz, et al.             Standards Track                   [Page 27]
^L
RFC 8610                          CDDL                         June 2019


   Note that, as with value restrictions in CDDL, this control is not a
   representation constraint; a number that fits into fewer bytes can
   still be represented in that form, and an inefficient implementation
   could use a longer form (unless that is restricted by some format
   constraints outside of CDDL, such as the rules in Section 3.9 of
   [RFC7049]).

3.8.2.  Control Operator .bits

   A ".bits" control on a byte string indicates that, in the target,
   only the bits numbered by a number in the control type are allowed to
   be set.  (Bits are counted the usual way, bit number "n" being set in
   "str" meaning that "(str[n >> 3] & (1 << (n & 7))) != 0".)
   Similarly, a ".bits" control on an unsigned integer "i" indicates
   that for all unsigned integers "n" where "(i & (1 << n)) != 0", "n"
   must be in the control type.

                      tcpflagbytes = bstr .bits flags
                      flags = &(
                        fin: 8,
                        syn: 9,
                        rst: 10,
                        psh: 11,
                        ack: 12,
                        urg: 13,
                        ece: 14,
                        cwr: 15,
                        ns: 0,
                      ) / (4..7) ; data offset bits

                      rwxbits = uint .bits rwx
                      rwx = &(r: 2, w: 1, x: 0)

                Figure 10: Control for What Bits Can Be Set

   The CDDL tool described in Appendix F generates the following ten
   example instances for "tcpflagbytes":

      h'906d' h'01fc' h'8145' h'01b7' h'013d' h'409f' h'018e' h'c05f'
      h'01fa' h'01fe'

   These examples do not illustrate that the above CDDL specification
   does not explicitly specify a size of two bytes: a valid all-clear
   instance of flag bytes could be "h''" or "h'00'" or even "h'000000'"
   as well.






Birkholz, et al.             Standards Track                   [Page 28]
^L
RFC 8610                          CDDL                         June 2019


3.8.3.  Control Operator .regexp

   A ".regexp" control indicates that the text string given as a target
   needs to match the XML Schema Definition (XSD) regular expression
   given as a value in the control type.  XSD regular expressions are
   defined in Appendix F of [W3C.REC-xmlschema-2-20041028].

     nai = tstr .regexp "[A-Za-z0-9]+@[A-Za-z0-9]+(\\.[A-Za-z0-9]+)+"

                   Figure 11: Control with an XSD regexp

   An example matching this regular expression:

                       "N1@CH57HF.4Znqe0.dYJRN.igjf"

3.8.3.1.  Usage Considerations

   Note that XSD regular expressions do not support the usual \x or \u
   escapes for hexadecimal expression of bytes or Unicode code points.
   However, in CDDL the XSD regular expressions are contained in text
   strings, the literal notation for which provides \u escapes; this
   should suffice for most applications that use regular expressions for
   text strings.  (Note that this also means that there is one level of
   string escaping before the XSD escaping rules are applied.)

   XSD regular expressions support character class subtraction, a
   feature often not found in regular expression libraries;
   specification writers may want to use this feature sparingly.
   Similar considerations apply to Unicode character classes; where
   these are used, the specification that employs CDDL SHOULD identify
   which Unicode versions are addressed.

   Other surprises for infrequent users of XSD regular expressions may
   include the following:

   o  No direct support for case insensitivity.  While case
      insensitivity has gone mostly out of fashion in protocol design,
      it is sometimes needed and then needs to be expressed manually as
      in "[Cc][Aa][Ss][Ee]".

   o  The support for popular character classes such as \w and \d is
      based on Unicode character properties; this is often not what is
      desired in an ASCII-based protocol and thus might lead to
      surprises.  (\s and \S do have their more conventional meanings,
      and "." matches any character but the line-ending characters \r
      or \n.)





Birkholz, et al.             Standards Track                   [Page 29]
^L
RFC 8610                          CDDL                         June 2019


3.8.3.2.  Discussion

   There are many flavors of regular expression in use in the
   programming community.  For instance, Perl-Compatible Regular
   Expressions (PCREs) are widely used and probably are more useful than
   XSD regular expressions.  However, there is no normative reference
   for PCREs that could be used in the present document.  Instead, we
   opt for XSD regular expressions for now.  There is precedent for that
   choice in the IETF, e.g., in YANG [RFC7950].

   Note that CDDL uses controls as its main extension point.  This
   creates the opportunity to add further regular expression formats in
   addition to the one referenced here, if desired.  As an example, a
   proposal for a ".pcre" control is defined in [CDDL-Freezer].

3.8.4.  Control Operators .cbor and .cborseq

   A ".cbor" control on a byte string indicates that the byte string
   carries a CBOR-encoded data item.  Decoded, the data item matches the
   type given as the right-hand-side argument (type1 in the following
   example).

      "bytes .cbor type1"

   Similarly, a ".cborseq" control on a byte string indicates that the
   byte string carries a sequence of CBOR-encoded data items.  When the
   data items are taken as an array, the array matches the type given as
   the right-hand-side argument (type2 in the following example).

      "bytes .cborseq type2"

   (The conversion of the encoded sequence to an array can be effected,
   for instance, by wrapping the byte string between the two bytes 0x9f
   and 0xff and decoding the wrapped byte string as a CBOR-encoded
   data item.)

3.8.5.  Control Operators .within and .and

   A ".and" control on a type indicates that the data item matches both
   the left-hand-side type and the type given as the right-hand side.
   (Formally, the resulting type is the intersection of the two types
   given.)

      "type1 .and type2"







Birkholz, et al.             Standards Track                   [Page 30]
^L
RFC 8610                          CDDL                         June 2019


   A variant of the ".and" control is the ".within" control, which
   expresses an additional intent: the left-hand-side type is meant to
   be a subset of the right-hand-side type.

      "type1 .within type2"

   While both forms have the identical formal semantics (intersection),
   the intention of the ".within" form is that the right-hand side gives
   guidance to the types allowed on the left-hand side, which typically
   is a socket (Section 3.9):

        message = $message .within message-structure
        message-structure = [message_type, *message_option]
        message_type = 0..255
        message_option = any

        $message /= [3, dough: text, topping: [* text]]
        $message /= [4, noodles: text, sauce: text, parmesan: bool]

   For ".within", a tool might flag an error if type1 allows data items
   that are not allowed by type2.  In contrast, for ".and", there is no
   expectation that type1 is already a subset of type2.

3.8.6.  Control Operators .lt, .le, .gt, .ge, .eq, .ne, and .default

   The controls .lt, .le, .gt, .ge, .eq, and .ne specify a constraint
   on the left-hand-side type to be a value less than, less than or
   equal to, greater than, greater than or equal to, equal to, or not
   equal to a value given as a right-hand-side type (containing just
   that single value).  In the present specification, the first four
   controls (.lt, .le, .gt, and .ge) are defined only for numeric types,
   as these have a natural ordering relationship.

                     speed = number .ge 0  ; unit: m/s

   .ne and .eq are defined for both numeric values and values of other
   types.  If one of the values is not of a numeric type, equality is
   determined as follows: text strings are equal (satisfy .eq / do not
   satisfy .ne) if they are bytewise identical; the same applies for
   byte strings.  Arrays are equal if they have the same number of
   elements, all of which are equal pairwise in order between the
   arrays.  Maps are equal if they have the same number of key/value
   pairs, and there is pairwise equality between the key/value pairs
   between the two maps.  Tagged values are equal if they both have the
   same tag and the values are equal.  Values of simple types match if
   they are the same values.  Numeric types that occur within arrays,





Birkholz, et al.             Standards Track                   [Page 31]
^L
RFC 8610                          CDDL                         June 2019


   maps, or tagged values are equal if their numeric value is equal and
   they are both integers or both floating-point values.  All other
   cases are not equal (e.g., comparing a text string with a byte
   string).

   A variant of the ".ne" control is the ".default" control, which
   expresses an additional intent: the value specified by the
   right-hand-side type is intended as a default value for the
   left-hand-side type given, and the implied .ne control is there to
   prevent this value from being sent over the wire.  This control is
   only meaningful when the control type is used in an optional context;
   otherwise, there would be no way to make use of the default value.

               timer = {
                 time: uint,
                 ? displayed-step: (number .gt 0) .default 1
               }

3.9.  Socket/Plug

   For both type choices and group choices, a mechanism is defined that
   facilitates starting out with empty choices and assembling them
   later, potentially in separate files that are concatenated to build
   the full specification.

   Per convention, CDDL extension points are marked with a leading
   dollar sign (types) or two leading dollar signs (groups).  Tools
   honor that convention by not raising an error if such a type or group
   is not defined at all; the symbol is then taken to be an empty type
   choice (group choice), i.e., no choice is available.

            tcp-header = {seq: uint, ack: uint, * $$tcp-option}

            ; later, in a different file

            $$tcp-option //= (
            sack: [+(left: uint, right: uint)]
            )

            ; and, maybe in another file

            $$tcp-option //= (
            sack-permitted: true
            )

   Names that start with a single "$" are "type sockets", starting out
   as an empty type, and intended to be extended via "/=".  Names that
   start with a double "$$" are "group sockets", starting out as an



Birkholz, et al.             Standards Track                   [Page 32]
^L
RFC 8610                          CDDL                         June 2019


   empty group choice, and intended to be extended via "//=".  In either
   case, it is not an error if there is no definition for a socket at
   all; this then means there is no way to satisfy the rule (i.e., the
   choice is empty).

   As a convention, all definitions (plugs) for socket names must be
   augmentations, i.e., they must be using "/=" and "//=", respectively.

   To pick up the example illustrated in Figure 7, the socket/plug
   mechanism could be used as shown in Figure 12:

                     PersonalData = {
                       ? displayName: tstr,
                       NameComponents,
                       ? age: uint,
                       * $$personaldata-extensions
                     }

                     NameComponents = (
                       ? firstName: tstr,
                       ? familyName: tstr,
                     )

                     ; The above already works as is.
                     ; But then, we can add later:

                     $$personaldata-extensions //= (
                       favorite-salsa: tstr,
                     )

                     ; and again, somewhere else:

                     $$personaldata-extensions //= (
                       shoesize: uint,
                     )

     Figure 12: Personal Data Example: Using Socket/Plug Extensibility

3.10.  Generics

   Using angle brackets, the left-hand side of a rule can add formal
   parameters after the name being defined, as in:

      messages = message<"reboot", "now"> / message<"sleep", 1..100>
      message<t, v> = {type: t, value: v}






Birkholz, et al.             Standards Track                   [Page 33]
^L
RFC 8610                          CDDL                         June 2019


   When using a generic rule, the formal parameters are bound to the
   actual arguments supplied (also using angle brackets), within the
   scope of the generic rule (as if there were a rule of the form
   parameter = argument).

   Generic rules can be used for establishing names for both types and
   groups.

   (At this time, there are some limitations to the nesting of generics
   in the CDDL tool described in Appendix F.)

3.11.  Operator Precedence

   As with any language that has multiple syntactic features such as
   prefix and infix operators, CDDL has operators that bind more tightly
   than others.  This is becoming more complicated than, say, in ABNF,
   as CDDL has both types and groups, with operators that are specific
   to these concepts.  Type operators (such as "/" for type choice)
   operate on types, while group operators (such as "//" for group
   choice) operate on groups.  Types can simply be used in groups, but
   groups need to be bracketed (as arrays or maps) to become types.  So,
   type operators naturally bind closer than group operators.

   For instance, in

      t = [group1]
      group1 = (a / b // c / d)
      a = 1 b = 2 c = 3 d = 4

   group1 is a group choice between the type choice of a and b and the
   type choice of c and d.  This becomes more relevant once member keys
   and/or occurrences are added in:

      t = {group2}
      group2 = (? ab: a / b // cd: c / d)
      a = 1 b = 2 c = 3 d = 4

   is a group choice between the optional member "ab" of type a or b and
   the member "cd" of type c or d.  Note that the optionality is
   attached to the first choice ("ab"), not to the second choice.











Birkholz, et al.             Standards Track                   [Page 34]
^L
RFC 8610                          CDDL                         June 2019


   Similarly, in

      t = [group3]
      group3 = (+ a / b / c)
      a = 1 b = 2 c = 3

   group3 is a repetition of a type choice between a, b, and c; if just
   a is to be repeatable, a group choice is needed to focus the
   occurrence:

      t = [group4]
      group4 = (+ a // b / c)
      a = 1 b = 2 c = 3

   group4 is a group choice between a repeatable a and a single b or c.

   A comment has been that the semantics of group3 could be
   counterintuitive.  In general, as with many other languages with
   operator precedence rules, the specification writer is encouraged not
   to rely on them, but to insert parentheses liberally to guide readers
   that are not familiar with CDDL precedence rules:

      t = [group4a]
      group4a = ((+ a) // (b / c))
      a = 1 b = 2 c = 3

   The operator precedences, in sequence of loose to tight binding, are
   defined in Appendix B and summarized in Table 1.  (Arities given are
   1 for unary prefix operators and 2 for binary infix operators.)






















Birkholz, et al.             Standards Track                   [Page 35]
^L
RFC 8610                          CDDL                         June 2019


       +----------+-------+---------------------------+------------+
       | Operator | Arity | Operates on               | Precedence |
       +----------+-------+---------------------------+------------+
       |    =     |   2   | name = type, name = group |     1      |
       |    /=    |   2   | name /= type              |     1      |
       |   //=    |   2   | name //= group            |     1      |
       |    //    |   2   | group // group            |     2      |
       |    ,     |   2   | group, group              |     3      |
       |    *     |   1   | * group                   |     4      |
       |   n*m    |   1   | n*m group                 |     4      |
       |    +     |   1   | + group                   |     4      |
       |    ?     |   1   | ? group                   |     4      |
       |    =>    |   2   | type => type              |     5      |
       |    :     |   2   | name: type                |     5      |
       |    /     |   2   | type / type               |     6      |
       |    ..    |   2   | type..type                |     7      |
       |   ...    |   2   | type...type               |     7      |
       |  .ctrl   |   2   | type .ctrl type           |     7      |
       |    &     |   1   | &group                    |     8      |
       |    ~     |   1   | ~type                     |     8      |
       +----------+-------+---------------------------+------------+

                 Table 1: Summary of Operator Precedences

4.  Making Use of CDDL

   In this section, we discuss several potential ways to employ CDDL.

4.1.  As a Guide for a Human User

   CDDL can be used to efficiently define the layout of CBOR data, such
   that a human implementer can easily see how data is supposed to be
   encoded.

   Since CDDL maps parts of the CBOR data to human-readable names, tools
   could be built that use CDDL to provide a human-friendly
   representation of the CBOR data and allow them to edit such data
   while remaining compliant with its CDDL definition.

4.2.  For Automated Checking of CBOR Data Structures

   CDDL has been specified such that a machine can handle the CDDL
   definition and related CBOR data (and, thus, also JSON data).  For
   example, a machine could use CDDL to check whether or not CBOR data
   is compliant with its definition.






Birkholz, et al.             Standards Track                   [Page 36]
^L
RFC 8610                          CDDL                         June 2019


   The need for thoroughness of such compliance checking depends on the
   application.  For example, an application may decide not to check the
   data structure at all and use the CDDL definition solely as a means
   to indicate the structure of the data to the programmer.

   On the other hand, the application may also implement a checking
   mechanism that goes as far as checking that all mandatory map members
   are available.

   The matter of how far the data description must be enforced by an
   application is left to the designers and implementers of that
   application, keeping in mind related security considerations.

   In no case is it intended that a CDDL tool would be "writing code"
   for an implementation.

4.3.  For Data Analysis Tools

   In the long run, it can be expected that more and more data will be
   stored using the CBOR data format.

   Where there is data, there is data analysis and the need to process
   such data automatically.  CDDL can be used for such automated data
   processing, allowing tools to verify data, clean it, and extract
   particular parts of interest from it.

   Since CBOR is designed with constrained devices in mind, a likely use
   of it would be small sensors.  An interesting use would thus be
   automated analysis of sensor data.

5.  Security Considerations

   This document presents a content rules language for expressing CBOR
   data structures.  As such, it does not bring any security issues on
   itself, although specifications of protocols that use CBOR naturally
   need security analyses when defined.  General guidelines for writing
   security considerations are defined in [RFC3552] (BCP 72).
   Specifications using CDDL to define CBOR structures in protocols need
   to follow those guidelines.  Additional topics that could be
   considered in a security considerations section for a specification
   that uses CDDL to define CBOR structures include the following:

   o  Where could the language maybe cause confusion in a way that will
      enable security issues?







Birkholz, et al.             Standards Track                   [Page 37]
^L
RFC 8610                          CDDL                         June 2019


   o  Where a CDDL matcher is part of the implementation of a system,
      the security of the system ought not depend on the correctness of
      the CDDL specification or CDDL implementation without any further
      defenses in place.

   o  Where the CDDL specification includes extension points, the impact
      of extensions on the security of the system needs to be carefully
      considered.

   Writers of CDDL specifications are strongly encouraged to value
   clarity and transparency of the specification over its elegance.
   Keep it as simple as possible while still expressing the needed data
   model.

   A related observation about formal description techniques in general
   that is strongly recommended to be kept in mind by writers of CDDL
   specifications: just because CDDL makes it easier to handle
   complexity in a specification, that does not make that complexity
   somehow less bad (except maybe on the level of the humans having to
   grasp the complex structure while reading the spec).

6.  IANA Considerations

6.1.  CDDL Control Operators Registry

   IANA has created a registry for control operators (Section 3.8).  The
   "CDDL Control Operators" registry has been created within the
   "Concise Data Definition Language (CDDL)" registry.

   Each entry in the subregistry must include the name of the control
   operator (by convention given with the leading dot) and a reference
   to its documentation.  Names must be composed of the leading dot
   followed by a text string conforming to the production "id" in
   Appendix B.

















Birkholz, et al.             Standards Track                   [Page 38]
^L
RFC 8610                          CDDL                         June 2019


   Initial entries in this registry are as follows:

                       +----------+---------------+
                       | Name     | Documentation |
                       +----------+---------------+
                       | .size    | RFC 8610      |
                       | .bits    | RFC 8610      |
                       | .regexp  | RFC 8610      |
                       | .cbor    | RFC 8610      |
                       | .cborseq | RFC 8610      |
                       | .within  | RFC 8610      |
                       | .and     | RFC 8610      |
                       | .lt      | RFC 8610      |
                       | .le      | RFC 8610      |
                       | .gt      | RFC 8610      |
                       | .ge      | RFC 8610      |
                       | .eq      | RFC 8610      |
                       | .ne      | RFC 8610      |
                       | .default | RFC 8610      |
                       +----------+---------------+

   All other control operator names are Unassigned.

   The IANA policy for additions to this registry is "Specification
   Required" as defined in [RFC8126] (which involves an Expert Review)
   for names that do not include an internal dot and "IETF Review" for
   names that do include an internal dot.  The expert reviewer is
   specifically instructed that other Standards Development
   Organizations (SDOs) may want to define control operators that are
   specific to their fields (e.g., based on a binary syntax already in
   use at the SDO); the review process should strive to facilitate such
   an undertaking.



















Birkholz, et al.             Standards Track                   [Page 39]
^L
RFC 8610                          CDDL                         June 2019


7.  References

7.1.  Normative References

   [ISO6093]  ISO, "Information processing -- Representation of
              numerical values in character strings for information
              interchange", ISO 6093, 1985.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3552]  Rescorla, E. and B. Korver, "Guidelines for Writing RFC
              Text on Security Considerations", BCP 72, RFC 3552,
              DOI 10.17487/RFC3552, July 2003,
              <https://www.rfc-editor.org/info/rfc3552>.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of
              ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629,
              November 2003, <https://www.rfc-editor.org/info/rfc3629>.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
              <https://www.rfc-editor.org/info/rfc4648>.

   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234,
              DOI 10.17487/RFC5234, January 2008,
              <https://www.rfc-editor.org/info/rfc5234>.

   [RFC7049]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
              October 2013, <https://www.rfc-editor.org/info/rfc7049>.

   [RFC7493]  Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
              DOI 10.17487/RFC7493, March 2015,
              <https://www.rfc-editor.org/info/rfc7493>.

   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
              Writing an IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://www.rfc-editor.org/info/rfc8126>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in
              RFC 2119 Key Words", BCP 14, RFC 8174,
              DOI 10.17487/RFC8174, May 2017,
              <https://www.rfc-editor.org/info/rfc8174>.



Birkholz, et al.             Standards Track                   [Page 40]
^L
RFC 8610                          CDDL                         June 2019


   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

   [W3C.REC-xmlschema-2-20041028]
              Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
              Second Edition", World Wide Web Consortium Recommendation
              REC-xmlschema-2-20041028, October 2004,
              <https://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.

7.2.  Informative References

   [CDDL-Freezer]
              Bormann, C., "A feature freezer for the Concise Data
              Definition Language (CDDL)", Work in Progress,
              draft-bormann-cbor-cddl-freezer-01, August 2018.

   [GRASP]    Bormann, C., Carpenter, B., Ed., and B. Liu, Ed., "A
              Generic Autonomic Signaling Protocol (GRASP)", Work in
              Progress, draft-ietf-anima-grasp-15, July 2017.

   [IEEE754]  IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE
              Std 754-2008.

   [JCR]      Newton, A. and P. Cordell, "A Language for Rules
              Describing JSON Content", Work in Progress,
              draft-newton-json-content-rules-09, September 2017.

   [PEG]      Ford, B., "Parsing expression grammars: a recognition-
              based syntactic foundation", Proceedings of the 31st ACM
              SIGPLAN-SIGACT symposium on Principles of programming
              languages - POPL '04, DOI 10.1145/964001.964011,
              January 2004.

   [RELAXNG]  ISO/IEC, "Information technology -- Document Schema
              Definition Language (DSDL) -- Part 2: Regular-grammar-
              based validation -- RELAX NG", ISO/IEC 19757-2,
              December 2008.

   [RFC7071]  Borenstein, N. and M. Kucherawy, "A Media Type for
              Reputation Interchange", RFC 7071, DOI 10.17487/RFC7071,
              November 2013, <https://www.rfc-editor.org/info/rfc7071>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.




Birkholz, et al.             Standards Track                   [Page 41]
^L
RFC 8610                          CDDL                         June 2019


   [RFC8007]  Murray, R. and B. Niven-Jenkins, "Content Delivery Network
              Interconnection (CDNI) Control Interface / Triggers",
              RFC 8007, DOI 10.17487/RFC8007, December 2016,
              <https://www.rfc-editor.org/info/rfc8007>.

   [RFC8152]  Schaad, J., "CBOR Object Signing and Encryption (COSE)",
              RFC 8152, DOI 10.17487/RFC8152, July 2017,
              <https://www.rfc-editor.org/info/rfc8152>.

   [RFC8428]  Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
              Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
              DOI 10.17487/RFC8428, August 2018,
              <https://www.rfc-editor.org/info/rfc8428>.

   [YAML]     Ben-Kiki, O., Evans, C., and I. Net, "YAML Ain't Markup
              Language (YAML[TM]) Version 1.2", 3rd Edition,
              October 2009, <https://yaml.org/spec/1.2/spec.html>.


































Birkholz, et al.             Standards Track                   [Page 42]
^L
RFC 8610                          CDDL                         June 2019


Appendix A.  Parsing Expression Grammars (PEGs)

   This appendix is normative.

   Since the 1950s, many grammar notations are based on Backus-Naur Form
   (BNF), a notation for context-free grammars (CFGs) within Chomsky's
   generative system of grammars.  The Augmented Backus-Naur Form (ABNF)
   [RFC5234], widely used in IETF specifications and also inspiring the
   syntax of CDDL, is an example of this.

   Generative grammars can express ambiguity well, but this very
   property may make them hard to use in recognition systems, spawning a
   number of subdialects that pose constraints on generative grammars to
   be used with parser generators; this scenario may be hard for the
   specification writer to manage.

   PEGs [PEG] provide an alternative formal foundation for describing
   grammars that emphasizes recognition over generation and resolves
   what would have been ambiguity in generative systems by introducing
   the concept of "prioritized choice".

   The notation for PEGs is quite close to BNF, with the usual "Extended
   BNF" features, such as repetition, added.  However, where BNF uses
   the unordered (symmetrical) choice operator "|" (incidentally notated
   as "/" in ABNF), PEG provides a prioritized choice operator "/".  The
   two alternatives listed are to be tested in left-to-right order,
   locking in the first successful match and disregarding any further
   potential matches within the choice (but not disabling alternatives
   in choices containing this choice, as a cut (Section 3.5.4) would).

   For example, the ABNF expressions

      A = "a" "b" / "a"    (1)

   and

      A = "a" / "a" "b"    (2)

   are equivalent in ABNF's original generative framework but are very
   different in PEG: in (2), the second alternative will never match, as
   any input string starting with an "a" will already succeed in the
   first alternative, locking in the match.

   Similarly, the occurrence indicators ("?", "*", "+") are "greedy" in
   PEG, i.e., they consume as much input as they match (and, as a
   consequence, "a* a" in PEG notation or "*a a" in CDDL syntax never
   can match anything, as all input matching "a" is already consumed by
   the initial "a*", leaving nothing to match the second "a").



Birkholz, et al.             Standards Track                   [Page 43]
^L
RFC 8610                          CDDL                         June 2019


   Incidentally, the grammar of CDDL itself, as written in ABNF in
   Appendix B, can be interpreted both (1) in the generative framework
   on which RFC 5234 is based and (2) as a PEG.  This was made possible
   by ordering the choices in the grammar such that a successful match
   made on the left-hand side of a "/" operator is always the intended
   match, instead of relying on the power of symmetrical choices (for
   example, note the sequence of alternatives in the rule for "uint",
   where the lone zero is behind the longer match alternatives that
   start with a zero).

   The syntax used for expressing the PEG component of CDDL is based on
   ABNF, interpreted in the obvious way with PEG semantics.  The ABNF
   convention of notating occurrence indicators before the controlled
   primary, and of allowing numeric values for minimum and maximum
   occurrence around a "*" sign, is copied.  While PEG is only about
   characters, CDDL has a richer set of elements, such as types and
   groups.  Specifically, the following constructs map:

       +-------+-------+-------------------------------------------+
       | CDDL  | PEG   | Remark                                    |
       +-------+-------+-------------------------------------------+
       | "="   | "<-"  | /= and //= are abbreviations              |
       | "//"  | "/"   | prioritized choice                        |
       | "/"   | "/"   | prioritized choice, limited to types only |
       | "?" P | P "?" | zero or one                               |
       | "*" P | P "*" | zero or more                              |
       | "+" P | P "+" | one or more                               |
       | A B   | A B   | sequence                                  |
       | A, B  | A B   | sequence, comma is decoration only        |
       +-------+-------+-------------------------------------------+

   The literal notation and the use of square brackets, curly braces,
   tildes, ampersands, and hash marks are specific to CDDL and unrelated
   to the conventional PEG notation.  The DOT (".") from PEG is replaced
   by the unadorned "#" or its alias "any".  Also, CDDL does not provide
   the syntactic predicate operators NOT ("!") or AND ("&") from PEG,
   reducing expressiveness as well as complexity.

   For more details about PEG's theoretical foundation and interesting
   properties of the operators such as associativity and distributivity,
   the reader is referred to [PEG].










Birkholz, et al.             Standards Track                   [Page 44]
^L
RFC 8610                          CDDL                         June 2019


Appendix B.  ABNF Grammar

   This appendix is normative.

   The following is a formal definition of the CDDL syntax in ABNF
   [RFC5234].  Note that, as is defined in ABNF, the quote-delimited
   strings below are case insensitive (while string values and names are
   case sensitive in CDDL).

     cddl = S 1*(rule S)
     rule = typename [genericparm] S assignt S type
          / groupname [genericparm] S assigng S grpent

     typename = id
     groupname = id

     assignt = "=" / "/="
     assigng = "=" / "//="

     genericparm = "<" S id S *("," S id S ) ">"
     genericarg = "<" S type1 S *("," S type1 S ) ">"

     type = type1 *(S "/" S type1)

     type1 = type2 [S (rangeop / ctlop) S type2]
     ; space may be needed before the operator if type2 ends in a name

     type2 = value
           / typename [genericarg]
           / "(" S type S ")"
           / "{" S group S "}"
           / "[" S group S "]"
           / "~" S typename [genericarg]
           / "&" S "(" S group S ")"
           / "&" S groupname [genericarg]
           / "#" "6" ["." uint] "(" S type S ")"
           / "#" DIGIT ["." uint]                ; major/ai
           / "#"                                 ; any

     rangeop = "..." / ".."

     ctlop = "." id

     group = grpchoice *(S "//" S grpchoice)

     grpchoice = *(grpent optcom)





Birkholz, et al.             Standards Track                   [Page 45]
^L
RFC 8610                          CDDL                         June 2019


     grpent = [occur S] [memberkey S] type
            / [occur S] groupname [genericarg]  ; preempted by above
            / [occur S] "(" S group S ")"

     memberkey = type1 S ["^" S] "=>"
               / bareword S ":"
               / value S ":"

     bareword = id

     optcom = S ["," S]

     occur = [uint] "*" [uint]
           / "+"
           / "?"

     uint = DIGIT1 *DIGIT
          / "0x" 1*HEXDIG
          / "0b" 1*BINDIG
          / "0"

     value = number
           / text
           / bytes

     int = ["-"] uint

     ; This is a float if it has fraction or exponent; int otherwise
     number = hexfloat / (int ["." fraction] ["e" exponent ])
     hexfloat = ["-"] "0x" 1*HEXDIG ["." 1*HEXDIG] "p" exponent
     fraction = 1*DIGIT
     exponent = ["+"/"-"] 1*DIGIT

     text = %x22 *SCHAR %x22
     SCHAR = %x20-21 / %x23-5B / %x5D-7E / %x80-10FFFD / SESC
     SESC = "\" (%x20-7E / %x80-10FFFD)

     bytes = [bsqual] %x27 *BCHAR %x27
     BCHAR = %x20-26 / %x28-5B / %x5D-10FFFD / SESC / CRLF
     bsqual = "h" / "b64"











Birkholz, et al.             Standards Track                   [Page 46]
^L
RFC 8610                          CDDL                         June 2019


     id = EALPHA *(*("-" / ".") (EALPHA / DIGIT))
     ALPHA = %x41-5A / %x61-7A
     EALPHA = ALPHA / "@" / "_" / "$"
     DIGIT = %x30-39
     DIGIT1 = %x31-39
     HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
     BINDIG = %x30-31

     S = *WS
     WS = SP / NL
     SP = %x20
     NL = COMMENT / CRLF
     COMMENT = ";" *PCHAR CRLF
     PCHAR = %x20-7E / %x80-10FFFD
     CRLF = %x0A / %x0D.0A

                           Figure 13: CDDL ABNF

   Note that this ABNF does not attempt to reflect the detailed rules of
   what can be in a prefixed byte string.

Appendix C.  Matching Rules

   This appendix is normative.

   In this appendix, we go through the ABNF syntax rules defined in
   Appendix B and briefly describe the matching semantics of each
   syntactic feature.  In this context, an instance (data item)
   "matches" a CDDL specification if it is allowed by the CDDL
   specification; this is then broken down into parts of specifications
   (type and group expressions) and parts of instances (data items).

   cddl = S 1*(rule S)

   A CDDL specification is a sequence of one or more rules.  Each rule
   gives a name to a right-hand-side expression, either a CDDL type or a
   CDDL group.  Rule names can be used in the rule itself and/or other
   rules (and tools can output warnings if that is not the case).  The
   order of the rules is significant only in two cases:

   1.  The first rule defines the semantics of the entire specification;
       hence, there is no need to give that root rule a special name or
       special syntax in the language (as, for example, with "start" in
       RELAX NG); its name can therefore be chosen to be descriptive.
       (As with all other rule names, the name of the initial rule may
       be used in itself or in other rules.)





Birkholz, et al.             Standards Track                   [Page 47]
^L
RFC 8610                          CDDL                         June 2019


   2.  Where a rule contributes to a type or group choice (using "/=" or
       "//="), that choice is populated in the order the rules are
       given; see below.

   rule = typename [genericparm] S assignt S type
        / groupname [genericparm] S assigng S grpent

   typename = id
   groupname = id

   A rule defines a name for a type expression (production "type") or
   for a group expression (production "grpent"), with the intention that
   the semantics does not change when the name is replaced by its
   (parenthesized if needed) definition.  Note that whether the name
   defined by a rule stands for a type or a group isn't always
   determined by syntax alone: e.g., "a = b" can make "a" a type if "b"
   is a type, or a group if "b" is a group.  More subtly, in "a = (b)",
   "a" may be used as a type if "b" is a type, or as a group both when
   "b" is a group and when "b" is a type (a good convention to make the
   latter case stand out to the human reader is to write "a = (b,)").
   (Note that the same dual meaning of parentheses applies within an
   expression but often can be resolved by the context of the
   parenthesized expression.  On the more general point, it may not be
   clear immediately either whether "b" stands for a group or a type --
   this semantic processing may need to span several levels of rule
   definitions before a determination can be made.)

   assignt = "=" / "/="
   assigng = "=" / "//="

   A plain equals sign defines the rule name as the equivalent of the
   expression to the right; it is an error if the name was already
   defined with a different expression.  A "/=" or "//=" extends a named
   type or a group by additional choices; a number of these could be
   replaced by collecting all the right-hand sides and creating a single
   rule with a type choice or a group choice built from the right-hand
   sides in the order of the rules given.  (It is not an error to extend
   a rule name that has not yet been defined; this makes the right-hand
   side the first entry in the choice being created.)

   genericparm = "<" S id S *("," S id S ) ">"
   genericarg = "<" S type1 S *("," S type1 S ) ">"

   Rule names can have generic parameters, which cause temporary
   assignments within the right-hand sides to the parameter names from
   the arguments given when citing the rule name.

   type = type1 *(S "/" S type1)



Birkholz, et al.             Standards Track                   [Page 48]
^L
RFC 8610                          CDDL                         June 2019


   A type can be given as a choice between one or more types.  The
   choice matches a data item if the data item matches any one of the
   types given in the choice.  The choice uses PEG semantics as
   discussed in Appendix A: the first choice that matches wins.  (As a
   result, the order of rules that contribute to a single rule name can
   very well matter.)

   type1 = type2 [S (rangeop / ctlop) S type2]

   Two types can be combined with a range operator (see below) or a
   control operator (see Section 3.8).

   type2 = value

   A type can be just a single value (such as 1 or "icecream" or
   h'0815'), which matches only a data item with that specific value (no
   conversions defined),

      / typename [genericarg]

   or be defined by a rule giving a meaning to a name (possibly after
   supplying generic arguments as required by the generic parameters),

      / "(" S type S ")"

   or be defined in a parenthesized type expression (parentheses may be
   necessary to override some operator precedence), or

      / "{" S group S "}"

   a map expression, which matches a valid CBOR map the key/value pairs
   of which can be ordered in such a way that the resulting sequence
   matches the group expression, or

      / "[" S group S "]"

   an array expression, which matches a CBOR array the elements of which
   -- when taken as values and complemented by a wildcard (matches
   anything) key each -- match the group, or

      / "~" S typename [genericarg]

   an "unwrapped" group (see Section 3.7), which matches the group
   inside a type defined as a map or an array by wrapping the group, or

      / "&" S "(" S group S ")"
      / "&" S groupname [genericarg]




Birkholz, et al.             Standards Track                   [Page 49]
^L
RFC 8610                          CDDL                         June 2019


   an enumeration expression, which matches any value that is within the
   set of values that the values of the group given can take, or

      / "#" "6" ["." uint] "(" S type S ")"

   a tagged data item, tagged with the "uint" given and containing the
   type given as the tagged value, or

      / "#" DIGIT ["." uint]                ; major/ai

   a data item of a major type (given by the DIGIT), optionally
   constrained to the additional information given by the uint, or

      / "#"                                 ; any

   any data item.

   rangeop = "..." / ".."

   A range operator can be used to join two type expressions that stand
   for either two integer values or two floating-point values; it
   matches any value that is between the two values, where the first
   value is always included in the matching set and the second value is
   included for ".." and excluded for "...".

   ctlop = "." id

   A control operator ties a _target_ type to a _controller_ type as
   defined in Section 3.8.  Note that control operators are an extension
   point for CDDL; additional documents may want to define additional
   control operators.

   group = grpchoice *(S "//" S grpchoice)

   A group matches any sequence of key/value pairs that matches any of
   the choices given (again using PEG semantics).

   grpchoice = *(grpent optcom)

   Each of the component groups is given as a sequence of group entries.
   For a match, the sequence of key/value pairs given needs to match the
   sequence of group entries in the sequence given.

   grpent = [occur S] [memberkey S] type

   A group entry can be given by a value type, which needs to be matched
   by the value part of a single element; and, optionally, a memberkey
   type, which needs to be matched by the key part of the element, if



Birkholz, et al.             Standards Track                   [Page 50]
^L
RFC 8610                          CDDL                         June 2019


   the memberkey is given.  If the memberkey is not given, the entry can
   only be used for matching arrays, not for maps.  (See below for how
   that is modified by the occurrence indicator.)

       / [occur S] groupname [genericarg]  ; preempted by above

   A group entry can be built from a named group, or

       / [occur S] "(" S group S ")"

   from a parenthesized group, again with a possible occurrence
   indicator.

   memberkey = type1 S ["^" S] "=>"
             / bareword S ":"
             / value S ":"

   Key types can be given by a type expression, a bareword (which stands
   for a type that just contains a string value created from this
   bareword), or a value (which stands for a type that just contains
   this value).  A key value matches its key type if the key value is a
   member of the key type, unless a cut preceding it in the group
   applies (see Section 3.5.4 for how map matching is influenced by the
   presence of the cuts denoted by "^" or ":" in previous entries).

   bareword = id

   A bareword is an alternative way to write a type with a single text
   string value; it can only be used in the syntactic context given
   above.

   optcom = S ["," S]

   (Optional commas do not influence the matching.)

   occur = [uint] "*" [uint]
         / "+"
         / "?"

   An occurrence indicator modifies the group given to its right by
   requiring the group to match the sequence to be matched exactly for a
   certain number of times (see Section 3.2) in sequence, i.e., it acts
   as a (possibly infinite) group choice that contains choices with the
   group repeated each of the occurrences times.







Birkholz, et al.             Standards Track                   [Page 51]
^L
RFC 8610                          CDDL                         June 2019


   The rest of the ABNF describes syntax for value notation that should
   be familiar to readers from programming languages, with the possible
   exception of h'..' and b64'..' for byte strings, as well as syntactic
   elements such as comments and line ends.

Appendix D.  Standard Prelude

   This appendix is normative.

   The following prelude is automatically added to each CDDL file.
   (Note that technically, it is a postlude, as it does not disturb the
   selection of the first rule as the root of the definition.)

                  any = #

                  uint = #0
                  nint = #1
                  int = uint / nint

                  bstr = #2
                  bytes = bstr
                  tstr = #3
                  text = tstr

                  tdate = #6.0(tstr)
                  time = #6.1(number)
                  number = int / float
                  biguint = #6.2(bstr)
                  bignint = #6.3(bstr)
                  bigint = biguint / bignint
                  integer = int / bigint
                  unsigned = uint / biguint
                  decfrac = #6.4([e10: int, m: integer])
                  bigfloat = #6.5([e2: int, m: integer])
                  eb64url = #6.21(any)
                  eb64legacy = #6.22(any)
                  eb16 = #6.23(any)
                  encoded-cbor = #6.24(bstr)
                  uri = #6.32(tstr)
                  b64url = #6.33(tstr)
                  b64legacy = #6.34(tstr)
                  regexp = #6.35(tstr)
                  mime-message = #6.36(tstr)
                  cbor-any = #6.55799(any)







Birkholz, et al.             Standards Track                   [Page 52]
^L
RFC 8610                          CDDL                         June 2019


                  float16 = #7.25
                  float32 = #7.26
                  float64 = #7.27
                  float16-32 = float16 / float32
                  float32-64 = float32 / float64
                  float = float16-32 / float64

                  false = #7.20
                  true = #7.21
                  bool = false / true
                  nil = #7.22
                  null = nil
                  undefined = #7.23

                          Figure 14: CDDL Prelude

   Note that the prelude is deemed to be fixed.  This means, for
   instance, that additional tags beyond those defined in [RFC7049], as
   registered, need to be defined in each CDDL file that is using them.

   A common stumbling point is that the prelude does not define a type
   "string".  CBOR has byte strings ("bytes" in the prelude) and text
   strings ("text"), so a type that is simply called "string" would be
   ambiguous.

Appendix E.  Use with JSON

   This appendix is normative.

   The JSON generic data model (implicit in [RFC8259]) is a subset of
   the generic data model of CBOR.  So, one can use CDDL with JSON by
   limiting oneself to what can be represented in JSON.  Roughly
   speaking, this means leaving out byte strings, tags, and simple
   values other than "false", "true", and "null", leading to the
   following limited prelude:
















Birkholz, et al.             Standards Track                   [Page 53]
^L
RFC 8610                          CDDL                         June 2019


                      any = #

                      uint = #0
                      nint = #1
                      int = uint / nint

                      tstr = #3
                      text = tstr

                      number = int / float

                      float16 = #7.25
                      float32 = #7.26
                      float64 = #7.27
                      float16-32 = float16 / float32
                      float32-64 = float32 / float64
                      float = float16-32 / float64

                      false = #7.20
                      true = #7.21
                      bool = false / true
                      nil = #7.22
                      null = nil

             Figure 15: JSON-Compatible Subset of CDDL Prelude

   (The major types given here do not have a direct meaning in JSON, but
   they can be interpreted as CBOR major types translated through
   Section 4 of [RFC7049].)

   There are a few fine points in using CDDL with JSON.  First, JSON
   does not distinguish between integers and floating-point numbers;
   there is only one kind of number (which may happen to be integral).
   In this context, specifying a type as "uint", "nint", or "int" then
   becomes a predicate that the number be integral.  As an example, this
   means that the following JSON numbers are all matching "uint":

      10 10.0 1e1 1.0e1 100e-1

   (The fact that these are all integers may be surprising to users
   accustomed to the long tradition in programming languages of using
   decimal points or exponents in a number to indicate a floating-point
   literal.)

   CDDL distinguishes the various CBOR number types, but there is only
   one number type in JSON.  The effect of specifying a floating-point
   precision (float16/float32/float64) is only to restrict the set of




Birkholz, et al.             Standards Track                   [Page 54]
^L
RFC 8610                          CDDL                         June 2019


   permissible values to those expressible with binary16/binary32/
   binary64; this is unlikely to be very useful when using CDDL for
   specifying JSON data structures.

   Fundamentally, the number system of JSON itself is based on decimal
   numbers and decimal fractions and does not have limits to its
   precision or range.  In practice, JSON numbers are often parsed into
   a number type that is called "float64" here, creating a number of
   limitations to the generic data model [RFC7493].  In particular, this
   means that integers can only be expressed with interoperable
   exactness when they lie in the range [-(2**53)+1, (2**53)-1] -- a
   smaller range than that covered by CDDL "int".

   JSON applications that want to stay compatible with I-JSON ("Internet
   JSON"; see [RFC7493]) may therefore want to define integer types with
   more limited ranges, such as in Figure 16.  Note that the types given
   here are not part of the prelude; they need to be copied into the
   CDDL specification if needed.

               ij-uint = 0..9007199254740991
               ij-nint = -9007199254740991..-1
               ij-int = -9007199254740991..9007199254740991

          Figure 16: I-JSON Types for CDDL (Not Part of Prelude)

   JSON applications that do not need to stay compatible with I-JSON and
   that actually may need to go beyond the 64-bit unsigned and negative
   integers supported by "int" (= "uint"/"nint") may want to use the
   following additional types from the standard prelude, which are
   expressed in terms of tags but can straightforwardly be mapped into
   JSON (but not I-JSON) numbers:

      biguint = #6.2(bstr)
      bignint = #6.3(bstr)
      bigint = biguint / bignint
      integer = int / bigint
      unsigned = uint / biguint

   CDDL at this point does not have a way to express the unlimited
   floating-point precision that is theoretically possible with JSON; at
   the time of writing, this is rarely used in protocols in practice.

   Note that a data model described in CDDL is always restricted by what
   can be expressed in the serialization; e.g., floating-point values
   such as NaN (not a number) and the infinities cannot be represented
   in JSON even if they are allowed in the CDDL generic data model.





Birkholz, et al.             Standards Track                   [Page 55]
^L
RFC 8610                          CDDL                         June 2019


Appendix F.  A CDDL Tool

   This appendix is for information only.

   A rough CDDL tool is available.  For CDDL specifications, it can
   check the syntax, generate one or more instances (expressed in CBOR
   diagnostic notation or in pretty-printed JSON), and validate an
   existing instance against the specification:

                   Usage:
                   cddl spec.cddl generate [n]
                   cddl spec.cddl json-generate [n]
                   cddl spec.cddl validate instance.cbor
                   cddl spec.cddl validate instance.json

                        Figure 17: CDDL Tool Usage

   Install on a system with a modern Ruby via:

                             gem install cddl

                     Figure 18: CDDL Tool Installation

   The accompanying CBOR diagnostic tools (which are automatically
   installed by the above) are described in <https://github.com/cabo/
   cbor-diag>; they can be used to convert between binary CBOR, a
   pretty-printed hexadecimal form of binary CBOR, CBOR diagnostic
   notation, JSON, and YAML [YAML].

Appendix G.  Extended Diagnostic Notation

   This appendix is normative.

   Section 6 of [RFC7049] defines a "diagnostic notation" in order to be
   able to converse about CBOR data items without having to resort to
   binary data.  Diagnostic notation is based on JSON, with extensions
   for representing CBOR constructs such as binary data and tags.

   (Standardizing this together with the actual interchange format does
   not serve to create another interchange format but enables the use of
   a shared diagnostic notation in tools for and documents about CBOR.)

   This appendix discusses a few extensions to the diagnostic notation
   that have turned out to be useful since RFC 7049 was written.  We
   refer to the result as Extended Diagnostic Notation (EDN).






Birkholz, et al.             Standards Track                   [Page 56]
^L
RFC 8610                          CDDL                         June 2019


G.1.  Whitespace in Byte String Notation

   Examples often benefit from some whitespace (spaces, line breaks) in
   byte strings.  In EDN, whitespace is ignored in prefixed byte
   strings; for instance, the following are equivalent:

      h'48656c6c6f20776f726c64'
      h'48 65 6c 6c 6f 20 77 6f 72 6c 64'
      h'4 86 56c 6c6f
        20776 f726c64'

G.2.  Text in Byte String Notation

   Diagnostic notation notates byte strings in one of the base encodings
   per [RFC4648], enclosed in single quotes, prefixed by >h< for base16,
   >b32< for base32, >h32< for base32hex, or >b64< for base64 or
   base64url.  Quite often, byte strings carry bytes that are
   meaningfully interpreted as UTF-8 text.  EDN allows the use of single
   quotes without a prefix to express byte strings with UTF-8 text; for
   instance, the following are equivalent:

      'hello world'
      h'68656c6c6f20776f726c64'

   The escaping rules of JSON strings are applied equivalently for
   text-based byte strings, e.g., "\" stands for a single backslash and
   "'" stands for a single quote.  Whitespace is included literally,
   i.e., the previous section does not apply to text-based byte strings.

G.3.  Embedded CBOR and CBOR Sequences in Byte Strings

   Where a byte string is to carry an embedded CBOR-encoded item, or
   more generally a sequence of zero or more such items, the diagnostic
   notation for these zero or more CBOR data items, separated by commas,
   can be enclosed in << and >> to notate the byte string resulting from
   encoding the data items and concatenating the result.  For instance,
   each pair of columns in the following are equivalent:

      <<1>>              h'01'
      <<1, 2>>           h'0102'
      <<"foo", null>>    h'63666F6FF6'
      <<>>               h''









Birkholz, et al.             Standards Track                   [Page 57]
^L
RFC 8610                          CDDL                         June 2019


G.4.  Concatenated Strings

   While the ability to include whitespace enables line-breaking of
   encoded byte strings, a mechanism is needed to be able to include
   text strings as well as byte strings in direct UTF-8 representation
   into line-based documents (such as RFCs and source code).

   We extend the diagnostic notation by allowing multiple text strings
   or multiple byte strings to be notated separated by whitespace; these
   are then concatenated into a single text or byte string,
   respectively.  Text strings and byte strings do not mix within such a
   concatenation, except that byte string notation can be used inside a
   sequence of concatenated text string notation to encode characters
   that may be better represented in an encoded way.  The following four
   values are equivalent:

      "Hello world"
      "Hello " "world"
      "Hello" h'20' "world"
      "" h'48656c6c6f20776f726c64' ""

   Similarly, the following byte string values are equivalent:

      'Hello world'
      'Hello ' 'world'
      'Hello ' h'776f726c64'
      'Hello' h'20' 'world'
      '' h'48656c6c6f20776f726c64' '' b64''
      h'4 86 56c 6c6f' h' 20776 f726c64'

   (Note that the approach of separating by whitespace, while familiar
   from the C language, requires some attention -- a single comma makes
   a big difference here.)


















Birkholz, et al.             Standards Track                   [Page 58]
^L
RFC 8610                          CDDL                         June 2019


G.5.  Hexadecimal, Octal, and Binary Numbers

   In addition to JSON's decimal numbers, EDN provides hexadecimal,
   octal, and binary numbers in the usual C-language notation (octal
   with 0o prefix present only).

   The following are equivalent:

      4711
      0x1267
      0o11147
      0b1001001100111

   As are:

      1.5
      0x1.8p0
      0x18p-4

G.6.  Comments

   Longer pieces of diagnostic notation may benefit from comments.  JSON
   famously does not provide for comments, and basic diagnostic notation
   per RFC 7049 inherits this property.

   In EDN, comments can be included, delimited by slashes ("/").  Any
   text within and including a pair of slashes is considered a comment.

   Comments are considered whitespace.  Hence, they are allowed in
   prefixed byte strings; for instance, the following are equivalent:

      h'68656c6c6f20776f726c64'
      h'68 65 6c /doubled l!/ 6c 6f /hello/
        20 /space/
        77 6f 72 6c 64' /world/

   This can be used to annotate a CBOR structure as in:

      /grasp-message/ [/M_DISCOVERY/ 1, /session-id/ 10584416,
                       /objective/ [/objective-name/ "opsonize",
                                    /D, N, S/ 7, /loop-count/ 105]]

   (There are currently no end-of-line comments.  If we want to add
   them, "//" sounds like a reasonable delimiter given that we already
   use slashes for comments, but we could also go, for example,
   for "#".)





Birkholz, et al.             Standards Track                   [Page 59]
^L
RFC 8610                          CDDL                         June 2019


Appendix H.  Examples

   This appendix is for information only.

   This appendix contains a few examples of structures defined
   using CDDL.  The theme for the examples is taken from [RFC7071],
   which defines certain JSON structures in English.  For a similar
   example, it may also be of interest to examine Appendix A of
   [RFC8007], which contains a CDDL definition for a JSON structure
   defined in the main body of that RFC.

   These examples all happen to describe data that is interchanged in
   JSON.  Examples for CDDL definitions of data that is interchanged in
   CBOR can be found in [RFC8152], [GRASP], and [RFC8428].

   [RFC7071] defines the "reputon" structure for JSON using somewhat
   formalized English text.  Here is a (somewhat verbose) equivalent
   definition using the same terms, but notated in CDDL:

                 reputation-object = {
                   reputation-context,
                   reputon-list
                 }

                 reputation-context = (
                   application: text
                 )

                 reputon-list = (
                   reputons: reputon-array
                 )

                 reputon-array = [* reputon]

                 reputon = {
                   rater-value,
                   assertion-value,
                   rated-value,
                   rating-value,
                   ? conf-value,
                   ? normal-value,
                   ? sample-value,
                   ? gen-value,
                   ? expire-value,
                   * ext-value,
                 }





Birkholz, et al.             Standards Track                   [Page 60]
^L
RFC 8610                          CDDL                         June 2019


                 rater-value = ( rater: text )
                 assertion-value = ( assertion: text )
                 rated-value = ( rated: text )
                 rating-value = ( rating: float16 )
                 conf-value = ( confidence: float16 )
                 normal-value = ( normal-rating: float16 )
                 sample-value = ( sample-size: uint )
                 gen-value = ( generated: uint )
                 expire-value = ( expires: uint )
                 ext-value = ( text => any )

   An equivalent, more compact form of this example would be:

                        reputation-object = {
                          application: text
                          reputons: [* reputon]
                        }

                        reputon = {
                          rater: text
                          assertion: text
                          rated: text
                          rating: float16
                          ? confidence: float16
                          ? normal-rating: float16
                          ? sample-size: uint
                          ? generated: uint
                          ? expires: uint
                          * text => any
                        }

   Note how this rather clearly delineates the structure somewhat
   shrouded by so many words in Section 6.2.2 of [RFC7071].  Also, this
   definition makes it clear that several ext-values are allowed (by
   definition with different member names); RFC 7071 could be read to
   forbid the repetition of ext-value ("A specific reputon-element
   MUST NOT appear more than once" is ambiguous).














Birkholz, et al.             Standards Track                   [Page 61]
^L
RFC 8610                          CDDL                         June 2019


   The CDDL tool described in Appendix F generates as one example:

                  {
                    "application": "conchometry",
                    "reputons": [
                      {
                        "rater": "Ephthianura",
                        "assertion": "codding",
                        "rated": "sphaerolitic",
                        "rating": 0.34133473256800795,
                        "confidence": 0.9481983064298332,
                        "expires": 1568,
                        "unplaster": "grassy"
                      },
                      {
                        "rater": "nonchargeable",
                        "assertion": "raglan",
                        "rated": "alienage",
                        "rating": 0.5724646875815566,
                        "sample-size": 3514,
                        "Aldebaran": "unchurched",
                        "puruloid": "impersonable",
                        "uninfracted": "pericarpoidal",
                        "schorl": "Caro"
                      },
                      {
                        "rater": "precollectable",
                        "assertion": "Merat",
                        "rated": "thermonatrite",
                        "rating": 0.19164006323936977,
                        "confidence": 0.6065252103391268,
                        "normal-rating": 0.5187773690879303,
                        "generated": 899,
                        "speedy": "solidungular",
                        "noviceship": "medicine",
                        "checkrow": "epidictic"
                      }
                    ]
                  }












Birkholz, et al.             Standards Track                   [Page 62]
^L
RFC 8610                          CDDL                         June 2019


Acknowledgements

   Inspiration was taken from the C and Pascal languages, MPEG's
   conventions for describing structures in the ISO base media file
   format, RELAX NG and its compact syntax [RELAXNG], and, in
   particular, Andrew Lee Newton's early proposals on JSON Content Rules
   (JCR) as found in draft version four (-04) of [JCR].

   Lots of highly useful feedback came from members of the IETF CBOR WG
   -- in particular, Ari Keranen, Brian Carpenter, Burt Harris, Jeffrey
   Yasskin, Jim Hague, Jim Schaad, Joe Hildebrand, Max Pritikin, Michael
   Richardson, Pete Cordell, Sean Leonard, and Yaron Sheffer.  Also,
   Francesca Palombini and Joe volunteered to chair the WG when it was
   created, providing the framework for generating and processing this
   feedback, with Barry Leiba having taken over from Joe since then.
   Chris Lonvick and Ines Robles provided additional reviews during IESG
   processing, and Alexey Melnikov steered the process as the
   responsible Area Director.

   The CDDL tool described in Appendix F was written by Carsten Bormann,
   building on previous work by Troy Heninger and Tom Lord.

Contributors

   CDDL was originally conceived by Bert Greevenbosch, who also wrote
   the original five draft versions of this document.

























Birkholz, et al.             Standards Track                   [Page 63]
^L
RFC 8610                          CDDL                         June 2019


Authors' Addresses

   Henk Birkholz
   Fraunhofer SIT
   Rheinstrasse 75
   Darmstadt  64295
   Germany

   Email: henk.birkholz@sit.fraunhofer.de


   Christoph Vigano
   Universitaet Bremen

   Email: christoph.vigano@uni-bremen.de


   Carsten Bormann
   Universitaet Bremen TZI
   Bibliothekstr. 1
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63921
   Email: cabo@tzi.org


























Birkholz, et al.             Standards Track                   [Page 64]
^L