idnits 2.17.1
draft-ietf-cbor-cddl-control-01.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 (17 November 2020) is 1250 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
== Missing Reference: 'RFCthis' is mentioned on line 380, 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: Informational 17 November 2020
5 Expires: 21 May 2021
7 Additional Control Operators for CDDL
8 draft-ietf-cbor-cddl-control-01
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 did
17 not make it into RFC 8610: ".cat"/".plus" for the construction of
18 constants, ".abnf"/".abnfb" for including ABNF (RFC 5234/RFC 7405) in
19 CDDL specifications, and ".feature" for indicating the use of a non-
20 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 21 May 2021.
39 Copyright Notice
41 Copyright (c) 2020 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. String Concatenation . . . . . . . . . . . . . . . . . . 3
59 2.2. Numeric Addition . . . . . . . . . . . . . . . . . . . . 4
60 3. Embedded ABNF . . . . . . . . . . . . . . . . . . . . . . . . 4
61 4. Features . . . . . . . . . . . . . . . . . . . . . . . . . . 6
62 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
63 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 9
64 7. Security considerations . . . . . . . . . . . . . . . . . . . 9
65 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
66 8.1. Normative References . . . . . . . . . . . . . . . . . . 9
67 8.2. Informative References . . . . . . . . . . . . . . . . . 10
68 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 10
69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10
71 1. Introduction
73 The Concise Data Definition Language (CDDL), standardized in RFC
74 8610, provides "control operators" as its main language extension
75 point.
77 The present document defines a number of control operators that did
78 not make it into RFC 8610:
80 +==========+===========================================+
81 | Name | Purpose |
82 +==========+===========================================+
83 | .cat | String Concatenation |
84 +----------+-------------------------------------------+
85 | .plus | Numeric addition |
86 +----------+-------------------------------------------+
87 | .abnf | ABNF in CDDL (text strings) |
88 +----------+-------------------------------------------+
89 | .abnfb | ABNF in CDDL (byte strings) |
90 +----------+-------------------------------------------+
91 | .feature | Detecting feature use in extension points |
92 +----------+-------------------------------------------+
94 Table 1: New control operators in this document
96 1.1. Terminology
98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
100 "OPTIONAL" in this document are to be interpreted as described in
101 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
102 capitals, as shown here.
104 This specification uses terminology from [RFC8610]. In particular,
105 with respect to control operators, "target" refers to the left hand
106 side operand, and "controller" to the right hand side operand.
108 2. Computed Literals
110 CDDL as defined in [RFC8610] does not have any mechanisms to compute
111 literals. As an 80 % solution, this specification adds two control
112 operators: ".cat" for string concatenation, and ".plus" for numeric
113 addition.
115 2.1. String Concatenation
117 It is often useful to be able to compose string literals out of
118 component literals defined in different places in the specification.
120 The ".cat" control identifies a string that is built from a
121 concatenation of the target and the controller. As targets and
122 controllers are types, the resulting type is formally the cross-
123 product of the two types, although not all tools may be able to work
124 with non-unique targets or controllers.
126 Target and controller MUST be strings. The result of the operation
127 has the type of the target. The concatenation is performed on the
128 bytes in both strings. If the target is a text string, the result of
129 that concatenation MUST be valid UTF-8.
131 a = "foo" .cat '
132 bar
133 baz
134 '
135 ; on a system where the newline is \n, is the same string as:
136 b = "foo\n bar\n baz\n"
138 Figure 1: Example: concatenation of text and byte string
140 The example in Figure 1 builds a text string named "a" out of
141 concatenating the target text string ""foo"" and the controller byte
142 string entered in a text form byte string literal. (This particular
143 idiom is useful when the text string contains newlines, which, as
144 shown in the example for "b", may be harder to read when entered in
145 the format that the pure CDDL text string notation inherits from
146 JSON.)
148 2.2. Numeric Addition
150 In many cases in a specification, numbers are needed relative to a
151 base number. The ".plus" control identifies a number that is
152 constructed by adding the numeric values of the target and of the
153 controller.
155 Target and controller MUST be numeric. If the target is a floating
156 point number and the controller an integer number, or vice versa, the
157 sum is converted into the type of the target; converting from a
158 floating point number to an integer selects its floor (the largest
159 integer less than or equal to the floating point number).
161 interval = (
162 BASE => int ; lower bound
163 (BASE .plus 1) => int ; upper bound
164 ? (BASE .plus 2) => int ; tolerance
165 )
167 X = 0
168 Y = 3
169 rect = {
170 interval
171 interval
172 }
174 Figure 2: Example: addition to a base value
176 The example in Figure 2 contains the generic definition of a group
177 "interval" that gives a lower and an upper bound and optionally a
178 tolerance. "rect" combines two of these groups into a map, one group
179 for the X dimension and one for Y dimension.
181 3. Embedded ABNF
183 Many IETF protocols define allowable values for their text strings in
184 ABNF [RFC5234] [RFC7405]. It is often desirable to define a text
185 string type in CDDL by employing existing ABNF embedded into the CDDL
186 specification. Without specific ABNF support in CDDL, that ABNF
187 would usually need to be translated into a regular expression (if
188 that is even possible).
190 ABNF is added to CDDL in the same way that regular expressions were
191 added: by defining a ".abnf" control operator. The target is usually
192 "text" or some restriction on it, the controller is the text of an
193 ABNF specification.
195 There are several small issues, with solutions given here:
197 * ABNF can be used to define byte sequences as well as UTF-8 text
198 strings interpreted as Unicode scalar sequences. This means this
199 specification defines two control operators: ".abnfb" for ABNF
200 denoting byte sequences and ".abnf" for denoting sequences of
201 Unicode scalar values (codepoint) represented as UTF-8 text
202 strings. Both control operators can be applied to targets of
203 either string type; the ABNF is applied to sequence of bytes in
204 the string interpreting that as a sequence of bytes (".abnfb") or
205 as a sequence of code points represented as an UTF-8 text string
206 (".abnf"). The controller string MUST be a text string.
208 * ABNF defines a list of rules, not a single expression (called
209 "elements" in [RFC5234]). This is resolved by requiring the
210 controller string to be one valid "element", followed by zero or
211 more valid "rule" separated from the element by a newline; so the
212 controller string can be built by preceding a piece of valid ABNF
213 by an "element" that selects from that ABNF and a newline.
215 * For the same reason, ABNF requires newlines; specifying newlines
216 in CDDL text strings is tedious (and leads to essentially
217 unreadable ABNF). The workaround employs the ".cat" operator
218 introduced in Section 2.1 and the syntax for text in byte strings.
219 As is customary for ABNF, the syntax of ABNF itself (NOT the
220 syntax expressed in ABNF!) is relaxed to allow a single linefeed
221 as a newline:
223 CRLF = %x0A / %x0D.0A
225 * One set of rules provided in an ABNF specification is often used
226 in multiple positions, in particular staples such as DIGIT and
227 ALPHA. (Note that all rules referenced need to be defined in each
228 ABNF operator controller string -- there is no implicit import of
229 [RFC5234] Core ABNF or other rules.) The composition this calls
230 for can be provided by the ".cat" operator.
232 These points are combined into an example in Figure 3, which uses
233 ABNF from [RFC3339] to specify the CBOR tags defined in
234 [I-D.ietf-cbor-date-tag].
236 ; for draft-ietf-cbor-date-tag
237 Tag1004 = #6.1004(text .abnf full-date)
238 ; for RFC 7049
239 Tag0 = #6.0(text .abnf date-time)
241 full-date = "full-date" .cat rfc3339
242 date-time = "date-time" .cat rfc3339
244 ; Note the trick of idiomatically starting with a newline, separating
245 ; off the element in the .cat from the rule-list
246 rfc3339 = '
247 date-fullyear = 4DIGIT
248 date-month = 2DIGIT ; 01-12
249 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
250 ; month/year
251 time-hour = 2DIGIT ; 00-23
252 time-minute = 2DIGIT ; 00-59
253 time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap sec
254 ; rules
255 time-secfrac = "." 1*DIGIT
256 time-numoffset = ("+" / "-") time-hour ":" time-minute
257 time-offset = "Z" / time-numoffset
259 partial-time = time-hour ":" time-minute ":" time-second
260 [time-secfrac]
261 full-date = date-fullyear "-" date-month "-" date-mday
262 full-time = partial-time time-offset
264 date-time = full-date "T" full-time
265 ' .cat rfc5234-core
267 rfc5234-core = '
268 DIGIT = %x30-39 ; 0-9
269 ; abbreviated here
270 '
272 Figure 3: Example: employing RFC 3339 ABNF for defining CBOR Tags
274 4. Features
276 Traditionally, the kind of validation enabled by languages such as
277 CDDL provided a Boolean result: valid, or invalid.
279 In rapidly evolving environments, this is too simplistic. The data
280 models described by a CDDL specification may continually be enhanced
281 by additional features, and it would be useful even for a
282 specification that does not yet describe a specific future feature to
283 identify the extension point the feature can use, accepting such
284 extensions while marking them as such.
286 The ".feature" control annotates the target as making use of the
287 feature named by the controller. The latter will usually be a
288 string. A tool that validates an instance against that specification
289 may mark the instance as using a feature that is annotated by the
290 specification.
292 More specifically, the tool's diagnostic output might contain the
293 controller (right hand side) as a feature name, and the target (left
294 hand side) as a feature detail. However, in some cases, the target
295 has too much detail, and the specification might want to hint the
296 tool that more limited detail is appropriate. In this case, the
297 controller should be an array, with the first element being the
298 feature name (that would otherwise be the entire controller), and the
299 second element being the detail (usually another string).
301 foo = {
302 kind: bar / baz .feature (["foo-extensions", "bazify"])
303 }
304 bar = ...
305 baz = ... ; complex stuff that doesn't all need to be in the detail
307 Figure 4 shows what could be the definition of a person, with
308 potential extensions beyond "name" and "organization" being marked
309 "further-person-extension". Extensions that are known at the time
310 this definition is written can be collected into "$$person-
311 extensions". However, future extensions would be deemed invalid
312 unless the wildcard at the end of the map is added. These extensions
313 could then be specifically examined by a user or a tool that makes
314 use of the validation result; the label (map key) actually used makes
315 a fine feature detail for the tool's diagnostic output.
317 Leaving out the entire extension point would mean that instances that
318 make use of an extension would be marked as whole-sale invalid,
319 making the entire validation approach much less useful. Leaving the
320 extension point in, but not marking its use as special, would render
321 mistakes such as using the label "organisation" instead of
322 "organization" invisible.
324 person = {
325 ? name: text
326 ? organization: text
327 $$person-extensions
328 * (text .feature "further-person-extension") => any
329 }
331 $$person-extensions //= (? bloodgroup: text)
333 Figure 4: Map extensibility with .feature
335 Figure 5 shows another example where ".feature" provides for type
336 extensibility.
338 allowed-types = number / text / bool / null
339 / [* number] / [* text] / [* bool]
340 / (any .feature "allowed-type-extension")
342 Figure 5: Type extensibility with .feature
344 A CDDL tool may simply report the set of features being used; the
345 control then only provides information to the process requesting the
346 validation. One could also imagine a tool that takes arguments
347 allowing the tool to accept certain features and reject others
348 (enable/disable). The latter approach could for instance be used for
349 a JSON/CBOR switch:
351 SenML-Record = {
352 ; ...
353 ? v => number
354 ; ...
355 }
356 v = JC<"v", 2>
357 JC = J .feature "json" / C .feature "cbor"
359 It remains to be seen if the enable/disable approach can lead to new
360 idioms of using CDDL. The language currently has no way to enforce
361 mutually exclusive use of features, as would be needed in this
362 example.
364 5. IANA Considerations
366 This document requests IANA to register the contents of Table 2 into
367 the CDDL Control Operators registry [IANA.cddl]:
369 +==========+===========+
370 | Name | Reference |
371 +==========+===========+
372 | .cat | [RFCthis] |
373 +----------+-----------+
374 | .plus | [RFCthis] |
375 +----------+-----------+
376 | .abnf | [RFCthis] |
377 +----------+-----------+
378 | .abnfb | [RFCthis] |
379 +----------+-----------+
380 | .feature | [RFCthis] |
381 +----------+-----------+
383 Table 2
385 6. Implementation Status
387 An early implementation of the control operator ".feature" has been
388 available in the CDDL tool since version 0.8.11. The validator warns
389 about each feature being used and provides the set of target values
390 used with the feature.
392 7. Security considerations
394 The security considerations of [RFC8610] apply.
396 8. References
398 8.1. Normative References
400 [IANA.cddl]
401 IANA, "Concise Data Definition Language (CDDL)",
402 .
404 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
405 Requirement Levels", BCP 14, RFC 2119,
406 DOI 10.17487/RFC2119, March 1997,
407 .
409 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
410 Specifications: ABNF", STD 68, RFC 5234,
411 DOI 10.17487/RFC5234, January 2008,
412 .
414 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
415 RFC 7405, DOI 10.17487/RFC7405, December 2014,
416 .
418 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
419 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
420 May 2017, .
422 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
423 Definition Language (CDDL): A Notational Convention to
424 Express Concise Binary Object Representation (CBOR) and
425 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
426 June 2019, .
428 8.2. Informative References
430 [I-D.ietf-cbor-date-tag]
431 Jones, M., Nadalin, A., and J. Richter, "Concise Binary
432 Object Representation (CBOR) Tags for Date", Work in
433 Progress, Internet-Draft, draft-ietf-cbor-date-tag-07, 10
434 September 2020, .
437 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
438 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
439 .
441 Acknowledgements
443 Jim Schaad suggested several improvements. The ".feature" feature
444 was developed out of a discussion with Henk Birkholz.
446 Author's Address
448 Carsten Bormann
449 Universität Bremen TZI
450 Postfach 330440
451 D-28359 Bremen
452 Germany
454 Phone: +49-421-218-63921
455 Email: cabo@tzi.org