idnits 2.17.1 draft-ietf-cbor-cddl-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 27, 2017) is 2464 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-16) exists of draft-ietf-core-senml-10 == Outdated reference: A later version (-09) exists of draft-newton-json-content-rules-08 -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group H. Birkholz 3 Internet-Draft Fraunhofer SIT 4 Intended status: Standards Track C. Vigano 5 Expires: January 28, 2018 Universitaet Bremen 6 C. Bormann 7 Universitaet Bremen TZI 8 July 27, 2017 10 Concise data definition language (CDDL): a notational convention to 11 express CBOR data structures 12 draft-ietf-cbor-cddl-00 14 Abstract 16 This document proposes a notational convention to express CBOR data 17 structures (RFC 7049). Its main goal is to provide an easy and 18 unambiguous way to express structures for protocol messages and data 19 formats that use CBOR. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 28, 2018. 38 Copyright Notice 40 Copyright (c) 2017 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 4 57 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. The Style of Data Structure Specification . . . . . . . . . . 4 59 2.1. Groups and Composition in CDDL . . . . . . . . . . . . . 6 60 2.1.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 8 61 2.1.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 8 62 2.2. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 2.2.1. Values . . . . . . . . . . . . . . . . . . . . . . . 9 64 2.2.2. Choices . . . . . . . . . . . . . . . . . . . . . . . 9 65 2.2.3. Representation Types . . . . . . . . . . . . . . . . 10 66 2.2.4. Root type . . . . . . . . . . . . . . . . . . . . . . 11 67 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 3.1. General conventions . . . . . . . . . . . . . . . . . . . 11 69 3.2. Occurrence . . . . . . . . . . . . . . . . . . . . . . . 13 70 3.3. Predefined names for types . . . . . . . . . . . . . . . 14 71 3.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 3.5. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 15 73 3.5.1. Structs . . . . . . . . . . . . . . . . . . . . . . . 15 74 3.5.2. Tables . . . . . . . . . . . . . . . . . . . . . . . 18 75 3.6. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 3.7. Unwrapping . . . . . . . . . . . . . . . . . . . . . . . 19 77 3.8. Controls . . . . . . . . . . . . . . . . . . . . . . . . 20 78 3.8.1. Control operator .size . . . . . . . . . . . . . . . 21 79 3.8.2. Control operator .bits . . . . . . . . . . . . . . . 21 80 3.8.3. Control operator .regexp . . . . . . . . . . . . . . 22 81 3.8.4. Control operators .cbor and .cborseq . . . . . . . . 23 82 3.8.5. Control operators .within and .and . . . . . . . . . 23 83 3.8.6. Control operators .lt, .le, .gt, .ge, .eq, .ne, and 84 .default . . . . . . . . . . . . . . . . . . . . . . 24 85 3.9. Socket/Plug . . . . . . . . . . . . . . . . . . . . . . . 24 86 3.10. Generics . . . . . . . . . . . . . . . . . . . . . . . . 26 87 3.11. Operator Precedence . . . . . . . . . . . . . . . . . . . 26 88 4. Making Use of CDDL . . . . . . . . . . . . . . . . . . . . . 28 89 4.1. As a guide to a human user . . . . . . . . . . . . . . . 28 90 4.2. For automated checking of CBOR data structure . . . . . . 28 91 4.3. For data analysis tools . . . . . . . . . . . . . . . . . 29 92 5. Security considerations . . . . . . . . . . . . . . . . . . . 29 93 6. IANA considerations . . . . . . . . . . . . . . . . . . . . . 29 94 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 95 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 96 8.1. Normative References . . . . . . . . . . . . . . . . . . 30 97 8.2. Informative References . . . . . . . . . . . . . . . . . 31 98 Appendix A. Cemetery . . . . . . . . . . . . . . . . . . . . . . 31 99 A.1. Resolved Issues . . . . . . . . . . . . . . . . . . . . . 32 100 Appendix B. (Not used.) . . . . . . . . . . . . . . . . . . . . 32 101 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 32 102 Appendix D. ABNF grammar . . . . . . . . . . . . . . . . . . . . 35 103 Appendix E. Standard Prelude . . . . . . . . . . . . . . . . . . 37 104 E.1. Use with JSON . . . . . . . . . . . . . . . . . . . . . . 39 105 Appendix F. The CDDL tool . . . . . . . . . . . . . . . . . . . 41 106 Appendix G. Extended Diagnostic Notation . . . . . . . . . . . . 41 107 G.1. White space in byte string notation . . . . . . . . . . . 42 108 G.2. Text in byte string notation . . . . . . . . . . . . . . 42 109 G.3. Embedded CBOR and CBOR sequences in byte strings . . . . 42 110 G.4. Concatenated Strings . . . . . . . . . . . . . . . . . . 43 111 G.5. Hexadecimal, octal, and binary numbers . . . . . . . . . 43 112 G.6. Comments . . . . . . . . . . . . . . . . . . . . . . . . 44 113 Appendix H. Examples . . . . . . . . . . . . . . . . . . . . . . 44 114 H.1. RFC 7071 . . . . . . . . . . . . . . . . . . . . . . . . 45 115 H.1.1. Examples from JSON Content Rules . . . . . . . . . . 48 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 118 1. Introduction 120 In this document, a notational convention to express CBOR [RFC7049] 121 data structures is defined. 123 The main goal for the convention is to provide a unified notation 124 that can be used when defining protocols that use CBOR. We term the 125 convention "Concise data definition language", or CDDL. 127 The CBOR notational convention has the following goals: 129 (G1) Provide an unambiguous description of the overall structure of 130 a CBOR data structure. 132 (G2) Flexibility to express the freedoms of choice in the CBOR data 133 format. 135 (G3) Possibility to restrict format choices where appropriate 136 [_format]. 138 (G4) Able to express common CBOR datatypes and structures. 140 (G5) Human and machine readable and processable. 142 (G6) Automatic checking of data format compliance. 144 (G7) Extraction of specific elements from CBOR data for further 145 processing. 147 Not an explicit goal per se, but a convenient side effect of the JSON 148 generic data model being a subset of the CBOR generic data model, is 149 the fact that CDDL can also be used for describing JSON data 150 structures (see Appendix E.1). 152 This document has the following structure: 154 The syntax of CDDL is defined in Section 3. Examples of CDDL and 155 related CBOR data instances are defined in Appendix H. Section 4 156 discusses usage of CDDL. Examples are provided early in the text to 157 better illustrate concept definitions. A formal definition of CDDL 158 using ABNF grammar is provided in Appendix D. Finally, a prelude of 159 standard CDDL definitions available in every CBOR specification is 160 listed in Appendix E. 162 1.1. Requirements notation 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 166 "OPTIONAL" in this document are to be interpreted as described in RFC 167 2119, BCP 14 [RFC2119]. 169 1.2. Terminology 171 New terms are introduced in _cursive_. CDDL text in the running text 172 is in "typewriter". 174 2. The Style of Data Structure Specification 176 CDDL focuses on styles of specification that are in use in the 177 community employing the data model as pioneered by JSON and now 178 refined in CBOR. 180 There are a number of more or less atomic elements of a CBOR data 181 model, such as numbers, simple values (false, true, nil), text and 182 byte strings; CDDL does not focus on specifying their structure. 183 CDDL of course also allows adding a CBOR tag to a data item. 185 The more important components of a data structure definition language 186 are the data types used for composition: arrays and maps in CBOR 187 (called arrays and objects in JSON). While these are only two 188 representation formats, they are used to specify four loosely 189 distinguishable styles of composition: 191 o A _vector_, an array of elements that are mostly of the same 192 semantics. The set of signatures associated with a signed data 193 item is a typical application of a vector. 195 o A _record_, an array the elements of which have different, 196 positionally defined semantics, as detailed in the data structure 197 definition. A 2D point, specified as an array of an x coordinate 198 (which comes first) and a y coordinate (coming second) is an 199 example of a record, as is the pair of exponent (first) and 200 mantissa (second) in a CBOR decimal fraction. 202 o A _table_, a map from a domain of map keys to a domain of map 203 values, that are mostly of the same semantics. A set of language 204 tags, each mapped to a text string translated to that specific 205 language, is an example of a table. The key domain is usually not 206 limited to a specific set by the specification, but open for the 207 application, e.g., in a table mapping IP addresses to MAC 208 addresses, the specification does not attempt to foresee all 209 possible IP addresses. 211 o A _struct_, a map from a domain of map keys as defined by the 212 specification to a domain of map values the semantics of each of 213 which is bound to a specific map key. This is what many people 214 have in mind when they think about JSON objects; CBOR adds the 215 ability to use map keys that are not just text strings. Structs 216 can be used to solve similar problems as records; the use of 217 explicit map keys facilitates optionality and extensibility. 219 Two important concepts provide the foundation for CDDL: 221 1. Instead of defining all four types of composition in CDDL 222 separately, or even defining one kind for arrays (vectors and 223 records) and one kind for maps (tables and structs), there is 224 only one kind of composition in CDDL: the _group_ (Section 2.1). 226 2. The other important concept is that of a _type_. The entire CDDL 227 specification defines a type (the one defined by its first 228 _rule_), which formally is the set of CBOR instances that are 229 acceptable for this specification. CDDL predefines a number of 230 basic types such as "uint" (unsigned integer) or "tstr" (text 231 string), often making use of a simple formal notation for CBOR 232 data items. Each value that can be expressed as a CBOR data item 233 also is a type in its own right, e.g. "1". A type can be built 234 as a _choice_ of other types, e.g., an "int" is either a "uint" 235 or a "nint" (negative integer). Finally, a type can be built as 236 an array or a map from a group. 238 2.1. Groups and Composition in CDDL 240 CDDL Groups are lists of name/value pairs (group _entries_). 242 In an array context, only the value of the entry is represented; the 243 name is annotation only (and can be left off if not needed). In a 244 map context, the names become the map keys ("member keys"). 246 In an array context, the sequence of elements in the group is 247 important, as it is the information that allows associating actual 248 array elements with entries in the group. In a map context, the 249 sequence of entries in a group is not relevant (but there is still a 250 need to write down group entries in a sequence). 252 A group can be placed in (round) parentheses, and given a name by 253 using it in a rule: 255 pii = ( 256 age: int, 257 name: tstr, 258 employer: tstr, 259 ) 261 Figure 1: A basic group 263 Or a group can just be used in the definition of something else: 265 person = {( 266 age: int, 267 name: tstr, 268 employer: tstr, 269 )} 271 Figure 2: Using a group in a map 273 which, given the above rule for pii, is identical to: 275 person = { 276 pii 277 } 279 Figure 3: Using a group by name 281 Note that the (curly) braces signify the creation of a map; the 282 groups themselves are neutral as to whether they will be used in a 283 map or an array. 285 The parentheses for groups are optional when there is some other set 286 of brackets present, so it would be slightly more natural to express 287 Figure 2 as: 289 person = { 290 age: int, 291 name: tstr, 292 employer: tstr, 293 } 295 Groups can be used to factor out common parts of structs, e.g., 296 instead of writing: 298 person = { 299 age: int, 300 name: tstr, 301 employer: tstr, 302 } 304 dog = { 305 age: int, 306 name: tstr, 307 leash-length: float, 308 } 310 one can choose a name for the common subgroup and write: 312 person = { 313 identity, 314 employer: tstr, 315 } 317 dog = { 318 identity, 319 leash-length: float, 320 } 322 identity = ( 323 age: int, 324 name: tstr, 325 ) 327 Figure 4: Using a group for factorization 329 Note that the contents of the braces in the above definitions 330 constitute (anonymous) groups, while "identity" is a named group. 332 2.1.1. Usage 334 Groups are the instrument used in composing data structures with 335 CDDL. It is a matter of style in defining those structures whether 336 to define groups (anonymously) right in their contexts or whether to 337 define them in a separate rule and to reference them with their 338 respective name (possibly more than once). 340 With this, one is allowed to define all small parts of their data 341 structures and compose bigger protocol units with those or to have 342 only one big protocol data unit that has all definitions ad hoc where 343 needed. 345 2.1.2. Syntax 347 The composition syntax intends to be concise and easy to read: 349 o The start of a group can be marked by '(' 351 o The end of a group can be marked by ')' 353 o Definitions of entries inside of a group are noted as follows: 354 _keytype => valuetype,_ (read "keytype maps to valuetype"). The 355 comma is actually optional (not just in the final entry), but it 356 is considered good style to set it. The double arrow can be 357 replaced by a colon in the common case of directly using a text 358 string as a key (see Section 3.5.1). 360 An entry consists of a _keytype_ and a _valuetype_: 362 o _keytype_ is either an atom used as the actual key or a type in 363 general. The latter case may be needed when using groups in a 364 table context, where the actual keys are of lesser importance than 365 the key types, e.g in contexts verifying incoming data. 367 o _valuetype_ is a type, which could be derived from the major types 368 defined in [RFC7049], could be a convenience valuetype defined in 369 this document (Appendix E) or the name of a type defined in the 370 specification. 372 A group definition can also contain choices between groups, see 373 Section 2.2.2. 375 2.2. Types 376 2.2.1. Values 378 Values such as numbers and strings can be used in place of a type. 379 (For instance, this is a very common thing to do for a keytype, 380 common enough that CDDL provides additional convenience syntax for 381 this.) 383 2.2.2. Choices 385 Many places that allow a type also allow a choice between types, 386 delimited by a "/" (slash). The entire choice construct can be put 387 into parentheses if this is required to make the construction 388 unambiguous (please see Appendix D for the details). 390 Choices of values can be used to express enumerations: 392 attire = "bow tie" / "necktie" / "Internet attire" 393 protocol = 6 / 17 395 Similarly as for types, CDDL also allows choices between groups, 396 delimited by a "//" (double slash). 398 address = { delivery } 400 delivery = ( 401 street: tstr, ? number: uint, city // 402 po-box: uint, city // 403 per-pickup: true ) 405 city = ( 406 name: tstr, zip-code: uint 407 ) 409 Both for type choices and for group choices, additional alternatives 410 can be added to a rule later in separate rules by using "/=" and 411 "//=", respectively, instead of "=": 413 attire /= "swimwear" 415 delivery //= ( 416 lat: float, long: float, drone-type: tstr 417 ) 419 It is not an error if a name is first used with a "/=" or "//=" 420 (there is no need to "create it" with "="). 422 2.2.2.1. Ranges 424 Instead of naming all the values that make up a choice, CDDL allows 425 building a _range_ out of two values that are in an ordering 426 relationship. A range can be inclusive of both ends given (denoted 427 by joining two values by ".."), or include the first and exclude the 428 second (denoted by instead using "..."). 430 device-address = byte 431 max-byte = 255 432 byte = 0..max-byte ; inclusive range 433 first-non-byte = 256 434 byte1 = 0...first-non-byte ; byte1 is equivalent to byte 436 CDDL currently only allows ranges between numbers [_range]. 438 2.2.2.2. Turning a group into a choice 440 Some choices are built out of large numbers of values, often 441 integers, each of which is best given a semantic name in the 442 specification. Instead of naming each of these integers and then 443 accumulating these into a choice, CDDL allows building a choice from 444 a group by prefixing it with a "&" character: 446 terminal-color = &basecolors 447 basecolors = ( 448 black: 0, red: 1, green: 2, yellow: 3, 449 blue: 4, magenta: 5, cyan: 6, white: 7, 450 ) 451 extended-color = &( 452 basecolors, 453 orange: 8, pink: 9, purple: 10, brown: 11, 454 ) 456 As with the use of groups in arrays (Section 3.4), the membernames 457 have only documentary value (in particular, they might be used by a 458 tool when displaying integers that are taken from that choice). 460 2.2.3. Representation Types 462 CDDL allows the specification of a data item type by referring to the 463 CBOR representation (major and minor numbers). How this is used 464 should be evident from the prelude (Appendix E). 466 It may be necessary to make use of representation types outside the 467 prelude, e.g., a specification could start by making use of an 468 existing tag in a more specific way, or define a new tag not defined 469 in the prelude: 471 my_breakfast = #6.55799(breakfast) ; cbor-any is too general! 472 breakfast = cereal / porridge 473 cereal = #6.998(tstr) 474 porridge = #6.999([liquid, solid]) 475 liquid = milk / water 476 milk = 0 477 water = 1 478 solid = tstr 480 2.2.4. Root type 482 There is no special syntax to identify the root of a CDDL data 483 structure definition: that role is simply taken by the first rule 484 defined in the file. 486 This is motivated by the usual top-down approach for defining data 487 structures, decomposing a big data structure unit into smaller parts; 488 however, except for the root type, there is no need to strictly 489 follow this sequence. 491 (Note that there is no way to use a group as a root - it must be a 492 type. Using a group as the root might be employed as a way to 493 specify a CBOR sequence in a future version of this specification; 494 this would act as if that group is used in an array and the data 495 items in that fictional array form the members of the CBOR sequence.) 497 3. Syntax 499 In this section, the overall syntax of CDDL is shown, alongside some 500 examples just illustrating syntax. (The definition will not attempt 501 to be overly formal; refer to Appendix D for the details.) 503 3.1. General conventions 505 The basic syntax is inspired by ABNF [RFC5234], with 507 o rules, whether they define groups or types, are defined with a 508 name, followed by an equals sign "=" and the actual definition 509 according to the respective syntactic rules of that definition. 511 o A name can consist of any of the characters from the set {'A', 512 ..., 'Z', 'a', ..., 'z', '0', ..., '9', '_', '-', '@', '.', '$'}, 513 starting with an alphabetic character (including '@', '_', '$') 514 and ending in one or a digit. 516 * Names are case sensitive. 518 * It is preferred style to start a name with a lower case letter. 520 * The hyphen is preferred over the underscore (except in a 521 "bareword" (Section 3.5.1), where the semantics may actually 522 require an underscore). 524 * The period may be useful for larger specifications, to express 525 some module structure (as in "tcp.throughput" vs. 526 "udp.throughput"). 528 * A number of names are predefined in the CDDL prelude, as listed 529 in Appendix E. 531 * Rule names (types or groups) do not appear in the actual CBOR 532 encoding, but names used as "barewords" in member keys do. 534 o Comments are started by a ';' (semicolon) character and finish at 535 the end of a line (LF or CRLF). 537 o outside strings, whitespace (spaces, newlines, and comments) is 538 used to separate syntactic elements for readability (and to 539 separate identifiers or numbers that follow each other); it is 540 otherwise completely optional. 542 o Hexadecimal numbers are preceded by '0x' (without quotes, lower 543 case x), and are case insensitive. Similarly, binary numbers are 544 preceded by '0b'. 546 o Text strings are enclosed by double quotation '"' characters. 547 They follow the conventions for strings as defined in section 7 of 548 [RFC7159]. (ABNF users may want to note that there is no support 549 in CDDL for the concept of case insensitivity in text strings; if 550 necessary, regular expressions can be used (Section 3.8.3).) 552 o Byte strings are enclosed by single quotation "'" characters and 553 may be prefixed by "h" or "b64". If unprefixed, the string is 554 interpreted as with a text string, except that single quotes must 555 be escaped and that the UTF-8 bytes resulting are marked as a byte 556 string (major type 2). If prefixed as "h" or "b64", the string is 557 interpreted as a sequence of hex digits or a base64(url) string, 558 respectively (as with the diagnostic notation in section 6 of 559 [RFC7049]; cf. Appendix G.2); any white space present within the 560 string (including comments) is ignored in the prefixed case. 561 [_strings] 563 o CDDL uses UTF-8 [RFC3629] for its encoding. 565 Example: 567 ; This is a comment 568 person = { g } 570 g = ( 571 "name": tstr, 572 age: int, ; "age" is a bareword 573 ) 575 3.2. Occurrence 577 An optional _occurrence_ indicator can be given in front of a group 578 entry. It is either one of the characters '?' (optional), '*' (zero 579 or more), or '+' (one or more), or is of the form n*m, where n and m 580 are optional unsigned integers and n is the lower limit (default 0) 581 and m is the upper limit (default no limit) of occurrences. 583 If no occurrence indicator is specified, the group entry is to occur 584 exactly once (as if 1*1 were specified). 586 Note that CDDL, outside any directives/annotations that could 587 possibly be defined, does not make any prescription as to whether 588 arrays or maps use the definite length or indefinite length encoding. 589 I.e., there is no correlation between leaving the size of an array 590 "open" in the spec and the fact that it is then interchanged with 591 definite or indefinite length. 593 Please also note that CDDL can describe flexibility that the data 594 model of the target representation does not have. This is rather 595 obvious for JSON, but also is relevant for CBOR: 597 apartment = { 598 kitchen: size, 599 * bedroom: size, 600 } 601 size = float ; in m2 603 The previous specification does not mean that CBOR is changed to 604 allow to use the key "bedroom" more than once. In other words, due 605 to the restrictions imposed by the data model, the third line pretty 606 much turns into: 608 ? bedroom: size, 610 (Occurrence indicators beyond one still are useful in maps for groups 611 that allow a variety of keys.) 613 3.3. Predefined names for types 615 CDDL predefines a number of names. This subsection summarizes these 616 names, but please see Appendix E for the exact definitions. 618 The following keywords for primitive datatypes are defined: 620 "bool" Boolean value (major type 7, additional information 20 or 621 21). 623 "uint" An unsigned integer (major type 0). 625 "nint" A negative integer (major type 1). 627 "int" An unsigned integer or a negative integer. 629 "float16" IEEE 754 half-precision float (major type 7, additional 630 information 25). 632 "float32" IEEE 754 single-precision float (major type 7, additional 633 information 26). 635 "float64" IEEE 754 double-precision float (major type 7, additional 636 information 27). 638 "float" One of float16, float32, or float64. 640 "bstr" or "bytes" A byte string (major type 2). 642 "tstr" or "text" Text string (major type 3) 644 (Note that there are no predefined names for arrays or maps; these 645 are defined with the syntax given below.) 647 In addition, a number of types are defined in the prelude that are 648 associated with CBOR tags, such as "tdate", "bigint", "regexp" etc. 650 3.4. Arrays 652 Array definitions surround a group with square brackets. 654 For each entry, an occurrence indicator as specified in Section 3.2 655 is permitted. 657 For example: 659 unlimited-people = [* person] 660 one-or-two-people = [1*2 person] 661 at-least-two-people = [2* person] 662 person = ( 663 name: tstr, 664 age: uint, 665 ) 667 The group "person" is defined in such a way that repeating it in the 668 array each time generates alternating names and ages, so these are 669 four valid values for a data item of type "unlimited-people": 671 ["roundlet", 1047, "psychurgy", 2204, "extrarhythmical", 2231] 672 [] 673 ["aluminize", 212, "climograph", 4124] 674 ["penintime", 1513, "endocarditis", 4084, "impermeator", 1669, 675 "coextension", 865] 677 3.5. Maps 679 The syntax for specifying maps merits special attention, as well as a 680 number of optimizations and conveniences, as it is likely to be the 681 focal point of many specifications employing CDDL. While the syntax 682 does not strictly distinguish struct and table usage of maps, it 683 caters specifically to each of them. 685 3.5.1. Structs 687 The "struct" usage of maps is similar to the way JSON objects are 688 used in many JSON applications. 690 A map is defined in the same way as defining an array (see 691 Section 3.4), except for using curly braces "{}" instead of square 692 brackets "[]". 694 An occurrence indicator as specified in Section 3.2 is permitted for 695 each group entry. 697 The following is an example of a structure: 699 Geography = [ 700 city : tstr, 701 gpsCoordinates : GpsCoordinates, 702 ] 704 GpsCoordinates = { 705 longitude : uint, ; multiplied by 10^7 706 latitude : uint, ; multiplied by 10^7 707 } 709 When encoding, the Geography structure is encoded using a CBOR array 710 with two entries (the keys for the group entries are ignored), 711 whereas the GpsCoordinates are encoded as a CBOR map with two key/ 712 value pairs. 714 Types used in a structure can be defined in separate rules or just in 715 place (potentially placed inside parentheses, such as for choices). 716 E.g.: 718 located-samples = { 719 sample-point: int, 720 samples: [+ float], 721 } 723 where "located-samples" is the datatype to be used when referring to 724 the struct, and "sample-point" and "samples" are the keys to be used. 725 This is actually a complete example: an identifier that is followed 726 by a colon can be directly used as the text string for a member key 727 (we speak of a "bareword" member key), as can a double-quoted string 728 or a number. (When other types, in particular multi-valued ones, are 729 used as keytypes, they are followed by a double arrow, see below.) 731 If a text string key does not match the syntax for an identifier (or 732 if the specifier just happens to prefer using double quotes), the 733 text string syntax can also be used in the member key position, 734 followed by a colon. The above example could therefore have been 735 written with quoted strings in the member key positions. 737 All the types defined can be used in a keytype position by following 738 them with a double arrow. A string also is a (single-valued) type, 739 so another form for this example is: 741 located-samples = { 742 "sample-point" => int, 743 "samples" => [+ float], 744 } 746 A better way to demonstrate the double-arrow use may be: 748 located-samples = { 749 sample-point: int, 750 samples: [+ float], 751 * equipment-type => equipment-tolerances, 752 } 753 equipment-type = [name: tstr, manufacturer: tstr] 754 equipment-tolerances = [+ [float, float]] 756 The example below defines a struct with optional entries: display 757 name (as a text string), the name components first name and family 758 name (as a map of text strings), and age information (as an unsigned 759 integer). 761 PersonalData = { 762 ? displayName: tstr, 763 NameComponents, 764 ? age: uint, 765 } 767 NameComponents = ( 768 ? firstName: tstr, 769 ? familyName: tstr, 770 ) 772 Note that the group definition for NameComponents does not generate 773 another map; instead, all four keys are directly in the struct built 774 by PersonalData. 776 In this example, all key/value pairs are optional from the 777 perspective of CDDL. With no occurrence indicator, an entry is 778 mandatory. 780 If the addition of more entries not specified by the current 781 specification is desired, one can add this possibility explicitly: 783 PersonalData = { 784 ? displayName: tstr, 785 NameComponents, 786 ? age: uint, 787 * tstr => any 788 } 790 NameComponents = ( 791 ? firstName: tstr, 792 ? familyName: tstr, 793 ) 795 Figure 5: Personal Data: Example for extensibility 797 The cddl tool (Appendix F) generated as one acceptable instance for 798 this specification: 800 {"familyName": "agust", "antiforeignism": "pretzel", 801 "springbuck": "illuminatingly", "exuviae": "ephemeris", 802 "kilometrage": "frogfish"} 804 (See Section 3.9 for one way to explicitly identify an extension 805 point.) 807 3.5.2. Tables 809 A table can be specified by defining a map with entries where the 810 keytype is not single-valued, e.g.: 812 square-roots = {* x => y} 813 x = int 814 y = float 816 Here, the key in each key/value pair has datatype x (defined as int), 817 and the value has datatype y (defined as float). 819 If the specification does not need to restrict one of x or y (i.e., 820 the application is free to choose per entry), it can be replaced by 821 the predefined name "any". 823 As another example, the following could be used as a conversion table 824 converting from an integer or float to a string: 826 tostring = {* mynumber => tstr} 827 mynumber = int / float 829 3.6. Tags 831 A type can make use of a CBOR tag (major type 6) by using the 832 representation type notation, giving #6.nnn(type) where nnn is an 833 unsigned integer giving the tag number and "type" is the type of the 834 data item being tagged. 836 For example, the following line from the CDDL prelude (Appendix E) 837 defines "biguint" as a type name for a positive bignum N: 839 biguint = #6.2(bstr) 841 The tags defined by [RFC7049] are included in the prelude. 842 Additional tags since registered need to be added to a CDDL 843 specification as needed; e.g., a binary UUID tag could be referenced 844 as "buuid" in a specification after defining 846 buuid = #6.37(bstr) 848 In the following example, usage of the tag 32 for URIs is optional: 850 my_uri = #6.32(tstr) / tstr 852 3.7. Unwrapping 854 The group that is used to define a map or an array can often be 855 reused in the definition of another map or array. Similarly, a type 856 defined as a tag carries an internal data item that one would like to 857 refer to. In these cases, it is expedient to simply use the name of 858 the map, array, or tag type as a handle for the group or type defined 859 inside it. 861 The "unwrap" operator (written by preceding a name by a tilde 862 character "~") can be used to strip the type defined for a name by 863 one layer, exposing the underlying group (for maps and arrays) or 864 type (for tags). 866 For example, an application might want to define a basic and an 867 advanced header. Without unwrapping, this might be done as follows: 869 basic-header-group = ( 870 field1: int, 871 field2: text, 872 ) 874 basic-header = { basic-header-group } 876 advanced-header = { 877 basic-header-group, 878 field3: bytes, 879 field4: number, ; as in the tagged type "time" 880 } 882 Unwrapping simplifies this to: 884 basic-header = { 885 field1: int, 886 field2: text, 887 } 889 advanced-header = { 890 ~basic-header, 891 field3: bytes, 892 field4: ~time, 893 } 895 (Note that leaving out the first unwrap operator in the latter 896 example would lead to nesting the basic-header in its own map inside 897 the advanced-header, while, with the unwrapped basic-header, the 898 definition of the group inside basic-header is essentially repeated 899 inside advanced-header, leading to a single map. This can be used 900 for various applications often solved by inheritance in programming 901 languages. The effect of unwrapping can also be described as 902 "threading in" the group or type inside the referenced type, which 903 suggested the thread-like "~" character.) 905 3.8. Controls 907 A _control_ allows to relate a _target_ type with a _controller_ type 908 via a _control operator_. 910 The syntax for a control type is "target .control-operator 911 controller", where control operators are special identifiers prefixed 912 by a dot. (Note that _target_ or _controller_ might need to be 913 parenthesized.) 914 A number of control operators are defined at his point. Note that 915 the CDDL tool does not currently support combining multiple controls 916 on a single target. 918 3.8.1. Control operator .size 920 A ".size" control controls the size of the target in bytes by the 921 control type. Examples: 923 full-address = [[+ label], ip4, ip6] 924 ip4 = bstr .size 4 925 ip6 = bstr .size 16 926 label = bstr .size (1..63) 928 Figure 6: Control for size in bytes 930 When applied to an unsigned integer, the ".size" control restricts 931 the range of that integer by giving a maximum number of bytes that 932 should be needed in a computer representation of that unsigned 933 integer. In other words, "uint .size N" is equivalent to 934 "0...BYTES_N", where BYTES_N == 256**N. 936 audio_sample = uint .size 3 ; 24-bit, equivalent to 0..16777215 938 Figure 7: Control for integer size in bytes 940 Note that, as with value restrictions in CDDL, this control is not a 941 representation constraint; a number that fits into fewer bytes can 942 still be represented in that form, and an inefficient implementation 943 could use a longer form (unless that is restricted by some format 944 constraints outside of CDDL, such as the rules in Section 3.9 of 945 [RFC7049]). 947 3.8.2. Control operator .bits 949 A ".bits" control on a byte string indicates that, in the target, 950 only the bits numbered by a number in the control type are allowed to 951 be set. (Bits are counted the usual way, bit number "n" being set in 952 "str" meaning that "(str[n >> 3] & (1 << (n & 7))) != 0".) 953 [_bitsendian] 955 Similarly, a ".bits" control on an unsigned integer "i" indicates 956 that for all unsigned integers "n" where "(i & (1 << n)) != 0", "n" 957 must be in the control type. 959 tcpflagbytes = bstr .bits flags 960 flags = &( 961 fin: 8, 962 syn: 9, 963 rst: 10, 964 psh: 11, 965 ack: 12, 966 urg: 13, 967 ece: 14, 968 cwr: 15, 969 ns: 0, 970 ) / (4..7) ; data offset bits 972 rwxbits = uint .bits rwx 973 rwx = &(r: 2, w: 1, x: 0) 975 Figure 8: Control for what bits can be set 977 The CDDL tool generates the following ten example instances for 978 "tcpflagbytes": 980 h'906d' h'01fc' h'8145' h'01b7' h'013d' h'409f' h'018e' h'c05f' 981 h'01fa' h'01fe' 983 These examples do not illustrate that the above CDDL specification 984 does not explicitly specify a size of two bytes: A valid all clear 985 instance of flag bytes could be "h''" or "h'00'" or even "h'000000'" 986 as well. 988 3.8.3. Control operator .regexp 990 A ".regexp" control indicates that the text string given as a target 991 needs to match the PCRE regular expression given as a value in the 992 control type, where that regular expression is anchored on both 993 sides. (If anchoring is not desired for a side, ".*" needs to be 994 inserted there.) 996 nai = tstr .regexp "\\w+@\\w+(\\.\\w+)+" 998 Figure 9: Control with a PCRE regexp 1000 The CDDL tool proposes: 1002 "N1@CH57HF.4Znqe0.dYJRN.igjf" 1004 3.8.4. Control operators .cbor and .cborseq 1006 A ".cbor" control on a byte string indicates that the byte string 1007 carries a CBOR encoded data item. Decoded, the data item matches the 1008 type given as the right-hand side argument (type1 in the following 1009 example). 1011 "bytes .cbor type1" 1013 Similarly, a ".cborseq" control on a byte string indicates that the 1014 byte string carries a sequence of CBOR encoded data items. When the 1015 data items are taken as an array, the array matches the type given as 1016 the right-hand side argument (type2 in the following example). 1018 "bytes .cborseq type2" 1020 (The conversion of the encoded sequence to an array can be effected 1021 for instance by wrapping the byte string between the two bytes 0x9f 1022 and 0xff and decoding the wrapped byte string as a CBOR encoded data 1023 item.) 1025 3.8.5. Control operators .within and .and 1027 A ".and" control on a type indicates that the data item matches both 1028 that left hand side type and the type given as the right hand side. 1029 (Formally, the resulting type is the intersection of the two types 1030 given.) 1032 "type1 .and type2" 1034 A variant of the ".and" control is the ".within" control, which 1035 expresses an additional intent: the left hand side type is meant to 1036 be a subset of the right-hand-side type. 1038 "type1 .within type2" 1040 While both forms have the identical formal semantics (intersection), 1041 the intention of the ".within" form is that the right hand side gives 1042 guidance to the types allowed on the left hand side, which typically 1043 is a socket (Section 3.9): 1045 message = $message .within message-structure 1046 message-structure = [message_type, *message_option] 1047 message_type = 0..255 1048 message_option = any 1050 $message /= [3, dough: text, topping: [* text]] 1051 $message /= [4, noodles: text, sauce: text, parmesan: bool] 1052 For ".within", a tool might flag an error if type1 allows data items 1053 that are not allowed by type2. In contrast, for ".and", there is no 1054 expectation that type1 already is a subset of type2. 1056 3.8.6. Control operators .lt, .le, .gt, .ge, .eq, .ne, and .default 1058 The controls .lt, .le, .gt, .ge, .eq, .ne specify a constraint on the 1059 left hand side type to be a value less than, less than or equal, 1060 equal to, not equal to, greather than, or greater than or equal to a 1061 value given as a (single-valued) right hand side type. In the 1062 present specification, the first four controls (.lt, .le, .gt, .ge) 1063 are defined only for numeric types, as these have a natural ordering 1064 relationship. 1066 speed = number .ge 0 ; unit: m/s 1068 A variant of the ".ne" control is the ".default" control, which 1069 expresses an additional intent: the value specified by the right- 1070 hand-side type is intended as a default value for the left hand side 1071 type given, and the implied .ne control is there to prevent this 1072 value from being sent over the wire. This control is only meaningful 1073 when the controld type is used in an optional context; otherwise 1074 there would be no way to express the default value. 1076 timer = { 1077 time: uint, 1078 ? displayed-step: (number .gt 0) .default 1 1079 } 1081 3.9. Socket/Plug 1083 Both for type choices and group choices, a mechanism is defined that 1084 facilitates starting out with empty choices and assembling them 1085 later, potentially in separate files that are concatenated to build 1086 the full specification. 1088 Per convention, CDDL extension points are marked with a leading 1089 dollar sign (types) or two leading dollar signs (groups). Tools 1090 honor that convention by not raising an error if such a type or group 1091 is not defined at all; the symbol is then taken to be an empty type 1092 choice (group choice), i.e., no choice is available. 1094 tcp-header = {seq: uint, ack: uint, * $$tcp-option} 1096 ; later, in a different file 1098 $$tcp-option //= ( 1099 sack: [+(left: uint, right: uint)] 1100 ) 1102 ; and, maybe in another file 1104 $$tcp-option //= ( 1105 sack-permitted: true 1106 ) 1108 Names that start with a single "$" are "type sockets", names with a 1109 double "$$" are "group sockets". It is not an error if there is no 1110 definition for a socket at all; this then means there is no way to 1111 satisfy the rule (i.e., the choice is empty). 1113 All definitions (plugs) for socket names must be augmentations, i.e., 1114 they must be using "/=" and "//=", respectively. 1116 To pick up the example illustrated in Figure 5, the socket/plug 1117 mechanism could be used as shown in Figure 10: 1119 PersonalData = { 1120 ? displayName: tstr, 1121 NameComponents, 1122 ? age: uint, 1123 * $$personaldata-extensions 1124 } 1126 NameComponents = ( 1127 ? firstName: tstr, 1128 ? familyName: tstr, 1129 ) 1131 ; The above already works as is. 1132 ; But then, we can add later: 1134 $$personaldata-extensions //= ( 1135 favorite-salsa: tstr, 1136 ) 1138 ; and again, somewhere else: 1140 $$personaldata-extensions //= ( 1141 shoesize: uint, 1142 ) 1144 Figure 10: Personal Data example: Using socket/plug extensibility 1146 3.10. Generics 1148 Using angle brackets, the left hand side of a rule can add formal 1149 parameters after the name being defined, as in: 1151 messages = message<"reboot", "now"> / message<"sleep", 1..100> 1152 message = {type: t, value: v} 1154 When using a generic rule, the formal parameters are bound to the 1155 actual arguments supplied (also using angle brackets), within the 1156 scope of the generic rule (as if there were a rule of the form 1157 parameter = argument). 1159 (There are some limitations to nesting of generics in Appendix F at 1160 this time.) 1162 3.11. Operator Precedence 1164 As with any language that has multiple syntactic features such as 1165 prefix and infix operators, CDDL has operators that bind more tightly 1166 than others. This is becoming more complicated than, say, in ABNF, 1167 as CDDL has both types and groups, with operators that are specific 1168 to these concepts. Type operators (such as "/" for type choice) 1169 operate on types, while group operators (such as "//" for group 1170 choice) operate on groups. Types can simply be used in groups, but 1171 groups need to be bracketed (as arrays or maps) to become types. So, 1172 type operators naturally bind closer than group operators. 1174 For instance, in 1176 t = [group1] 1177 group1 = (a / b // c / d) 1178 a = 1 b = 2 c = 3 d = 4 1180 group1 is a group choice between the type choice of a and b and the 1181 type choice of c and d. This becomes more relevant once member keys 1182 and/or occurrences are added in: 1184 t = {group2} 1185 group2 = (? ab: a / b // cd: c / d) 1186 a = 1 b = 2 c = 3 d = 4 1188 is a group choice between the optional member "ab" of type a or b and 1189 the member "cd" of type c or d. Note that the optionality is 1190 attached to the first choice ("ab"), not to the second choice. 1192 Similarly, in 1194 t = [group3] 1195 group3 = (+ a / b / c) 1196 a = 1 b = 2 c = 3 1198 group3 is a repetition of a type choice between a, b, and c [unflex]; 1199 if just a is to be repeatable, a group choice is needed to focus the 1200 occurrence: 1202 t = [group4] 1203 group4 = (+ a // b / c) 1204 a = 1 b = 2 c = 3 1206 group4 is a group choice between a repeatable a and a single b or c. 1208 In general, as with many other languages with operator precedence 1209 rules, it is best not to rely on them, but to insert parentheses for 1210 readability: 1212 t = [group4a] 1213 group4a = ((+ a) // (b / c)) 1214 a = 1 b = 2 c = 3 1215 The operator precedences, in sequence of loose to tight binding, are 1216 defined in Appendix D and summarized in Table 1. (Arities given are 1217 1 for unary prefix operators and 2 for binary infix operators.) 1219 +----------+----+---------------------------+------+ 1220 | Operator | Ar | Operates on | Prec | 1221 +----------+----+---------------------------+------+ 1222 | = | 2 | name = type, name = group | 1 | 1223 | /= | 2 | name /= type | 1 | 1224 | //= | 2 | name //= group | 1 | 1225 | // | 2 | group // group | 2 | 1226 | , | 2 | group, group | 3 | 1227 | * | 1 | * group | 4 | 1228 | N*M | 1 | N*M group | 4 | 1229 | + | 1 | + group | 4 | 1230 | ? | 1 | ? group | 4 | 1231 | => | 2 | type => type | 5 | 1232 | : | 2 | name: type | 5 | 1233 | / | 2 | type / type | 6 | 1234 | & | 1 | &group | 6 | 1235 | .. | 2 | type..type | 7 | 1236 | ... | 2 | type...type | 7 | 1237 | .anno | 2 | type .anno type | 7 | 1238 +----------+----+---------------------------+------+ 1240 Table 1: Summary of operator precedences 1242 4. Making Use of CDDL 1244 In this section, we discuss several potential ways to employ CDDL. 1246 4.1. As a guide to a human user 1248 CDDL can be used to efficiently define the layout of CBOR data, such 1249 that a human implementer can easily see how data is supposed to be 1250 encoded. 1252 Since CDDL maps parts of the CBOR data to human readable names, tools 1253 could be built that use CDDL to provide a human friendly 1254 representation of the CBOR data, and allow them to edit such data 1255 while remaining compliant to its CDDL definition. 1257 4.2. For automated checking of CBOR data structure 1259 CDDL has been specified such that a machine can handle the CDDL 1260 definition and related CBOR data (and, thus, also JSON data). For 1261 example, a machine could use CDDL to check whether or not CBOR data 1262 is compliant to its definition. 1264 The need for thoroughness of such compliance checking depends on the 1265 application. For example, an application may decide not to check the 1266 data structure at all, and use the CDDL definition solely as a means 1267 to indicate the structure of the data to the programmer. 1269 On the other end, the application may also implement a checking 1270 mechanism that goes as far as checking that all mandatory map members 1271 are available. 1273 The matter in how far the data description must be enforced by an 1274 application is left to the designers and implementers of that 1275 application, keeping in mind related security considerations. 1277 In no case the intention is that a CDDL tool would be "writing code" 1278 for an implementation. 1280 4.3. For data analysis tools 1282 In the long run, it can be expected that more and more data will be 1283 stored using the CBOR data format. 1285 Where there is data, there is data analysis and the need to process 1286 such data automatically. CDDL can be used for such automated data 1287 processing, allowing tools to verify data, clean it, and extract 1288 particular parts of interest from it. 1290 Since CBOR is designed with constrained devices in mind, a likely use 1291 of it would be small sensors. An interesting use would thus be 1292 automated analysis of sensor data. 1294 5. Security considerations 1296 This document presents a content rules language for expressing CBOR 1297 data structures. As such, it does not bring any security issues on 1298 itself, although specification of protocols that use CBOR naturally 1299 need security analysis when defined. 1301 Topics that could be considered in a security considerations section 1302 that uses CDDL to define CBOR structures include the following: 1304 o Where could the language maybe cause confusion in a way that will 1305 enable security issues? 1307 6. IANA considerations 1309 This document does not require any IANA registrations. 1311 7. Acknowledgements 1313 CDDL was originally conceived by Bert Greevenbosch, who also wrote 1314 the original five versions of this document. 1316 Inspiration was taken from the C and Pascal languages, MPEG's 1317 conventions for describing structures in the ISO base media file 1318 format, Relax-NG and its compact syntax [RELAXNG], and in particular 1319 from Andrew Lee Newton's "JSON Content Rules" 1320 [I-D.newton-json-content-rules]. 1322 Useful feedback came from Joe Hildebrand, Sean Leonard and Jim 1323 Schaad. 1325 The CDDL tool was written by Carsten Bormann, building on previous 1326 work by Troy Heninger and Tom Lord. 1328 8. References 1330 8.1. Normative References 1332 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1333 Requirement Levels", BCP 14, RFC 2119, 1334 DOI 10.17487/RFC2119, March 1997, 1335 . 1337 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1338 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1339 2003, . 1341 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1342 Specifications: ABNF", STD 68, RFC 5234, 1343 DOI 10.17487/RFC5234, January 2008, 1344 . 1346 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1347 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1348 October 2013, . 1350 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1351 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1352 2014, . 1354 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 1355 DOI 10.17487/RFC7493, March 2015, 1356 . 1358 8.2. Informative References 1360 [I-D.ietf-anima-grasp] 1361 Bormann, C., Carpenter, B., and B. Liu, "A Generic 1362 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 1363 grasp-15 (work in progress), July 2017. 1365 [I-D.ietf-core-senml] 1366 Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 1367 Bormann, "Media Types for Sensor Measurement Lists 1368 (SenML)", draft-ietf-core-senml-10 (work in progress), 1369 July 2017. 1371 [I-D.newton-json-content-rules] 1372 Newton, A. and P. Cordell, "A Language for Rules 1373 Describing JSON Content", draft-newton-json-content- 1374 rules-08 (work in progress), March 2017. 1376 [RELAXNG] OASIS, "RELAX-NG Compact Syntax", November 2002, 1377 . 1379 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1380 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1381 . 1383 [RFC7071] Borenstein, N. and M. Kucherawy, "A Media Type for 1384 Reputation Interchange", RFC 7071, DOI 10.17487/RFC7071, 1385 November 2013, . 1387 [RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network 1388 Interconnection (CDNI) Control Interface / Triggers", 1389 RFC 8007, DOI 10.17487/RFC8007, December 2016, 1390 . 1392 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1393 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1394 . 1396 Appendix A. Cemetery 1398 The following ideas have been buried in the discussions leading up to 1399 the present specification: 1401 o <...> as syntax for enumerations. We view values to be just 1402 another type (a very specific type with just one member), so that 1403 an enumeration can be denoted as a choice using "/" as the 1404 delimiter of choices. Because of this, no evidence is present 1405 that a separate syntax for enumerations is needed. 1407 A.1. Resolved Issues 1409 o The key/value pairs in maps have no fixed ordering. One could 1410 imagine situations where fixing the ordering may be of use. For 1411 example, a decoder could look for values related with integer keys 1412 1, 3 and 7. If the order were fixed and the decoder encounters 1413 the key 4 without having encountered key 3, it could conclude that 1414 key 3 is not available without doing more complicated bookkeeping. 1415 Unfortunately, neither JSON nor CBOR support this, so no attempt 1416 was made to support this in CDDL either. 1418 o CDDL distinguishes the various CBOR number types, but there is 1419 only one number type in JSON. There is no effect in specifying a 1420 precision (float16/float32/float64) when using CDDL for specifying 1421 JSON data structures. (The current validator implementation 1422 Appendix F does not handle this very well, either.) 1424 Appendix B. (Not used.) 1426 Appendix C. Change Log 1428 Changes from version 00 to version 01: 1430 o Removed constants 1432 o Updated the tag mechanism 1434 o Extended the map structure 1436 o Added examples 1438 Changes from version 01 to version 02: 1440 o Fixed example 1442 Changes from version 02 to version 03: 1444 o Added information about characters used in names 1446 o Added text about an overall data structure and order of definition 1447 of fields 1449 o Added text about encoding of keys 1451 o Added table with keywords 1453 o Strings and integer writing conventions 1454 o Added ABNF 1456 Changes from version 03 to version 04: 1458 o Removed optional fields for non-maps 1460 o Defined all key/value pairs in maps are considered optional from 1461 the CDDL perspective 1463 o Allow omission of type of keys for maps with only text string and 1464 integer keys 1466 o Changed order of definitions 1468 o Updated fruit and moves examples 1470 o Renamed the "Philosophy" section to "Using CDDL", and added more 1471 text about CDDL usage 1473 o Several editorials 1475 Changes from version 04 to version 05: 1477 o Added text about alternative datatypes and any datatype 1479 o Fixed typos 1481 o Restructured syntax and semantics 1483 Changes from version 05 to version 05: 1485 o Fixed the ABNF for choices (no longer need to write a: (b/c)) 1487 o Added group choices (//) 1489 o Added /= and //= 1491 o Added experimental socket/plug 1493 o Added aliases text, bytes, null to prelude 1495 o Documented generics 1497 o Fixed more typos 1499 Changes from 06 to 07: 1501 o .cbor, .cborseq, .within, .and 1502 o Define .size on uint 1504 o Extended Diagnostic Notation 1506 o Precedence discussion and table 1508 o Remove some of the "issues" that can only be understood with 1509 historical context 1511 o Prefer "text" over "tstr" in some of the examples 1513 o Add "unsigned" to the prelude 1515 Changes from 07 to 08: 1517 o .lt, .le, .eq, .ne, .gt, .ge 1519 o .default 1521 Changes from 08 to 09: 1523 o Take annotations and socket/plug out of the nursery; they have 1524 been battle-proven enough. 1526 o Define a value notation for byte strings as well. 1528 o Removed discussion section that was no longer relevant; move 1529 "Resolved Issues" to appendix. 1531 Changes from 09 to 10: 1533 o Remove a long but not very elucidating example. (Maybe we'll add 1534 back some shorter examples later.) 1536 o A few clarifications. 1538 o Updated author list. 1540 Changes from 10 to 11: 1542 o Define unwrapping operator ~ 1544 o Change term for annotation into "control" (but leave "annotate" 1545 for when it actually is meant in that sense) 1547 Appendix D. ABNF grammar 1549 The following is a formal definition of the CDDL syntax in Augmented 1550 Backus-Naur Form (ABNF, [RFC5234]). [_abnftodo] 1552 cddl = S 1*rule 1553 rule = typename [genericparm] S assign S type S 1554 / groupname [genericparm] S assign S grpent S 1556 typename = id 1557 groupname = id 1559 assign = "=" / "/=" / "//=" 1561 genericparm = "<" S id S *("," S id S ) ">" 1562 genericarg = "<" S type1 S *("," S type1 S ) ">" 1564 type = type1 S *("/" S type1 S) 1566 type1 = type2 [S (rangeop / ctlop) S type2] 1568 type2 = value 1569 / typename [genericarg] 1570 / "(" type ")" 1571 / "~" S groupname [genericarg] 1572 / "#" "6" ["." uint] "(" S type S ")" ; note no space! 1573 / "#" DIGIT ["." uint] ; major/ai 1574 / "#" ; any 1575 / "{" S group S "}" 1576 / "[" S group S "]" 1577 / "&" S "(" S group S ")" 1578 / "&" S groupname [genericarg] 1580 rangeop = "..." / ".." 1582 ctlop = "." id 1584 group = grpchoice S *("//" S grpchoice S) 1586 grpchoice = *grpent 1588 grpent = [occur S] [memberkey S] type optcom 1589 / [occur S] groupname [genericarg] optcom ; preempted by above 1590 / [occur S] "(" S group S ")" optcom 1592 memberkey = type1 S "=>" 1593 / bareword S ":" 1594 / value S ":" 1596 bareword = id 1598 optcom = S ["," S] 1600 occur = [uint] "*" [uint] 1601 / "+" 1602 / "?" 1604 uint = ["0x" / "0b"] "0" 1605 / DIGIT1 *DIGIT 1606 / "0x" 1*HEXDIG 1607 / "0b" 1*BINDIG 1609 value = number 1610 / text 1611 / bytes 1613 int = ["-"] uint 1615 ; This is a float if it has fraction or exponent; int otherwise 1616 number = int ["." fraction] ["e" exponent ] 1617 fraction = 1*DIGIT 1618 exponent = int 1620 text = %x22 *SCHAR %x22 1621 SCHAR = %x20-21 / %x23-5B / %x5D-10FFFD / SESC 1622 SESC = "\" %x20-10FFFD 1624 bytes = [bsqual] %x27 *BCHAR %x27 1625 BCHAR = %x20-26 / %x28-5B / %x5D-10FFFD / SESC / CRLF 1626 bsqual = %x68 ; "h" 1627 / %x62.36.34 ; "b64" 1629 id = EALPHA *(*("-" / ".") (EALPHA / DIGIT)) 1630 ALPHA = %x41-5A / %x61-7A 1631 EALPHA = %x41-5A / %x61-7A / "@" / "_" / "$" 1632 DIGIT = %x30-39 1633 DIGIT1 = %x31-39 1634 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 1635 BINDIG = %x30-31 1637 S = *WS 1638 WS = SP / NL 1639 SP = %x20 1640 NL = COMMENT / CRLF 1641 COMMENT = ";" *PCHAR CRLF 1642 PCHAR = %x20-10FFFD 1643 CRLF = %x0A / %x0D.0A 1644 Figure 11: CDDL ABNF 1646 Appendix E. Standard Prelude 1648 The following prelude is automatically added to each CDDL file 1649 [tdate]. (Note that technically, it is a postlude, as it does not 1650 disturb the selection of the first rule as the root of the 1651 definition.) 1652 any = # 1654 uint = #0 1655 nint = #1 1656 int = uint / nint 1658 bstr = #2 1659 bytes = bstr 1660 tstr = #3 1661 text = tstr 1663 tdate = #6.0(tstr) 1664 time = #6.1(number) 1665 number = int / float 1666 biguint = #6.2(bstr) 1667 bignint = #6.3(bstr) 1668 bigint = biguint / bignint 1669 integer = int / bigint 1670 unsigned = uint / biguint 1671 decfrac = #6.4([e10: int, m: integer]) 1672 bigfloat = #6.5([e2: int, m: integer]) 1673 eb64url = #6.21(any) 1674 eb64legacy = #6.22(any) 1675 eb16 = #6.23(any) 1676 encoded-cbor = #6.24(bstr) 1677 uri = #6.32(tstr) 1678 b64url = #6.33(tstr) 1679 b64legacy = #6.34(tstr) 1680 regexp = #6.35(tstr) 1681 mime-message = #6.36(tstr) 1682 cbor-any = #6.55799(any) 1684 float16 = #7.25 1685 float32 = #7.26 1686 float64 = #7.27 1687 float16-32 = float16 / float32 1688 float32-64 = float32 / float64 1689 float = float16-32 / float64 1691 false = #7.20 1692 true = #7.21 1693 bool = false / true 1694 nil = #7.22 1695 null = nil 1696 undefined = #7.23 1698 Figure 12: CDDL Prelude 1700 Note that the prelude is deemed to be fixed. This means, for 1701 instance, that additional tags beyond [RFC7049], as registered, need 1702 to be defined in each CDDL file that is using them. 1704 A common stumbling point is that the prelude does not define a type 1705 "string". CBOR has byte strings ("bytes" in the prelude) and text 1706 strings ("text"), so a type that is simply called "string" would be 1707 ambiguous. 1709 E.1. Use with JSON 1711 The JSON generic data model (implicit in [RFC7159]) is a subset of 1712 the generic data model of CBOR. So one can use CDDL with JSON by 1713 limiting oneself to what can be represented in JSON. Roughly 1714 speaking, this means leaving out byte strings, tags, and simple 1715 values other than "false", "true", and "null", leading to the 1716 following limited prelude: 1718 any = # 1720 uint = #0 1721 nint = #1 1722 int = uint / nint 1724 tstr = #3 1725 text = tstr 1727 number = int / float 1729 float16 = #7.25 1730 float32 = #7.26 1731 float64 = #7.27 1732 float16-32 = float16 / float32 1733 float32-64 = float32 / float64 1734 float = float16-32 / float64 1736 false = #7.20 1737 true = #7.21 1738 bool = false / true 1739 nil = #7.22 1740 null = nil 1742 Figure 13: JSON compatible subset of CDDL Prelude 1744 (The major types given here do not have a direct meaning in JSON, but 1745 they can be interpreted as CBOR major types translated through 1746 Section 4 of [RFC7049].) 1747 There are a few fine points in using CDDL with JSON. First, JSON 1748 does not distinguish between integers and floating point numbers; 1749 there is only one kind of number (which may happen to be integral). 1750 In this context, specifying a type as "uint", "nint" or "int" then 1751 becomes a predicate that the number be integral. As an example, this 1752 means that the following JSON numbers are all matching "uint": 1754 10 10.0 1e1 1.0e1 100e-1 1756 (The fact that these are all integers may be surprising to users 1757 accustomed to the long tradition in programming languages of using 1758 decimal points or exponents in a number to indicate a floating point 1759 literal.) 1761 Fundamentally, the number system of JSON itself is based on decimal 1762 numbers and decimal fractions and does not have limits to its 1763 precision or range. In practice, JSON numbers are often parsed into 1764 a number type that is called float64 here, creating a number of 1765 limitations to the generic data model [RFC7493]. In particular, this 1766 means that integers can only be expressed with interoperable 1767 exactness when they lie in the range [-(2**53)+1, (2**53)-1] -- a 1768 smaller range than that covered by CDDL "int". 1770 JSON applications that want to stay compatible with I-JSON therefore 1771 may want to define integer types with more limited ranges, such as in 1772 Figure 14. Note that the types given here are not part of the 1773 prelude; they need to be copied into the CDDL specification if 1774 needed. 1776 ij-uint = 0..9007199254740991 1777 ij-nint = -9007199254740991..-1 1778 ij-int = -9007199254740991..9007199254740991 1780 Figure 14: I-JSON types for CDDL (not part of prelude) 1782 JSON applications that do not need to stay compatible with I-JSON and 1783 that actually may need to go beyond the 64-bit unsigned and negative 1784 integers supported by "int" (= "uint"/"nint") may want to use the 1785 following additional types from the standard prelude, which are 1786 expressed in terms of tags but can straightforwardly be mapped into 1787 JSON (but not I-JSON) numbers: 1789 biguint = #6.2(bstr) 1790 bignint = #6.3(bstr) 1791 bigint = biguint / bignint 1792 integer = int / bigint 1793 unsigned = uint / biguint 1794 CDDL at this point does not have a way to express the unlimited 1795 floating point precision that is theoretically possible with JSON; at 1796 the time of writing, this is rarely used in protocols in practice. 1798 Note that a data model described in CDDL is always restricted by what 1799 can be expressed in the serialization; e.g., floating point values 1800 such as NaN (not a number) and the infinities cannot be represented 1801 in JSON even if they are allowed in the CDDL generic data model. 1803 Appendix F. The CDDL tool 1805 A rough CDDL tool is available. For CDDL specifications, it can 1806 check the syntax, generate one or more instances (expressed in CBOR 1807 diagnostic notation or in pretty-printed JSON), and validate an 1808 existing instance against the specification: 1810 Usage: 1811 cddl spec.cddl generate [n] 1812 cddl spec.cddl json-generate [n] 1813 cddl spec.cddl validate instance.cbor 1814 cddl spec.cddl validate instance.json 1816 Figure 15: CDDL tool usage 1818 Install on a system with a modern Ruby via: 1820 gem install cddl 1822 Figure 16: CDDL tool installation 1824 The accompanying CBOR diagnostic tools (which are automatically 1825 installed by the above) are described in https://github.com/cabo/ 1826 cbor-diag; they can be used to convert between binary CBOR, a pretty- 1827 printed form of that, CBOR diagnostic notation, JSON, and YAML. 1829 Appendix G. Extended Diagnostic Notation 1831 Section 6 of [RFC7049] defines a "diagnostic notation" in order to be 1832 able to converse about CBOR data items without having to resort to 1833 binary data. Diagnostic notation is based on JSON, with extensions 1834 for representing CBOR constructs such as binary data and tags. 1836 (Standardizing this together with the actual interchange format does 1837 not serve to create another interchange format, but enables the use 1838 of a shared diagnostic notation in tools for and documents about 1839 CBOR.) 1840 This section discusses a few extensions to the diagnostic notation 1841 that have turned out to be useful since RFC 7049 was written. We 1842 refer to the result as extended diagnostic notation (EDN). 1844 G.1. White space in byte string notation 1846 Examples often benefit from some white space (spaces, line breaks) in 1847 byte strings. In extended diagnostic notation, white space is 1848 ignored in prefixed byte strings; for instance, the following are 1849 equivalent: 1851 h'48656c6c6f20776f726c64' 1852 h'48 65 6c 6c 6f 20 77 6f 72 6c 64' 1853 h'4 86 56c 6c6f 1854 20776 f726c64' 1856 G.2. Text in byte string notation 1858 Diagnostic notation notates Byte strings in one of the [RFC4648] base 1859 encodings,, enclosed in single quotes, prefixed by >h< for base16, 1860 >b32< for base32, >h32< for base32hex, >b64< for base64 or base64url. 1861 Quite often, byte strings carry bytes that are meaningfully 1862 interpreted as UTF-8 text. Extended Diagnostic Notation allows the 1863 use of single quotes without a prefix to express byte strings with 1864 UTF-8 text; for instance, the following are equivalent: 1866 'hello world' 1867 h'68656c6c6f20776f726c64' 1869 The escaping rules of JSON strings are applied equivalently for text- 1870 based byte strings, e.g., \ stands for a single backslash and ' 1871 stands for a single quote. White space is included literally, i.e., 1872 the previous section does not apply to text-based byte strings. 1874 G.3. Embedded CBOR and CBOR sequences in byte strings 1876 Where a byte string is to carry an embedded CBOR-encoded item, or 1877 more generally a sequence of zero or more such items, the diagnostic 1878 notation for these zero or more CBOR data items, separated by 1879 commata, can be enclosed in << and >> to notate the byte string 1880 resulting from encoding the data items and concatenating the result. 1881 For instance, each pair of columns in the following are equivalent: 1883 <<1>> h'01' 1884 <<1, 2>> h'0102' 1885 <<"foo", null>> h'63666F6FF6' 1886 <<>> h'' 1888 G.4. Concatenated Strings 1890 While the ability to include white space enables line-breaking of 1891 encoded byte strings, a mechanism is needed to be able to include 1892 text strings as well as byte strings in direct UTF-8 representation 1893 into line-based documents (such as RFCs and source code). 1895 We extend the diagnostic notation by allowing multiple text strings 1896 or multiple byte strings to be notated separated by white space, 1897 these are then concatenated into a single text or byte string, 1898 respectively. Text strings and byte strings do not mix within such a 1899 concatenation, except that byte string notation can be used inside a 1900 sequence of concatenated text string notation to encode characters 1901 that may be better represented in an encoded way. The following four 1902 values are equivalent: 1904 "Hello world" 1905 "Hello " "world" 1906 "Hello" h'20' "world" 1907 "" h'48656c6c6f20776f726c64' "" 1909 Similarly, the following byte string values are equivalent 1911 'Hello world' 1912 'Hello ' 'world' 1913 'Hello ' h'776f726c64' 1914 'Hello' h'20' 'world' 1915 '' h'48656c6c6f20776f726c64' '' b64'' 1916 h'4 86 56c 6c6f' h' 20776 f726c64' 1918 (Note that the approach of separating by whitespace, while familiar 1919 from the C language, requires some attention - a single comma makes a 1920 big difference here.) 1922 G.5. Hexadecimal, octal, and binary numbers 1924 In addition to JSON's decimal numbers, EDN provides hexadecimal, 1925 octal and binary numbers in the usual C-language notation (octal with 1926 0o prefix present only). 1928 The following are equivalent: 1930 4711 1931 0x1267 1932 0o11147 1933 0b1001001100111 1935 As are: 1937 1.5 1938 0x1.8p0 1939 0x18p-4 1941 G.6. Comments 1943 Longer pieces of diagnostic notation may benefit from comments. JSON 1944 famously does not provide for comments, and basic RFC 7049 diagnostic 1945 notation inherits this property. 1947 In extended diagnostic notation, comments can be included, delimited 1948 by slashes ("/"). Any text within and including a pair of slashes is 1949 considered a comment. 1951 Comments are considered white space. Hence, they are allowed in 1952 prefixed byte strings; for instance, the following are equivalent: 1954 h'68656c6c6f20776f726c64' 1955 h'68 65 6c /doubled l!/ 6c 6f /hello/ 1956 20 /space/ 1957 77 6f 72 6c 64' /world/ 1959 This can be used to annotate a CBOR structure as in: 1961 /grasp-message/ [/M_DISCOVERY/ 1, /session-id/ 10584416, 1962 /objective/ [/objective-name/ "opsonize", 1963 /D, N, S/ 7, /loop-count/ 105]] 1965 (There are currently no end-of-line comments. If we want to add 1966 them, "//" sounds like a reasonable delimiter given that we already 1967 use slashes for comments, but we also could go e.g. for "#".) 1969 Appendix H. Examples 1971 This section contains various examples of structures defined using 1972 CDDL. 1974 The theme for the first example is taken from [RFC7071], which 1975 defines certain JSON structures in English. For a similar example, 1976 it may also be of interest to examine Appendix A of [RFC8007], which 1977 contains a CDDL definition for a JSON structure defined in the main 1978 body of the RFC. 1980 The second subsection in this appendix translates examples from 1981 [I-D.newton-json-content-rules] into CDDL. 1983 These examples all happen to describe data that is interchanged in 1984 JSON. Examples for CDDL definitions of data that is interchanged in 1985 CBOR can be found in [RFC8152], [I-D.ietf-anima-grasp], or 1986 [I-D.ietf-core-senml]. 1988 H.1. RFC 7071 1990 [RFC7071] defines the Reputon structure for JSON using somewhat 1991 formalized English text. Here is a (somewhat verbose) equivalent 1992 definition using the same terms, but notated in CDDL: 1994 reputation-object = { 1995 reputation-context, 1996 reputon-list 1997 } 1999 reputation-context = ( 2000 application: text 2001 ) 2003 reputon-list = ( 2004 reputons: reputon-array 2005 ) 2007 reputon-array = [* reputon] 2009 reputon = { 2010 rater-value, 2011 assertion-value, 2012 rated-value, 2013 rating-value, 2014 ? conf-value, 2015 ? normal-value, 2016 ? sample-value, 2017 ? gen-value, 2018 ? expire-value, 2019 * ext-value, 2020 } 2022 rater-value = ( rater: text ) 2023 assertion-value = ( assertion: text ) 2024 rated-value = ( rated: text ) 2025 rating-value = ( rating: float16 ) 2026 conf-value = ( confidence: float16 ) 2027 normal-value = ( normal-rating: float16 ) 2028 sample-value = ( sample-size: uint ) 2029 gen-value = ( generated: uint ) 2030 expire-value = ( expires: uint ) 2031 ext-value = ( text => any ) 2033 An equivalent, more compact form of this example would be: 2035 reputation-object = { 2036 application: text 2037 reputons: [* reputon] 2038 } 2040 reputon = { 2041 rater: text 2042 assertion: text 2043 rated: text 2044 rating: float16 2045 ? confidence: float16 2046 ? normal-rating: float16 2047 ? sample-size: uint 2048 ? generated: uint 2049 ? expires: uint 2050 * text => any 2051 } 2053 Note how this rather clearly delineates the structure somewhat 2054 shrouded by so many words in section 6.2.2. of [RFC7071]. Also, this 2055 definition makes it clear that several ext-values are allowed (by 2056 definition with different member names); RFC 7071 could be read to 2057 forbid the repetition of ext-value ("A specific reputon-element MUST 2058 NOT appear more than once" is ambiguous.) 2060 The CDDL tool (which hasn't quite been trained for polite 2061 conversation) says: 2063 { 2064 "application": "tridentiferous", 2065 "reputons": [ 2066 { 2067 "rater": "loamily", 2068 "assertion": "Dasyprocta", 2069 "rated": "uncommensurableness", 2070 "rating": 0.05055809746548934, 2071 "confidence": 0.7484706448605812, 2072 "normal-rating": 0.8677887734049299, 2073 "sample-size": 4059, 2074 "expires": 3969, 2075 "bearer": "nitty", 2076 "faucal": "postulnar", 2077 "naturalism": "sarcotic" 2078 }, 2079 { 2080 "rater": "precreed", 2081 "assertion": "xanthosis", 2082 "rated": "balsamy", 2083 "rating": 0.36091333590593955, 2084 "confidence": 0.3700759808403371, 2085 "sample-size": 3904 2086 }, 2087 { 2088 "rater": "urinosexual", 2089 "assertion": "malacostracous", 2090 "rated": "arenariae", 2091 "rating": 0.9210673488013762, 2092 "normal-rating": 0.4778762617112776, 2093 "sample-size": 4428, 2094 "generated": 3294, 2095 "backfurrow": "enterable", 2096 "fruitgrower": "flannelflower" 2097 }, 2098 { 2099 "rater": "pedologistically", 2100 "assertion": "unmetaphysical", 2101 "rated": "elocutionist", 2102 "rating": 0.42073613384304287, 2103 "misimagine": "retinaculum", 2104 "snobbish": "contradict", 2105 "Bosporanic": "periostotomy", 2106 "dayworker": "intragyral" 2107 } 2108 ] 2109 } 2111 H.1.1. Examples from JSON Content Rules 2113 Although JSON Content Rules [I-D.newton-json-content-rules] seems to 2114 address a more general problem than CDDL, it is still a worthwhile 2115 resource to explore for examples (beyond all the inspiration the 2116 format itself has had for CDDL). 2118 Figure 2 of the JCR I-D looks very similar, if slightly less noisy, 2119 in CDDL: 2121 root = [2*2 { 2122 precision: text, 2123 Latitude: float, 2124 Longitude: float, 2125 Address: text, 2126 City: text, 2127 State: text, 2128 Zip: text, 2129 Country: text 2130 }] 2132 Figure 17: JCR, Figure 2, in CDDL 2134 Apart from the lack of a need to quote the member names, text strings 2135 are called "text" or "tstr" in CDDL ("string" would be ambiguous as 2136 CBOR also provides byte strings). 2138 The CDDL tool creates the below example instance for this: 2140 [{"precision": "pyrosphere", "Latitude": 0.5399712314350172, 2141 "Longitude": 0.5157523963028087, "Address": "resow", 2142 "City": "problemwise", "State": "martyrlike", "Zip": "preprove", 2143 "Country": "Pace"}, 2144 {"precision": "unrigging", "Latitude": 0.10422704368372193, 2145 "Longitude": 0.6279808663725834, "Address": "picturedom", 2146 "City": "decipherability", "State": "autometry", "Zip": "pout", 2147 "Country": "wimple"}] 2149 Figure 4 of the JCR I-D in CDDL: 2151 root = { image } 2153 image = ( 2154 Image: { 2155 size, 2156 Title: text, 2157 thumbnail, 2158 IDs: [* int] 2159 } 2160 ) 2162 size = ( 2163 Width: 0..1280 2164 Height: 0..1024 2165 ) 2167 thumbnail = ( 2168 Thumbnail: { 2169 size, 2170 Url: ~uri 2171 } 2172 ) 2174 This shows how the group concept can be used to keep related elements 2175 (here: width, height) together, and to emulate the JCR style of 2176 specification. (It also shows referencing a type by unwrapping a tag 2177 from the prelude, "uri" - this could be done differently.) The more 2178 compact form of Figure 5 of the JCR I-D could be emulated like this: 2180 root = { 2181 Image: { 2182 size, Title: text, 2183 Thumbnail: { size, Url: ~uri }, 2184 IDs: [* int] 2185 } 2186 } 2188 size = ( 2189 Width: 0..1280, 2190 Height: 0..1024, 2191 ) 2193 The CDDL tool creates the below example instance for this: 2195 {"Image": {"Width": 566, "Height": 516, "Title": "leisterer", 2196 "Thumbnail": {"Width": 1111, "Height": 176, "Url": 32("scrog")}, 2197 "IDs": []}} 2199 Editorial Comments 2201 [_format] So far, the ability to restrict format choices have not been 2202 needed beyond the floating point formats. Those can be 2203 applied to ranges using the new .and control now. It is not 2204 clear we want to add more format control before we have a use 2205 case. 2207 [_range] TO DO: define this precisely. This clearly includes integers 2208 and floats. Strings - as in "a".."z" - could be added if 2209 desired, but this would require adopting a definition of string 2210 ordering and possibly a successor function so "a".."z" does not 2211 include "bb". 2213 [_strings] TO DO: This still needs to be fully realized in the ABNF and 2214 in the CDDL tool. 2216 [_bitsendian] How useful would it be to have another variant that counts 2217 bits like in RFC box notation? (Or at least per-byte? 2218 32-bit words don't always perfectly mesh with byte 2219 strings.) 2221 [unflex] A comment has been that this is counter-intuitive. One 2222 solution would be to simply disallow unparenthesized usage of 2223 occurrence indicators in front of type choices unless a member 2224 key is also present like in group2 above. 2226 [_abnftodo] Potential improvements: the prefixed byte strings are more 2227 liberally specified than they actually are. [^_abnfdontdo]: 2228 representation indicators are not supported. - and this will 2229 stay so. 2231 [tdate] The prelude as included here does not yet have a .regexp control 2232 on tdate, but we probably do want to have one. 2234 Authors' Addresses 2236 Henk Birkholz 2237 Fraunhofer SIT 2238 Rheinstrasse 75 2239 Darmstadt 64295 2240 Germany 2242 Email: henk.birkholz@sit.fraunhofer.de 2243 Christoph Vigano 2244 Universitaet Bremen 2246 Email: christoph.vigano@uni-bremen.de 2248 Carsten Bormann 2249 Universitaet Bremen TZI 2250 Bibliothekstr. 1 2251 Bremen D-28359 2252 Germany 2254 Phone: +49-421-218-63921 2255 Email: cabo@tzi.org