More Control Operators for CDDL

1.1. 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 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 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".¶

2.1. 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:¶

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.¶

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 at least strongly specified not to allow sloppy forms of encoding).¶

2.2. Numbers

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.¶

2.3. Printf-style Formatting

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".¶

2.4. 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].¶

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

Note that a .jsonseq is not provided, as no use case 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.¶

3.1. Join

Often, text strings need to be constructed out of parts that can best be modeled as an array.¶

In general, this control operator is hard to validate as it would require full parser functionality. It is therefore recommended to only use it in simple cases, and leave full parsing to ABNF (see Section 3 of [RFC9165]) or similar.¶

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