idnits 2.17.1 draft-greevenbosch-appsawg-cbor-cddl-03.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 (September 16, 2014) is 3509 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '4' on line 201 -- Looks like a reference, but probably isn't: '2' on line 486 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Greevenbosch 3 Internet-Draft Huawei Technologies 4 Intended status: Informational C. Vigano 5 Expires: March 20, 2015 University of Bremen 6 September 16, 2014 8 CBOR data definition language: a notational convention to express CBOR 9 data structures. 10 draft-greevenbosch-appsawg-cbor-cddl-03 12 Abstract 14 This document proposes a notational convention to express CBOR data 15 structures. Its main goal is to make it easy to express message 16 structures for protocols that use CBOR. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on March 20, 2015. 35 Copyright Notice 37 Copyright (c) 2014 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 3 53 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 4. Notational conventions . . . . . . . . . . . . . . . . . . . . 6 56 4.1. General conventions . . . . . . . . . . . . . . . . . . . 6 57 4.2. Keywords for primitive datatypes . . . . . . . . . . . . . 6 58 4.3. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 4.4. Structures . . . . . . . . . . . . . . . . . . . . . . . . 7 60 4.5. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 4.6. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 4.7. Optional variables . . . . . . . . . . . . . . . . . . . . 10 63 5. Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 64 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 65 6.1. Moves in a computer game . . . . . . . . . . . . . . . . . 14 66 6.2. Fruit . . . . . . . . . . . . . . . . . . . . . . . . . . 16 67 7. Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . 20 68 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 21 69 9. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 22 70 10. Security considerations . . . . . . . . . . . . . . . . . . . 23 71 11. IANA considerations . . . . . . . . . . . . . . . . . . . . . 24 72 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 25 73 Appendix A. ABNF grammar . . . . . . . . . . . . . . . . . . . . 26 74 Appendix B. CBOR keywords . . . . . . . . . . . . . . . . . . . . 28 75 13. Normative References . . . . . . . . . . . . . . . . . . . . . 29 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 78 1. Requirements notation 80 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 81 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 82 document are to be interpreted as described in [RFC2119]. 84 2. Introduction 86 In this document, a notational convention to express CBOR [RFC7049] 87 data structures is defined. 89 The main goal for the convention is to provide a unified notation 90 that can be used when defining protocols that use CBOR. 92 The CBOR notational convention has the following goals: 94 (G1) Able to provide an unambiguous description of a CBOR data 95 structures. 97 (G2) Easy for humans to read and write. 99 (G3) Flexibility to express the freedoms of choice in the CBOR data 100 format. 102 (G4) Possibility to restrict format choices where appropriate. 104 (G5) Able to express common CBOR datatypes and structures. 106 (G6) Human and machine readable and processable. 108 (G7) Usable for automatic verification of whether CBOR data is 109 compliant to a predefined format. 111 3. Definitions 113 The following contains a list of used words in this document: 115 "datatype" defines the format of a variable. 117 "variable" a data component encoded in CBOR. 119 4. Notational conventions 121 4.1. General conventions 123 The basic syntax is as follows: 125 o Each field has a name and a datatype. 127 o The name is written first, followed by a colon and then the 128 datatype. The declarations is finished with a semicolon. 129 Whitespace may appear around the colon and semicolon, as well as 130 in front of the name. 132 o The datatype in itself MAY be a name of a structure or a map. 134 o A name or datatype can consist of any of the characters from the 135 set {'A', ..., 'Z', 'a', ..., 'z', '0', ..., '9', '_'}. 137 * Names and datatypes SHALL NOT start with a numerical character. 139 * Names and datatypes SHALL NOT equal a CDDL keyword, as listed 140 in Appendix B. 142 * Names and datatypes are case sensitive. 144 * Names and datatypes do not appear in the actual CBOR encoding. 146 * It is RECOMMENDED to start a name with a lower case letter, and 147 a datatype with a capital. 149 o Comments are preceded by a '#' character. 151 o Hexadecimal numbers are preceded by '0x' (without quotes, lower 152 case x), and further are case insensitive. Similarly, binary 153 numbers are preceded by '0b'. 155 o Strings are enclosed by double quotation '"' characters. 157 4.2. Keywords for primitive datatypes 159 The following keywords for primitive datatypes are defined: 161 "bool" Boolean value (major type 7, additional information 20 or 162 21). 164 "bstr" A byte string (major type 2). 166 "float(16)" IEEE 754 half-precision float (major type 7, additional 167 information 25). 169 "float(32)" IEEE 754 single-precision float (major type 7, 170 additional information 26). 172 "float(64)" IEEE 754 double-precision float (major type 7, 173 additional information 27). 175 "int" An unsigned integer (major type 0) or a negative integer 176 (major type 1). 178 "nint" A negative integer (major type 1). 180 "simple" Simple value (major type 7, additional information 24). 182 "tstr" Text string (major type 3) 184 "uint" An unsigned integer (major type 0). 186 In addition, Section 4.6 defines datatypes associated with CBOR tags. 188 4.3. Arrays 190 Arrays can be of fixed length or of variable length. Both fixed 191 length and variable length arrays can be implemented as definite and 192 indefinite length arrays. 194 A fixed length array is is indicated by '[' and ']' characters behind 195 its type, where number in between specifies the number of elements. 197 A variable length array can be indicated with a "*" behind its type. 199 The following is an example of an array of 4 integers: 201 fourNumbers: int[4]; 203 The following is an example of a variable length array: 205 fibonacci : uint*; 207 4.4. Structures 209 Structures are a logical grouping of CBOR fields. 211 A structure has a name, which can be used as a datatype for other 212 fields. The name is followed by a '{' character and the declarations 213 of the variables inside of the structure. The structure is closed by 214 a '}' character. 216 A structure MAY be encoded as an array, in which case its name is 217 preceded by a '*' character. Otherwise there is no CBOR encoding for 218 the grouping. 220 The following is an example of a structure: 222 *Geography { 223 city : tstr; 224 gpsCoordinates : GpsCoordinates; 225 } 227 GpsCoordinates { 228 longitude : uint; # multiplied by 10^7 229 lattitude : uint; # multiplied by 10^7 230 } 232 When encoding, the Geography structure is encoded using a CBOR array, 233 whereas the GpsCoordinates do not have their own encompassing array. 235 4.5. Maps 237 If an entity is a map (major type 5), its datatype has the form 239 map( x, y ) 241 where the keys have datatype x, and the values a datatype y. 243 If either x or y is unspecified (i.e. free to choose per entry), it 244 is replaced by a '.'. 246 It is also possible to define a map with predefined keys as a type. 247 In this case, type declaration is as follows: 249 x: map( y ) { 250 key1: type1; 251 key2: type2; 252 ... 253 } 255 y is the datatype of the keys, and type1, type2, etc the datatype of 256 the value associated with keys key1, key2 etc. 258 The name of an optional map element is preceded by a '?' character. 260 The example below the defines a map with display name (as a string), 261 optionally the name components first name and family name (see 262 Section 4.7 for more on optional variables), and age information (as 263 an unsigned int). 265 PersonalData: map( tstr ) { 266 "displayName": tstr; 267 ?"nameComponents": NameComponents; 268 "age": uint; 269 } 271 NameComponents: map( tstr, tstr ) { 272 "firstName": tstr; 273 "familyName" : tstr; 274 } 276 It is up to the application how to handle unknown tags, however, it 277 is RECOMMENDED to ignore them. 279 When defining keys in the CDDL, the writing conventions for "value" 280 from [RFC7159], Section 3, are followed. 282 4.6. Tags 284 A variable can have an associated CBOR tag (major type 6). This is 285 indicated by the tag encapsulated between the square brackets '[' and 286 ']', just before the variable's datatype declaration. 288 For example, the following defines a positive bignum N: 290 N: [2]bstr; 292 [RFC7049] defines several tags. These tags can be also written using 293 the datatypes from Table 1. For table rows with an empty "possible 294 tag notation" entry, we refer to Table 3 in [RFC7049] and associated 295 references for the possible encodings. 297 For example, the following is another way to define the bignum: 299 N: bignum; 301 +------------+-----------------+------------------------------------+ 302 | datatype | possible tag | description | 303 | | notation | | 304 +------------+-----------------+------------------------------------+ 305 | b64 | [34]tstr | Base 64 (tag 34) | 306 | | | | 307 | b64url | [33]tstr | Base 64 URL (tag 33) | 308 | | | | 309 | bigfloat | | bigfloat (tag 5) | 310 | | | | 311 | bignum | [2]bstr or | positive (tag 2) or negative (tag | 312 | | [3]bstr | 3) bignum | 313 | | | | 314 | cbor | [24]bstr | Encoded CBOR data item (tag 24) | 315 | | | | 316 | decfrac | | decimal fraction (tag 4) | 317 | | | | 318 | eb16 | | Expected conversion to base16 | 319 | | | encoding (tag 23) | 320 | | | | 321 | eb64 | | Expected conversion to base64 | 322 | | | encoding (tag 22) | 323 | | | | 324 | eb64url | | Expected conversion to base64 url | 325 | | | encoding (tag 21) | 326 | | | | 327 | epochdt | | epoch date/time (tag 1) | 328 | | | | 329 | mime | [36]tstr | Mime message (tag 36) | 330 | | | | 331 | nbignum | [3]bstr | negative bignum (tag 3) | 332 | | | | 333 | regex | [35]tstr | regular expression (tag 35) | 334 | | | | 335 | standarddt | [0]tstr | standard date/time string (tag 0) | 336 | | | | 337 | ubignum | [2]bstr | positive bignum (tag 2) | 338 | | | | 339 | uri | [32]tstr | URI (tag 32) | 340 +------------+-----------------+------------------------------------+ 342 Table 1 344 4.7. Optional variables 346 There may be variables or structures whose inclusion is optional. In 347 this case, the name of the variable is preceded by a '?' character 348 For example, the following defines a CBOR structure that is dependent 349 on a boolean value. 351 *MainStruct { 352 whichForm : bool; 353 ?data1 : Form1; # when whichForm == true 354 ?data2 : Form2; # when whichForm == false 355 } 357 Form1 { 358 anInteger : int; 359 aTextString : tstr; 360 } 362 Form2 { 363 aFloat : float(16); 364 aBinaryString : bstr; 365 } 367 Notice that it is not possible to define the relationship between 368 "whichForm" and inclusion of either "data1" or "data2" with CDDL. 369 Such relationship should be otherwise communicated to the 370 implementer, for example in the text of the specification that uses 371 the CBOR structure, or with comments as was done in this example. 373 Protocol designers should exhibit utmost care when defining CBOR 374 structures with optional variables, especially when some of these 375 variables have the same datatype. 377 For example, the following CBOR data structure is ambiguous: 379 *DataStruct { 380 ?OptionalVariable : uint; 381 MandatoryVariable : uint; 382 ?AnotherOptionalVariable : uint; 383 } 385 Since optional variables are often detected from their datatype, it 386 is RECOMMENDED to not have a following of multiple variables of the 387 same datatype, when some of these variables are optional. 389 5. Ordering 391 The declaration of datatypes does not require a specific order. 392 However, it is RECOMMENDED that a datatype that uses another datatype 393 is declared before that other datatype. 395 For example 397 BigStructure { 398 innerData: SmallStructure; 399 } 401 SmallStructure { 402 text: tstr; 403 price: float(16); 404 } 406 is preferable over 408 SmallStructure { 409 text: tstr; 410 price: float(16); 411 } 413 BigStructure { 414 innerData: SmallStructure; 415 } 417 but both are valid. 419 Furthermore, it is RECOMMENDED that the CBOR data is encapsulated in 420 an overal structure or map, and all data is encapsulated (at some 421 level) in this overal structure or map. The declaration of the 422 overal structure or map naturally would be above the declaration of 423 any further datatypes. 425 For example, when defining a message, it would be good to start with 426 the declaration of a structure "Message" that encapsulates the whole 427 message as follows: 429 Message { 430 id: bstr; 431 data: bstr; 432 metadata: Metadata; 433 } 435 *Metadata { 436 senderName: tstr; 437 receiverName: tstr; 438 } 440 The order of variable instances within structures is fixed by the 441 order of declaration. This means that when a variable A is declared 442 before a variable B, a data instance of A will be encoded in front of 443 a data instance of B. 445 The ordering of variables in maps is not fixed, as the keys are 446 already an indication for the related value. 448 6. Examples 450 This section contains various examples of structures defined using 451 the CBOR notational convention. 453 6.1. Moves in a computer game 455 A multiplayer computer game uses CBOR to exchange moves between the 456 players. To ensure a good gaming experience, the move information 457 needs to be exchanged quickly and frequently. Therefore, the game 458 uses CBOR to send its information in a compact format. Figure 1 459 shows definition of the CBOR information exchange format. 461 *UpdateMsg { 462 move_no : uint; # increases for each move 463 player_info : PlayerInfo; # general information 464 moves : Moves*; # moves in this message 465 } 467 PlayerInfo { 468 alias : tstr; 469 player_id : uint; 470 experience : uint; # beginner: 0; expert: 3 471 gold : uint; 472 supplies : Supplies; 473 avg_strength : float(16); 474 } 476 Supplies : map( uint ) { 477 0 : uint; # wood 478 1 : uint; # iron 479 2 : uint; # grain 480 } 482 *Moves { 483 unit_id : uint; 484 unit_strength : uint; # between 0 and 100 485 source_pos : uint[2]; # (x,y) 486 target_pos : uint[2]; # (x,y) 487 } 489 Figure 1: CBOR definition of an information exchange format for a 490 computer game 492 Notice that the supplies have been encoded as a map with integer 493 keys. In this example, using string keys would also have been 494 suitable. However, the example illustrates the possibility to use 495 other datatypes for keys, leading to more efficient encoding. 497 Player "Johnny" does two moves. The game server has assigned Johnny 498 the ID 0x7a3b871f. Johnny is an amateur player, so has experience 1. 499 He currently has 1200 gold, 13 units of wood, 70 units of iron and 29 500 units of grain. He has several units, with a total average strength 501 of 30.25. 503 The units Johnny plays in move 250 are the unit with ID 19, strength 504 20 from (5,7) to (6,9), and the unit with ID 87, strength 40 from 505 (7,10) to (6,10). 507 This information is coded in CBOR as depicted in Figure 2. 509 9F 510 18 FA # move 250 511 66 4A 6F 68 6E 6E 79 # "Johnny" 512 1A 7A 3B 87 1F # player_id 513 01 # experience 514 19 04 B0 # 1200 gold as uint 515 A3 # begin map "supplies" with 3 elements 516 00 # wood: 517 0C # 13 as uint 518 01 # iron: 519 18 86 # 70 as uint 520 02 # grain: 521 18 1D # 29 as uint 522 F9 4F 90 # average strength 30.25 half-precision float 523 9F # indefinite length "moves" array 524 84 # 4-element array Moves 525 13 # unit id 19 as uint 526 14 # strength 20 as uint 527 82 # 2-element array source_pos 528 05 # source_pos.x=5 529 07 # source_pos.y=7 530 82 # 2-element array target_pos 531 06 # target_pos.x=6 532 09 # target_pos.y=9 533 84 # 4-element array Moves 534 18 57 # unit id 87 535 18 28 # strength 40 536 82 # 2-element array source_pos 537 07 # source_pos.x=7 538 0a # source_pos.y=10 539 82 # 2-element array target_pos 540 06 # target_pos.x=6 541 0a # target_pos.y=10 542 FF # end of "moves" array 543 FF 545 Figure 2: CBOR instance for game example 547 6.2. Fruit 549 Figure 3 contains an example for a CBOR structure that contains 550 information about fruit. 552 fruitlist : Fruit*; 554 *Fruit { 555 name : tstr; 556 colour : uint*; 557 avg_weight : float( 16 ); 558 price : uint; 559 international_names : International; 560 rfu : bstr; # reserved for future use 561 } 563 International : map( tstr ) { 564 "CN" : tstr; # Chinese 565 "NL" : tstr; # Dutch 566 "EN" : tstr; # English 567 "FR" : tstr; # French 568 "DE" : tstr; # German 569 } 571 Figure 3: Example CBOR structure 573 The colour integer can have the values from Table 2. 575 +---------+-------+ 576 | Colour | Value | 577 +---------+-------+ 578 | black | 0 | 579 | | | 580 | red | 1 | 581 | | | 582 | green | 2 | 583 | | | 584 | yellow | 3 | 585 | | | 586 | blue | 4 | 587 | | | 588 | magenta | 5 | 589 | | | 590 | cyan | 6 | 591 | | | 592 | white | 7 | 593 | | | 594 | orange | 8 | 595 | | | 596 | pink | 9 | 597 | | | 598 | purple | 10 | 599 | | | 600 | brown | 11 | 601 | | | 602 | grey | 12 | 603 +---------+-------+ 605 Table 2: Possible values for the colour field 607 For example, apples can be red, yellow or green. They have an 608 average weight of 0.195kg and a price of 30 cents. Chinese for 609 "apple" in UTF-8 is [ E8 8B B9 E6 9E 9C ], the Dutch word is "appel" 610 and the French word "pomme". 612 For simplicity, let's assume that the colour of oranges can only be 613 orange. They have an average weight of 0.230kg and a price of 50 614 cents. Chinese for "orange" in UTF-8 is [ E6 A9 99 E5 AD 90 ], the 615 Dutch word is "sinaasappel" and the German word "Orange". 617 This information would be encoded as depicted in Figure 4. 619 9F # indefinite length "fruitlist" array 620 86 # First "Fruit" instance, 6 elements 621 65 # text string "name" length 5 622 61 70 70 6C 65 # "apple" 623 83 # array for "Colour", 3 elements 624 01 # "red" as uint 625 02 # "green" as uint 626 03 # "yellow" as uint 627 F9 # Floating point half precision 628 32 3D # "avg_weight" 0.195 629 18 1E # "price" 30 as uint 630 A3 # map "international_names", 3 pairs 631 62 43 4E # text string length 2, "CN" 632 66 E8 8B B9 E6 9E 9C # Chinese word for apple 633 62 4E 4C # "NL" 634 65 61 70 70 65 6C # "appel" 635 62 46 52 # "FR" 636 65 70 6F 6D 6D 65 # "pomme" 637 40 # byte string "rfu", 0 bytes length 638 86 # Second "Fruit" instance 639 66 # text string "name" length 6 640 6F 72 61 6E 67 65 # "orange" 641 81 # array for "Colour", 3 elements 642 08 # "orange" as uint 643 F9 # Floating point half precision 644 33 5C # "avg_weight" 0.230 645 18 32 # "price" 50 as uint 646 A3 # map "international_names", 3 pairs 647 62 43 4E # text string length 2, "CN" 648 66 E6 A9 99 E5 AD 90 # Chinese word for orange 649 62 4E 4C # "NL" 650 6B 73 69 6E 61 61 73 61 70 70 65 6C # "sinaasappel" 651 62 44 45 # "DE" 652 66 4F 72 61 6E 67 65 # "Orange" 653 40 # byte string "rfu", 0 bytes length 654 FF # end of "fruitlist" array 656 Figure 4: Example CBOR instance 658 Notice that if the "Fruit" structure did not have the preceding "*", 659 the two "Fruit" instance arrays would have been omitted. In 660 addition, the "fruitlist" array would have had 12 elements instead of 661 2. (Although for "fruitlist" the indefinite length approach was 662 chosen, such that the number of elements is not explicitely 663 signalled.) 665 7. Philosophy 667 The CBOR notational convention can be used to efficiently define the 668 layout of CBOR data. 670 In addition, it has been specified such that a machine can verify 671 whether or not CBOR data is compliant to its definition. The 672 thoroughness of this compliance verification depends on the 673 application. 675 For example, an application may decide not to verify the data 676 structure at all, and use the CDDL definition solely as a means to 677 indicate the structure of the data to the programmer. 679 On the other end, the application may also implement a verification 680 method that goes as far as verifying that all mandatory map keys are 681 available. 683 The matter in how far the data description must be enforced by an 684 application is left to the designers and implementers of that 685 application, keeping in mind related security considerations. 687 8. Open Issues 689 At least the following issues need further consideration: 691 o Whether to remove optional variables (other than in maps). 693 o More extensive security considerations. 695 o The key/value pairs in maps have no fixed ordering. However, 696 there may be situations where fixing the ordering may be of use. 697 For example, an decoder could look for values related with integer 698 keys 1, 3 and 7. If the order was fixed and the decoder 699 encounters the key 4 without having encountered key 3, it can 700 conclude that key 3 is not available without doing more 701 complicated bookkeeping. 703 9. Change Log 705 Changes from version 00 to version 01 707 o Removed constants 709 o Updated the tag mechanism 711 o Extended the map structure 713 o Added examples 715 Changes from version 01 to version 02 717 o Fixed example 719 Changes from version 02 to version 03 721 o Added information about characters used in names 723 o Added text about an overlapping data structure and order of 724 definition of fields 726 o Added text about encoding of keys 728 o Added table with keywords 730 o Strings and integer writing conventions 732 o Added ABNF 734 10. Security considerations 736 This document presents a content rules language for expressing CBOR 737 data structures. As such, it does not bring any security issues on 738 itself, although specification of protocols that use CBOR naturally 739 need security analysis when defined. 741 Topics that could be considered in a security considerations section 742 that uses CDDL to define CBOR structures include the following: 744 o Whether or not ommission of an optional field could lead to 745 misinterpretation of a later field. 747 11. IANA considerations 749 This document does not require any IANA registrations. 751 12. Acknowledgements 753 For this draft, there has been inspiration from the C and Pascal 754 languages, MPEG's conventions for describing structures in the ISO 755 base media file format, and Andrew Lee Newton's "JSON Content Rules" 756 draft. 758 Useful feedback came from Carsten Bormann and Joe Hildebrand. 760 Appendix A. ABNF grammar 762 The following is a formal definition of CBOR in Augmented Backus-Naur 763 Form (ABNF, [RFC5234]). We also use the conventions from [RFC5234], 764 Appendix B and [RFC3629], section 4. 766 file = 1*( structure / map / field) 768 field = name ":" type ";" newline 770 name = valid-name 771 type = fixed-array / indefinite-array / valid-type 773 fixed-array = valid-type "[" 1*DIGIT "]" 774 indefinite-array = valid-type "*" 776 structure = (simple-structure / array-structure) newline 777 structure-body = S "{" S 1*(field / comment) S "}" 778 simple-structure = name structure-body 779 array-structure = "*" name structure-body 781 map = name ":" map-header map-body 782 map-header = map "(" (valid-type / ".") "," 783 (valid-type / ".") ")" 784 map-body = S "{" newline 1*map-entry "}" 786 map-entry = map-optional-entry / map-mandatory-entry / comment 787 map-mandatory-entry = cbor-data ":" type ";" 788 map-optional-entry = "?" map-mandatory-entry 790 cbor-data = cbor-string / cbor-number / cbor-extension 791 cbor-string = DQUOTE text DQUOTE 792 cbor-number = cbor-leading-numerical / cbor-leading-dot / 793 cbor-hex-number / cbor-binary-number 794 cbor-leading-dot = '.' 1*DIGIT ['e' 1*DIGIT] 795 cbor-leading-numerical = 1*DIGIT ['.' 1*DIGIT] ['e' 1*DIGIT] 796 cbor-hex-number = hex-prefix 1*HEXDIG 797 cbor-bin-number = bin-prefix 1*BIT 799 hex-prefix = %d48.120 ; 0x 800 bin-prefix = %d48.98 ; 0b 801 cbor-extension = *text-char 803 valid-char = DIGIT / ALPHA / "_" 804 valid-name = 1*valid-char 805 valid-type = primitive-datatype / 1*valid-char 807 primitive-datatype = bool / bstr / float16 808 / float32 / float64 / int 809 / nint / simple / tstr / uint 811 S = *(WS) 812 newline = [CR] LF 813 text-char = %20-7e 814 comment-char = UTF8-char 815 comment = "#" *(comment-char) newline 816 WS = SP / HTAB / newline / comment ; white space 818 ; case-sensitive literals 819 bool = %d98.111.111.108 820 bstr = %d98.115.116.114 821 float16 = %d102.108.111.97.116.40.49.54.41 ; float(16) 822 float32 = %d102.108.111.97.116.40.51.50.41 ; float(32) 823 float64 = %d102.108.111.97.116.40.54.52.41 ; float(64) 824 int = %d105.110.116 825 map = %d109.97.112 826 nint = %d110.105.110.116 827 simple = %d115.105.109.112.108.101 828 tstr = %d116.115.116.114 829 uint = %d117.105.110.116 831 Appendix B. CBOR keywords 833 The following table contains an overview of the CDDL keywords. 835 +----------------+----------------+----------------+----------------+ 836 | b64 | b64url | bigfloat | bignum | 837 | | | | | 838 | bool | bstr | cbor | decfrac | 839 | | | | | 840 | eb16 | eb64 | eb64url | epochdt | 841 | | | | | 842 | float | int | map | mime | 843 | | | | | 844 | nbignum | nint | regex | simple | 845 | | | | | 846 | standarddt | tstr | ubignum | uint | 847 | | | | | 848 | uri | | | | 849 +----------------+----------------+----------------+----------------+ 851 13. Normative References 853 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 854 Requirement Levels", BCP 14, RFC 2119, March 1997. 856 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 857 10646", STD 63, RFC 3629, November 2003. 859 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 860 Specifications: ABNF", STD 68, RFC 5234, January 2008. 862 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 863 Representation (CBOR)", RFC 7049, October 2013. 865 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 866 Interchange Format", RFC 7159, March 2014. 868 Authors' Addresses 870 Bert Greevenbosch 871 Huawei Technologies Co., Ltd. 872 Huawei Industrial Base 873 Bantian, Longgang District 874 Shenzhen 518129 875 P.R. China 877 Email: bert.greevenbosch@huawei.com 879 Christoph Vigano 880 University of Bremen 882 Email: christoph.vigano@uni-bremen.de