More Control Operators for CDDL
Internet-Draft draft-ietf-cbor-cddl-more-control-06
Carsten Bormann
Universität Bremen TZI
Postfach 330440
Bremen
D-28359
Germany
+49-421-218-63921
cabo@tzi.org
21 July 2024
Concise Data Definition Language
Control Operator
The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. RFCs have added to this extension point both in an application-specific and a more general way.
The present document defines a number of additional generally applicable control operators for text conversion (Bytes, Integers, JSON, Printf-style formatting) and for an operation on text.
About This Document
The latest revision of this draft can be found at https://cbor-wg.github.io/cddl-more-control/. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-cbor-cddl-more-control/.
Discussion of this document takes place on the Concise Binary Object Representation (CBOR) Maintenance and Extensions Working Group mailing list (mailto:cbor@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/cbor/. Subscribe at https://www.ietf.org/mailman/listinfo/cbor/.
Source for this draft and an issue tracker can be found at https://github.com/cbor-wg/cddl-more-control.
Introduction
The Concise Data Definition Language (CDDL), standardized in [RFC8610], provides "control operators" as its main language extension point (Section 3.8 of [RFC8610]). RFCs have added to this extension point both in an application-specific [RFC9090] and a more general [RFC9165] way.
The present document defines a number of additional generally applicable control operators:
New control operators in this document, t = target type (left-hand side), c = controller type (right-hand side)
Name | t | c | Purpose
.b64u , .b64c | text | bytes | Base64 representation of byte strings
.b64u-sloppy , .b64c-sloppy | text | bytes | (sloppy-tolerant variants of the above)
.hex , .hexlc , .hexuc | text | bytes | Base16 representation of byte strings
.b32 , .h32 | text | bytes | Base32 representation of byte strings
.b45 | text | bytes | Base45 representation of byte strings
.decimal | text | int | Text representation of integer numbers
.printf | text | array | Printf-formatted text representation of data items
.json | text | any | Text representation of JSON values
.join | text or bytes | array | Build text or byte string from array of components
Terminology
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 [BCP14] ([RFC2119]) ([RFC8174]) when, and only when, they appear in all capitals, as shown here.
Regular expressions mentioned in the text are as defined in [RFC9485].
This specification uses terminology from [RFC8610]. In particular, with respect to control operators, "target" refers to the left-hand side operand, and "controller" to the right-hand side operand. "Tool" refers to tools along the lines of that described in Appendix F of [RFC8610]. Note also that the data model underlying CDDL provides for text strings as well as byte strings as two separate types, which are then collectively referred to as "strings".
Text Conversion
Byte Strings: Base16 (Hex), Base32, Base45, Base64
A CDDL model often defines data that are byte strings in essence but need to be transported in various encoded forms, such as base64 or hex. This section defines a number of control operators to model these conversions.
The control operators generally are of a form that could be used like this:

signature-for-json = text .b64u signature
signature = bytes .cbor COSE_Sign1

The specification of these control operators is complicated by the large number of transformations in use. Inspired by Section 8 of RFC 8949 [STD94], we use representations defined in [RFC4648] with the following names:
Control Operators for Text Conversion of byte strings
name | meaning | reference
.b64u | Base64URL, no padding | Section 5 of [RFC4648]
.b64u-sloppy | Base64URL, no padding, sloppy | Section 5 of [RFC4648]
.b64c | Base64 classic, padding | Section 4 of [RFC4648]
.b64c-sloppy | Base64 classic, padding, sloppy | Section 4 of [RFC4648]
.b32 | Base32, no padding | Section 6 of [RFC4648]
.h32 | Base32/hex alphabet, no padding | Section 7 of [RFC4648]
.hex | Base16 (hex), either case | Section 8 of [RFC4648]
.hexlc | Base16 (hex), lower case | Section 8 of [RFC4648]
.hexuc | Base16 (hex), upper case | Section 8 of [RFC4648]
.b45 | Base45 | [RFC9285]
Note that this specification is somewhat opinionated here: It does not provide base64url, base32 or base32hex encoding with padding, or base64 classic without padding. Experience indicates that these combinations only ever occur in error, so the usability of CDDL is increased by not providing them in the first place. Also, adding "c" makes sure that any decision for classic base64 is actively taken.
These control operators are "strict" in their matching, i.e., they do validate the mandates of their base documents. Note that this also means that .b64u and .b64c only accept the alphabets defined for each of them, respectively; this is maybe worth pointing out here explicitly as CDDL's "b64" literal prefix simply accepts either alphabet and this behavior is different from that of these control operators.
The additional designation "sloppy" indicates that the text string is not validated for any additional bits being zero, in variance to what is specified in the paragraph behind table 1 in Section 4 of [RFC4648]. Note that the present specification is opinionated again in not specifying a sloppy variant of base32 or base32/hex, as no legacy use of sloppy base32(/hex) was known at the time of writing. Base45 is known to be suboptimal for use in environments with limited data transparency (such as URLs), but is included because of its close relationship to QR codes and its wide use in health informatics (note that base45 is strongly specified not to allow sloppy forms of encoding).
Numbers
Control Operator for Text Conversion of Integers
name | meaning | reference
.decimal | Decimal Integer | ---
The control operator .decimal allows the modeling of text strings that carry numeric information in decimal form, such as in the uint64/int64 formats of YANG-JSON [RFC7951].

yang-json-sid = text .decimal (0..9223372036854775807)

Again, the specification is opinionated by only providing integer numbers without leading zeros, i.e., the decimal numbers match the regular expression 0|-?[1-9][0-9]* (of course, further restricted by the control type). See the next section for more flexibility, and for octal, hexadecimal, or binary conversions.
Printf-style Formatting
Control Operator for Printf-formatting of data item(s)
name | meaning | reference
.printf | Printf-formatting of data item(s) | ---
The control operator .printf allows the modeling of text strings that carry various formatted information, as long as the format can be represented in Printf-style formatting strings as they are used in the C language (see Section 7.21.6.1 of [C]).
The controller (right-hand side) of the .printf control is an array of one Printf-style format string and zero or more data items that fit the individual conversion specifications in the format string. The construct matches a text string representing the textual output of an equivalent C-language printf function call that is given the format string and the data items following it in the array.
From the printf specification in the C language, length modifiers (paragraph 7) are not used and MUST NOT be included in the format string. The 's' conversion specifier (paragraph 8) is used to interpolate a text string in UTF-8 form. The 'c' conversion specifier (paragraph 8) represents a single Unicode scalar value as a UTF-8 character. The 'p' and 'n' conversion specifiers (paragraph 8) are not used and MUST NOT be included in the format string.
In the following example, my_alg_19 matches the text string "0x0013":

my_alg_19 = hexlabel<19>
hexlabel<K> = text .printf (["0x%04x", K])

The data items in the controller array do not need to be literals, as for example in:

any_alg = hexlabel<1..20>
hexlabel<K> = text .printf (["0x%04x", K])

Here, any_alg matches the text strings "0x0013" or "0x0001" but not "0x1234".
JSON Values
Some applications store complete JSON texts into text strings, the JSON value for which can easily be defined in CDDL. This is supported by a control operator similar to .cbor in Section 3.8.4 of [RFC8610].
Control Operator for Text Conversion of JSON values
name | meaning | reference
.json | JSON | [STD90]

embedded-claims = text .json claims
claims = {iss: text, exp: text}

Note that a .jsonseq is not provided for [RFC7464], as no use case for inclusion in CDDL is known yet.
There is no way to constrain the use of blank space in data items to be validated; variants (e.g, not providing for any blank space) could be defined.
Text Processing
Join
Often, text strings need to be constructed out of parts that can best be modeled as an array.
Control Operator for Text Generation from Arrays
name | meaning | reference
.join | concatenate elements of an array | ---
For example, an IPv4 address in dotted-decimal might be modeled as in Figure 1.
Using the .join operator to build dotted-decimal IPv4 addresses

legacy-ip-address = text .join legacy-ip-address-elements
legacy-ip-address-elements = [bytetext, ".", bytetext, ".",
                              bytetext, ".", bytetext]
bytetext = text .decimal byte
byte = 0..255

The elements of the controller array need to be strings (text or byte strings). The control operator matches a data item if that data item is also a string, built by concatenating the strings in the array. The result of this concatenation is of the same kind of string (text or bytes) as the first element of the array. (If there is no element in the array, the .join construct matches either kind of empty string, obviously further constrained by the control operator target.) The concatenation is performed on the sequences of bytes in the strings. If the result of the concatenation is a text string, the resulting sequence of bytes MUST be valid UTF-8.
Note that this control operator is hard to validate in the most general case, as this would require full parser functionality. Simple implementation strategies will use array elements with constant values as guideposts ("markers", such as the "." in Figure 1) for isolating the variable elements that need further validation at the CDDL data model level. It is therefore recommended to limit the use of .join to simple arrangements where the array elements are laid out explicitly and there are no adjacent variable elements without intervening constant values, and where these constant values do not occur within the text described by the variable elements.
If more complex parsing functionality is required, the ABNF control operators (see Section 3 of [RFC9165]) may be useful; however, these cannot reach back into CDDL-specified elements like .join can do.
Implementation note: A validator implementation can use the marker elements to scan the text, isolating the variable elements. It also can build a parsing regexp (Section 6 of [RFC9485]) from the elements of the controller array, with capture groups for each element, and validate the captures against the elements of the array. In the most general case, these implementation strategies can exhibit false negatives, where the implementation cannot find the structure that would be successfully validated using the controller; it is RECOMMENDED that implementations provide full coverage at least for the marker-based subset outlined in the previous paragraph.
IANA Considerations
RFC Editor: please replace RFC-XXXX with the RFC number of this RFC and remove this note.
This document requests IANA to register the contents of Table 7 into the registry "CDDL Control Operators" of [IANA.cddl]:
New control operators to be registered
Name | Reference
.b64u | [RFC-XXXX]
.b64u-sloppy | [RFC-XXXX]
.b64c | [RFC-XXXX]
.b64c-sloppy | [RFC-XXXX]
.b45 | [RFC-XXXX]
.b32 | [RFC-XXXX]
.h32 | [RFC-XXXX]
.hex | [RFC-XXXX]
.hexlc | [RFC-XXXX]
.hexuc | [RFC-XXXX]
.decimal | [RFC-XXXX]
.printf | [RFC-XXXX]
.json | [RFC-XXXX]
.join | [RFC-XXXX]
Implementation Status
In the CDDL tool described in Appendix F of [RFC8610], the control operators defined in the present revision of this specification are implemented as of version 0.10.4.
Security considerations
The security considerations of [RFC8610] apply.
References
Normative References
[RFC8259]

The JavaScript Object Notation (JSON) Data Interchange Format
T. Bray, Ed.
December 2017
STD 90
RFC 8259
DOI 10.17487/RFC8259
[RFC8949]

Concise Binary Object Representation (CBOR)
C. Bormann
P. Hoffman
December 2020
STD 94
RFC 8949
DOI 10.17487/RFC8949
[RFC8610]

Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures
H. Birkholz
C. Vigano
C. Bormann
June 2019
RFC 8610
DOI 10.17487/RFC8610
[IANA.cddl]

Concise Data Definition Language (CDDL)
IANA
28 March 2019
[RFC9165]

Additional Control Operators for the Concise Data Definition Language (CDDL)
C. Bormann
December 2021
RFC 9165
DOI 10.17487/RFC9165
[RFC4648]

The Base16, Base32, and Base64 Data Encodings
S. Josefsson
October 2006
RFC 4648
DOI 10.17487/RFC4648
[RFC9285]

The Base45 Data Encoding
P. Fältström
F. Ljunggren
D.W. van Gulik
August 2022
RFC 9285
DOI 10.17487/RFC9285
[RFC9485]

I-Regexp: An Interoperable Regular Expression Format
C. Bormann
T. Bray
October 2023
RFC 9485
DOI 10.17487/RFC9485
[C]

Information technology — Programming languages — C
International Organization for Standardization
June 2018
ISO/IEC 9899:2018
Technically equivalent specification text is available at https://web.archive.org/web/20181230041359if_/http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf
Fourth Edition
[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels
S. Bradner
March 1997
BCP 14
RFC 2119
DOI 10.17487/RFC2119
[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
B. Leiba
May 2017
BCP 14
RFC 8174
DOI 10.17487/RFC8174
Informative References
[RFC7464]

JavaScript Object Notation (JSON) Text Sequences
N. Williams
February 2015
RFC 7464
DOI 10.17487/RFC7464
[RFC9090]

Concise Binary Object Representation (CBOR) Tags for Object Identifiers
C. Bormann
July 2021
RFC 9090
DOI 10.17487/RFC9090
[RFC7951]

JSON Encoding of Data Modeled with YANG
L. Lhotka
August 2016
RFC 7951
DOI 10.17487/RFC7951
Acknowledgements
Henk Birkholz suggested the need for many of the control operators defined here.