draft-ietf-cbor-cddl-05.txt   draft-ietf-cbor-cddl-06.txt 
CBOR H. Birkholz CBOR H. Birkholz
Internet-Draft Fraunhofer SIT Internet-Draft Fraunhofer SIT
Intended status: Standards Track C. Vigano Intended status: Standards Track C. Vigano
Expires: February 24, 2019 Universitaet Bremen Expires: May 23, 2019 Universitaet Bremen
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
August 23, 2018 November 19, 2018
Concise data definition language (CDDL): a notational convention to Concise data definition language (CDDL): a notational convention to
express CBOR and JSON data structures express CBOR and JSON data structures
draft-ietf-cbor-cddl-05 draft-ietf-cbor-cddl-06
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, Concise Binary Object Representation). Its
unambiguous way to express structures for protocol messages and data main goal is to provide an easy and unambiguous way to express
formats that use CBOR or JSON. structures for protocol messages and data 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 February 24, 2019. This Internet-Draft will expire on May 23, 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 3, line 15 skipping to change at page 3, line 15
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.1. Normative References . . . . . . . . . . . . . . . . . . 36 7.1. Normative References . . . . . . . . . . . . . . . . . . 36
7.2. Informative References . . . . . . . . . . . . . . . . . 37 7.2. Informative References . . . . . . . . . . . . . . . . . 37
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 39 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 39
A.1. RFC 7071 . . . . . . . . . . . . . . . . . . . . . . . . 39 A.1. RFC 7071 . . . . . . . . . . . . . . . . . . . . . . . . 39
A.2. Examples from JSON Content Rules . . . . . . . . . . . . 43 A.2. Examples from JSON Content Rules . . . . . . . . . . . . 43
Appendix B. ABNF grammar . . . . . . . . . . . . . . . . . . . . 45 Appendix B. ABNF grammar . . . . . . . . . . . . . . . . . . . . 45
Appendix C. Matching rules . . . . . . . . . . . . . . . . . . . 47 Appendix C. Matching rules . . . . . . . . . . . . . . . . . . . 47
Appendix D. Standard Prelude . . . . . . . . . . . . . . . . . . 51 Appendix D. Standard Prelude . . . . . . . . . . . . . . . . . . 51
Appendix E. Use with JSON . . . . . . . . . . . . . . . . . . . 53 Appendix E. Use with JSON . . . . . . . . . . . . . . . . . . . 53
Appendix F. The CDDL tool . . . . . . . . . . . . . . . . . . . 55 Appendix F. A CDDL tool . . . . . . . . . . . . . . . . . . . . 55
Appendix G. Extended Diagnostic Notation . . . . . . . . . . . . 55 Appendix G. Extended Diagnostic Notation . . . . . . . . . . . . 56
G.1. White space in byte string notation . . . . . . . . . . . 56 G.1. White space in byte string notation . . . . . . . . . . . 56
G.2. Text in byte string notation . . . . . . . . . . . . . . 56 G.2. Text in byte string notation . . . . . . . . . . . . . . 56
G.3. Embedded CBOR and CBOR sequences in byte strings . . . . 56 G.3. Embedded CBOR and CBOR sequences in byte strings . . . . 57
G.4. Concatenated Strings . . . . . . . . . . . . . . . . . . 57 G.4. Concatenated Strings . . . . . . . . . . . . . . . . . . 57
G.5. Hexadecimal, octal, and binary numbers . . . . . . . . . 57 G.5. Hexadecimal, octal, and binary numbers . . . . . . . . . 58
G.6. Comments . . . . . . . . . . . . . . . . . . . . . . . . 58 G.6. Comments . . . . . . . . . . . . . . . . . . . . . . . . 58
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 59 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 59
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 59 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 59
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
skipping to change at page 11, line 9 skipping to change at page 11, line 9
lat: float, long: float, drone-type: tstr lat: float, long: float, drone-type: tstr
) )
It is not an error if a name is first used with a "/=" or "//=" It is not an error if a name is first used with a "/=" or "//="
(there is no need to "create it" with "="). (there is no need to "create it" with "=").
2.2.2.1. Ranges 2.2.2.1. Ranges
Instead of naming all the values that make up a choice, CDDL allows Instead of naming all the values that make up a choice, CDDL allows
building a _range_ out of two values that are in an ordering building a _range_ out of two values that are in an ordering
relationship. A range can be inclusive of both ends given (denoted relationship: A lower bound (first value) and an upper bound (second
by joining two values by ".."), or include the first and exclude the value). A range can be inclusive of both bounds given (denoted by
second (denoted by instead using "..."). joining two values by ".."), or include the lower bound and exclude
the upper bound (denoted by instead using "..."). If the lower bound
exceeds the upper bound, the resulting type is the empty set (this
behavior can be desirable when generics, Section 3.10, are being
used).
device-address = byte 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 integers (matching integer CDDL currently only allows ranges between integers (matching integer
values) or between floating point values (matching floating point values) or between floating point values (matching floating point
values). If both are needed in a type, a type choice between the two values). If both are needed in a type, a type choice between the two
skipping to change at page 11, line 34 skipping to change at page 11, line 38
int-range = 0..10 ; only integers match int-range = 0..10 ; only integers match
float-range = 0.0..10.0 ; only floats match float-range = 0.0..10.0 ; only floats match
BAD-range1 = 0..10.0 ; NOT DEFINED BAD-range1 = 0..10.0 ; NOT DEFINED
BAD-range2 = 0.0..10 ; NOT DEFINED BAD-range2 = 0.0..10 ; NOT DEFINED
numeric-range = int-range / float-range numeric-range = int-range / float-range
(See also the control operators .lt/.ge and .le/.gt in (See also the control operators .lt/.ge and .le/.gt in
Section 3.8.6.) Section 3.8.6.)
Note that the dot is a valid name continuation character in CDDL, so Note that the dot is a valid name continuation character in CDDL, so
"min..max" is not a range expression but a single name. When using a
name as the left hand side of a range operator, use spacing as in min..max
"min .. max" to separate off the range operator.
is not a range expression but a single name. When using a name as
the left hand side of a range operator, use spacing as in
min .. max
to separate off the range operator.
2.2.2.2. Turning a group into a choice 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 12, line 22 skipping to change at page 12, line 24
orange: 8, pink: 9, purple: 10, brown: 11, orange: 8, pink: 9, purple: 10, brown: 11,
) )
As with the use of groups in arrays (Section 3.4), the member names As with the use of groups in arrays (Section 3.4), the member names
have only documentary value (in particular, they might be used by a 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 types and additional information,
should be evident from the prelude (Appendix D): a hash mark ("#") Section 2 of [RFC7049]). How this is used should be evident from the
optionally followed by a number from 0 to 7 identifying the major prelude (Appendix D): a hash mark ("#") optionally followed by a
type, which then can be followed by a dot and a number specifying the number from 0 to 7 identifying the major type, which then can be
additional information. This construction specifies the set of followed by a dot and a number specifying the additional information.
values that can be serialized in CBOR (i.e., "any"), by the given This construction specifies the set of values that can be serialized
major type if one is given, or by the given major type with the in CBOR (i.e., "any"), by the given major type if one is given, or by
additional information if both are given. Where a major type of 6 the given major type with the additional information if both are
(Tag) is used, the type of the tagged item can be specified by given. Where a major type of 6 (Tag) is used, the type of the tagged
appending it in parentheses. item can be specified by appending it in parentheses.
Note that although this notation is based on the CBOR serialization, 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" 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 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 floats; it does not mandate that these values also do have to be
serialized as half-precision floats: CDDL does not provide any serialized as half-precision floats: CDDL does not provide any
language means to restrict the choice of serialization variants. language means to restrict the choice of serialization variants.
This also enables the use of CDDL with JSON, which uses a This also enables the use of CDDL with JSON, which uses a
fundamentally different way of serializing (some of) the same values. fundamentally different way of serializing (some of) the same values.
skipping to change at page 13, line 26 skipping to change at page 13, line 26
There is no special syntax to identify the root of a CDDL data There is no special syntax to identify the root of a CDDL data
structure definition: that role is simply taken by the first rule structure definition: that role is simply taken by the first rule
defined in the file. defined in the file.
This is motivated by the usual top-down approach for defining data This is motivated by the usual top-down approach for defining data
structures, decomposing a big data structure unit into smaller parts; structures, decomposing a big data structure unit into smaller parts;
however, except for the root type, there is no need to strictly however, except for the root type, there is no need to strictly
follow this sequence. follow this sequence.
(Note that there is no way to use a group as a root - it must be a (Note that there is no way to use a group as a root - it must be a
type. Using a group as the root might be employed as a way to type.)
specify a CBOR sequence in a future version of this specification;
this would act as if that group is used in an array and the data
items in that fictional array form the members of the CBOR sequence.)
3. Syntax 3. Syntax
In this section, the overall syntax of CDDL is shown, alongside some In this section, the overall syntax of CDDL is shown, alongside some
examples just illustrating syntax. (The definition will not attempt examples just illustrating syntax. (The definition will not attempt
to be overly formal; refer to Appendix B for the details.) to be overly formal; refer to Appendix B for the details.)
3.1. General conventions 3.1. General conventions
The basic syntax is inspired by ABNF [RFC5234], with The basic syntax is inspired by ABNF [RFC5234], with
skipping to change at page 20, line 19 skipping to change at page 20, line 19
* tstr => any * tstr => any
} }
NameComponents = ( NameComponents = (
? firstName: tstr, ? firstName: tstr,
? familyName: tstr, ? familyName: tstr,
) )
Figure 7: 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 reported on in Appendix F generated as one acceptable
this specification: instance for 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.)
3.5.2. Tables 3.5.2. Tables
skipping to change at page 26, line 23 skipping to change at page 26, line 23
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 10: 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 reported on in Appendix F generates the following ten
"tcpflagbytes": example instances for "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'"
as well. as well.
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 11: Control with an XSD regexp Figure 11: Control with an XSD regexp
The CDDL tool proposes: An example matching this regular expression:
"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
strings, the literal notation for which provides \u escapes; this strings, the literal notation for which provides \u escapes; this
should suffice for most applications that use regular expressions for should suffice for most applications that use regular expressions for
text strings. (Note that this also means that there is one level of text strings. (Note that this also means that there is one level of
string escaping before the XSD escaping rules are applied.) string escaping before the XSD escaping rules are applied.)
XSD regular expressions support character class subtraction, a XSD regular expressions support character class subtraction, a
feature often not found in regular expression libraries; feature often not found in regular expression libraries;
specification writers may want to use this feature sparingly. specification writers may want to use this feature sparingly.
Similar considerations apply to Unicode character classes; where Similar considerations apply to Unicode character classes; where
these are used, the specification SHOULD identify which Unicode these are used, the specification that employs CDDL SHOULD identify
versions are addressed. which Unicode versions are addressed.
Other surprises for infrequent users of XSD regular expressions may Other surprises for infrequent users of XSD regular expressions may
include: include:
o No direct support for case insensitivity. While case o No direct support for case insensitivity. While case
insensitivity has gone mostly out of fashion in protocol design, insensitivity has gone mostly out of fashion in protocol design,
it is sometimes needed and then needs to be expressed manually as it is sometimes needed and then needs to be expressed manually as
in "[Cc][Aa][Ss][Ee]". in "[Cc][Aa][Ss][Ee]".
o The support for popular character classes such as \w and \d is o The support for popular character classes such as \w and \d is
skipping to change at page 34, line 51 skipping to change at page 34, line 51
particular parts of interest from it. particular parts of interest from it.
Since CBOR is designed with constrained devices in mind, a likely use Since CBOR is designed with constrained devices in mind, a likely use
of it would be small sensors. An interesting use would thus be of it would be small sensors. An interesting use would thus be
automated analysis of sensor data. automated analysis of sensor data.
5. Security considerations 5. Security considerations
This document presents a content rules language for expressing CBOR This document presents a content rules language for expressing CBOR
data structures. As such, it does not bring any security issues on data structures. As such, it does not bring any security issues on
itself, although specification of protocols that use CBOR naturally itself, although specifications of protocols that use CBOR naturally
need security analysis when defined. need security analyses when defined. General guidelines for writing
security considerations are defined in
Topics that could be considered in a security considerations section Security Considerations Guidelines [RFC3552] (BCP 72).
Specifications using CDDL to define CBOR structures in protocols need
to follow those guidelines. Additional topics that could be
considered in a security considerations section for a specification
that uses CDDL to define CBOR structures include the following: that uses CDDL to define CBOR structures include the following:
o Where could the language maybe cause confusion in a way that will o Where could the language maybe cause confusion in a way that will
enable security issues? enable security issues?
o Where a CDDL matcher is part of the implementation of a system, o Where a CDDL matcher is part of the implementation of a system,
the security of the system ought not depend on the correctness of the security of the system ought not depend on the correctness of
the CDDL specification or CDDL implementation without any further the CDDL specification or CDDL implementation without any further
defenses in place. defenses in place.
skipping to change at page 36, line 48 skipping to change at page 36, line 48
[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
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552,
DOI 10.17487/RFC3552, July 2003,
<https://www.rfc-editor.org/info/rfc3552>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <https://www.rfc-editor.org/info/rfc3629>. 2003, <https://www.rfc-editor.org/info/rfc3629>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<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
skipping to change at page 38, line 5 skipping to change at page 38, line 5
[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-01 (work in progress), August 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]
Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
Bormann, "Sensor Measurement Lists (SenML)", draft-ietf-
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 [PEG] Ford, B., "Parsing expression grammars", Proceedings of
the 31st ACM SIGPLAN-SIGACT symposium on Principles of the 31st ACM SIGPLAN-SIGACT symposium on Principles of
programming languages - POPL '04, programming languages - POPL '04,
DOI 10.1145/964001.964011, 2004. DOI 10.1145/964001.964011, 2004.
skipping to change at page 38, line 46 skipping to change at page 38, line 41
[RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network [RFC8007] Murray, R. and B. Niven-Jenkins, "Content Delivery Network
Interconnection (CDNI) Control Interface / Triggers", Interconnection (CDNI) Control Interface / Triggers",
RFC 8007, DOI 10.17487/RFC8007, December 2016, RFC 8007, DOI 10.17487/RFC8007, December 2016,
<https://www.rfc-editor.org/info/rfc8007>. <https://www.rfc-editor.org/info/rfc8007>.
[RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)",
RFC 8152, DOI 10.17487/RFC8152, July 2017, RFC 8152, DOI 10.17487/RFC8152, July 2017,
<https://www.rfc-editor.org/info/rfc8152>. <https://www.rfc-editor.org/info/rfc8152>.
[RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
DOI 10.17487/RFC8428, August 2018,
<https://www.rfc-editor.org/info/rfc8428>.
7.3. URIs 7.3. URIs
[1] https://github.com/cabo/cbor-diag [1] https://github.com/cabo/cbor-diag
Appendix A. Examples Appendix A. Examples
This appendix is for information only.
This section contains a few examples of structures defined using This section contains a few examples of structures defined using
CDDL. CDDL.
The theme for the first example is taken from [RFC7071], which The theme for the first example is taken from [RFC7071], which
defines certain JSON structures in English. For a similar example, defines certain JSON structures in English. For a similar example,
it may also be of interest to examine Appendix A of [RFC8007], which it may also be of interest to examine Appendix A of [RFC8007], which
contains a CDDL definition for a JSON structure defined in the main contains a CDDL definition for a JSON structure defined in the main
body of the RFC. body of the RFC.
The second subsection in this appendix translates examples from The second subsection in this appendix translates examples from
[I-D.newton-json-content-rules] into CDDL. [I-D.newton-json-content-rules] into CDDL.
These examples all happen to describe data that is interchanged in These examples all happen to describe data that is interchanged in
JSON. Examples for CDDL definitions of data that is interchanged in JSON. Examples for CDDL definitions of data that is interchanged in
CBOR can be found in [RFC8152], [I-D.ietf-anima-grasp], or CBOR can be found in [RFC8152], [I-D.ietf-anima-grasp], or [RFC8428].
[I-D.ietf-core-senml].
A.1. RFC 7071 A.1. RFC 7071
[RFC7071] defines the Reputon structure for JSON using somewhat [RFC7071] defines the Reputon structure for JSON using somewhat
formalized English text. Here is a (somewhat verbose) equivalent formalized English text. Here is a (somewhat verbose) equivalent
definition using the same terms, but notated in CDDL: definition using the same terms, but notated in CDDL:
reputation-object = { reputation-object = {
reputation-context, reputation-context,
reputon-list reputon-list
skipping to change at page 41, line 30 skipping to change at page 41, line 30
* text => any * text => any
} }
Note how this rather clearly delineates the structure somewhat Note how this rather clearly delineates the structure somewhat
shrouded by so many words in section 6.2.2. of [RFC7071]. Also, this shrouded by so many words in section 6.2.2. of [RFC7071]. Also, this
definition makes it clear that several ext-values are allowed (by definition makes it clear that several ext-values are allowed (by
definition with different member names); RFC 7071 could be read to definition with different member names); RFC 7071 could be read to
forbid the repetition of ext-value ("A specific reputon-element MUST forbid the repetition of ext-value ("A specific reputon-element MUST
NOT appear more than once" is ambiguous.) NOT appear more than once" is ambiguous.)
The CDDL tool (which hasn't quite been trained for polite The CDDL tool reported on in Appendix F (which hasn't quite been
conversation) says: trained for polite conversation) says:
{ {
"application": "tridentiferous", "application": "tridentiferous",
"reputons": [ "reputons": [
{ {
"rater": "loamily", "rater": "loamily",
"assertion": "Dasyprocta", "assertion": "Dasyprocta",
"rated": "uncommensurableness", "rated": "uncommensurableness",
"rating": 0.05055809746548934, "rating": 0.05055809746548934,
"confidence": 0.7484706448605812, "confidence": 0.7484706448605812,
skipping to change at page 43, line 32 skipping to change at page 43, line 32
Zip: text, Zip: text,
Country: text Country: text
}] }]
Figure 13: JCR, Figure 2, in CDDL Figure 13: 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 reported on in Appendix F 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",
"Country": "Pace"}, "Country": "Pace"},
{"precision": "unrigging", "Latitude": 0.10422704368372193, {"precision": "unrigging", "Latitude": 0.10422704368372193,
"Longitude": 0.6279808663725834, "Address": "picturedom", "Longitude": 0.6279808663725834, "Address": "picturedom",
"City": "decipherability", "State": "autometry", "Zip": "pout", "City": "decipherability", "State": "autometry", "Zip": "pout",
"Country": "wimple"}] "Country": "wimple"}]
skipping to change at page 44, line 47 skipping to change at page 44, line 47
Thumbnail: { size, Url: ~uri }, Thumbnail: { size, Url: ~uri },
IDs: [* int] IDs: [* int]
} }
} }
size = ( size = (
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 reported on in Appendix F 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": []}}
Appendix B. ABNF grammar Appendix B. ABNF grammar
This appendix is normative.
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]). Backus-Naur Form (ABNF, [RFC5234]).
cddl = S 1*(rule S) cddl = S 1*(rule S)
rule = typename [genericparm] S assignt S type rule = typename [genericparm] S assignt S type
/ groupname [genericparm] S assigng S grpent / groupname [genericparm] S assigng S grpent
typename = id typename = id
groupname = id groupname = id
skipping to change at page 47, line 14 skipping to change at page 47, line 16
PCHAR = %x20-10FFFD PCHAR = %x20-10FFFD
CRLF = %x0A / %x0D.0A CRLF = %x0A / %x0D.0A
Figure 14: CDDL ABNF Figure 14: CDDL ABNF
Note that this ABNF does not attempt to reflect the detailed rules of Note that this ABNF does not attempt to reflect the detailed rules of
what can be in a prefixed byte string. what can be in a prefixed byte string.
Appendix C. Matching rules Appendix C. Matching rules
This appendix is normative.
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).
cddl = S 1*rule cddl = S 1*(rule S)
A CDDL specification is a sequence of one or more rules. Each rule A CDDL specification is a sequence of one or more rules. Each rule
gives a name to a right hand side expression, either a CDDL type or a gives a name to a right hand side expression, either a CDDL type or a
CDDL group. Rule names can be used in the rule itself and/or other CDDL group. Rule names can be used in the rule itself and/or other
rules (and tools can output warnings if that is not the case). The rules (and tools can output warnings if that is not the case). The
order of the rules is significant only in two cases: order of the rules is significant only in two cases:
1. The first rule defines the semantics of the entire specification; 1. The first rule defines the semantics of the entire specification;
hence, there is no need to give that root rule a special name or hence, there is no need to give that root rule a special name or
special syntax in the language (as, e.g., with "start" in Relax- special syntax in the language (as, e.g., with "start" in Relax-
NG); its name can be therefore chosen to be descriptive. (As NG); its name can be therefore chosen to be descriptive. (As
with all other rule names, the name of the initial rule may be with all other rule names, the name of the initial rule may be
used in itself or in other rules). used in itself or in other rules).
2. Where a rule contributes to a type or group choice (using "/=" or 2. Where a rule contributes to a type or group choice (using "/=" or
"//="), that choice is populated in the order the rules are "//="), that choice is populated in the order the rules are
given; see below. given; see below.
rule = typename [genericparm] S assignt S type S rule = typename [genericparm] S assignt S type
/ groupname [genericparm] S assigng S grpent S / groupname [genericparm] S assigng S grpent
typename = id typename = id
groupname = id groupname = id
A rule defines a name for a type expression (production "type") or A rule defines a name for a type expression (production "type") or
for a group expression (production "grpent"), with the intention that for a group expression (production "grpent"), with the intention that
the semantics does not change when the name is replaced by its the semantics does not change when the name is replaced by its
(parenthesized if needed) definition. Note that whether the name (parenthesized if needed) definition. Note that whether the name
defined by a rule stands for a type or a group isn't always defined by a rule stands for a type or a group isn't always
determined by syntax alone: e.g., "a = b" can make "a" a type if "b" determined by syntax alone: e.g., "a = b" can make "a" a type if "b"
skipping to change at page 48, line 34 skipping to change at page 48, line 38
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.) first entry in the choice being created.)
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)
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 Parsing Expression types given in the choice. The choice uses Parsing Expression
Grammar [PEG] semantics: The first choice that matches wins. (As a Grammar [PEG] semantics: The first choice that matches wins. (As a
result, the order of rules that contribute to a single rule name can result, the order of rules that contribute to a single rule name can
very well matter.) very well matter.)
type1 = type2 [S (rangeop / ctlop) S type2] type1 = type2 [S (rangeop / ctlop) S type2]
skipping to change at page 50, line 22 skipping to change at page 50, line 23
value is always included in the matching set and the second value is value is always included in the matching set and the second value is
included for ".." and excluded for "...". included for ".." and excluded for "...".
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)
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 Parsing Expression Grammar semantics). the choices given (again using Parsing Expression Grammar semantics).
grpchoice = *grpent grpchoice = *(grpent optcom)
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
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
by the value part of a single element, and optionally a memberkey by the value part of a single element, and optionally a memberkey
type, which needs to be matched by the key part of the element, if type, which needs to be matched by the key part of the element, if
the memberkey is given. If the memberkey is not given, the entry can the memberkey is given. If the memberkey is not given, the entry can
only be used for matching arrays, not for maps. (See below how that only be used for matching arrays, not for maps. (See below how that
is modified by the occurrence indicator.) is modified by the occurrence indicator.)
/ [occur S] groupname [genericarg] optcom ; preempted by above / [occur S] groupname [genericarg] ; preempted by above
A group entry can be built from a named group, or A group entry can be built from a named group, or
/ [occur S] "(" S group S ")" optcom / [occur S] "(" S group S ")"
from a parenthesized group, again with a possible occurrence from a parenthesized group, again with a possible occurrence
indicator. indicator.
memberkey = type1 S ["^" S] "=>" memberkey = type1 S ["^" S] "=>"
/ bareword S ":" / bareword S ":"
/ value S ":" / value S ":"
Key types can be given by a type expression, a bareword (which stands Key types can be given by a type expression, a bareword (which stands
for a type that just contains a string value created from this for a type that just contains a string value created from this
skipping to change at page 51, line 44 skipping to change at page 51, line 44
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. Standard Prelude Appendix D. Standard Prelude
This appendix is normative.
The following prelude is automatically added to each CDDL file. The following prelude is automatically added to each CDDL file.
(Note that technically, it is a postlude, as it does not disturb the (Note that technically, it is a postlude, as it does not disturb the
selection of the first rule as the root of the definition.) selection of the first rule as the root of the definition.)
any = # any = #
uint = #0 uint = #0
nint = #1 nint = #1
int = uint / nint int = uint / nint
bstr = #2 bstr = #2
skipping to change at page 53, line 16 skipping to change at page 53, line 16
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.
Appendix E. Use with JSON Appendix E. Use with JSON
This appendix is normative.
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 = #
uint = #0 uint = #0
skipping to change at page 54, line 34 skipping to change at page 54, line 39
Fundamentally, the number system of JSON itself is based on decimal Fundamentally, the number system of JSON itself is based on decimal
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
may want to define integer types with more limited ranges, such as in ([RFC7493], "Internet JSON") therefore may want to define integer
Figure 17. Note that the types given here are not part of the types with more limited ranges, such as in Figure 17. Note that the
prelude; they need to be copied into the CDDL specification if types given here are not part of the prelude; they need to be copied
needed. into the CDDL specification if 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 17: I-JSON types for CDDL (not part of prelude) Figure 17: 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
skipping to change at page 55, line 20 skipping to change at page 55, line 24
CDDL at this point does not have a way to express the unlimited CDDL at this point does not have a way to express the unlimited
floating point precision that is theoretically possible with JSON; at floating point precision that is theoretically possible with JSON; at
the time of writing, this is rarely used in protocols in practice. the time of writing, this is rarely used in protocols in practice.
Note that a data model described in CDDL is always restricted by what Note that a data model described in CDDL is always restricted by what
can be expressed in the serialization; e.g., floating point values can be expressed in the serialization; e.g., floating point values
such as NaN (not a number) and the infinities cannot be represented such as NaN (not a number) and the infinities cannot be represented
in JSON even if they are allowed in the CDDL generic data model. in JSON even if they are allowed in the CDDL generic data model.
Appendix F. The CDDL tool Appendix F. A CDDL tool
This appendix is for information only.
A rough CDDL tool is available. For CDDL specifications, it can A rough CDDL tool is available. For CDDL specifications, it can
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
skipping to change at page 55, line 49 skipping to change at page 56, line 7
Figure 19: CDDL tool installation Figure 19: 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
This appendix is normative.
Section 6 of [RFC7049] defines a "diagnostic notation" in order to be Section 6 of [RFC7049] defines a "diagnostic notation" in order to be
able to converse about CBOR data items without having to resort to able to converse about CBOR data items without having to resort to
binary data. Diagnostic notation is based on JSON, with extensions binary data. Diagnostic notation is based on JSON, with extensions
for representing CBOR constructs such as binary data and tags. for representing CBOR constructs such as binary data and tags.
(Standardizing this together with the actual interchange format does (Standardizing this together with the actual interchange format does
not serve to create another interchange format, but enables the use not serve to create another interchange format, but enables the use
of a shared diagnostic notation in tools for and documents about of a shared diagnostic notation in tools for and documents about
CBOR.) CBOR.)
skipping to change at page 59, line 19 skipping to change at page 59, line 24
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].
Lots of highly useful feedback came from members of the IETF CBOR WG, Lots of highly useful feedback came from members of the IETF CBOR WG,
in particular Ari Keraenen, Brian Carpenter, Burt Harris, Jeffrey in particular Ari Keraenen, Brian Carpenter, Burt Harris, Jeffrey
Yasskin, Jim Hague, Jim Schaad, Joe Hildebrand, Max Pritikin, Michael Yasskin, Jim Hague, Jim Schaad, Joe Hildebrand, Max Pritikin, Michael
Richardson, Pete Cordell, Sean Leonard, and Yaron Sheffer. Also, Richardson, Pete Cordell, Sean Leonard, and Yaron Sheffer. Also,
Francesca Palombini and Joe volunteered to chair the WG when it was Francesca Palombini and Joe volunteered to chair the WG when it was
created, providing the framework for generating and processing this created, providing the framework for generating and processing this
feedback; with Barry Leiba having taken over from Joe since. feedback; with Barry Leiba having taken over from Joe since. Chris
Lonvick and Ines Robles provided additional reviews during IESG
processing, and Alexey Melnikov steered the process as the
responsible area director.
The CDDL tool was written by Carsten Bormann, building on previous The CDDL tool reported on in Appendix F was written by Carsten
work by Troy Heninger and Tom Lord. Bormann, building on previous work by Troy Heninger and Tom Lord.
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. 44 change blocks. 
71 lines changed or deleted 106 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/