Internet-Draft CDDL control operators February 2023
Bormann Expires 29 August 2023 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-bormann-cbor-cddl-more-control-00
Published:
Intended Status:
Standards Track
Expires:
Author:
C. Bormann
Universität Bremen TZI

More Control Operators for CDDL

Abstract

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 application control operators for text conversion (Bytes, Integers, JSON) and operations on text.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 29 August 2023.

1. 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:

Table 1: New control operators in this document
Name Purpose
.b64u, .b64c Base64 representation of byte strings
.hex, .hexlc, .hexuc Base16 representation of byte strings
.b32, .h32 Base32 representation of byte strings
.decimal Text representation of integer numbers
.json Text representation of JSON values
.join Building text from array of components

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.

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. Text Conversion

2.1. Byte Strings: Base16 (Hex), Base32, 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 [STD94], we use representations defined in [RFC4648] with the following names:

Table 2: Control Operators for Text Conversion of byte strings
name meaning reference
.b64u Base64URL, no padding Section 5 of [RFC4648]
.b64c Base64 classic, padding 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]

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.

2.2. Numbers

Table 3: Control Operator for Text Conversion of Integers
name meaning reference
.decimal Decimal Integer ---

This allows the modeling of text strings that carry numeric information, 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 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). Future specifications can provide octal, hexadecimal, or binary conversions.

2.3. JSON Values

Some applications store complete JSON texts into text strings, the JSON value for can easily be defined in CDDL. This is supported by a control operator similar to .cbor in Section 3.8.4 of [RFC8610].

Table 4: Control Operator for Text Conversion of JSON values
name meaning reference
.json JSON [STD90]
embedded-claims = text .json claims
claims = {iss: issuer, exp: expiry}

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. Text Processing

3.1. Join

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

Table 5: Control Operator for Text Generation from Arrays
name meaning reference
.join concatenate elements of 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 Section 3 of [RFC9165] or similar.

legacy-ip-address = text .join [digits<1>, ".", digits<2>,
                           ".", digits<3>, ".", digits<4>]
digits<N> = text .decimal byte<n>

3.2. Intersperse

(This section requires some additional design effort before it can be implemented and registered.)

The previous example is somewhat unwieldy as the dots are just syntactic noise.

The .intersperse control is modeled after Haskell's function of the same name [INTERSPERSE]. It takes the elements of an array and intersperses a given additional elements between each to elements of the additional array.

legacy-ip-address = text .join ("." .intersperse digits)
digits = [4*4 digit]
digit = text .decimal (uint .size 1)

.intersperse is actually not limited to text strings; it can be used for any juggling of arrays.

We want to stop here, as there is a danger of generating a functional programming language in an ad-hoc fashion.

4. IANA Considerations

This document requests IANA to register the contents of Table 6 into the registry "CDDL Control Operators" of [IANA.cddl]:

Table 6: New control operators to be registered
Name Reference
.b64u [RFCthis]
.b64c [RFCthis]
.b32 [RFCthis]
.h32 [RFCthis]
.hex [RFCthis]
.hexlc [RFCthis]
.hexuc [RFCthis]
.decimal [RFCthis]
.json [RFCthis]
.join [RFCthis]

5. Implementation Status

This section is to be removed before publishing as an RFC.

In the CDDL tool described in Appendix F of [RFC8610], the control operators defined in this specification are implemented as of version 0.10.2.

6. Security considerations

The security considerations of [RFC8610] apply.

7. References

7.1. Normative References

[IANA.cddl]
IANA, "Concise Data Definition Language (CDDL)", <https://www.iana.org/assignments/cddl>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC4648]
Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, , <https://www.rfc-editor.org/rfc/rfc4648>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8610]
Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, , <https://www.rfc-editor.org/rfc/rfc8610>.
[RFC9165]
Bormann, C., "Additional Control Operators for the Concise Data Definition Language (CDDL)", RFC 9165, DOI 10.17487/RFC9165, , <https://www.rfc-editor.org/rfc/rfc9165>.
[STD90]
Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/rfc/rfc8259>.
[STD94]
Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, , <https://www.rfc-editor.org/rfc/rfc8949>.

7.2. Informative References

[INTERSPERSE]
"intersperse", Haskell Documentation, <https://hoogle.haskell.org/?hoogle=intersperse>.
[RFC7951]
Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, , <https://www.rfc-editor.org/rfc/rfc7951>.
[RFC9090]
Bormann, C., "Concise Binary Object Representation (CBOR) Tags for Object Identifiers", RFC 9090, DOI 10.17487/RFC9090, , <https://www.rfc-editor.org/rfc/rfc9090>.

Acknowledgements

Henk Birkholz suggested the need for many of the control operators defined here.

Author's Address

Carsten Bormann
Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany