]> Universität Bremen TZI

Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org

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 . Status information for this document may be found at . Discussion of this document takes place on the Concise Binary Object Representation (CBOR) Maintenance and Extensions Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The Concise Data Definition Language (CDDL), standardized in , 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: 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 () () when, and only when, they appear in all capitals, as shown here. Regular expressions mentioned in the text are as defined in . This specification uses terminology from . 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 . 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: The specification of these control operators is complicated by the large number of transformations in use. Inspired by Section of RFC 8949 , we use representations defined in with the following names: Control Operators for Text Conversion of Byte Strings

name	meaning	reference
.b64u	Base64URL, no padding
.b64u-sloppy	Base64URL, no padding, sloppy
.b64c	Base64 classic, padding
.b64c-sloppy	Base64 classic, padding, sloppy
.b32	Base32, no padding
.h32	Base32/hex alphabet, no padding
.hex	Base16 (hex), either case
.hexlc	Base16 (hex), lower case
.hexuc	Base16 (hex), upper case
.b45	Base45

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 only match base encodings that conform to the mandates of their defining documents. Note that this also means that .b64u and .b64c only match text strings composed of the set of characters defined for each of them, respectively. (This is maybe worth pointing out here explicitly as this contrasts with the "b64" literal prefix that can be used to notate byte strings in CDDL source code, which simply accepts characters from either alphabet. This behavior is different from the matching behavior of the four base64 control operators defined here.) 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 . 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 . 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 ). 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": hexlabel = text .printf (["0x%04x", K]) ]]> The data items in the controller array do not need to be literals, as for example in: hexlabel = 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 by using the default JSON-to-CBOR conversion rules provided by Section of RFC 8949 . This is supported by a control operator similar to .cbor as defined in . Control Operator for Text Conversion of JSON Values

name	meaning	reference
.json	JSON

Notes:

• JSON has known interoperability problems . While probably is not relevant to this specification, provides requirements that need to be followed to make use of the generic data model underlying CDDL. Note that the intention of is directly supported by Section of RFC 8949 . 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, 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 , as no use case for inclusion in CDDL is known at the time of writing; again, future control operators could address this use case.

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 .

Using the .join operator to build dotted-decimal IPv4 addresses

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 only matches the target data item if that result is a valid text string (i.e., valid UTF-8; note that in contrast to the algorithm used in Section of RFC 8949 there is no need that all individual byte sequences going into the concatenation constitute valid text strings). 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 ) 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 ) may be useful; however, these cannot reach back into CDDL-specified elements like .join can do.

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 into the registry "" of : 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 , the control operators defined in the present revision of this specification are implemented as of version 0.10.4.

Security considerations The security considerations in apply, as well as those in for the control operators defined in .

References Normative References JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. IANA The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. The present document defines a number of control operators that were not yet ready at the time RFC 8610 was completed:.plus,.cat, and.det for the construction of constants;.abnf/.abnfb for including ABNF (RFC 5234 and RFC 7405) in CDDL specifications; and.feature for indicating the use of a non-basic feature in an instance. This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] This document describes the Base45 encoding scheme, which is built upon the Base64, Base32, and Base16 encoding schemes. This document specifies I-Regexp, a flavor of regular expression that is limited in scope with the goal of interoperation across many different regular expression libraries. International Organization for Standardization 
 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 In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This document describes the JavaScript Object Notation (JSON) text sequence format and associated media type "application/json-seq". A JSON text sequence consists of any number of JSON texts, all encoded in UTF-8, each prefixed by an ASCII Record Separator (0x1E), and each ending with an ASCII Line Feed character (0x0A). I-JSON (short for "Internet JSON") is a restricted profile of JSON designed to maximize interoperability and increase confidence that software can process it successfully with predictable results. The Concise Binary Object Representation (CBOR), defined in RFC 8949, is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. This document defines CBOR tags for object identifiers (OIDs) and is the reference document for the IANA registration of the CBOR tags so defined. This document defines encoding rules for representing configuration data, state data, parameters of Remote Procedure Call (RPC) operations or actions, and notifications defined using YANG as JavaScript Object Notation (JSON) text.

List of Figures

1. Using the .join operator to build dotted-decimal IPv4 addresses

List of Tables

1. New Control Operators in this Document
2. Control Operators for Text Conversion of Byte Strings
3. Control Operator for Text Conversion of Integers
4. Control Operator for Printf-formatting of Data Item(s)
5. Control Operator for Text Conversion of JSON Values
6. Control Operator for Text Generation from Arrays
7. New Control Operators To Be Registered

Acknowledgements suggested the need for many of the control operators defined here. The author would like to thank and for sharpening some of the mandates, for improvements to some examples, for serving as shepherd for this document and for his shepherd review, and for serving as responsible AD and for providing a detailed AD review.