draft-ietf-cbor-cddl-01.txt   draft-ietf-cbor-cddl-02.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: July 31, 2018 Universitaet Bremen Expires: August 30, 2018 Universitaet Bremen
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
January 27, 2018 February 26, 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 data structures
draft-ietf-cbor-cddl-01 draft-ietf-cbor-cddl-02
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.
Status of This Memo Status of This Memo
skipping to change at page 1, line 37 skipping to change at page 1, line 37
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 July 31, 2018. This Internet-Draft will expire on August 30, 2018.
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 4, line 16 skipping to change at page 4, line 16
processing. processing.
Not an explicit goal per se, but a convenient side effect of the JSON Not an explicit 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.1).
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 instances are defined in Appendix H. Section 4 related CBOR data items ("instances") are defined in Appendix H.
discusses usage of CDDL. Examples are provided early in the text to Section 4 discusses usage of CDDL. Examples are provided early in
better illustrate concept definitions. A formal definition of CDDL the text to better illustrate concept definitions. A formal
using ABNF grammar is provided in Appendix B. Finally, a prelude of definition of CDDL using ABNF grammar is provided in Appendix B.
standard CDDL definitions available in every CBOR specification is Finally, a prelude of standard CDDL definitions available in every
listed in Appendix E. CBOR specification is listed in Appendix E.
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
skipping to change at page 5, line 42 skipping to change at page 5, line 42
Two important concepts provide the foundation for CDDL: Two important concepts provide the foundation for CDDL:
1. Instead of defining all four types of composition in CDDL 1. Instead of defining all four types of composition in CDDL
separately, or even defining one kind for arrays (vectors and separately, or even defining one kind for arrays (vectors and
records) and one kind for maps (tables and structs), there is records) and one kind for maps (tables and structs), there is
only one kind of composition in CDDL: the _group_ (Section 2.1). only one kind of composition in CDDL: the _group_ (Section 2.1).
2. The other important concept is that of a _type_. The entire CDDL 2. The other important concept is that of a _type_. The entire CDDL
specification defines a type (the one defined by its first specification defines a type (the one defined by its first
_rule_), which formally is the set of CBOR instances that are _rule_), which formally is the set of CBOR data items that are
acceptable for this specification. CDDL predefines a number of acceptable as "instances" for this specification. CDDL
basic types such as "uint" (unsigned integer) or "tstr" (text predefines a number of basic types such as "uint" (unsigned
string), often making use of a simple formal notation for CBOR integer) or "tstr" (text string), often making use of a simple
data items. Each value that can be expressed as a CBOR data item formal notation for CBOR data items. Each value that can be
also is a type in its own right, e.g. "1". A type can be built expressed as a CBOR data item also is a type in its own right,
as a _choice_ of other types, e.g., an "int" is either a "uint" e.g. "1". A type can be built as a _choice_ of other types,
or a "nint" (negative integer). Finally, a type can be built as e.g., an "int" is either a "uint" or a "nint" (negative integer).
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 name/value pairs (group _entries_). CDDL Groups are lists of name/value pairs (group _entries_).
In an array context, only the value of the entry is represented; the In an array context, only the value of the entry is represented; the
skipping to change at page 14, line 43 skipping to change at page 14, line 43
"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).
"int" An unsigned integer or a negative integer. "int" An unsigned integer or a negative integer.
"float16" IEEE 754 half-precision float (major type 7, additional "float16" A number representable as an IEEE 754 half-precision float
information 25). (major type 7, additional information 25).
"float32" IEEE 754 single-precision float (major type 7, additional "float32" A number representable as an IEEE 754 single-precision
information 26). float (major type 7, additional information 26).
"float64" IEEE 754 double-precision float (major type 7, additional "float64" A number representable as an IEEE 754 double-precision
information 27). float (major type 7, additional information 27).
"float" One of float16, float32, or float64. "float" One of float16, float32, or float64.
"bstr" or "bytes" A byte string (major type 2). "bstr" or "bytes" A byte string (major type 2).
"tstr" or "text" Text string (major type 3) "tstr" or "text" Text string (major type 3)
(Note that there are no predefined names for arrays or maps; these (Note that there are no predefined names for arrays or maps; these
are defined with the syntax given below.) are defined with the syntax given below.)
skipping to change at page 19, line 40 skipping to change at page 19, line 40
extensible-map-example = { extensible-map-example = {
? "optional-key" => int, ? "optional-key" => int,
* tstr => any * tstr => any
} }
In this example, there is one optional key "optional-key", which, In this example, there is one optional key "optional-key", which,
when present, maps to an integer. There is also a wild card for any when present, maps to an integer. There is also a wild card for any
future additions. future additions.
Unfortunately, the instance Unfortunately, the data item
{ "optional-key": "nonsense" } { "optional-key": "nonsense" }
does match this specification: While the first entry of the group does match this specification: While the first entry of the group
does not match, the second one (the wildcard) does. This may be very does not match, the second one (the wildcard) does. This may be very
well desirable (e.g., if a future extension is to be allowed to well desirable (e.g., if a future extension is to be allowed to
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:
skipping to change at page 33, line 16 skipping to change at page 33, line 16
Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
Bormann, "Media Types for Sensor Measurement Lists Bormann, "Media Types for Sensor Measurement Lists
(SenML)", draft-ietf-core-senml-12 (work in progress), (SenML)", draft-ietf-core-senml-12 (work in progress),
December 2017. December 2017.
[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.
[RELAXNG] OASIS, "RELAX-NG Compact Syntax", November 2002, [RELAXNG] ISO/IEC, "Information technology -- Document Schema
<http://relaxng.org/compact-20021121.html>. Definition Language (DSDL) -- Part 2: Regular-grammar-
based validation -- RELAX NG", ISO/IEC 19757-2, December
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
Reputation Interchange", RFC 7071, DOI 10.17487/RFC7071, Reputation Interchange", RFC 7071, DOI 10.17487/RFC7071,
November 2013, <https://www.rfc-editor.org/info/rfc7071>. November 2013, <https://www.rfc-editor.org/info/rfc7071>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
skipping to change at page 35, line 18 skipping to change at page 35, line 20
/ "0x" 1*HEXDIG / "0x" 1*HEXDIG
/ "0b" 1*BINDIG / "0b" 1*BINDIG
value = number value = number
/ text / text
/ bytes / bytes
int = ["-"] uint int = ["-"] uint
; This is a float if it has fraction or exponent; int otherwise ; This is a float if it has fraction or exponent; int otherwise
number = int ["." fraction] ["e" exponent ] number = hexfloat / (int ["." fraction] ["e" exponent ])
hexfloat = "0x" 1*HEXDIG ["." 1*HEXDIG] "p" exponent
fraction = 1*DIGIT fraction = 1*DIGIT
exponent = int exponent = ["+"/"-"] 1*DIGIT
text = %x22 *SCHAR %x22 text = %x22 *SCHAR %x22
SCHAR = %x20-21 / %x23-5B / %x5D-10FFFD / SESC SCHAR = %x20-21 / %x23-5B / %x5D-10FFFD / SESC
SESC = "\" %x20-10FFFD SESC = "\" %x20-10FFFD
bytes = [bsqual] %x27 *BCHAR %x27 bytes = [bsqual] %x27 *BCHAR %x27
BCHAR = %x20-26 / %x28-5B / %x5D-10FFFD / SESC / CRLF BCHAR = %x20-26 / %x28-5B / %x5D-10FFFD / SESC / CRLF
bsqual = %x68 ; "h" bsqual = %x68 ; "h"
/ %x62.36.34 ; "b64" / %x62.36.34 ; "b64"
skipping to change at page 37, line 11 skipping to change at page 37, line 11
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 an instance if the instance 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 Parse Expression Grammar
(PEG) semantics: The first choice that matches wins. (As a result, (PEG) semantics: The first choice that matches wins. (As a result,
the order of rules that contribute to a single rule name can very the order of rules that contribute to a single rule name can very
well matter.) 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 an instance with that specific value (no h'0815'), which matches only a data item with that specific value (no
conversions defined), conversions defined),
/ 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
skipping to change at page 37, line 50 skipping to change at page 37, line 50
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
an instance of a major type (given by the DIGIT), optionally a data item of a major type (given by the DIGIT), optionally
constrained to the additional information given by the uint, or constrained to the additional information given by the uint, or
/ "#" ; any / "#" ; any
any data item, or any data item, or
/ "{" S group S "}" / "{" S group S "}"
a map expression, which matches a valid CBOR map the key/value pairs a map expression, which matches a valid CBOR map the key/value pairs
of which can be ordered in such a way that the resulting sequence of which can be ordered in such a way that the resulting sequence
matches the group expression, or matches the group expression, or
skipping to change at page 39, line 9 skipping to change at page 39, line 9
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
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 pard 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] optcom ; 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 ")" optcom
 End of changes. 17 change blocks. 
34 lines changed or deleted 37 lines changed or added

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