doc: Add RFC documents

1 files changed, 3587 insertions, 0 deletions

diff --git a/doc/rfc/rfc8610.txt b/doc/rfc/rfc8610.txt
new file mode 100644
index 0000000..bec963a
--- /dev/null
+++ b/doc/rfc/rfc8610.txt
@@ -0,0 +1,3587 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                       H. Birkholz
+Request for Comments: 8610                                Fraunhofer SIT
+Category: Standards Track                                      C. Vigano
+ISSN: 2070-1721                                      Universitaet Bremen
+                                                              C. Bormann
+                                                 Universitaet Bremen TZI
+                                                               June 2019
+
+
+    Concise Data Definition Language (CDDL): A Notational Convention
+         to Express Concise Binary Object Representation (CBOR)
+                        and JSON Data Structures
+
+Abstract
+
+   This document proposes a notational convention to express Concise
+   Binary Object Representation (CBOR) data structures (RFC 7049).  Its
+   main goal is to provide an easy and unambiguous way to express
+   structures for protocol messages and data formats that use CBOR or
+   JSON.
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 7841.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   https://www.rfc-editor.org/info/rfc8610.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                    [Page 1]
+
+RFC 8610                          CDDL                         June 2019
+
+
+Copyright Notice
+
+   Copyright (c) 2019 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (https://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+Table of Contents
+
+   1. Introduction ....................................................4
+      1.1. Requirements Notation ......................................5
+      1.2. Terminology ................................................5
+   2. The Style of Data Structure Specification .......................5
+      2.1. Groups and Composition in CDDL .............................7
+           2.1.1. Usage ..............................................10
+           2.1.2. Syntax .............................................10
+      2.2. Types .....................................................11
+           2.2.1. Values .............................................11
+           2.2.2. Choices ............................................11
+           2.2.3. Representation Types ...............................13
+           2.2.4. Root Type ..........................................14
+   3. Syntax .........................................................15
+      3.1. General Conventions .......................................15
+      3.2. Occurrence ................................................16
+      3.3. Predefined Names for Types ................................17
+      3.4. Arrays ....................................................18
+      3.5. Maps ......................................................19
+           3.5.1. Structs ............................................19
+           3.5.2. Tables .............................................22
+           3.5.3. Non-deterministic Order ............................23
+           3.5.4. Cuts in Maps .......................................24
+      3.6. Tags ......................................................25
+      3.7. Unwrapping ................................................26
+      3.8. Controls ..................................................27
+           3.8.1. Control Operator .size .............................27
+           3.8.2. Control Operator .bits .............................28
+           3.8.3. Control Operator .regexp ...........................29
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                    [Page 2]
+
+RFC 8610                          CDDL                         June 2019
+
+
+           3.8.4. Control Operators .cbor and .cborseq ...............30
+           3.8.5. Control Operators .within and .and .................30
+           3.8.6. Control Operators .lt, .le, .gt, .ge, .eq,
+                  .ne, and .default ..................................31
+      3.9. Socket/Plug ...............................................32
+      3.10. Generics .................................................33
+      3.11. Operator Precedence ......................................34
+   4. Making Use of CDDL .............................................36
+      4.1. As a Guide for a Human User ...............................36
+      4.2. For Automated Checking of CBOR Data Structures ............36
+      4.3. For Data Analysis Tools ...................................37
+   5. Security Considerations ........................................37
+   6. IANA Considerations ............................................38
+      6.1. CDDL Control Operators Registry ...........................38
+   7. References .....................................................40
+      7.1. Normative References ......................................40
+      7.2. Informative References ....................................41
+   Appendix A. Parsing Expression Grammars (PEGs) ....................43
+   Appendix B. ABNF Grammar ..........................................45
+   Appendix C. Matching Rules ........................................47
+   Appendix D. Standard Prelude ......................................52
+   Appendix E. Use with JSON .........................................53
+   Appendix F. A CDDL Tool ...........................................56
+   Appendix G. Extended Diagnostic Notation ..........................56
+     G.1. Whitespace in Byte String Notation .........................57
+     G.2. Text in Byte String Notation ...............................57
+     G.3. Embedded CBOR and CBOR Sequences in Byte Strings ...........57
+     G.4. Concatenated Strings .......................................58
+     G.5. Hexadecimal, Octal, and Binary Numbers .....................59
+     G.6. Comments ...................................................59
+   Appendix H. Examples ..............................................60
+   Acknowledgements ..................................................63
+   Contributors ......................................................63
+   Authors' Addresses ................................................64
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                    [Page 3]
+
+RFC 8610                          CDDL                         June 2019
+
+
+1.  Introduction
+
+   In this document, a notational convention to express Concise Binary
+   Object Representation (CBOR) data structures [RFC7049] is defined.
+
+   The main goal for the convention is to provide a unified notation
+   that can be used when defining protocols that use CBOR.  We term the
+   convention "Concise Data Definition Language", or CDDL.
+
+   The CBOR notational convention has the following goals:
+
+   (G1)  Provide an unambiguous description of the overall structure of
+         a CBOR data item.
+
+   (G2)  Be flexible in expressing the multiple ways in which data can
+         be represented in the CBOR data format.
+
+   (G3)  Be able to express common CBOR datatypes and structures.
+
+   (G4)  Provide a single format that is both readable and editable for
+         humans and processable by a machine.
+
+   (G5)  Enable automatic checking of CBOR data items for data format
+         compliance.
+
+   (G6)  Enable extraction of specific elements from CBOR data for
+         further processing.
+
+   Not an original goal per se, but a convenient side effect of the JSON
+   generic data model being a subset of the CBOR generic data model, is
+   the fact that CDDL can also be used for describing JSON data
+   structures (see Appendix E).
+
+   This document has the following structure:
+
+   The syntax of CDDL is defined in Section 3.  Examples of CDDL and a
+   related CBOR data item ("instance"), some of which use the JSON form,
+   are described in Appendix H.  Section 4 discusses usage of CDDL.
+   Examples are provided throughout the text to better illustrate
+   concept definitions.  A formal definition of CDDL using ABNF grammar
+   [RFC5234] is provided in Appendix B.  Finally, a _prelude_ of
+   standard CDDL definitions that is automatically prepended to, and
+   thus available in, every CDDL specification is listed in Appendix D.
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                    [Page 4]
+
+RFC 8610                          CDDL                         June 2019
+
+
+1.1.  Requirements Notation
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+   "OPTIONAL" in this document are to be interpreted as described in
+   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+   capitals, as shown here.
+
+1.2.  Terminology
+
+   New terms are introduced in _cursive_, which is rendered in plain
+   text as the new term surrounded by underscores.  CDDL text in the
+   running text is in "typewriter", which is rendered in plain text as
+   the CDDL text in double quotes (double quotes are also used in the
+   usual English sense; the reader is expected to disambiguate this by
+   context).
+
+   In this specification, the term "byte" is used in its now-customary
+   sense as a synonym for "octet".
+
+2.  The Style of Data Structure Specification
+
+   CDDL focuses on styles of specification that are in use in the
+   community employing the data model as pioneered by JSON and now
+   refined in CBOR.
+
+   There are a number of more or less atomic elements of a CBOR data
+   model, such as numbers, simple values (false, true, nil), text
+   strings, and byte strings; CDDL does not focus on specifying their
+   structure.  CDDL of course also allows adding a CBOR tag to a
+   data item.
+
+   Beyond those atomic elements, further components of a data structure
+   definition language are the datatypes used for composition: arrays
+   and maps in CBOR (called "arrays" and "objects" in JSON).  While
+   these are only two representation formats, they are used to specify
+   four loosely distinguishable styles of composition:
+
+   o  A _vector_: an array of elements that are mostly of the same
+      semantics.  The set of signatures associated with a signed data
+      item is a typical application of a vector.
+
+   o  A _record_: an array the elements of which have different,
+      positionally defined semantics, as detailed in the data structure
+      definition.  A 2D point, specified as an array of an x coordinate
+      (which comes first) and a y coordinate (coming second), is an
+      example of a record, as is the pair of exponent (first) and
+      mantissa (second) in a CBOR decimal fraction.
+
+
+
+Birkholz, et al.             Standards Track                    [Page 5]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   o  A _table_: a map from a domain of map keys to a domain of map
+      values, that are mostly of the same semantics.  A set of language
+      tags, each mapped to a text string translated to that specific
+      language, is an example of a table.  The key domain is usually not
+      limited to a specific set by the specification but is open for the
+      application, e.g., in a table mapping IP addresses to Media Access
+      Control (MAC) addresses, the specification does not attempt to
+      foresee all possible IP addresses.  In a language such as
+      JavaScript, a "Map" (as opposed to a plain "Object") would often
+      be employed to achieve the generality of the key domain.
+
+   o  A _struct_: a map from a domain of map keys as defined by the
+      specification to a domain of map values the semantics of each of
+      which is bound to a specific map key.  This is what many people
+      have in mind when they think about JSON objects; CBOR adds the
+      ability to use map keys that are not just text strings.  Structs
+      can be used to solve problems similar to those records are used
+      for; the use of explicit map keys facilitates optionality and
+      extensibility.
+
+   Two important concepts provide the foundation for CDDL:
+
+   1.  Instead of defining all four types of composition in CDDL
+       separately, or even defining one kind for arrays (vectors and
+       records) and one kind for maps (tables and structs), there is
+       only one kind of composition in CDDL: the _group_ (Section 2.1).
+
+   2.  The other important concept is that of a _type_.  The entire CDDL
+       specification defines a type (the one defined by its first
+       _rule_), which formally is the set of CBOR data items that are
+       acceptable as "instances" for this specification.  CDDL
+       predefines a number of basic types such as "uint" (unsigned
+       integer) or "tstr" (text string), often making use of a simple
+       formal notation for CBOR data items.  Each value that can be
+       expressed as a CBOR data item is also a type in its own right,
+       e.g., "1".  A type can be built as a _choice_ of other types,
+       e.g., an "int" is either a "uint" or a "nint" (negative integer).
+       Finally, a type can be built as an array or a map from a group.
+
+   The rest of this section introduces a number of basic concepts of
+   CDDL, and Section 3 defines additional syntax.  Appendix C gives a
+   concise summary of the semantics of CDDL.
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                    [Page 6]
+
+RFC 8610                          CDDL                         June 2019
+
+
+2.1.  Groups and Composition in CDDL
+
+   CDDL groups are lists of group _entries_, each of which can be a
+   name/value pair or a more complex group expression (which then in
+   turn stands for a sequence of name/value pairs).  A CDDL group is a
+   production in a grammar that matches certain sequences of name/value
+   pairs but not others.  The grammar is based on the concepts of
+   Parsing Expression Grammars (PEGs) (see Appendix A).
+
+   In an array context, only the value of the name/value pair is
+   represented; the name is annotation only (and can be left off from
+   the group specification if not needed).  In a map context, the names
+   become the map keys ("member keys").
+
+   In an array context, the actual sequence of elements in the group is
+   important, as that sequence is the information that allows
+   associating actual array elements with entries in the group.  In a
+   map context, the sequence of entries in a group is not relevant (but
+   there is still a need to write down group entries in a sequence).
+
+   An array matches a specification given as a group when the group
+   matches a sequence of name/value pairs the value parts of which
+   exactly match the elements of the array in order.
+
+   A map matches a specification given as a group when the group matches
+   a sequence of name/value pairs such that all of these name/value
+   pairs are present in the map and the map has no name/value pair that
+   is not covered by the group.
+
+   A simple example of using a group directly in a map definition is:
+
+                             person = {
+                               age: int,
+                               name: tstr,
+                               employer: tstr,
+                             }
+
+                 Figure 1: Using a Group Directly in a Map
+
+   The three entries of the group are written between the curly braces
+   that create the map: here, "age", "name", and "employer" are the
+   names that turn into the map key text strings, and "int" and "tstr"
+   (text string) are the types of the map values under these keys.
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                    [Page 7]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   A group by itself (without creating a map around it) can be placed in
+   (round) parentheses and given a name by using it in a rule:
+
+                             pii = (
+                               age: int,
+                               name: tstr,
+                               employer: tstr,
+                             )
+
+                          Figure 2: A Basic Group
+
+   This separate, named group definition allows us to rephrase
+   Figure 1 as:
+
+                                person = {
+                                  pii
+                                }
+
+                      Figure 3: Using a Group by Name
+
+   Note that the (curly) braces signify the creation of a map; the
+   groups themselves are neutral as to whether they will be used in a
+   map or an array.
+
+   As shown in Figure 1, the parentheses for groups are optional when
+   there is some other set of brackets present.  Note that they can
+   still be used, leading to this not-so-realistic, but perfectly valid,
+   example:
+
+                             person = {(
+                               age: int,
+                               name: tstr,
+                               employer: tstr,
+                             )}
+
+              Figure 4: Using a Parenthesized Group in a Map
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                    [Page 8]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Groups can be used to factor out common parts of structs, e.g.,
+   instead of writing specifications in copy/paste style, such as in
+   Figure 5, one can factor out the common subgroup, choose a name for
+   it, and write only the specific parts into the individual maps
+   (Figure 6).
+
+                          person = {
+                            age: int,
+                            name: tstr,
+                            employer: tstr,
+                          }
+
+                          dog = {
+                            age: int,
+                            name: tstr,
+                            leash-length: float,
+                          }
+
+                      Figure 5: Maps with Copy/Paste
+
+                          person = {
+                            identity,
+                            employer: tstr,
+                          }
+
+                          dog = {
+                            identity,
+                            leash-length: float,
+                          }
+
+                          identity = (
+                            age: int,
+                            name: tstr,
+                          )
+
+                 Figure 6: Using a Group for Factorization
+
+   Note that the lists inside the braces in the above definitions
+   constitute (anonymous) groups, while "identity" is a named group,
+   which can then be included as part of other groups (anonymous as in
+   the example, or themselves named).
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                    [Page 9]
+
+RFC 8610                          CDDL                         June 2019
+
+
+2.1.1.  Usage
+
+   Groups are the instrument used in composing data structures with
+   CDDL.  It is a matter of style in defining those structures whether
+   to define groups (anonymously) right in their contexts or whether to
+   define them in a separate rule and to reference them with their
+   respective name (possibly more than once).
+
+   With this, one is allowed to define all small parts of their data
+   structures and compose bigger protocol data units with those or to
+   have only one big protocol data unit that has all definitions ad hoc
+   where needed.
+
+2.1.2.  Syntax
+
+   The composition syntax is intended to be concise and easy to read:
+
+   o  The start and end of a group can be marked by "(" and ")".
+
+   o  Definitions of entries inside of a group are noted as follows:
+      _keytype => valuetype,_ (read "keytype maps to valuetype").  The
+      comma is actually optional (not just in the final entry), but it
+      is considered good style to set it.  The double arrow can be
+      replaced by a colon in the common case of directly using a text
+      string or integer literal as a key; see Section 3.5.1.  This is
+      also the common way of naming elements of an array just for
+      documentation; see Section 3.4.
+
+   A basic entry consists of a _keytype_ and a _valuetype_, both of
+   which are types (Section 2.2); this entry matches any name/value pair
+   the name of which is in the keytype and the value of which is in the
+   valuetype.
+
+   A group defined as a sequence of group entries matches any sequence
+   of name/value pairs that is composed by concatenation in order of
+   what the entries match.
+
+   A group definition can also contain choices between groups; see
+   Section 2.2.2.
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 10]
+
+RFC 8610                          CDDL                         June 2019
+
+
+2.2.  Types
+
+2.2.1.  Values
+
+   Values such as numbers and strings can be used in place of a type.
+   (For instance, this is a very common thing to do for a key type,
+   common enough that CDDL provides additional convenience syntax
+   for this.)
+
+   The value notation is based on the C language, but does not offer all
+   the syntactic variations (see Appendix B for details).  The value
+   notation for numbers inherits from C the distinction between integer
+   values (no fractional part or exponent given -- NR1 [ISO6093];
+   "NR" stands for "numerical representation") and floating-point values
+   (where a fractional part, an exponent, or both are present -- NR2 or
+   NR3), so the type "1" does not include any floating-point numbers
+   while the types "1e3" and "1.5" are both floating-point numbers and
+   do not include any integer numbers.
+
+2.2.2.  Choices
+
+   Many places that allow a type also allow a choice between types,
+   delimited by a "/" (slash).  The entire choice construct can be put
+   into parentheses if this is required to make the construction
+   unambiguous (please see Appendix B for details of the CDDL grammar).
+
+   Choices of values can be used to express enumerations:
+
+            attire = "bow tie" / "necktie" / "Internet attire"
+            protocol = 6 / 17
+
+   Analogous to types, CDDL also allows choices between groups,
+   delimited by a "//" (double slash).  Note that the "//" operator
+   binds much more weakly than the other CDDL operators, so each line
+   within "delivery" in the following example is its own alternative in
+   the group choice:
+
+                   address = { delivery }
+
+                   delivery = (
+                   street: tstr, ? number: uint, city //
+                   po-box: uint, city //
+                   per-pickup: true )
+
+                   city = (
+                   name: tstr, zip-code: uint
+                   )
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 11]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   A group choice matches the union of the sets of name/value pair
+   sequences that the alternatives in the choice can.
+
+   For both type choices and group choices, additional alternatives can
+   be added to a rule later in separate rules by using "/=" and "//=",
+   respectively, instead of "=":
+
+                 attire /= "swimwear"
+
+                 delivery //= (
+                 lat: float, long: float, drone-type: tstr
+                 )
+
+   It is not an error if a name is first used with a "/=" or "//="
+   (there is no need to "create it" with "=").
+
+2.2.2.1.  Ranges
+
+   Instead of naming all the values that make up a choice, CDDL allows
+   building a _range_ out of two values that are in an ordering
+   relationship: a lower bound (first value) and an upper bound (second
+   value).  A range can be inclusive of both bounds given (denoted by
+   joining two values by ".."), or it can include the lower bound and
+   exclude the upper bound (denoted by instead using "...").  If the
+   lower bound exceeds the upper bound, the resulting type is the empty
+   set (this behavior can be desirable when generics (Section 3.10) are
+   being used).
+
+         device-address = byte
+         max-byte = 255
+         byte = 0..max-byte ; inclusive range
+         first-non-byte = 256
+         byte1 = 0...first-non-byte ; byte1 is equivalent to byte
+
+   CDDL currently only allows ranges between integers (matching integer
+   values) or between floating-point values (matching floating-point
+   values).  If both are needed in a type, a type choice between the two
+   kinds of ranges can be (clumsily) used:
+
+                int-range = 0..10 ; only integers match
+                float-range = 0.0..10.0 ; only floats match
+                BAD-range1 = 0..10.0 ; NOT DEFINED
+                BAD-range2 = 0.0..10 ; NOT DEFINED
+                numeric-range = int-range / float-range
+
+   (See also the control operators .lt/.ge and .le/.gt in
+   Section 3.8.6.)
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 12]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Note that the dot is a valid name continuation character in CDDL, so
+
+      min..max
+
+   is not a range expression but a single name.  When using a name as
+   the left-hand side of a range operator, use spacing as in
+
+      min .. max
+
+   to separate off the range operator.
+
+2.2.2.2.  Turning a Group into a Choice
+
+   Some choices are built out of large numbers of values, often
+   integers, each of which is best given a semantic name in the
+   specification.  Instead of naming each of these integers and then
+   accumulating them into a choice, CDDL allows building a choice from a
+   group by prefixing it with an "&" character:
+
+              terminal-color = &basecolors
+              basecolors = (
+                black: 0,  red: 1,  green: 2,  yellow: 3,
+                blue: 4,  magenta: 5,  cyan: 6,  white: 7,
+              )
+              extended-color = &(
+                basecolors,
+                orange: 8,  pink: 9,  purple: 10,  brown: 11,
+              )
+
+   As with the use of groups in arrays (Section 3.4), the member names
+   have only documentary value (in particular, they might be used by a
+   tool when displaying integers that are taken from that choice).
+
+2.2.3.  Representation Types
+
+   CDDL allows the specification of a data item type by referring to the
+   CBOR representation (specifically, to major types and additional
+   information; see Section 2 of [RFC7049]).  How this is used should be
+   evident from the prelude (Appendix D): a hash mark ("#") optionally
+   followed by a number from 0 to 7 identifying the major type, which
+   then can be followed by a dot and a number specifying the additional
+   information.  This construction specifies the set of values that can
+   be serialized in CBOR (i.e., "any"), by the given major type if one
+   is given, or by the given major type with the additional information
+   if both are given.  Where a major type of 6 (Tag) is used, the type
+   of the tagged item can be specified by appending it in parentheses.
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 13]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Note that although this notation is based on the CBOR serialization,
+   it is about a set of values at the data model level, e.g., "#7.25"
+   specifies the set of values that can be represented as half-precision
+   floats; it does not mandate that these values also do have to be
+   serialized as half-precision floats: CDDL does not provide any
+   language means to restrict the choice of serialization variants.
+   This also enables the use of CDDL with JSON, which uses a
+   fundamentally different way of serializing (some of) the same values.
+
+   It may be necessary to make use of representation types outside the
+   prelude, e.g., a specification could start by making use of an
+   existing tag in a more specific way or could define a new tag not
+   defined in the prelude:
+
+      my_breakfast = #6.55799(breakfast)   ; cbor-any is too general!
+      breakfast = cereal / porridge
+      cereal = #6.998(tstr)
+      porridge = #6.999([liquid, solid])
+      liquid = milk / water
+      milk = 0
+      water = 1
+      solid = tstr
+
+2.2.4.  Root Type
+
+   There is no special syntax to identify the root of a CDDL data
+   structure definition: that role is simply taken by the first rule
+   defined in the file.
+
+   This is motivated by the usual top-down approach for defining data
+   structures, decomposing a big data structure unit into smaller parts;
+   however, except for the root type, there is no need to strictly
+   follow this sequence.
+
+   (Note that there is no way to use a group as a root -- it must be
+   a type.)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 14]
+
+RFC 8610                          CDDL                         June 2019
+
+
+3.  Syntax
+
+   In this section, the overall syntax of CDDL is shown, alongside some
+   examples just illustrating syntax.  (The definition does not attempt
+   to be overly formal; refer to Appendix B for details.)
+
+3.1.  General Conventions
+
+   The basic syntax is inspired by ABNF [RFC5234], with the following:
+
+   o  Rules, whether they define groups or types, are defined with a
+      name, followed by an equals sign "=" and the actual definition
+      according to the respective syntactic rules of that definition.
+
+   o  A name can consist of any of the characters from the set {"A" to
+      "Z", "a" to "z", "0" to "9", "_", "-", "@", ".", "$"}, starting
+      with an alphabetic character (including "@", "_", "$") and ending
+      in such a character or a digit.
+
+      *  Names are case sensitive.
+
+      *  It is preferred style to start a name with a lowercase letter.
+
+      *  The hyphen is preferred over the underscore (except in a
+         "bareword" (Section 3.5.1), where the semantics may actually
+         require an underscore).
+
+      *  The period may be useful for larger specifications, to express
+         some module structure (as in "tcp.throughput" vs.
+         "udp.throughput").
+
+      *  A number of names are predefined in the CDDL prelude, as listed
+         in Appendix D.
+
+      *  Rule names (types or groups) do not appear in the actual CBOR
+         encoding, but names used as "barewords" in member keys do.
+
+   o  Comments are started by a ";" (semicolon) character and finish at
+      the end of a line (LF or CRLF).
+
+   o  Except within strings, whitespace (spaces, newlines, and comments)
+      is used to separate syntactic elements for readability (and to
+      separate identifiers, range operators, or numbers that follow each
+      other); it is otherwise completely optional.
+
+   o  Hexadecimal numbers are preceded by "0x" (without quotes) and are
+      case insensitive.  Similarly, binary numbers are preceded by "0b".
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 15]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   o  Text strings are enclosed by double quotation '"' characters.
+      They follow the conventions for strings as defined in Section 7 of
+      [RFC8259].  (ABNF users may want to note that there is no support
+      in CDDL for the concept of case insensitivity in text strings; if
+      necessary, regular expressions can be used (Section 3.8.3).)
+
+   o  Byte strings are enclosed by single quotation "'" characters and
+      may be prefixed by "h" or "b64".  If unprefixed, the string is
+      interpreted as with a text string, except that single quotes must
+      be escaped and that the resulting UTF-8 bytes are marked as a byte
+      string (major type 2).  If prefixed as "h" or "b64", the string is
+      interpreted as a sequence of pairs of hex digits (base16; see
+      Section 8 of [RFC4648]) or a base64(url) string (Section 4 or
+      Section 5 of [RFC4648]), respectively (as with the diagnostic
+      notation in Section 6 of [RFC7049]; cf. Appendix G.2); any
+      whitespace present within the string (including comments) is
+      ignored in the prefixed case.
+
+   o  CDDL uses UTF-8 [RFC3629] for its encoding.  Processing of CDDL
+      does not involve Unicode normalization processes.
+
+   Example:
+
+                    ; This is a comment
+                    person = { g }
+
+                    g = (
+                      "name": tstr,
+                      age: int,  ; "age" is a bareword
+                    )
+
+3.2.  Occurrence
+
+   An optional _occurrence_ indicator can be given in front of a group
+   entry.  It is either (1) one of the characters "?" (optional), "*"
+   (zero or more), or "+" (one or more) or (2) of the form n*m, where n
+   and m are optional unsigned integers and n is the lower limit
+   (default 0) and m is the upper limit (default no limit) of
+   occurrences.
+
+   If no occurrence indicator is specified, the group entry is to occur
+   exactly once (as if 1*1 were specified).  A group entry with an
+   occurrence indicator matches sequences of name/value pairs that are
+   composed by concatenating a number of sequences that the basic group
+   entry matches, where the number needs to be allowed by the occurrence
+   indicator.
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 16]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Note that CDDL, outside any directives/annotations that could
+   possibly be defined, does not make any prescription as to whether
+   arrays or maps use definite-length or indefinite-length encoding.
+   That is, there is no correlation between leaving the size of an array
+   "open" in the spec and the fact that it is then interchanged with
+   definite or indefinite length.
+
+   Please also note that CDDL can describe flexibility that the data
+   model of the target representation does not have.  This is rather
+   obvious for JSON but is also relevant for CBOR:
+
+                           apartment = {
+                             kitchen: size,
+                             * bedroom: size,
+                           }
+                           size = float ; in m2
+
+   The previous specification does not mean that CBOR is changed to
+   allow using the key "bedroom" more than once.  In other words, due to
+   the restrictions imposed by the data model, the third line pretty
+   much turns into:
+
+                             ? bedroom: size,
+
+   (Occurrence indicators beyond one are still useful in maps for groups
+   that allow a variety of keys.)
+
+3.3.  Predefined Names for Types
+
+   CDDL predefines a number of names.  This subsection summarizes these
+   names, but please see Appendix D for the exact definitions.
+
+   The following keywords for primitive datatypes are defined:
+
+   "bool"  Boolean value (major type 7, additional information 20
+      or 21).
+
+   "uint"  An unsigned integer (major type 0).
+
+   "nint"  A negative integer (major type 1).
+
+   "int"  An unsigned integer or a negative integer.
+
+   "float16"  A number representable as a half-precision float [IEEE754]
+      (major type 7, additional information 25).
+
+   "float32"  A number representable as a single-precision float
+      [IEEE754] (major type 7, additional information 26).
+
+
+
+Birkholz, et al.             Standards Track                   [Page 17]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   "float64"  A number representable as a double-precision float
+      [IEEE754] (major type 7, additional information 27).
+
+   "float"  One of float16, float32, or float64.
+
+   "bstr" or "bytes"  A byte string (major type 2).
+
+   "tstr" or "text"  Text string (major type 3).
+
+   (Note that there are no predefined names for arrays or maps; these
+   are defined with the syntax given below.)
+
+   In addition, a number of types are defined in the prelude that are
+   associated with CBOR tags, such as "tdate", "bigint", "regexp", etc.
+
+3.4.  Arrays
+
+   Array definitions surround a group with square brackets.
+
+   For each entry, an occurrence indicator as specified in Section 3.2
+   is permitted.
+
+   For example:
+
+                     unlimited-people = [* person]
+                     one-or-two-people = [1*2 person]
+                     at-least-two-people = [2* person]
+                     person = (
+                         name: tstr,
+                         age: uint,
+                     )
+
+   The group "person" is defined in such a way that repeating it in the
+   array each time generates alternating names and ages, so these are
+   four valid values for a data item of type "unlimited-people":
+
+      ["roundlet", 1047, "psychurgy", 2204, "extrarhythmical", 2231]
+      []
+      ["aluminize", 212, "climograph", 4124]
+      ["penintime", 1513, "endocarditis", 4084, "impermeator", 1669,
+       "coextension", 865]
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 18]
+
+RFC 8610                          CDDL                         June 2019
+
+
+3.5.  Maps
+
+   The syntax for specifying maps merits special attention, as well as a
+   number of optimizations and conveniences, as it is likely to be the
+   focal point of many specifications employing CDDL.  While the syntax
+   does not strictly distinguish struct and table usage of maps, it
+   caters specifically to each of them.
+
+   But first, let's reiterate a feature of CBOR that it has inherited
+   from JSON: the key/value pairs in CBOR maps have no fixed ordering.
+   (One could imagine situations where fixing the ordering may be of
+   use.  For example, a decoder could look for values related with
+   integer keys 1, 3, and 7.  If the order were fixed and the decoder
+   encounters the key 4 without having encountered key 3, it could
+   conclude that key 3 is not available without doing more complicated
+   bookkeeping.  Unfortunately, neither JSON nor CBOR supports this, so
+   no attempt was made to support this in CDDL either.)
+
+3.5.1.  Structs
+
+   The "struct" usage of maps is similar to the way JSON objects are
+   used in many JSON applications.
+
+   A map is defined in the same way as that for defining an array (see
+   Section 3.4), except for using curly braces "{}" instead of square
+   brackets "[]".
+
+   An occurrence indicator as specified in Section 3.2 is permitted for
+   each group entry.
+
+   The following is an example of a record with a structure embedded:
+
+       Geography = [
+         city           : tstr,
+         gpsCoordinates : GpsCoordinates,
+       ]
+
+       GpsCoordinates = {
+         longitude      : uint,            ; degrees, scaled by 10^7
+         latitude       : uint,            ; degrees, scaled by 10^7
+       }
+
+   When encoding, the Geography record is encoded using a CBOR array
+   with two members (the keys for the group entries are ignored),
+   whereas the GpsCoordinates structure is encoded as a CBOR map with
+   two key/value pairs.
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 19]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Types used in a structure can be defined in separate rules or just in
+   place (potentially placed inside parentheses, such as for choices).
+   For example:
+
+                           located-samples = {
+                             sample-point: int,
+                             samples: [+ float],
+                           }
+
+   where "located-samples" is the datatype to be used when referring to
+   the struct, and "sample-point" and "samples" are the keys to be used.
+   This is actually a complete example: an identifier that is followed
+   by a colon can be directly used as the text string for a member key
+   (we speak of a "bareword" member key), as can a double-quoted string
+   or a number.  (When other types -- in particular, types that contain
+   more than one value -- are used as the types of keys, they are
+   followed by a double arrow; see below.)
+
+   If a text string key does not match the syntax for an identifier (or
+   if the specifier just happens to prefer using double quotes), the
+   text string syntax can also be used in the member key position,
+   followed by a colon.  The above example could therefore have been
+   written with quoted strings in the member key positions.
+
+   More generally, types specified in ways other than those listed for
+   the cases described above can be used in a key-type position by
+   following them with a double arrow -- in particular, the double arrow
+   is necessary if a type is named by an identifier (which, when
+   followed by a colon, would be interpreted as a "bareword" and turned
+   into a text string).  A literal text string also gives rise to a type
+   (which contains a single value only -- the given string), so another
+   form for this example is:
+
+                         located-samples = {
+                           "sample-point" => int,
+                           "samples" => [+ float],
+                         }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 20]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   See Section 3.5.4 below for how the colon (":") shortcut described
+   here also adds some implied semantics.
+
+   A better way to demonstrate the use of the double arrow may be:
+
+             located-samples = {
+               sample-point: int,
+               samples: [+ float],
+               * equipment-type => equipment-tolerances,
+             }
+             equipment-type = [name: tstr, manufacturer: tstr]
+             equipment-tolerances = [+ [float, float]]
+
+   The example below defines a struct with optional entries: display
+   name (as a text string), the name components first name and family
+   name (as text strings), and age information (as an unsigned integer).
+
+                          PersonalData = {
+                            ? displayName: tstr,
+                            NameComponents,
+                            ? age: uint,
+                          }
+
+                          NameComponents = (
+                            ? firstName: tstr,
+                            ? familyName: tstr,
+                          )
+
+   Note that the group definition for NameComponents does not generate
+   another map; instead, all four keys are directly in the struct built
+   by PersonalData.
+
+   In this example, all key/value pairs are optional from the
+   perspective of CDDL.  With no occurrence indicator, an entry is
+   mandatory.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 21]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   If the addition of more entries not specified by the current
+   specification is desired, one can add this possibility explicitly:
+
+                          PersonalData = {
+                            ? displayName: tstr,
+                            NameComponents,
+                            ? age: uint,
+                            * tstr => any
+                          }
+
+                          NameComponents = (
+                            ? firstName: tstr,
+                            ? familyName: tstr,
+                          )
+
+            Figure 7: Personal Data: Example for Extensibility
+
+   The CDDL tool described in Appendix F generated the following as one
+   acceptable instance for this specification:
+
+         {"familyName": "agust", "antiforeignism": "pretzel",
+          "springbuck": "illuminatingly", "exuviae": "ephemeris",
+          "kilometrage": "frogfish"}
+
+   (See Section 3.9 for one way to explicitly identify an extension
+   point.)
+
+3.5.2.  Tables
+
+   A table can be specified by defining a map with entries where the
+   key type allows more than just a single value; for example:
+
+                         square-roots = {* x => y}
+                         x = int
+                         y = float
+
+   Here, the key in each key/value pair has datatype x (defined as int),
+   and the value has datatype y (defined as float).
+
+   If the specification does not need to restrict one of x or y (i.e.,
+   the application is free to choose per entry), it can be replaced by
+   the predefined name "any".
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 22]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   As another example, the following could be used as a conversion table
+   converting from an integer or float to a string:
+
+                      tostring = {* mynumber => tstr}
+                      mynumber = int / float
+
+3.5.3.  Non-deterministic Order
+
+   While the way arrays are matched is fully determined by the PEG
+   formalism (see Appendix A), matching is more complicated for maps, as
+   maps do not have an inherent order.  For each candidate name/value
+   pair that the PEG algorithm would try, a matching member is picked
+   out of the entire map.  For certain group expressions, more than one
+   member in the map may match.  Most often, this is inconsequential, as
+   the group expression tends to consume all matches:
+
+                            labeled-values = {
+                              ? fritz: number,
+                              * label => value
+                            }
+                            label = text
+                            value = number
+
+   Here, if any member with the key "fritz" is present, this will be
+   picked by the first entry of the group; all remaining text/number
+   members will be picked by the second entry (and if anything remains
+   unpicked, the map does not match).
+
+   However, it is possible to construct group expressions where what is
+   actually picked is indeterminate, but does matter:
+
+                            do-not-do-this = {
+                              int => int,
+                              int => 6,
+                            }
+
+   When this expression is matched against "{3: 5, 4: 6}", the first
+   group entry might pick off the "3: 5", leaving "4: 6" for matching
+   the second one.  Or it might pick off "4: 6", leaving nothing for the
+   second entry.  This pathological non-determinism is caused by
+   specifying "more general" before "more specific" and by having a
+   general rule that only consumes a subset of the map key/value pairs
+   that it is able to match -- both tend not to occur in real-world
+   specifications of maps.  At the time of writing, CDDL tools cannot
+   detect such cases automatically, and for the present version of the
+   CDDL specification, the specification writer is simply urged to not
+   write pathologically non-deterministic specifications.
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 23]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   (The astute reader will be reminded of what was called "ambiguous
+   content models" in the Standard Generalized Markup Language (SGML)
+   and "non-deterministic content models" in XML.  That problem is
+   related to the one described here, but the problem here is
+   specifically caused by the lack of order in maps, something that the
+   XML schema languages do not have to contend with.  Note that
+   RELAX NG's "interleave" pattern handles lack of order explicitly on
+   the specification side, while the instances in XML always have
+   determinate order.)
+
+3.5.4.  Cuts in Maps
+
+   The extensibility idiom discussed above for structs has one problem:
+
+                        extensible-map-example = {
+                          ? "optional-key" => int,
+                          * tstr => any
+                        }
+
+   In this example, there is one optional key "optional-key", which,
+   when present, maps to an integer.  There is also a wildcard for any
+   future additions.
+
+   Unfortunately, the data item
+
+                      { "optional-key": "nonsense" }
+
+   does match this specification: while the first entry of the group
+   does not match, the second one (the wildcard) does.  This may very
+   well be desirable (e.g., if a future extension is to be allowed to
+   extend the type of "optional-key"), but in many cases it isn't.
+
+   In anticipation of a more general potential feature called "cuts",
+   CDDL allows inserting a cut "^" into the definition of the map entry:
+
+                       extensible-map-example = {
+                         ? "optional-key" ^ => int,
+                         * tstr => any
+                       }
+
+   A cut in this position means that once the member key matches the
+   name part of an entry that carries a cut, other potential matches for
+   the key of the member that occur in later entries in the group of the
+   map are no longer allowed.  In other words, when a group entry would
+   pick a key/value pair based on just a matching key, it "locks in" the
+   pick -- this rule applies, independently of whether the value matches
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 24]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   as well, so when it does not, the entire map fails to match.  In
+   summary, the example above no longer matches the specification as
+   modified with the cut.
+
+   Since the desire for this kind of exclusive matching is so frequent,
+   the ":" shortcut is actually defined to include the cut semantics.
+   So, the preceding example (including the cut) can be written more
+   simply as:
+
+                        extensible-map-example = {
+                          ? "optional-key": int,
+                          * tstr => any
+                        }
+
+   or even shorter, using a bareword for the key:
+
+                        extensible-map-example = {
+                          ? optional-key: int,
+                          * tstr => any
+                        }
+
+3.6.  Tags
+
+   A type can make use of a CBOR tag (major type 6) by using the
+   representation type notation, giving #6.nnn(type) where nnn is an
+   unsigned integer giving the tag number and "type" is the type of the
+   data item being tagged.
+
+   For example, the following line from the CDDL prelude (Appendix D)
+   defines "biguint" as a type name for an unsigned bignum N:
+
+                           biguint = #6.2(bstr)
+
+   The tags defined by [RFC7049] are included in the prelude.
+   Additional tags registered since [RFC7049] was written need to be
+   added to a CDDL specification as needed; e.g., a binary Universally
+   Unique Identifier (UUID) tag could be referenced as "buuid" in a
+   specification after defining
+
+                            buuid = #6.37(bstr)
+
+   In the following example, usage of tag 32 for URIs is optional:
+
+                        my_uri = #6.32(tstr) / tstr
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 25]
+
+RFC 8610                          CDDL                         June 2019
+
+
+3.7.  Unwrapping
+
+   The group that is used to define a map or an array can often be
+   reused in the definition of another map or array.  Similarly, a type
+   defined as a tag carries an internal data item that one would like to
+   refer to.  In these cases, it is expedient to simply use the name of
+   the map, array, or tag type as a handle for the group or type defined
+   inside it.
+
+   The "unwrap" operator (written by preceding a name by a tilde
+   character "~") can be used to strip the type defined for a name by
+   one layer, exposing the underlying group (for maps and arrays) or
+   type (for tags).
+
+   For example, an application might want to define a basic header and
+   an advanced header.  Without unwrapping, this might be done as
+   follows:
+
+             basic-header-group = (
+               field1: int,
+               field2: text,
+             )
+
+             basic-header = [ basic-header-group ]
+
+             advanced-header = [
+               basic-header-group,
+               field3: bytes,
+               field4: number, ; as in the tagged type "time"
+             ]
+
+   Unwrapping simplifies this to:
+
+                            basic-header = [
+                              field1: int,
+                              field2: text,
+                            ]
+
+                            advanced-header = [
+                              ~basic-header,
+                              field3: bytes,
+                              field4: ~time,
+                            ]
+
+   (Note that leaving out the first unwrap operator in the latter
+   example would lead to nesting the basic-header in its own array
+   inside the advanced-header, while, with the unwrapped basic-header,
+   the definition of the group inside basic-header is essentially
+
+
+
+Birkholz, et al.             Standards Track                   [Page 26]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   repeated inside advanced-header, leading to a single array.  This can
+   be used for various applications often solved by inheritance in
+   programming languages.  The effect of unwrapping can also be
+   described as "threading in" the group or type inside the referenced
+   type, which suggested the thread-like "~" character.)
+
+3.8.  Controls
+
+   A _control_ allows relating a _target_ type with a _controller_ type
+   via a _control operator_.
+
+   The syntax for a control type is "target .control-operator
+   controller", where control operators are special identifiers prefixed
+   by a dot.  (Note that _target_ or _controller_ might need to be
+   parenthesized.)
+
+   A number of control operators are defined at this point.  Further
+   control operators may be defined by new versions of this
+   specification or by registering them according to the procedures in
+   Section 6.1.
+
+3.8.1.  Control Operator .size
+
+   A ".size" control controls the size of the target in bytes by the
+   control type.  The control is defined for text and byte strings,
+   where it directly controls the number of bytes in the string.  It is
+   also defined for unsigned integers (see below).  Figure 8 shows
+   example usage for byte strings.
+
+                   full-address = [[+ label], ip4, ip6]
+                   ip4 = bstr .size 4
+                   ip6 = bstr .size 16
+                   label = bstr .size (1..63)
+
+                    Figure 8: Control for Size in Bytes
+
+   When applied to an unsigned integer, the ".size" control restricts
+   the range of that integer by giving a maximum number of bytes that
+   should be needed in a computer representation of that unsigned
+   integer.  In other words, "uint .size N" is equivalent to
+   "0...BYTES_N", where BYTES_N == 256**N.
+
+     audio_sample = uint .size 3 ; 24-bit, equivalent to 0...16777216
+
+                Figure 9: Control for Integer Size in Bytes
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 27]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Note that, as with value restrictions in CDDL, this control is not a
+   representation constraint; a number that fits into fewer bytes can
+   still be represented in that form, and an inefficient implementation
+   could use a longer form (unless that is restricted by some format
+   constraints outside of CDDL, such as the rules in Section 3.9 of
+   [RFC7049]).
+
+3.8.2.  Control Operator .bits
+
+   A ".bits" control on a byte string indicates that, in the target,
+   only the bits numbered by a number in the control type are allowed to
+   be set.  (Bits are counted the usual way, bit number "n" being set in
+   "str" meaning that "(str[n >> 3] & (1 << (n & 7))) != 0".)
+   Similarly, a ".bits" control on an unsigned integer "i" indicates
+   that for all unsigned integers "n" where "(i & (1 << n)) != 0", "n"
+   must be in the control type.
+
+                      tcpflagbytes = bstr .bits flags
+                      flags = &(
+                        fin: 8,
+                        syn: 9,
+                        rst: 10,
+                        psh: 11,
+                        ack: 12,
+                        urg: 13,
+                        ece: 14,
+                        cwr: 15,
+                        ns: 0,
+                      ) / (4..7) ; data offset bits
+
+                      rwxbits = uint .bits rwx
+                      rwx = &(r: 2, w: 1, x: 0)
+
+                Figure 10: Control for What Bits Can Be Set
+
+   The CDDL tool described in Appendix F generates the following ten
+   example instances for "tcpflagbytes":
+
+      h'906d' h'01fc' h'8145' h'01b7' h'013d' h'409f' h'018e' h'c05f'
+      h'01fa' h'01fe'
+
+   These examples do not illustrate that the above CDDL specification
+   does not explicitly specify a size of two bytes: a valid all-clear
+   instance of flag bytes could be "h''" or "h'00'" or even "h'000000'"
+   as well.
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 28]
+
+RFC 8610                          CDDL                         June 2019
+
+
+3.8.3.  Control Operator .regexp
+
+   A ".regexp" control indicates that the text string given as a target
+   needs to match the XML Schema Definition (XSD) regular expression
+   given as a value in the control type.  XSD regular expressions are
+   defined in Appendix F of [W3C.REC-xmlschema-2-20041028].
+
+     nai = tstr .regexp "[A-Za-z0-9]+@[A-Za-z0-9]+(\\.[A-Za-z0-9]+)+"
+
+                   Figure 11: Control with an XSD regexp
+
+   An example matching this regular expression:
+
+                       "N1@CH57HF.4Znqe0.dYJRN.igjf"
+
+3.8.3.1.  Usage Considerations
+
+   Note that XSD regular expressions do not support the usual \x or \u
+   escapes for hexadecimal expression of bytes or Unicode code points.
+   However, in CDDL the XSD regular expressions are contained in text
+   strings, the literal notation for which provides \u escapes; this
+   should suffice for most applications that use regular expressions for
+   text strings.  (Note that this also means that there is one level of
+   string escaping before the XSD escaping rules are applied.)
+
+   XSD regular expressions support character class subtraction, a
+   feature often not found in regular expression libraries;
+   specification writers may want to use this feature sparingly.
+   Similar considerations apply to Unicode character classes; where
+   these are used, the specification that employs CDDL SHOULD identify
+   which Unicode versions are addressed.
+
+   Other surprises for infrequent users of XSD regular expressions may
+   include the following:
+
+   o  No direct support for case insensitivity.  While case
+      insensitivity has gone mostly out of fashion in protocol design,
+      it is sometimes needed and then needs to be expressed manually as
+      in "[Cc][Aa][Ss][Ee]".
+
+   o  The support for popular character classes such as \w and \d is
+      based on Unicode character properties; this is often not what is
+      desired in an ASCII-based protocol and thus might lead to
+      surprises.  (\s and \S do have their more conventional meanings,
+      and "." matches any character but the line-ending characters \r
+      or \n.)
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 29]
+
+RFC 8610                          CDDL                         June 2019
+
+
+3.8.3.2.  Discussion
+
+   There are many flavors of regular expression in use in the
+   programming community.  For instance, Perl-Compatible Regular
+   Expressions (PCREs) are widely used and probably are more useful than
+   XSD regular expressions.  However, there is no normative reference
+   for PCREs that could be used in the present document.  Instead, we
+   opt for XSD regular expressions for now.  There is precedent for that
+   choice in the IETF, e.g., in YANG [RFC7950].
+
+   Note that CDDL uses controls as its main extension point.  This
+   creates the opportunity to add further regular expression formats in
+   addition to the one referenced here, if desired.  As an example, a
+   proposal for a ".pcre" control is defined in [CDDL-Freezer].
+
+3.8.4.  Control Operators .cbor and .cborseq
+
+   A ".cbor" control on a byte string indicates that the byte string
+   carries a CBOR-encoded data item.  Decoded, the data item matches the
+   type given as the right-hand-side argument (type1 in the following
+   example).
+
+      "bytes .cbor type1"
+
+   Similarly, a ".cborseq" control on a byte string indicates that the
+   byte string carries a sequence of CBOR-encoded data items.  When the
+   data items are taken as an array, the array matches the type given as
+   the right-hand-side argument (type2 in the following example).
+
+      "bytes .cborseq type2"
+
+   (The conversion of the encoded sequence to an array can be effected,
+   for instance, by wrapping the byte string between the two bytes 0x9f
+   and 0xff and decoding the wrapped byte string as a CBOR-encoded
+   data item.)
+
+3.8.5.  Control Operators .within and .and
+
+   A ".and" control on a type indicates that the data item matches both
+   the left-hand-side type and the type given as the right-hand side.
+   (Formally, the resulting type is the intersection of the two types
+   given.)
+
+      "type1 .and type2"
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 30]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   A variant of the ".and" control is the ".within" control, which
+   expresses an additional intent: the left-hand-side type is meant to
+   be a subset of the right-hand-side type.
+
+      "type1 .within type2"
+
+   While both forms have the identical formal semantics (intersection),
+   the intention of the ".within" form is that the right-hand side gives
+   guidance to the types allowed on the left-hand side, which typically
+   is a socket (Section 3.9):
+
+        message = $message .within message-structure
+        message-structure = [message_type, *message_option]
+        message_type = 0..255
+        message_option = any
+
+        $message /= [3, dough: text, topping: [* text]]
+        $message /= [4, noodles: text, sauce: text, parmesan: bool]
+
+   For ".within", a tool might flag an error if type1 allows data items
+   that are not allowed by type2.  In contrast, for ".and", there is no
+   expectation that type1 is already a subset of type2.
+
+3.8.6.  Control Operators .lt, .le, .gt, .ge, .eq, .ne, and .default
+
+   The controls .lt, .le, .gt, .ge, .eq, and .ne specify a constraint
+   on the left-hand-side type to be a value less than, less than or
+   equal to, greater than, greater than or equal to, equal to, or not
+   equal to a value given as a right-hand-side type (containing just
+   that single value).  In the present specification, the first four
+   controls (.lt, .le, .gt, and .ge) are defined only for numeric types,
+   as these have a natural ordering relationship.
+
+                     speed = number .ge 0  ; unit: m/s
+
+   .ne and .eq are defined for both numeric values and values of other
+   types.  If one of the values is not of a numeric type, equality is
+   determined as follows: text strings are equal (satisfy .eq / do not
+   satisfy .ne) if they are bytewise identical; the same applies for
+   byte strings.  Arrays are equal if they have the same number of
+   elements, all of which are equal pairwise in order between the
+   arrays.  Maps are equal if they have the same number of key/value
+   pairs, and there is pairwise equality between the key/value pairs
+   between the two maps.  Tagged values are equal if they both have the
+   same tag and the values are equal.  Values of simple types match if
+   they are the same values.  Numeric types that occur within arrays,
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 31]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   maps, or tagged values are equal if their numeric value is equal and
+   they are both integers or both floating-point values.  All other
+   cases are not equal (e.g., comparing a text string with a byte
+   string).
+
+   A variant of the ".ne" control is the ".default" control, which
+   expresses an additional intent: the value specified by the
+   right-hand-side type is intended as a default value for the
+   left-hand-side type given, and the implied .ne control is there to
+   prevent this value from being sent over the wire.  This control is
+   only meaningful when the control type is used in an optional context;
+   otherwise, there would be no way to make use of the default value.
+
+               timer = {
+                 time: uint,
+                 ? displayed-step: (number .gt 0) .default 1
+               }
+
+3.9.  Socket/Plug
+
+   For both type choices and group choices, a mechanism is defined that
+   facilitates starting out with empty choices and assembling them
+   later, potentially in separate files that are concatenated to build
+   the full specification.
+
+   Per convention, CDDL extension points are marked with a leading
+   dollar sign (types) or two leading dollar signs (groups).  Tools
+   honor that convention by not raising an error if such a type or group
+   is not defined at all; the symbol is then taken to be an empty type
+   choice (group choice), i.e., no choice is available.
+
+            tcp-header = {seq: uint, ack: uint, * $$tcp-option}
+
+            ; later, in a different file
+
+            $$tcp-option //= (
+            sack: [+(left: uint, right: uint)]
+            )
+
+            ; and, maybe in another file
+
+            $$tcp-option //= (
+            sack-permitted: true
+            )
+
+   Names that start with a single "$" are "type sockets", starting out
+   as an empty type, and intended to be extended via "/=".  Names that
+   start with a double "$$" are "group sockets", starting out as an
+
+
+
+Birkholz, et al.             Standards Track                   [Page 32]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   empty group choice, and intended to be extended via "//=".  In either
+   case, it is not an error if there is no definition for a socket at
+   all; this then means there is no way to satisfy the rule (i.e., the
+   choice is empty).
+
+   As a convention, all definitions (plugs) for socket names must be
+   augmentations, i.e., they must be using "/=" and "//=", respectively.
+
+   To pick up the example illustrated in Figure 7, the socket/plug
+   mechanism could be used as shown in Figure 12:
+
+                     PersonalData = {
+                       ? displayName: tstr,
+                       NameComponents,
+                       ? age: uint,
+                       * $$personaldata-extensions
+                     }
+
+                     NameComponents = (
+                       ? firstName: tstr,
+                       ? familyName: tstr,
+                     )
+
+                     ; The above already works as is.
+                     ; But then, we can add later:
+
+                     $$personaldata-extensions //= (
+                       favorite-salsa: tstr,
+                     )
+
+                     ; and again, somewhere else:
+
+                     $$personaldata-extensions //= (
+                       shoesize: uint,
+                     )
+
+     Figure 12: Personal Data Example: Using Socket/Plug Extensibility
+
+3.10.  Generics
+
+   Using angle brackets, the left-hand side of a rule can add formal
+   parameters after the name being defined, as in:
+
+      messages = message<"reboot", "now"> / message<"sleep", 1..100>
+      message<t, v> = {type: t, value: v}
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 33]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   When using a generic rule, the formal parameters are bound to the
+   actual arguments supplied (also using angle brackets), within the
+   scope of the generic rule (as if there were a rule of the form
+   parameter = argument).
+
+   Generic rules can be used for establishing names for both types and
+   groups.
+
+   (At this time, there are some limitations to the nesting of generics
+   in the CDDL tool described in Appendix F.)
+
+3.11.  Operator Precedence
+
+   As with any language that has multiple syntactic features such as
+   prefix and infix operators, CDDL has operators that bind more tightly
+   than others.  This is becoming more complicated than, say, in ABNF,
+   as CDDL has both types and groups, with operators that are specific
+   to these concepts.  Type operators (such as "/" for type choice)
+   operate on types, while group operators (such as "//" for group
+   choice) operate on groups.  Types can simply be used in groups, but
+   groups need to be bracketed (as arrays or maps) to become types.  So,
+   type operators naturally bind closer than group operators.
+
+   For instance, in
+
+      t = [group1]
+      group1 = (a / b // c / d)
+      a = 1 b = 2 c = 3 d = 4
+
+   group1 is a group choice between the type choice of a and b and the
+   type choice of c and d.  This becomes more relevant once member keys
+   and/or occurrences are added in:
+
+      t = {group2}
+      group2 = (? ab: a / b // cd: c / d)
+      a = 1 b = 2 c = 3 d = 4
+
+   is a group choice between the optional member "ab" of type a or b and
+   the member "cd" of type c or d.  Note that the optionality is
+   attached to the first choice ("ab"), not to the second choice.
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 34]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Similarly, in
+
+      t = [group3]
+      group3 = (+ a / b / c)
+      a = 1 b = 2 c = 3
+
+   group3 is a repetition of a type choice between a, b, and c; if just
+   a is to be repeatable, a group choice is needed to focus the
+   occurrence:
+
+      t = [group4]
+      group4 = (+ a // b / c)
+      a = 1 b = 2 c = 3
+
+   group4 is a group choice between a repeatable a and a single b or c.
+
+   A comment has been that the semantics of group3 could be
+   counterintuitive.  In general, as with many other languages with
+   operator precedence rules, the specification writer is encouraged not
+   to rely on them, but to insert parentheses liberally to guide readers
+   that are not familiar with CDDL precedence rules:
+
+      t = [group4a]
+      group4a = ((+ a) // (b / c))
+      a = 1 b = 2 c = 3
+
+   The operator precedences, in sequence of loose to tight binding, are
+   defined in Appendix B and summarized in Table 1.  (Arities given are
+   1 for unary prefix operators and 2 for binary infix operators.)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 35]
+
+RFC 8610                          CDDL                         June 2019
+
+
+       +----------+-------+---------------------------+------------+
+       | Operator | Arity | Operates on               | Precedence |
+       +----------+-------+---------------------------+------------+
+       |    =     |   2   | name = type, name = group |     1      |
+       |    /=    |   2   | name /= type              |     1      |
+       |   //=    |   2   | name //= group            |     1      |
+       |    //    |   2   | group // group            |     2      |
+       |    ,     |   2   | group, group              |     3      |
+       |    *     |   1   | * group                   |     4      |
+       |   n*m    |   1   | n*m group                 |     4      |
+       |    +     |   1   | + group                   |     4      |
+       |    ?     |   1   | ? group                   |     4      |
+       |    =>    |   2   | type => type              |     5      |
+       |    :     |   2   | name: type                |     5      |
+       |    /     |   2   | type / type               |     6      |
+       |    ..    |   2   | type..type                |     7      |
+       |   ...    |   2   | type...type               |     7      |
+       |  .ctrl   |   2   | type .ctrl type           |     7      |
+       |    &     |   1   | &group                    |     8      |
+       |    ~     |   1   | ~type                     |     8      |
+       +----------+-------+---------------------------+------------+
+
+                 Table 1: Summary of Operator Precedences
+
+4.  Making Use of CDDL
+
+   In this section, we discuss several potential ways to employ CDDL.
+
+4.1.  As a Guide for a Human User
+
+   CDDL can be used to efficiently define the layout of CBOR data, such
+   that a human implementer can easily see how data is supposed to be
+   encoded.
+
+   Since CDDL maps parts of the CBOR data to human-readable names, tools
+   could be built that use CDDL to provide a human-friendly
+   representation of the CBOR data and allow them to edit such data
+   while remaining compliant with its CDDL definition.
+
+4.2.  For Automated Checking of CBOR Data Structures
+
+   CDDL has been specified such that a machine can handle the CDDL
+   definition and related CBOR data (and, thus, also JSON data).  For
+   example, a machine could use CDDL to check whether or not CBOR data
+   is compliant with its definition.
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 36]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   The need for thoroughness of such compliance checking depends on the
+   application.  For example, an application may decide not to check the
+   data structure at all and use the CDDL definition solely as a means
+   to indicate the structure of the data to the programmer.
+
+   On the other hand, the application may also implement a checking
+   mechanism that goes as far as checking that all mandatory map members
+   are available.
+
+   The matter of how far the data description must be enforced by an
+   application is left to the designers and implementers of that
+   application, keeping in mind related security considerations.
+
+   In no case is it intended that a CDDL tool would be "writing code"
+   for an implementation.
+
+4.3.  For Data Analysis Tools
+
+   In the long run, it can be expected that more and more data will be
+   stored using the CBOR data format.
+
+   Where there is data, there is data analysis and the need to process
+   such data automatically.  CDDL can be used for such automated data
+   processing, allowing tools to verify data, clean it, and extract
+   particular parts of interest from it.
+
+   Since CBOR is designed with constrained devices in mind, a likely use
+   of it would be small sensors.  An interesting use would thus be
+   automated analysis of sensor data.
+
+5.  Security Considerations
+
+   This document presents a content rules language for expressing CBOR
+   data structures.  As such, it does not bring any security issues on
+   itself, although specifications of protocols that use CBOR naturally
+   need security analyses when defined.  General guidelines for writing
+   security considerations are defined in [RFC3552] (BCP 72).
+   Specifications using CDDL to define CBOR structures in protocols need
+   to follow those guidelines.  Additional topics that could be
+   considered in a security considerations section for a specification
+   that uses CDDL to define CBOR structures include the following:
+
+   o  Where could the language maybe cause confusion in a way that will
+      enable security issues?
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 37]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   o  Where a CDDL matcher is part of the implementation of a system,
+      the security of the system ought not depend on the correctness of
+      the CDDL specification or CDDL implementation without any further
+      defenses in place.
+
+   o  Where the CDDL specification includes extension points, the impact
+      of extensions on the security of the system needs to be carefully
+      considered.
+
+   Writers of CDDL specifications are strongly encouraged to value
+   clarity and transparency of the specification over its elegance.
+   Keep it as simple as possible while still expressing the needed data
+   model.
+
+   A related observation about formal description techniques in general
+   that is strongly recommended to be kept in mind by writers of CDDL
+   specifications: just because CDDL makes it easier to handle
+   complexity in a specification, that does not make that complexity
+   somehow less bad (except maybe on the level of the humans having to
+   grasp the complex structure while reading the spec).
+
+6.  IANA Considerations
+
+6.1.  CDDL Control Operators Registry
+
+   IANA has created a registry for control operators (Section 3.8).  The
+   "CDDL Control Operators" registry has been created within the
+   "Concise Data Definition Language (CDDL)" registry.
+
+   Each entry in the subregistry must include the name of the control
+   operator (by convention given with the leading dot) and a reference
+   to its documentation.  Names must be composed of the leading dot
+   followed by a text string conforming to the production "id" in
+   Appendix B.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 38]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Initial entries in this registry are as follows:
+
+                       +----------+---------------+
+                       | Name     | Documentation |
+                       +----------+---------------+
+                       | .size    | RFC 8610      |
+                       | .bits    | RFC 8610      |
+                       | .regexp  | RFC 8610      |
+                       | .cbor    | RFC 8610      |
+                       | .cborseq | RFC 8610      |
+                       | .within  | RFC 8610      |
+                       | .and     | RFC 8610      |
+                       | .lt      | RFC 8610      |
+                       | .le      | RFC 8610      |
+                       | .gt      | RFC 8610      |
+                       | .ge      | RFC 8610      |
+                       | .eq      | RFC 8610      |
+                       | .ne      | RFC 8610      |
+                       | .default | RFC 8610      |
+                       +----------+---------------+
+
+   All other control operator names are Unassigned.
+
+   The IANA policy for additions to this registry is "Specification
+   Required" as defined in [RFC8126] (which involves an Expert Review)
+   for names that do not include an internal dot and "IETF Review" for
+   names that do include an internal dot.  The expert reviewer is
+   specifically instructed that other Standards Development
+   Organizations (SDOs) may want to define control operators that are
+   specific to their fields (e.g., based on a binary syntax already in
+   use at the SDO); the review process should strive to facilitate such
+   an undertaking.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 39]
+
+RFC 8610                          CDDL                         June 2019
+
+
+7.  References
+
+7.1.  Normative References
+
+   [ISO6093]  ISO, "Information processing -- Representation of
+              numerical values in character strings for information
+              interchange", ISO 6093, 1985.
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <https://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC3552]  Rescorla, E. and B. Korver, "Guidelines for Writing RFC
+              Text on Security Considerations", BCP 72, RFC 3552,
+              DOI 10.17487/RFC3552, July 2003,
+              <https://www.rfc-editor.org/info/rfc3552>.
+
+   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of
+              ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629,
+              November 2003, <https://www.rfc-editor.org/info/rfc3629>.
+
+   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
+              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
+              <https://www.rfc-editor.org/info/rfc4648>.
+
+   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+              Specifications: ABNF", STD 68, RFC 5234,
+              DOI 10.17487/RFC5234, January 2008,
+              <https://www.rfc-editor.org/info/rfc5234>.
+
+   [RFC7049]  Bormann, C. and P. Hoffman, "Concise Binary Object
+              Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
+              October 2013, <https://www.rfc-editor.org/info/rfc7049>.
+
+   [RFC7493]  Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
+              DOI 10.17487/RFC7493, March 2015,
+              <https://www.rfc-editor.org/info/rfc7493>.
+
+   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
+              Writing an IANA Considerations Section in RFCs", BCP 26,
+              RFC 8126, DOI 10.17487/RFC8126, June 2017,
+              <https://www.rfc-editor.org/info/rfc8126>.
+
+   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in
+              RFC 2119 Key Words", BCP 14, RFC 8174,
+              DOI 10.17487/RFC8174, May 2017,
+              <https://www.rfc-editor.org/info/rfc8174>.
+
+
+
+Birkholz, et al.             Standards Track                   [Page 40]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
+              Interchange Format", STD 90, RFC 8259,
+              DOI 10.17487/RFC8259, December 2017,
+              <https://www.rfc-editor.org/info/rfc8259>.
+
+   [W3C.REC-xmlschema-2-20041028]
+              Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
+              Second Edition", World Wide Web Consortium Recommendation
+              REC-xmlschema-2-20041028, October 2004,
+              <https://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
+
+7.2.  Informative References
+
+   [CDDL-Freezer]
+              Bormann, C., "A feature freezer for the Concise Data
+              Definition Language (CDDL)", Work in Progress,
+              draft-bormann-cbor-cddl-freezer-01, August 2018.
+
+   [GRASP]    Bormann, C., Carpenter, B., Ed., and B. Liu, Ed., "A
+              Generic Autonomic Signaling Protocol (GRASP)", Work in
+              Progress, draft-ietf-anima-grasp-15, July 2017.
+
+   [IEEE754]  IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE
+              Std 754-2008.
+
+   [JCR]      Newton, A. and P. Cordell, "A Language for Rules
+              Describing JSON Content", Work in Progress,
+              draft-newton-json-content-rules-09, September 2017.
+
+   [PEG]      Ford, B., "Parsing expression grammars: a recognition-
+              based syntactic foundation", Proceedings of the 31st ACM
+              SIGPLAN-SIGACT symposium on Principles of programming
+              languages - POPL '04, DOI 10.1145/964001.964011,
+              January 2004.
+
+   [RELAXNG]  ISO/IEC, "Information technology -- Document Schema
+              Definition Language (DSDL) -- Part 2: Regular-grammar-
+              based validation -- RELAX NG", ISO/IEC 19757-2,
+              December 2008.
+
+   [RFC7071]  Borenstein, N. and M. Kucherawy, "A Media Type for
+              Reputation Interchange", RFC 7071, DOI 10.17487/RFC7071,
+              November 2013, <https://www.rfc-editor.org/info/rfc7071>.
+
+   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
+              RFC 7950, DOI 10.17487/RFC7950, August 2016,
+              <https://www.rfc-editor.org/info/rfc7950>.
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 41]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   [RFC8007]  Murray, R. and B. Niven-Jenkins, "Content Delivery Network
+              Interconnection (CDNI) Control Interface / Triggers",
+              RFC 8007, DOI 10.17487/RFC8007, December 2016,
+              <https://www.rfc-editor.org/info/rfc8007>.
+
+   [RFC8152]  Schaad, J., "CBOR Object Signing and Encryption (COSE)",
+              RFC 8152, DOI 10.17487/RFC8152, July 2017,
+              <https://www.rfc-editor.org/info/rfc8152>.
+
+   [RFC8428]  Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
+              Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
+              DOI 10.17487/RFC8428, August 2018,
+              <https://www.rfc-editor.org/info/rfc8428>.
+
+   [YAML]     Ben-Kiki, O., Evans, C., and I. Net, "YAML Ain't Markup
+              Language (YAML[TM]) Version 1.2", 3rd Edition,
+              October 2009, <https://yaml.org/spec/1.2/spec.html>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 42]
+
+RFC 8610                          CDDL                         June 2019
+
+
+Appendix A.  Parsing Expression Grammars (PEGs)
+
+   This appendix is normative.
+
+   Since the 1950s, many grammar notations are based on Backus-Naur Form
+   (BNF), a notation for context-free grammars (CFGs) within Chomsky's
+   generative system of grammars.  The Augmented Backus-Naur Form (ABNF)
+   [RFC5234], widely used in IETF specifications and also inspiring the
+   syntax of CDDL, is an example of this.
+
+   Generative grammars can express ambiguity well, but this very
+   property may make them hard to use in recognition systems, spawning a
+   number of subdialects that pose constraints on generative grammars to
+   be used with parser generators; this scenario may be hard for the
+   specification writer to manage.
+
+   PEGs [PEG] provide an alternative formal foundation for describing
+   grammars that emphasizes recognition over generation and resolves
+   what would have been ambiguity in generative systems by introducing
+   the concept of "prioritized choice".
+
+   The notation for PEGs is quite close to BNF, with the usual "Extended
+   BNF" features, such as repetition, added.  However, where BNF uses
+   the unordered (symmetrical) choice operator "|" (incidentally notated
+   as "/" in ABNF), PEG provides a prioritized choice operator "/".  The
+   two alternatives listed are to be tested in left-to-right order,
+   locking in the first successful match and disregarding any further
+   potential matches within the choice (but not disabling alternatives
+   in choices containing this choice, as a cut (Section 3.5.4) would).
+
+   For example, the ABNF expressions
+
+      A = "a" "b" / "a"    (1)
+
+   and
+
+      A = "a" / "a" "b"    (2)
+
+   are equivalent in ABNF's original generative framework but are very
+   different in PEG: in (2), the second alternative will never match, as
+   any input string starting with an "a" will already succeed in the
+   first alternative, locking in the match.
+
+   Similarly, the occurrence indicators ("?", "*", "+") are "greedy" in
+   PEG, i.e., they consume as much input as they match (and, as a
+   consequence, "a* a" in PEG notation or "*a a" in CDDL syntax never
+   can match anything, as all input matching "a" is already consumed by
+   the initial "a*", leaving nothing to match the second "a").
+
+
+
+Birkholz, et al.             Standards Track                   [Page 43]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   Incidentally, the grammar of CDDL itself, as written in ABNF in
+   Appendix B, can be interpreted both (1) in the generative framework
+   on which RFC 5234 is based and (2) as a PEG.  This was made possible
+   by ordering the choices in the grammar such that a successful match
+   made on the left-hand side of a "/" operator is always the intended
+   match, instead of relying on the power of symmetrical choices (for
+   example, note the sequence of alternatives in the rule for "uint",
+   where the lone zero is behind the longer match alternatives that
+   start with a zero).
+
+   The syntax used for expressing the PEG component of CDDL is based on
+   ABNF, interpreted in the obvious way with PEG semantics.  The ABNF
+   convention of notating occurrence indicators before the controlled
+   primary, and of allowing numeric values for minimum and maximum
+   occurrence around a "*" sign, is copied.  While PEG is only about
+   characters, CDDL has a richer set of elements, such as types and
+   groups.  Specifically, the following constructs map:
+
+       +-------+-------+-------------------------------------------+
+       | CDDL  | PEG   | Remark                                    |
+       +-------+-------+-------------------------------------------+
+       | "="   | "<-"  | /= and //= are abbreviations              |
+       | "//"  | "/"   | prioritized choice                        |
+       | "/"   | "/"   | prioritized choice, limited to types only |
+       | "?" P | P "?" | zero or one                               |
+       | "*" P | P "*" | zero or more                              |
+       | "+" P | P "+" | one or more                               |
+       | A B   | A B   | sequence                                  |
+       | A, B  | A B   | sequence, comma is decoration only        |
+       +-------+-------+-------------------------------------------+
+
+   The literal notation and the use of square brackets, curly braces,
+   tildes, ampersands, and hash marks are specific to CDDL and unrelated
+   to the conventional PEG notation.  The DOT (".") from PEG is replaced
+   by the unadorned "#" or its alias "any".  Also, CDDL does not provide
+   the syntactic predicate operators NOT ("!") or AND ("&") from PEG,
+   reducing expressiveness as well as complexity.
+
+   For more details about PEG's theoretical foundation and interesting
+   properties of the operators such as associativity and distributivity,
+   the reader is referred to [PEG].
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 44]
+
+RFC 8610                          CDDL                         June 2019
+
+
+Appendix B.  ABNF Grammar
+
+   This appendix is normative.
+
+   The following is a formal definition of the CDDL syntax in ABNF
+   [RFC5234].  Note that, as is defined in ABNF, the quote-delimited
+   strings below are case insensitive (while string values and names are
+   case sensitive in CDDL).
+
+     cddl = S 1*(rule S)
+     rule = typename [genericparm] S assignt S type
+          / groupname [genericparm] S assigng S grpent
+
+     typename = id
+     groupname = id
+
+     assignt = "=" / "/="
+     assigng = "=" / "//="
+
+     genericparm = "<" S id S *("," S id S ) ">"
+     genericarg = "<" S type1 S *("," S type1 S ) ">"
+
+     type = type1 *(S "/" S type1)
+
+     type1 = type2 [S (rangeop / ctlop) S type2]
+     ; space may be needed before the operator if type2 ends in a name
+
+     type2 = value
+           / typename [genericarg]
+           / "(" S type S ")"
+           / "{" S group S "}"
+           / "[" S group S "]"
+           / "~" S typename [genericarg]
+           / "&" S "(" S group S ")"
+           / "&" S groupname [genericarg]
+           / "#" "6" ["." uint] "(" S type S ")"
+           / "#" DIGIT ["." uint]                ; major/ai
+           / "#"                                 ; any
+
+     rangeop = "..." / ".."
+
+     ctlop = "." id
+
+     group = grpchoice *(S "//" S grpchoice)
+
+     grpchoice = *(grpent optcom)
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 45]
+
+RFC 8610                          CDDL                         June 2019
+
+
+     grpent = [occur S] [memberkey S] type
+            / [occur S] groupname [genericarg]  ; preempted by above
+            / [occur S] "(" S group S ")"
+
+     memberkey = type1 S ["^" S] "=>"
+               / bareword S ":"
+               / value S ":"
+
+     bareword = id
+
+     optcom = S ["," S]
+
+     occur = [uint] "*" [uint]
+           / "+"
+           / "?"
+
+     uint = DIGIT1 *DIGIT
+          / "0x" 1*HEXDIG
+          / "0b" 1*BINDIG
+          / "0"
+
+     value = number
+           / text
+           / bytes
+
+     int = ["-"] uint
+
+     ; This is a float if it has fraction or exponent; int otherwise
+     number = hexfloat / (int ["." fraction] ["e" exponent ])
+     hexfloat = ["-"] "0x" 1*HEXDIG ["." 1*HEXDIG] "p" exponent
+     fraction = 1*DIGIT
+     exponent = ["+"/"-"] 1*DIGIT
+
+     text = %x22 *SCHAR %x22
+     SCHAR = %x20-21 / %x23-5B / %x5D-7E / %x80-10FFFD / SESC
+     SESC = "\" (%x20-7E / %x80-10FFFD)
+
+     bytes = [bsqual] %x27 *BCHAR %x27
+     BCHAR = %x20-26 / %x28-5B / %x5D-10FFFD / SESC / CRLF
+     bsqual = "h" / "b64"
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 46]
+
+RFC 8610                          CDDL                         June 2019
+
+
+     id = EALPHA *(*("-" / ".") (EALPHA / DIGIT))
+     ALPHA = %x41-5A / %x61-7A
+     EALPHA = ALPHA / "@" / "_" / "$"
+     DIGIT = %x30-39
+     DIGIT1 = %x31-39
+     HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
+     BINDIG = %x30-31
+
+     S = *WS
+     WS = SP / NL
+     SP = %x20
+     NL = COMMENT / CRLF
+     COMMENT = ";" *PCHAR CRLF
+     PCHAR = %x20-7E / %x80-10FFFD
+     CRLF = %x0A / %x0D.0A
+
+                           Figure 13: CDDL ABNF
+
+   Note that this ABNF does not attempt to reflect the detailed rules of
+   what can be in a prefixed byte string.
+
+Appendix C.  Matching Rules
+
+   This appendix is normative.
+
+   In this appendix, we go through the ABNF syntax rules defined in
+   Appendix B and briefly describe the matching semantics of each
+   syntactic feature.  In this context, an instance (data item)
+   "matches" a CDDL specification if it is allowed by the CDDL
+   specification; this is then broken down into parts of specifications
+   (type and group expressions) and parts of instances (data items).
+
+   cddl = S 1*(rule S)
+
+   A CDDL specification is a sequence of one or more rules.  Each rule
+   gives a name to a right-hand-side expression, either a CDDL type or a
+   CDDL group.  Rule names can be used in the rule itself and/or other
+   rules (and tools can output warnings if that is not the case).  The
+   order of the rules is significant only in two cases:
+
+   1.  The first rule defines the semantics of the entire specification;
+       hence, there is no need to give that root rule a special name or
+       special syntax in the language (as, for example, with "start" in
+       RELAX NG); its name can therefore be chosen to be descriptive.
+       (As with all other rule names, the name of the initial rule may
+       be used in itself or in other rules.)
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 47]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   2.  Where a rule contributes to a type or group choice (using "/=" or
+       "//="), that choice is populated in the order the rules are
+       given; see below.
+
+   rule = typename [genericparm] S assignt S type
+        / groupname [genericparm] S assigng S grpent
+
+   typename = id
+   groupname = id
+
+   A rule defines a name for a type expression (production "type") or
+   for a group expression (production "grpent"), with the intention that
+   the semantics does not change when the name is replaced by its
+   (parenthesized if needed) definition.  Note that whether the name
+   defined by a rule stands for a type or a group isn't always
+   determined by syntax alone: e.g., "a = b" can make "a" a type if "b"
+   is a type, or a group if "b" is a group.  More subtly, in "a = (b)",
+   "a" may be used as a type if "b" is a type, or as a group both when
+   "b" is a group and when "b" is a type (a good convention to make the
+   latter case stand out to the human reader is to write "a = (b,)").
+   (Note that the same dual meaning of parentheses applies within an
+   expression but often can be resolved by the context of the
+   parenthesized expression.  On the more general point, it may not be
+   clear immediately either whether "b" stands for a group or a type --
+   this semantic processing may need to span several levels of rule
+   definitions before a determination can be made.)
+
+   assignt = "=" / "/="
+   assigng = "=" / "//="
+
+   A plain equals sign defines the rule name as the equivalent of the
+   expression to the right; it is an error if the name was already
+   defined with a different expression.  A "/=" or "//=" extends a named
+   type or a group by additional choices; a number of these could be
+   replaced by collecting all the right-hand sides and creating a single
+   rule with a type choice or a group choice built from the right-hand
+   sides in the order of the rules given.  (It is not an error to extend
+   a rule name that has not yet been defined; this makes the right-hand
+   side the first entry in the choice being created.)
+
+   genericparm = "<" S id S *("," S id S ) ">"
+   genericarg = "<" S type1 S *("," S type1 S ) ">"
+
+   Rule names can have generic parameters, which cause temporary
+   assignments within the right-hand sides to the parameter names from
+   the arguments given when citing the rule name.
+
+   type = type1 *(S "/" S type1)
+
+
+
+Birkholz, et al.             Standards Track                   [Page 48]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   A type can be given as a choice between one or more types.  The
+   choice matches a data item if the data item matches any one of the
+   types given in the choice.  The choice uses PEG semantics as
+   discussed in Appendix A: the first choice that matches wins.  (As a
+   result, the order of rules that contribute to a single rule name can
+   very well matter.)
+
+   type1 = type2 [S (rangeop / ctlop) S type2]
+
+   Two types can be combined with a range operator (see below) or a
+   control operator (see Section 3.8).
+
+   type2 = value
+
+   A type can be just a single value (such as 1 or "icecream" or
+   h'0815'), which matches only a data item with that specific value (no
+   conversions defined),
+
+      / typename [genericarg]
+
+   or be defined by a rule giving a meaning to a name (possibly after
+   supplying generic arguments as required by the generic parameters),
+
+      / "(" S type S ")"
+
+   or be defined in a parenthesized type expression (parentheses may be
+   necessary to override some operator precedence), or
+
+      / "{" S group S "}"
+
+   a map expression, which matches a valid CBOR map the key/value pairs
+   of which can be ordered in such a way that the resulting sequence
+   matches the group expression, or
+
+      / "[" S group S "]"
+
+   an array expression, which matches a CBOR array the elements of which
+   -- when taken as values and complemented by a wildcard (matches
+   anything) key each -- match the group, or
+
+      / "~" S typename [genericarg]
+
+   an "unwrapped" group (see Section 3.7), which matches the group
+   inside a type defined as a map or an array by wrapping the group, or
+
+      / "&" S "(" S group S ")"
+      / "&" S groupname [genericarg]
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 49]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   an enumeration expression, which matches any value that is within the
+   set of values that the values of the group given can take, or
+
+      / "#" "6" ["." uint] "(" S type S ")"
+
+   a tagged data item, tagged with the "uint" given and containing the
+   type given as the tagged value, or
+
+      / "#" DIGIT ["." uint]                ; major/ai
+
+   a data item of a major type (given by the DIGIT), optionally
+   constrained to the additional information given by the uint, or
+
+      / "#"                                 ; any
+
+   any data item.
+
+   rangeop = "..." / ".."
+
+   A range operator can be used to join two type expressions that stand
+   for either two integer values or two floating-point values; it
+   matches any value that is between the two values, where the first
+   value is always included in the matching set and the second value is
+   included for ".." and excluded for "...".
+
+   ctlop = "." id
+
+   A control operator ties a _target_ type to a _controller_ type as
+   defined in Section 3.8.  Note that control operators are an extension
+   point for CDDL; additional documents may want to define additional
+   control operators.
+
+   group = grpchoice *(S "//" S grpchoice)
+
+   A group matches any sequence of key/value pairs that matches any of
+   the choices given (again using PEG semantics).
+
+   grpchoice = *(grpent optcom)
+
+   Each of the component groups is given as a sequence of group entries.
+   For a match, the sequence of key/value pairs given needs to match the
+   sequence of group entries in the sequence given.
+
+   grpent = [occur S] [memberkey S] type
+
+   A group entry can be given by a value type, which needs to be matched
+   by the value part of a single element; and, optionally, a memberkey
+   type, which needs to be matched by the key part of the element, if
+
+
+
+Birkholz, et al.             Standards Track                   [Page 50]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   the memberkey is given.  If the memberkey is not given, the entry can
+   only be used for matching arrays, not for maps.  (See below for how
+   that is modified by the occurrence indicator.)
+
+       / [occur S] groupname [genericarg]  ; preempted by above
+
+   A group entry can be built from a named group, or
+
+       / [occur S] "(" S group S ")"
+
+   from a parenthesized group, again with a possible occurrence
+   indicator.
+
+   memberkey = type1 S ["^" S] "=>"
+             / bareword S ":"
+             / value S ":"
+
+   Key types can be given by a type expression, a bareword (which stands
+   for a type that just contains a string value created from this
+   bareword), or a value (which stands for a type that just contains
+   this value).  A key value matches its key type if the key value is a
+   member of the key type, unless a cut preceding it in the group
+   applies (see Section 3.5.4 for how map matching is influenced by the
+   presence of the cuts denoted by "^" or ":" in previous entries).
+
+   bareword = id
+
+   A bareword is an alternative way to write a type with a single text
+   string value; it can only be used in the syntactic context given
+   above.
+
+   optcom = S ["," S]
+
+   (Optional commas do not influence the matching.)
+
+   occur = [uint] "*" [uint]
+         / "+"
+         / "?"
+
+   An occurrence indicator modifies the group given to its right by
+   requiring the group to match the sequence to be matched exactly for a
+   certain number of times (see Section 3.2) in sequence, i.e., it acts
+   as a (possibly infinite) group choice that contains choices with the
+   group repeated each of the occurrences times.
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 51]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   The rest of the ABNF describes syntax for value notation that should
+   be familiar to readers from programming languages, with the possible
+   exception of h'..' and b64'..' for byte strings, as well as syntactic
+   elements such as comments and line ends.
+
+Appendix D.  Standard Prelude
+
+   This appendix is normative.
+
+   The following prelude is automatically added to each CDDL file.
+   (Note that technically, it is a postlude, as it does not disturb the
+   selection of the first rule as the root of the definition.)
+
+                  any = #
+
+                  uint = #0
+                  nint = #1
+                  int = uint / nint
+
+                  bstr = #2
+                  bytes = bstr
+                  tstr = #3
+                  text = tstr
+
+                  tdate = #6.0(tstr)
+                  time = #6.1(number)
+                  number = int / float
+                  biguint = #6.2(bstr)
+                  bignint = #6.3(bstr)
+                  bigint = biguint / bignint
+                  integer = int / bigint
+                  unsigned = uint / biguint
+                  decfrac = #6.4([e10: int, m: integer])
+                  bigfloat = #6.5([e2: int, m: integer])
+                  eb64url = #6.21(any)
+                  eb64legacy = #6.22(any)
+                  eb16 = #6.23(any)
+                  encoded-cbor = #6.24(bstr)
+                  uri = #6.32(tstr)
+                  b64url = #6.33(tstr)
+                  b64legacy = #6.34(tstr)
+                  regexp = #6.35(tstr)
+                  mime-message = #6.36(tstr)
+                  cbor-any = #6.55799(any)
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 52]
+
+RFC 8610                          CDDL                         June 2019
+
+
+                  float16 = #7.25
+                  float32 = #7.26
+                  float64 = #7.27
+                  float16-32 = float16 / float32
+                  float32-64 = float32 / float64
+                  float = float16-32 / float64
+
+                  false = #7.20
+                  true = #7.21
+                  bool = false / true
+                  nil = #7.22
+                  null = nil
+                  undefined = #7.23
+
+                          Figure 14: CDDL Prelude
+
+   Note that the prelude is deemed to be fixed.  This means, for
+   instance, that additional tags beyond those defined in [RFC7049], as
+   registered, need to be defined in each CDDL file that is using them.
+
+   A common stumbling point is that the prelude does not define a type
+   "string".  CBOR has byte strings ("bytes" in the prelude) and text
+   strings ("text"), so a type that is simply called "string" would be
+   ambiguous.
+
+Appendix E.  Use with JSON
+
+   This appendix is normative.
+
+   The JSON generic data model (implicit in [RFC8259]) is a subset of
+   the generic data model of CBOR.  So, one can use CDDL with JSON by
+   limiting oneself to what can be represented in JSON.  Roughly
+   speaking, this means leaving out byte strings, tags, and simple
+   values other than "false", "true", and "null", leading to the
+   following limited prelude:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 53]
+
+RFC 8610                          CDDL                         June 2019
+
+
+                      any = #
+
+                      uint = #0
+                      nint = #1
+                      int = uint / nint
+
+                      tstr = #3
+                      text = tstr
+
+                      number = int / float
+
+                      float16 = #7.25
+                      float32 = #7.26
+                      float64 = #7.27
+                      float16-32 = float16 / float32
+                      float32-64 = float32 / float64
+                      float = float16-32 / float64
+
+                      false = #7.20
+                      true = #7.21
+                      bool = false / true
+                      nil = #7.22
+                      null = nil
+
+             Figure 15: JSON-Compatible Subset of CDDL Prelude
+
+   (The major types given here do not have a direct meaning in JSON, but
+   they can be interpreted as CBOR major types translated through
+   Section 4 of [RFC7049].)
+
+   There are a few fine points in using CDDL with JSON.  First, JSON
+   does not distinguish between integers and floating-point numbers;
+   there is only one kind of number (which may happen to be integral).
+   In this context, specifying a type as "uint", "nint", or "int" then
+   becomes a predicate that the number be integral.  As an example, this
+   means that the following JSON numbers are all matching "uint":
+
+      10 10.0 1e1 1.0e1 100e-1
+
+   (The fact that these are all integers may be surprising to users
+   accustomed to the long tradition in programming languages of using
+   decimal points or exponents in a number to indicate a floating-point
+   literal.)
+
+   CDDL distinguishes the various CBOR number types, but there is only
+   one number type in JSON.  The effect of specifying a floating-point
+   precision (float16/float32/float64) is only to restrict the set of
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 54]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   permissible values to those expressible with binary16/binary32/
+   binary64; this is unlikely to be very useful when using CDDL for
+   specifying JSON data structures.
+
+   Fundamentally, the number system of JSON itself is based on decimal
+   numbers and decimal fractions and does not have limits to its
+   precision or range.  In practice, JSON numbers are often parsed into
+   a number type that is called "float64" here, creating a number of
+   limitations to the generic data model [RFC7493].  In particular, this
+   means that integers can only be expressed with interoperable
+   exactness when they lie in the range [-(2**53)+1, (2**53)-1] -- a
+   smaller range than that covered by CDDL "int".
+
+   JSON applications that want to stay compatible with I-JSON ("Internet
+   JSON"; see [RFC7493]) may therefore want to define integer types with
+   more limited ranges, such as in Figure 16.  Note that the types given
+   here are not part of the prelude; they need to be copied into the
+   CDDL specification if needed.
+
+               ij-uint = 0..9007199254740991
+               ij-nint = -9007199254740991..-1
+               ij-int = -9007199254740991..9007199254740991
+
+          Figure 16: I-JSON Types for CDDL (Not Part of Prelude)
+
+   JSON applications that do not need to stay compatible with I-JSON and
+   that actually may need to go beyond the 64-bit unsigned and negative
+   integers supported by "int" (= "uint"/"nint") may want to use the
+   following additional types from the standard prelude, which are
+   expressed in terms of tags but can straightforwardly be mapped into
+   JSON (but not I-JSON) numbers:
+
+      biguint = #6.2(bstr)
+      bignint = #6.3(bstr)
+      bigint = biguint / bignint
+      integer = int / bigint
+      unsigned = uint / biguint
+
+   CDDL at this point does not have a way to express the unlimited
+   floating-point precision that is theoretically possible with JSON; at
+   the time of writing, this is rarely used in protocols in practice.
+
+   Note that a data model described in CDDL is always restricted by what
+   can be expressed in the serialization; e.g., floating-point values
+   such as NaN (not a number) and the infinities cannot be represented
+   in JSON even if they are allowed in the CDDL generic data model.
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 55]
+
+RFC 8610                          CDDL                         June 2019
+
+
+Appendix F.  A CDDL Tool
+
+   This appendix is for information only.
+
+   A rough CDDL tool is available.  For CDDL specifications, it can
+   check the syntax, generate one or more instances (expressed in CBOR
+   diagnostic notation or in pretty-printed JSON), and validate an
+   existing instance against the specification:
+
+                   Usage:
+                   cddl spec.cddl generate [n]
+                   cddl spec.cddl json-generate [n]
+                   cddl spec.cddl validate instance.cbor
+                   cddl spec.cddl validate instance.json
+
+                        Figure 17: CDDL Tool Usage
+
+   Install on a system with a modern Ruby via:
+
+                             gem install cddl
+
+                     Figure 18: CDDL Tool Installation
+
+   The accompanying CBOR diagnostic tools (which are automatically
+   installed by the above) are described in <https://github.com/cabo/
+   cbor-diag>; they can be used to convert between binary CBOR, a
+   pretty-printed hexadecimal form of binary CBOR, CBOR diagnostic
+   notation, JSON, and YAML [YAML].
+
+Appendix G.  Extended Diagnostic Notation
+
+   This appendix is normative.
+
+   Section 6 of [RFC7049] defines a "diagnostic notation" in order to be
+   able to converse about CBOR data items without having to resort to
+   binary data.  Diagnostic notation is based on JSON, with extensions
+   for representing CBOR constructs such as binary data and tags.
+
+   (Standardizing this together with the actual interchange format does
+   not serve to create another interchange format but enables the use of
+   a shared diagnostic notation in tools for and documents about CBOR.)
+
+   This appendix discusses a few extensions to the diagnostic notation
+   that have turned out to be useful since RFC 7049 was written.  We
+   refer to the result as Extended Diagnostic Notation (EDN).
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 56]
+
+RFC 8610                          CDDL                         June 2019
+
+
+G.1.  Whitespace in Byte String Notation
+
+   Examples often benefit from some whitespace (spaces, line breaks) in
+   byte strings.  In EDN, whitespace is ignored in prefixed byte
+   strings; for instance, the following are equivalent:
+
+      h'48656c6c6f20776f726c64'
+      h'48 65 6c 6c 6f 20 77 6f 72 6c 64'
+      h'4 86 56c 6c6f
+        20776 f726c64'
+
+G.2.  Text in Byte String Notation
+
+   Diagnostic notation notates byte strings in one of the base encodings
+   per [RFC4648], enclosed in single quotes, prefixed by >h< for base16,
+   >b32< for base32, >h32< for base32hex, or >b64< for base64 or
+   base64url.  Quite often, byte strings carry bytes that are
+   meaningfully interpreted as UTF-8 text.  EDN allows the use of single
+   quotes without a prefix to express byte strings with UTF-8 text; for
+   instance, the following are equivalent:
+
+      'hello world'
+      h'68656c6c6f20776f726c64'
+
+   The escaping rules of JSON strings are applied equivalently for
+   text-based byte strings, e.g., "\" stands for a single backslash and
+   "'" stands for a single quote.  Whitespace is included literally,
+   i.e., the previous section does not apply to text-based byte strings.
+
+G.3.  Embedded CBOR and CBOR Sequences in Byte Strings
+
+   Where a byte string is to carry an embedded CBOR-encoded item, or
+   more generally a sequence of zero or more such items, the diagnostic
+   notation for these zero or more CBOR data items, separated by commas,
+   can be enclosed in << and >> to notate the byte string resulting from
+   encoding the data items and concatenating the result.  For instance,
+   each pair of columns in the following are equivalent:
+
+      <<1>>              h'01'
+      <<1, 2>>           h'0102'
+      <<"foo", null>>    h'63666F6FF6'
+      <<>>               h''
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 57]
+
+RFC 8610                          CDDL                         June 2019
+
+
+G.4.  Concatenated Strings
+
+   While the ability to include whitespace enables line-breaking of
+   encoded byte strings, a mechanism is needed to be able to include
+   text strings as well as byte strings in direct UTF-8 representation
+   into line-based documents (such as RFCs and source code).
+
+   We extend the diagnostic notation by allowing multiple text strings
+   or multiple byte strings to be notated separated by whitespace; these
+   are then concatenated into a single text or byte string,
+   respectively.  Text strings and byte strings do not mix within such a
+   concatenation, except that byte string notation can be used inside a
+   sequence of concatenated text string notation to encode characters
+   that may be better represented in an encoded way.  The following four
+   values are equivalent:
+
+      "Hello world"
+      "Hello " "world"
+      "Hello" h'20' "world"
+      "" h'48656c6c6f20776f726c64' ""
+
+   Similarly, the following byte string values are equivalent:
+
+      'Hello world'
+      'Hello ' 'world'
+      'Hello ' h'776f726c64'
+      'Hello' h'20' 'world'
+      '' h'48656c6c6f20776f726c64' '' b64''
+      h'4 86 56c 6c6f' h' 20776 f726c64'
+
+   (Note that the approach of separating by whitespace, while familiar
+   from the C language, requires some attention -- a single comma makes
+   a big difference here.)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 58]
+
+RFC 8610                          CDDL                         June 2019
+
+
+G.5.  Hexadecimal, Octal, and Binary Numbers
+
+   In addition to JSON's decimal numbers, EDN provides hexadecimal,
+   octal, and binary numbers in the usual C-language notation (octal
+   with 0o prefix present only).
+
+   The following are equivalent:
+
+      4711
+      0x1267
+      0o11147
+      0b1001001100111
+
+   As are:
+
+      1.5
+      0x1.8p0
+      0x18p-4
+
+G.6.  Comments
+
+   Longer pieces of diagnostic notation may benefit from comments.  JSON
+   famously does not provide for comments, and basic diagnostic notation
+   per RFC 7049 inherits this property.
+
+   In EDN, comments can be included, delimited by slashes ("/").  Any
+   text within and including a pair of slashes is considered a comment.
+
+   Comments are considered whitespace.  Hence, they are allowed in
+   prefixed byte strings; for instance, the following are equivalent:
+
+      h'68656c6c6f20776f726c64'
+      h'68 65 6c /doubled l!/ 6c 6f /hello/
+        20 /space/
+        77 6f 72 6c 64' /world/
+
+   This can be used to annotate a CBOR structure as in:
+
+      /grasp-message/ [/M_DISCOVERY/ 1, /session-id/ 10584416,
+                       /objective/ [/objective-name/ "opsonize",
+                                    /D, N, S/ 7, /loop-count/ 105]]
+
+   (There are currently no end-of-line comments.  If we want to add
+   them, "//" sounds like a reasonable delimiter given that we already
+   use slashes for comments, but we could also go, for example,
+   for "#".)
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 59]
+
+RFC 8610                          CDDL                         June 2019
+
+
+Appendix H.  Examples
+
+   This appendix is for information only.
+
+   This appendix contains a few examples of structures defined
+   using CDDL.  The theme for the examples is taken from [RFC7071],
+   which defines certain JSON structures in English.  For a similar
+   example, it may also be of interest to examine Appendix A of
+   [RFC8007], which contains a CDDL definition for a JSON structure
+   defined in the main body of that RFC.
+
+   These examples all happen to describe data that is interchanged in
+   JSON.  Examples for CDDL definitions of data that is interchanged in
+   CBOR can be found in [RFC8152], [GRASP], and [RFC8428].
+
+   [RFC7071] defines the "reputon" structure for JSON using somewhat
+   formalized English text.  Here is a (somewhat verbose) equivalent
+   definition using the same terms, but notated in CDDL:
+
+                 reputation-object = {
+                   reputation-context,
+                   reputon-list
+                 }
+
+                 reputation-context = (
+                   application: text
+                 )
+
+                 reputon-list = (
+                   reputons: reputon-array
+                 )
+
+                 reputon-array = [* reputon]
+
+                 reputon = {
+                   rater-value,
+                   assertion-value,
+                   rated-value,
+                   rating-value,
+                   ? conf-value,
+                   ? normal-value,
+                   ? sample-value,
+                   ? gen-value,
+                   ? expire-value,
+                   * ext-value,
+                 }
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 60]
+
+RFC 8610                          CDDL                         June 2019
+
+
+                 rater-value = ( rater: text )
+                 assertion-value = ( assertion: text )
+                 rated-value = ( rated: text )
+                 rating-value = ( rating: float16 )
+                 conf-value = ( confidence: float16 )
+                 normal-value = ( normal-rating: float16 )
+                 sample-value = ( sample-size: uint )
+                 gen-value = ( generated: uint )
+                 expire-value = ( expires: uint )
+                 ext-value = ( text => any )
+
+   An equivalent, more compact form of this example would be:
+
+                        reputation-object = {
+                          application: text
+                          reputons: [* reputon]
+                        }
+
+                        reputon = {
+                          rater: text
+                          assertion: text
+                          rated: text
+                          rating: float16
+                          ? confidence: float16
+                          ? normal-rating: float16
+                          ? sample-size: uint
+                          ? generated: uint
+                          ? expires: uint
+                          * text => any
+                        }
+
+   Note how this rather clearly delineates the structure somewhat
+   shrouded by so many words in Section 6.2.2 of [RFC7071].  Also, this
+   definition makes it clear that several ext-values are allowed (by
+   definition with different member names); RFC 7071 could be read to
+   forbid the repetition of ext-value ("A specific reputon-element
+   MUST NOT appear more than once" is ambiguous).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 61]
+
+RFC 8610                          CDDL                         June 2019
+
+
+   The CDDL tool described in Appendix F generates as one example:
+
+                  {
+                    "application": "conchometry",
+                    "reputons": [
+                      {
+                        "rater": "Ephthianura",
+                        "assertion": "codding",
+                        "rated": "sphaerolitic",
+                        "rating": 0.34133473256800795,
+                        "confidence": 0.9481983064298332,
+                        "expires": 1568,
+                        "unplaster": "grassy"
+                      },
+                      {
+                        "rater": "nonchargeable",
+                        "assertion": "raglan",
+                        "rated": "alienage",
+                        "rating": 0.5724646875815566,
+                        "sample-size": 3514,
+                        "Aldebaran": "unchurched",
+                        "puruloid": "impersonable",
+                        "uninfracted": "pericarpoidal",
+                        "schorl": "Caro"
+                      },
+                      {
+                        "rater": "precollectable",
+                        "assertion": "Merat",
+                        "rated": "thermonatrite",
+                        "rating": 0.19164006323936977,
+                        "confidence": 0.6065252103391268,
+                        "normal-rating": 0.5187773690879303,
+                        "generated": 899,
+                        "speedy": "solidungular",
+                        "noviceship": "medicine",
+                        "checkrow": "epidictic"
+                      }
+                    ]
+                  }
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 62]
+
+RFC 8610                          CDDL                         June 2019
+
+
+Acknowledgements
+
+   Inspiration was taken from the C and Pascal languages, MPEG's
+   conventions for describing structures in the ISO base media file
+   format, RELAX NG and its compact syntax [RELAXNG], and, in
+   particular, Andrew Lee Newton's early proposals on JSON Content Rules
+   (JCR) as found in draft version four (-04) of [JCR].
+
+   Lots of highly useful feedback came from members of the IETF CBOR WG
+   -- in particular, Ari Keranen, Brian Carpenter, Burt Harris, Jeffrey
+   Yasskin, Jim Hague, Jim Schaad, Joe Hildebrand, Max Pritikin, Michael
+   Richardson, Pete Cordell, Sean Leonard, and Yaron Sheffer.  Also,
+   Francesca Palombini and Joe volunteered to chair the WG when it was
+   created, providing the framework for generating and processing this
+   feedback, with Barry Leiba having taken over from Joe since then.
+   Chris Lonvick and Ines Robles provided additional reviews during IESG
+   processing, and Alexey Melnikov steered the process as the
+   responsible Area Director.
+
+   The CDDL tool described in Appendix F was written by Carsten Bormann,
+   building on previous work by Troy Heninger and Tom Lord.
+
+Contributors
+
+   CDDL was originally conceived by Bert Greevenbosch, who also wrote
+   the original five draft versions of this document.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 63]
+
+RFC 8610                          CDDL                         June 2019
+
+
+Authors' Addresses
+
+   Henk Birkholz
+   Fraunhofer SIT
+   Rheinstrasse 75
+   Darmstadt  64295
+   Germany
+
+   Email: henk.birkholz@sit.fraunhofer.de
+
+
+   Christoph Vigano
+   Universitaet Bremen
+
+   Email: christoph.vigano@uni-bremen.de
+
+
+   Carsten Bormann
+   Universitaet Bremen TZI
+   Bibliothekstr. 1
+   Bremen  D-28359
+   Germany
+
+   Phone: +49-421-218-63921
+   Email: cabo@tzi.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Birkholz, et al.             Standards Track                   [Page 64]
+