idnits 2.17.1
draft-ietf-cbor-cddl-control-07.txt:
-(3): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
== There are 2 instances of lines with non-ascii characters in the document.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (22 October 2021) is 915 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Missing Reference: 'RFCthis' is mentioned on line 461, but not defined
Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group C. Bormann
3 Internet-Draft Universität Bremen TZI
4 Intended status: Standards Track 22 October 2021
5 Expires: 25 April 2022
7 Additional Control Operators for CDDL
8 draft-ietf-cbor-cddl-control-07
10 Abstract
12 The Concise Data Definition Language (CDDL), standardized in RFC
13 8610, provides "control operators" as its main language extension
14 point.
16 The present document defines a number of control operators that were
17 not yet ready at the time RFC 8610 was completed: .plus, .cat and
18 .det for the construction of constants, .abnf/.abnfb for including
19 ABNF (RFC 5234/RFC 7405) in CDDL specifications, and .feature for
20 indicating the use of a non-basic feature in an instance.
22 Status of This Memo
24 This Internet-Draft is submitted in full conformance with the
25 provisions of BCP 78 and BCP 79.
27 Internet-Drafts are working documents of the Internet Engineering
28 Task Force (IETF). Note that other groups may also distribute
29 working documents as Internet-Drafts. The list of current Internet-
30 Drafts is at https://datatracker.ietf.org/drafts/current/.
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as "work in progress."
37 This Internet-Draft will expire on 25 April 2022.
39 Copyright Notice
41 Copyright (c) 2021 IETF Trust and the persons identified as the
42 document authors. All rights reserved.
44 This document is subject to BCP 78 and the IETF Trust's Legal
45 Provisions Relating to IETF Documents (https://trustee.ietf.org/
46 license-info) in effect on the date of publication of this document.
47 Please review these documents carefully, as they describe your rights
48 and restrictions with respect to this document. Code Components
49 extracted from this document must include Simplified BSD License text
50 as described in Section 4.e of the Trust Legal Provisions and are
51 provided without warranty as described in the Simplified BSD License.
53 Table of Contents
55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
56 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
57 2. Computed Literals . . . . . . . . . . . . . . . . . . . . . . 3
58 2.1. Numeric Addition . . . . . . . . . . . . . . . . . . . . 4
59 2.2. String Concatenation . . . . . . . . . . . . . . . . . . 4
60 2.3. String Concatenation with Dedenting . . . . . . . . . . . 5
61 3. Embedded ABNF . . . . . . . . . . . . . . . . . . . . . . . . 6
62 4. Features . . . . . . . . . . . . . . . . . . . . . . . . . . 8
63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
64 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 11
65 7. Security considerations . . . . . . . . . . . . . . . . . . . 11
66 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
67 8.1. Normative References . . . . . . . . . . . . . . . . . . 12
68 8.2. Informative References . . . . . . . . . . . . . . . . . 12
69 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13
70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
72 1. Introduction
74 The Concise Data Definition Language (CDDL), standardized in
75 [RFC8610], provides "control operators" as its main language
76 extension point (Section 3.8 of [RFC8610]).
78 The present document defines a number of control operators that were
79 not yet ready at the time RFC 8610 was completed:
81 +==========+=================================================+
82 | Name | Purpose |
83 +==========+=================================================+
84 | .plus | Numeric addition |
85 +----------+-------------------------------------------------+
86 | .cat | String Concatenation |
87 +----------+-------------------------------------------------+
88 | .det | String Concatenation, pre-dedenting |
89 +----------+-------------------------------------------------+
90 | .abnf | ABNF in CDDL (text strings) |
91 +----------+-------------------------------------------------+
92 | .abnfb | ABNF in CDDL (byte strings) |
93 +----------+-------------------------------------------------+
94 | .feature | Indicate name of feature used (extension point) |
95 +----------+-------------------------------------------------+
97 Table 1: New control operators in this document
99 1.1. Terminology
101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
103 "OPTIONAL" in this document are to be interpreted as described in
104 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
105 capitals, as shown here.
107 This specification uses terminology from [RFC8610]. In particular,
108 with respect to control operators, "target" refers to the left-hand
109 side operand, and "controller" to the right-hand side operand.
110 "Tool" refers to tools along the lines of that described in
111 Appendix F of [RFC8610]. Note also that the data model underlying
112 CDDL provides for text strings as well as byte strings as two
113 separate types, which are then collectively referred to as "strings".
115 The term ABNF in this specification stands for the combination of
116 [RFC5234] and [RFC7405], i.e., the ABNF control operators defined by
117 this document allow use of the case-sensitive extensions defined in
118 [RFC7405].
120 2. Computed Literals
122 CDDL as defined in [RFC8610] does not have any mechanisms to compute
123 literals. To cover a large part of the use cases, this specification
124 adds three control operators: .plus for numeric addition, .cat for
125 string concatenation, and .det for string concatenation with
126 dedenting of both sides (target and controller).
128 For these operators, as with all control operators, targets and
129 controllers are types. The resulting type is therefore formally a
130 function of the elements of the cross-product of the two types. Not
131 all tools may be able to work with non-unique targets or controllers.
133 2.1. Numeric Addition
135 In many cases in a specification, numbers are needed relative to a
136 base number. The .plus control identifies a number that is
137 constructed by adding the numeric values of the target and of the
138 controller.
140 Target and controller MUST be numeric. If the target is a floating
141 point number and the controller an integer number, or vice versa, the
142 sum is converted into the type of the target; converting from a
143 floating point number to an integer selects its floor (the largest
144 integer less than or equal to the floating point number, i.e.,
145 rounding towards negative infinity).
147 interval = (
148 BASE => int ; lower bound
149 (BASE .plus 1) => int ; upper bound
150 ? (BASE .plus 2) => int ; tolerance
151 )
153 X = 0
154 Y = 3
155 rect = {
156 interval
157 interval
158 }
160 Figure 1: Example: addition to a base value
162 The example in Figure 1 contains the generic definition of a CDDL
163 group interval that gives a lower and an upper bound and optionally a
164 tolerance. The parameter BASE allows the non-conflicting use of
165 multiple of these interval groups in one map, by assigning different
166 labels to the entries of the interval. rect combines two of these
167 interval groups into a map, one group for the X dimension (using 0,
168 1, and 2 as labels) and one for Y dimension (using 3, 4, and 5 as
169 labels).
171 2.2. String Concatenation
173 It is often useful to be able to compose string literals out of
174 component literals defined in different places in the specification.
176 The .cat control identifies a string that is built from a
177 concatenation of the target and the controller. Target and
178 controller MUST be strings. The result of the operation has the type
179 of the target. The concatenation is performed on the bytes in both
180 strings. If the target is a text string, the result of that
181 concatenation MUST be valid UTF-8.
183 a = "foo" .cat '
184 bar
185 baz
186 '
187 ; on a system where the newline is \n, is the same string as:
188 b = "foo\n bar\n baz\n"
190 Figure 2: Example: concatenation of text and byte string
192 The example in Figure 2 builds a text string named a out of
193 concatenating the target text string "foo" and the controller byte
194 string entered in a text form byte string literal. (This particular
195 idiom is useful when the text string contains newlines, which, as
196 shown in the example for b, may be harder to read when entered in the
197 format that the pure CDDL text string notation inherits from JSON.)
199 2.3. String Concatenation with Dedenting
201 Multi-line string literals for various applications, including
202 embedded ABNF (Section 3), need to be set flush left, at least
203 partially. Often, having some indentation in the source code for the
204 literal can promote readability, as in Figure 3.
206 oid = bytes .abnfb ("oid" .det cbor-tags-oid)
207 roid = bytes .abnfb ("roid" .det cbor-tags-oid)
209 cbor-tags-oid = '
210 oid = 1*arc
211 roid = *arc
212 arc = [nlsb] %x00-7f
213 nlsb = %x81-ff *%x80-ff
214 '
216 Figure 3: Example: dedenting concatenation
218 The control operator .det works like .cat, except that both arguments
219 (target and controller) are independently _dedented_ before the
220 concatenation takes place.
222 For the first rule in Figure 3, the result is equivalent to Figure 4.
224 oid = bytes .abnfb 'oid
225 oid = 1*arc
226 roid = *arc
227 arc = [nlsb] %x00-7f
228 nlsb = %x81-ff *%x80-ff
229 '
231 Figure 4: Dedenting example: result of first .det
233 For the purposes of this specification, we define dedenting as:
235 1. determining the smallest amount of left-most blank space (number
236 of leading space characters) present in all the non-blank lines,
237 and
239 2. removing exactly that number of leading space characters from
240 each line. For blank (blank space only or empty) lines, there
241 may be less (or no) leading space characters than this amount, in
242 which case all leading space is removed.
244 (The name .det is a shortcut for "dedenting cat". The maybe more
245 obvious name .dedcat has not been chosen as it is longer and may
246 invoke unpleasant images.)
248 Occasionally, dedenting of only a single item is needed. This can be
249 achieved by using this operator with an empty string, e.g., "" .det
250 rhs or lhs .det "", which can in turn be combined with a .cat: in the
251 construct lhs .cat ("" .det rhs), only rhs is dedented.
253 3. Embedded ABNF
255 Many IETF protocols define allowable values for their text strings in
256 ABNF [RFC5234] [RFC7405]. It is often desirable to define a text
257 string type in CDDL by employing existing ABNF embedded into the CDDL
258 specification. Without specific ABNF support in CDDL, that ABNF
259 would usually need to be translated into a regular expression (if
260 that is even possible).
262 ABNF is added to CDDL in the same way that regular expressions were
263 added: by defining a .abnf control operator. The target is usually
264 text or some restriction on it, the controller is the text of an ABNF
265 specification.
267 There are several small issues, with solutions given here:
269 * ABNF can be used to define byte sequences as well as UTF-8 text
270 strings interpreted as Unicode scalar sequences. This means this
271 specification defines two control operators: .abnfb for ABNF
272 denoting byte sequences and .abnf for denoting sequences of
273 Unicode scalar values (codepoint) represented as UTF-8 text
274 strings. Both control operators can be applied to targets of
275 either string type; the ABNF is applied to sequence of bytes in
276 the string interpreting that as a sequence of bytes (.abnfb) or as
277 a sequence of code points represented as an UTF-8 text string
278 (.abnf). The controller string MUST be a text string.
280 * ABNF defines a list of rules, not a single expression (called
281 "elements" in [RFC5234]). This is resolved by requiring the
282 controller string to be one valid "element", followed by zero or
283 more valid "rule" separated from the element by a newline; so the
284 controller string can be built by preceding a piece of valid ABNF
285 by an "element" that selects from that ABNF and a newline.
287 * For the same reason, ABNF requires newlines; specifying newlines
288 in CDDL text strings is tedious (and leads to essentially
289 unreadable ABNF). The workaround employs the .cat operator
290 introduced in Section 2.2 and the syntax for text in byte strings.
291 As is customary for ABNF, the syntax of ABNF itself (NOT the
292 syntax expressed in ABNF!) is relaxed to allow a single linefeed
293 as a newline:
295 CRLF = %x0A / %x0D.0A
297 * One set of rules provided in an ABNF specification is often used
298 in multiple positions, in particular staples such as DIGIT and
299 ALPHA. (Note that all rules referenced need to be defined in each
300 ABNF operator controller string -- there is no implicit import of
301 [RFC5234] Core ABNF or other rules.) The composition this calls
302 for can be provided by the .cat operator, and/or by .det if there
303 is indentation to be disposed of.
305 These points are combined into an example in Figure 5, which uses
306 ABNF from [RFC3339] to specify one each of the CBOR tags defined in
307 [RFC8943] and [RFC8949].
309 ; for RFC 8943
310 Tag1004 = #6.1004(text .abnf full-date)
311 ; for RFC 8949
312 Tag0 = #6.0(text .abnf date-time)
314 full-date = "full-date" .cat rfc3339
315 date-time = "date-time" .cat rfc3339
317 ; Note the trick of idiomatically starting with a newline, separating
318 ; off the element in the concatenations above from the rule-list
319 rfc3339 = '
320 date-fullyear = 4DIGIT
321 date-month = 2DIGIT ; 01-12
322 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
323 ; month/year
324 time-hour = 2DIGIT ; 00-23
325 time-minute = 2DIGIT ; 00-59
326 time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap sec
327 ; rules
328 time-secfrac = "." 1*DIGIT
329 time-numoffset = ("+" / "-") time-hour ":" time-minute
330 time-offset = "Z" / time-numoffset
332 partial-time = time-hour ":" time-minute ":" time-second
333 [time-secfrac]
334 full-date = date-fullyear "-" date-month "-" date-mday
335 full-time = partial-time time-offset
337 date-time = full-date "T" full-time
338 ' .det rfc5234-core
340 rfc5234-core = '
341 DIGIT = %x30-39 ; 0-9
342 ; abbreviated here
343 '
345 Figure 5: Example: employing RFC 3339 ABNF for defining CBOR Tags
347 4. Features
349 Commonly, the kind of validation enabled by languages such as CDDL
350 provides a Boolean result: valid, or invalid.
352 In rapidly evolving environments, this is too simplistic. The data
353 models described by a CDDL specification may continually be enhanced
354 by additional features, and it would be useful even for a
355 specification that does not yet describe a specific future feature to
356 identify the extension point the feature can use, accepting such
357 extensions while marking them as such.
359 The .feature control annotates the target as making use of the
360 feature named by the controller. The latter will usually be a
361 string. A tool that validates an instance against that specification
362 may mark the instance as using a feature that is annotated by the
363 specification.
365 More specifically, the tool's diagnostic output might contain the
366 controller (right-hand side) as a feature name, and the target (left-
367 hand side) as a feature detail. However, in some cases, the target
368 has too much detail, and the specification might want to hint the
369 tool that more limited detail is appropriate. In this case, the
370 controller should be an array, with the first element being the
371 feature name (that would otherwise be the entire controller), and the
372 second element being the detail (usually another string), as
373 illustrated in Figure 6.
375 foo = {
376 kind: bar / baz .feature (["foo-extensions", "bazify"])
377 }
378 bar = ...
379 baz = ... ; complex stuff that doesn't all need to be in the detail
381 Figure 6: Providing explicit detail with .feature
383 Figure 7 shows what could be the definition of a person, with
384 potential extensions beyond name and organization being marked
385 further-person-extension. Extensions that are known at the time this
386 definition is written can be collected into $$person-extensions.
387 However, future extensions would be deemed invalid unless the
388 wildcard at the end of the map is added. These extensions could then
389 be specifically examined by a user or a tool that makes use of the
390 validation result; the label (map key) actually used makes a fine
391 feature detail for the tool's diagnostic output.
393 Leaving out the entire extension point would mean that instances that
394 make use of an extension would be marked as whole-sale invalid,
395 making the entire validation approach much less useful. Leaving the
396 extension point in, but not marking its use as special, would render
397 mistakes such as using the label "organisation" instead of
398 "organization" invisible.
400 person = {
401 ? name: text
402 ? organization: text
403 $$person-extensions
404 * (text .feature "further-person-extension") => any
405 }
407 $$person-extensions //= (? bloodgroup: text)
409 Figure 7: Map extensibility with .feature
411 Figure 8 shows another example where .feature provides for type
412 extensibility.
414 allowed-types = number / text / bool / null
415 / [* number] / [* text] / [* bool]
416 / (any .feature "allowed-type-extension")
418 Figure 8: Type extensibility with .feature
420 A CDDL tool may simply report the set of features being used; the
421 control then only provides information to the process requesting the
422 validation. One could also imagine a tool that takes arguments
423 allowing the tool to accept certain features and reject others
424 (enable/disable). The latter approach could for instance be used for
425 a JSON/CBOR switch, as illustrated in Figure 9, using SenML [RFC8428]
426 as the example data model used with both JSON and CBOR.
428 SenML-Record = {
429 ; ...
430 ? v => number
431 ; ...
432 }
433 v = JC<"v", 2>
434 JC = J .feature "json" / C .feature "cbor"
436 Figure 9: Describing variants with .feature
438 It remains to be seen if the enable/disable approach can lead to new
439 idioms of using CDDL. The language currently has no way to enforce
440 mutually exclusive use of features, as would be needed in this
441 example.
443 5. IANA Considerations
445 This document requests IANA to register the contents of Table 2 into
446 the registry "CDDL Control Operators" of [IANA.cddl]:
448 +==========+===========+
449 | Name | Reference |
450 +==========+===========+
451 | .plus | [RFCthis] |
452 +----------+-----------+
453 | .cat | [RFCthis] |
454 +----------+-----------+
455 | .det | [RFCthis] |
456 +----------+-----------+
457 | .abnf | [RFCthis] |
458 +----------+-----------+
459 | .abnfb | [RFCthis] |
460 +----------+-----------+
461 | .feature | [RFCthis] |
462 +----------+-----------+
464 Table 2: New control
465 operators to be
466 registered
468 6. Implementation Status
470 This section is to be removed before publishing as an RFC.
472 An early implementation of the control operator .feature has been
473 available in the CDDL tool described in Appendix F of [RFC8610] since
474 version 0.8.11. The validator warns about each feature being used
475 and provides the set of target values used with the feature. The
476 other control operators defined in this specification are also
477 implemented as of version 0.8.21 and 0.8.26 (double-handed .det).
479 Andrew Weiss' [CDDL-RS] has an ongoing implementation of this draft
480 which is feature-complete except for the ABNF and dedenting support
481 (https://github.com/anweiss/cddl/pull/79
482 (https://github.com/anweiss/cddl/pull/79)).
484 7. Security considerations
486 The security considerations of [RFC8610] apply.
488 While both [RFC5234] and [RFC7405] state that security is truly
489 believed to be irrelevant to the respective document, the use of
490 formal description techniques cannot only simplify, but sometimes
491 also complicate a specification. This can lead to security problems
492 in implementations and in the specification itself. As with CDDL
493 itself, ABNF should be judiciously applied, and overly complex (or
494 "cute") constructions should be avoided.
496 8. References
498 8.1. Normative References
500 [IANA.cddl]
501 IANA, "Concise Data Definition Language (CDDL)",
502 .
504 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
505 Requirement Levels", BCP 14, RFC 2119,
506 DOI 10.17487/RFC2119, March 1997,
507 .
509 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
510 Specifications: ABNF", STD 68, RFC 5234,
511 DOI 10.17487/RFC5234, January 2008,
512 .
514 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
515 RFC 7405, DOI 10.17487/RFC7405, December 2014,
516 .
518 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
519 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
520 May 2017, .
522 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
523 Definition Language (CDDL): A Notational Convention to
524 Express Concise Binary Object Representation (CBOR) and
525 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
526 June 2019, .
528 8.2. Informative References
530 [CDDL-RS] Weiss, A., "cddl-rs", n.d.,
531 .
533 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
534 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
535 .
537 [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
538 Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
539 DOI 10.17487/RFC8428, August 2018,
540 .
542 [RFC8943] Jones, M., Nadalin, A., and J. Richter, "Concise Binary
543 Object Representation (CBOR) Tags for Date", RFC 8943,
544 DOI 10.17487/RFC8943, November 2020,
545 .
547 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
548 Representation (CBOR)", STD 94, RFC 8949,
549 DOI 10.17487/RFC8949, December 2020,
550 .
552 Acknowledgements
554 Jim Schaad suggested several improvements. The .feature feature was
555 developed out of a discussion with Henk Birkholz. Paul Kyzivat
556 helped isolate the need for .det.
558 .det is an abbreviation for "dedenting cat", but Det is also the name
559 of a German TV Cartoon character created in the 1960s.
561 Author's Address
563 Carsten Bormann
564 Universität Bremen TZI
565 Postfach 330440
566 D-28359 Bremen
567 Germany
569 Phone: +49-421-218-63921
570 Email: cabo@tzi.org