1. Introduction
In this document, a notational convention to express Concise Binary Object Representation (CBOR) data structures [RFC7049] is defined.
The main goal for the convention is to provide a unified notation that can be used when defining protocols that use CBOR. We term the convention "Concise Data Definition Language", or CDDL.
The CBOR notational convention has the following goals:
(G1) Provide an unambiguous description of the overall structure of a CBOR data item.
(G2) Be flexible in expressing the multiple ways in which data can be represented in the CBOR data format.
(G3) Be able to express common CBOR datatypes and structures.
(G4) Provide a single format that is both readable and editable for humans and processable by a machine.
(G5) Enable automatic checking of CBOR data items for data format compliance.
(G6) Enable extraction of specific elements from CBOR data for further processing.
Not an original goal per se, but a convenient side effect of the JSON generic data model being a subset of the CBOR generic data model, is the fact that CDDL can also be used for describing JSON data structures (see Appendix E).
This document has the following structure:
The syntax of CDDL is defined in Section 3. Examples of CDDL and a related CBOR data item ("instance"), some of which use the JSON form, are described in Appendix H. Section 4 discusses usage of CDDL. Examples are provided throughout the text to better illustrate concept definitions. A formal definition of CDDL using ABNF grammar [RFC5234] is provided in Appendix B. Finally, a prelude of standard CDDL definitions that is automatically prepended to, and thus available in, every CDDL specification is listed in Appendix D.
1.1. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
1.2. Terminology
New terms are introduced in cursive, which is rendered in plain text as the new term surrounded by underscores. CDDL text in the running text is in "typewriter", which is rendered in plain text as the CDDL text in double quotes (double quotes are also used in the usual English sense; the reader is expected to disambiguate this by context).
In this specification, the term "byte" is used in its now-customary sense as a synonym for "octet".