idnits 2.17.1 draft-ietf-cbor-cddl-06.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 (November 19, 2018) is 1985 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) == Missing Reference: 'Cc' is mentioned on line 1249, but not defined == Missing Reference: 'Aa' is mentioned on line 1249, but not defined == Missing Reference: 'Ss' is mentioned on line 1249, but not defined == Missing Reference: 'Ee' is mentioned on line 1249, but not defined == Missing Reference: 'RFCthis' is mentioned on line 1655, but not defined -- Looks like a reference, but probably isn't: '1' on line 2533 -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO6093' ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-13) exists of draft-bormann-cbor-cddl-freezer-01 -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CBOR H. Birkholz 3 Internet-Draft Fraunhofer SIT 4 Intended status: Standards Track C. Vigano 5 Expires: May 23, 2019 Universitaet Bremen 6 C. Bormann 7 Universitaet Bremen TZI 8 November 19, 2018 10 Concise data definition language (CDDL): a notational convention to 11 express CBOR and JSON data structures 12 draft-ietf-cbor-cddl-06 14 Abstract 16 This document proposes a notational convention to express CBOR data 17 structures (RFC 7049, Concise Binary Object Representation). Its 18 main goal is to provide an easy and unambiguous way to express 19 structures for protocol messages and data formats that use CBOR or 20 JSON. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on May 23, 2019. 39 Copyright Notice 41 Copyright (c) 2018 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 4 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 59 2. The Style of Data Structure Specification . . . . . . . . . . 4 60 2.1. Groups and Composition in CDDL . . . . . . . . . . . . . 6 61 2.1.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 8 62 2.1.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 9 63 2.2. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 2.2.1. Values . . . . . . . . . . . . . . . . . . . . . . . 9 65 2.2.2. Choices . . . . . . . . . . . . . . . . . . . . . . . 10 66 2.2.3. Representation Types . . . . . . . . . . . . . . . . 12 67 2.2.4. Root type . . . . . . . . . . . . . . . . . . . . . . 13 68 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 69 3.1. General conventions . . . . . . . . . . . . . . . . . . . 13 70 3.2. Occurrence . . . . . . . . . . . . . . . . . . . . . . . 15 71 3.3. Predefined names for types . . . . . . . . . . . . . . . 16 72 3.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 16 73 3.5. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 17 74 3.5.1. Structs . . . . . . . . . . . . . . . . . . . . . . . 17 75 3.5.2. Tables . . . . . . . . . . . . . . . . . . . . . . . 20 76 3.5.3. Non-deterministic order . . . . . . . . . . . . . . . 21 77 3.5.4. Cuts in Maps . . . . . . . . . . . . . . . . . . . . 22 78 3.6. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 23 79 3.7. Unwrapping . . . . . . . . . . . . . . . . . . . . . . . 23 80 3.8. Controls . . . . . . . . . . . . . . . . . . . . . . . . 24 81 3.8.1. Control operator .size . . . . . . . . . . . . . . . 25 82 3.8.2. Control operator .bits . . . . . . . . . . . . . . . 25 83 3.8.3. Control operator .regexp . . . . . . . . . . . . . . 26 84 3.8.4. Control operators .cbor and .cborseq . . . . . . . . 28 85 3.8.5. Control operators .within and .and . . . . . . . . . 28 86 3.8.6. Control operators .lt, .le, .gt, .ge, .eq, .ne, and 87 .default . . . . . . . . . . . . . . . . . . . . . . 29 88 3.9. Socket/Plug . . . . . . . . . . . . . . . . . . . . . . . 30 89 3.10. Generics . . . . . . . . . . . . . . . . . . . . . . . . 31 90 3.11. Operator Precedence . . . . . . . . . . . . . . . . . . . 32 91 4. Making Use of CDDL . . . . . . . . . . . . . . . . . . . . . 33 92 4.1. As a guide to a human user . . . . . . . . . . . . . . . 33 93 4.2. For automated checking of CBOR data structure . . . . . . 34 94 4.3. For data analysis tools . . . . . . . . . . . . . . . . . 34 95 5. Security considerations . . . . . . . . . . . . . . . . . . . 34 96 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 97 6.1. CDDL control operator registry . . . . . . . . . . . . . 35 98 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 99 7.1. Normative References . . . . . . . . . . . . . . . . . . 36 100 7.2. Informative References . . . . . . . . . . . . . . . . . 37 101 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 39 102 A.1. RFC 7071 . . . . . . . . . . . . . . . . . . . . . . . . 39 103 A.2. Examples from JSON Content Rules . . . . . . . . . . . . 43 104 Appendix B. ABNF grammar . . . . . . . . . . . . . . . . . . . . 45 105 Appendix C. Matching rules . . . . . . . . . . . . . . . . . . . 47 106 Appendix D. Standard Prelude . . . . . . . . . . . . . . . . . . 51 107 Appendix E. Use with JSON . . . . . . . . . . . . . . . . . . . 53 108 Appendix F. A CDDL tool . . . . . . . . . . . . . . . . . . . . 55 109 Appendix G. Extended Diagnostic Notation . . . . . . . . . . . . 56 110 G.1. White space in byte string notation . . . . . . . . . . . 56 111 G.2. Text in byte string notation . . . . . . . . . . . . . . 56 112 G.3. Embedded CBOR and CBOR sequences in byte strings . . . . 57 113 G.4. Concatenated Strings . . . . . . . . . . . . . . . . . . 57 114 G.5. Hexadecimal, octal, and binary numbers . . . . . . . . . 58 115 G.6. Comments . . . . . . . . . . . . . . . . . . . . . . . . 58 116 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 59 117 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 59 118 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 59 120 1. Introduction 122 In this document, a notational convention to express CBOR [RFC7049] 123 data structures is defined. 125 The main goal for the convention is to provide a unified notation 126 that can be used when defining protocols that use CBOR. We term the 127 convention "Concise data definition language", or CDDL. 129 The CBOR notational convention has the following goals: 131 (G1) Provide an unambiguous description of the overall structure of 132 a CBOR data item. 134 (G2) Be flexible in expressing the multiple ways in which data can 135 be represented in the CBOR data format. 137 (G3) Able to express common CBOR datatypes and structures. 139 (G4) Provide a single format that is both readable and editable for 140 humans and processable by machine. 142 (G5) Enable automatic checking of CBOR data items for data format 143 compliance. 145 (G6) Enable extraction of specific elements from CBOR data for 146 further processing. 148 Not an original goal per se, but a convenient side effect of the JSON 149 generic data model being a subset of the CBOR generic data model, is 150 the fact that CDDL can also be used for describing JSON data 151 structures (see Appendix E). 153 This document has the following structure: 155 The syntax of CDDL is defined in Section 3. Examples of CDDL and 156 related CBOR data items ("instances", which all happen to be in JSON 157 form) are given in Appendix A. Section 4 discusses usage of CDDL. 158 Examples are provided early in the text to better illustrate concept 159 definitions. A formal definition of CDDL using ABNF grammar is 160 provided in Appendix B. Finally, a _prelude_ of standard CDDL 161 definitions that is automatically prepended to and thus available in 162 every CBOR specification is listed in Appendix D. 164 1.1. Requirements notation 166 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 167 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 168 "OPTIONAL" in this document are to be interpreted as described in 169 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 170 capitals, as shown here. 172 1.2. Terminology 174 New terms are introduced in _cursive_. CDDL text in the running text 175 is in "typewriter". 177 In this specification, the term "byte" is used in its now customary 178 sense as a synonym for "octet". 180 2. The Style of Data Structure Specification 182 CDDL focuses on styles of specification that are in use in the 183 community employing the data model as pioneered by JSON and now 184 refined in CBOR. 186 There are a number of more or less atomic elements of a CBOR data 187 model, such as numbers, simple values (false, true, nil), text and 188 byte strings; CDDL does not focus on specifying their structure. 189 CDDL of course also allows adding a CBOR tag to a data item. 191 The more important components of a data structure definition language 192 are the data types used for composition: arrays and maps in CBOR 193 (called arrays and objects in JSON). While these are only two 194 representation formats, they are used to specify four loosely 195 distinguishable styles of composition: 197 o A _vector_, an array of elements that are mostly of the same 198 semantics. The set of signatures associated with a signed data 199 item is a typical application of a vector. 201 o A _record_, an array the elements of which have different, 202 positionally defined semantics, as detailed in the data structure 203 definition. A 2D point, specified as an array of an x coordinate 204 (which comes first) and a y coordinate (coming second) is an 205 example of a record, as is the pair of exponent (first) and 206 mantissa (second) in a CBOR decimal fraction. 208 o A _table_, a map from a domain of map keys to a domain of map 209 values, that are mostly of the same semantics. A set of language 210 tags, each mapped to a text string translated to that specific 211 language, is an example of a table. The key domain is usually not 212 limited to a specific set by the specification, but open for the 213 application, e.g., in a table mapping IP addresses to MAC 214 addresses, the specification does not attempt to foresee all 215 possible IP addresses. In a language such as JavaScript, a "Map" 216 (as opposed to a plain "Object") would often be employed to 217 achieve the generality of the key domain. 219 o A _struct_, a map from a domain of map keys as defined by the 220 specification to a domain of map values the semantics of each of 221 which is bound to a specific map key. This is what many people 222 have in mind when they think about JSON objects; CBOR adds the 223 ability to use map keys that are not just text strings. Structs 224 can be used to solve similar problems as records; the use of 225 explicit map keys facilitates optionality and extensibility. 227 Two important concepts provide the foundation for CDDL: 229 1. Instead of defining all four types of composition in CDDL 230 separately, or even defining one kind for arrays (vectors and 231 records) and one kind for maps (tables and structs), there is 232 only one kind of composition in CDDL: the _group_ (Section 2.1). 234 2. The other important concept is that of a _type_. The entire CDDL 235 specification defines a type (the one defined by its first 236 _rule_), which formally is the set of CBOR data items that are 237 acceptable as "instances" for this specification. CDDL 238 predefines a number of basic types such as "uint" (unsigned 239 integer) or "tstr" (text string), often making use of a simple 240 formal notation for CBOR data items. Each value that can be 241 expressed as a CBOR data item also is a type in its own right, 242 e.g. "1". A type can be built as a _choice_ of other types, 243 e.g., an "int" is either a "uint" or a "nint" (negative integer). 244 Finally, a type can be built as an array or a map from a group. 246 The rest of this section introduces a number of basic concepts of 247 CDDL, and section Section 3 defines additional syntax. Appendix C 248 gives a concise summary of the semantics of CDDL. 250 2.1. Groups and Composition in CDDL 252 CDDL Groups are lists of group _entries_, each of which can be a 253 name/value pair or a more complex group expression (which then in 254 turn stands for a sequence of name/value pairs). A CDDL group is a 255 production in a grammar that matches certain sequences of name/value 256 pairs but not others. The grammar is based on the concepts of 257 Parsing Expression Grammars [PEG]. 259 In an array context, only the value of the name/value pair is 260 represented; the name is annotation only (and can be left off from 261 the group specification if not needed). In a map context, the names 262 become the map keys ("member keys"). 264 In an array context, the actual sequence of elements in the group is 265 important, as that sequence is the information that allows 266 associating actual array elements with entries in the group. In a 267 map context, the sequence of entries in a group is not relevant (but 268 there is still a need to write down group entries in a sequence). 270 An array matches a specification given as a group when the group 271 matches a sequence of name/value pairs the value parts of which 272 exactly match the elements of the array in order. 274 A map matches a specification given as a group when the group matches 275 a sequence of name/value pairs such that all of these name/value 276 pairs are present in the map and the map has no name/value pair that 277 is not covered by the group. 279 A simple example of using a group directly in a map definition is: 281 person = { 282 age: int, 283 name: tstr, 284 employer: tstr, 285 } 287 Figure 1: Using a group directly in a map 289 The three entries of the group are written between the curly braces 290 that create the map: Here, "age", "name", and "employer" are the 291 names that turn into the map key text strings, and "int" and "tstr" 292 (text string) are the types of the map values under these keys. 294 A group by itself (without creating a map around it) can be placed in 295 (round) parentheses, and given a name by using it in a rule: 297 pii = ( 298 age: int, 299 name: tstr, 300 employer: tstr, 301 ) 303 Figure 2: A basic group 305 This separate, named group definition allows us to rephrase Figure 1 306 as: 308 person = { 309 pii 310 } 312 Figure 3: Using a group by name 314 Note that the (curly) braces signify the creation of a map; the 315 groups themselves are neutral as to whether they will be used in a 316 map or an array. 318 As shown in Figure 1, the parentheses for groups are optional when 319 there is some other set of brackets present. Note that they can 320 still be used, leading to the not so realistic, but perfectly valid 321 example: 323 person = {( 324 age: int, 325 name: tstr, 326 employer: tstr, 327 )} 329 Figure 4: Using a parenthesized group in a map 331 Groups can be used to factor out common parts of structs, e.g., 332 instead of writing copy/paste style specifications such as in 333 Figure 5, one can factor out the common subgroup, choose a name for 334 it, and write only the specific parts into the individual maps 335 (Figure 6). 337 person = { 338 age: int, 339 name: tstr, 340 employer: tstr, 341 } 343 dog = { 344 age: int, 345 name: tstr, 346 leash-length: float, 347 } 349 Figure 5: Maps with copy/paste 351 person = { 352 identity, 353 employer: tstr, 354 } 356 dog = { 357 identity, 358 leash-length: float, 359 } 361 identity = ( 362 age: int, 363 name: tstr, 364 ) 366 Figure 6: Using a group for factorization 368 Note that the lists inside the braces in the above definitions 369 constitute (anonymous) groups, while "identity" is a named group. 371 2.1.1. Usage 373 Groups are the instrument used in composing data structures with 374 CDDL. It is a matter of style in defining those structures whether 375 to define groups (anonymously) right in their contexts or whether to 376 define them in a separate rule and to reference them with their 377 respective name (possibly more than once). 379 With this, one is allowed to define all small parts of their data 380 structures and compose bigger protocol units with those or to have 381 only one big protocol data unit that has all definitions ad hoc where 382 needed. 384 2.1.2. Syntax 386 The composition syntax intends to be concise and easy to read: 388 o The start and end of a group can be marked by '(' and ')' 390 o Definitions of entries inside of a group are noted as follows: 391 _keytype => valuetype,_ (read "keytype maps to valuetype"). The 392 comma is actually optional (not just in the final entry), but it 393 is considered good style to set it. The double arrow can be 394 replaced by a colon in the common case of directly using a text 395 string or integer literal as a key (see Section 3.5.1; this is 396 also the common way of naming elements of an array just for 397 documentation, see Section 3.4). 399 A basic entry consists of a _keytype_ and a _valuetype_, both of 400 which are types (Section 2.2); this entry matches any name-value pair 401 the name of which is in the keytype and the value of which is in the 402 valuetype. 404 A group defined as a sequence of group entries matches any sequence 405 of name-value pairs that is composed by concatenation in order of 406 what the entries match. 408 A group definition can also contain choices between groups, see 409 Section 2.2.2. 411 2.2. Types 413 2.2.1. Values 415 Values such as numbers and strings can be used in place of a type. 416 (For instance, this is a very common thing to do for a keytype, 417 common enough that CDDL provides additional convenience syntax for 418 this.) 420 The value notation is based on the C language, but does not offer all 421 the syntactic variations (see Appendix B for details). The value 422 notation for numbers inherits from C the distinction between integer 423 values (no fractional part or exponent given -- NR1 [ISO6093]) and 424 floating point values (where a fractional part and/or an exponent is 425 present -- NR2 or NR3), so the type "1" does not include any floating 426 point numbers while the types "1e3" and "1.5" are both floating point 427 numbers and do not include any integer numbers. 429 2.2.2. Choices 431 Many places that allow a type also allow a choice between types, 432 delimited by a "/" (slash). The entire choice construct can be put 433 into parentheses if this is required to make the construction 434 unambiguous (please see Appendix B for the details). 436 Choices of values can be used to express enumerations: 438 attire = "bow tie" / "necktie" / "Internet attire" 439 protocol = 6 / 17 441 Similarly as for types, CDDL also allows choices between groups, 442 delimited by a "//" (double slash). Note that the "//" operators 443 binds much more weakly than the other CDDL operators, so each line 444 within "delivery" in the following example is its own alternative in 445 the group choice: 447 address = { delivery } 449 delivery = ( 450 street: tstr, ? number: uint, city // 451 po-box: uint, city // 452 per-pickup: true ) 454 city = ( 455 name: tstr, zip-code: uint 456 ) 458 A group choice matches the union of the sets of name-value pair 459 sequences that the alternatives in the choice can. 461 Both for type choices and for group choices, additional alternatives 462 can be added to a rule later in separate rules by using "/=" and 463 "//=", respectively, instead of "=": 465 attire /= "swimwear" 467 delivery //= ( 468 lat: float, long: float, drone-type: tstr 469 ) 471 It is not an error if a name is first used with a "/=" or "//=" 472 (there is no need to "create it" with "="). 474 2.2.2.1. Ranges 476 Instead of naming all the values that make up a choice, CDDL allows 477 building a _range_ out of two values that are in an ordering 478 relationship: A lower bound (first value) and an upper bound (second 479 value). A range can be inclusive of both bounds given (denoted by 480 joining two values by ".."), or include the lower bound and exclude 481 the upper bound (denoted by instead using "..."). If the lower bound 482 exceeds the upper bound, the resulting type is the empty set (this 483 behavior can be desirable when generics, Section 3.10, are being 484 used). 486 device-address = byte 487 max-byte = 255 488 byte = 0..max-byte ; inclusive range 489 first-non-byte = 256 490 byte1 = 0...first-non-byte ; byte1 is equivalent to byte 492 CDDL currently only allows ranges between integers (matching integer 493 values) or between floating point values (matching floating point 494 values). If both are needed in a type, a type choice between the two 495 kinds of ranges can be (clumsily) used: 497 int-range = 0..10 ; only integers match 498 float-range = 0.0..10.0 ; only floats match 499 BAD-range1 = 0..10.0 ; NOT DEFINED 500 BAD-range2 = 0.0..10 ; NOT DEFINED 501 numeric-range = int-range / float-range 503 (See also the control operators .lt/.ge and .le/.gt in 504 Section 3.8.6.) 506 Note that the dot is a valid name continuation character in CDDL, so 508 min..max 510 is not a range expression but a single name. When using a name as 511 the left hand side of a range operator, use spacing as in 513 min .. max 515 to separate off the range operator. 517 2.2.2.2. Turning a group into a choice 519 Some choices are built out of large numbers of values, often 520 integers, each of which is best given a semantic name in the 521 specification. Instead of naming each of these integers and then 522 accumulating these into a choice, CDDL allows building a choice from 523 a group by prefixing it with a "&" character: 525 terminal-color = &basecolors 526 basecolors = ( 527 black: 0, red: 1, green: 2, yellow: 3, 528 blue: 4, magenta: 5, cyan: 6, white: 7, 529 ) 530 extended-color = &( 531 basecolors, 532 orange: 8, pink: 9, purple: 10, brown: 11, 533 ) 535 As with the use of groups in arrays (Section 3.4), the member names 536 have only documentary value (in particular, they might be used by a 537 tool when displaying integers that are taken from that choice). 539 2.2.3. Representation Types 541 CDDL allows the specification of a data item type by referring to the 542 CBOR representation (major types and additional information, 543 Section 2 of [RFC7049]). How this is used should be evident from the 544 prelude (Appendix D): a hash mark ("#") optionally followed by a 545 number from 0 to 7 identifying the major type, which then can be 546 followed by a dot and a number specifying the additional information. 547 This construction specifies the set of values that can be serialized 548 in CBOR (i.e., "any"), by the given major type if one is given, or by 549 the given major type with the additional information if both are 550 given. Where a major type of 6 (Tag) is used, the type of the tagged 551 item can be specified by appending it in parentheses. 553 Note that although this notation is based on the CBOR serialization, 554 it is about a set of values at the data model level, e.g. "#7.25" 555 specifies the set of values that can be represented as half-precision 556 floats; it does not mandate that these values also do have to be 557 serialized as half-precision floats: CDDL does not provide any 558 language means to restrict the choice of serialization variants. 559 This also enables the use of CDDL with JSON, which uses a 560 fundamentally different way of serializing (some of) the same values. 562 It may be necessary to make use of representation types outside the 563 prelude, e.g., a specification could start by making use of an 564 existing tag in a more specific way, or define a new tag not defined 565 in the prelude: 567 my_breakfast = #6.55799(breakfast) ; cbor-any is too general! 568 breakfast = cereal / porridge 569 cereal = #6.998(tstr) 570 porridge = #6.999([liquid, solid]) 571 liquid = milk / water 572 milk = 0 573 water = 1 574 solid = tstr 576 2.2.4. Root type 578 There is no special syntax to identify the root of a CDDL data 579 structure definition: that role is simply taken by the first rule 580 defined in the file. 582 This is motivated by the usual top-down approach for defining data 583 structures, decomposing a big data structure unit into smaller parts; 584 however, except for the root type, there is no need to strictly 585 follow this sequence. 587 (Note that there is no way to use a group as a root - it must be a 588 type.) 590 3. Syntax 592 In this section, the overall syntax of CDDL is shown, alongside some 593 examples just illustrating syntax. (The definition will not attempt 594 to be overly formal; refer to Appendix B for the details.) 596 3.1. General conventions 598 The basic syntax is inspired by ABNF [RFC5234], with 600 o rules, whether they define groups or types, are defined with a 601 name, followed by an equals sign "=" and the actual definition 602 according to the respective syntactic rules of that definition. 604 o A name can consist of any of the characters from the set {'A', 605 ..., 'Z', 'a', ..., 'z', '0', ..., '9', '_', '-', '@', '.', '$'}, 606 starting with an alphabetic character (including '@', '_', '$') 607 and ending in one or a digit. 609 * Names are case sensitive. 611 * It is preferred style to start a name with a lower case letter. 613 * The hyphen is preferred over the underscore (except in a 614 "bareword" (Section 3.5.1), where the semantics may actually 615 require an underscore). 617 * The period may be useful for larger specifications, to express 618 some module structure (as in "tcp.throughput" vs. 619 "udp.throughput"). 621 * A number of names are predefined in the CDDL prelude, as listed 622 in Appendix D. 624 * Rule names (types or groups) do not appear in the actual CBOR 625 encoding, but names used as "barewords" in member keys do. 627 o Comments are started by a ';' (semicolon) character and finish at 628 the end of a line (LF or CRLF). 630 o outside strings, whitespace (spaces, newlines, and comments) is 631 used to separate syntactic elements for readability (and to 632 separate identifiers or numbers that follow each other); it is 633 otherwise completely optional. 635 o Hexadecimal numbers are preceded by '0x' (without quotes, lower 636 case x), and are case insensitive. Similarly, binary numbers are 637 preceded by '0b'. 639 o Text strings are enclosed by double quotation '"' characters. 640 They follow the conventions for strings as defined in section 7 of 641 [RFC8259]. (ABNF users may want to note that there is no support 642 in CDDL for the concept of case insensitivity in text strings; if 643 necessary, regular expressions can be used (Section 3.8.3).) 645 o Byte strings are enclosed by single quotation "'" characters and 646 may be prefixed by "h" or "b64". If unprefixed, the string is 647 interpreted as with a text string, except that single quotes must 648 be escaped and that the UTF-8 bytes resulting are marked as a byte 649 string (major type 2). If prefixed as "h" or "b64", the string is 650 interpreted as a sequence of pairs of hex digits (base16) or a 651 base64(url) string, respectively (as with the diagnostic notation 652 in section 6 of [RFC7049]; cf. Appendix G.2); any white space 653 present within the string (including comments) is ignored in the 654 prefixed case. 656 o CDDL uses UTF-8 [RFC3629] for its encoding. 658 Example: 660 ; This is a comment 661 person = { g } 663 g = ( 664 "name": tstr, 665 age: int, ; "age" is a bareword 666 ) 668 3.2. Occurrence 670 An optional _occurrence_ indicator can be given in front of a group 671 entry. It is either one of the characters '?' (optional), '*' (zero 672 or more), or '+' (one or more), or is of the form n*m, where n and m 673 are optional unsigned integers and n is the lower limit (default 0) 674 and m is the upper limit (default no limit) of occurrences. 676 If no occurrence indicator is specified, the group entry is to occur 677 exactly once (as if 1*1 were specified). A group entry with an 678 occurrence indicator matches sequences of name-value pairs that are 679 composed by concatenating a number of sequences that the basic group 680 entry matches, where the number needs to be allowed by the occurrence 681 indicator. 683 Note that CDDL, outside any directives/annotations that could 684 possibly be defined, does not make any prescription as to whether 685 arrays or maps use the definite length or indefinite length encoding. 686 I.e., there is no correlation between leaving the size of an array 687 "open" in the spec and the fact that it is then interchanged with 688 definite or indefinite length. 690 Please also note that CDDL can describe flexibility that the data 691 model of the target representation does not have. This is rather 692 obvious for JSON, but also is relevant for CBOR: 694 apartment = { 695 kitchen: size, 696 * bedroom: size, 697 } 698 size = float ; in m2 700 The previous specification does not mean that CBOR is changed to 701 allow to use the key "bedroom" more than once. In other words, due 702 to the restrictions imposed by the data model, the third line pretty 703 much turns into: 705 ? bedroom: size, 707 (Occurrence indicators beyond one still are useful in maps for groups 708 that allow a variety of keys.) 710 3.3. Predefined names for types 712 CDDL predefines a number of names. This subsection summarizes these 713 names, but please see Appendix D for the exact definitions. 715 The following keywords for primitive datatypes are defined: 717 "bool" Boolean value (major type 7, additional information 20 or 718 21). 720 "uint" An unsigned integer (major type 0). 722 "nint" A negative integer (major type 1). 724 "int" An unsigned integer or a negative integer. 726 "float16" A number representable as an IEEE 754 half-precision float 727 (major type 7, additional information 25). 729 "float32" A number representable as an IEEE 754 single-precision 730 float (major type 7, additional information 26). 732 "float64" A number representable as an IEEE 754 double-precision 733 float (major type 7, additional information 27). 735 "float" One of float16, float32, or float64. 737 "bstr" or "bytes" A byte string (major type 2). 739 "tstr" or "text" Text string (major type 3) 741 (Note that there are no predefined names for arrays or maps; these 742 are defined with the syntax given below.) 744 In addition, a number of types are defined in the prelude that are 745 associated with CBOR tags, such as "tdate", "bigint", "regexp" etc. 747 3.4. Arrays 749 Array definitions surround a group with square brackets. 751 For each entry, an occurrence indicator as specified in Section 3.2 752 is permitted. 754 For example: 756 unlimited-people = [* person] 757 one-or-two-people = [1*2 person] 758 at-least-two-people = [2* person] 759 person = ( 760 name: tstr, 761 age: uint, 762 ) 764 The group "person" is defined in such a way that repeating it in the 765 array each time generates alternating names and ages, so these are 766 four valid values for a data item of type "unlimited-people": 768 ["roundlet", 1047, "psychurgy", 2204, "extrarhythmical", 2231] 769 [] 770 ["aluminize", 212, "climograph", 4124] 771 ["penintime", 1513, "endocarditis", 4084, "impermeator", 1669, 772 "coextension", 865] 774 3.5. Maps 776 The syntax for specifying maps merits special attention, as well as a 777 number of optimizations and conveniences, as it is likely to be the 778 focal point of many specifications employing CDDL. While the syntax 779 does not strictly distinguish struct and table usage of maps, it 780 caters specifically to each of them. 782 But first, let's reiterate a feature of CBOR that it has inherited 783 from JSON: The key/value pairs in CBOR maps have no fixed ordering. 784 (One could imagine situations where fixing the ordering may be of 785 use. For example, a decoder could look for values related with 786 integer keys 1, 3 and 7. If the order were fixed and the decoder 787 encounters the key 4 without having encountered key 3, it could 788 conclude that key 3 is not available without doing more complicated 789 bookkeeping. Unfortunately, neither JSON nor CBOR support this, so 790 no attempt was made to support this in CDDL either.) 792 3.5.1. Structs 794 The "struct" usage of maps is similar to the way JSON objects are 795 used in many JSON applications. 797 A map is defined in the same way as defining an array (see 798 Section 3.4), except for using curly braces "{}" instead of square 799 brackets "[]". 801 An occurrence indicator as specified in Section 3.2 is permitted for 802 each group entry. 804 The following is an example of a structure: 806 Geography = [ 807 city : tstr, 808 gpsCoordinates : GpsCoordinates, 809 ] 811 GpsCoordinates = { 812 longitude : uint, ; multiplied by 10^7 813 latitude : uint, ; multiplied by 10^7 814 } 816 When encoding, the Geography structure is encoded using a CBOR array 817 with two entries (the keys for the group entries are ignored), 818 whereas the GpsCoordinates are encoded as a CBOR map with two key/ 819 value pairs. 821 Types used in a structure can be defined in separate rules or just in 822 place (potentially placed inside parentheses, such as for choices). 823 E.g.: 825 located-samples = { 826 sample-point: int, 827 samples: [+ float], 828 } 830 where "located-samples" is the datatype to be used when referring to 831 the struct, and "sample-point" and "samples" are the keys to be used. 832 This is actually a complete example: an identifier that is followed 833 by a colon can be directly used as the text string for a member key 834 (we speak of a "bareword" member key), as can a double-quoted string 835 or a number. (When other types, in particular multi-valued ones, are 836 used as the types of keys, they are followed by a double arrow, see 837 below.) 839 If a text string key does not match the syntax for an identifier (or 840 if the specifier just happens to prefer using double quotes), the 841 text string syntax can also be used in the member key position, 842 followed by a colon. The above example could therefore have been 843 written with quoted strings in the member key positions. More 844 generally, all the types defined can be used in a keytype position by 845 following them with a double arrow -- in particular, the double arrow 846 is necessary if a type is named by an identifier (which would be 847 interpreted as a string before a colon). A string also is a (single- 848 valued) type, so another form for this example is: 850 located-samples = { 851 "sample-point" => int, 852 "samples" => [+ float], 853 } 855 See Section 3.5.4 below for how the colon shortcut described here 856 also adds some implied semantics. 858 A better way to demonstrate the double-arrow use may be: 860 located-samples = { 861 sample-point: int, 862 samples: [+ float], 863 * equipment-type => equipment-tolerances, 864 } 865 equipment-type = [name: tstr, manufacturer: tstr] 866 equipment-tolerances = [+ [float, float]] 868 The example below defines a struct with optional entries: display 869 name (as a text string), the name components first name and family 870 name (as text strings), and age information (as an unsigned integer). 872 PersonalData = { 873 ? displayName: tstr, 874 NameComponents, 875 ? age: uint, 876 } 878 NameComponents = ( 879 ? firstName: tstr, 880 ? familyName: tstr, 881 ) 883 Note that the group definition for NameComponents does not generate 884 another map; instead, all four keys are directly in the struct built 885 by PersonalData. 887 In this example, all key/value pairs are optional from the 888 perspective of CDDL. With no occurrence indicator, an entry is 889 mandatory. 891 If the addition of more entries not specified by the current 892 specification is desired, one can add this possibility explicitly: 894 PersonalData = { 895 ? displayName: tstr, 896 NameComponents, 897 ? age: uint, 898 * tstr => any 899 } 901 NameComponents = ( 902 ? firstName: tstr, 903 ? familyName: tstr, 904 ) 906 Figure 7: Personal Data: Example for extensibility 908 The CDDL tool reported on in Appendix F generated as one acceptable 909 instance for this specification: 911 {"familyName": "agust", "antiforeignism": "pretzel", 912 "springbuck": "illuminatingly", "exuviae": "ephemeris", 913 "kilometrage": "frogfish"} 915 (See Section 3.9 for one way to explicitly identify an extension 916 point.) 918 3.5.2. Tables 920 A table can be specified by defining a map with entries where the 921 keytype is not single-valued, e.g.: 923 square-roots = {* x => y} 924 x = int 925 y = float 927 Here, the key in each key/value pair has datatype x (defined as int), 928 and the value has datatype y (defined as float). 930 If the specification does not need to restrict one of x or y (i.e., 931 the application is free to choose per entry), it can be replaced by 932 the predefined name "any". 934 As another example, the following could be used as a conversion table 935 converting from an integer or float to a string: 937 tostring = {* mynumber => tstr} 938 mynumber = int / float 940 3.5.3. Non-deterministic order 942 While the way arrays are matched is fully determined by the Parsing 943 Expression Grammar (PEG) algorithm, matching is more complicated for 944 maps, as maps do not have an inherent order. For each candidate 945 name/value pair that the PEG algorithm would try, a matching member 946 is picked out of the entire map. For certain group expressions, more 947 than one member in the map may match. Most often, this is 948 inconsequential, as the group expression tends to consume all 949 matches: 951 labeled-values = { 952 ? fritz: number, 953 * label => value 954 } 955 label = text 956 value = number 958 Here, if any member with the key "fritz" is present, this will be 959 picked by the first entry of the group; all remaining text/number 960 member will be picked by the second entry (and if anything remains 961 unpicked, the map does not match). 963 However, it is possible to construct group expressions where what is 964 actually picked is indeterminate, and does matter: 966 do-not-do-this = { 967 int => int, 968 int => 6, 969 } 971 When this expression is matched against "{3: 5, 4: 6}", the first 972 group entry might pick off the "3: 5", leaving "4: 6" for matching 973 the second one. Or it might pick off "4: 6", leaving nothing for the 974 second entry. This pathological non-determinism is caused by 975 specifying more general before more specific, and by having a general 976 rule that only consumes a subset of the map key/value pairs that it 977 is able to match -- both tend not to occur in real-world 978 specifications of maps. At the time of writing, CDDL tools cannot 979 detect such cases automatically, and for the present version of the 980 CDDL specification, the specification writer is simply urged to not 981 write pathologically non-deterministic specifications. 983 (The astute reader will be reminded of what was called "ambiguous 984 content models" in SGML and "non-deterministic content models" in 985 XML. That problem is related to the one described here, but the 986 problem here is specifically caused by the lack of order in maps, 987 something that the XML schema languages do not have to contend with. 989 Note that Relax-NG's "interleave" pattern handles lack of order 990 explicitly on the specification side, while the instances in XML 991 always have determinate order.) 993 3.5.4. Cuts in Maps 995 The extensibility idiom discussed above for structs has one problem: 997 extensible-map-example = { 998 ? "optional-key" => int, 999 * tstr => any 1000 } 1002 In this example, there is one optional key "optional-key", which, 1003 when present, maps to an integer. There is also a wild card for any 1004 future additions. 1006 Unfortunately, the data item 1008 { "optional-key": "nonsense" } 1010 does match this specification: While the first entry of the group 1011 does not match, the second one (the wildcard) does. This may be very 1012 well desirable (e.g., if a future extension is to be allowed to 1013 extend the type of "optional-key"), but in many cases isn't. 1015 In anticipation of a more general potential feature called "cuts", 1016 CDDL allows inserting a cut "^" into the definition of the map entry: 1018 extensible-map-example = { 1019 ? "optional-key" ^ => int, 1020 * tstr => any 1021 } 1023 A cut in this position means that once the member key matches the 1024 name part of an entry that carries a cut, other potential matches for 1025 the key of the member that occur in later entries in the group of the 1026 map are no longer allowed. In other words, when a group entry would 1027 pick a key/value pair based on just a matching key, it "locks in" the 1028 pick -- this rule applies independent of whether the value matches as 1029 well, so when it does not, the entire map fails to match. In 1030 summary, the example above no longer matches the specification as 1031 modified with the cut. 1033 Since the desire for this kind of exclusive matching is so frequent, 1034 the ":" shortcut is actually defined to include the cut semantics. 1035 So the preceding example (including the cut) can be written more 1036 simply as: 1038 extensible-map-example = { 1039 ? "optional-key": int, 1040 * tstr => any 1041 } 1043 or even shorter, using a bareword for the key: 1045 extensible-map-example = { 1046 ? optional-key: int, 1047 * tstr => any 1048 } 1050 3.6. Tags 1052 A type can make use of a CBOR tag (major type 6) by using the 1053 representation type notation, giving #6.nnn(type) where nnn is an 1054 unsigned integer giving the tag number and "type" is the type of the 1055 data item being tagged. 1057 For example, the following line from the CDDL prelude (Appendix D) 1058 defines "biguint" as a type name for a positive bignum N: 1060 biguint = #6.2(bstr) 1062 The tags defined by [RFC7049] are included in the prelude. 1063 Additional tags since registered need to be added to a CDDL 1064 specification as needed; e.g., a binary UUID tag could be referenced 1065 as "buuid" in a specification after defining 1067 buuid = #6.37(bstr) 1069 In the following example, usage of the tag 32 for URIs is optional: 1071 my_uri = #6.32(tstr) / tstr 1073 3.7. Unwrapping 1075 The group that is used to define a map or an array can often be 1076 reused in the definition of another map or array. Similarly, a type 1077 defined as a tag carries an internal data item that one would like to 1078 refer to. In these cases, it is expedient to simply use the name of 1079 the map, array, or tag type as a handle for the group or type defined 1080 inside it. 1082 The "unwrap" operator (written by preceding a name by a tilde 1083 character "~") can be used to strip the type defined for a name by 1084 one layer, exposing the underlying group (for maps and arrays) or 1085 type (for tags). 1087 For example, an application might want to define a basic and an 1088 advanced header. Without unwrapping, this might be done as follows: 1090 basic-header-group = ( 1091 field1: int, 1092 field2: text, 1093 ) 1095 basic-header = [ basic-header-group ] 1097 advanced-header = [ 1098 basic-header-group, 1099 field3: bytes, 1100 field4: number, ; as in the tagged type "time" 1101 ] 1103 Unwrapping simplifies this to: 1105 basic-header = [ 1106 field1: int, 1107 field2: text, 1108 ] 1110 advanced-header = [ 1111 ~basic-header, 1112 field3: bytes, 1113 field4: ~time, 1114 ] 1116 (Note that leaving out the first unwrap operator in the latter 1117 example would lead to nesting the basic-header in its own array 1118 inside the advanced-header, while, with the unwrapped basic-header, 1119 the definition of the group inside basic-header is essentially 1120 repeated inside advanced-header, leading to a single array. This can 1121 be used for various applications often solved by inheritance in 1122 programming languages. The effect of unwrapping can also be 1123 described as "threading in" the group or type inside the referenced 1124 type, which suggested the thread-like "~" character.) 1126 3.8. Controls 1128 A _control_ allows to relate a _target_ type with a _controller_ type 1129 via a _control operator_. 1131 The syntax for a control type is "target .control-operator 1132 controller", where control operators are special identifiers prefixed 1133 by a dot. (Note that _target_ or _controller_ might need to be 1134 parenthesized.) 1135 A number of control operators are defined at this point. Further 1136 control operators may be defined by new versions of this 1137 specification or by registering them according to the procedures in 1138 Section 6.1. 1140 3.8.1. Control operator .size 1142 A ".size" control controls the size of the target in bytes by the 1143 control type. The control is defined for text and byte strings, 1144 where it directly controls the number of bytes in the string. It is 1145 also defined for unsigned integers (see below). Figure 8 shows 1146 example usage for byte strings. 1148 full-address = [[+ label], ip4, ip6] 1149 ip4 = bstr .size 4 1150 ip6 = bstr .size 16 1151 label = bstr .size (1..63) 1153 Figure 8: Control for size in bytes 1155 When applied to an unsigned integer, the ".size" control restricts 1156 the range of that integer by giving a maximum number of bytes that 1157 should be needed in a computer representation of that unsigned 1158 integer. In other words, "uint .size N" is equivalent to 1159 "0...BYTES_N", where BYTES_N == 256**N. 1161 audio_sample = uint .size 3 ; 24-bit, equivalent to 0..16777215 1163 Figure 9: Control for integer size in bytes 1165 Note that, as with value restrictions in CDDL, this control is not a 1166 representation constraint; a number that fits into fewer bytes can 1167 still be represented in that form, and an inefficient implementation 1168 could use a longer form (unless that is restricted by some format 1169 constraints outside of CDDL, such as the rules in Section 3.9 of 1170 [RFC7049]). 1172 3.8.2. Control operator .bits 1174 A ".bits" control on a byte string indicates that, in the target, 1175 only the bits numbered by a number in the control type are allowed to 1176 be set. (Bits are counted the usual way, bit number "n" being set in 1177 "str" meaning that "(str[n >> 3] & (1 << (n & 7))) != 0".) 1178 Similarly, a ".bits" control on an unsigned integer "i" indicates 1179 that for all unsigned integers "n" where "(i & (1 << n)) != 0", "n" 1180 must be in the control type. 1182 tcpflagbytes = bstr .bits flags 1183 flags = &( 1184 fin: 8, 1185 syn: 9, 1186 rst: 10, 1187 psh: 11, 1188 ack: 12, 1189 urg: 13, 1190 ece: 14, 1191 cwr: 15, 1192 ns: 0, 1193 ) / (4..7) ; data offset bits 1195 rwxbits = uint .bits rwx 1196 rwx = &(r: 2, w: 1, x: 0) 1198 Figure 10: Control for what bits can be set 1200 The CDDL tool reported on in Appendix F generates the following ten 1201 example instances for "tcpflagbytes": 1203 h'906d' h'01fc' h'8145' h'01b7' h'013d' h'409f' h'018e' h'c05f' 1204 h'01fa' h'01fe' 1206 These examples do not illustrate that the above CDDL specification 1207 does not explicitly specify a size of two bytes: A valid all clear 1208 instance of flag bytes could be "h''" or "h'00'" or even "h'000000'" 1209 as well. 1211 3.8.3. Control operator .regexp 1213 A ".regexp" control indicates that the text string given as a target 1214 needs to match the XSD regular expression given as a value in the 1215 control type. XSD regular expressions are defined in Appendix F of 1216 [W3C.REC-xmlschema-2-20041028]. 1218 nai = tstr .regexp "[A-Za-z0-9]+@[A-Za-z0-9]+(\\.[A-Za-z0-9]+)+" 1220 Figure 11: Control with an XSD regexp 1222 An example matching this regular expression: 1224 "N1@CH57HF.4Znqe0.dYJRN.igjf" 1226 3.8.3.1. Usage considerations 1228 Note that XSD regular expressions do not support the usual \x or \u 1229 escapes for hexadecimal expression of bytes or unicode code points. 1230 However, in CDDL the XSD regular expressions are contained in text 1231 strings, the literal notation for which provides \u escapes; this 1232 should suffice for most applications that use regular expressions for 1233 text strings. (Note that this also means that there is one level of 1234 string escaping before the XSD escaping rules are applied.) 1236 XSD regular expressions support character class subtraction, a 1237 feature often not found in regular expression libraries; 1238 specification writers may want to use this feature sparingly. 1239 Similar considerations apply to Unicode character classes; where 1240 these are used, the specification that employs CDDL SHOULD identify 1241 which Unicode versions are addressed. 1243 Other surprises for infrequent users of XSD regular expressions may 1244 include: 1246 o No direct support for case insensitivity. While case 1247 insensitivity has gone mostly out of fashion in protocol design, 1248 it is sometimes needed and then needs to be expressed manually as 1249 in "[Cc][Aa][Ss][Ee]". 1251 o The support for popular character classes such as \w and \d is 1252 based on Unicode character properties, which is often not what is 1253 desired in an ASCII-based protocol and thus might lead to 1254 surprises. (\s and \S do have their more conventional meanings, 1255 and "." matches any character but the line ending characters \r or 1256 \n.) 1258 3.8.3.2. Discussion 1260 There are many flavors of regular expression in use in the 1261 programming community. For instance, perl-compatible regular 1262 expressions (PCRE) are widely used and probably are more useful than 1263 XSD regular expressions. However, there is no normative reference 1264 for PCRE that could be used in the present document. Instead, we opt 1265 for XSD regular expressions for now. There is precedent for that 1266 choice in the IETF, e.g., in YANG [RFC7950]. 1268 Note that CDDL uses controls as its main extension point. This 1269 creates the opportunity to add further regular expression formats in 1270 addition to the one referenced here if desired. As an example, a 1271 control ".pcre" is defined in [I-D.bormann-cbor-cddl-freezer]. 1273 3.8.4. Control operators .cbor and .cborseq 1275 A ".cbor" control on a byte string indicates that the byte string 1276 carries a CBOR encoded data item. Decoded, the data item matches the 1277 type given as the right-hand side argument (type1 in the following 1278 example). 1280 "bytes .cbor type1" 1282 Similarly, a ".cborseq" control on a byte string indicates that the 1283 byte string carries a sequence of CBOR encoded data items. When the 1284 data items are taken as an array, the array matches the type given as 1285 the right-hand side argument (type2 in the following example). 1287 "bytes .cborseq type2" 1289 (The conversion of the encoded sequence to an array can be effected 1290 for instance by wrapping the byte string between the two bytes 0x9f 1291 and 0xff and decoding the wrapped byte string as a CBOR encoded data 1292 item.) 1294 3.8.5. Control operators .within and .and 1296 A ".and" control on a type indicates that the data item matches both 1297 that left hand side type and the type given as the right hand side. 1298 (Formally, the resulting type is the intersection of the two types 1299 given.) 1301 "type1 .and type2" 1303 A variant of the ".and" control is the ".within" control, which 1304 expresses an additional intent: the left hand side type is meant to 1305 be a subset of the right-hand-side type. 1307 "type1 .within type2" 1309 While both forms have the identical formal semantics (intersection), 1310 the intention of the ".within" form is that the right hand side gives 1311 guidance to the types allowed on the left hand side, which typically 1312 is a socket (Section 3.9): 1314 message = $message .within message-structure 1315 message-structure = [message_type, *message_option] 1316 message_type = 0..255 1317 message_option = any 1319 $message /= [3, dough: text, topping: [* text]] 1320 $message /= [4, noodles: text, sauce: text, parmesan: bool] 1321 For ".within", a tool might flag an error if type1 allows data items 1322 that are not allowed by type2. In contrast, for ".and", there is no 1323 expectation that type1 already is a subset of type2. 1325 3.8.6. Control operators .lt, .le, .gt, .ge, .eq, .ne, and .default 1327 The controls .lt, .le, .gt, .ge, .eq, .ne specify a constraint on the 1328 left hand side type to be a value less than, less than or equal, 1329 greater than, greater than or equal, equal, or not equal, to a value 1330 given as a (single-valued) right hand side type. In the present 1331 specification, the first four controls (.lt, .le, .gt, .ge) are 1332 defined only for numeric types, as these have a natural ordering 1333 relationship. 1335 speed = number .ge 0 ; unit: m/s 1337 .ne and .eq are defined both for numeric values and values of other 1338 types. If one of the values is not of a numeric type, equality is 1339 determined as follows: Text strings are equal (satisfy .eq/do not 1340 satisfy .ne) if they are byte-wise identical; the same applies for 1341 byte strings. Arrays are equal if they have the same number of 1342 elements, all of which are equal pairwise in order between the 1343 arrays. Maps are equal if they have the same number of key/value 1344 pairs, and there is pairwise equality between the key/value pairs 1345 between the two maps. Tagged values are equal if they both have the 1346 same tag and the values are equal. Values of simple types match if 1347 they are the same values. Numeric types that occur within arrays, 1348 maps, or tagged values are equal if their numeric value is equal and 1349 they are both integers or both floating point values. All other 1350 cases are not equal (e.g., comparing a text string with a byte 1351 string). 1353 A variant of the ".ne" control is the ".default" control, which 1354 expresses an additional intent: the value specified by the right- 1355 hand-side type is intended as a default value for the left hand side 1356 type given, and the implied .ne control is there to prevent this 1357 value from being sent over the wire. This control is only meaningful 1358 when the control type is used in an optional context; otherwise there 1359 would be no way to express the default value. 1361 timer = { 1362 time: uint, 1363 ? displayed-step: (number .gt 0) .default 1 1364 } 1366 3.9. Socket/Plug 1368 Both for type choices and group choices, a mechanism is defined that 1369 facilitates starting out with empty choices and assembling them 1370 later, potentially in separate files that are concatenated to build 1371 the full specification. 1373 Per convention, CDDL extension points are marked with a leading 1374 dollar sign (types) or two leading dollar signs (groups). Tools 1375 honor that convention by not raising an error if such a type or group 1376 is not defined at all; the symbol is then taken to be an empty type 1377 choice (group choice), i.e., no choice is available. 1379 tcp-header = {seq: uint, ack: uint, * $$tcp-option} 1381 ; later, in a different file 1383 $$tcp-option //= ( 1384 sack: [+(left: uint, right: uint)] 1385 ) 1387 ; and, maybe in another file 1389 $$tcp-option //= ( 1390 sack-permitted: true 1391 ) 1393 Names that start with a single "$" are "type sockets", names with a 1394 double "$$" are "group sockets". It is not an error if there is no 1395 definition for a socket at all; this then means there is no way to 1396 satisfy the rule (i.e., the choice is empty). 1398 As a convention, all definitions (plugs) for socket names must be 1399 augmentations, i.e., they must be using "/=" and "//=", respectively. 1401 To pick up the example illustrated in Figure 7, the socket/plug 1402 mechanism could be used as shown in Figure 12: 1404 PersonalData = { 1405 ? displayName: tstr, 1406 NameComponents, 1407 ? age: uint, 1408 * $$personaldata-extensions 1409 } 1411 NameComponents = ( 1412 ? firstName: tstr, 1413 ? familyName: tstr, 1414 ) 1416 ; The above already works as is. 1417 ; But then, we can add later: 1419 $$personaldata-extensions //= ( 1420 favorite-salsa: tstr, 1421 ) 1423 ; and again, somewhere else: 1425 $$personaldata-extensions //= ( 1426 shoesize: uint, 1427 ) 1429 Figure 12: Personal Data example: Using socket/plug extensibility 1431 3.10. Generics 1433 Using angle brackets, the left hand side of a rule can add formal 1434 parameters after the name being defined, as in: 1436 messages = message<"reboot", "now"> / message<"sleep", 1..100> 1437 message = {type: t, value: v} 1439 When using a generic rule, the formal parameters are bound to the 1440 actual arguments supplied (also using angle brackets), within the 1441 scope of the generic rule (as if there were a rule of the form 1442 parameter = argument). 1444 Generic rules can be used for establishing names for both types and 1445 groups. 1447 (There are some limitations to nesting of generics in the tool 1448 described in Appendix F at this time.) 1450 3.11. Operator Precedence 1452 As with any language that has multiple syntactic features such as 1453 prefix and infix operators, CDDL has operators that bind more tightly 1454 than others. This is becoming more complicated than, say, in ABNF, 1455 as CDDL has both types and groups, with operators that are specific 1456 to these concepts. Type operators (such as "/" for type choice) 1457 operate on types, while group operators (such as "//" for group 1458 choice) operate on groups. Types can simply be used in groups, but 1459 groups need to be bracketed (as arrays or maps) to become types. So, 1460 type operators naturally bind closer than group operators. 1462 For instance, in 1464 t = [group1] 1465 group1 = (a / b // c / d) 1466 a = 1 b = 2 c = 3 d = 4 1468 group1 is a group choice between the type choice of a and b and the 1469 type choice of c and d. This becomes more relevant once member keys 1470 and/or occurrences are added in: 1472 t = {group2} 1473 group2 = (? ab: a / b // cd: c / d) 1474 a = 1 b = 2 c = 3 d = 4 1476 is a group choice between the optional member "ab" of type a or b and 1477 the member "cd" of type c or d. Note that the optionality is 1478 attached to the first choice ("ab"), not to the second choice. 1480 Similarly, in 1482 t = [group3] 1483 group3 = (+ a / b / c) 1484 a = 1 b = 2 c = 3 1486 group3 is a repetition of a type choice between a, b, and c; if just 1487 a is to be repeatable, a group choice is needed to focus the 1488 occurrence: 1490 (A comment has been that this could be counter-intuitive. The 1491 specification writer is encouraged to use parentheses liberally to 1492 guide readers that are not familiar with CDDL precedence rules.) 1494 t = [group4] 1495 group4 = (+ a // b / c) 1496 a = 1 b = 2 c = 3 1497 group4 is a group choice between a repeatable a and a single b or c. 1499 In general, as with many other languages with operator precedence 1500 rules, it is best not to rely on them, but to insert parentheses for 1501 readability: 1503 t = [group4a] 1504 group4a = ((+ a) // (b / c)) 1505 a = 1 b = 2 c = 3 1507 The operator precedences, in sequence of loose to tight binding, are 1508 defined in Appendix B and summarized in Table 1. (Arities given are 1509 1 for unary prefix operators and 2 for binary infix operators.) 1511 +----------+----+---------------------------+------+ 1512 | Operator | Ar | Operates on | Prec | 1513 +----------+----+---------------------------+------+ 1514 | = | 2 | name = type, name = group | 1 | 1515 | /= | 2 | name /= type | 1 | 1516 | //= | 2 | name //= group | 1 | 1517 | // | 2 | group // group | 2 | 1518 | , | 2 | group, group | 3 | 1519 | * | 1 | * group | 4 | 1520 | N*M | 1 | N*M group | 4 | 1521 | + | 1 | + group | 4 | 1522 | ? | 1 | ? group | 4 | 1523 | => | 2 | type => type | 5 | 1524 | : | 2 | name: type | 5 | 1525 | / | 2 | type / type | 6 | 1526 | .. | 2 | type..type | 7 | 1527 | ... | 2 | type...type | 7 | 1528 | .ctrl | 2 | type .ctrl type | 7 | 1529 | & | 1 | &group | 8 | 1530 | ~ | 1 | ~type | 8 | 1531 +----------+----+---------------------------+------+ 1533 Table 1: Summary of operator precedences 1535 4. Making Use of CDDL 1537 In this section, we discuss several potential ways to employ CDDL. 1539 4.1. As a guide to a human user 1541 CDDL can be used to efficiently define the layout of CBOR data, such 1542 that a human implementer can easily see how data is supposed to be 1543 encoded. 1545 Since CDDL maps parts of the CBOR data to human readable names, tools 1546 could be built that use CDDL to provide a human friendly 1547 representation of the CBOR data, and allow them to edit such data 1548 while remaining compliant to its CDDL definition. 1550 4.2. For automated checking of CBOR data structure 1552 CDDL has been specified such that a machine can handle the CDDL 1553 definition and related CBOR data (and, thus, also JSON data). For 1554 example, a machine could use CDDL to check whether or not CBOR data 1555 is compliant to its definition. 1557 The need for thoroughness of such compliance checking depends on the 1558 application. For example, an application may decide not to check the 1559 data structure at all, and use the CDDL definition solely as a means 1560 to indicate the structure of the data to the programmer. 1562 On the other end, the application may also implement a checking 1563 mechanism that goes as far as checking that all mandatory map members 1564 are available. 1566 The matter in how far the data description must be enforced by an 1567 application is left to the designers and implementers of that 1568 application, keeping in mind related security considerations. 1570 In no case the intention is that a CDDL tool would be "writing code" 1571 for an implementation. 1573 4.3. For data analysis tools 1575 In the long run, it can be expected that more and more data will be 1576 stored using the CBOR data format. 1578 Where there is data, there is data analysis and the need to process 1579 such data automatically. CDDL can be used for such automated data 1580 processing, allowing tools to verify data, clean it, and extract 1581 particular parts of interest from it. 1583 Since CBOR is designed with constrained devices in mind, a likely use 1584 of it would be small sensors. An interesting use would thus be 1585 automated analysis of sensor data. 1587 5. Security considerations 1589 This document presents a content rules language for expressing CBOR 1590 data structures. As such, it does not bring any security issues on 1591 itself, although specifications of protocols that use CBOR naturally 1592 need security analyses when defined. General guidelines for writing 1593 security considerations are defined in 1595 Security Considerations Guidelines [RFC3552] (BCP 72). 1596 Specifications using CDDL to define CBOR structures in protocols need 1597 to follow those guidelines. Additional topics that could be 1598 considered in a security considerations section for a specification 1599 that uses CDDL to define CBOR structures include the following: 1601 o Where could the language maybe cause confusion in a way that will 1602 enable security issues? 1604 o Where a CDDL matcher is part of the implementation of a system, 1605 the security of the system ought not depend on the correctness of 1606 the CDDL specification or CDDL implementation without any further 1607 defenses in place. 1609 o Where the CDDL includes extension points, the impact of extensions 1610 on the security of the system needs to be carefully considered. 1612 Writers of CDDL specifications are strongly encouraged to value 1613 simplicity and transparency of the specification over its elegance. 1614 Keep it as simple as possible while still expressing the needed data 1615 model. 1617 A related observation about formal description techniques in general 1618 that is strongly recommended to be kept in mind by writers of CDDL 1619 specifications: Just because CDDL makes it easier to handle 1620 complexity in a specification, that does not make that complexity 1621 somehow less bad (except maybe on the level of the humans having to 1622 grasp the complex structure while reading the spec). 1624 6. IANA Considerations 1626 6.1. CDDL control operator registry 1628 IANA is requested to create a registry for control operators 1629 Section 3.8. The name of this registry is "CDDL Control Operators". 1631 Each entry in the subregistry must include the name of the control 1632 operator (by convention given with the leading dot) and a reference 1633 to its documentation. Names must be composed of the leading dot 1634 followed by a text string conforming to the production "id" in 1635 Appendix B. 1637 Initial entries in this registry are as follows: 1639 +----------+---------------+ 1640 | name | documentation | 1641 +----------+---------------+ 1642 | .size | [RFCthis] | 1643 | .bits | [RFCthis] | 1644 | .regexp | [RFCthis] | 1645 | .cbor | [RFCthis] | 1646 | .cborseq | [RFCthis] | 1647 | .within | [RFCthis] | 1648 | .and | [RFCthis] | 1649 | .lt | [RFCthis] | 1650 | .le | [RFCthis] | 1651 | .gt | [RFCthis] | 1652 | .ge | [RFCthis] | 1653 | .eq | [RFCthis] | 1654 | .ne | [RFCthis] | 1655 | .default | [RFCthis] | 1656 +----------+---------------+ 1658 All other control operator names are Unassigned. 1660 The IANA policy for additions to this registry is "Specification 1661 Required" as defined in [RFC8126] (which involves an Expert Review) 1662 for names that do not include an internal dot, and "IETF Review" for 1663 names that do include an internal dot. The Expert is specifically 1664 instructed that other Standards Development Organizations (SDOs) may 1665 want to define control operators that are specific to their fields 1666 (e.g., based on a binary syntax already in use at the SDO); the 1667 review process should strive to facilitate such an undertaking. 1669 7. References 1671 7.1. Normative References 1673 [ISO6093] ISO, "Information processing -- Representation of 1674 numerical values in character strings for information 1675 interchange", ISO 6093, 1985. 1677 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1678 Requirement Levels", BCP 14, RFC 2119, 1679 DOI 10.17487/RFC2119, March 1997, 1680 . 1682 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 1683 Text on Security Considerations", BCP 72, RFC 3552, 1684 DOI 10.17487/RFC3552, July 2003, 1685 . 1687 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1688 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1689 2003, . 1691 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1692 Specifications: ABNF", STD 68, RFC 5234, 1693 DOI 10.17487/RFC5234, January 2008, 1694 . 1696 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1697 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1698 October 2013, . 1700 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 1701 DOI 10.17487/RFC7493, March 2015, 1702 . 1704 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1705 Writing an IANA Considerations Section in RFCs", BCP 26, 1706 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1707 . 1709 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1710 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1711 May 2017, . 1713 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1714 Interchange Format", STD 90, RFC 8259, 1715 DOI 10.17487/RFC8259, December 2017, 1716 . 1718 [W3C.REC-xmlschema-2-20041028] 1719 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 1720 Second Edition", World Wide Web Consortium Recommendation 1721 REC-xmlschema-2-20041028, October 2004, 1722 . 1724 7.2. Informative References 1726 [I-D.bormann-cbor-cddl-freezer] 1727 Bormann, C., "A feature freezer for the Concise Data 1728 Definition Language (CDDL)", draft-bormann-cbor-cddl- 1729 freezer-01 (work in progress), August 2018. 1731 [I-D.ietf-anima-grasp] 1732 Bormann, C., Carpenter, B., and B. Liu, "A Generic 1733 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 1734 grasp-15 (work in progress), July 2017. 1736 [I-D.newton-json-content-rules] 1737 Newton, A. and P. Cordell, "A Language for Rules 1738 Describing JSON Content", draft-newton-json-content- 1739 rules-09 (work in progress), September 2017. 1741 [PEG] Ford, B., "Parsing expression grammars", Proceedings of 1742 the 31st ACM SIGPLAN-SIGACT symposium on Principles of 1743 programming languages - POPL '04, 1744 DOI 10.1145/964001.964011, 2004. 1746 [RELAXNG] ISO/IEC, "Information technology -- Document Schema 1747 Definition Language (DSDL) -- Part 2: Regular-grammar- 1748 based validation -- RELAX NG", ISO/IEC 19757-2, December 1749 2008. 1751 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1752 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1753 . 1755 [RFC7071] Borenstein, N. and M. Kucherawy, "A Media Type for 1756 Reputation Interchange", RFC 7071, DOI 10.17487/RFC7071, 1757 November 2013, . 1759 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1760 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1761 . 1763 [RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network 1764 Interconnection (CDNI) Control Interface / Triggers", 1765 RFC 8007, DOI 10.17487/RFC8007, December 2016, 1766 . 1768 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1769 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1770 . 1772 [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 1773 Bormann, "Sensor Measurement Lists (SenML)", RFC 8428, 1774 DOI 10.17487/RFC8428, August 2018, 1775 . 1777 7.3. URIs 1779 [1] https://github.com/cabo/cbor-diag 1781 Appendix A. Examples 1783 This appendix is for information only. 1785 This section contains a few examples of structures defined using 1786 CDDL. 1788 The theme for the first example is taken from [RFC7071], which 1789 defines certain JSON structures in English. For a similar example, 1790 it may also be of interest to examine Appendix A of [RFC8007], which 1791 contains a CDDL definition for a JSON structure defined in the main 1792 body of the RFC. 1794 The second subsection in this appendix translates examples from 1795 [I-D.newton-json-content-rules] into CDDL. 1797 These examples all happen to describe data that is interchanged in 1798 JSON. Examples for CDDL definitions of data that is interchanged in 1799 CBOR can be found in [RFC8152], [I-D.ietf-anima-grasp], or [RFC8428]. 1801 A.1. RFC 7071 1803 [RFC7071] defines the Reputon structure for JSON using somewhat 1804 formalized English text. Here is a (somewhat verbose) equivalent 1805 definition using the same terms, but notated in CDDL: 1807 reputation-object = { 1808 reputation-context, 1809 reputon-list 1810 } 1812 reputation-context = ( 1813 application: text 1814 ) 1816 reputon-list = ( 1817 reputons: reputon-array 1818 ) 1820 reputon-array = [* reputon] 1822 reputon = { 1823 rater-value, 1824 assertion-value, 1825 rated-value, 1826 rating-value, 1827 ? conf-value, 1828 ? normal-value, 1829 ? sample-value, 1830 ? gen-value, 1831 ? expire-value, 1832 * ext-value, 1833 } 1835 rater-value = ( rater: text ) 1836 assertion-value = ( assertion: text ) 1837 rated-value = ( rated: text ) 1838 rating-value = ( rating: float16 ) 1839 conf-value = ( confidence: float16 ) 1840 normal-value = ( normal-rating: float16 ) 1841 sample-value = ( sample-size: uint ) 1842 gen-value = ( generated: uint ) 1843 expire-value = ( expires: uint ) 1844 ext-value = ( text => any ) 1846 An equivalent, more compact form of this example would be: 1848 reputation-object = { 1849 application: text 1850 reputons: [* reputon] 1851 } 1853 reputon = { 1854 rater: text 1855 assertion: text 1856 rated: text 1857 rating: float16 1858 ? confidence: float16 1859 ? normal-rating: float16 1860 ? sample-size: uint 1861 ? generated: uint 1862 ? expires: uint 1863 * text => any 1864 } 1866 Note how this rather clearly delineates the structure somewhat 1867 shrouded by so many words in section 6.2.2. of [RFC7071]. Also, this 1868 definition makes it clear that several ext-values are allowed (by 1869 definition with different member names); RFC 7071 could be read to 1870 forbid the repetition of ext-value ("A specific reputon-element MUST 1871 NOT appear more than once" is ambiguous.) 1873 The CDDL tool reported on in Appendix F (which hasn't quite been 1874 trained for polite conversation) says: 1876 { 1877 "application": "tridentiferous", 1878 "reputons": [ 1879 { 1880 "rater": "loamily", 1881 "assertion": "Dasyprocta", 1882 "rated": "uncommensurableness", 1883 "rating": 0.05055809746548934, 1884 "confidence": 0.7484706448605812, 1885 "normal-rating": 0.8677887734049299, 1886 "sample-size": 4059, 1887 "expires": 3969, 1888 "bearer": "nitty", 1889 "faucal": "postulnar", 1890 "naturalism": "sarcotic" 1891 }, 1892 { 1893 "rater": "precreed", 1894 "assertion": "xanthosis", 1895 "rated": "balsamy", 1896 "rating": 0.36091333590593955, 1897 "confidence": 0.3700759808403371, 1898 "sample-size": 3904 1899 }, 1900 { 1901 "rater": "urinosexual", 1902 "assertion": "malacostracous", 1903 "rated": "arenariae", 1904 "rating": 0.9210673488013762, 1905 "normal-rating": 0.4778762617112776, 1906 "sample-size": 4428, 1907 "generated": 3294, 1908 "backfurrow": "enterable", 1909 "fruitgrower": "flannelflower" 1910 }, 1911 { 1912 "rater": "pedologistically", 1913 "assertion": "unmetaphysical", 1914 "rated": "elocutionist", 1915 "rating": 0.42073613384304287, 1916 "misimagine": "retinaculum", 1917 "snobbish": "contradict", 1918 "Bosporanic": "periostotomy", 1919 "dayworker": "intragyral" 1920 } 1921 ] 1922 } 1924 A.2. Examples from JSON Content Rules 1926 Although JSON Content Rules [I-D.newton-json-content-rules] seems to 1927 address a more general problem than CDDL, it is still a worthwhile 1928 resource to explore for examples (beyond all the inspiration the 1929 format itself has had for CDDL). 1931 Figure 2 of the JCR I-D looks very similar, if slightly less noisy, 1932 in CDDL: 1934 root = [2*2 { 1935 precision: text, 1936 Latitude: float, 1937 Longitude: float, 1938 Address: text, 1939 City: text, 1940 State: text, 1941 Zip: text, 1942 Country: text 1943 }] 1945 Figure 13: JCR, Figure 2, in CDDL 1947 Apart from the lack of a need to quote the member names, text strings 1948 are called "text" or "tstr" in CDDL ("string" would be ambiguous as 1949 CBOR also provides byte strings). 1951 The CDDL tool reported on in Appendix F creates the below example 1952 instance for this: 1954 [{"precision": "pyrosphere", "Latitude": 0.5399712314350172, 1955 "Longitude": 0.5157523963028087, "Address": "resow", 1956 "City": "problemwise", "State": "martyrlike", "Zip": "preprove", 1957 "Country": "Pace"}, 1958 {"precision": "unrigging", "Latitude": 0.10422704368372193, 1959 "Longitude": 0.6279808663725834, "Address": "picturedom", 1960 "City": "decipherability", "State": "autometry", "Zip": "pout", 1961 "Country": "wimple"}] 1963 Figure 4 of the JCR I-D in CDDL: 1965 root = { image } 1967 image = ( 1968 Image: { 1969 size, 1970 Title: text, 1971 thumbnail, 1972 IDs: [* int] 1973 } 1974 ) 1976 size = ( 1977 Width: 0..1280 1978 Height: 0..1024 1979 ) 1981 thumbnail = ( 1982 Thumbnail: { 1983 size, 1984 Url: ~uri 1985 } 1986 ) 1988 This shows how the group concept can be used to keep related elements 1989 (here: width, height) together, and to emulate the JCR style of 1990 specification. (It also shows referencing a type by unwrapping a tag 1991 from the prelude, "uri" - this could be done differently.) The more 1992 compact form of Figure 5 of the JCR I-D could be emulated like this: 1994 root = { 1995 Image: { 1996 size, Title: text, 1997 Thumbnail: { size, Url: ~uri }, 1998 IDs: [* int] 1999 } 2000 } 2002 size = ( 2003 Width: 0..1280, 2004 Height: 0..1024, 2005 ) 2007 The CDDL tool reported on in Appendix F creates the below example 2008 instance for this: 2010 {"Image": {"Width": 566, "Height": 516, "Title": "leisterer", 2011 "Thumbnail": {"Width": 1111, "Height": 176, "Url": 32("scrog")}, 2012 "IDs": []}} 2014 Appendix B. ABNF grammar 2016 This appendix is normative. 2018 The following is a formal definition of the CDDL syntax in Augmented 2019 Backus-Naur Form (ABNF, [RFC5234]). 2021 cddl = S 1*(rule S) 2022 rule = typename [genericparm] S assignt S type 2023 / groupname [genericparm] S assigng S grpent 2025 typename = id 2026 groupname = id 2028 assignt = "=" / "/=" 2029 assigng = "=" / "//=" 2031 genericparm = "<" S id S *("," S id S ) ">" 2032 genericarg = "<" S type1 S *("," S type1 S ) ">" 2034 type = type1 *(S "/" S type1) 2036 type1 = type2 [S (rangeop / ctlop) S type2] 2038 type2 = value 2039 / typename [genericarg] 2040 / "(" S type S ")" 2041 / "{" S group S "}" 2042 / "[" S group S "]" 2043 / "~" S typename [genericarg] 2044 / "&" S "(" S group S ")" 2045 / "&" S groupname [genericarg] 2046 / "#" "6" ["." uint] "(" S type S ")" ; note no space! 2047 / "#" DIGIT ["." uint] ; major/ai 2048 / "#" ; any 2050 rangeop = "..." / ".." 2052 ctlop = "." id 2054 group = grpchoice *(S "//" S grpchoice) 2056 grpchoice = *(grpent optcom) 2058 grpent = [occur S] [memberkey S] type 2059 / [occur S] groupname [genericarg] ; preempted by above 2060 / [occur S] "(" S group S ")" 2062 memberkey = type1 S ["^" S] "=>" 2063 / bareword S ":" 2064 / value S ":" 2066 bareword = id 2068 optcom = S ["," S] 2070 occur = [uint] "*" [uint] 2071 / "+" 2072 / "?" 2074 uint = DIGIT1 *DIGIT 2075 / "0x" 1*HEXDIG 2076 / "0b" 1*BINDIG 2077 / "0" 2079 value = number 2080 / text 2081 / bytes 2083 int = ["-"] uint 2085 ; This is a float if it has fraction or exponent; int otherwise 2086 number = hexfloat / (int ["." fraction] ["e" exponent ]) 2087 hexfloat = "0x" 1*HEXDIG ["." 1*HEXDIG] "p" exponent 2088 fraction = 1*DIGIT 2089 exponent = ["+"/"-"] 1*DIGIT 2091 text = %x22 *SCHAR %x22 2092 SCHAR = %x20-21 / %x23-5B / %x5D-10FFFD / SESC 2093 SESC = "\" %x20-10FFFD 2095 bytes = [bsqual] %x27 *BCHAR %x27 2096 BCHAR = %x20-26 / %x28-5B / %x5D-10FFFD / SESC / CRLF 2097 bsqual = "h" / "b64" 2099 id = EALPHA *(*("-" / ".") (EALPHA / DIGIT)) 2100 ALPHA = %x41-5A / %x61-7A 2101 EALPHA = ALPHA / "@" / "_" / "$" 2102 DIGIT = %x30-39 2103 DIGIT1 = %x31-39 2104 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 2105 BINDIG = %x30-31 2107 S = *WS 2108 WS = SP / NL 2109 SP = %x20 2110 NL = COMMENT / CRLF 2111 COMMENT = ";" *PCHAR CRLF 2112 PCHAR = %x20-10FFFD 2113 CRLF = %x0A / %x0D.0A 2115 Figure 14: CDDL ABNF 2117 Note that this ABNF does not attempt to reflect the detailed rules of 2118 what can be in a prefixed byte string. 2120 Appendix C. Matching rules 2122 This appendix is normative. 2124 In this appendix, we go through the ABNF syntax rules defined in 2125 Appendix B and briefly describe the matching semantics of each 2126 syntactic feature. In this context, an instance (data item) 2127 "matches" a CDDL specification if it is allowed by the CDDL 2128 specification; this is then broken down to parts of specifications 2129 (type and group expressions) and parts of instances (data items). 2131 cddl = S 1*(rule S) 2133 A CDDL specification is a sequence of one or more rules. Each rule 2134 gives a name to a right hand side expression, either a CDDL type or a 2135 CDDL group. Rule names can be used in the rule itself and/or other 2136 rules (and tools can output warnings if that is not the case). The 2137 order of the rules is significant only in two cases: 2139 1. The first rule defines the semantics of the entire specification; 2140 hence, there is no need to give that root rule a special name or 2141 special syntax in the language (as, e.g., with "start" in Relax- 2142 NG); its name can be therefore chosen to be descriptive. (As 2143 with all other rule names, the name of the initial rule may be 2144 used in itself or in other rules). 2146 2. Where a rule contributes to a type or group choice (using "/=" or 2147 "//="), that choice is populated in the order the rules are 2148 given; see below. 2150 rule = typename [genericparm] S assignt S type 2151 / groupname [genericparm] S assigng S grpent 2153 typename = id 2154 groupname = id 2156 A rule defines a name for a type expression (production "type") or 2157 for a group expression (production "grpent"), with the intention that 2158 the semantics does not change when the name is replaced by its 2159 (parenthesized if needed) definition. Note that whether the name 2160 defined by a rule stands for a type or a group isn't always 2161 determined by syntax alone: e.g., "a = b" can make "a" a type if "b" 2162 is one, or a group if "b" is one. More subtly, in "a = (b)", "a" may 2163 be used as a type if "b" is a type, or as a group both when "b" is a 2164 group and when "b" is a type (a good convention to make the latter 2165 case stand out to the human reader is to write "a = (b,)"). (Note 2166 that the same dual meaning of parentheses applies within an 2167 expression, but often can be resolved by the context of the 2168 parenthesized expression. On the more general point, it may not be 2169 clear immediately either whether "b" stands for a group or a type -- 2170 this semantic processing may need to span several levels of rule 2171 definitions before a determination can be made.) 2173 assignt = "=" / "/=" 2174 assigng = "=" / "//=" 2176 A plain equals sign defines the rule name as the equivalent of the 2177 expression to the right. A "/=" or "//=" extends a named type or a 2178 group by additional choices; a number of these could be replaced by 2179 collecting all the right hand sides and creating a single rule with a 2180 type choice or a group choice built from the right hand sides in the 2181 order of the rules given. (It is not an error to extend a rule name 2182 that has not yet been defined; this makes the right hand side the 2183 first entry in the choice being created.) 2185 genericparm = "<" S id S *("," S id S ) ">" 2186 genericarg = "<" S type1 S *("," S type1 S ) ">" 2188 Rule names can have generic parameters, which cause temporary 2189 assignments within the right hand sides to the parameter names from 2190 the arguments given when citing the rule name. 2192 type = type1 *(S "/" S type1) 2194 A type can be given as a choice between one or more types. The 2195 choice matches a data item if the data item matches any one of the 2196 types given in the choice. The choice uses Parsing Expression 2197 Grammar [PEG] semantics: The first choice that matches wins. (As a 2198 result, the order of rules that contribute to a single rule name can 2199 very well matter.) 2201 type1 = type2 [S (rangeop / ctlop) S type2] 2203 Two types can be combined with a range operator (which see below) or 2204 a control operator (see Section 3.8). 2206 type2 = value 2208 A type can be just a single value (such as 1 or "icecream" or 2209 h'0815'), which matches only a data item with that specific value (no 2210 conversions defined), 2212 / typename [genericarg] 2214 or be defined by a rule giving a meaning to a name (possibly after 2215 supplying generic arguments as required by the generic parameters), 2217 / "(" S type S ")" 2219 or be defined in a parenthesized type expression (parentheses may be 2220 necessary to override some operator precedence), or 2222 / "{" S group S "}" 2224 a map expression, which matches a valid CBOR map the key/value pairs 2225 of which can be ordered in such a way that the resulting sequence 2226 matches the group expression, or 2228 / "[" S group S "]" 2230 an array expression, which matches a CBOR array the elements of 2231 which, when taken as values and complemented by a wildcard (matches 2232 anything) key each, match the group, or 2234 / "~" S typename [genericarg] 2236 an "unwrapped" group (see Section 3.7), which matches the group 2237 inside a type defined as a map or an array by wrapping the group, or 2239 / "&" S "(" S group S ")" 2240 / "&" S groupname [genericarg] 2242 an enumeration expression, which matches any a value that is within 2243 the set of values that the values of the group given can take, or 2245 / "#" "6" ["." uint] "(" S type S ")" ; note no space! 2247 a tagged data item, tagged with the "uint" given and containing the 2248 type given as the tagged value, or 2250 / "#" DIGIT ["." uint] ; major/ai 2252 a data item of a major type (given by the DIGIT), optionally 2253 constrained to the additional information given by the uint, or 2254 / "#" ; any 2256 any data item. 2258 rangeop = "..." / ".." 2260 A range operator can be used to join two type expressions that stand 2261 for either two integer values or two floating point values; it 2262 matches any value that is between the two values, where the first 2263 value is always included in the matching set and the second value is 2264 included for ".." and excluded for "...". 2266 ctlop = "." id 2268 A control operator ties a _target_ type to a _controller_ type as 2269 defined in Section 3.8. Note that control operators are an extension 2270 point for CDDL; additional documents may want to define additional 2271 control operators. 2273 group = grpchoice *(S "//" S grpchoice) 2275 A group matches any sequence of key/value pairs that matches any of 2276 the choices given (again using Parsing Expression Grammar semantics). 2278 grpchoice = *(grpent optcom) 2280 Each of the component groups is given as a sequence of group entries. 2281 For a match, the sequence of key/value pairs given needs to match the 2282 sequence of group entries in the sequence given. 2284 grpent = [occur S] [memberkey S] type 2286 A group entry can be given by a value type, which needs to be matched 2287 by the value part of a single element, and optionally a memberkey 2288 type, which needs to be matched by the key part of the element, if 2289 the memberkey is given. If the memberkey is not given, the entry can 2290 only be used for matching arrays, not for maps. (See below how that 2291 is modified by the occurrence indicator.) 2293 / [occur S] groupname [genericarg] ; preempted by above 2295 A group entry can be built from a named group, or 2297 / [occur S] "(" S group S ")" 2299 from a parenthesized group, again with a possible occurrence 2300 indicator. 2302 memberkey = type1 S ["^" S] "=>" 2303 / bareword S ":" 2304 / value S ":" 2306 Key types can be given by a type expression, a bareword (which stands 2307 for a type that just contains a string value created from this 2308 bareword), or a value (which stands for a type that just contains 2309 this value). A key value matches its key type if the key value is a 2310 member of the key type, unless a cut preceding it in the group 2311 applies (see Section 3.5.4 how map matching is influenced by the 2312 presence of the cuts denoted by "^" or ":" in previous entries). 2314 bareword = id 2316 A bareword is an alternative way to write a type with a single text 2317 string value; it can only be used in the syntactic context given 2318 above. 2320 optcom = S ["," S] 2322 (Optional commas do not influence the matching.) 2324 occur = [uint] "*" [uint] 2325 / "+" 2326 / "?" 2328 An occurrence indicator modifies the group given to its right by 2329 requiring the group to match the sequence to be matched exactly for a 2330 certain number of times (see Section 3.2) in sequence, i.e. it acts 2331 as a (possibly infinite) group choice that contains choices with the 2332 group repeated each of the occurrences times. 2334 The rest of the ABNF describes syntax for value notation that should 2335 be familiar from programming languages, with the possible exception 2336 of h'..' and b64'..' for byte strings, as well as syntactic elements 2337 such as comments and line ends. 2339 Appendix D. Standard Prelude 2341 This appendix is normative. 2343 The following prelude is automatically added to each CDDL file. 2344 (Note that technically, it is a postlude, as it does not disturb the 2345 selection of the first rule as the root of the definition.) 2346 any = # 2348 uint = #0 2349 nint = #1 2350 int = uint / nint 2352 bstr = #2 2353 bytes = bstr 2354 tstr = #3 2355 text = tstr 2357 tdate = #6.0(tstr) 2358 time = #6.1(number) 2359 number = int / float 2360 biguint = #6.2(bstr) 2361 bignint = #6.3(bstr) 2362 bigint = biguint / bignint 2363 integer = int / bigint 2364 unsigned = uint / biguint 2365 decfrac = #6.4([e10: int, m: integer]) 2366 bigfloat = #6.5([e2: int, m: integer]) 2367 eb64url = #6.21(any) 2368 eb64legacy = #6.22(any) 2369 eb16 = #6.23(any) 2370 encoded-cbor = #6.24(bstr) 2371 uri = #6.32(tstr) 2372 b64url = #6.33(tstr) 2373 b64legacy = #6.34(tstr) 2374 regexp = #6.35(tstr) 2375 mime-message = #6.36(tstr) 2376 cbor-any = #6.55799(any) 2378 float16 = #7.25 2379 float32 = #7.26 2380 float64 = #7.27 2381 float16-32 = float16 / float32 2382 float32-64 = float32 / float64 2383 float = float16-32 / float64 2385 false = #7.20 2386 true = #7.21 2387 bool = false / true 2388 nil = #7.22 2389 null = nil 2390 undefined = #7.23 2392 Figure 15: CDDL Prelude 2394 Note that the prelude is deemed to be fixed. This means, for 2395 instance, that additional tags beyond [RFC7049], as registered, need 2396 to be defined in each CDDL file that is using them. 2398 A common stumbling point is that the prelude does not define a type 2399 "string". CBOR has byte strings ("bytes" in the prelude) and text 2400 strings ("text"), so a type that is simply called "string" would be 2401 ambiguous. 2403 Appendix E. Use with JSON 2405 This appendix is normative. 2407 The JSON generic data model (implicit in [RFC8259]) is a subset of 2408 the generic data model of CBOR. So one can use CDDL with JSON by 2409 limiting oneself to what can be represented in JSON. Roughly 2410 speaking, this means leaving out byte strings, tags, and simple 2411 values other than "false", "true", and "null", leading to the 2412 following limited prelude: 2414 any = # 2416 uint = #0 2417 nint = #1 2418 int = uint / nint 2420 tstr = #3 2421 text = tstr 2423 number = int / float 2425 float16 = #7.25 2426 float32 = #7.26 2427 float64 = #7.27 2428 float16-32 = float16 / float32 2429 float32-64 = float32 / float64 2430 float = float16-32 / float64 2432 false = #7.20 2433 true = #7.21 2434 bool = false / true 2435 nil = #7.22 2436 null = nil 2438 Figure 16: JSON compatible subset of CDDL Prelude 2440 (The major types given here do not have a direct meaning in JSON, but 2441 they can be interpreted as CBOR major types translated through 2442 Section 4 of [RFC7049].) 2444 There are a few fine points in using CDDL with JSON. First, JSON 2445 does not distinguish between integers and floating point numbers; 2446 there is only one kind of number (which may happen to be integral). 2447 In this context, specifying a type as "uint", "nint" or "int" then 2448 becomes a predicate that the number be integral. As an example, this 2449 means that the following JSON numbers are all matching "uint": 2451 10 10.0 1e1 1.0e1 100e-1 2453 (The fact that these are all integers may be surprising to users 2454 accustomed to the long tradition in programming languages of using 2455 decimal points or exponents in a number to indicate a floating point 2456 literal.) 2458 CDDL distinguishes the various CBOR number types, but there is only 2459 one number type in JSON. The effect of specifying a floating point 2460 precision (float16/float32/float64) is only to restrict the set of 2461 permissible values to those expressible with binary16/binary32/ 2462 binary64; this is unlikely to be very useful when using CDDL for 2463 specifying JSON data structures. 2465 Fundamentally, the number system of JSON itself is based on decimal 2466 numbers and decimal fractions and does not have limits to its 2467 precision or range. In practice, JSON numbers are often parsed into 2468 a number type that is called float64 here, creating a number of 2469 limitations to the generic data model [RFC7493]. In particular, this 2470 means that integers can only be expressed with interoperable 2471 exactness when they lie in the range [-(2**53)+1, (2**53)-1] -- a 2472 smaller range than that covered by CDDL "int". 2474 JSON applications that want to stay compatible with I-JSON 2475 ([RFC7493], "Internet JSON") therefore may want to define integer 2476 types with more limited ranges, such as in Figure 17. Note that the 2477 types given here are not part of the prelude; they need to be copied 2478 into the CDDL specification if needed. 2480 ij-uint = 0..9007199254740991 2481 ij-nint = -9007199254740991..-1 2482 ij-int = -9007199254740991..9007199254740991 2484 Figure 17: I-JSON types for CDDL (not part of prelude) 2486 JSON applications that do not need to stay compatible with I-JSON and 2487 that actually may need to go beyond the 64-bit unsigned and negative 2488 integers supported by "int" (= "uint"/"nint") may want to use the 2489 following additional types from the standard prelude, which are 2490 expressed in terms of tags but can straightforwardly be mapped into 2491 JSON (but not I-JSON) numbers: 2493 biguint = #6.2(bstr) 2494 bignint = #6.3(bstr) 2495 bigint = biguint / bignint 2496 integer = int / bigint 2497 unsigned = uint / biguint 2499 CDDL at this point does not have a way to express the unlimited 2500 floating point precision that is theoretically possible with JSON; at 2501 the time of writing, this is rarely used in protocols in practice. 2503 Note that a data model described in CDDL is always restricted by what 2504 can be expressed in the serialization; e.g., floating point values 2505 such as NaN (not a number) and the infinities cannot be represented 2506 in JSON even if they are allowed in the CDDL generic data model. 2508 Appendix F. A CDDL tool 2510 This appendix is for information only. 2512 A rough CDDL tool is available. For CDDL specifications, it can 2513 check the syntax, generate one or more instances (expressed in CBOR 2514 diagnostic notation or in pretty-printed JSON), and validate an 2515 existing instance against the specification: 2517 Usage: 2518 cddl spec.cddl generate [n] 2519 cddl spec.cddl json-generate [n] 2520 cddl spec.cddl validate instance.cbor 2521 cddl spec.cddl validate instance.json 2523 Figure 18: CDDL tool usage 2525 Install on a system with a modern Ruby via: 2527 gem install cddl 2529 Figure 19: CDDL tool installation 2531 The accompanying CBOR diagnostic tools (which are automatically 2532 installed by the above) are described in https://github.com/cabo/ 2533 cbor-diag [1]; they can be used to convert between binary CBOR, a 2534 pretty-printed form of that, CBOR diagnostic notation, JSON, and 2535 YAML. 2537 Appendix G. Extended Diagnostic Notation 2539 This appendix is normative. 2541 Section 6 of [RFC7049] defines a "diagnostic notation" in order to be 2542 able to converse about CBOR data items without having to resort to 2543 binary data. Diagnostic notation is based on JSON, with extensions 2544 for representing CBOR constructs such as binary data and tags. 2546 (Standardizing this together with the actual interchange format does 2547 not serve to create another interchange format, but enables the use 2548 of a shared diagnostic notation in tools for and documents about 2549 CBOR.) 2551 This section discusses a few extensions to the diagnostic notation 2552 that have turned out to be useful since RFC 7049 was written. We 2553 refer to the result as extended diagnostic notation (EDN). 2555 G.1. White space in byte string notation 2557 Examples often benefit from some white space (spaces, line breaks) in 2558 byte strings. In extended diagnostic notation, white space is 2559 ignored in prefixed byte strings; for instance, the following are 2560 equivalent: 2562 h'48656c6c6f20776f726c64' 2563 h'48 65 6c 6c 6f 20 77 6f 72 6c 64' 2564 h'4 86 56c 6c6f 2565 20776 f726c64' 2567 G.2. Text in byte string notation 2569 Diagnostic notation notates Byte strings in one of the [RFC4648] base 2570 encodings,, enclosed in single quotes, prefixed by >h< for base16, 2571 >b32< for base32, >h32< for base32hex, >b64< for base64 or base64url. 2572 Quite often, byte strings carry bytes that are meaningfully 2573 interpreted as UTF-8 text. Extended Diagnostic Notation allows the 2574 use of single quotes without a prefix to express byte strings with 2575 UTF-8 text; for instance, the following are equivalent: 2577 'hello world' 2578 h'68656c6c6f20776f726c64' 2580 The escaping rules of JSON strings are applied equivalently for text- 2581 based byte strings, e.g., \ stands for a single backslash and ' 2582 stands for a single quote. White space is included literally, i.e., 2583 the previous section does not apply to text-based byte strings. 2585 G.3. Embedded CBOR and CBOR sequences in byte strings 2587 Where a byte string is to carry an embedded CBOR-encoded item, or 2588 more generally a sequence of zero or more such items, the diagnostic 2589 notation for these zero or more CBOR data items, separated by 2590 commata, can be enclosed in << and >> to notate the byte string 2591 resulting from encoding the data items and concatenating the result. 2592 For instance, each pair of columns in the following are equivalent: 2594 <<1>> h'01' 2595 <<1, 2>> h'0102' 2596 <<"foo", null>> h'63666F6FF6' 2597 <<>> h'' 2599 G.4. Concatenated Strings 2601 While the ability to include white space enables line-breaking of 2602 encoded byte strings, a mechanism is needed to be able to include 2603 text strings as well as byte strings in direct UTF-8 representation 2604 into line-based documents (such as RFCs and source code). 2606 We extend the diagnostic notation by allowing multiple text strings 2607 or multiple byte strings to be notated separated by white space, 2608 these are then concatenated into a single text or byte string, 2609 respectively. Text strings and byte strings do not mix within such a 2610 concatenation, except that byte string notation can be used inside a 2611 sequence of concatenated text string notation to encode characters 2612 that may be better represented in an encoded way. The following four 2613 values are equivalent: 2615 "Hello world" 2616 "Hello " "world" 2617 "Hello" h'20' "world" 2618 "" h'48656c6c6f20776f726c64' "" 2620 Similarly, the following byte string values are equivalent 2622 'Hello world' 2623 'Hello ' 'world' 2624 'Hello ' h'776f726c64' 2625 'Hello' h'20' 'world' 2626 '' h'48656c6c6f20776f726c64' '' b64'' 2627 h'4 86 56c 6c6f' h' 20776 f726c64' 2629 (Note that the approach of separating by whitespace, while familiar 2630 from the C language, requires some attention - a single comma makes a 2631 big difference here.) 2633 G.5. Hexadecimal, octal, and binary numbers 2635 In addition to JSON's decimal numbers, EDN provides hexadecimal, 2636 octal and binary numbers in the usual C-language notation (octal with 2637 0o prefix present only). 2639 The following are equivalent: 2641 4711 2642 0x1267 2643 0o11147 2644 0b1001001100111 2646 As are: 2648 1.5 2649 0x1.8p0 2650 0x18p-4 2652 G.6. Comments 2654 Longer pieces of diagnostic notation may benefit from comments. JSON 2655 famously does not provide for comments, and basic RFC 7049 diagnostic 2656 notation inherits this property. 2658 In extended diagnostic notation, comments can be included, delimited 2659 by slashes ("/"). Any text within and including a pair of slashes is 2660 considered a comment. 2662 Comments are considered white space. Hence, they are allowed in 2663 prefixed byte strings; for instance, the following are equivalent: 2665 h'68656c6c6f20776f726c64' 2666 h'68 65 6c /doubled l!/ 6c 6f /hello/ 2667 20 /space/ 2668 77 6f 72 6c 64' /world/ 2670 This can be used to annotate a CBOR structure as in: 2672 /grasp-message/ [/M_DISCOVERY/ 1, /session-id/ 10584416, 2673 /objective/ [/objective-name/ "opsonize", 2674 /D, N, S/ 7, /loop-count/ 105]] 2676 (There are currently no end-of-line comments. If we want to add 2677 them, "//" sounds like a reasonable delimiter given that we already 2678 use slashes for comments, but we also could go e.g. for "#".) 2680 Contributors 2682 CDDL was originally conceived by Bert Greevenbosch, who also wrote 2683 the original five versions of this document. 2685 Acknowledgements 2687 Inspiration was taken from the C and Pascal languages, MPEG's 2688 conventions for describing structures in the ISO base media file 2689 format, Relax-NG and its compact syntax [RELAXNG], and in particular 2690 from Andrew Lee Newton's "JSON Content Rules" 2691 [I-D.newton-json-content-rules]. 2693 Lots of highly useful feedback came from members of the IETF CBOR WG, 2694 in particular Ari Keraenen, Brian Carpenter, Burt Harris, Jeffrey 2695 Yasskin, Jim Hague, Jim Schaad, Joe Hildebrand, Max Pritikin, Michael 2696 Richardson, Pete Cordell, Sean Leonard, and Yaron Sheffer. Also, 2697 Francesca Palombini and Joe volunteered to chair the WG when it was 2698 created, providing the framework for generating and processing this 2699 feedback; with Barry Leiba having taken over from Joe since. Chris 2700 Lonvick and Ines Robles provided additional reviews during IESG 2701 processing, and Alexey Melnikov steered the process as the 2702 responsible area director. 2704 The CDDL tool reported on in Appendix F was written by Carsten 2705 Bormann, building on previous work by Troy Heninger and Tom Lord. 2707 Authors' Addresses 2709 Henk Birkholz 2710 Fraunhofer SIT 2711 Rheinstrasse 75 2712 Darmstadt 64295 2713 Germany 2715 Email: henk.birkholz@sit.fraunhofer.de 2717 Christoph Vigano 2718 Universitaet Bremen 2720 Email: christoph.vigano@uni-bremen.de 2721 Carsten Bormann 2722 Universitaet Bremen TZI 2723 Bibliothekstr. 1 2724 Bremen D-28359 2725 Germany 2727 Phone: +49-421-218-63921 2728 Email: cabo@tzi.org