draft-ietf-cbor-cddl-03.txt   draft-ietf-cbor-cddl-04.txt 
Network Working Group H. Birkholz Network Working Group H. Birkholz
Internet-Draft Fraunhofer SIT Internet-Draft Fraunhofer SIT
Intended status: Standards Track C. Vigano Intended status: Standards Track C. Vigano
Expires: January 3, 2019 Universitaet Bremen Expires: February 11, 2019 Universitaet Bremen
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
July 02, 2018 August 10, 2018
Concise data definition language (CDDL): a notational convention to Concise data definition language (CDDL): a notational convention to
express CBOR data structures express CBOR and JSON data structures
draft-ietf-cbor-cddl-03 draft-ietf-cbor-cddl-04
Abstract Abstract
This document proposes a notational convention to express CBOR data This document proposes a notational convention to express CBOR data
structures (RFC 7049). Its main goal is to provide an easy and structures (RFC 7049). Its main goal is to provide an easy and
unambiguous way to express structures for protocol messages and data unambiguous way to express structures for protocol messages and data
formats that use CBOR. formats that use CBOR or JSON.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 3, 2019. This Internet-Draft will expire on February 11, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 16 skipping to change at page 2, line 16
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements notation . . . . . . . . . . . . . . . . . . 4 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. The Style of Data Structure Specification . . . . . . . . . . 4 2. The Style of Data Structure Specification . . . . . . . . . . 4
2.1. Groups and Composition in CDDL . . . . . . . . . . . . . 6 2.1. Groups and Composition in CDDL . . . . . . . . . . . . . 6
2.1.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 8 2.1.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 9
2.2. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.1. Values . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.1. Values . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.2. Choices . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.2. Choices . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.3. Representation Types . . . . . . . . . . . . . . . . 11 2.2.3. Representation Types . . . . . . . . . . . . . . . . 12
2.2.4. Root type . . . . . . . . . . . . . . . . . . . . . . 11 2.2.4. Root type . . . . . . . . . . . . . . . . . . . . . . 13
3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1. General conventions . . . . . . . . . . . . . . . . . . . 12 3.1. General conventions . . . . . . . . . . . . . . . . . . . 13
3.2. Occurrence . . . . . . . . . . . . . . . . . . . . . . . 13 3.2. Occurrence . . . . . . . . . . . . . . . . . . . . . . . 15
3.3. Predefined names for types . . . . . . . . . . . . . . . 14 3.3. Predefined names for types . . . . . . . . . . . . . . . 15
3.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.5. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.5. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.5.1. Structs . . . . . . . . . . . . . . . . . . . . . . . 16 3.5.1. Structs . . . . . . . . . . . . . . . . . . . . . . . 17
3.5.2. Tables . . . . . . . . . . . . . . . . . . . . . . . 19 3.5.2. Tables . . . . . . . . . . . . . . . . . . . . . . . 20
3.5.3. Cuts in Maps . . . . . . . . . . . . . . . . . . . . 19 3.5.3. Cuts in Maps . . . . . . . . . . . . . . . . . . . . 21
3.6. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 20 3.6. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.7. Unwrapping . . . . . . . . . . . . . . . . . . . . . . . 21 3.7. Unwrapping . . . . . . . . . . . . . . . . . . . . . . . 22
3.8. Controls . . . . . . . . . . . . . . . . . . . . . . . . 22 3.8. Controls . . . . . . . . . . . . . . . . . . . . . . . . 23
3.8.1. Control operator .size . . . . . . . . . . . . . . . 22 3.8.1. Control operator .size . . . . . . . . . . . . . . . 24
3.8.2. Control operator .bits . . . . . . . . . . . . . . . 23 3.8.2. Control operator .bits . . . . . . . . . . . . . . . 24
3.8.3. Control operator .regexp . . . . . . . . . . . . . . 24 3.8.3. Control operator .regexp . . . . . . . . . . . . . . 25
3.8.4. Control operators .cbor and .cborseq . . . . . . . . 25 3.8.4. Control operators .cbor and .cborseq . . . . . . . . 27
3.8.5. Control operators .within and .and . . . . . . . . . 25 3.8.5. Control operators .within and .and . . . . . . . . . 27
3.8.6. Control operators .lt, .le, .gt, .ge, .eq, .ne, and 3.8.6. Control operators .lt, .le, .gt, .ge, .eq, .ne, and
.default . . . . . . . . . . . . . . . . . . . . . . 26 .default . . . . . . . . . . . . . . . . . . . . . . 28
3.9. Socket/Plug . . . . . . . . . . . . . . . . . . . . . . . 27 3.9. Socket/Plug . . . . . . . . . . . . . . . . . . . . . . . 29
3.10. Generics . . . . . . . . . . . . . . . . . . . . . . . . 28 3.10. Generics . . . . . . . . . . . . . . . . . . . . . . . . 30
3.11. Operator Precedence . . . . . . . . . . . . . . . . . . . 28 3.11. Operator Precedence . . . . . . . . . . . . . . . . . . . 31
4. Making Use of CDDL . . . . . . . . . . . . . . . . . . . . . 30 4. Making Use of CDDL . . . . . . . . . . . . . . . . . . . . . 32
4.1. As a guide to a human user . . . . . . . . . . . . . . . 30 4.1. As a guide to a human user . . . . . . . . . . . . . . . 32
4.2. For automated checking of CBOR data structure . . . . . . 30 4.2. For automated checking of CBOR data structure . . . . . . 33
4.3. For data analysis tools . . . . . . . . . . . . . . . . . 31 4.3. For data analysis tools . . . . . . . . . . . . . . . . . 33
5. Security considerations . . . . . . . . . . . . . . . . . . . 31 5. Security considerations . . . . . . . . . . . . . . . . . . . 33
6. IANA considerations . . . . . . . . . . . . . . . . . . . . . 32 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34
6.1. CDDL control operator registry . . . . . . . . . . . . . 32 6.1. CDDL control operator registry . . . . . . . . . . . . . 34
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 35
7.1. Normative References . . . . . . . . . . . . . . . . . . 32 7.1. Normative References . . . . . . . . . . . . . . . . . . 35
7.2. Informative References . . . . . . . . . . . . . . . . . 33 7.2. Informative References . . . . . . . . . . . . . . . . . 36
Appendix A. (Not used.) . . . . . . . . . . . . . . . . . . . . 34 Appendix A. (Not used.) . . . . . . . . . . . . . . . . . . . . 37
Appendix B. ABNF grammar . . . . . . . . . . . . . . . . . . . . 34 Appendix B. ABNF grammar . . . . . . . . . . . . . . . . . . . . 37
Appendix C. Matching rules . . . . . . . . . . . . . . . . . . . 36 Appendix C. Matching rules . . . . . . . . . . . . . . . . . . . 40
Appendix D. (Not used.) . . . . . . . . . . . . . . . . . . . . 40 Appendix D. Standard Prelude . . . . . . . . . . . . . . . . . . 44
Appendix E. Standard Prelude . . . . . . . . . . . . . . . . . . 40 Appendix E. Use with JSON . . . . . . . . . . . . . . . . . . . 46
E.1. Use with JSON . . . . . . . . . . . . . . . . . . . . . . 42 Appendix F. The CDDL tool . . . . . . . . . . . . . . . . . . . 48
Appendix F. The CDDL tool . . . . . . . . . . . . . . . . . . . 44 Appendix G. Extended Diagnostic Notation . . . . . . . . . . . . 48
Appendix G. Extended Diagnostic Notation . . . . . . . . . . . . 44 G.1. White space in byte string notation . . . . . . . . . . . 49
G.1. White space in byte string notation . . . . . . . . . . . 45 G.2. Text in byte string notation . . . . . . . . . . . . . . 49
G.2. Text in byte string notation . . . . . . . . . . . . . . 45 G.3. Embedded CBOR and CBOR sequences in byte strings . . . . 49
G.3. Embedded CBOR and CBOR sequences in byte strings . . . . 45 G.4. Concatenated Strings . . . . . . . . . . . . . . . . . . 50
G.4. Concatenated Strings . . . . . . . . . . . . . . . . . . 46 G.5. Hexadecimal, octal, and binary numbers . . . . . . . . . 50
G.5. Hexadecimal, octal, and binary numbers . . . . . . . . . 46 G.6. Comments . . . . . . . . . . . . . . . . . . . . . . . . 51
G.6. Comments . . . . . . . . . . . . . . . . . . . . . . . . 47 Appendix H. Examples . . . . . . . . . . . . . . . . . . . . . . 51
Appendix H. Examples . . . . . . . . . . . . . . . . . . . . . . 47 H.1. RFC 7071 . . . . . . . . . . . . . . . . . . . . . . . . 52
H.1. RFC 7071 . . . . . . . . . . . . . . . . . . . . . . . . 48 H.1.1. Examples from JSON Content Rules . . . . . . . . . . 56
H.1.1. Examples from JSON Content Rules . . . . . . . . . . 52 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 54 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 58
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58
1. Introduction 1. Introduction
In this document, a notational convention to express CBOR [RFC7049] In this document, a notational convention to express CBOR [RFC7049]
data structures is defined. data structures is defined.
The main goal for the convention is to provide a unified notation 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 that can be used when defining protocols that use CBOR. We term the
convention "Concise data definition language", or CDDL. convention "Concise data definition language", or CDDL.
The CBOR notational convention has the following goals: The CBOR notational convention has the following goals:
(G1) Provide an unambiguous description of the overall structure of (G1) Provide an unambiguous description of the overall structure of
a CBOR data structure. a CBOR data structure.
(G2) Flexibility to express the freedoms of choice in the CBOR data (G2) Flexibility to express the freedoms of choice in the CBOR data
format. format.
(G3) Possibility to restrict format choices where appropriate (G3) Able to express common CBOR datatypes and structures.
[_format].
(G4) Able to express common CBOR datatypes and structures.
(G5) Human and machine readable and processable. (G4) Human and machine readable and processable.
(G6) Automatic checking of data format compliance. (G5) Automatic checking of data format compliance.
(G7) Extraction of specific elements from CBOR data for further (G6) Extraction of specific elements from CBOR data for further
processing. processing.
Not an explicit goal per se, but a convenient side effect of the JSON 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 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 the fact that CDDL can also be used for describing JSON data
structures (see Appendix E.1). structures (see Appendix E).
This document has the following structure: This document has the following structure:
The syntax of CDDL is defined in Section 3. Examples of CDDL and The syntax of CDDL is defined in Section 3. Examples of CDDL and
related CBOR data items ("instances") are defined in Appendix H. related CBOR data items ("instances") are defined in Appendix H.
Section 4 discusses usage of CDDL. Examples are provided early in Section 4 discusses usage of CDDL. Examples are provided early in
the text to better illustrate concept definitions. A formal the text to better illustrate concept definitions. A formal
definition of CDDL using ABNF grammar is provided in Appendix B. definition of CDDL using ABNF grammar is provided in Appendix B.
Finally, a _prelude_ of standard CDDL definitions that is Finally, a _prelude_ of standard CDDL definitions that is
automatically prepended to and thus available in every CBOR automatically prepended to and thus available in every CBOR
specification is listed in Appendix E. specification is listed in Appendix D.
1.1. Requirements notation 1.1. Requirements notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC "OPTIONAL" in this document are to be interpreted as described in RFC
2119, BCP 14 [RFC2119]. 2119, BCP 14 [RFC2119].
1.2. Terminology 1.2. Terminology
New terms are introduced in _cursive_. CDDL text in the running text New terms are introduced in _cursive_. CDDL text in the running text
is in "typewriter". is in "typewriter".
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 2. The Style of Data Structure Specification
CDDL focuses on styles of specification that are in use in the CDDL focuses on styles of specification that are in use in the
community employing the data model as pioneered by JSON and now community employing the data model as pioneered by JSON and now
refined in CBOR. refined in CBOR.
There are a number of more or less atomic elements of a CBOR data There are a number of more or less atomic elements of a CBOR data
model, such as numbers, simple values (false, true, nil), text and model, such as numbers, simple values (false, true, nil), text and
byte strings; CDDL does not focus on specifying their structure. byte strings; CDDL does not focus on specifying their structure.
CDDL of course also allows adding a CBOR tag to a data item. CDDL of course also allows adding a CBOR tag to a data item.
skipping to change at page 6, line 13 skipping to change at page 6, line 13
Finally, a type can be built as an array or a map from a group. 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 The rest of this section introduces a number of basic concepts of
CDDL, and section Section 3 defines additional syntax. Appendix C CDDL, and section Section 3 defines additional syntax. Appendix C
gives a concise summary of the semantics of CDDL. gives a concise summary of the semantics of CDDL.
2.1. Groups and Composition in CDDL 2.1. Groups and Composition in CDDL
CDDL Groups are lists of group _entries_, each of which can be a CDDL Groups are lists of group _entries_, each of which can be a
name/value pair or a more complex group expression composed of name/ name/value pair or a more complex group expression composed of name/
value pairs. value pairs. A CDDL group is a production in a grammar that can
produce certain sequences of name/value pairs but not others.
In an array context, only the value of the entry is represented; the In an array context, only the value of the name/value pair is
name is annotation only (and can be left off if not needed). In a represented; the name is annotation only (and can be left off from
map context, the names become the map keys ("member keys"). the group specification if not needed). In a map context, the names
become the map keys ("member keys").
In an array context, the sequence of elements in the group is In an array context, the sequence of elements in the group is
important, as it is the information that allows associating actual important, as it is the information that allows associating actual
array elements with entries in the group. In a map context, the 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 sequence of entries in a group is not relevant (but there is still a
need to write down group entries in a sequence). need to write down group entries in a sequence).
An array matches a specification given as a group when the group can
produce 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 can
produce 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 right in a map definition is: A simple example of using a group right in a map definition is:
person = { person = {
age: int, age: int,
name: tstr, name: tstr,
employer: tstr, employer: tstr,
} }
Figure 1: Using a group in a map Figure 1: Using a group directly in a map
The three entries of the group are written between the curly braces The three entries of the group are written between the curly braces
that create the map: Here, "age", "name", and "employer" are the that create the map: Here, "age", "name", and "employer" are the
names that turn into the map key text strings, and "int" and "tstr" 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. (text string) are the types of the map values under these keys.
A group by itself (without creating a map around it) can be placed in 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: (round) parentheses, and given a name by using it in a rule:
pii = ( pii = (
skipping to change at page 7, line 26 skipping to change at page 7, line 37
there is some other set of brackets present. Note that they can there is some other set of brackets present. Note that they can
still be used, leading to the not so realistic, but perfectly valid still be used, leading to the not so realistic, but perfectly valid
example: example:
person = {( person = {(
age: int, age: int,
name: tstr, name: tstr,
employer: tstr, employer: tstr,
)} )}
Figure 4: Using a parenthesized group in a map
Groups can be used to factor out common parts of structs, e.g., Groups can be used to factor out common parts of structs, e.g.,
instead of writing copy/paste style specifications such as in instead of writing copy/paste style specifications such as in
Figure 4, one can factor out the common subgroup, choose a name for Figure 5, one can factor out the common subgroup, choose a name for
it, and write only the specific parts into the individual maps it, and write only the specific parts into the individual maps
(Figure 5). (Figure 6).
person = { person = {
age: int, age: int,
name: tstr, name: tstr,
employer: tstr, employer: tstr,
} }
dog = { dog = {
age: int, age: int,
name: tstr, name: tstr,
leash-length: float, leash-length: float,
} }
Figure 4: Maps with copy/paste Figure 5: Maps with copy/paste
person = { person = {
identity, identity,
employer: tstr, employer: tstr,
} }
dog = { dog = {
identity, identity,
leash-length: float, leash-length: float,
} }
identity = ( identity = (
age: int, age: int,
name: tstr, name: tstr,
) )
Figure 5: Using a group for factorization Figure 6: Using a group for factorization
Note that the lists inside the braces in the above definitions Note that the lists inside the braces in the above definitions
constitute (anonymous) groups, while "identity" is a named group. constitute (anonymous) groups, while "identity" is a named group.
2.1.1. Usage 2.1.1. Usage
Groups are the instrument used in composing data structures with Groups are the instrument used in composing data structures with
CDDL. It is a matter of style in defining those structures whether CDDL. It is a matter of style in defining those structures whether
to define groups (anonymously) right in their contexts or whether to to define groups (anonymously) right in their contexts or whether to
define them in a separate rule and to reference them with their define them in a separate rule and to reference them with their
skipping to change at page 9, line 6 skipping to change at page 9, line 21
o The end of a group can be marked by ')' o The end of a group can be marked by ')'
o Definitions of entries inside of a group are noted as follows: o Definitions of entries inside of a group are noted as follows:
_keytype => valuetype,_ (read "keytype maps to valuetype"). The _keytype => valuetype,_ (read "keytype maps to valuetype"). The
comma is actually optional (not just in the final entry), but it comma is actually optional (not just in the final entry), but it
is considered good style to set it. The double arrow can be 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 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). string or integer literal as a key (see Section 3.5.1).
A basic entry consists of a _keytype_ and a _valuetype_, both of A basic entry consists of a _keytype_ and a _valuetype_, both of
which are types (Section 2.2). which are types (Section 2.2); this entry can produce 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 can produce any
sequence of name-value pairs that is composed by concatenation in
order of what the entries can produce.
A group definition can also contain choices between groups, see A group definition can also contain choices between groups, see
Section 2.2.2. Section 2.2.2.
2.2. Types 2.2. Types
2.2.1. Values 2.2.1. Values
Values such as numbers and strings can be used in place of a type. 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 keytype, (For instance, this is a very common thing to do for a keytype,
common enough that CDDL provides additional convenience syntax for common enough that CDDL provides additional convenience syntax for
this.) this.)
The value notation is based on the C language, but does not offer all The value notation is based on the C language, but does not offer all
the syntactic variations Appendix B. The value notation for numbers the syntactic variations Appendix B. The value notation for numbers
inherits from C the distinction between integer values (no fractional inherits from C the distinction between integer values (no fractional
part or exponent given -- NR1 [ISO6093]) and floating point values part or exponent given -- NR1 [ISO6093]) and floating point values
(where a fractional part and/or an exponent is present -- NR2 or (where a fractional part and/or an exponent is present -- NR2 or
NR3), so the type "1" does not include any floating point numbers 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 while the types "1e3" and "1.5" are both floating point numbers and
do not include any integer numbers. do not include any integer numbers.
2.2.2. Choices 2.2.2. Choices
Many places that allow a type also allow a choice between types, Many places that allow a type also allow a choice between types,
delimited by a "/" (slash). The entire choice construct can be put delimited by a "/" (slash). The entire choice construct can be put
into parentheses if this is required to make the construction into parentheses if this is required to make the construction
unambiguous (please see Appendix B for the details). unambiguous (please see Appendix B for the details).
Choices of values can be used to express enumerations: Choices of values can be used to express enumerations:
attire = "bow tie" / "necktie" / "Internet attire" attire = "bow tie" / "necktie" / "Internet attire"
protocol = 6 / 17 protocol = 6 / 17
Similarly as for types, CDDL also allows choices between groups, Similarly as for types, CDDL also allows choices between groups,
delimited by a "//" (double slash). delimited by a "//" (double slash). Note that the "//" operators
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 } address = { delivery }
delivery = ( delivery = (
street: tstr, ? number: uint, city // street: tstr, ? number: uint, city //
po-box: uint, city // po-box: uint, city //
per-pickup: true ) per-pickup: true )
city = ( city = (
name: tstr, zip-code: uint name: tstr, zip-code: uint
) )
A group choice can produce the union of the sets of name-value pair
sequences that the alternatives in the choice can.
Both for type choices and for group choices, additional alternatives Both for type choices and for group choices, additional alternatives
can be added to a rule later in separate rules by using "/=" and can be added to a rule later in separate rules by using "/=" and
"//=", respectively, instead of "=": "//=", respectively, instead of "=":
attire /= "swimwear" attire /= "swimwear"
delivery //= ( delivery //= (
lat: float, long: float, drone-type: tstr lat: float, long: float, drone-type: tstr
) )
skipping to change at page 10, line 43 skipping to change at page 11, line 19
relationship. A range can be inclusive of both ends given (denoted relationship. A range can be inclusive of both ends given (denoted
by joining two values by ".."), or include the first and exclude the by joining two values by ".."), or include the first and exclude the
second (denoted by instead using "..."). second (denoted by instead using "...").
device-address = byte device-address = byte
max-byte = 255 max-byte = 255
byte = 0..max-byte ; inclusive range byte = 0..max-byte ; inclusive range
first-non-byte = 256 first-non-byte = 256
byte1 = 0...first-non-byte ; byte1 is equivalent to byte byte1 = 0...first-non-byte ; byte1 is equivalent to byte
CDDL currently only allows ranges between numbers [_range]. 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.)
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, use spacing as in "min .. max" to
separate off the range operator.
2.2.2.2. Turning a group into a choice 2.2.2.2. Turning a group into a choice
Some choices are built out of large numbers of values, often Some choices are built out of large numbers of values, often
integers, each of which is best given a semantic name in the integers, each of which is best given a semantic name in the
specification. Instead of naming each of these integers and then specification. Instead of naming each of these integers and then
accumulating these into a choice, CDDL allows building a choice from accumulating these into a choice, CDDL allows building a choice from
a group by prefixing it with a "&" character: a group by prefixing it with a "&" character:
terminal-color = &basecolors terminal-color = &basecolors
skipping to change at page 11, line 23 skipping to change at page 12, line 23
) )
As with the use of groups in arrays (Section 3.4), the membernames As with the use of groups in arrays (Section 3.4), the membernames
have only documentary value (in particular, they might be used by a have only documentary value (in particular, they might be used by a
tool when displaying integers that are taken from that choice). tool when displaying integers that are taken from that choice).
2.2.3. Representation Types 2.2.3. Representation Types
CDDL allows the specification of a data item type by referring to the CDDL allows the specification of a data item type by referring to the
CBOR representation (major and minor numbers). How this is used CBOR representation (major and minor numbers). How this is used
should be evident from the prelude (Appendix E). should be evident from the prelude (Appendix D): a hash mark ("#")
optionally followed by a major type, which can be followed by
additional information, 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. 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 It may be necessary to make use of representation types outside the
prelude, e.g., a specification could start by making use of an prelude, e.g., a specification could start by making use of an
existing tag in a more specific way, or define a new tag not defined existing tag in a more specific way, or define a new tag not defined
in the prelude: in the prelude:
my_breakfast = #6.55799(breakfast) ; cbor-any is too general! my_breakfast = #6.55799(breakfast) ; cbor-any is too general!
breakfast = cereal / porridge breakfast = cereal / porridge
cereal = #6.998(tstr) cereal = #6.998(tstr)
porridge = #6.999([liquid, solid]) porridge = #6.999([liquid, solid])
skipping to change at page 12, line 39 skipping to change at page 14, line 6
* The hyphen is preferred over the underscore (except in a * The hyphen is preferred over the underscore (except in a
"bareword" (Section 3.5.1), where the semantics may actually "bareword" (Section 3.5.1), where the semantics may actually
require an underscore). require an underscore).
* The period may be useful for larger specifications, to express * The period may be useful for larger specifications, to express
some module structure (as in "tcp.throughput" vs. some module structure (as in "tcp.throughput" vs.
"udp.throughput"). "udp.throughput").
* A number of names are predefined in the CDDL prelude, as listed * A number of names are predefined in the CDDL prelude, as listed
in Appendix E. in Appendix D.
* Rule names (types or groups) do not appear in the actual CBOR * Rule names (types or groups) do not appear in the actual CBOR
encoding, but names used as "barewords" in member keys do. encoding, but names used as "barewords" in member keys do.
o Comments are started by a ';' (semicolon) character and finish at o Comments are started by a ';' (semicolon) character and finish at
the end of a line (LF or CRLF). the end of a line (LF or CRLF).
o outside strings, whitespace (spaces, newlines, and comments) is o outside strings, whitespace (spaces, newlines, and comments) is
used to separate syntactic elements for readability (and to used to separate syntactic elements for readability (and to
separate identifiers or numbers that follow each other); it is separate identifiers or numbers that follow each other); it is
skipping to change at page 13, line 24 skipping to change at page 14, line 38
o Byte strings are enclosed by single quotation "'" characters and o Byte strings are enclosed by single quotation "'" characters and
may be prefixed by "h" or "b64". If unprefixed, the string is may be prefixed by "h" or "b64". If unprefixed, the string is
interpreted as with a text string, except that single quotes must interpreted as with a text string, except that single quotes must
be escaped and that the UTF-8 bytes resulting are marked as a byte be escaped and that the UTF-8 bytes resulting are marked as a byte
string (major type 2). If prefixed as "h" or "b64", the string is string (major type 2). If prefixed as "h" or "b64", the string is
interpreted as a sequence of hex digits or a base64(url) string, interpreted as a sequence of hex digits or a base64(url) string,
respectively (as with the diagnostic notation in section 6 of respectively (as with the diagnostic notation in section 6 of
[RFC7049]; cf. Appendix G.2); any white space present within the [RFC7049]; cf. Appendix G.2); any white space present within the
string (including comments) is ignored in the prefixed case. string (including comments) is ignored in the prefixed case.
[_strings]
o CDDL uses UTF-8 [RFC3629] for its encoding. o CDDL uses UTF-8 [RFC3629] for its encoding.
Example: Example:
; This is a comment ; This is a comment
person = { g } person = { g }
g = ( g = (
"name": tstr, "name": tstr,
skipping to change at page 13, line 47 skipping to change at page 15, line 14
3.2. Occurrence 3.2. Occurrence
An optional _occurrence_ indicator can be given in front of a group An optional _occurrence_ indicator can be given in front of a group
entry. It is either one of the characters '?' (optional), '*' (zero entry. It is either one of the characters '?' (optional), '*' (zero
or more), or '+' (one or more), or is of the form n*m, where n and m or more), or '+' (one or more), or is of the form n*m, where n and m
are optional unsigned integers and n is the lower limit (default 0) are optional unsigned integers and n is the lower limit (default 0)
and m is the upper limit (default no limit) of occurrences. and m is the upper limit (default no limit) of occurrences.
If no occurrence indicator is specified, the group entry is to occur If no occurrence indicator is specified, the group entry is to occur
exactly once (as if 1*1 were specified). exactly once (as if 1*1 were specified). A group entry with an
occurrence indicator can produce sequences of name-value pairs that
are composed by concatenating a number of sequences that the basic
group entry can produce, where the number needs to be allowed by the
occurrence indicator.
Note that CDDL, outside any directives/annotations that could Note that CDDL, outside any directives/annotations that could
possibly be defined, does not make any prescription as to whether possibly be defined, does not make any prescription as to whether
arrays or maps use the definite length or indefinite length encoding. arrays or maps use the definite length or indefinite length encoding.
I.e., there is no correlation between leaving the size of an array I.e., there is no correlation between leaving the size of an array
"open" in the spec and the fact that it is then interchanged with "open" in the spec and the fact that it is then interchanged with
definite or indefinite length. definite or indefinite length.
Please also note that CDDL can describe flexibility that the data Please also note that CDDL can describe flexibility that the data
model of the target representation does not have. This is rather model of the target representation does not have. This is rather
skipping to change at page 14, line 30 skipping to change at page 15, line 50
much turns into: much turns into:
? bedroom: size, ? bedroom: size,
(Occurrence indicators beyond one still are useful in maps for groups (Occurrence indicators beyond one still are useful in maps for groups
that allow a variety of keys.) that allow a variety of keys.)
3.3. Predefined names for types 3.3. Predefined names for types
CDDL predefines a number of names. This subsection summarizes these CDDL predefines a number of names. This subsection summarizes these
names, but please see Appendix E for the exact definitions. names, but please see Appendix D for the exact definitions.
The following keywords for primitive datatypes are defined: The following keywords for primitive datatypes are defined:
"bool" Boolean value (major type 7, additional information 20 or "bool" Boolean value (major type 7, additional information 20 or
21). 21).
"uint" An unsigned integer (major type 0). "uint" An unsigned integer (major type 0).
"nint" A negative integer (major type 1). "nint" A negative integer (major type 1).
skipping to change at page 18, line 39 skipping to change at page 20, line 17
NameComponents, NameComponents,
? age: uint, ? age: uint,
* tstr => any * tstr => any
} }
NameComponents = ( NameComponents = (
? firstName: tstr, ? firstName: tstr,
? familyName: tstr, ? familyName: tstr,
) )
Figure 6: Personal Data: Example for extensibility Figure 7: Personal Data: Example for extensibility
The cddl tool (Appendix F) generated as one acceptable instance for The cddl tool (Appendix F) generated as one acceptable instance for
this specification: this specification:
{"familyName": "agust", "antiforeignism": "pretzel", {"familyName": "agust", "antiforeignism": "pretzel",
"springbuck": "illuminatingly", "exuviae": "ephemeris", "springbuck": "illuminatingly", "exuviae": "ephemeris",
"kilometrage": "frogfish"} "kilometrage": "frogfish"}
(See Section 3.9 for one way to explicitly identify an extension (See Section 3.9 for one way to explicitly identify an extension
point.) point.)
skipping to change at page 20, line 10 skipping to change at page 21, line 35
extend the type of "optional-key"), but in many cases isn't. extend the type of "optional-key"), but in many cases isn't.
In anticipation of a more general potential feature called "cuts", In anticipation of a more general potential feature called "cuts",
CDDL allows inserting a cut "^" into the definition of the map entry: CDDL allows inserting a cut "^" into the definition of the map entry:
extensible-map-example = { extensible-map-example = {
? "optional-key" ^ => int, ? "optional-key" ^ => int,
* tstr => any * tstr => any
} }
A cut in this position means that once the map key matches the entry A cut in this position means that once the map key matches the name
carrying the cut, other potential matches for the key that occur in part of an entry that can be produced and carries a cut, other
later entries in the group of the map are no longer allowed. (This potential matches for the key that occur in later entries in the
rule applies independent of whether the value matches, too.) So the group of the map are no longer allowed. (This rule applies
example above no longer matches the version modified with a cut. independent of whether the value matches, too.) So the example above
no longer matches the version modified with a cut.
Since the desire for this kind of exclusive matching is so frequent, Since the desire for this kind of exclusive matching is so frequent,
the ":" shortcut is actually defined to include the cut semantics. the ":" shortcut is actually defined to include the cut semantics.
So the preceding example (including the cut) can be written more So the preceding example (including the cut) can be written more
simply as: simply as:
extensible-map-example = { extensible-map-example = {
? "optional-key": int, ? "optional-key": int,
* tstr => any * tstr => any
} }
skipping to change at page 20, line 40 skipping to change at page 22, line 17
* tstr => any * tstr => any
} }
3.6. Tags 3.6. Tags
A type can make use of a CBOR tag (major type 6) by using the 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 representation type notation, giving #6.nnn(type) where nnn is an
unsigned integer giving the tag number and "type" is the type of the unsigned integer giving the tag number and "type" is the type of the
data item being tagged. data item being tagged.
For example, the following line from the CDDL prelude (Appendix E) For example, the following line from the CDDL prelude (Appendix D)
defines "biguint" as a type name for a positive bignum N: defines "biguint" as a type name for a positive bignum N:
biguint = #6.2(bstr) biguint = #6.2(bstr)
The tags defined by [RFC7049] are included in the prelude. The tags defined by [RFC7049] are included in the prelude.
Additional tags since registered need to be added to a CDDL Additional tags since registered need to be added to a CDDL
specification as needed; e.g., a binary UUID tag could be referenced specification as needed; e.g., a binary UUID tag could be referenced
as "buuid" in a specification after defining as "buuid" in a specification after defining
buuid = #6.37(bstr) buuid = #6.37(bstr)
skipping to change at page 22, line 23 skipping to change at page 24, line 4
A _control_ allows to relate a _target_ type with a _controller_ type A _control_ allows to relate a _target_ type with a _controller_ type
via a _control operator_. via a _control operator_.
The syntax for a control type is "target .control-operator The syntax for a control type is "target .control-operator
controller", where control operators are special identifiers prefixed controller", where control operators are special identifiers prefixed
by a dot. (Note that _target_ or _controller_ might need to be by a dot. (Note that _target_ or _controller_ might need to be
parenthesized.) parenthesized.)
A number of control operators are defined at his point. Note that A number of control operators are defined at his point. Note that
the CDDL tool does not currently support combining multiple controls the CDDL tool does not currently support combining multiple controls
on a single target. on a single target. 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 3.8.1. Control operator .size
A ".size" control controls the size of the target in bytes by the A ".size" control controls the size of the target in bytes by the
control type. Examples: 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] full-address = [[+ label], ip4, ip6]
ip4 = bstr .size 4 ip4 = bstr .size 4
ip6 = bstr .size 16 ip6 = bstr .size 16
label = bstr .size (1..63) label = bstr .size (1..63)
Figure 7: Control for size in bytes Figure 8: Control for size in bytes
When applied to an unsigned integer, the ".size" control restricts When applied to an unsigned integer, the ".size" control restricts
the range of that integer by giving a maximum number of bytes that the range of that integer by giving a maximum number of bytes that
should be needed in a computer representation of that unsigned should be needed in a computer representation of that unsigned
integer. In other words, "uint .size N" is equivalent to integer. In other words, "uint .size N" is equivalent to
"0...BYTES_N", where BYTES_N == 256**N. "0...BYTES_N", where BYTES_N == 256**N.
audio_sample = uint .size 3 ; 24-bit, equivalent to 0..16777215 audio_sample = uint .size 3 ; 24-bit, equivalent to 0..16777215
Figure 8: Control for integer size in bytes Figure 9: Control for integer size in bytes
Note that, as with value restrictions in CDDL, this control is not a Note that, as with value restrictions in CDDL, this control is not a
representation constraint; a number that fits into fewer bytes can representation constraint; a number that fits into fewer bytes can
still be represented in that form, and an inefficient implementation still be represented in that form, and an inefficient implementation
could use a longer form (unless that is restricted by some format 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 constraints outside of CDDL, such as the rules in Section 3.9 of
[RFC7049]). [RFC7049]).
3.8.2. Control operator .bits 3.8.2. Control operator .bits
A ".bits" control on a byte string indicates that, in the target, 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 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 be set. (Bits are counted the usual way, bit number "n" being set in
"str" meaning that "(str[n >> 3] & (1 << (n & 7))) != 0".) "str" meaning that "(str[n >> 3] & (1 << (n & 7))) != 0".)
[_bitsendian]
Similarly, a ".bits" control on an unsigned integer "i" indicates Similarly, a ".bits" control on an unsigned integer "i" indicates
that for all unsigned integers "n" where "(i & (1 << n)) != 0", "n" that for all unsigned integers "n" where "(i & (1 << n)) != 0", "n"
must be in the control type. must be in the control type.
tcpflagbytes = bstr .bits flags tcpflagbytes = bstr .bits flags
flags = &( flags = &(
fin: 8, fin: 8,
syn: 9, syn: 9,
rst: 10, rst: 10,
psh: 11, psh: 11,
ack: 12, ack: 12,
urg: 13, urg: 13,
ece: 14, ece: 14,
cwr: 15, cwr: 15,
ns: 0, ns: 0,
) / (4..7) ; data offset bits ) / (4..7) ; data offset bits
rwxbits = uint .bits rwx rwxbits = uint .bits rwx
rwx = &(r: 2, w: 1, x: 0) rwx = &(r: 2, w: 1, x: 0)
Figure 9: Control for what bits can be set Figure 10: Control for what bits can be set
The CDDL tool generates the following ten example instances for The CDDL tool generates the following ten example instances for
"tcpflagbytes": "tcpflagbytes":
h'906d' h'01fc' h'8145' h'01b7' h'013d' h'409f' h'018e' h'c05f' h'906d' h'01fc' h'8145' h'01b7' h'013d' h'409f' h'018e' h'c05f'
h'01fa' h'01fe' h'01fa' h'01fe'
These examples do not illustrate that the above CDDL specification These examples do not illustrate that the above CDDL specification
does not explicitly specify a size of two bytes: A valid all clear 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'" instance of flag bytes could be "h''" or "h'00'" or even "h'000000'"
skipping to change at page 24, line 14 skipping to change at page 25, line 43
3.8.3. Control operator .regexp 3.8.3. Control operator .regexp
A ".regexp" control indicates that the text string given as a target A ".regexp" control indicates that the text string given as a target
needs to match the XSD regular expression given as a value in the needs to match the XSD regular expression given as a value in the
control type. XSD regular expressions are defined in Appendix F of control type. XSD regular expressions are defined in Appendix F of
[W3C.REC-xmlschema-2-20041028]. [W3C.REC-xmlschema-2-20041028].
nai = tstr .regexp "[A-Za-z0-9]+@[A-Za-z0-9]+(\\.[A-Za-z0-9]+)+" nai = tstr .regexp "[A-Za-z0-9]+@[A-Za-z0-9]+(\\.[A-Za-z0-9]+)+"
Figure 10: Control with an XSD regexp Figure 11: Control with an XSD regexp
The CDDL tool proposes: The CDDL tool proposes:
"N1@CH57HF.4Znqe0.dYJRN.igjf" "N1@CH57HF.4Znqe0.dYJRN.igjf"
3.8.3.1. Usage considerations 3.8.3.1. Usage considerations
Note that XSD regular expressions do not support the usual \x or \u Note that XSD regular expressions do not support the usual \x or \u
escapes for hexadecimal expression of bytes or unicode code points. escapes for hexadecimal expression of bytes or unicode code points.
However, in CDDL the XSD regular expressions are contained in text However, in CDDL the XSD regular expressions are contained in text
skipping to change at page 26, line 36 skipping to change at page 28, line 20
The controls .lt, .le, .gt, .ge, .eq, .ne specify a constraint on the The controls .lt, .le, .gt, .ge, .eq, .ne specify a constraint on the
left hand side type to be a value less than, less than or equal, left hand side type to be a value less than, less than or equal,
equal to, not equal to, greater than, or greater than or equal to a equal to, not equal to, greater than, or greater than or equal to a
value given as a (single-valued) right hand side type. In the value given as a (single-valued) right hand side type. In the
present specification, the first four controls (.lt, .le, .gt, .ge) present specification, the first four controls (.lt, .le, .gt, .ge)
are defined only for numeric types, as these have a natural ordering are defined only for numeric types, as these have a natural ordering
relationship. relationship.
speed = number .ge 0 ; unit: m/s speed = number .ge 0 ; unit: m/s
.ne and .eq are defined both for 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,
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 A variant of the ".ne" control is the ".default" control, which
expresses an additional intent: the value specified by the right- expresses an additional intent: the value specified by the right-
hand-side type is intended as a default value for the left hand side 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 type given, and the implied .ne control is there to prevent this
value from being sent over the wire. This control is only meaningful value from being sent over the wire. This control is only meaningful
when the control type is used in an optional context; otherwise there when the control type is used in an optional context; otherwise there
would be no way to express the default value. would be no way to express the default value.
timer = { timer = {
time: uint, time: uint,
skipping to change at page 27, line 40 skipping to change at page 29, line 40
) )
Names that start with a single "$" are "type sockets", names with a Names that start with a single "$" are "type sockets", names with a
double "$$" are "group sockets". It is not an error if there is no double "$$" are "group sockets". It is not an error if there is no
definition for a socket at all; this then means there is no way to definition for a socket at all; this then means there is no way to
satisfy the rule (i.e., the choice is empty). satisfy the rule (i.e., the choice is empty).
All definitions (plugs) for socket names must be augmentations, i.e., All definitions (plugs) for socket names must be augmentations, i.e.,
they must be using "/=" and "//=", respectively. they must be using "/=" and "//=", respectively.
To pick up the example illustrated in Figure 6, the socket/plug To pick up the example illustrated in Figure 7, the socket/plug
mechanism could be used as shown in Figure 11: mechanism could be used as shown in Figure 12:
PersonalData = { PersonalData = {
? displayName: tstr, ? displayName: tstr,
NameComponents, NameComponents,
? age: uint, ? age: uint,
* $$personaldata-extensions * $$personaldata-extensions
} }
NameComponents = ( NameComponents = (
? firstName: tstr, ? firstName: tstr,
skipping to change at page 28, line 30 skipping to change at page 30, line 30
$$personaldata-extensions //= ( $$personaldata-extensions //= (
favorite-salsa: tstr, favorite-salsa: tstr,
) )
; and again, somewhere else: ; and again, somewhere else:
$$personaldata-extensions //= ( $$personaldata-extensions //= (
shoesize: uint, shoesize: uint,
) )
Figure 11: Personal Data example: Using socket/plug extensibility Figure 12: Personal Data example: Using socket/plug extensibility
3.10. Generics 3.10. Generics
Using angle brackets, the left hand side of a rule can add formal Using angle brackets, the left hand side of a rule can add formal
parameters after the name being defined, as in: parameters after the name being defined, as in:
messages = message<"reboot", "now"> / message<"sleep", 1..100> messages = message<"reboot", "now"> / message<"sleep", 1..100>
message<t, v> = {type: t, value: v} message<t, v> = {type: t, value: v}
When using a generic rule, the formal parameters are bound to the When using a generic rule, the formal parameters are bound to the
actual arguments supplied (also using angle brackets), within the actual arguments supplied (also using angle brackets), within the
scope of the generic rule (as if there were a rule of the form scope of the generic rule (as if there were a rule of the form
parameter = argument). parameter = argument).
(There are some limitations to nesting of generics in Appendix F at Generic rules can be used for establishing names for both types and
this time.) groups.
(There are some limitations to nesting of generics in the tool
described in Appendix F at this time.)
3.11. Operator Precedence 3.11. Operator Precedence
As with any language that has multiple syntactic features such as As with any language that has multiple syntactic features such as
prefix and infix operators, CDDL has operators that bind more tightly prefix and infix operators, CDDL has operators that bind more tightly
than others. This is becoming more complicated than, say, in ABNF, than others. This is becoming more complicated than, say, in ABNF,
as CDDL has both types and groups, with operators that are specific as CDDL has both types and groups, with operators that are specific
to these concepts. Type operators (such as "/" for type choice) to these concepts. Type operators (such as "/" for type choice)
operate on types, while group operators (such as "//" for group operate on types, while group operators (such as "//" for group
choice) operate on groups. Types can simply be used in groups, but choice) operate on groups. Types can simply be used in groups, but
skipping to change at page 29, line 35 skipping to change at page 31, line 41
is a group choice between the optional member "ab" of type a or b and 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 the member "cd" of type c or d. Note that the optionality is
attached to the first choice ("ab"), not to the second choice. attached to the first choice ("ab"), not to the second choice.
Similarly, in Similarly, in
t = [group3] t = [group3]
group3 = (+ a / b / c) group3 = (+ a / b / c)
a = 1 b = 2 c = 3 a = 1 b = 2 c = 3
group3 is a repetition of a type choice between a, b, and c [unflex]; group3 is a repetition of a type choice between a, b, and c; if just
if just a is to be repeatable, a group choice is needed to focus the a is to be repeatable, a group choice is needed to focus the
occurrence: occurrence:
(A comment has been that this could be counter-intuitive. The
specification writer is encouraged to use parentheses liberally to
guide readers that are not familiar with CDDL precedence rules.)
t = [group4] t = [group4]
group4 = (+ a // b / c) group4 = (+ a // b / c)
a = 1 b = 2 c = 3 a = 1 b = 2 c = 3
group4 is a group choice between a repeatable a and a single b or c. group4 is a group choice between a repeatable a and a single b or c.
In general, as with many other languages with operator precedence In general, as with many other languages with operator precedence
rules, it is best not to rely on them, but to insert parentheses for rules, it is best not to rely on them, but to insert parentheses for
readability: readability:
t = [group4a] t = [group4a]
group4a = ((+ a) // (b / c)) group4a = ((+ a) // (b / c))
a = 1 b = 2 c = 3 a = 1 b = 2 c = 3
The operator precedences, in sequence of loose to tight binding, are The operator precedences, in sequence of loose to tight binding, are
defined in Appendix B and summarized in Table 1. (Arities given are defined in Appendix B and summarized in Table 1. (Arities given are
1 for unary prefix operators and 2 for binary infix operators.) 1 for unary prefix operators and 2 for binary infix operators.)
+----------+----+---------------------------+------+ +----------+----+---------------------------+------+
| Operator | Ar | Operates on | Prec | | Operator | Ar | Operates on | Prec |
+----------+----+---------------------------+------+ +----------+----+---------------------------+------+
| = | 2 | name = type, name = group | 1 | | = | 2 | name = type, name = group | 1 |
| /= | 2 | name /= type | 1 | | /= | 2 | name /= type | 1 |
| //= | 2 | name //= group | 1 | | //= | 2 | name //= group | 1 |
skipping to change at page 30, line 23 skipping to change at page 32, line 33
| //= | 2 | name //= group | 1 | | //= | 2 | name //= group | 1 |
| // | 2 | group // group | 2 | | // | 2 | group // group | 2 |
| , | 2 | group, group | 3 | | , | 2 | group, group | 3 |
| * | 1 | * group | 4 | | * | 1 | * group | 4 |
| N*M | 1 | N*M group | 4 | | N*M | 1 | N*M group | 4 |
| + | 1 | + group | 4 | | + | 1 | + group | 4 |
| ? | 1 | ? group | 4 | | ? | 1 | ? group | 4 |
| => | 2 | type => type | 5 | | => | 2 | type => type | 5 |
| : | 2 | name: type | 5 | | : | 2 | name: type | 5 |
| / | 2 | type / type | 6 | | / | 2 | type / type | 6 |
| & | 1 | &group | 6 |
| .. | 2 | type..type | 7 | | .. | 2 | type..type | 7 |
| ... | 2 | type...type | 7 | | ... | 2 | type...type | 7 |
| .anno | 2 | type .anno type | 7 | | .anno | 2 | type .anno type | 7 |
| & | 1 | &group | 8 |
| ~ | 1 | ~type | 8 |
+----------+----+---------------------------+------+ +----------+----+---------------------------+------+
Table 1: Summary of operator precedences Table 1: Summary of operator precedences
4. Making Use of CDDL 4. Making Use of CDDL
In this section, we discuss several potential ways to employ CDDL. In this section, we discuss several potential ways to employ CDDL.
4.1. As a guide to a human user 4.1. As a guide to a human user
skipping to change at page 32, line 17 skipping to change at page 34, line 28
Keep it as simple as possible while still expressing the needed data Keep it as simple as possible while still expressing the needed data
model. model.
A related observation about formal description techniques in general A related observation about formal description techniques in general
that is strongly recommended to be kept in mind by writers of CDDL that is strongly recommended to be kept in mind by writers of CDDL
specifications: Just because CDDL makes it easier to handle specifications: Just because CDDL makes it easier to handle
complexity in a specification, that does not make that complexity complexity in a specification, that does not make that complexity
somehow less bad (except maybe on the level of the humans having to somehow less bad (except maybe on the level of the humans having to
grasp the complex structure while reading the spec). grasp the complex structure while reading the spec).
6. IANA considerations 6. IANA Considerations
6.1. CDDL control operator registry 6.1. CDDL control operator registry
IANA is requested ... IANA is requested to create a registry for control operators
Section 3.8. The name of this registry is "CDDL Control Operators".
(TBD: define a registry of control operators. Policy to be defined, Each entry in the subregistry must include the name of the control
definitely at least specification required. Designated expert should operator (by convention given with the leading dot) and a reference
be instructed to require a workable specification that enables to its documentation. Names must be composed of the leading dot
interoperability of implementations of CDDL specifications making use followed by a text string conforming to the production "id" in
of the control operator. Define initial table from the present Appendix B.
document.)
Initial entries in this registry are as follows:
+----------+---------------+
| name | documentation |
+----------+---------------+
| .size | [RFCthis] |
| .bits | [RFCthis] |
| .regexp | [RFCthis] |
| .cbor | [RFCthis] |
| .cborseq | [RFCthis] |
| .within | [RFCthis] |
| .and | [RFCthis] |
| .lt | [RFCthis] |
| .le | [RFCthis] |
| .gt | [RFCthis] |
| .ge | [RFCthis] |
| .eq | [RFCthis] |
| .ne | [RFCthis] |
| .default | [RFCthis] |
+----------+---------------+
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 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.
7. References 7. References
7.1. Normative References 7.1. Normative References
[ISO6093] ISO, "Information processing -- Representation of [ISO6093] ISO, "Information processing -- Representation of
numerical values in character strings for information numerical values in character strings for information
interchange", ISO 6093, 1985. interchange", ISO 6093, 1985.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
skipping to change at page 33, line 13 skipping to change at page 36, line 18
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
DOI 10.17487/RFC7493, March 2015, DOI 10.17487/RFC7493, March 2015,
<https://www.rfc-editor.org/info/rfc7493>. <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>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
[W3C.REC-xmlschema-2-20041028] [W3C.REC-xmlschema-2-20041028]
Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium Recommendation Second Edition", World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028, October 2004, REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
7.2. Informative References 7.2. Informative References
[I-D.bormann-cbor-cddl-freezer] [I-D.bormann-cbor-cddl-freezer]
Bormann, C., "A feature freezer for the Concise Data Bormann, C., "A feature freezer for the Concise Data
Definition Language (CDDL)", draft-bormann-cbor-cddl- Definition Language (CDDL)", draft-bormann-cbor-cddl-
freezer-00 (work in progress), January 2018. freezer-01 (work in progress), August 2018.
[I-D.ietf-anima-grasp] [I-D.ietf-anima-grasp]
Bormann, C., Carpenter, B., and B. Liu, "A Generic Bormann, C., Carpenter, B., and B. Liu, "A Generic
Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- Autonomic Signaling Protocol (GRASP)", draft-ietf-anima-
grasp-15 (work in progress), July 2017. grasp-15 (work in progress), July 2017.
[I-D.ietf-core-senml] [I-D.ietf-core-senml]
Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
Bormann, "Sensor Measurement Lists (SenML)", draft-ietf- Bormann, "Sensor Measurement Lists (SenML)", draft-ietf-
core-senml-16 (work in progress), May 2018. core-senml-16 (work in progress), May 2018.
[I-D.newton-json-content-rules] [I-D.newton-json-content-rules]
Newton, A. and P. Cordell, "A Language for Rules Newton, A. and P. Cordell, "A Language for Rules
Describing JSON Content", draft-newton-json-content- Describing JSON Content", draft-newton-json-content-
rules-09 (work in progress), September 2017. rules-09 (work in progress), September 2017.
[PEG] Ford, B., "Parsing expression grammars", Proceedings of
the 31st ACM SIGPLAN-SIGACT symposium on Principles of
programming languages - POPL '04,
DOI 10.1145/964001.964011, 2004.
[RELAXNG] ISO/IEC, "Information technology -- Document Schema [RELAXNG] ISO/IEC, "Information technology -- Document Schema
Definition Language (DSDL) -- Part 2: Regular-grammar- Definition Language (DSDL) -- Part 2: Regular-grammar-
based validation -- RELAX NG", ISO/IEC 19757-2, December based validation -- RELAX NG", ISO/IEC 19757-2, December
2008. 2008.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
[RFC7071] Borenstein, N. and M. Kucherawy, "A Media Type for [RFC7071] Borenstein, N. and M. Kucherawy, "A Media Type for
skipping to change at page 34, line 35 skipping to change at page 37, line 50
7.3. URIs 7.3. URIs
[1] https://github.com/cabo/cbor-diag [1] https://github.com/cabo/cbor-diag
Appendix A. (Not used.) Appendix A. (Not used.)
Appendix B. ABNF grammar Appendix B. ABNF grammar
The following is a formal definition of the CDDL syntax in Augmented The following is a formal definition of the CDDL syntax in Augmented
Backus-Naur Form (ABNF, [RFC5234]). [_abnftodo] Backus-Naur Form (ABNF, [RFC5234]).
cddl = S 1*rule cddl = S 1*(rule S)
rule = typename [genericparm] S assign S type S rule = typename [genericparm] S assign S type
/ groupname [genericparm] S assign S grpent S / groupname [genericparm] S assign S grpent
typename = id typename = id
groupname = id groupname = id
assign = "=" / "/=" / "//=" assign = "=" / "/=" / "//="
genericparm = "<" S id S *("," S id S ) ">" genericparm = "<" S id S *("," S id S ) ">"
genericarg = "<" S type1 S *("," S type1 S ) ">" genericarg = "<" S type1 S *("," S type1 S ) ">"
type = type1 S *("/" S type1 S) type = type1 *(S "/" S type1)
type1 = type2 [S (rangeop / ctlop) S type2] type1 = type2 [S (rangeop / ctlop) S type2]
type2 = value
/ typename [genericarg]
/ "(" type ")"
/ "~" S groupname [genericarg]
/ "#" "6" ["." uint] "(" S type S ")" ; note no space!
/ "#" DIGIT ["." uint] ; major/ai
/ "#" ; any
/ "{" S group S "}"
/ "[" S group S "]"
/ "&" S "(" S group S ")"
/ "&" S groupname [genericarg]
rangeop = "..." / ".." 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 ")" ; note no space!
/ "#" DIGIT ["." uint] ; major/ai
/ "#" ; any
ctlop = "." id rangeop = "..." / ".."
group = grpchoice S *("//" S grpchoice S) ctlop = "." id
grpchoice = *grpent group = grpchoice *(S "//" S grpchoice)
grpent = [occur S] [memberkey S] type optcom grpchoice = *(grpent optcom)
/ [occur S] groupname [genericarg] optcom ; preempted by above
/ [occur S] "(" S group S ")" optcom
memberkey = type1 S ["^" S] "=>" grpent = [occur S] [memberkey S] type
/ bareword S ":" / [occur S] groupname [genericarg] ; preempted by above
/ value S ":" / [occur S] "(" S group S ")"
bareword = id memberkey = type1 S ["^" S] "=>"
/ bareword S ":"
/ value S ":"
optcom = S ["," S] bareword = id
occur = [uint] "*" [uint] optcom = S ["," S]
/ "+"
/ "?"
uint = ["0x" / "0b"] "0" occur = [uint] "*" [uint]
/ DIGIT1 *DIGIT / "+"
/ "0x" 1*HEXDIG / "?"
/ "0b" 1*BINDIG
value = number uint = DIGIT1 *DIGIT
/ text / "0x" 1*HEXDIG
/ bytes / "0b" 1*BINDIG
/ "0"
int = ["-"] uint value = number
/ text
/ bytes
; This is a float if it has fraction or exponent; int otherwise int = ["-"] uint
number = hexfloat / (int ["." fraction] ["e" exponent ])
hexfloat = "0x" 1*HEXDIG ["." 1*HEXDIG] "p" exponent
fraction = 1*DIGIT
exponent = ["+"/"-"] 1*DIGIT
text = %x22 *SCHAR %x22 ; This is a float if it has fraction or exponent; int otherwise
SCHAR = %x20-21 / %x23-5B / %x5D-10FFFD / SESC number = hexfloat / (int ["." fraction] ["e" exponent ])
SESC = "\" %x20-10FFFD hexfloat = "0x" 1*HEXDIG ["." 1*HEXDIG] "p" exponent
fraction = 1*DIGIT
exponent = ["+"/"-"] 1*DIGIT
bytes = [bsqual] %x27 *BCHAR %x27 text = %x22 *SCHAR %x22
BCHAR = %x20-26 / %x28-5B / %x5D-10FFFD / SESC / CRLF SCHAR = %x20-21 / %x23-5B / %x5D-10FFFD / SESC
bsqual = %x68 ; "h" SESC = "\" %x20-10FFFD
/ %x62.36.34 ; "b64"
id = EALPHA *(*("-" / ".") (EALPHA / DIGIT)) bytes = [bsqual] %x27 *BCHAR %x27
ALPHA = %x41-5A / %x61-7A BCHAR = %x20-26 / %x28-5B / %x5D-10FFFD / SESC / CRLF
EALPHA = %x41-5A / %x61-7A / "@" / "_" / "$" bsqual = "h" / "b64"
DIGIT = %x30-39
DIGIT1 = %x31-39
HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
BINDIG = %x30-31
S = *WS id = EALPHA *(*("-" / ".") (EALPHA / DIGIT))
WS = SP / NL ALPHA = %x41-5A / %x61-7A
SP = %x20 EALPHA = ALPHA / "@" / "_" / "$"
NL = COMMENT / CRLF DIGIT = %x30-39
COMMENT = ";" *PCHAR CRLF DIGIT1 = %x31-39
PCHAR = %x20-10FFFD HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
CRLF = %x0A / %x0D.0A BINDIG = %x30-31
Figure 12: CDDL ABNF S = *WS
WS = SP / NL
SP = %x20
NL = COMMENT / CRLF
COMMENT = ";" *PCHAR CRLF
PCHAR = %x20-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 Appendix C. Matching rules
In this appendix, we go through the ABNF syntax rules defined in In this appendix, we go through the ABNF syntax rules defined in
Appendix B and briefly describe the matching semantics of each Appendix B and briefly describe the matching semantics of each
syntactic feature. In this context, an instance (data item) syntactic feature. In this context, an instance (data item)
"matches" a CDDL specification if it is allowed by the CDDL "matches" a CDDL specification if it is allowed by the CDDL
specification; this is then broken down to parts of specifications specification; this is then broken down to parts of specifications
(type and group expressions) and parts of instances (data items). (type and group expressions) and parts of instances (data items).
skipping to change at page 37, line 34 skipping to change at page 41, line 4
collecting all the right hand sides and creating a single rule with a 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 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 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 that has not yet been defined; this makes the right hand side the
first entry in the choice being created.) The creation of the type first entry in the choice being created.) The creation of the type
choices and group choices from the right hand sides of rules is the choices and group choices from the right hand sides of rules is the
other case where rule order can be significant. other case where rule order can be significant.
genericparm = "<" S id S *("," S id S ) ">" genericparm = "<" S id S *("," S id S ) ">"
genericarg = "<" S type1 S *("," S type1 S ) ">" genericarg = "<" S type1 S *("," S type1 S ) ">"
Rule names can have generic parameters, which cause temporary Rule names can have generic parameters, which cause temporary
assignments within the right hand sides to the parameter names from assignments within the right hand sides to the parameter names from
the arguments given when citing the rule name. the arguments given when citing the rule name.
type = type1 S *("/" S type1 S) type = type1 S *("/" S type1 S)
A type can be given as a choice between one or more types. The 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 choice matches a data item if the data item matches any one of the
types given in the choice. The choice uses Parse Expression Grammar types given in the choice. The choice uses Parsing Expression
(PEG) semantics: The first choice that matches wins. (As a result, Grammar [PEG] semantics: The first choice that matches wins. (As a
the order of rules that contribute to a single rule name can very result, the order of rules that contribute to a single rule name can
well matter.) very well matter.)
type1 = type2 [S (rangeop / ctlop) S type2] type1 = type2 [S (rangeop / ctlop) S type2]
Two types can be combined with a range operator (which see below) or Two types can be combined with a range operator (which see below) or
a control operator (see Section 3.8). a control operator (see Section 3.8).
type2 = value type2 = value
A type can be just a single value (such as 1 or "icecream" or 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 h'0815'), which matches only a data item with that specific value (no
skipping to change at page 38, line 21 skipping to change at page 41, line 38
/ typename [genericarg] / typename [genericarg]
or be defined by a rule giving a meaning to a name (possibly after or be defined by a rule giving a meaning to a name (possibly after
supplying generic args as required by the generic parameters), supplying generic args as required by the generic parameters),
/ "(" type ")" / "(" type ")"
or be defined in a parenthesized type expression (parentheses may be or be defined in a parenthesized type expression (parentheses may be
necessary to override some operator precendence), or necessary to override some operator precendence), or
/ "~" S groupname [genericarg] / "~" S typename [genericarg]
an "unwrapped" group (see Section 3.7), which matches the group 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 inside a type defined as a map or an array by wrapping the group, or
/ "#" "6" ["." uint] "(" S type S ")" ; note no space! / "#" "6" ["." uint] "(" S type S ")" ; note no space!
a tagged data item, tagged with the "uint" given and containing the a tagged data item, tagged with the "uint" given and containing the
type given as the tagged value, or type given as the tagged value, or
/ "#" DIGIT ["." uint] ; major/ai / "#" DIGIT ["." uint] ; major/ai
skipping to change at page 39, line 28 skipping to change at page 42, line 44
ctlop = "." id ctlop = "." id
A control operator ties a _target_ type to a _controller_ type as A control operator ties a _target_ type to a _controller_ type as
defined in Section 3.8. Note that control operators are an extension defined in Section 3.8. Note that control operators are an extension
point for CDDL; additional documents may want to define additional point for CDDL; additional documents may want to define additional
control operators. control operators.
group = grpchoice S *("//" S grpchoice S) group = grpchoice S *("//" S grpchoice S)
A group matches any sequence of key/value pairs that matches any of A group matches any sequence of key/value pairs that matches any of
the choices given (again using Parse Expression Grammar semantics). the choices given (again using Parsing Expression Grammar semantics).
grpchoice = *grpent grpchoice = *grpent
Each of the component groups is given as a sequence of group entries. 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 For a match, the sequence of key/value pairs given needs to match the
sequence of group entries in the sequence given. sequence of group entries in the sequence given.
grpent = [occur S] [memberkey S] type optcom grpent = [occur S] [memberkey S] type optcom
A group entry can be given by a value type, which needs to be matched A group entry can be given by a value type, which needs to be matched
skipping to change at page 40, line 45 skipping to change at page 44, line 12
requiring the group to match the sequence to be matched exactly for a 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 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 as a (possibly infinite) group choice that contains choices with the
group repeated each of the occurrences times. group repeated each of the occurrences times.
The rest of the ABNF describes syntax for value notation that should The rest of the ABNF describes syntax for value notation that should
be familiar from programming languages, with the possible exception be familiar from programming languages, with the possible exception
of h'..' and b64'..' for byte strings, as well as syntactic elements of h'..' and b64'..' for byte strings, as well as syntactic elements
such as comments and line ends. such as comments and line ends.
Appendix D. (Not used.) Appendix D. Standard Prelude
Appendix E. Standard Prelude
The following prelude is automatically added to each CDDL file The following prelude is automatically added to each CDDL file.
[tdate]. (Note that technically, it is a postlude, as it does not (Note that technically, it is a postlude, as it does not disturb the
disturb the selection of the first rule as the root of the selection of the first rule as the root of the definition.)
definition.)
any = # any = #
uint = #0 uint = #0
nint = #1 nint = #1
int = uint / nint int = uint / nint
bstr = #2 bstr = #2
bytes = bstr bytes = bstr
tstr = #3 tstr = #3
text = tstr text = tstr
skipping to change at page 41, line 50 skipping to change at page 45, line 50
float32-64 = float32 / float64 float32-64 = float32 / float64
float = float16-32 / float64 float = float16-32 / float64
false = #7.20 false = #7.20
true = #7.21 true = #7.21
bool = false / true bool = false / true
nil = #7.22 nil = #7.22
null = nil null = nil
undefined = #7.23 undefined = #7.23
Figure 13: CDDL Prelude Figure 14: CDDL Prelude
Note that the prelude is deemed to be fixed. This means, for Note that the prelude is deemed to be fixed. This means, for
instance, that additional tags beyond [RFC7049], as registered, need instance, that additional tags beyond [RFC7049], as registered, need
to be defined in each CDDL file that is using them. to be defined in each CDDL file that is using them.
A common stumbling point is that the prelude does not define a type A common stumbling point is that the prelude does not define a type
"string". CBOR has byte strings ("bytes" in the prelude) and text "string". CBOR has byte strings ("bytes" in the prelude) and text
strings ("text"), so a type that is simply called "string" would be strings ("text"), so a type that is simply called "string" would be
ambiguous. ambiguous.
E.1. Use with JSON Appendix E. Use with JSON
The JSON generic data model (implicit in [RFC8259]) is a subset of 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 the generic data model of CBOR. So one can use CDDL with JSON by
limiting oneself to what can be represented in JSON. Roughly limiting oneself to what can be represented in JSON. Roughly
speaking, this means leaving out byte strings, tags, and simple speaking, this means leaving out byte strings, tags, and simple
values other than "false", "true", and "null", leading to the values other than "false", "true", and "null", leading to the
following limited prelude: following limited prelude:
any = # any = #
skipping to change at page 42, line 47 skipping to change at page 46, line 47
float16-32 = float16 / float32 float16-32 = float16 / float32
float32-64 = float32 / float64 float32-64 = float32 / float64
float = float16-32 / float64 float = float16-32 / float64
false = #7.20 false = #7.20
true = #7.21 true = #7.21
bool = false / true bool = false / true
nil = #7.22 nil = #7.22
null = nil null = nil
Figure 14: JSON compatible subset of CDDL Prelude Figure 15: JSON compatible subset of CDDL Prelude
(The major types given here do not have a direct meaning in JSON, but (The major types given here do not have a direct meaning in JSON, but
they can be interpreted as CBOR major types translated through they can be interpreted as CBOR major types translated through
Section 4 of [RFC7049].) Section 4 of [RFC7049].)
There are a few fine points in using CDDL with JSON. First, JSON There are a few fine points in using CDDL with JSON. First, JSON
does not distinguish between integers and floating point numbers; does not distinguish between integers and floating point numbers;
there is only one kind of number (which may happen to be integral). 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 In this context, specifying a type as "uint", "nint" or "int" then
becomes a predicate that the number be integral. As an example, this becomes a predicate that the number be integral. As an example, this
means that the following JSON numbers are all matching "uint": means that the following JSON numbers are all matching "uint":
skipping to change at page 43, line 36 skipping to change at page 47, line 36
numbers and decimal fractions and does not have limits to its numbers and decimal fractions and does not have limits to its
precision or range. In practice, JSON numbers are often parsed into precision or range. In practice, JSON numbers are often parsed into
a number type that is called float64 here, creating a number of a number type that is called float64 here, creating a number of
limitations to the generic data model [RFC7493]. In particular, this limitations to the generic data model [RFC7493]. In particular, this
means that integers can only be expressed with interoperable means that integers can only be expressed with interoperable
exactness when they lie in the range [-(2**53)+1, (2**53)-1] -- a exactness when they lie in the range [-(2**53)+1, (2**53)-1] -- a
smaller range than that covered by CDDL "int". smaller range than that covered by CDDL "int".
JSON applications that want to stay compatible with I-JSON therefore JSON applications that want to stay compatible with I-JSON therefore
may want to define integer types with more limited ranges, such as in may want to define integer types with more limited ranges, such as in
Figure 15. Note that the types given here are not part of the Figure 16. Note that the types given here are not part of the
prelude; they need to be copied into the CDDL specification if prelude; they need to be copied into the CDDL specification if
needed. needed.
ij-uint = 0..9007199254740991 ij-uint = 0..9007199254740991
ij-nint = -9007199254740991..-1 ij-nint = -9007199254740991..-1
ij-int = -9007199254740991..9007199254740991 ij-int = -9007199254740991..9007199254740991
Figure 15: I-JSON types for CDDL (not part of prelude) Figure 16: I-JSON types for CDDL (not part of prelude)
JSON applications that do not need to stay compatible with I-JSON and 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 that actually may need to go beyond the 64-bit unsigned and negative
integers supported by "int" (= "uint"/"nint") may want to use the integers supported by "int" (= "uint"/"nint") may want to use the
following additional types from the standard prelude, which are following additional types from the standard prelude, which are
expressed in terms of tags but can straightforwardly be mapped into expressed in terms of tags but can straightforwardly be mapped into
JSON (but not I-JSON) numbers: JSON (but not I-JSON) numbers:
biguint = #6.2(bstr) biguint = #6.2(bstr)
bignint = #6.3(bstr) bignint = #6.3(bstr)
skipping to change at page 44, line 33 skipping to change at page 48, line 33
check the syntax, generate one or more instances (expressed in CBOR check the syntax, generate one or more instances (expressed in CBOR
diagnostic notation or in pretty-printed JSON), and validate an diagnostic notation or in pretty-printed JSON), and validate an
existing instance against the specification: existing instance against the specification:
Usage: Usage:
cddl spec.cddl generate [n] cddl spec.cddl generate [n]
cddl spec.cddl json-generate [n] cddl spec.cddl json-generate [n]
cddl spec.cddl validate instance.cbor cddl spec.cddl validate instance.cbor
cddl spec.cddl validate instance.json cddl spec.cddl validate instance.json
Figure 16: CDDL tool usage Figure 17: CDDL tool usage
Install on a system with a modern Ruby via: Install on a system with a modern Ruby via:
gem install cddl gem install cddl
Figure 17: CDDL tool installation Figure 18: CDDL tool installation
The accompanying CBOR diagnostic tools (which are automatically The accompanying CBOR diagnostic tools (which are automatically
installed by the above) are described in https://github.com/cabo/ installed by the above) are described in https://github.com/cabo/
cbor-diag [1]; they can be used to convert between binary CBOR, a cbor-diag [1]; they can be used to convert between binary CBOR, a
pretty-printed form of that, CBOR diagnostic notation, JSON, and pretty-printed form of that, CBOR diagnostic notation, JSON, and
YAML. YAML.
Appendix G. Extended Diagnostic Notation Appendix G. Extended Diagnostic Notation
Section 6 of [RFC7049] defines a "diagnostic notation" in order to be Section 6 of [RFC7049] defines a "diagnostic notation" in order to be
skipping to change at page 52, line 26 skipping to change at page 56, line 26
precision: text, precision: text,
Latitude: float, Latitude: float,
Longitude: float, Longitude: float,
Address: text, Address: text,
City: text, City: text,
State: text, State: text,
Zip: text, Zip: text,
Country: text Country: text
}] }]
Figure 18: JCR, Figure 2, in CDDL Figure 19: JCR, Figure 2, in CDDL
Apart from the lack of a need to quote the member names, text strings Apart from the lack of a need to quote the member names, text strings
are called "text" or "tstr" in CDDL ("string" would be ambiguous as are called "text" or "tstr" in CDDL ("string" would be ambiguous as
CBOR also provides byte strings). CBOR also provides byte strings).
The CDDL tool creates the below example instance for this: The CDDL tool creates the below example instance for this:
[{"precision": "pyrosphere", "Latitude": 0.5399712314350172, [{"precision": "pyrosphere", "Latitude": 0.5399712314350172,
"Longitude": 0.5157523963028087, "Address": "resow", "Longitude": 0.5157523963028087, "Address": "resow",
"City": "problemwise", "State": "martyrlike", "Zip": "preprove", "City": "problemwise", "State": "martyrlike", "Zip": "preprove",
skipping to change at page 54, line 5 skipping to change at page 58, line 5
Width: 0..1280, Width: 0..1280,
Height: 0..1024, Height: 0..1024,
) )
The CDDL tool creates the below example instance for this: The CDDL tool creates the below example instance for this:
{"Image": {"Width": 566, "Height": 516, "Title": "leisterer", {"Image": {"Width": 566, "Height": 516, "Title": "leisterer",
"Thumbnail": {"Width": 1111, "Height": 176, "Url": 32("scrog")}, "Thumbnail": {"Width": 1111, "Height": 176, "Url": 32("scrog")},
"IDs": []}} "IDs": []}}
Acknowledgements Contributors
CDDL was originally conceived by Bert Greevenbosch, who also wrote CDDL was originally conceived by Bert Greevenbosch, who also wrote
the original five versions of this document. the original five versions of this document.
Acknowledgements
Inspiration was taken from the C and Pascal languages, MPEG's Inspiration was taken from the C and Pascal languages, MPEG's
conventions for describing structures in the ISO base media file conventions for describing structures in the ISO base media file
format, Relax-NG and its compact syntax [RELAXNG], and in particular format, Relax-NG and its compact syntax [RELAXNG], and in particular
from Andrew Lee Newton's "JSON Content Rules" from Andrew Lee Newton's "JSON Content Rules"
[I-D.newton-json-content-rules]. [I-D.newton-json-content-rules].
Useful feedback came from members of the IETF CBOR WG, in particular Lots of highly useful feedback came from members of the IETF CBOR WG,
Joe Hildebrand, Sean Leonard and Jim Schaad. Also, Francesca in particular Brian Carpenter, Burt Harris, Jeffrey Yasskin, Jim
Palombini and Joe volunteered to chair this WG, providing the Hague, Jim Schaad, Joe Hildebrand, Max Pritikin, Michael Richardson,
framework for generating and processing this feedback. 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.
The CDDL tool was written by Carsten Bormann, building on previous The CDDL tool was written by Carsten Bormann, building on previous
work by Troy Heninger and Tom Lord. work by Troy Heninger and Tom Lord.
Editorial Comments
[_format] So far, the ability to restrict format choices have not been
needed beyond the floating point formats. Those can be
applied to ranges using the new .and control now. It is not
clear we want to add more format control before we have a use
case.
[_range] TO DO: define this precisely. This clearly includes integers
and floats. Strings - as in "a".."z" - could be added if
desired, but this would require adopting a definition of string
ordering and possibly a successor function so "a".."z" does not
include "bb".
[_strings] TO DO: This still needs to be fully realized in the ABNF and
in the CDDL tool.
[_bitsendian] How useful would it be to have another variant that counts
bits like in RFC box notation? (Or at least per-byte?
32-bit words don't always perfectly mesh with byte
strings.)
[unflex] A comment has been that this is counter-intuitive. One
solution would be to simply disallow unparenthesized usage of
occurrence indicators in front of type choices unless a member
key is also present like in group2 above.
[_abnftodo] Potential improvements: the prefixed byte strings are more
liberally specified than they actually are.
[tdate] The prelude as included here does not yet have a .regexp control
on tdate, but we probably do want to have one.
Authors' Addresses Authors' Addresses
Henk Birkholz Henk Birkholz
Fraunhofer SIT Fraunhofer SIT
Rheinstrasse 75 Rheinstrasse 75
Darmstadt 64295 Darmstadt 64295
Germany Germany
Email: henk.birkholz@sit.fraunhofer.de Email: henk.birkholz@sit.fraunhofer.de
 End of changes. 104 change blocks. 
253 lines changed or deleted 353 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/