draft-ietf-cbor-cddl-control-06.txt   draft-ietf-cbor-cddl-control-07.txt 
Network Working Group C. Bormann Network Working Group C. Bormann
Internet-Draft Universit├Ąt Bremen TZI Internet-Draft Universit├Ąt Bremen TZI
Intended status: Standards Track 27 September 2021 Intended status: Standards Track 22 October 2021
Expires: 31 March 2022 Expires: 25 April 2022
Additional Control Operators for CDDL Additional Control Operators for CDDL
draft-ietf-cbor-cddl-control-06 draft-ietf-cbor-cddl-control-07
Abstract Abstract
The Concise Data Definition Language (CDDL), standardized in RFC The Concise Data Definition Language (CDDL), standardized in RFC
8610, provides "control operators" as its main language extension 8610, provides "control operators" as its main language extension
point. point.
The present document defines a number of control operators that were The present document defines a number of control operators that were
not yet ready at the time RFC 8610 was completed: .plus, .cat and not yet ready at the time RFC 8610 was completed: .plus, .cat and
.det for the construction of constants, .abnf/.abnfb for including .det for the construction of constants, .abnf/.abnfb for including
skipping to change at page 1, line 38 skipping to change at page 1, line 38
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 31 March 2022. This Internet-Draft will expire on 25 April 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 21 skipping to change at page 2, line 21
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Computed Literals . . . . . . . . . . . . . . . . . . . . . . 3 2. Computed Literals . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Numeric Addition . . . . . . . . . . . . . . . . . . . . 4 2.1. Numeric Addition . . . . . . . . . . . . . . . . . . . . 4
2.2. String Concatenation . . . . . . . . . . . . . . . . . . 4 2.2. String Concatenation . . . . . . . . . . . . . . . . . . 4
2.3. String Concatenation with Dedenting . . . . . . . . . . . 5 2.3. String Concatenation with Dedenting . . . . . . . . . . . 5
3. Embedded ABNF . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Embedded ABNF . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Features . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. Features . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6. Implementation Status . . . . . . . . . . . . . . . . . . . . 11 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 11
7. Security considerations . . . . . . . . . . . . . . . . . . . 11 7. Security considerations . . . . . . . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.1. Normative References . . . . . . . . . . . . . . . . . . 11 8.1. Normative References . . . . . . . . . . . . . . . . . . 12
8.2. Informative References . . . . . . . . . . . . . . . . . 12 8.2. Informative References . . . . . . . . . . . . . . . . . 12
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction 1. Introduction
The Concise Data Definition Language (CDDL), standardized in The Concise Data Definition Language (CDDL), standardized in
[RFC8610], provides "control operators" as its main language [RFC8610], provides "control operators" as its main language
extension point (Section 3.8 of [RFC8610]). extension point (Section 3.8 of [RFC8610]).
The present document defines a number of control operators that were The present document defines a number of control operators that were
not yet ready at the time RFC 8610 was completed: not yet ready at the time RFC 8610 was completed:
skipping to change at page 3, line 32 skipping to change at page 3, line 32
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This specification uses terminology from [RFC8610]. In particular, This specification uses terminology from [RFC8610]. In particular,
with respect to control operators, "target" refers to the left hand with respect to control operators, "target" refers to the left-hand
side operand, and "controller" to the right hand side operand. side operand, and "controller" to the right-hand side operand.
"Tool" refers to tools along the lines of that described in "Tool" refers to tools along the lines of that described in
Appendix F of [RFC8610]. 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".
The term ABNF in this specification stands for the combination of
[RFC5234] and [RFC7405], i.e., the ABNF control operators defined by
this document allow use of the case-sensitive extensions defined in
[RFC7405].
2. Computed Literals 2. Computed Literals
CDDL as defined in [RFC8610] does not have any mechanisms to compute CDDL as defined in [RFC8610] does not have any mechanisms to compute
literals. To cover a large part of the use cases, this specification literals. To cover a large part of the use cases, this specification
adds three control operators: .plus for numeric addition, .cat for adds three control operators: .plus for numeric addition, .cat for
string concatenation, and .det for string concatenation with string concatenation, and .det for string concatenation with
dedenting of both sides (target and controller). dedenting of both sides (target and controller).
For these operators, as with all control operators, targets and For these operators, as with all control operators, targets and
skipping to change at page 4, line 16 skipping to change at page 4, line 21
In many cases in a specification, numbers are needed relative to a In many cases in a specification, numbers are needed relative to a
base number. The .plus control identifies a number that is base number. The .plus control identifies a number that is
constructed by adding the numeric values of the target and of the constructed by adding the numeric values of the target and of the
controller. controller.
Target and controller MUST be numeric. If the target is a floating Target and controller MUST be numeric. If the target is a floating
point number and the controller an integer number, or vice versa, the point number and the controller an integer number, or vice versa, the
sum is converted into the type of the target; converting from a sum is converted into the type of the target; converting from a
floating point number to an integer selects its floor (the largest floating point number to an integer selects its floor (the largest
integer less than or equal to the floating point number). integer less than or equal to the floating point number, i.e.,
rounding towards negative infinity).
interval<BASE> = ( interval<BASE> = (
BASE => int ; lower bound BASE => int ; lower bound
(BASE .plus 1) => int ; upper bound (BASE .plus 1) => int ; upper bound
? (BASE .plus 2) => int ; tolerance ? (BASE .plus 2) => int ; tolerance
) )
X = 0 X = 0
Y = 3 Y = 3
rect = { rect = {
interval<X> interval<X>
interval<Y> interval<Y>
} }
Figure 1: Example: addition to a base value Figure 1: Example: addition to a base value
The example in Figure 1 contains the generic definition of a group The example in Figure 1 contains the generic definition of a CDDL
interval that gives a lower and an upper bound and optionally a group interval that gives a lower and an upper bound and optionally a
tolerance. rect combines two of these groups into a map, one group tolerance. The parameter BASE allows the non-conflicting use of
for the X dimension and one for Y dimension. multiple of these interval groups in one map, by assigning different
labels to the entries of the interval. rect combines two of these
interval groups into a map, one group for the X dimension (using 0,
1, and 2 as labels) and one for Y dimension (using 3, 4, and 5 as
labels).
2.2. String Concatenation 2.2. String Concatenation
It is often useful to be able to compose string literals out of It is often useful to be able to compose string literals out of
component literals defined in different places in the specification. component literals defined in different places in the specification.
The .cat control identifies a string that is built from a The .cat control identifies a string that is built from a
concatenation of the target and the controller. Target and concatenation of the target and the controller. Target and
controller MUST be strings. The result of the operation has the type controller MUST be strings. The result of the operation has the type
of the target. The concatenation is performed on the bytes in both of the target. The concatenation is performed on the bytes in both
skipping to change at page 6, line 4 skipping to change at page 6, line 11
concatenation takes place. concatenation takes place.
For the first rule in Figure 3, the result is equivalent to Figure 4. For the first rule in Figure 3, the result is equivalent to Figure 4.
oid = bytes .abnfb 'oid oid = bytes .abnfb 'oid
oid = 1*arc oid = 1*arc
roid = *arc roid = *arc
arc = [nlsb] %x00-7f arc = [nlsb] %x00-7f
nlsb = %x81-ff *%x80-ff nlsb = %x81-ff *%x80-ff
' '
Figure 4: Dedenting example: result of first .det Figure 4: Dedenting example: result of first .det
For the purposes of this specification, we define dedenting as: For the purposes of this specification, we define dedenting as:
1. determining the smallest amount of left-most blank space (number 1. determining the smallest amount of left-most blank space (number
of leading space characters) in all the non-blank lines, and of leading space characters) present in all the non-blank lines,
and
2. removing exactly that number of leading space characters from 2. removing exactly that number of leading space characters from
each line. For blank (blank space only or empty) lines, there each line. For blank (blank space only or empty) lines, there
may be less (or no) leading space characters than this amount, in may be less (or no) leading space characters than this amount, in
which case all leading space is removed. which case all leading space is removed.
(The name .det is a shortcut for "dedenting cat". The maybe more (The name .det is a shortcut for "dedenting cat". The maybe more
obvious name .dedcat has not been chosen as it is longer and may obvious name .dedcat has not been chosen as it is longer and may
invoke unpleasant images.) invoke unpleasant images.)
skipping to change at page 9, line 19 skipping to change at page 9, line 19
identify the extension point the feature can use, accepting such identify the extension point the feature can use, accepting such
extensions while marking them as such. extensions while marking them as such.
The .feature control annotates the target as making use of the The .feature control annotates the target as making use of the
feature named by the controller. The latter will usually be a feature named by the controller. The latter will usually be a
string. A tool that validates an instance against that specification string. A tool that validates an instance against that specification
may mark the instance as using a feature that is annotated by the may mark the instance as using a feature that is annotated by the
specification. specification.
More specifically, the tool's diagnostic output might contain the More specifically, the tool's diagnostic output might contain the
controller (right hand side) as a feature name, and the target (left controller (right-hand side) as a feature name, and the target (left-
hand side) as a feature detail. However, in some cases, the target hand side) as a feature detail. However, in some cases, the target
has too much detail, and the specification might want to hint the has too much detail, and the specification might want to hint the
tool that more limited detail is appropriate. In this case, the tool that more limited detail is appropriate. In this case, the
controller should be an array, with the first element being the controller should be an array, with the first element being the
feature name (that would otherwise be the entire controller), and the feature name (that would otherwise be the entire controller), and the
second element being the detail (usually another string), as second element being the detail (usually another string), as
illustrated in Figure 6. illustrated in Figure 6.
foo = { foo = {
kind: bar / baz .feature (["foo-extensions", "bazify"]) kind: bar / baz .feature (["foo-extensions", "bazify"])
skipping to change at page 9, line 50 skipping to change at page 9, line 50
However, future extensions would be deemed invalid unless the However, future extensions would be deemed invalid unless the
wildcard at the end of the map is added. These extensions could then wildcard at the end of the map is added. These extensions could then
be specifically examined by a user or a tool that makes use of the be specifically examined by a user or a tool that makes use of the
validation result; the label (map key) actually used makes a fine validation result; the label (map key) actually used makes a fine
feature detail for the tool's diagnostic output. feature detail for the tool's diagnostic output.
Leaving out the entire extension point would mean that instances that Leaving out the entire extension point would mean that instances that
make use of an extension would be marked as whole-sale invalid, make use of an extension would be marked as whole-sale invalid,
making the entire validation approach much less useful. Leaving the making the entire validation approach much less useful. Leaving the
extension point in, but not marking its use as special, would render extension point in, but not marking its use as special, would render
mistakes such as using the label organisation instead of organization mistakes such as using the label "organisation" instead of
invisible. "organization" invisible.
person = { person = {
? name: text ? name: text
? organization: text ? organization: text
$$person-extensions $$person-extensions
* (text .feature "further-person-extension") => any * (text .feature "further-person-extension") => any
} }
$$person-extensions //= (? bloodgroup: text) $$person-extensions //= (? bloodgroup: text)
skipping to change at page 10, line 30 skipping to change at page 10, line 30
/ [* number] / [* text] / [* bool] / [* number] / [* text] / [* bool]
/ (any .feature "allowed-type-extension") / (any .feature "allowed-type-extension")
Figure 8: Type extensibility with .feature Figure 8: Type extensibility with .feature
A CDDL tool may simply report the set of features being used; the A CDDL tool may simply report the set of features being used; the
control then only provides information to the process requesting the control then only provides information to the process requesting the
validation. One could also imagine a tool that takes arguments validation. One could also imagine a tool that takes arguments
allowing the tool to accept certain features and reject others allowing the tool to accept certain features and reject others
(enable/disable). The latter approach could for instance be used for (enable/disable). The latter approach could for instance be used for
a JSON/CBOR switch, as illustrated in Figure 9. a JSON/CBOR switch, as illustrated in Figure 9, using SenML [RFC8428]
as the example data model used with both JSON and CBOR.
SenML-Record = { SenML-Record = {
; ... ; ...
? v => number ? v => number
; ... ; ...
} }
v = JC<"v", 2> v = JC<"v", 2>
JC<J,C> = J .feature "json" / C .feature "cbor" JC<J,C> = J .feature "json" / C .feature "cbor"
Figure 9: Describing variants with .feature Figure 9: Describing variants with .feature
skipping to change at page 11, line 45 skipping to change at page 11, line 45
Andrew Weiss' [CDDL-RS] has an ongoing implementation of this draft Andrew Weiss' [CDDL-RS] has an ongoing implementation of this draft
which is feature-complete except for the ABNF and dedenting support which is feature-complete except for the ABNF and dedenting support
(https://github.com/anweiss/cddl/pull/79 (https://github.com/anweiss/cddl/pull/79
(https://github.com/anweiss/cddl/pull/79)). (https://github.com/anweiss/cddl/pull/79)).
7. Security considerations 7. Security considerations
The security considerations of [RFC8610] apply. The security considerations of [RFC8610] apply.
While both [RFC5234] and [RFC7405] state that security is truly
believed to be irrelevant to the respective document, the use of
formal description techniques cannot only simplify, but sometimes
also complicate a specification. This can lead to security problems
in implementations and in the specification itself. As with CDDL
itself, ABNF should be judiciously applied, and overly complex (or
"cute") constructions should be avoided.
8. References 8. References
8.1. Normative References 8.1. Normative References
[IANA.cddl] [IANA.cddl]
IANA, "Concise Data Definition Language (CDDL)", IANA, "Concise Data Definition Language (CDDL)",
<http://www.iana.org/assignments/cddl>. <https://www.iana.org/assignments/cddl>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
skipping to change at page 12, line 38 skipping to change at page 12, line 46
8.2. Informative References 8.2. Informative References
[CDDL-RS] Weiss, A., "cddl-rs", n.d., [CDDL-RS] Weiss, A., "cddl-rs", n.d.,
<https://github.com/anweiss/cddl>. <https://github.com/anweiss/cddl>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>. <https://www.rfc-editor.org/info/rfc3339>.
[RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
DOI 10.17487/RFC8428, August 2018,
<https://www.rfc-editor.org/info/rfc8428>.
[RFC8943] Jones, M., Nadalin, A., and J. Richter, "Concise Binary [RFC8943] Jones, M., Nadalin, A., and J. Richter, "Concise Binary
Object Representation (CBOR) Tags for Date", RFC 8943, Object Representation (CBOR) Tags for Date", RFC 8943,
DOI 10.17487/RFC8943, November 2020, DOI 10.17487/RFC8943, November 2020,
<https://www.rfc-editor.org/info/rfc8943>. <https://www.rfc-editor.org/info/rfc8943>.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949, Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020, DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/info/rfc8949>. <https://www.rfc-editor.org/info/rfc8949>.
 End of changes. 17 change blocks. 
21 lines changed or deleted 49 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/