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