| RFC 9741 | CDDL: More Control Operators for Text | March 2025 |
| Bormann | Standards Track | [Page] |
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 in both anapplication-specific and a more general way.¶
The present document defines a number of additional generallyapplicable control operators for text conversion (bytes, integers,printf-style formatting, and JSON) and for an operation on text.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc9741.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
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 in both anapplication-specific[RFC9090] and a more general[RFC9165] way.¶
The present document defines a number of additional generallyapplicable control operators. InTable 1, the column marked t is for "target type" (left-hand side), and the column marked c is for "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 |
.base10 | 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 |
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.¶
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 tothe left-hand-side operand and "controller" to the right-hand-side operand."Tool" refers to tools along the lines of that described inAppendix F of [RFC8610].Note also that the data model underlying CDDL provides for textstrings as well as byte strings as two separate types, which are then collectively referred to as "strings".¶
The term "opinionated" is used in this document to explain that the selection of operators included is somewhat frugal, based on opinions about what the preferred (and likely) usage scenarios will be. Specifically, not including a potential choice doesn't by itself intend to express that the choice is unacceptable; it might still be added in a future registration if these opinions evolve.¶
A CDDL model often defines data that are byte strings in essence butneed to be transported in various encoded forms, such as base64 orhex.This section defines a number of control operators to model theseconversions.¶
The control operators generally are of a form that could be used likethis:¶
signature-for-json = text .b64u signaturesignature = bytes .cbor COSE_Sign1¶
The specification of these control operators cannot provide full coverage of the large number of transformations in use; it focuses on[RFC4648] and additionally[RFC9285], as shown inTable 2. For the representations defined in[RFC4648], this specification uses names as inspired by Section8 of RFC 8949[STD94]:¶
| 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 with "Extended 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 notprovide base64url or base32(hex) encoding with padding orbase64 classic without padding. Experience indicates that thesecombinations only ever occur in error, so the usability of CDDL isincreased 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., theyonly match base encodings that conform to the mandates of theirdefining documents.Note that this also means that.b64u and.b64c only match textstrings composed of the set of characters defined for each of them,respectively.(This is perhaps worth pointing out explicitly as it contrastswith the "b64" literal prefix that can be used to notate byte stringsin CDDL source code, which simply accepts characters from either alphabet.This behavior is different from the matching behavior of the fourbase64 control operators defined here.)¶
The additional designation "sloppy" indicates that the text string isnot validated for any additional bits being zero, in variance to whatis specified in the paragraph that follows Table 1 inSection 4 of [RFC4648].Note that the present specification is opinionated again in notspecifying a sloppy variant of base32 or base32hex, as no legacy useof sloppy base32(hex) was known at the time of writing.Base45[RFC9285] is known to be suboptimal for use in environments with limiteddata transparency (such as URLs) but is included because of its closerelationship to QR codes and its wide use in health informatics (notethat base45 is strongly specified not to allow sloppy formsof encoding).¶
| Name | Meaning | Reference |
|---|---|---|
.base10 | Base-ten (decimal) integer | --- |
The control operator.base10 allows the modeling of text stringsthat carry an integer number in decimal form (as a text string withdigits in the usual base-ten positional numeral system), such as in the uint64/int64 formats ofYANG-JSON[RFC7951].¶
yang-json-sid = text .base10 (0..9223372036854775807)¶
Again, the specification is opinionated by only providing for integer numbersrepresented without leading zeros, i.e., the decimal integernumerals match the regularexpression0|-?[1-9][0-9]* (of course, this is further restricted by thecontrol type).SeeSection 2.3 for more flexibility and for other numeric basessuch as octal, hexadecimal,or binary conversions.¶
Note that this control operator governs text representations ofintegers and should not be confused with the control operatorsgoverning text representations of byte strings (such as.b64u).This contrast is somewhat reinforced by spelling out "base" in thename.base10 as opposed to those of the byte string operators.¶
| Name | Meaning | Reference |
|---|---|---|
.printf | Printf-style formatting of data item(s) | --- |
The control operator.printf allows the modeling of text strings that carry various formattedinformation, as long as the format can be represented in printf-styleformatting strings as they are used in the C language (see Section7.23.6.1 of[C]; note that the "C23" standard includes %b and %B for formatting into binary digits).¶
The controller (right-hand side) of the.printf control is an arrayof one printf-style format string and zero or more data items that fitthe individual conversion specifications in the format string. The construct matches a text string representing the textual output of an equivalent C-languageprintf function call that receives as arguments the format string and the data items following it in the array.¶
Out of the functionality described for printf formatting in Section 7.23.6.1 of the C language specification[C], length modifiers (paragraph 7)are not used andMUST NOT be included in the format string.The "s" conversion specifier (paragraph 8) is used tointerpolate a text string in UTF-8 form.The "c" conversion specifier (paragraph 8) represents a single Unicodescalar value as a UTF-8 character.The "p" and "n" conversion specifiers (paragraph 8) are not used andMUST 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 in the following example:¶
any_alg = hexlabel<1..20>hexlabel<K> = text .printf (["0x%04x", K])¶
Here,any_alg matches the text strings"0x0013" or"0x0001" butnot"0x1234".¶
Some applications store complete JSON texts[STD90] into text strings. TheJSON value of these can easily be defined in CDDL by using the defaultJSON-to-CBOR conversion rules provided in Section6.2 of RFC 8949[STD94].This is supported by a control operator similar to.cbor as defined inSection 3.8.4 of [RFC8610].¶
| Name | Meaning | Reference |
|---|---|---|
.json | JSON | [STD90] |
embedded-claims = text .json claimsclaims = {iss: text, exp: text}¶Notes:¶
JSON has known interoperability problems[RFC7493]. WhileSection 4 of [RFC7493] probably is not relevant to this specification,Section 2 of [RFC7493] provides requirements that need to be followed to make use of the generic data model underlying CDDL. Note that the intention ofSection 2.2 of [RFC7493] is directly supported by Section6.2 of RFC 8949[STD94]. The recommendation to use text strings for representing numbers outside JSON's interoperable range is a requirement on the application data model and therefore needs to be reflected on the right-hand side of the.json control operator.¶
This control operator provides no way to constrain the use of blank space or other serialization variants in the JSON representation of the data items; restrictions on the serialization to specific variants (e.g., not providing for the addition of any insignificant blank space and prescribing an order in which map entries are serialized) could be defined in future control operators.¶
A.jsonseq is not provided in this document for JSON text sequences[RFC7464], as no use case for inclusion in CDDL is known at the time of writing; again, future control operators could address this use case.¶
Often, text strings need to be constructed out of parts that can bestbe modeled as an array.¶
| Name | Meaning | Reference |
|---|---|---|
.join | Concatenate elements of an array | --- |
For example, an IPv4 address in dotted-decimal might be modeled as inFigure 1.¶
legacy-ip-address = text .join legacy-ip-address-elementslegacy-ip-address-elements = [bytetext, ".", bytetext, ".", bytetext, ".", bytetext]bytetext = text .base10 bytebyte = 0..255
The elements of the controller array need to be strings (text or bytestrings).The control operator matches a data item if that data item is also astring, built by concatenating the strings in the array.The result of this concatenation is of the same kind of string (textor bytes) as the first element of the array.(If there is no element in the array, the.join construct matcheseither kind of empty string, obviously further constrained by thecontrol operator target.)The concatenation is performed on the sequences of bytes in thestrings.If the result of the concatenation is a text string, the resultingsequence of bytes only matches the target data item if that result isa valid text string (i.e., valid UTF-8). Note that in contrast to thealgorithm used in Section3.2.3 of RFC 8949[STD94], there is no needfor all individual byte sequences going into the concatenation toconstitute valid text strings.¶
Note that this control operator is hard to validate in the mostgeneral case, as this would require full parser functionality.Simple implementation strategies will use array elements with constantvalues as guideposts ("markers", such as the"." inFigure 1)for isolating the variable elements that need further validation atthe CDDL data model level.Therefore, it is recommended to limit the use of.join to simplearrangements where the array elements are laid out explicitly andthere are no adjacent variable elements without intervening constantvalues, and where these constant values do not occur within the textdescribed by the variable elements.If more complex parsing functionality is required, the ABNF controloperators (seeSection 3 of [RFC9165]) may be useful; however, thesecannot reach back into CDDL-specified elements like.join can.¶
Implementation note: A validator implementation can use the markerelements to scan the text and isolate the variable elements.It also can build a parsing regexp from the elements of the controller array, with capturegroups for each element, and validate the captures against theelements of the array. (For more about parsing regexps, seeSection 6 of [RFC9485]; see alsoSection 8 of [RFC9485] for security considerations related toregexps.)In the most general case, these implementation strategies can exhibitfalse negatives, where the implementation cannot find the structurethat would be successfully validated using the controller; it isRECOMMENDED that implementations provide full coverage at least forthe marker-based subset outlined in the previous paragraph.¶
IANA has registered the contents ofTable 7 into the "CDDL Control Operators" registry of[IANA.cddl]:¶
| Name | Reference |
|---|---|
.b64u | RFC 9741 |
.b64u-sloppy | RFC 9741 |
.b64c | RFC 9741 |
.b64c-sloppy | RFC 9741 |
.b45 | RFC 9741 |
.b32 | RFC 9741 |
.h32 | RFC 9741 |
.hex | RFC 9741 |
.hexlc | RFC 9741 |
.hexuc | RFC 9741 |
.base10 | RFC 9741 |
.printf | RFC 9741 |
.json | RFC 9741 |
.join | RFC 9741 |
The security considerations inSection 5 of [RFC8610] apply. In addition, for the control operators defined inSection 2.1, the security considerations inSection 12 of [RFC4648] apply.¶
Table 1:Summary of New Control Operators in This Document¶
Table 2:Control Operators for Text Conversion of Byte Strings¶
Table 3:Control Operator for Text Conversion of Integers¶
Table 4:Control Operator for Printf-Style Formatting of Data Item(s)¶
Table 5:Control Operator for Text Conversion of JSON Values¶
Henk Birkholz suggested the need for many of the control operators defined here. The author would like to thankLaurence Lundblade andJeremy O'Donoghue for sharpening some of the mandates,Mikolai Gütschow for improvements to some examples,A.J. Stein for serving as shepherd for this document and for his shepherd review, the IESG and Directorate reviewers (notablyAri Keränen,Darrel Miller, andÉric Vyncke), andOrie Steele for serving as responsible AD and for providing a detailed AD review.¶