idnits 2.17.1 draft-bormann-asdf-sdf-mapping-00.txt: -(3): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(5): 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 7 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 37 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (7 November 2021) is 899 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) == Outdated reference: A later version (-18) exists of draft-ietf-asdf-sdf-08 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ASDF C. Bormann, Ed. 3 Internet-Draft Universität Bremen TZI 4 Intended status: Standards Track J. Romann 5 Expires: 11 May 2022 Universität Bremen 6 7 November 2021 8 Semantic Definition Format (SDF): Mapping files 9 draft-bormann-asdf-sdf-mapping-00 11 Abstract 13 The Semantic Definition Format (SDF) is a format for domain experts 14 to use in the creation and maintenance of data and interaction models 15 in the Internet of Things. It was created as a common language for 16 use in the development of the One Data Model liaison organization 17 (OneDM) definitions. Tools convert this format to database formats 18 and other serializations as needed. 20 An SDF specification often needs to be augmented by additional 21 information that is specific to its use in a particular ecosystem or 22 application. SDF mapping files provide a mechanism to represent this 23 augmentation. 25 Discussion Venues 27 This note is to be removed before publishing as an RFC. 29 Discussion of this document takes place on the asdf Working Group 30 mailing list (asdf@ietf.org), which is archived at 31 https://mailarchive.ietf.org/arch/browse/asdf/. 33 Source for this draft and an issue tracker can be found at 34 https://github.com/cabo/sdf-mapping. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on 11 May 2022. 53 Copyright Notice 55 Copyright (c) 2021 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 60 license-info) in effect on the date of publication of this document. 61 Please review these documents carefully, as they describe your rights 62 and restrictions with respect to this document. Code Components 63 extracted from this document must include Simplified BSD License text 64 as described in Section 4.e of the Trust Legal Provisions and are 65 provided without warranty as described in the Simplified BSD License. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 70 1.1. Terminology and Conventions . . . . . . . . . . . . . . . 3 71 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 72 2.1. Example Definition 1 (ecosystem: IPSO/OMA) . . . . . . . 3 73 2.2. Example Definition 2 (ecosystem: W3C WoT) . . . . . . . . 4 74 3. Formal Syntax of SDF mapping files . . . . . . . . . . . . . 6 75 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 76 4.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 7 77 4.2. Registries . . . . . . . . . . . . . . . . . . . . . . . 8 78 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 79 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 80 6.1. Normative References . . . . . . . . . . . . . . . . . . 8 81 6.2. Informative References . . . . . . . . . . . . . . . . . 9 82 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 85 1. Introduction 87 The Semantic Definition Format (SDF) is a format for domain experts 88 to use in the creation and maintenance of data and interaction models 89 in the Internet of Things. It was created as a common language for 90 use in the development of the One Data Model liaison organization 91 (OneDM) definitions. Tools convert this format to database formats 92 and other serializations as needed. 94 An SDF specification often needs to be augmented by additional 95 information that is specific to its use in a particular ecosystem or 96 application. SDF mapping files provide a mechanism to represent this 97 augmentation. 99 1.1. Terminology and Conventions 101 The definitions of [I-D.ietf-asdf-sdf] apply. 103 The term "byte" is used in its now-customary sense as a synonym for 104 "octet". 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 108 "OPTIONAL" in this document are to be interpreted as described in 109 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 110 capitals, as shown here. 112 2. Overview 114 An SDF mapping file provides augmentation information for one or more 115 SDF definitions. Its main contents is a map from SDF name references 116 (Section 4.3 of [I-D.ietf-asdf-sdf]) to a set of qualities. 118 When processing the mapping file together with one or more SDF 119 definitions, these qualities are added to the SDF definition at the 120 referenced name, as in a merge-patch operation [RFC7396]. Note that 121 this is somewhat similar to the way sdfRef (Section 4.4 of 122 [I-D.ietf-asdf-sdf]) works, but in a mapping file the arrows point in 123 the inverse direction (from the augmenter to the augmented). 125 2.1. Example Definition 1 (ecosystem: IPSO/OMA) 127 An example for an SDF mapping file is given in Figure 1. This 128 mapping file is meant to attach to an SDF specification published by 129 OneDM, and to add qualities relevant to the IPSO/OMA ecosystem. 130 // Note that this example uses namespaces to identify elements of 131 // the referenced specification(s), but has un-namespaced quality 132 // names. These two kinds of namespaces are probably unrelated, and 133 // we may need to add quality namespacing to SDF (independent of a 134 // potential feature to add namespace references to definitions that 135 // are not intended to go into the default namespace -- these are SDF 136 // definition namespaces and not quality namespaces, which are one 137 // meta-level higher). 139 * Start of mapping file for certain OneDM playground models: 141 { 142 "info": { 143 "title": "IPSO ID mapping" 144 }, 145 "namespace": { 146 "onedm": "https://onedm.org/models" 147 }, 148 "defaultNamespace": "onedm", 149 "map": { 150 "#/sdfObject/Digital_Input": { 151 "id": 3200 152 }, 153 "#/sdfObject/Digital_Input/sdfProperty/Digital_Input_State": { 154 "id": 5500 155 }, 156 "#/sdfObject/Digital_Input/sdfProperty/Digital_Input_Counter": { 157 "id": 5501 158 } 159 } 160 } 162 Figure 1: A simple example of an SDF mapping file 164 2.2. Example Definition 2 (ecosystem: W3C WoT) 166 This example shows a the translation of a hypothetical W3C WoT Thing 167 Model into an SDF model plus a mapping file to catch Thing Model 168 attributes that don't currently have SDF qualities defined. 169 // The example probably would be more useful with, say, protocol 170 // bindings. This is left for a future version of this example, and/ 171 // or a future specification that specifically addresses how to map 172 // Thing Models into SDF. (There is also the separate requirement to 173 // transform a Thing Description into the kind of information that 174 // can be represented in SDF plus instance information, such as IP 175 // addresses or specific node names.) Finally, namespaces are all 176 // wrong in this example. 178 * The input: WoT Thing Model 179 { 180 "@context": ["http://www.w3.org/ns/td"], 181 "@type" : "tm:ThingModel", 182 "title": "Lamp Thing Model", 183 "titles": { 184 "en": "Lamp Thing Model", 185 "de": "Thing Model für eine Lampe" 186 }, 187 "properties": { 188 "status": { 189 "description": "Current status of the lamp", 190 "descriptions": { 191 "en": "Current status of the lamp", 192 "de": "Aktueller Status der Lampe" 193 }, 194 "type": "string", 195 "readOnly": true 196 } 197 } 198 } 200 Figure 2: Input: WoT Thing Model 202 * The output: SDF model 204 { 205 "info": { 206 "title": "Lamp Thing Model" 207 }, 208 "namespaces": { 209 "wot": "http://www.w3.org/ns/td" 210 }, 211 "defaultNamespace": "wot", 212 "sdfObject": { 213 "LampThingModel": { 214 "label": "Lamp Thing Model", 215 "sdfProperty": { 216 "status": { 217 "description": "Current status of the lamp", 218 "writable": false, 219 "type": "string" 220 } 221 } 222 } 223 } 224 } 226 Figure 3: Output 1: SDF Model 228 * The other output: SDF mapping file 230 { 231 "info": { 232 "title": "Lamp Thing Model: WoT TM mapping" 233 }, 234 "namespace": { 235 "wot": "http://www.w3.org/ns/td" 236 }, 237 "defaultNamespace": "wot", 238 "map": { 239 "#/sdfObject/LampThingModel": { 240 "titles": { 241 "en": "Lamp Thing Model", 242 "de": "Thing Model für eine Lampe" 243 } 244 }, 245 "#/sdfObject/LampThingModel/sdfProperty/status": { 246 "descriptions": { 247 "en": "Current status of the lamp", 248 "de": "Aktueller Status der Lampe" 249 } 250 } 251 } 252 } 254 Figure 4: Output 2: SDF Mapping File 256 3. Formal Syntax of SDF mapping files 258 An SDF mapping file has three optional components that are taken 259 unchanged from SDF: The info block, the namespace declaration, and 260 the default namespace. The mandatory fourth component, the "map", 261 contains the mappings from a SDF name reference (usually a namespace 262 and a JSON pointer) to a nested map providing a set of qualities to 263 be merged in at the site identified in the name reference. 265 Figure 5 describes the syntax of SDF mapping files using CDDL 266 [RFC8610]. 268 start = sdf-mapping 270 sdf-mapping = { 271 ? info: sdfinfo ; This will be required in most process policies, but not a syntax error 272 ? namespace: named 273 ? defaultNamespace: text 274 ? map: { * sdf-pointer => additionalqualities} 275 } 277 ; we can't really be much more specific here: 278 additionalqualities = named 280 ; --------------------------------- import from SDF: 282 sdfinfo = { 283 ? title: text 284 ? version: text 285 ? copyright: text 286 ? license: text 287 EXTENSION-POINT<"info-ext"> 288 } 290 ; Shortcut for a map that gives names to instances of X (has text keys and values of type X) 291 named = { * text => X } 293 EXTENSION-POINT = ( * (text .feature f) => any ) ; only used in framework syntax 295 sdf-pointer = text ; .regexp curie-regexp -- TO DO! 297 Figure 5: CDDL definition of SDF mapping file 299 4. IANA Considerations 301 4.1. Media Type 303 IANA is requested to add the following Media-Type to the "Media 304 Types" registry. 306 +==================+==============================+=============+ 307 | Name | Template | Reference | 308 +==================+==============================+=============+ 309 | sdf-mapping+json | application/sdf-mapping+json | RFC XXXX, | 310 | | | Section 4.1 | 311 +------------------+------------------------------+-------------+ 313 Table 1: A media type for SDF mapping files 315 // RFC Editor: please replace RFC XXXX with this RFC number and 316 // remove this note. 318 Type name: application 319 Subtype name: sdf-mapping+json 320 Required parameters: none 321 Optional parameters: none 322 Encoding considerations: binary (JSON is UTF-8-encoded text) 323 Security considerations: Section 5 of RFC XXXX 324 Interoperability considerations: none 325 Published specification: Section 4.1 of RFC XXXX 326 Applications that use this media type: Tools for data and 327 interaction modeling in the Internet of Things 328 Fragment identifier considerations: A JSON Pointer fragment 329 identifier may be used, as defined in Section 6 of [RFC6901]. 330 Person & email address to contact for further information: ASDF WG 331 mailing list (asdf@ietf.org), or IETF Applications and Real-Time 332 Area (art@ietf.org) 333 Intended usage: COMMON 334 Restrictions on usage: none 335 Author/Change controller: IETF 336 Provisional registration: no 338 4.2. Registries 340 (TBD: After future additions, check if we need any.) 342 5. Security Considerations 344 Some wider issues are discussed in [RFC8576]. 346 (Specifics: TBD.) 348 6. References 350 6.1. Normative References 352 [I-D.ietf-asdf-sdf] 353 Koster, M. and C. Bormann, "Semantic Definition Format 354 (SDF) for Data and Interactions of Things", Work in 355 Progress, Internet-Draft, draft-ietf-asdf-sdf-08, 25 356 October 2021, . 359 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 360 Requirement Levels", BCP 14, RFC 2119, 361 DOI 10.17487/RFC2119, March 1997, 362 . 364 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 365 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 366 DOI 10.17487/RFC6901, April 2013, 367 . 369 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 370 DOI 10.17487/RFC7396, October 2014, 371 . 373 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 374 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 375 May 2017, . 377 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 378 Definition Language (CDDL): A Notational Convention to 379 Express Concise Binary Object Representation (CBOR) and 380 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 381 June 2019, . 383 6.2. Informative References 385 [RFC8576] Garcia-Morchon, O., Kumar, S., and M. Sethi, "Internet of 386 Things (IoT) Security: State of the Art and Challenges", 387 RFC 8576, DOI 10.17487/RFC8576, April 2019, 388 . 390 Acknowledgements 392 This draft is based on discussions in the Thing-to-Thing Research 393 Group (T2TRG) and the SDF working group. Input for Section 2.1 was 394 provided by Ari Keränen. 396 Authors' Addresses 398 Carsten Bormann (editor) 399 Universität Bremen TZI 400 Postfach 330440 401 D-28359 Bremen 402 Germany 404 Phone: +49-421-218-63921 405 Email: cabo@tzi.org 407 Jan Romann 408 Universität Bremen 410 Email: jan.romann@uni-bremen.de