idnits 2.17.1 draft-ietf-asdf-sdf-01.txt: -(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 3 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 33 instances of too long lines in the document, the longest one being 97 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 (15 November 2020) is 1251 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-07) exists of draft-ietf-cbor-cddl-control-00 == Outdated reference: A later version (-13) exists of draft-irtf-t2trg-rest-iot-06 Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 T2TRG M. Koster, Ed. 3 Internet-Draft SmartThings 4 Intended status: Informational C. Bormann, Ed. 5 Expires: 19 May 2021 Universität Bremen TZI 6 15 November 2020 8 Semantic Definition Format (SDF) for Data and Interactions of Things 9 draft-ietf-asdf-sdf-01 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 describes definitions of SDF Objects and their 21 associated interactions (Events, Actions, Properties), as well as the 22 Data types for the information exchanged in those interactions. 24 A JSON format representation of SDF 1.0 was defined in the previous 25 (-00) version of this document. SDF 1.1 is expected to be defined in 26 a future version; the present document represents a draft on the way 27 from 1.0 to 1.1. Hence, this is not an implementation draft. 29 Contributing 31 Recent versions of this document are available at its GitHub 32 repository https://github.com/ietf-wg-asdf/SDF (https://github.com/ 33 ietf-wg-asdf/SDF) -- this also provides an issue tracker as well as a 34 way to supply "pull requests". 36 General discussion of this SDF Internet-Draft happens on the mailing 37 list of the IETF ASDF Working Group, asdf@ietf.org (subscribe at 38 https://www.ietf.org/mailman/listinfo/asdf 39 (https://www.ietf.org/mailman/listinfo/asdf)). 41 The IETF Note Well applies (https://www.ietf.org/about/note-well/ 42 (https://www.ietf.org/about/note-well/)). 44 Status of This Memo 46 This Internet-Draft is submitted in full conformance with the 47 provisions of BCP 78 and BCP 79. 49 Internet-Drafts are working documents of the Internet Engineering 50 Task Force (IETF). Note that other groups may also distribute 51 working documents as Internet-Drafts. The list of current Internet- 52 Drafts is at https://datatracker.ietf.org/drafts/current/. 54 Internet-Drafts are draft documents valid for a maximum of six months 55 and may be updated, replaced, or obsoleted by other documents at any 56 time. It is inappropriate to use Internet-Drafts as reference 57 material or to cite them other than as "work in progress." 59 This Internet-Draft will expire on 19 May 2021. 61 Copyright Notice 63 Copyright (c) 2020 IETF Trust and the persons identified as the 64 document authors. All rights reserved. 66 This document is subject to BCP 78 and the IETF Trust's Legal 67 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 68 license-info) in effect on the date of publication of this document. 69 Please review these documents carefully, as they describe your rights 70 and restrictions with respect to this document. Code Components 71 extracted from this document must include Simplified BSD License text 72 as described in Section 4.e of the Trust Legal Provisions and are 73 provided without warranty as described in the Simplified BSD License. 75 Table of Contents 77 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 78 1.1. Terminology and Conventions . . . . . . . . . . . . . . . 3 79 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 80 2.1. Example Definition . . . . . . . . . . . . . . . . . . . 5 81 2.2. Elements of an SDF model . . . . . . . . . . . . . . . . 7 82 2.2.1. sdfObject . . . . . . . . . . . . . . . . . . . . . . 8 83 2.2.2. sdfProperty . . . . . . . . . . . . . . . . . . . . . 8 84 2.2.3. sdfAction . . . . . . . . . . . . . . . . . . . . . . 9 85 2.2.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . 10 86 2.2.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . 10 87 2.2.6. sdfThing . . . . . . . . . . . . . . . . . . . . . . 11 88 2.2.7. sdfProduct . . . . . . . . . . . . . . . . . . . . . 11 89 3. SDF structure . . . . . . . . . . . . . . . . . . . . . . . . 11 90 3.1. Information block . . . . . . . . . . . . . . . . . . . . 11 91 3.2. Namespaces section . . . . . . . . . . . . . . . . . . . 12 92 3.3. Definitions section . . . . . . . . . . . . . . . . . . . 13 93 4. Names and namespaces . . . . . . . . . . . . . . . . . . . . 14 94 4.1. Structure . . . . . . . . . . . . . . . . . . . . . . . . 14 95 4.2. Contributing global names . . . . . . . . . . . . . . . . 15 96 4.3. Referencing global names . . . . . . . . . . . . . . . . 15 97 4.4. sdfRef . . . . . . . . . . . . . . . . . . . . . . . . . 16 98 4.5. sdfRequired . . . . . . . . . . . . . . . . . . . . . . . 17 99 4.5.1. Optionality using the keyword "sdfRequired" . . . . . 17 100 4.6. Common Qualities . . . . . . . . . . . . . . . . . . . . 18 101 4.7. Data Qualities . . . . . . . . . . . . . . . . . . . . . 19 102 5. Keywords for definition groups . . . . . . . . . . . . . . . 23 103 5.1. sdfObject . . . . . . . . . . . . . . . . . . . . . . . . 23 104 5.2. sdfProperty . . . . . . . . . . . . . . . . . . . . . . . 23 105 5.3. sdfAction . . . . . . . . . . . . . . . . . . . . . . . . 24 106 5.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . . . 24 107 5.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . . . 25 108 6. High Level Composition . . . . . . . . . . . . . . . . . . . 25 109 6.1. Paths in the model namespaces . . . . . . . . . . . . . . 26 110 6.2. Modular Composition . . . . . . . . . . . . . . . . . . . 26 111 6.2.1. Use of the "sdfRef" keyword to re-use a definition . 26 112 6.3. sdfThing . . . . . . . . . . . . . . . . . . . . . . . . 27 113 6.4. sdfProduct . . . . . . . . . . . . . . . . . . . . . . . 28 114 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 115 7.1. Normative References . . . . . . . . . . . . . . . . . . 28 116 7.2. Informative References . . . . . . . . . . . . . . . . . 29 117 Appendix A. Formal Syntax of SDF . . . . . . . . . . . . . . . . 30 118 Appendix B. json-schema.org Rendition of SDF Syntax . . . . . . 33 119 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 34 120 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 34 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 123 1. Introduction 125 The Semantic Definition Format (SDF) is a format for domain experts 126 to use in the creation and maintenance of data and interaction models 127 in the Internet of Things. It was created as a common language for 128 use in the development of the One Data Model liaison organization 129 (OneDM) definitions. Tools convert this format to database formats 130 and other serializations as needed. 132 An SDF specification describes definitions of SDF Objects and their 133 associated interactions (Events, Actions, Properties), as well as the 134 Data types for the information exchanged in those interactions. 136 A JSON format representation of SDF 1.0 was defined in the previous 137 (-00) version of this document. SDF 1.1 is expected to be defined in 138 a future version; the present document represents a draft on the way 139 from 1.0 to 1.1. Hence, this is not an implementation draft. 141 1.1. Terminology and Conventions 143 Thing: A physical device that is also made available in the Internet 144 of Things. The term is used here for Things that are notable for 145 their interaction with the physical world beyond interaction with 146 humans; a temperature sensor or a light might be a Thing, but a 147 router that employs both temperature sensors and indicator lights 148 might exhibit less Thingness, as the effects of its functioning 149 are mostly on the digital side. 151 Affordance: An element of an interface offered for interaction, 152 defining its possible uses or making clear how it can or should be 153 used. The term is used here for the digital interfaces of a Thing 154 only; it might also have physical affordances such as buttons, 155 dials, and displays. 157 Quality: A metadata item in a definition or declaration which says 158 something about that definition or declaration. A quality is 159 represented in SDF as an entry in a JSON map (object) that serves 160 as a definition or declaration. 162 Entry: A key-value pair in a map. (In JSON maps, sometimes also 163 called "member".) 165 Block: One or more entries in a JSON map that is part of an SDF 166 specification; these entries together serve a specific function. 168 Group: An entry in the main SDF map and in certain nested 169 definitions that has a Class Name Keyword as its key and a map of 170 definition entries (Definition Group) as a value. 172 Class Name Keyword: One of sdfThing, sdfProduct, sdfObject, 173 sdfProperty, sdfAction, sdfEvent, or sdfData; the Classes for 174 these type keywords are capitalized and prefixed with "sdf". 176 Class: Abstract term for the information that is contained in groups 177 identified by a Class Name Keyword. 179 Property: An affordance that can potentially be used to read, write, 180 and/or observe state on an Object. (Note that Entries are often 181 called properties in other environments; in this document, the 182 term Property is specifically reserved for affordances, even if 183 the map key "properties" might be imported from a data definition 184 language with the other semantics.) 186 Action: An affordance that can potentially be used to perform a 187 named operation on an Object. 189 Event: An affordance that can potentially be used to obtain 190 information about what happened to an Object. 192 Object: A grouping of Property, Action, and Event definitions; the 193 main "atom" of reusable semantics for model construction. (Note 194 that JSON maps are often called JSON objects due to JSON's 195 JavaScript heritage; in this document, the term Object is 196 specifically reserved for the above grouping, even if the type 197 name "object" might be imported from a data definition language 198 with the other semantics.) 200 Element: A part or an aspect of something abstract; used here in its 201 usual English definition. (Occasionally, also used specifically 202 for the elements of JSON arrays.) 204 Definition: An entry in a Definition Group; the entry creates a new 205 semantic term for use in SDF models and associates it with a set 206 of qualities. 208 Declaration: A reference to and a use of a definition within an 209 enclosing definition, intended to create component instances 210 within that enclosing definition. Every declaration can also be 211 used as a definition for reference in a different place. 213 Protocol Binding: A companion document to an SDF specification that 214 defines how to map the abstract concepts in the specification into 215 the protocols in use in a specific ecosystem. Might supply URL 216 components, numeric IDs, and similar details. 218 Conventions: 220 * The singular form is chosen as the preferred one for the keywords 221 defined here. 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 225 "OPTIONAL" in this document are to be interpreted as described in 226 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 227 capitals, as shown here. 229 2. Overview 231 2.1. Example Definition 233 We start with an example for the SDF definition of a simple Object 234 called "Switch" (Figure 1). 236 { 237 "info": { 238 "title": "Example file for OneDM Semantic Definition Format", 239 "version": "2019-04-24", 240 "copyright": "Copyright 2019 Example Corp. All rights reserved.", 241 "license": "https://example.com/license" 242 }, 243 "namespace": { 244 "cap": "https://example.com/capability/cap" 245 }, 246 "defaultNamespace": "cap", 247 "sdfObject": { 248 "Switch": { 249 "sdfProperty": { 250 "value": { 251 "description": "The state of the switch; false for off and true for on." 252 "type": "boolean" 253 } 254 }, 255 "sdfAction": { 256 "on": { 257 "description": "Turn the switch on; equivalent to setting value to true." 258 }, 259 "off": { 260 "description": "Turn the switch off; equivalent to setting value to false." 261 }, 262 "toggle": { 263 "description": "Toggle the switch; equivalent to setting value to its complement." 264 } 265 } 266 } 267 } 268 } 270 Figure 1: A simple example of an SDF definition file 272 This is a model of a switch. The state "value" declared in the 273 "sdfProperty" group, represented by a Boolean, will be true for "on" 274 and will be false for "off". The actions "on" or "off" declared in 275 the "sdfAction" group are redundant with setting the "value" and are 276 in the example to illustrate that there are often different ways of 277 achieving the same effect. The action "toggle" will invert the value 278 of the sdfProperty value, so that 2-way switches can be created; 279 having such action will avoid the need for first retrieving the 280 current value and then applying/setting the inverted value. 282 The "sdfObject" group lists the affordances of instances of this 283 object. The "sdfProperty" group lists the property affordances 284 described by the model; these represent various perspectives on the 285 state of the object. Properties can have additional qualities to 286 describe the state more precisely. Properties can be annotated to be 287 read, write or read/write; how this is actually done by the 288 underlying transfer protocols is not described in the SDF model but 289 left to companion protocol bindings. Properties are often used with 290 RESTful paradigms [I-D.irtf-t2trg-rest-iot], describing state. The 291 "sdfAction" group is the mechanism to describe other interactions in 292 terms of their names, input, and output data (no data are used in the 293 example), as in a POST method in REST or in a remote procedure call. 294 The example "toggle" is an Action that changes the state based on the 295 current state of the Property named "value". (The third type of 296 affordance is Events, which are not described in this example.) 298 2.2. Elements of an SDF model 300 The SDF language uses seven predefined Class Name Keywords for 301 modeling connected Things, six of which are illustrated in Figure 2 302 (the seventh class "sdfProduct" is exactly like "sdfThing"). 304 ,--------. 305 |sdfThing| 306 |--------| 307 |--------| 308 `--------' 309 | 310 | 311 ,---------. 312 |sdfObject| 313 |---------| 314 |---------| 315 `---------' 316 | 317 ,-----------. ,---------. ,--------. 318 |sdfProperty| |sdfAction| |sdfEvent| 319 |-----------| |---------| |--------| 320 |-----------| |---------| |--------| 321 `-----------' `---------' `--------' 323 ,-------. 324 |sdfData| 325 |-------| 326 |-------| 327 `-------' 329 Figure 2: Main classes used in SDF models 331 The seven main Class Name Keywords are discussed below. 333 2.2.1. sdfObject 335 Objects, the items listed in an "sdfObject" group, are the main 336 "atom" of reusable semantics for model construction. It aligns in 337 scope with common definition items from many IoT modeling systems, 338 for example ZigBee Clusters [ZCL], OMA SpecWorks LwM2M Objects [OMA], 339 and OCF Resource Types [OCF]. 341 An "sdfObject" contains a set of "sdfProperty", "sdfAction", and 342 "sdfEvent" definitions that describe the interaction affordances 343 associated with some scope of functionality. 345 For the granularity of definition, "sdfObject" definitions are meant 346 to be kept narrow enough in scope to enable broad reuse and 347 interoperability. For example, defining a light bulb using separate 348 "sdfObject" definitions for on/off control, dimming, and color 349 control affordances will enable interoperable functionality to be 350 configured for diverse product types. An "sdfObject" definition for 351 a common on/off control may be used to control may different kinds of 352 Things that require on/off control. 354 2.2.2. sdfProperty 356 "sdfProperty" is used to model elements of state within "sdfObject" 357 instances. 359 An instance of "sdfProperty" may be associated with some protocol 360 affordance to enable the application to obtain the state variable 361 and, optionally, modify the state variable. Additionally, some 362 protocols provide for in-time reporting of state changes. (These 363 three aspects are described by the qualities "readable", "writable", 364 and "observable" defined for an "sdfProperty".) 366 Definitions in "sdfProperty" groups look like definitions in 367 "sdfData" groups, however, they actually also declare a Property with 368 the given qualities to be potentially present in the containing 369 Object. (Qualities beyond those of "sdfData" definitions could be 370 defined for "sdfProperty" declarations but currently aren't; this 371 means that even Property qualities such as "readable" and "writable" 372 can be associated with definitions in "sdfData" groups, as well.) 373 For definitions in "sdfProperty" and "sdfData", SDF provides 374 qualities that can constrain the structure and values of data allowed 375 in an instance of these data, as well as qualities that associate 376 semantics to these data, for engineering units and unit scaling 377 information. 379 For the data definition within "sdfProperty" or "sdfData", SDF 380 borrows a number of elements proposed for the drafts 4 and 7 of the 381 json-schema.org "JSON Schema" format 382 [I-D.handrews-json-schema-validation], enhanced by qualities that are 383 specific to SDF. For the current version of SDF, data are 384 constrained to be of simple types (number, string, Boolean), JSON 385 maps composed of named data ("objects"), and arrays of these types. 386 Syntax extension points are provided that can be used to provide 387 richer types in future versions of this specification (possibly more 388 of which can be borrowed from json-schema.org). 390 Note that "sdfProperty" definitions (and "sdfData" definitions in 391 general) are not intended to constrain the formats of data used for 392 communication over network interfaces. Where needed, data 393 definitions for payloads of protocol messages are expected to be part 394 of the protocol binding. 396 2.2.3. sdfAction 398 The "sdfAction" group contains declarations of Actions, model 399 affordances that, when triggered, have more effect than just reading, 400 updating, or observing Thing state, often resulting in some outward 401 physical effect (which, itself, cannot be modeled in SDF). From a 402 programmer's perspective, they might be considered to be roughly 403 analogous to method calls. 405 Actions may have data parameters; these are modeled as a single item 406 of input data and output data, each. (Where multiple parameters need 407 to be modeled, an "object" type can be used to combine these 408 parameters into one.) Actions may be long-running, that is to say 409 that the effects may not take place immediately as would be expected 410 for an update to an "sdfPoperty"; the effects may play out over time 411 and emit action results. Actions may also not always complete and 412 may result in application errors, such as an item blocking the 413 closing of an automatic door. 415 Actions may have (or lack) qualities of idempotency and side-effect 416 safety. 418 The current version of SDF only provides data constraint modeling and 419 semantics for the input and output data of definitions in "sdfAction" 420 groups. Again, data definitions for payloads of protocol messages, 421 and detailed protocol settings for invoking the action, are expected 422 to be part of the protocol binding. 424 2.2.4. sdfEvent 426 The "sdfEvent" group contains declarations of Events, which can model 427 affordances that inform about "happenings" associated with an 428 instance of an Object; these may result in a signal being stored or 429 emitted as a result. 431 Note that there is a trivial overlap with sdfProperty state changes, 432 which may also be defined as events but are not generally required to 433 be defined as such. However, Events may exhibit certain ordering, 434 consistency, and reliability requirements that are expected to be 435 supported in various implementations of "sdfEvent" that do 436 distinguish sdfEvent from sdfProperty. For instance, while a state 437 change may simply be superseded by another state change, some events 438 are "precious" and need to be preserved even if further events 439 follow. 441 The current version of SDF only provides data constraint modeling and 442 semantics for the output data of Event affordances. Again, data 443 definitions for payloads of protocol messages, and detailed protocol 444 settings for invoking the action, are expected to be part of the 445 protocol binding. 447 2.2.5. sdfData 449 Definitions in "sdfData" groups are provided separately from those in 450 "sdfProperty" groups to enable common modeling patterns, data 451 constraints, and semantic anchor concepts to be factored out for data 452 items that make up "sdfProperty" items and serve as input and output 453 data for "sdfAction" and "sdfEvent" items. 455 It is a common use case for such a data definition to be shared 456 between an "sdfProperty" item and input or output parameters of an 457 "sdfAction" or output data provided by an "sdfEvent". "sdfData" 458 definitions also enable factoring out extended application data types 459 such as mode and machine state enumerations to be reused across 460 multiple definitions that have similar basic characteristics and 461 requirements. 463 2.2.6. sdfThing 465 Back at the top level, the "sdfThing" groups enables definition of 466 models for complex devices that will use one or more "sdfObject" 467 definitions. 469 A definition in an "sdfThing" group can refine the metadata of the 470 definitions it is composed from: other definitions in "sdfThing" 471 groups definitions in "sdfObject" groups. 473 2.2.7. sdfProduct 475 "sdfThing" has a derived class "sdfProduct", which can be used to 476 indicate a top level inventory item with a Stock-Keeping Unit (SKU) 477 identifier and other particular metadata. Structurally, there is no 478 difference between definitions in either group; semantically, a 479 definition in an "sdfProduct" group is intended to describe a class 480 of complete Things. 482 3. SDF structure 484 SDF definitions are contained in SDF files. One or more SDF files 485 can work together to provide the definitions and declarations that 486 are the payload of the SDF format. 488 A SDF definition file contains a single JSON map (JSON object). This 489 object has three sections: the information block, the namespaces 490 section, and the definitions section. 492 3.1. Information block 494 The information block contains generic meta data for the file itself 495 and all included definitions. 497 The keyword (map key) that defines an information block is "info". 498 Its value is a JSON map in turn, with a set of entries that represent 499 qualities that apply to the included definition. 501 Qualities of the information block are shown in Table 1. 503 +===========+========+==========+=================================+ 504 | Quality | Type | Required | Description | 505 +===========+========+==========+=================================+ 506 | title | string | yes | A short summary to be displayed | 507 | | | | in search results, etc. | 508 +-----------+--------+----------+---------------------------------+ 509 | version | string | yes | The incremental version of the | 510 | | | | definition, format TBD | 511 +-----------+--------+----------+---------------------------------+ 512 | copyright | string | yes | Link to text or embedded text | 513 | | | | containing a copyright notice | 514 +-----------+--------+----------+---------------------------------+ 515 | license | string | yes | Link to text or embedded text | 516 | | | | containing license terms | 517 +-----------+--------+----------+---------------------------------+ 519 Table 1: Qualities of the Information Block 521 While the format of the version string is marked as TBD, it is 522 intended to be lexicographically increasing over the life of a model: 523 a newer model always has a version string that string-compares higher 524 than all previous versions. This is easily achieved by following the 525 convention to start the version with an [RFC3339] "date-time" or, if 526 new versions are generated less frequently than once a day, just the 527 "full-date" (i.e., YYYY-MM-DD); in many cases, that will be all that 528 is needed (see Figure 1 for an example). 530 The license string is preferably either a URI that points to a web 531 page with an unambiguous definition of the license, or an [SPDX] 532 license identifier. (For models to be handled by the One Data Model 533 liaison group, this will typically be "BSD-3-Clause".) 535 3.2. Namespaces section 537 The namespaces section contains the namespace map and the 538 defaultNamespace setting. 540 The namespace map is a map from short names for URIs to the namespace 541 URIs themselves. 543 The defaultNamespace setting selects one of the entries in the 544 namespace map by giving its short name. The associated URI (value of 545 this entry) becomes the default namespace for the SDF definition 546 file. 548 +==================+========+==========+=======================+ 549 | Quality | Type | Required | Description | 550 +==================+========+==========+=======================+ 551 | namespace | map | no | Defines short names | 552 | | | | mapped to namespace | 553 | | | | URIs, to be used as | 554 | | | | identifier prefixes | 555 +------------------+--------+----------+-----------------------+ 556 | defaultNamespace | string | no | Identifies one of the | 557 | | | | prefixes in the | 558 | | | | namespace map to be | 559 | | | | used as a default in | 560 | | | | resolving identifiers | 561 +------------------+--------+----------+-----------------------+ 563 Table 2: Namespaces Section 565 The following example declares a set of namespaces and defines "cap" 566 as the default namespace. By convention, the values in the namespace 567 map contain full URIs without a fragment identifier, and the fragment 568 identifier is then added, if needed, where the namespace entry is 569 used. 571 "namespace": { 572 "cap": "https://example.com/capability/cap", 573 "zcl": "https://zcl.example.com/sdf" 574 }, 575 "defaultNamespace": "cap", 577 If no defaultNamespace setting is given, the SDF definition file does 578 not contribute to a global namespace. As the defaultNamespace is set 579 by giving a namespace short name, its presence requires a namespace 580 map that contains a mapping for that namespace short name. 582 If no namespace map is given, no short names for namespace URIs are 583 set up, and no defaultNamespace can be given. 585 3.3. Definitions section 587 The Definitions section contains one or more groups, each identified 588 by a Class Name Keyword (there can only be one group per keyword; the 589 actual grouping is just a shortcut and does not carry any specific 590 semantics). The value of each group is a JSON map (object), the keys 591 of which serve for naming the individual definitions in this group, 592 and the corresponding values provide a set of qualities (name-value 593 pairs) for the individual definition. (In short, we speak of the map 594 entries as "named sets of qualities".) 595 Each group may contain zero or more definitions. Each identifier 596 defined creates a new type and term in the target namespace. 597 Declarations have a scope of the current definition block. 599 A definition may in turn contain other definitions. Each definition 600 is a named set of qualities, i.e., it consists of the newly defined 601 identifier and a set of key-value pairs that represent the defined 602 qualities and contained definitions. 604 An example for an Object definition is given in Figure 3: 606 "sdfObject": { 607 "foo": { 608 "sdfProperty": { 609 "bar": { 610 "type": "boolean" 611 } 612 } 613 } 614 } 616 Figure 3: Example Object definition 618 This example defines an Object "foo" that is defined in the default 619 namespace (full address: "#/sdfObject/foo"), containing a property 620 that can be addressed as "#/sdfObject/foo/sdfProperty/bar", with data 621 of type boolean. 623 Some of the definitions are also declarations: the definition of the 624 entry "bar" in the property "foo" means that each instance of a "foo" 625 can have zero or one instance of a "bar". Entries within 626 "sdfProperty", "sdfAction", and "sdfEvent", within "sdfObject" 627 entries, are declarations. Similarly, entries within an "sdfThing" 628 describe instances of "sdfObject" (or nested "sdfThing") that form 629 part of instances of the Thing. 631 4. Names and namespaces 633 SDF definition files may contribute to a global namespace, and may 634 reference elements from that global namespace. (An SDF definition 635 file that does not set a defaultNamespace does not contribute to a 636 global namespace.) 638 4.1. Structure 640 Global names look exactly like "https://" URIs with attached fragment 641 identifiers. 643 There is no intention to require that these URIs can be dereferenced. 644 (However, as future versions of SDF might find a use for 645 dereferencing global names, the URI should be chosen in such a way 646 that this may become possible in the future.) 648 The absolute URI of a global name should be a URI as per Section 3 of 649 [RFC3986], with a scheme of "https" and a path ("hier-part" in 650 [RFC3986]). For the present version of this specification, the query 651 part should not be used (it might be used in later versions). 653 The fragment identifier is constructed as per Section 6 of [RFC6901]. 655 4.2. Contributing global names 657 The fragment identifier part of a global name defined in an SDF 658 definition file is constructed from a JSON pointer that selects the 659 element defined for this name in the SDF definition file. 661 The absolute URI part is a copy of the default namespace, i.e., the 662 default namespace is always the target namespace for a name for which 663 a definition is contributed. When emphasizing that name definitions 664 are contributed to the default namespace, we therefore also call it 665 the "target namespace" of the SDF definition file. 667 E.g., in Figure 1, definitions for the following global names are 668 contributed: 670 * https://example.com/capability/cap#/sdfObject/Switch 672 * https://example.com/capability/cap#/sdfObject/Switch/sdfProperty/ 673 value 675 * https://example.com/capability/cap#/sdfObject/Switch/sdfAction/on 677 * https://example.com/capability/cap#/sdfObject/Switch/sdfAction/off 679 Note the "#", which separates the absolute-URI part (Section 4.3 of 680 [RFC3986]) from the fragment identifier part. 682 4.3. Referencing global names 684 A name reference takes the form of the production "curie" in 685 [W3C.NOTE-curie-20101216] (note that this excludes the production 686 "safe-curie"), but also limiting the IRIs involved in that production 687 to URIs as per [RFC3986] and the prefixes to ASCII characters 688 [RFC0020]. 690 A name that is contributed by the current SDF definition file can be 691 referenced by a Same-Document Reference as per section 4.4 of 692 [RFC3986]. As there is little point in referencing the entire SDF 693 definition file, this will be a "#" followed by a JSON pointer. This 694 is the only kind of name reference to itself that is possible in an 695 SDF definition file that does not set a default namespace. 697 Name references that point outside the current SDF definition file 698 need to contain curie prefixes. These then reference namespace 699 declarations in the namespaces section. 701 For example, if a namespace prefix is defined: 703 "namespace": { 704 "foo": "https://example.com/" 705 } 707 Then this reference to that namespace: 709 { "sdfRef": "foo:#/sdfData/temperatureData" } 711 references the global name: 713 "https://example.com/#/sdfData/temperatureData" 715 Note that there is no way to provide a URI scheme name in a curie, so 716 all references outside of the document need to go through the 717 namespace map. 719 Name references occur only in specific elements of the syntax of SDF: 721 * copying elements via sdfRef values 723 * pointing to elements via sdfRequired value elements 725 4.4. sdfRef 727 In a JSON map establishing a definition, the keyword "sdfRef" is used 728 to copy all of the qualities of the referenced definition, indicated 729 by the included name reference, into the newly formed definition. 730 (This can be compared to the processing of the "$ref" keyword in 731 [I-D.handrews-json-schema-validation].) 733 For example, this reference: 735 "temperatureProperty": { 736 "sdfRef": "#/sdfData/temperatureData" 737 } 738 creates a new definition "temperatureProperty" that contains all of 739 the qualities defined in the definition at /sdfData/temperatureData. 741 4.5. sdfRequired 743 The value of "sdfRequired" is an array of name references, each 744 pointing to one declaration the instantiation of which is declared 745 mandatory. 747 4.5.1. Optionality using the keyword "sdfRequired" 749 The keyword "sdfRequired" is provided to apply a constraint that 750 defines for which declarations corresponding data are mandatory in an 751 instance conforming the current definition. 753 The value of "sdfRequired" is an array of JSON pointers, each 754 indicating one declaration that is mandatory to be represented. 756 The example in Figure 4 shows two required elements in the sdfObject 757 definition for "temperatureWithAlarm", the sdfProperty 758 "temperatureData", and the sdfEvent "overTemperatureEvent". The 759 example also shows the use of JSON pointer with "sdfRef" to use a 760 pre-existing definition in this definition, for the "alarmType" data 761 (sdfOutputData) produced by the sdfEvent "overTemperatureEvent". 763 { 764 "sdfObject": { 765 "temperatureWithAlarm": { 766 "sdfRequired": [ 767 "#/sdfObject/temperatureWithAlarm/sdfData/temperatureData", 768 "#/sdfObject/temperatureWithAlarm/sdfEvent/overTemperatureEvent" 769 ], 770 "sdfData":{ 771 "temperatureData": { 772 "type": "number" 773 } 774 }, 775 "sdfEvent": { 776 "overTemperatureEvent": { 777 "sdfOutputData": { 778 "type": "object", 779 "properties": { 780 "alarmType": { 781 "sdfRef": "cap:/sdfData/alarmTypes/quantityAlarms", 782 "const": "OverTemperatureAlarm" 783 }, 784 "temperature": { 785 "sdfRef": "#/sdfObject/temperatureWithAlarm/sdfData/temperatureData" 786 } 787 } 788 } 789 } 790 } 791 } 792 } 793 } 795 Figure 4: Using sdfRequired 797 4.6. Common Qualities 799 Definitions in SDF share a number of qualities that provide metadata 800 for them. These are listed in Table 3. None of these qualities are 801 required or have default values that are assumed if the quality is 802 absent. If a label is required for an application and no label is 803 given in the SDF model, the last part ("reference-token", Section 3 804 of [RFC6901]) of the JSON pointer to the definition can be used. 806 +=============+==============+===================================+ 807 | Quality | Type | Description | 808 +=============+==============+===================================+ 809 | description | text | long text (no constraints) | 810 +-------------+--------------+-----------------------------------+ 811 | label | text | short text (no constraints) | 812 +-------------+--------------+-----------------------------------+ 813 | $comment | text | source code comments only, no | 814 | | | semantics | 815 +-------------+--------------+-----------------------------------+ 816 | sdfRef | sdf-pointer | (see Section 4.4) | 817 +-------------+--------------+-----------------------------------+ 818 | sdfRequired | pointer-list | (see Section 4.5, applies to | 819 | | | qualities of properties, of data) | 820 +-------------+--------------+-----------------------------------+ 822 Table 3: Common Qualities 824 4.7. Data Qualities 826 Data qualities are used in "sdfData" and "sdfProperty" definitions, 827 which are named sets of data qualities (abbreviated as "named-sdq"). 829 Table 4 lists data qualities borrowed from 830 [I-D.handrews-json-schema-validation]; the intention is that these 831 qualities retain their semantics from the versions of the json- 832 schema.org proposal they were imported from. A description that 833 starts with a parenthesized term means the quality is only applicable 834 when "type" has the value of the term. 836 Table 5 lists data qualities defined specifically for the present 837 specification. 839 The term "allowed types" stands for primitive JSON types, JSON maps 840 ("objects")" as well as homogeneous arrays of numbers, text, 841 Booleans, or maps. (This list might be extended in a future version 842 of SDF.) An "allowed value" is a value allowed for one of these 843 types. 845 +================+==========+=======================================+ 846 |Quality |Type |Description | 847 +================+==========+=======================================+ 848 |type |"number" /|JSON data type (note 1) | 849 | |"string" /| | 850 | |"boolean" | | 851 | |/ | | 852 | |"integer" | | 853 | |/ "array" | | 854 | |/ "object"| | 855 +----------------+----------+---------------------------------------+ 856 |enum |array of |enumeration constraint | 857 | |allowed | | 858 | |values | | 859 +----------------+----------+---------------------------------------+ 860 |const |allowed |specifies a constant value for a data | 861 | |value |item or property | 862 +----------------+----------+---------------------------------------+ 863 |default |allowed |specifies the default value for | 864 | |value |initialization | 865 +----------------+----------+---------------------------------------+ 866 |minimum |number |(number) lower limit of value | 867 +----------------+----------+---------------------------------------+ 868 |maximum |number |(number) upper limit of value | 869 +----------------+----------+---------------------------------------+ 870 |exclusiveMinimum|number or |(number) lower limit of value | 871 | |boolean | | 872 | |(jso draft| | 873 | |7/4) | | 874 +----------------+----------+---------------------------------------+ 875 |exclusiveMaximum|number or |(number) lower limit of value | 876 | |boolean | | 877 | |(jso draft| | 878 | |7/4) | | 879 +----------------+----------+---------------------------------------+ 880 |multipleOf |number |(number) resolution of the number | 881 | | |[NEEDED?] | 882 +----------------+----------+---------------------------------------+ 883 |minLength |integer |(string) shortest length string in | 884 | | |octets | 885 +----------------+----------+---------------------------------------+ 886 |maxLength |integer |(string) longest length string in | 887 | | |octets | 888 +----------------+----------+---------------------------------------+ 889 |pattern |string |(string) regular expression to | 890 | | |constrain a string pattern | 891 +----------------+----------+---------------------------------------+ 892 |format |"date- |(string) JSON Schema formats as per | 893 | |time" / |[I-D.handrews-json-schema-validation], | 894 | |"date" / |Section 7.3 | 895 | |"time" / | | 896 | |"uri" / | | 897 | |"uri- | | 898 | |reference"| | 899 | |/ "uuid" | | 900 +----------------+----------+---------------------------------------+ 901 |minItems |number |(array) Minimum number of items in | 902 | | |array | 903 +----------------+----------+---------------------------------------+ 904 |maxItems |number |(array) Maximum number of items in | 905 | | |array | 906 +----------------+----------+---------------------------------------+ 907 |uniqueItems |boolean |(array) if true, requires items to be | 908 | | |all different | 909 +----------------+----------+---------------------------------------+ 910 |items |(subset of|(array) constraints on array items | 911 | |common/ | | 912 | |data | | 913 | |qualities;| | 914 | |see | | 915 | |Appendix A| | 916 +----------------+----------+---------------------------------------+ 917 |required |array of |(object) names of properties (note 2) | 918 | |strings |that are required in the JSON map | 919 | | |("object") | 920 +----------------+----------+---------------------------------------+ 921 |properties |named set |(object) entries allowed for the JSON | 922 | |of data |map ("object") | 923 | |qualities | | 924 +----------------+----------+---------------------------------------+ 926 Table 4: Qualities of sdfProperty and sdfData borrowed from json- 927 schema.org 929 (1) A type value of "integer" means that only integral values of JSON 930 numbers can be used. 932 (2) Note that the term "properties" as used for map entries in 933 [I-D.handrews-json-schema-validation] is unrelated to sdfProperty. 935 +===============+===============+====================+=========+ 936 | Quality | Type | Description | Default | 937 +===============+===============+====================+=========+ 938 | (common) | | Section 4.6 | | 939 +---------------+---------------+--------------------+---------+ 940 | unit | string | SenML unit name as | N/A | 941 | | | per [IANA.senml], | | 942 | | | subregistry SenML | | 943 | | | Units (note 3) | | 944 +---------------+---------------+--------------------+---------+ 945 | scaleMinimum | number | lower limit of | N/A | 946 | | | value in units | | 947 | | | given by unit | | 948 +---------------+---------------+--------------------+---------+ 949 | scaleMaximum | number | upper limit of | N/A | 950 | | | value in units | | 951 | | | given by unit | | 952 +---------------+---------------+--------------------+---------+ 953 | readable | boolean | Reads are allowed | true | 954 +---------------+---------------+--------------------+---------+ 955 | writable | boolean | Writes are allowed | true | 956 +---------------+---------------+--------------------+---------+ 957 | observable | boolean | flag to indicate | true | 958 | | | asynchronous | | 959 | | | notification is | | 960 | | | available | | 961 +---------------+---------------+--------------------+---------+ 962 | nullable | boolean | indicates a null | true | 963 | | | value is available | | 964 | | | for this type | | 965 +---------------+---------------+--------------------+---------+ 966 | contentFormat | string | content type (IANA | N/A | 967 | | | media type string | | 968 | | | plus parameters), | | 969 | | | encoding | | 970 +---------------+---------------+--------------------+---------+ 971 | subtype | "byte-string" | subtype | N/A | 972 | | / "unix-time" | enumeration | | 973 +---------------+---------------+--------------------+---------+ 975 Table 5: SDF-defined Qualities of sdfProperty and sdfData 977 (3) note that the quality "unit" was called "units" in SDF 1.0. 979 5. Keywords for definition groups 981 The following SDF keywords are used to create definition groups in 982 the target namespace. All these definitions share some common 983 qualities as discussed in Section 4.6. 985 5.1. sdfObject 987 The sdfObject keyword denotes a group of zero or more Object 988 definitions. Object definitions may contain or include definitions 989 of Properties, Actions, Events declared for the object, as well as 990 data types (sdfData group) to be used in this or other Objects. 992 The qualities of an sdfObject include the common qualities, 993 additional qualities are shown in Table 6. None of these qualities 994 are required or have default values that are assumed if the quality 995 is absent. 997 +=============+===========+=============================+ 998 | Quality | Type | Description | 999 +=============+===========+=============================+ 1000 | (common) | | Section 4.6 | 1001 +-------------+-----------+-----------------------------+ 1002 | sdfProperty | property | zero or more named property | 1003 | | | definitions for this object | 1004 +-------------+-----------+-----------------------------+ 1005 | sdfAction | action | zero or more named action | 1006 | | | definitions for this object | 1007 +-------------+-----------+-----------------------------+ 1008 | sdfEvent | event | zero or more named event | 1009 | | | definitions for this object | 1010 +-------------+-----------+-----------------------------+ 1011 | sdfData | named-sdq | zero or more named data | 1012 | | | type definitions that might | 1013 | | | be used in the above | 1014 +-------------+-----------+-----------------------------+ 1016 Table 6: Qualities of sdfObject 1018 5.2. sdfProperty 1020 The sdfProperty keyword denotes a group of zero or more Property 1021 definitions. 1023 Properties are used to model elements of state. 1025 The qualities of a Property definition include the data qualities 1026 (and thus the common qualities), see Section 4.7. 1028 5.3. sdfAction 1030 The sdfAction keyword denotes a group of zero or more Action 1031 definitions. 1033 Actions are used to model commands and methods which are invoked. 1034 Actions have parameter data that are supplied upon invocation. 1036 The qualities of an Action definition include the common qualities, 1037 additional qualities are shown in Table 7. 1039 +===============+===========+============================+ 1040 | Quality | Type | Description | 1041 +===============+===========+============================+ 1042 | (common) | | Section 4.6 | 1043 +---------------+-----------+----------------------------+ 1044 | sdfInputData | map | data qualities of the | 1045 | | | input data for an Action | 1046 +---------------+-----------+----------------------------+ 1047 | sdfOutputData | map | data qualities of the | 1048 | | | output data for an Action | 1049 +---------------+-----------+----------------------------+ 1050 | sdfData | named-sdq | zero or more named data | 1051 | | | type definitions that | 1052 | | | might be used in the above | 1053 +---------------+-----------+----------------------------+ 1055 Table 7: Qualities of sdfAction 1057 "sdfInputData" defines the input data of the action. "sdfOutputData" 1058 defines the output data of the action. As discussed in 1059 Section 2.2.3, a set of data qualities with type "object" can be used 1060 to substructure either data item, with optionality indicated by the 1061 data quality "required". 1063 5.4. sdfEvent 1065 The sdfEvent keyword denotes zero or more Event definitions. 1067 Events are used to model asynchronous occurrences that may be 1068 communicated proactively. Events have data elements which are 1069 communicated upon the occurrence of the event. 1071 The qualities of sdfEvent include the common qualities, additional 1072 qualities are shown in Table 8. 1074 +===============+===========+============================+ 1075 | Quality | Type | Description | 1076 +===============+===========+============================+ 1077 | (common) | | Section 4.6 | 1078 +---------------+-----------+----------------------------+ 1079 | sdfOutputData | map | data qualities of the | 1080 | | | output data for an Event | 1081 +---------------+-----------+----------------------------+ 1082 | sdfData | named-sdq | zero or more named data | 1083 | | | type definitions that | 1084 | | | might be used in the above | 1085 +---------------+-----------+----------------------------+ 1087 Table 8: Qualities of sdfEvent 1089 "sdfOutputData" defines the output data of the action. As discussed 1090 in Section 2.2.4, a set of data qualities with type "object" can be 1091 used to substructure the output data item, with optionality indicated 1092 by the data quality "required". 1094 5.5. sdfData 1096 The sdfData keyword denotes a group of zero or more named data type 1097 definitions (named-sdq). 1099 An sdfData definition provides a reusable semantic identifier for a 1100 type of data item and describes the constraints on the defined type. 1101 It is not itself a declaration, i.e., it does not cause any of these 1102 data items to be included in an affordance definition. 1104 The qualities of sdfData include the data qualities (and thus the 1105 common qualities), see Section 4.7. 1107 6. High Level Composition 1109 The requirements for high level composition include the following: 1111 * The ability to represent products, standardized product types, and 1112 modular products while maintaining the atomicity of Objects. 1114 * The ability to compose a reusable definition block from Objects, 1115 for example a single plug unit of an outlet strip with on/off 1116 control, energy monitor, and optional dimmer objects, while 1117 retaining the atomicity of the individual objects. 1119 * The ability to compose Objects and other definition blocks into a 1120 higher level thing that represents a product, while retaining the 1121 atomicity of objects. 1123 * The ability to enrich and refine a base definition to have 1124 product-specific qualities and quality values, e.g. unit, range, 1125 and scale settings. 1127 * The ability to reference items in one part of a complex definition 1128 from another part of the same definition, for example to summarize 1129 the energy readings from all plugs in an outlet strip. 1131 6.1. Paths in the model namespaces 1133 The model namespace is organized according to terms that are defined 1134 in the definition files that are present in the namespace. For 1135 example, definitions that originate from an organization or vendor 1136 are expected to be in a namespace that is specific to that 1137 organization or vendor. There is expected to be an SDF namespace for 1138 common SDF definitions used in OneDM. 1140 The structure of a path in a namespace is defined by the JSON 1141 Pointers to the definitions in the files in that namespace. For 1142 example, if there is a file defining an object "Switch" with an 1143 action "on", then the reference to the action would be 1144 "ns:/sdfObject/Switch/sdfAction/on" where "ns" is the namespace 1145 prefix (short name for the namespace). 1147 6.2. Modular Composition 1149 Modular composition of definitions enables an existing definition 1150 (could be in the same file or another file) to become part of a new 1151 definition by including a reference to the existing definition within 1152 the model namespace. 1154 6.2.1. Use of the "sdfRef" keyword to re-use a definition 1156 An existing definition may be used as a template for a new 1157 definition, that is, a new definition is created in the target 1158 namespace which uses the defined qualities of some existing 1159 definition. This pattern will use the keyword "sdfRef" as a quality 1160 of a new definition with a value consisting of a reference to the 1161 existing definition that is to be used as a template. Optionally, 1162 new qualities may be added and values of optional qualities and 1163 quality values may be defined. 1165 ISSUE: Do we want to enable qualities from the source definition to 1166 be overridden in future versions? The above only says "added". 1167 (Yes, we do want to enable overriding, but need to warn specifiers 1168 not to use this in a way that contradicts the referenced semantics.) 1169 "sdfData": 1170 "length" : { 1171 "type": "number", 1172 "minimum": 0, 1173 "unit": "m" 1174 "description": "There can be no negative lengths." 1175 } 1176 ... 1177 "cable-length" : { 1178 "sdfRef": "#/sdfData/length" 1179 "minimum": 0.05, 1180 "description": "Cables must be at least 5 cm." 1181 } 1183 6.3. sdfThing 1185 An sdfThing is a set of declarations and qualities that may be part 1186 of a more complex model. For example, the object declarations that 1187 make up the definition of a single socket of an outlet strip could be 1188 encapsulated in an sdfThing, and the socket-thing itself could be 1189 used in a declaration in the sdfThing definition for the outlet 1190 strip. 1192 sdfThing definitions carry semantic meaning, such as a defined 1193 refrigerator compartment and a defined freezer compartment, making up 1194 a combination refrigerator-freezer product. 1196 An sdfThing may be composed of sdfObjects and other sdfThings. 1198 The qualities of sdfThing are shown in Table 9. 1200 +===========+========+=============+ 1201 | Quality | Type | Description | 1202 +===========+========+=============+ 1203 | (common) | | Section 4.6 | 1204 +-----------+--------+-------------+ 1205 | sdfThing | thing | | 1206 +-----------+--------+-------------+ 1207 | sdfObject | object | | 1208 +-----------+--------+-------------+ 1210 Table 9: Qualities of sdfThing 1211 and sdfProduct 1213 6.4. sdfProduct 1215 An sdfProduct provides the level of abstraction for representing a 1216 unique product or a profile for a standardized type of product, for 1217 example a "device type" definition with required minimum 1218 functionality. 1220 Products may be composed of Objects and Things at the high level, and 1221 may include their own definitions of Properties, Actions, and Events 1222 that can be used to extend or complete the included Object 1223 definitions. 1225 Product definitions may set optional defaults and constant values for 1226 specific use cases, for example units, range, and scale settings for 1227 properties, or available parameters for Actions. 1229 The qualities of sdfProduct are the same as for sdfThing and are 1230 shown in Table 9. 1232 7. References 1234 7.1. Normative References 1236 [I-D.handrews-json-schema-validation] 1237 Wright, A., Andrews, H., and B. Hutton, "JSON Schema 1238 Validation: A Vocabulary for Structural Validation of 1239 JSON", Work in Progress, Internet-Draft, draft-handrews- 1240 json-schema-validation-02, 17 September 2019, 1241 . 1244 [I-D.ietf-cbor-cddl-control] 1245 Bormann, C., "Additional Control Operators for CDDL", Work 1246 in Progress, Internet-Draft, draft-ietf-cbor-cddl-control- 1247 00, 29 September 2020, . 1250 [IANA.senml] 1251 IANA, "Sensor Measurement Lists (SenML)", 1252 . 1254 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 1255 RFC 20, DOI 10.17487/RFC0020, October 1969, 1256 . 1258 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1259 Requirement Levels", BCP 14, RFC 2119, 1260 DOI 10.17487/RFC2119, March 1997, 1261 . 1263 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1264 Resource Identifier (URI): Generic Syntax", STD 66, 1265 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1266 . 1268 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 1269 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 1270 DOI 10.17487/RFC6901, April 2013, 1271 . 1273 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1274 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1275 May 2017, . 1277 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1278 Definition Language (CDDL): A Notational Convention to 1279 Express Concise Binary Object Representation (CBOR) and 1280 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1281 June 2019, . 1283 [SPDX] "SPDX License List", . 1285 [W3C.NOTE-curie-20101216] 1286 Birbeck, M. and S. McCarron, "CURIE Syntax 1.0", World 1287 Wide Web Consortium NOTE NOTE-curie-20101216, 16 December 1288 2010, . 1290 7.2. Informative References 1292 [I-D.irtf-t2trg-rest-iot] 1293 Keranen, A., Kovatsch, M., and K. Hartke, "RESTful Design 1294 for Internet of Things Systems", Work in Progress, 1295 Internet-Draft, draft-irtf-t2trg-rest-iot-06, 11 May 2020, 1296 . 1299 [OCF] "OCF Resource Type Specification", 1300 . 1303 [OMA] "OMA LightweightM2M (LwM2M) Object and Resource Registry", 1304 . 1307 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1308 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1309 . 1311 [ZCL] "The ZigBee Cluster Library", Zigbee Wireless 1312 Networking pp. 239-271, 1313 DOI 10.1016/b978-0-7506-8597-9.00006-9, 2008, 1314 . 1316 Appendix A. Formal Syntax of SDF 1318 This appendix describes the syntax of SDF using CDDL [RFC8610]. Note 1319 that this appendix was derived from Ari Keranen's "alt-schema" and 1320 Michael Koster's "schema", with a view of covering the syntax that is 1321 currently in use at the One Data Model "playground" repository. 1323 This appendix shows the framework syntax only, i.e., a syntax with 1324 liberal extension points. Since this syntax is nearly useless in 1325 finding typos in an SDF specification, a second syntax, the 1326 validation syntax, is defined that does not include the extension 1327 points. The validation syntax can be generated from the framework 1328 syntax by leaving out all lines containing the string "EXTENSION- 1329 POINT"; as this is trivial, the result is not shown here. 1331 This appendix makes use of CDDL "features" as defined in Section 4 of 1332 [I-D.ietf-cbor-cddl-control]. A feature named "1.0" is used to 1333 indicate parts of the syntax being deprecated towards SDF 1.1, and a 1334 feature named "1.1" is used to indicate new syntax intended for SDF 1335 1.1. Features whose names end in "-ext" indicate extension points 1336 for further evolution. 1338 start = sdf-syntax 1340 sdf-syntax = { 1341 info: sdfinfo ; don't *require* this in flexible syntax, though 1342 ? namespace: named 1343 ? defaultNamespace: text 1344 ? sdfThing: named ; Thing is a composition of objects that work together in some way 1345 ? sdfProduct: named ; Product is a composition of things and objects that can model a SKU-level instance of a product 1346 ? sdfObject: named ; Object is a set of Properties, Actions, and Events that together perform a particular function 1347 ? sdfProperty: named ; Property represents the state of an instance of an object 1348 ? sdfAction: named ; Action is a directive to invoke an application layer verb associated with an object 1349 ? sdfEvent: named ; Event represents an occurence of something associated with an object 1350 ? sdfData: named ; Data represents a piece of information that can be the state of a property or a parameter to an action or a signal in an event 1351 EXTENSION-POINT<"top-ext"> 1352 } 1354 sdfinfo = { 1355 title: text 1356 version: text 1357 copyright: text 1358 license: text 1359 EXTENSION-POINT<"info-ext"> 1360 } 1362 ; Shortcut for a map that gives names to instances of X (has text keys and values of type X) 1363 named = { * text => X } 1365 EXTENSION-POINT = ( * (text .feature f) => any ) ; only used in framework syntax 1367 sdf-pointer = text ; .regexp curie-regexp -- TO DO! 1368 pointer-list = [* sdf-pointer] ; ISSUE: no point in having an empty list, no? but used for sdfRequired in odmobject-multiple_axis_joystick.sdf.json 1370 commonqualities = ( 1371 ? description: text ; long text (no constraints) 1372 ? label: text ; short text (no constraints); default to key 1373 ? $comment: text ; source code comments only, no semantics 1374 ? sdfRef: sdf-pointer 1375 ? sdfRequired: pointer-list ; applies to qualities of properties, of data 1376 ) 1378 ; for building hierarchy 1379 thingqualities = { 1380 commonqualities, 1381 ? sdfObject: named 1382 ? sdfThing: named 1383 EXTENSION-POINT<"thing-ext"> 1384 } 1386 productqualities = thingqualities ; ISSUE: get rid of sdfProduct? 1388 ; for single objects 1389 objectqualities = { 1390 commonqualities, 1391 ? sdfProperty: named 1392 ? sdfAction: named 1393 ? sdfEvent: named 1394 ? sdfData: named 1395 EXTENSION-POINT<"object-ext"> 1396 } 1398 propertyqualities = dataqualities ; the definitions in sdfData are declarations in sdfProperty 1400 parameter-list = 1401 pointer-list .feature (["1.0", "pointerlist-as-parameter"]) / 1402 dataqualities .feature (["1.1", "dataqualities-as-parameter"]) 1404 actionqualities = { 1405 commonqualities, 1406 ? sdfInputData: parameter-list ; sdfRequiredInputData applies here (a bit redundant) 1407 ? sdfRequiredInputData: pointer-list 1408 ? sdfOutputData: parameter-list ; sdfRequired applies here 1409 ? sdfData: named ; zero or more named data type definitions that might be used in the above 1410 EXTENSION-POINT<"action-ext"> 1411 } 1413 eventqualities = { 1414 commonqualities 1415 ? sdfOutputData: parameter-list ; sdfRequired applies here 1416 ? sdfData: named ; zero or more named data type definitions that might be used in the above 1417 EXTENSION-POINT<"event-ext"> 1418 } 1420 dataqualities = { ; also propertyqualities 1421 commonqualities, 1422 jsonschema, 1423 ? ("units" .feature "1.0") => text 1424 ? ("unit" .feature "1.1") => text 1425 ? scaleMinimum: number 1426 ? scaleMaximum: number 1427 ? observable: bool 1428 ? readable: bool 1429 ? writable: bool 1430 ? nullable: bool 1431 ? subtype: "byte-string" / "unix-time" 1432 / (text .feature "subtype-ext") ; EXTENSION-POINT 1433 ? contentFormat: text 1434 EXTENSION-POINT<"data-ext"> 1435 } 1437 allowed-types = number / text / bool / null 1438 / [* number] / [* text] / [* bool] 1439 / {* text => any} 1440 / (any .feature "allowed-ext") ; EXTENSION-POINT 1442 compound-type = ( 1443 "type" => ("object" .feature "1.1"), 1444 ? required: [+text], 1445 ? properties: named, 1446 ) 1448 jsonschema = ( 1449 ? (("type" => "number" / "string" / "boolean" / "integer" / "array") 1450 // compound-type 1451 // (type: text .feature "type-ext") ; EXTENSION-POINT 1453 ) 1454 ? enum: [+ allowed-types] ; should validate against type 1455 ? const: allowed-types 1456 ? default: allowed-types 1457 ; number/integer constraints 1458 ? minimum: number 1459 ? maximum: number 1460 ? exclusiveMinimum: bool / number ; jso draft 4/7 1461 ? exclusiveMaximum: bool / number ; jso draft 4/7 1462 ? multipleOf: number ; ISSUE: Do we need this? 1463 ; text string constraints 1464 ? minLength: number 1465 ? maxLength: number 1466 ? pattern: text ; regexp 1467 ? format: "date-time" / "date" / "time" 1468 / "uri" / "uri-reference" / "uuid" 1469 / (text .feature "format-ext") ; EXTENSION-POINT 1470 ; array constraints 1471 ? minItems: number 1472 ? maxItems: number 1473 ? uniqueItems: bool 1474 ? items: { ;;; ultimately, this will be mostly recursive, but, for now 1475 ;;; let's find out what we actually need 1476 ? sdfRef: sdf-pointer ; import limited to the subset that we allow here... 1477 ? description: text ; long text (no constraints) 1478 ? $comment: text ; source code comments only, no semantics 1479 ; commonqualities, ; -- ISSUE: should leave this out for non-complex data types, but need the above three 1480 ? ((type: "number" / "string" / "boolean" / "integer") ; no "array" 1481 // compound-type 1482 // (type: text .feature "itemtype-ext") ; EXTENSION-POINT 1483 ) 1484 ; jso subset 1485 ? minimum: number 1486 ? maximum: number 1487 ? enum: [+ any] 1488 ? format: text 1489 ? minLength: number 1490 ? maxLength: number 1491 EXTENSION-POINT<"items-ext"> 1492 } 1493 ) 1495 Appendix B. json-schema.org Rendition of SDF Syntax 1497 This appendix describes the syntax of SDF defined in Appendix A, but 1498 using a version of the description techniques advertised on json- 1499 schema.org [I-D.handrews-json-schema-validation]. 1501 The appendix shows both the validation and the framework syntax. 1502 Since most of the lines are the same between these two files, those 1503 lines are shown only once, with a leading space, in the form of a 1504 unified diff. Lines leading with a "-" are part of the validation 1505 syntax, and lines leading with a "+" are part of the framework 1506 syntax. 1508 (The json-schema.org descriptions need to be regenerated after the 1509 converter has been upgraded to handle the group choices introduced in 1510 the latest CDDL.) 1512 Acknowledgements 1514 This draft is based on "sdf.md" and "sdf-schema.json" in the old one- 1515 data-model "language" repository, as well as Ari Keranen's "alt- 1516 schema" from the Ericsson Research "ipso-odm" repository (which is 1517 now under subdirectory "sdflint" in the one-data model "tools" 1518 repository). 1520 Contributors 1522 Ari Keränen 1523 Ericsson 1524 FI-02420 Jorvas 1525 Finland 1527 Email: ari.keranen@ericsson.com 1529 Wouter van der Beek 1530 Cisco Systems 1531 Eastpoint Business Park 1532 Alfie Byrne Road 1533 Dublin 3 1534 Ireland 1536 Email: wovander@cisco.com 1538 Authors' Addresses 1540 Michael Koster (editor) 1541 SmartThings 1542 665 Clyde Avenue 1543 Mountain View, 94043 1544 United States of America 1546 Phone: +1-707-502-5136 1547 Email: Michael.Koster@smartthings.com 1549 Carsten Bormann (editor) 1550 Universität Bremen TZI 1551 Postfach 330440 1552 D-28359 Bremen 1553 Germany 1555 Phone: +49-421-218-63921 1556 Email: cabo@tzi.org