idnits 2.17.1
draft-bormann-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 June 2020) is 1407 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
== Missing Reference: 'RFCthis' is mentioned on line 350, but not defined
== Outdated reference: A later version (-07) exists of
draft-ietf-cbor-date-tag-01
Summary: 0 errors (**), 0 flaws (~~), 4 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 June 2020
5 Expires: 19 December 2020
7 Additional Control Operators for CDDL
8 draft-bormann-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.
19 Status of This Memo
21 This Internet-Draft is submitted in full conformance with the
22 provisions of BCP 78 and BCP 79.
24 Internet-Drafts are working documents of the Internet Engineering
25 Task Force (IETF). Note that other groups may also distribute
26 working documents as Internet-Drafts. The list of current Internet-
27 Drafts is at https://datatracker.ietf.org/drafts/current/.
29 Internet-Drafts are draft documents valid for a maximum of six months
30 and may be updated, replaced, or obsoleted by other documents at any
31 time. It is inappropriate to use Internet-Drafts as reference
32 material or to cite them other than as "work in progress."
34 This Internet-Draft will expire on 19 December 2020.
36 Copyright Notice
38 Copyright (c) 2020 IETF Trust and the persons identified as the
39 document authors. All rights reserved.
41 This document is subject to BCP 78 and the IETF Trust's Legal
42 Provisions Relating to IETF Documents (https://trustee.ietf.org/
43 license-info) in effect on the date of publication of this document.
44 Please review these documents carefully, as they describe your rights
45 and restrictions with respect to this document. Code Components
46 extracted from this document must include Simplified BSD License text
47 as described in Section 4.e of the Trust Legal Provisions and are
48 provided without warranty as described in the Simplified BSD License.
50 Table of Contents
52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
53 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
54 2. Computed Literals . . . . . . . . . . . . . . . . . . . . . . 3
55 2.1. String Concatenation . . . . . . . . . . . . . . . . . . 3
56 2.2. Numeric Addition . . . . . . . . . . . . . . . . . . . . 4
57 3. Embedded ABNF . . . . . . . . . . . . . . . . . . . . . . . . 4
58 4. Features . . . . . . . . . . . . . . . . . . . . . . . . . . 6
59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
60 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 8
61 7. Security considerations . . . . . . . . . . . . . . . . . . . 8
62 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
63 8.1. Normative References . . . . . . . . . . . . . . . . . . 8
64 8.2. Informative References . . . . . . . . . . . . . . . . . 9
65 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9
66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
68 1. Introduction
70 The Concise Data Definition Language (CDDL), standardized in RFC
71 8610, provides "control operators" as its main language extension
72 point.
74 The present document defines a number of control operators that did
75 not make it into RFC 8610:
77 +----------+-------------------------------------------+
78 | Name | Purpose |
79 +==========+===========================================+
80 | .cat | String Concatenation |
81 +----------+-------------------------------------------+
82 | .plus | Numeric addition |
83 +----------+-------------------------------------------+
84 | .abnf | ABNF in CDDL (text strings) |
85 +----------+-------------------------------------------+
86 | .abnfb | ABNF in CDDL (byte strings) |
87 +----------+-------------------------------------------+
88 | .feature | Detecting feature use in extension points |
89 +----------+-------------------------------------------+
91 Table 1: New control operators in this document
93 1.1. Terminology
95 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
96 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
97 "OPTIONAL" in this document are to be interpreted as described in
98 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
99 capitals, as shown here.
101 This specification uses terminology from [RFC8610]. In particular,
102 with respect to control operators, "target" refers to the left hand
103 side operand, and "controller" to the right hand side operand.
105 2. Computed Literals
107 CDDL as defined in [RFC8610] does not have any mechanisms to compute
108 literals. As an 80 % solution, this specification adds two control
109 operators: ".cat" for string concatenation, and ".plus" for numeric
110 addition.
112 2.1. String Concatenation
114 It is often useful to be able to compose string literals out of
115 component literals defined in different places in the specification.
117 The ".cat" control identifies a string that is built from a
118 concatenation of the target and the controller. As targets and
119 controllers are types, the resulting type is formally the cross-
120 product of the two types, although not all tools may be able to work
121 with non-unique targets or controllers.
123 Target and controller MUST be strings. The result of the operation
124 has the type of the target. The concatenation is performed on the
125 bytes in both strings. If the target is a text string, the result of
126 that concatenation MUST be valid UTF-8.
128 a = "foo" .cat '
129 bar
130 baz
131 '
132 ; is the same string as:
133 b = "foo\n bar\n baz\n"
135 Figure 1: Example: concatenation of text and byte string
137 The example in Figure 1 builds a text string named "a" out of
138 concatenating the target text string ""foo"" and the controller byte
139 string entered in a text form byte string literal. (This particular
140 idiom is useful when the text string contains newlines, which, as
141 shown in the example for "b", may be harder to read when entered in
142 the format that the pure CDDL text string notation inherits from
143 JSON.)
145 2.2. Numeric Addition
147 In many cases in a specification, numbers are needed relative to a
148 base number. The ".plus" control identifies a number that is
149 constructed by adding the numeric values of the target and of the
150 controller.
152 Target and controller MUST be numeric. If the target is a floating
153 point number and the controller an integer number, or vice versa, the
154 sum is converted into the type of the target; converting from a
155 floating point number to an integer selects its floor (the largest
156 integer less than or equal to the floating point number).
158 interval = (
159 BASE => int ; lower bound
160 (BASE .plus 1) => int ; upper bound
161 ? (BASE .plus 2) => int ; tolerance
162 )
164 X = 0
165 Y = 3
166 rect = {
167 interval
168 interval
169 }
171 Figure 2: Example: addition to a base value
173 The example in Figure 2 contains the generic definition of a group
174 "interval" that gives a lower and an upper bound and optionally a
175 tolerance. "rect" combines two of these groups into a map, one group
176 for the X dimension and one for Y dimension.
178 3. Embedded ABNF
180 Many IETF protocols define allowable values for their text strings in
181 ABNF [RFC5234] [RFC7405]. It is often desirable to define a text
182 string type in CDDL by employing existing ABNF embedded into the CDDL
183 specification. Without specific ABNF support in CDDL, that ABNF
184 would usually need to be translated into a regular expression (if
185 that is even possible).
187 ABNF is added to CDDL in the same way that regular expressions were
188 added: by defining a ".abnf" control operator. The target is usually
189 "text" or some restriction on it, the controller is the text of an
190 ABNF specification.
192 There are several small issues, with solutions given here:
194 * ABNF can be used to define byte sequences as well as UTF-8 text
195 strings interpreted as Unicode scalar sequences. This means this
196 specification defines two control operators: ".abnfb" for ABNF
197 denoting byte sequences and ".abnf" for denoting sequences of
198 Unicode scalar values (codepoint) represented as UTF-8 text
199 strings. Both control operators can be applied to targets of
200 either string type; the ABNF is applied to sequence of bytes in
201 the string interpreting that as a sequence of bytes (".abnfb") or
202 as a sequence of code points represented as an UTF-8 text string
203 (".abnf"). The controller string MUST be a text string.
205 * ABNF defines a list of rules, not a single expression (called
206 "elements" in [RFC5234]). This is resolved by requiring the
207 controller string to be one valid "element", followed by zero or
208 more valid "rule" separated from the element by a newline; so the
209 controller string can be built by preceding a piece of valid ABNF
210 by an "element" that selects from that ABNF and a newline.
212 * For the same reason, ABNF requires newlines; specifying newlines
213 in CDDL text strings is tedious (and leads to essentially
214 unreadable ABNF). The workaround employs the ".cat" operator
215 introduced in Section 2.1 and the syntax for text in byte strings.
216 As is customary for ABNF, the syntax of ABNF itself (NOT the
217 syntax expressed in ABNF!) is relaxed to allow a single linefeed
218 as a newline:
220 CRLF = %x0A / %x0D.0A
222 * One set of rules provided in an ABNF specification is often used
223 in multiple positions, in particular staples such as DIGIT and
224 ALPHA. The composition this calls for can also be provided by the
225 ".cat" operator.
227 These points are combined into an example in Figure 3, which uses
228 ABNF from [RFC3339] to specify the CBOR tags defined in
229 [I-D.ietf-cbor-date-tag].
231 ; for draft-ietf-cbor-date-tag
232 Tag1004 = #6.1004(text .abnf full-date)
233 ; for RFC 7049
234 Tag0 = #6.0(text .abnf date-time)
236 full-date = "full-date" .cat rfc3339
237 date-time = "date-time" .cat rfc3339
239 ; Note the trick of idiomatically starting with a newline, separating
240 ; off the element in the .cat from the rule-list
241 rfc3339 = '
242 date-fullyear = 4DIGIT
243 date-month = 2DIGIT ; 01-12
244 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
245 ; month/year
246 time-hour = 2DIGIT ; 00-23
247 time-minute = 2DIGIT ; 00-59
248 time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap sec
249 ; rules
250 time-secfrac = "." 1*DIGIT
251 time-numoffset = ("+" / "-") time-hour ":" time-minute
252 time-offset = "Z" / time-numoffset
254 partial-time = time-hour ":" time-minute ":" time-second
255 [time-secfrac]
256 full-date = date-fullyear "-" date-month "-" date-mday
257 full-time = partial-time time-offset
259 date-time = full-date "T" full-time
260 ' .cat rfc5234-core
262 rfc5234-core = '
263 DIGIT = %x30-39 ; 0-9
264 ; abbreviated here
265 '
267 Figure 3: Example: employing RFC 3339 ABNF for defining CBOR Tags
269 4. Features
271 Traditionally, the kind of validation enabled by languages such as
272 CDDL provided a Boolean result: valid, or invalid.
274 In rapidly evolving environments, this is too simplistic. The data
275 models described by a CDDL specification may continually be enhanced
276 by additional features, and it would be useful even for a
277 specification that does not yet describe a specific future feature to
278 identify the extension point the feature can use, accepting such
279 extensions while marking them as such.
281 The ".feature" control annotates the target as making use of the
282 feature named by the controller. The latter will usually be a
283 string. A tool that validates an instance against that specification
284 may mark the instance as using a feature that is annotated by the
285 specification.
287 Figure 4 shows what could be the definition of a person, with
288 potential extensions beyond "name" and "organization" being marked
289 "further-person-extension". Extensions that are known at the time
290 this definition is written can be collected into "$$person-
291 extensions". However, future extensions would be deemed invalid
292 unless the wildcard at the end of the map is added. These extensions
293 could then be specifically examined by a user or a tool that makes
294 use of the validation result.
296 Leaving out the entire extension point would mean that instances that
297 make use of an extension would be marked as whole-sale invalid,
298 making the entire validation approach much less useful. Leaving the
299 extension point in, but not marking its use as special, would render
300 mistakes such as using the label "organisation" instead of
301 "organization" invisible.
303 person = {
304 ? name: text
305 ? organization: text
306 $$person-extensions
307 * (text .feature "further-person-extension") => any
308 }
310 $$person-extensions //= (? bloodgroup: text)
312 Figure 4: Extensibility with .feature
314 A CDDL tool may simply report the set of features being used; the
315 control then only provides information to the process requesting the
316 validation. One could also imagine a tool that takes arguments
317 allowing the tool to accept certain features and reject others
318 (enable/disable). The latter approach could for instance be used for
319 a JSON/CBOR switch:
321 SenML-Record = {
322 ; ...
323 ? v => number
324 ; ...
325 }
326 v = JC<"v", 2>
327 JC = J .feature "json" / C .feature "cbor"
329 It remains to be seen if the enable/disable approach can lead to new
330 idioms of using CDDL. The language currently has no way to enforce
331 mutually exclusive use of features, as would be needed in this
332 example.
334 5. IANA Considerations
336 This document requests IANA to register the contents of Table 2 into
337 the CDDL Control Operators registry [IANA.cddl]:
339 +----------+-----------+
340 | Name | Reference |
341 +==========+===========+
342 | .cat | [RFCthis] |
343 +----------+-----------+
344 | .plus | [RFCthis] |
345 +----------+-----------+
346 | .abnf | [RFCthis] |
347 +----------+-----------+
348 | .abnfb | [RFCthis] |
349 +----------+-----------+
350 | .feature | [RFCthis] |
351 +----------+-----------+
353 Table 2
355 6. Implementation Status
357 An early implementation of the control operator ".feature" has been
358 available in the CDDL tool since version 0.8.11. The validator warns
359 about each feature being used and provides the set of target values
360 used with the feature.
362 7. Security considerations
364 The security considerations of [RFC8610] apply.
366 8. References
368 8.1. Normative References
370 [IANA.cddl]
371 IANA, "Concise Data Definition Language (CDDL)",
372 .
374 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
375 Requirement Levels", BCP 14, RFC 2119,
376 DOI 10.17487/RFC2119, March 1997,
377 .
379 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
380 Specifications: ABNF", STD 68, RFC 5234,
381 DOI 10.17487/RFC5234, January 2008,
382 .
384 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
385 RFC 7405, DOI 10.17487/RFC7405, December 2014,
386 .
388 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
389 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
390 May 2017, .
392 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
393 Definition Language (CDDL): A Notational Convention to
394 Express Concise Binary Object Representation (CBOR) and
395 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
396 June 2019, .
398 8.2. Informative References
400 [I-D.ietf-cbor-date-tag]
401 Jones, M., Nadalin, A., and J. Richter, "Concise Binary
402 Object Representation (CBOR) Tags for Date", Work in
403 Progress, Internet-Draft, draft-ietf-cbor-date-tag-01, 9
404 June 2020, .
407 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
408 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
409 .
411 Acknowledgements
413 The ".feature" feature was developed out of a discussion with Henk
414 Birkholz. Jim Schaad suggested several improvements.
416 Author's Address
417 Carsten Bormann
418 Universität Bremen TZI
419 Postfach 330440
420 D-28359 Bremen
421 Germany
423 Phone: +49-421-218-63921
424 Email: cabo@tzi.org