Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures
updated by
- rfc-9682 — Updates to the Concise Data Definition Language (CDDL) Grammar
Extracted elements (29)
CDDL's matching semantics are grounded in Parsing Expression Grammars (PEGs), which use prioritized (ordered) choice to resolve what would be ambiguity in generative grammars. Occurrence indicators are greedy, consuming as much input as possible, which eliminates most ambiguity but requires careful ordering of alternatives.
CDDL uses a single universal composition primitive — the _group_ — instead of separate constructs for vectors, records, tables, and structs. Groups are neutral with respect to whether they will be placed in an array or a map context, which avoids redundancy and provides one conceptual model for all composition styles.
Map matching is non-deterministic in the face of overlapping key types; CDDL does not require tools to detect pathological cases where a general entry precedes a more specific one. Specification writers are urged not to write such non-deterministic maps.
The root of a CDDL specification is simply the first rule in the file; there is no special root keyword. This reflects a top-down decomposition style. Only a type (not a bare group) may be the root.
XSD regular expressions were chosen over PCREs for '.regexp' because XSD has a normative reference usable in IETF documents; PCREs do not. The control operator registry allows a future '.pcre' or other regex flavors to be registered without revising the base specification.
Because the JSON generic data model is a subset of the CBOR generic data model, CDDL can describe JSON data structures as well as CBOR structures. Appendix E defines the mapping conventions; the '.regexp' and '.within' controls are particularly useful when targeting JSON.
CDDL source files use UTF-8 encoding. Processing of CDDL does not involve Unicode normalization. Text strings within CDDL follow the conventions of JSON strings as defined in RFC 8259 Section 7.
Registration policy for CDDL Control Operators is 'Specification Required' (Expert Review) for names without an internal dot, and 'IETF Review' for names that include an internal dot. Experts are instructed to facilitate registrations from other SDOs needing field-specific operators.
A CDDL _group_ is a list of group entries (name/value pairs or nested group expressions). In an array context only the value is represented; the name is annotation only. In a map context the names become map keys. A map matches a group when all group name/value pairs are present in the map and the map has no extra entries.
CDDL maps use curly braces '{}' and arrays use square brackets '[]'. The ':' colon shorthand for member keys (bareword or quoted string followed by colon) implicitly includes cut semantics. The '=>' double arrow is used when the key type is not a single literal value.
CDDL operator precedence from loosest to tightest: rule definition (=, /=, //=); group choice (//); group sequence (,); occurrence indicators (?, *, +, n*m); member key mapping (=>, :); type choice (/); range and control operators (.., ..., .ctrl); unary prefix operators (&, ~).
CDDL predefines primitive type names directly mapped to CBOR major types: bool (MT7/20-21), uint (MT0), nint (MT1), int, float16 (MT7/25), float32 (MT7/26), float64 (MT7/27), float, bstr/bytes (MT2), and tstr/text (MT3). Additional tagged types (tdate, bigint, regexp, etc.) are defined in the standard prelude.
Control operators relate a target type to a controller type via '.ctrl-op' syntax. The 14 operators defined in RFC 8610 are: .size, .bits, .regexp, .cbor, .cborseq, .within, .and, .lt, .le, .gt, .ge, .eq, .ne, and .default. Further operators may be registered per Section 6.1.
Cuts ('^') in map group entries mean that once a member key matches an entry carrying a cut, later entries in the group may no longer match that key — even if the value does not match the cut entry's value type, causing the entire map to fail. The ':' colon shortcut implicitly includes cut semantics.
Generics allow parameterized rules with angle-bracket formal parameters, e.g., 'message<t, v> = {type: t, value: v}'. At the call site actual arguments are substituted within the generic rule's scope as if additional rules of the form 'parameter = argument' were prepended.
Occurrence indicators precede a group entry: '?' (zero or one), '*' (zero or more), '+' (one or more), or 'n*m' (between n and m). Without an indicator the entry occurs exactly once. CDDL does not prescribe whether arrays or maps use CBOR definite-length or indefinite-length encoding.
Range expressions use '..' for bounds inclusive on both sides and '...' to exclude the upper bound (e.g., '0..255' for a byte). Ranges are defined only between two integers or two floating-point values; mixing the two numeric kinds (e.g., '0..10.0') is explicitly not defined.
Representation types use '#N.M' notation referencing CBOR major type N and additional information M. For tagged values (major type 6), '#6.nnn(type)' specifies the tag number and the type of the tagged item. This notation describes a set of values at the data-model level and does not mandate a specific serialization encoding.
The '.bits' control on a byte string or unsigned integer restricts which bit positions may be set. Bit n is set in string str when '(str[n>>3] & (1<<(n&7))) != 0'. For unsigned integer i, all n where '(i & (1<<n)) != 0' must be in the control type.
The '.cbor' control on a byte string asserts that the string carries a single CBOR-encoded data item matching the right-hand-side type. The '.cborseq' variant asserts a CBOR sequence; when treated as an array, it must match the right-hand-side type.
The '.default' control is a variant of '.ne' that identifies a default value: the data item must not equal the default value when transmitted (the default applies when the item is absent). This control is meaningful only in an optional context.
The '.regexp' control requires a target text string to match an XSD regular expression (XML Schema Part 2 Appendix F). XSD regexes are embedded in CDDL text strings, so one level of string escaping precedes XSD escaping rules.
The '.size' control restricts byte or text strings to an exact byte length, or restricts unsigned integers to a maximum byte-width representation (e.g., 'uint .size 3' is equivalent to '0...16777216'). It is not a representation constraint; a smaller encoding is still valid.
The Socket/Plug extension mechanism uses '$name' (type socket) and '$$name' (group socket) as named extension points that begin as empty choices. Plugs added via '/=' or '//=' augment these points; tools must not raise an error if a socket has no plugs.
The unwrap operator '~' strips one type layer from a named map, array, or tag type, exposing the underlying group (for maps/arrays) or inner type (for tags). This allows re-use of named definitions inline without introducing extra nesting, analogous to inheritance.
Type choices use '/' and group choices use '//' (double slash). Additional alternatives can be added to existing rules via '/=' (type) or '//=' (group) without a prior '=' definition. The '//' operator binds more loosely than all other CDDL operators.
IANA created the 'CDDL Control Operators' registry within the 'Concise Data Definition Language (CDDL)' registry group. Each entry has a name (leading dot followed by an identifier) and a documentation reference. Initial entries are the 14 operators defined in RFC 8610.
Extension points in CDDL specifications (sockets, wildcards such as '* tstr => any') require careful security analysis, as extensions may introduce data items outside the original security model. Specification writers are strongly encouraged to keep CDDL as simple as possible and to value clarity over elegance.
Where a CDDL matcher is part of a system's implementation, the security of that system must not depend solely on the correctness of the CDDL specification or CDDL tool; additional independent defenses must be in place. CDDL correctness cannot be assumed as a security property.