draft-ietf-cbor-cddl-07.txt   draft-ietf-cbor-cddl-08.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: August 17, 2019 Universitaet Bremen Expires: September 25, 2019 Universitaet Bremen
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
February 13, 2019 March 24, 2019
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-07 draft-ietf-cbor-cddl-08
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, Concise Binary Object Representation). Its structures (RFC 7049, Concise Binary Object Representation). Its
main goal is to provide an easy and unambiguous way to express main goal is to provide an easy and unambiguous way to express
structures for protocol messages and data formats that use CBOR or structures for protocol messages and data formats that use CBOR or
JSON. JSON.
Status of This Memo Status of This Memo
skipping to change at page 1, line 38 skipping to change at page 1, line 38
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 August 17, 2019. This Internet-Draft will expire on September 25, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 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 19 skipping to change at page 2, line 19
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 . . . . . . . . . . . . . . . . . . . . . . . . 9 2.1.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 9 2.1.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 9
2.2. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.1. Values . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.1. Values . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.2. Choices . . . . . . . . . . . . . . . . . . . . . . . 10 2.2.2. Choices . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.3. Representation Types . . . . . . . . . . . . . . . . 12 2.2.3. Representation Types . . . . . . . . . . . . . . . . 12
2.2.4. Root type . . . . . . . . . . . . . . . . . . . . . . 13 2.2.4. Root type . . . . . . . . . . . . . . . . . . . . . . 13
3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1. General conventions . . . . . . . . . . . . . . . . . . . 13 3.1. General conventions . . . . . . . . . . . . . . . . . . . 13
3.2. Occurrence . . . . . . . . . . . . . . . . . . . . . . . 15 3.2. Occurrence . . . . . . . . . . . . . . . . . . . . . . . 15
3.3. Predefined names for types . . . . . . . . . . . . . . . 16 3.3. Predefined names for types . . . . . . . . . . . . . . . 16
3.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.5. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.5. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.5.1. Structs . . . . . . . . . . . . . . . . . . . . . . . 17 3.5.1. Structs . . . . . . . . . . . . . . . . . . . . . . . 18
3.5.2. Tables . . . . . . . . . . . . . . . . . . . . . . . 20 3.5.2. Tables . . . . . . . . . . . . . . . . . . . . . . . 20
3.5.3. Non-deterministic order . . . . . . . . . . . . . . . 21 3.5.3. Non-deterministic order . . . . . . . . . . . . . . . 21
3.5.4. Cuts in Maps . . . . . . . . . . . . . . . . . . . . 22 3.5.4. Cuts in Maps . . . . . . . . . . . . . . . . . . . . 22
3.6. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.6. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.7. Unwrapping . . . . . . . . . . . . . . . . . . . . . . . 23 3.7. Unwrapping . . . . . . . . . . . . . . . . . . . . . . . 24
3.8. Controls . . . . . . . . . . . . . . . . . . . . . . . . 24 3.8. Controls . . . . . . . . . . . . . . . . . . . . . . . . 25
3.8.1. Control operator .size . . . . . . . . . . . . . . . 25 3.8.1. Control operator .size . . . . . . . . . . . . . . . 25
3.8.2. Control operator .bits . . . . . . . . . . . . . . . 25 3.8.2. Control operator .bits . . . . . . . . . . . . . . . 26
3.8.3. Control operator .regexp . . . . . . . . . . . . . . 26 3.8.3. Control operator .regexp . . . . . . . . . . . . . . 26
3.8.4. Control operators .cbor and .cborseq . . . . . . . . 28 3.8.4. Control operators .cbor and .cborseq . . . . . . . . 28
3.8.5. Control operators .within and .and . . . . . . . . . 28 3.8.5. Control operators .within and .and . . . . . . . . . 28
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 . . . . . . . . . . . . . . . . . . . . . . 29 .default . . . . . . . . . . . . . . . . . . . . . . 29
3.9. Socket/Plug . . . . . . . . . . . . . . . . . . . . . . . 30 3.9. Socket/Plug . . . . . . . . . . . . . . . . . . . . . . . 30
3.10. Generics . . . . . . . . . . . . . . . . . . . . . . . . 31 3.10. Generics . . . . . . . . . . . . . . . . . . . . . . . . 31
3.11. Operator Precedence . . . . . . . . . . . . . . . . . . . 32 3.11. Operator Precedence . . . . . . . . . . . . . . . . . . . 32
4. Making Use of CDDL . . . . . . . . . . . . . . . . . . . . . 33 4. Making Use of CDDL . . . . . . . . . . . . . . . . . . . . . 33
4.1. As a guide to a human user . . . . . . . . . . . . . . . 33 4.1. As a guide to a human user . . . . . . . . . . . . . . . 33
skipping to change at page 3, line 45 skipping to change at page 3, line 45
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 item. a CBOR data item.
(G2) Be flexible in expressing the multiple ways in which data can (G2) Be flexible in expressing the multiple ways in which data can
be represented in the CBOR data format. be represented in the CBOR data format.
(G3) Able to express common CBOR datatypes and structures. (G3) Be able to express common CBOR datatypes and structures.
(G4) Provide a single format that is both readable and editable for (G4) Provide a single format that is both readable and editable for
humans and processable by machine. humans and processable by machine.
(G5) Enable automatic checking of CBOR data items for data format (G5) Enable automatic checking of CBOR data items for data format
compliance. compliance.
(G6) Enable extraction of specific elements from CBOR data for (G6) Enable extraction of specific elements from CBOR data for
further processing. further processing.
skipping to change at page 4, line 35 skipping to change at page 4, line 35
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 "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
1.2. Terminology 1.2. Terminology
New terms are introduced in _cursive_, which is rendered in plain New terms are introduced in _cursive_, which is rendered in plain
text as the new term surrouded by underscores. CDDL text in the text as the new term surrounded by underscores. CDDL text in the
running text is in "typewriter", which is rendered in plain text as running text is in "typewriter", which is rendered in plain text as
the CDDL text in double quotes (double quotes are also used in the the CDDL text in double quotes (double quotes are also used in the
usual English sense; the reader is expected to disambiguate this by usual English sense; the reader is expected to disambiguate this by
context). context).
In this specification, the term "byte" is used in its now customary In this specification, the term "byte" is used in its now customary
sense as a synonym for "octet". sense as a synonym for "octet".
2. The Style of Data Structure Specification 2. The Style of Data Structure Specification
skipping to change at page 8, line 51 skipping to change at page 8, line 51
} }
identity = ( identity = (
age: int, age: int,
name: tstr, name: tstr,
) )
Figure 6: 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,
which can then be included as part of other groups (anonymous as in
the example, or themselves named).
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
respective name (possibly more than once). respective name (possibly more than once).
With this, one is allowed to define all small parts of their data With this, one is allowed to define all small parts of their data
skipping to change at page 14, line 51 skipping to change at page 15, line 7
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 pairs of hex digits (base16, interpreted as a sequence of pairs of hex digits (base16,
Section 8 of [RFC4648]) or a base64(url) string (Sections 4 or 5 Section 8 of [RFC4648]) or a base64(url) string (Sections 4 or 5
of [RFC4648]), respectively (as with the diagnostic notation in of [RFC4648]), respectively (as with the diagnostic notation in
section 6 of [RFC7049]; cf. Appendix G.2); any white space present section 6 of [RFC7049]; cf. Appendix G.2); any white space present
within the string (including comments) is ignored in the prefixed within the string (including comments) is ignored in the prefixed
case. case.
o CDDL uses UTF-8 [RFC3629] for its encoding. o CDDL uses UTF-8 [RFC3629] for its encoding. Processing of CDDL
does not involve Unicode normalization processes.
Example: Example:
; This is a comment ; This is a comment
person = { g } person = { g }
g = ( g = (
"name": tstr, "name": tstr,
age: int, ; "age" is a bareword age: int, ; "age" is a bareword
) )
skipping to change at page 18, line 5 skipping to change at page 18, line 17
The "struct" usage of maps is similar to the way JSON objects are The "struct" usage of maps is similar to the way JSON objects are
used in many JSON applications. used in many JSON applications.
A map is defined in the same way as defining an array (see A map is defined in the same way as defining an array (see
Section 3.4), except for using curly braces "{}" instead of square Section 3.4), except for using curly braces "{}" instead of square
brackets "[]". brackets "[]".
An occurrence indicator as specified in Section 3.2 is permitted for An occurrence indicator as specified in Section 3.2 is permitted for
each group entry. each group entry.
The following is an example of a structure: The following is an example of a record with a structure enbedded:
Geography = [ Geography = [
city : tstr, city : tstr,
gpsCoordinates : GpsCoordinates, gpsCoordinates : GpsCoordinates,
] ]
GpsCoordinates = { GpsCoordinates = {
longitude : uint, ; multiplied by 10^7 longitude : uint, ; degrees, scaled by 10^7
latitude : uint, ; multiplied by 10^7 latitude : uint, ; degreed, scaled by 10^7
} }
When encoding, the Geography structure is encoded using a CBOR array When encoding, the Geography record is encoded using a CBOR array
with two entries (the keys for the group entries are ignored), with two members (the keys for the group entries are ignored),
whereas the GpsCoordinates are encoded as a CBOR map with two key/ whereas the GpsCoordinates structure is encoded as a CBOR map with
value pairs. two key/value pairs.
Types used in a structure can be defined in separate rules or just in Types used in a structure can be defined in separate rules or just in
place (potentially placed inside parentheses, such as for choices). place (potentially placed inside parentheses, such as for choices).
E.g.: E.g.:
located-samples = { located-samples = {
sample-point: int, sample-point: int,
samples: [+ float], samples: [+ float],
} }
skipping to change at page 29, line 42 skipping to change at page 30, line 5
they are both integers or both floating point values. All other they are both integers or both floating point values. All other
cases are not equal (e.g., comparing a text string with a byte cases are not equal (e.g., comparing a text string with a byte
string). 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 make use of the default value.
timer = { timer = {
time: uint, time: uint,
? displayed-step: (number .gt 0) .default 1 ? displayed-step: (number .gt 0) .default 1
} }
3.9. Socket/Plug 3.9. Socket/Plug
Both for type choices and group choices, a mechanism is defined that Both for type choices and group choices, a mechanism is defined that
facilitates starting out with empty choices and assembling them facilitates starting out with empty choices and assembling them
skipping to change at page 35, line 25 skipping to change at page 35, line 25
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.
o Where the CDDL includes extension points, the impact of extensions o Where the CDDL includes extension points, the impact of extensions
on the security of the system needs to be carefully considered. on the security of the system needs to be carefully considered.
Writers of CDDL specifications are strongly encouraged to value Writers of CDDL specifications are strongly encouraged to value
simplicity and transparency of the specification over its elegance. clarity and transparency of the specification over its elegance.
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).
 End of changes. 19 change blocks. 
29 lines changed or deleted 32 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/