idnits 2.17.1 draft-ietf-asdf-sdf-00.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 29 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 1257 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-13) exists of draft-irtf-t2trg-rest-iot-06 Summary: 3 errors (**), 0 flaws (~~), 4 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-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 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 is defined in this document. 26 (This is a republication of draft-onedm-t2trg-sdf-00 as an IETF ASDF 27 Working Group document, with no technical changes, a superfluous 28 figure removed, and some tool version induced reformatting.) 30 Contributing 32 Recent versions of this document are available at its GitHub 33 repository https://github.com/ietf-wg-asdf/SDF (https://github.com/ 34 ietf-wg-asdf/SDF) -- this also provides an issue tracker as well as a 35 way to supply "pull requests". 37 General discussion of this SDF Internet-Draft happens on the mailing 38 list of the IETF ASDF Working Group, asdf@ietf.org (subscribe at 39 https://www.ietf.org/mailman/listinfo/asdf 40 (https://www.ietf.org/mailman/listinfo/asdf)). 42 The IETF Note Well applies (https://www.ietf.org/about/note-well/ 43 (https://www.ietf.org/about/note-well/)). 45 Status of This Memo 47 This Internet-Draft is submitted in full conformance with the 48 provisions of BCP 78 and BCP 79. 50 Internet-Drafts are working documents of the Internet Engineering 51 Task Force (IETF). Note that other groups may also distribute 52 working documents as Internet-Drafts. The list of current Internet- 53 Drafts is at https://datatracker.ietf.org/drafts/current/. 55 Internet-Drafts are draft documents valid for a maximum of six months 56 and may be updated, replaced, or obsoleted by other documents at any 57 time. It is inappropriate to use Internet-Drafts as reference 58 material or to cite them other than as "work in progress." 60 This Internet-Draft will expire on 19 May 2021. 62 Copyright Notice 64 Copyright (c) 2020 IETF Trust and the persons identified as the 65 document authors. All rights reserved. 67 This document is subject to BCP 78 and the IETF Trust's Legal 68 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 69 license-info) in effect on the date of publication of this document. 70 Please review these documents carefully, as they describe your rights 71 and restrictions with respect to this document. Code Components 72 extracted from this document must include Simplified BSD License text 73 as described in Section 4.e of the Trust Legal Provisions and are 74 provided without warranty as described in the Simplified BSD License. 76 Table of Contents 78 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 79 1.1. Terminology and Conventions . . . . . . . . . . . . . . . 3 80 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 81 2.1. Example Definition . . . . . . . . . . . . . . . . . . . 5 82 2.2. Elements of an SDF model . . . . . . . . . . . . . . . . 7 83 2.2.1. sdfObject . . . . . . . . . . . . . . . . . . . . . . 8 84 2.2.2. sdfProperty . . . . . . . . . . . . . . . . . . . . . 8 85 2.2.3. sdfAction . . . . . . . . . . . . . . . . . . . . . . 9 86 2.2.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . 10 87 2.2.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . 10 88 2.2.6. sdfThing . . . . . . . . . . . . . . . . . . . . . . 11 89 2.2.7. sdfProduct . . . . . . . . . . . . . . . . . . . . . 11 90 3. SDF structure . . . . . . . . . . . . . . . . . . . . . . . . 11 91 3.1. Information block . . . . . . . . . . . . . . . . . . . . 11 92 3.2. Namespaces section . . . . . . . . . . . . . . . . . . . 12 93 3.3. Definitions section . . . . . . . . . . . . . . . . . . . 13 94 4. Names and namespaces . . . . . . . . . . . . . . . . . . . . 14 95 4.1. Structure . . . . . . . . . . . . . . . . . . . . . . . . 14 96 4.2. Contributing global names . . . . . . . . . . . . . . . . 15 97 4.3. Referencing global names . . . . . . . . . . . . . . . . 15 98 4.4. sdfRef . . . . . . . . . . . . . . . . . . . . . . . . . 16 99 4.5. sdfRequired . . . . . . . . . . . . . . . . . . . . . . . 17 100 4.5.1. Optionality using the keyword "sdfRequired" . . . . . 17 101 4.6. Common Qualities . . . . . . . . . . . . . . . . . . . . 18 102 4.7. Data Qualities . . . . . . . . . . . . . . . . . . . . . 19 103 5. Keywords for definition groups . . . . . . . . . . . . . . . 22 104 5.1. sdfObject . . . . . . . . . . . . . . . . . . . . . . . . 22 105 5.2. sdfProperty . . . . . . . . . . . . . . . . . . . . . . . 22 106 5.3. sdfAction . . . . . . . . . . . . . . . . . . . . . . . . 23 107 5.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . . . 23 108 5.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . . . 24 109 6. High Level Composition . . . . . . . . . . . . . . . . . . . 24 110 6.1. Paths in the model namespaces . . . . . . . . . . . . . . 25 111 6.2. Modular Composition . . . . . . . . . . . . . . . . . . . 25 112 6.2.1. Use of the "sdfRef" keyword to re-use a definition . 25 113 6.3. sdfThing . . . . . . . . . . . . . . . . . . . . . . . . 26 114 6.4. sdfProduct . . . . . . . . . . . . . . . . . . . . . . . 27 115 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 116 7.1. Normative References . . . . . . . . . . . . . . . . . . 27 117 7.2. Informative References . . . . . . . . . . . . . . . . . 28 118 Appendix A. Formal Syntax of SDF . . . . . . . . . . . . . . . . 29 119 Appendix B. json-schema.org Rendition of SDF Syntax . . . . . . 32 120 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 49 121 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 49 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 124 1. Introduction 126 The Semantic Definition Format (SDF) is a format for domain experts 127 to use in the creation and maintenance of data and interaction models 128 in the Internet of Things. It was created as a common language for 129 use in the development of the One Data Model liaison organization 130 (OneDM) definitions. Tools convert this format to database formats 131 and other serializations as needed. 133 An SDF specification describes definitions of SDF Objects and their 134 associated interactions (Events, Actions, Properties), as well as the 135 Data types for the information exchanged in those interactions. 137 A JSON format representation of SDF 1.0 is defined in this document. 139 1.1. Terminology and Conventions 141 Thing: A physical device that is also made available in the Internet 142 of Things. The term is used here for Things that are notable for 143 their interaction with the physical world beyond interaction with 144 humans; a temperature sensor or a light might be a Thing, but a 145 router that employs both temperature sensors and indicator lights 146 might exhibit less Thingness, as the effects of its functioning 147 are mostly on the digital side. 149 Affordance: An element of an interface offered for interaction, 150 defining its possible uses or making clear how it can or should be 151 used. The term is used here for the digital interfaces of a Thing 152 only; it might also have physical affordances such as buttons, 153 dials, and displays. 155 Quality: A metadata item in a definition or declaration which says 156 something about that definition or declaration. A quality is 157 represented in SDF as an entry in a JSON map (object) that serves 158 as a definition or declaration. 160 Entry: A key-value pair in a map. (In JSON maps, sometimes also 161 called "member".) 163 Block: One or more entries in a JSON map that is part of an SDF 164 specification; these entries together serve a specific function. 166 Group: An entry in the main SDF map and in certain nested 167 definitions that either has a Class Name Keyword as its key and a 168 map of definition entries (Definition Group) or a Parameter Name 169 Keyword as its key and an array of SDF pointers as a value 170 (Parameter Group). 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; properties in other environments; in this 196 document, the term Object is specifically reserved for the above 197 grouping, even if the type name "object" might be imported from a 198 data definition language with the other semantics.) 200 Parameter name keyword: One of sdfInputData, sdfOutputData, 201 sdfRequiredInputData, or sdfRequired. 203 Element: A part or an aspect of something abstract; used here in its 204 usual English definition. (Occasionally, also used specifically 205 for the elements of JSON arrays.) 207 Definition: An entry in a Definition Group; the entry creates a new 208 semantic term for use in SDF models and associates it with a set 209 of qualities. 211 Declaration: A reference to and a use of a definition within an 212 enclosing definition, intended to create component instances 213 within that enclosing definition. Every declaration can also be 214 used as a definition for reference in a different place. 216 Protocol Binding: A companion document to an SDF specification that 217 defines how to map the abstract concepts in the specification into 218 the protocols in use in a specific ecosystem. Might supply URL 219 components, numeric IDs, and similar details. 221 Conventions: 223 * The singular form is chosen as the preferred one for the keywords 224 defined here. 226 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 227 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 228 "OPTIONAL" in this document are to be interpreted as described in 229 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 230 capitals, as shown here. 232 2. Overview 234 2.1. Example Definition 236 We start with an example for the SDF definition of a simple Object 237 called "Switch" (Figure 1). 239 { 240 "info": { 241 "title": "Example file for OneDM Semantic Definition Format", 242 "version": "2019-04-24", 243 "copyright": "Copyright 2019 Example Corp. All rights reserved.", 244 "license": "https://example.com/license" 245 }, 246 "namespace": { 247 "cap": "https://example.com/capability/cap" 248 }, 249 "defaultNamespace": "cap", 250 "sdfObject": { 251 "Switch": { 252 "sdfProperty": { 253 "value": { 254 "description": "The state of the switch; false for off and true for on." 255 "type": "boolean" 256 } 257 }, 258 "sdfAction": { 259 "on": { 260 "description": "Turn the switch on; equivalent to setting value to true." 261 }, 262 "off": { 263 "description": "Turn the switch on; equivalent to setting value to false." 264 }, 265 "toggle": { 266 "description": "Toggle the switch; equivalent to setting value to its complement." 267 } 268 } 269 } 270 } 271 } 273 Figure 1: A simple example of an SDF definition file 275 This is a model of a switch. The state "value" declared in the 276 "sdfProperty" group, represented by a Boolean, will be true for "on" 277 and will be false for "off". The actions "on" or "off" declared in 278 the "sdfAction" group are redundant with setting the "value" and are 279 in the example to illustrate that there are often different ways of 280 achieving the same effect. The action "toggle" will invert the value 281 of the sdfProperty value, so that 2-way switches can be created; 282 having such action will avoid the need for first retrieving the 283 current value and then applying/setting the inverted value. 285 The "sdfObject" group lists the affordances of instances of this 286 object. The "sdfProperty" group lists the property affordances 287 described by the model; these represent various perspectives on the 288 state of the object. Properties can have additional qualities to 289 describe the state more precisely. Properties can be annotated to be 290 read, write or read/write; how this is actually done by the 291 underlying transfer protocols is not described in the SDF model but 292 left to companion protocol bindings. Properties are often used with 293 RESTful paradigms [I-D.irtf-t2trg-rest-iot], describing state. The 294 "sdfAction" group is the mechanism to describe other interactions in 295 terms of their names, input, and output data (no data are used in the 296 example), as in a POST method in REST or in a remote procedure call. 297 The example "toggle" is an Action that changes the state based on the 298 current state of the Property named "value". (The third type of 299 affordance is Events, which are not described in this example.) 301 2.2. Elements of an SDF model 303 The SDF language uses seven predefined Class Name Keywords for 304 modeling connected Things, six of which are illustrated in Figure 2 305 (the seventh class "sdfProduct" is exactly like "sdfThing"). 307 ,--------. 308 |sdfThing| 309 |--------| 310 |--------| 311 `--------' 312 | 313 | 314 ,---------. 315 |sdfObject| 316 |---------| 317 |---------| 318 `---------' 319 | 320 ,-----------. ,---------. ,--------. 321 |sdfProperty| |sdfAction| |sdfEvent| 322 |-----------| |---------| |--------| 323 |-----------| |---------| |--------| 324 `-----------' `---------' `--------' 326 ,-------. 327 |sdfData| 328 |-------| 329 |-------| 330 `-------' 332 Figure 2: Main classes used in SDF models 334 The seven main Class Name Keywords are discussed below. 336 2.2.1. sdfObject 338 Objects, the items listed in an "sdfObject" group, are the main 339 "atom" of reusable semantics for model construction. It aligns in 340 scope with common definition items from many IoT modeling systems, 341 for example ZigBee Clusters [ZCL], OMA SpecWorks LwM2M Objects [OMA], 342 and OCF Resource Types [OCF]. 344 An "sdfObject" contains a set of "sdfProperty", "sdfAction", and 345 "sdfEvent" definitions that describe the interaction affordances 346 associated with some scope of functionality. 348 For the granularity of definition, "sdfObject" definitions are meant 349 to be kept narrow enough in scope to enable broad reuse and 350 interoperability. For example, defining a light bulb using separate 351 "sdfObject" definitions for on/off control, dimming, and color 352 control affordances will enable interoperable functionality to be 353 configured for diverse product types. An "sdfObject" definition for 354 a common on/off control may be used to control may different kinds of 355 Things that require on/off control. 357 2.2.2. sdfProperty 359 "sdfProperty" is used to model elements of state within "sdfObject" 360 instances. 362 An instance of "sdfProperty" may be associated with some protocol 363 affordance to enable the application to obtain the state variable 364 and, optionally, modify the state variable. Additionally, some 365 protocols provide for in-time reporting of state changes. (These 366 three aspects are described by the qualities "readable", "writable", 367 and "observable" defined for an "sdfProperty".) 369 Definitions in "sdfProperty" groups look like definitions in 370 "sdfData" groups, however, they actually also declare a Property with 371 the given qualities to be potentially present in the containing 372 Object. (Qualities beyond those of "sdfData" definitions could be 373 defined for "sdfProperty" declarations but currently aren't; this 374 means that even Property qualities such as "readable" and "writable" 375 can be associated with definitions in "sdfData" groups, as well.) 376 For definitions in "sdfProperty" and "sdfData", SDF provides 377 qualities that can constrain the structure and values of data allowed 378 in an instance of these data, as well as qualities that associate 379 semantics to these data, for engineering units and unit scaling 380 information. 382 For the data definition within "sdfProperty" or "sdfData", SDF 383 borrows a number of elements proposed for the drafts 4 and 7 of the 384 json-schema.org "JSON Schema" format 385 [I-D.handrews-json-schema-validation], enhanced by qualities that are 386 specific to SDF. However, for the current version of SDF, data are 387 constrained to be of simple types (number, string, Boolean) and 388 arrays of these types. Syntax extension points are provided that can 389 be used to provide richer types in future versions of this 390 specification (possibly more of which can be borrowed from json- 391 schema.org). 393 Note that "sdfProperty" definitions (and "sdfData" definitions in 394 general) are not intended to constrain the formats of data used for 395 communication over network interfaces. Where needed, data 396 definitions for payloads of protocol messages are expected to be part 397 of the protocol binding. 399 2.2.3. sdfAction 401 The "sdfAction" group contains declarations of Actions, model 402 affordances that, when triggered, have more effect than just reading, 403 updating, or observing Thing state, often resulting in some outward 404 physical effect (which, itself, cannot be modeled in SDF). From a 405 programmer's perspective, they might be considered to be roughly 406 analogous to method calls. 408 Actions may have multiple data parameters; these are modeled as input 409 data and output data (using "sdfData" definitions, i.e., the same 410 entries as for "sdfProperty" declarations). Actions may be long- 411 running, that is to say that the effects may not take place 412 immediately as would be expected for an update to an "sdfPoperty"; 413 the effects may play out over time and emit action results. Actions 414 may also not always complete and may result in application errors, 415 such as an item blocking the closing of an automatic door. 417 Actions may have (or lack) qualities of idempotency and side-effect 418 safety. 420 The current version of SDF only provides data constraint modeling and 421 semantics for the input and output data of definitions in "sdfAction" 422 groups. Again, data definitions for payloads of protocol messages, 423 and detailed protocol settings for invoking the action, are expected 424 to be part of the protocol binding. 426 2.2.4. sdfEvent 428 The "sdfEvent" group contains declarations of Events, which can model 429 affordances that inform about "happenings" associated with an 430 instance of an Object; these may result in a signal being stored or 431 emitted as a result. 433 Note that there is a trivial overlap with sdfProperty state changes, 434 which may also be defined as events but are not generally required to 435 be defined as such. However, Events may exhibit certain ordering, 436 consistency, and reliability requirements that are expected to be 437 supported in various implementations of "sdfEvent" that do 438 distinguish sdfEvent from sdfProperty. For instance, while a state 439 change may simply be superseded by another state change, some events 440 are "precious" and need to be preserved even if further events 441 follow. 443 The current version of SDF only provides data constraint modeling and 444 semantics for the output data of Event affordances. Again, data 445 definitions for payloads of protocol messages, and detailed protocol 446 settings for invoking the action, are expected to be part of the 447 protocol binding. 449 2.2.5. sdfData 451 Definitions in "sdfData" groups are provided separately from those in 452 "sdfProperty" groups to enable common modeling patterns, data 453 constraints, and semantic anchor concepts to be factored out for data 454 items that make up "sdfProperty" items and serve as input and output 455 data for "sdfAction" and "sdfEvent" items. 457 It is a common use case for such a data definition to be shared 458 between an "sdfProperty" item and input or output parameters of an 459 "sdfAction" or output data provided by an "sdfEvent". "sdfData" 460 definitions also enable factoring out extended application data types 461 such as mode and machine state enumerations to be reused across 462 multiple definitions that have similar basic characteristics and 463 requirements. 465 2.2.6. sdfThing 467 Back at the top level, the "sdfThing" groups enables definition of 468 models for complex devices that will use one or more "sdfObject" 469 definitions. 471 A definition in an "sdfThing" group can refine the metadata of the 472 definitions it is composed from: other definitions in "sdfThing" 473 groups definitions in "sdfObject" groups. 475 2.2.7. sdfProduct 477 "sdfThing" has a derived class "sdfProduct", which can be used to 478 indicate a top level inventory item with a Stock-Keeping Unit (SKU) 479 identifier and other particular metadata. Structurally, there is no 480 difference between definitions in either group; semantically, a 481 definition in an "sdfProduct" group is intended to describe a class 482 of complete Things. 484 3. SDF structure 486 SDF definitions are contained in SDF files. One or more SDF files 487 can work together to provide the definitions and declarations that 488 are the payload of the SDF format. 490 A SDF definition file contains a single JSON map (JSON object). This 491 object has three sections: the information block, the namespaces 492 section, and the definitions section. 494 3.1. Information block 496 The information block contains generic meta data for the file itself 497 and all included definitions. 499 The keyword (map key) that defines an information block is "info". 500 Its value is a JSON map in turn, with a set of entries that represent 501 qualities that apply to the included definition. 503 Qualities of the information block are shown in Table 1. 505 +===========+========+==========+=================================+ 506 | Quality | Type | Required | Description | 507 +===========+========+==========+=================================+ 508 | title | string | yes | A short summary to be displayed | 509 | | | | in search results, etc. | 510 +-----------+--------+----------+---------------------------------+ 511 | version | string | yes | The incremental version of the | 512 | | | | definition, format TBD | 513 +-----------+--------+----------+---------------------------------+ 514 | copyright | string | yes | Link to text or embedded text | 515 | | | | containing a copyright notice | 516 +-----------+--------+----------+---------------------------------+ 517 | license | string | yes | Link to text or embedded text | 518 | | | | containing license terms | 519 +-----------+--------+----------+---------------------------------+ 521 Table 1: Qualities of the Information Block 523 While the format of the version string is marked as TBD, it is 524 intended to be lexicographically increasing over the life of a model: 525 a newer model always has a version string that string-compares higher 526 than all previous versions. This is easily achieved by following the 527 convention to start the version with an [RFC3339] "date-time" or, if 528 new versions are generated less frequently than once a day, just the 529 "full-date" (i.e., YYYY-MM-DD); in many cases, that will be all that 530 is needed (see Figure 1 for an example). 532 The license string is preferably either a URI that points to a web 533 page with an unambiguous definition of the license, or an [SPDX] 534 license identifier. (For models to be handled by the One Data Model 535 liaison group, this will typically be "BSD-3-Clause".) 537 3.2. Namespaces section 539 The namespaces section contains the namespace map and the 540 defaultNamespace setting. 542 The namespace map is a map from short names for URIs to the namespace 543 URIs themselves. 545 The defaultNamespace setting selects one of the entries in the 546 namespace map by giving its short name. The associated URI (value of 547 this entry) becomes the default namespace for the SDF definition 548 file. 550 +==================+========+==========+=======================+ 551 | Quality | Type | Required | Description | 552 +==================+========+==========+=======================+ 553 | namespace | map | no | Defines short names | 554 | | | | mapped to namespace | 555 | | | | URIs, to be used as | 556 | | | | identifier prefixes | 557 +------------------+--------+----------+-----------------------+ 558 | defaultNamespace | string | no | Identifies one of the | 559 | | | | prefixes in the | 560 | | | | namespace map to be | 561 | | | | used as a default in | 562 | | | | resolving identifiers | 563 +------------------+--------+----------+-----------------------+ 565 Table 2: Namespaces Section 567 The following example declares a set of namespaces and defines "cap" 568 as the default namespace. 570 "namespace": { 571 "cap": "https://example.com/capability/cap", 572 "zcl": "https://zcl.example.com/sdf" 573 }, 574 "defaultNamespace": "cap", 576 If no defaultNamespace setting is given, the SDF definition file does 577 not contribute to a global namespace. As the defaultNamespace is set 578 by giving a namespace short name, its presence requires a namespace 579 map that contains a mapping for that namespace short name. 581 If no namespace map is given, no short names for namespace URIs are 582 set up, and no defaultNamespace can be given. 584 3.3. Definitions section 586 The Definitions section contains one or more groups, each identified 587 by a Class Name Keyword (there can only be one group per keyword; the 588 actual grouping is just a shortcut and does not carry any specific 589 semantics). The value of each group is a JSON map (object), the keys 590 of which serve for naming the individual definitions in this group, 591 and the corresponding values provide the qualities (name-value pairs) 592 for the individual definition. 594 Each group may contain zero or more definitions. Each identifier 595 defined creates a new type and term in the target namespace. 596 Declarations have a scope of the current definition block. 598 A definition may in turn contain other definitions. Each definition 599 consists of the newly defined identifier and a set of key-value pairs 600 that represent the defined qualities and contained definitions. 602 An example for an Object definition is given in Figure 3: 604 "sdfObject": { 605 "foo": { 606 "sdfProperty": { 607 "bar": { 608 "type": "boolean" 609 } 610 } 611 } 612 } 614 Figure 3: Example Object definition 616 This example defines an Object "foo" that is defined in the default 617 namespace (full address: "#/sdfObject/foo"), containing a property 618 that can be addressed as "#/sdfObject/foo/sdfProperty/bar", with data 619 of type boolean. 621 Some of the definitions are also declarations: the definition of the 622 entry "bar" in the property "foo" means that each instance of a "foo" 623 can have zero or one instance of a "bar". Entries within 624 "sdfProperty", "sdfAction", and "sdfEvent", within "sdfObject" 625 entries, are declarations. Similarly, entries within an "sdfThing" 626 describe instances of "sdfObject" (or nested "sdfThing") that form 627 part of instances of the Thing. 629 4. Names and namespaces 631 SDF definition files may contribute to a global namespace, and may 632 reference elements from that global namespace. (An SDF definition 633 file that does not set a defaultNamespace does not contribute to a 634 global namespace.) 636 4.1. Structure 638 Global names look exactly like https:// URIs with attached fragment 639 identifiers. 641 There is no intention to require that these URIs can be dereferenced. 642 (However, as future versions of SDF might find a use for 643 dereferencing global names, the URI should be chosen in such a way 644 that this may become possible in the future.) 645 The absolute URI of a global name should be a URI as per Section 3 of 646 [RFC3986], with a scheme of "https" and a path ("hier-part" in 647 [RFC3986]). For the present version of this specification, the query 648 part should not be used (it might be used in later versions). 650 The fragment identifier is constructed as per Section 6 of [RFC6901]. 652 4.2. Contributing global names 654 The fragment identifier part of a global name defined in an SDF 655 definition file is constructed from a JSON pointer that selects the 656 element defined for this name in the SDF definition file. 658 The absolute URI part is a copy of the default namespace, i.e., the 659 default namespace is always the target namespace for a name for which 660 a definition is contributed. When emphasizing that name definitions 661 are contributed to the default namespace, we therefore also call it 662 the "target namespace" of the SDF definition file. 664 E.g., in Figure 1, definitions for the following global names are 665 contributed: 667 * https://example.com/capability/cap#/sdfObject/Switch 669 * https://example.com/capability/cap#/sdfObject/Switch/sdfProperty/ 670 value 672 * https://example.com/capability/cap#/sdfObject/Switch/sdfAction/on 674 * https://example.com/capability/cap#/sdfObject/Switch/sdfAction/off 676 Note the "#", which separates the base part from the fragment 677 identifier part. 679 4.3. Referencing global names 681 A name reference takes the form of the production "curie" in 682 [W3C.NOTE-curie-20101216] (note that this excludes the production 683 "safe-curie"), but also limiting the IRIs involved in that production 684 to URIs as per [RFC3986] and the prefixes to ASCII characters 685 [RFC0020]. 687 A name that is contributed by the current SDF definition file can be 688 referenced by a Same-Document Reference as per section 4.4 of 689 [RFC3986]. As there is little point in referencing the entire SDF 690 definition file, this will be a "#" followed by a JSON pointer. This 691 is the only kind of name reference that is possible in an SDF 692 definition file that does not set a default namespace. 694 Name references that point outside the current SDF definition file 695 need to contain curie prefixes. These then reference namespace 696 declarations in the namespaces section. 698 For example, if a namespace prefix is defined: 700 "namespace": { 701 "foo": "https://example.com/#" 702 } 704 Then this reference to that namespace: 706 { "sdfRef": "foo:/sdfData/temperatureData" } 708 references the global name: 710 "https://example.com/#/sdfData/temperatureData" 712 Note that there is no way to provide a URI scheme name in a curie, so 713 all references outside of the document need to go through the 714 namespace map. 716 Name references occur only in specific elements of the syntax of SDF: 718 * copying elements via sdfRef values 720 * pointing to elements via sdfRequired value elements or as 721 sdfInput/OutputData etc. 723 4.4. sdfRef 725 In a JSON map establishing a definition, the keyword "sdfRef" is used 726 to copy all of the qualities of the referenced definition, indicated 727 by the included name reference, into the newly formed definition. 728 (This can be compared to the processing of the "$ref" keyword in 729 [I-D.handrews-json-schema-validation].) 731 For example, this reference: 733 "temperatureProperty": { 734 "sdfRef": "#/sdfData/temperatureData" 735 } 737 creates a new definition "temperatureProperty" that contains all of 738 the qualities defined in the definition at /sdfData/temperatureData. 740 4.5. sdfRequired 742 The value of "sdfRequired" is an array of name references, each 743 pointing to one declaration the instantiation of which is declared 744 mandatory. 746 4.5.1. Optionality using the keyword "sdfRequired" 748 The keyword "sdfRequired" is provided to apply a constraint that 749 defines for which declarations corresponding data are mandatory in an 750 instance conforming the current definition. 752 The value of "sdfRequired" is an array of JSON pointers, each 753 indicating one declaration that is mandatory to be represented. 755 The example in Figure 4 shows two required elements in the sdfObject 756 definition for "temperatureWithAlarm", the sdfProperty 757 "temperatureData", and the sdfEvent "overTemperatureEvent". The 758 example also shows the use of JSON pointer with "sdfRef" to use a 759 pre-existing definition in this definition, for the "alarmType" data 760 (sdfOutputData) produced by the sdfEvent "overTemperatureEvent". 762 { 763 "sdfObject": { 764 "temperatureWithAlarm": { 765 "sdfRequired": [ 766 "#/sdfObject/temperatureWithAlarm/sdfData/temperatureData", 767 "#/sdfObject/temperatureWithAlarm/sdfEvent/overTemperatureEvent" 768 ], 769 "sdfData":{ 770 "temperatureData": { 771 "type": "number" 772 } 773 }, 774 "sdfEvent": { 775 "overTemperatureEvent": { 776 "sdfOutputData": { 777 "alarmType": { 778 "sdfRef": "cap:/sdfData/alarmTypes/quantityAlarms", 779 "const": "OverTemperatureAlarm" 780 }, 781 "temperature": { 782 "sdfRef": "#/sdfObject/temperatureWithAlarm/sdfData/temperatureData" 783 } 784 } 785 } 786 } 787 } 788 } 789 } 791 Figure 4: Using sdfRequired 793 4.6. Common Qualities 795 Definitions in SDF share a number of qualities that provide metadata 796 for them. These are listed in Table 3. None of these qualities are 797 required or have default values that are assumed if the quality is 798 absent. If a label is required for an application and no label is 799 given, the last part ("reference-token", Section 3 of [RFC6901]) of 800 the JSON pointer to the definition can be used. 802 +=============+==============+===================================+ 803 | Quality | Type | Description | 804 +=============+==============+===================================+ 805 | description | text | long text (no constraints) | 806 +-------------+--------------+-----------------------------------+ 807 | label | text | short text (no constraints) | 808 +-------------+--------------+-----------------------------------+ 809 | $comment | text | source code comments only, no | 810 | | | semantics | 811 +-------------+--------------+-----------------------------------+ 812 | sdfRef | sdf-pointer | (see Section 4.4) | 813 +-------------+--------------+-----------------------------------+ 814 | sdfRequired | pointer-list | (see Section 4.5, applies to | 815 | | | qualities of properties, of data) | 816 +-------------+--------------+-----------------------------------+ 818 Table 3: Common Qualities 820 4.7. Data Qualities 822 Data qualities are used in "sdfData" and "sdfProperty" definitions. 824 Table 4 lists data qualities borrowed from 825 [I-D.handrews-json-schema-validation]; the intention is that these 826 qualities retain their semantics from the versions of the json- 827 schema.org proposal they were imported from. 829 Table 5 lists data qualities defined specifically for the present 830 specification. 832 The term "allowed types" stands for primitive JSON types as well as 833 homogeneous arrays of numbers, text, or Booleans. (This list might 834 be extended in a future version of SDF.) An "allowed value" is a 835 value allowed for one of these types. 837 +================+==========+=======================================+ 838 |Quality |Type |Description | 839 +================+==========+=======================================+ 840 |type |"number" /|JSON data type | 841 | |"string" /| | 842 | |"boolean" | | 843 | |/ | | 844 | |"integer" | | 845 | |/ "array" | | 846 +----------------+----------+---------------------------------------+ 847 |enum |array of |enumeration constraint | 848 | |allowed | | 849 | |values | | 850 +----------------+----------+---------------------------------------+ 851 |const |allowed |specifies a constant value for a data | 852 | |value |item or property | 853 +----------------+----------+---------------------------------------+ 854 |default |allowed |specifies the default value for | 855 | |value |initialization | 856 +----------------+----------+---------------------------------------+ 857 |minimum |number |lower limit of value | 858 +----------------+----------+---------------------------------------+ 859 |maximum |number |upper limit of value | 860 +----------------+----------+---------------------------------------+ 861 |exclusiveMinimum|number or |lower limit of value | 862 | |boolean | | 863 | |(jso draft| | 864 | |7/4) | | 865 +----------------+----------+---------------------------------------+ 866 |exclusiveMaximum|number or |lower limit of value | 867 | |boolean | | 868 | |(jso draft| | 869 | |7/4) | | 870 +----------------+----------+---------------------------------------+ 871 |multipleOf |number |resolution of the number [NEEDED?] | 872 +----------------+----------+---------------------------------------+ 873 |minLength |integer |shortest length string in octets | 874 +----------------+----------+---------------------------------------+ 875 |maxLength |integer |longest length string in octets | 876 +----------------+----------+---------------------------------------+ 877 |pattern |string |regular expression to constrain a | 878 | | |string pattern | 879 +----------------+----------+---------------------------------------+ 880 |format |"date- |JSON Schema formats as per | 881 | |time" / |[I-D.handrews-json-schema-validation], | 882 | |"date" / |Section 7.3 | 883 | |"time" / | | 884 | |"uri" / | | 885 | |"uri- | | 886 | |reference"| | 887 | |/ "uuid" | | 888 +----------------+----------+---------------------------------------+ 889 |minItems |number |Minimum number of items in array | 890 +----------------+----------+---------------------------------------+ 891 |maxItems |number |Maximum number of items in array | 892 +----------------+----------+---------------------------------------+ 893 |uniqueItems |boolean |if true, requires items to be all | 894 | | |different | 895 +----------------+----------+---------------------------------------+ 896 |items |(subset of|constraints on array items | 897 | |common/ | | 898 | |data | | 899 | |qualities;| | 900 | |see | | 901 | |Appendix A| | 902 +----------------+----------+---------------------------------------+ 904 Table 4: Qualities of sdfProperty and sdfData borrowed from json- 905 schema.org 907 +===============+===============+=========================+=========+ 908 | Quality | Type | Description | Default | 909 +===============+===============+=========================+=========+ 910 | (common) | | Section 4.6 | | 911 +---------------+---------------+-------------------------+---------+ 912 | units | string | SenML unit name as | N/A | 913 | | | per [IANA.senml], | | 914 | | | subregistry SenML | | 915 | | | Units | | 916 +---------------+---------------+-------------------------+---------+ 917 | scaleMinimum | number | lower limit of | N/A | 918 | | | value in units | | 919 +---------------+---------------+-------------------------+---------+ 920 | scaleMaximum | number | upper limit of | N/A | 921 | | | value in units | | 922 +---------------+---------------+-------------------------+---------+ 923 | readable | boolean | Reads are allowed | true | 924 +---------------+---------------+-------------------------+---------+ 925 | writable | boolean | Writes are allowed | true | 926 +---------------+---------------+-------------------------+---------+ 927 | observable | boolean | flag to indicate | true | 928 | | | asynchronous | | 929 | | | notification is | | 930 | | | available | | 931 +---------------+---------------+-------------------------+---------+ 932 | nullable | boolean | indicates a null | true | 933 | | | value is available | | 934 | | | for this type | | 935 +---------------+---------------+-------------------------+---------+ 936 | contentFormat | string | content type (IANA | N/A | 937 | | | media type string | | 938 | | | plus parameters), | | 939 | | | encoding | | 940 +---------------+---------------+-------------------------+---------+ 941 | subtype | "byte-string" | subtype | N/A | 942 | | / "unix-time" | enumeration | | 943 +---------------+---------------+-------------------------+---------+ 945 Table 5: SDF-defined Qualities of sdfProperty and sdfData 947 5. Keywords for definition groups 949 The following SDF keywords are used to create definition groups in 950 the target namespace. All these definitions share some common 951 qualities as discussed in Section 4.6. 953 5.1. sdfObject 955 The sdfObject keyword denotes a group of zero or more Object 956 definitions. Object definitions may contain or include definitions 957 of Properties, Actions, Events declared for the object, as well as 958 data types (sdfData group) to be used in this or other Objects. 960 The qualities of an sdfObject include the common qualities, 961 additional qualities are shown in Table 6. None of these qualities 962 are required or have default values that are assumed if the quality 963 is absent. 965 +=============+==========+==========================================+ 966 | Quality | Type | Description | 967 +=============+==========+==========================================+ 968 | (common) | | Section 4.6 | 969 +-------------+----------+------------------------------------------+ 970 | sdfProperty | property | zero or more named property | 971 | | | definitions for this object | 972 +-------------+----------+------------------------------------------+ 973 | sdfAction | action | zero or more named action | 974 | | | definitions for this object | 975 +-------------+----------+------------------------------------------+ 976 | sdfEvent | event | zero or more named event | 977 | | | definitions for this object | 978 +-------------+----------+------------------------------------------+ 979 | sdfData | data | zero or more named data | 980 | | | type definitions that might | 981 | | | be used in the above | 982 +-------------+----------+------------------------------------------+ 984 Table 6: Qualities of sdfObject 986 5.2. sdfProperty 988 The sdfProperty keyword denotes a group of zero or more Property 989 definitions. 991 Properties are used to model elements of state. 993 The qualities of a Property definition include the common qualities 994 and the data qualities, see Section 4.7. 996 5.3. sdfAction 998 The sdfAction keyword denotes a group of zero or more Action 999 definitions. 1001 Actions are used to model commands and methods which are invoked. 1002 Actions have parameter data that are supplied upon invocation. 1004 The qualities of an Action definition include the common qualities, 1005 additional qualities are shown in Table 7. 1007 +======================+=======+================================+ 1008 | Quality | Type | Description | 1009 +======================+=======+================================+ 1010 | (common) | | Section 4.6 | 1011 +----------------------+-------+--------------------------------+ 1012 | sdfInputData | array | Array of JSON Pointers to Data | 1013 | | | items in the input data for an | 1014 | | | Action | 1015 +----------------------+-------+--------------------------------+ 1016 | sdfRequiredInputData | array | Array of JSON Pointers to | 1017 | | | mandatory Data items in the | 1018 | | | input data for an Action | 1019 +----------------------+-------+--------------------------------+ 1020 | sdfOutputData | array | Array of JSON Pointers to Data | 1021 | | | items in the Output data for | 1022 | | | an Action (mandatory items are | 1023 | | | listed under sdfRequired) | 1024 +----------------------+-------+--------------------------------+ 1025 | sdfData | data | zero or more named data type | 1026 | | | definitions that might be used | 1027 | | | in the above | 1028 +----------------------+-------+--------------------------------+ 1030 Table 7: Qualities of sdfAction 1032 "sdfInputData", as refined by "sdfRequiredInputData", define the 1033 input data of the action. "sdfOutputData", as refined by 1034 "sdfRequired," (a quality defined in Table 3) define the output data 1035 of the action. 1037 5.4. sdfEvent 1039 The sdfEvent keyword denotes zero or more Event definitions. 1041 Events are used to model asynchronous occurrences that may be 1042 communicated proactively. Events have data elements which are 1043 communicated upon the occurrence of the event. 1045 The qualities of sdfEvent include the common qualities, additional 1046 qualities are shown in Table 8. 1048 +===============+=======+==========================================+ 1049 | Quality | Type | Description | 1050 +===============+=======+==========================================+ 1051 | (common) | | Section 4.6 | 1052 +---------------+-------+------------------------------------------+ 1053 | sdfOutputData | array | Array of JSON Pointers to Data items in | 1054 | | | the Output data for an Action (mandatory | 1055 | | | items are listed under sdfRequired) | 1056 +---------------+-------+------------------------------------------+ 1057 | sdfData | data | zero or more named data type definitions | 1058 | | | that might be used in the above | 1059 +---------------+-------+------------------------------------------+ 1061 Table 8: Qualities of sdfEvent 1063 "sdfOutputData", as refined by "sdfRequired" (a quality defined in 1064 Table 3), define the output data of the action. 1066 5.5. sdfData 1068 The sdfData keyword denotes a group of zero or more Data type 1069 definitions. 1071 An sdfData definition provides a semantic identifier for a data item 1072 and describes the constraints on the defined data item. 1074 sdfData is used for Action parameters, for Event output data, and for 1075 reusable constraints in Property definitions. 1077 The qualities of sdfData include the common qualities and the data 1078 qualities, see Section 4.7. 1080 6. High Level Composition 1082 The requirements for high level composition include the following: 1084 * The ability to represent products, standardized product types, and 1085 modular products while maintaining the atomicity of Objects. 1087 * The ability to compose a reusable definition block from Objects, 1088 for example a single plug unit of an outlet strip with on/off 1089 control, energy monitor, and optional dimmer objects, while 1090 retaining the atomicity of the individual objects. 1092 * The ability to compose Objects and other definition blocks into a 1093 higher level thing that represents a product, while retaining the 1094 atomicity of objects. 1096 * The ability to enrich and refine a base definition to have 1097 product-specific qualities and quality values, e.g. unit, range, 1098 and scale settings. 1100 * The ability to reference items in one part of a complex definition 1101 from another part of the same definition, for example to summarize 1102 the energy readings from all plugs in an outlet strip. 1104 6.1. Paths in the model namespaces 1106 The model namespace is organized according to terms that are defined 1107 in the definition files that are present in the namespace. For 1108 example, definitions that originate from an organization or vendor 1109 are expected to be in a namespace that is specific to that 1110 organization or vendor. There is expected to be an SDF namespace for 1111 common SDF definitions used in OneDM. 1113 The structure of a path in a namespace is defined by the JSON 1114 Pointers to the definitions in the files in that namespace. For 1115 example, if there is a file defining an object "Switch" with an 1116 action "on", then the reference to the action would be 1117 "ns:/sdfObject/Switch/sdfAction/on" where ns is the namespace prefix 1118 (short name for the namespace). 1120 6.2. Modular Composition 1122 Modular composition of definitions enables an existing definition 1123 (could be in the same file or another file) to become part of a new 1124 definition by including a reference to the existing definition within 1125 the model namespace. 1127 6.2.1. Use of the "sdfRef" keyword to re-use a definition 1129 An existing definition may be used as a template for a new 1130 definition, that is, a new definition is created in the target 1131 namespace which uses the defined qualities of some existing 1132 definition. This pattern will use the keyword "sdfRef" as a quality 1133 of a new definition with a value consisting of a reference to the 1134 existing definition that is to be used as a template. Optionally, 1135 new qualities may be added and values of optional qualities and 1136 quality values may be defined. 1138 ISSUE: Do we want to enable qualities from the source definition to 1139 be overridden in future versions? The above only says "added". 1140 (Yes, we do want to enable overriding, but need to warn specifiers 1141 not to use this in a way that contradicts the referenced semantics.) 1143 "sdfData": 1144 "length" : { 1145 "type": "number", 1146 "minimum": 0, 1147 "units": "m" 1148 "description": "There can be no negative lengths." 1149 } 1150 ... 1151 "cable-length" : { 1152 "sdfRef": "#/sdfData/length" 1153 "minimum": 0.05, 1154 "description": "Cables must be at least 5 cm." 1155 } 1157 6.3. sdfThing 1159 An sdfThing is a set of declarations and qualities that may be part 1160 of a more complex model. For example, the object declarations that 1161 make up the definition of a single socket of an outlet strip could be 1162 encapsulated in an sdfThing, and the socket-thing itself could be 1163 used in a declaration in the sdfThing definition for the outlet 1164 strip. 1166 sdfThing definitions carry semantic meaning, such as a defined 1167 refrigerator compartment and a defined freezer compartment, making up 1168 a combination refrigerator-freezer product. 1170 An sdfThing may be composed of sdfObjects and other sdfThings. 1172 The qualities of sdfThing are shown in Table 9. 1174 +===========+========+=============+ 1175 | Quality | Type | Description | 1176 +===========+========+=============+ 1177 | (common) | | Section 4.6 | 1178 +-----------+--------+-------------+ 1179 | sdfThing | thing | | 1180 +-----------+--------+-------------+ 1181 | sdfObject | object | | 1182 +-----------+--------+-------------+ 1184 Table 9: Qualities of sdfThing 1185 and sdfProduct 1187 6.4. sdfProduct 1189 An sdfProduct provides the level of abstraction for representing a 1190 unique product or a profile for a standardized type of product, for 1191 example a "device type" definition with required minimum 1192 functionality. 1194 Products may be composed of Objects and Things at the high level, and 1195 may include their own definitions of Properties, Actions, and Events 1196 that can be used to extend or complete the included Object 1197 definitions. 1199 Product definitions may set optional defaults and constant values for 1200 specific use cases, for example units, range, and scale settings for 1201 properties, or available parameters for Actions. 1203 The qualities of sdfProduct are the same as for sdfThing and are 1204 shown in Table 9. 1206 7. References 1208 7.1. Normative References 1210 [I-D.handrews-json-schema-validation] 1211 Wright, A., Andrews, H., and B. Hutton, "JSON Schema 1212 Validation: A Vocabulary for Structural Validation of 1213 JSON", Work in Progress, Internet-Draft, draft-handrews- 1214 json-schema-validation-02, 17 September 2019, 1215 . 1218 [IANA.senml] 1219 IANA, "Sensor Measurement Lists (SenML)", 1220 . 1222 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 1223 RFC 20, DOI 10.17487/RFC0020, October 1969, 1224 . 1226 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1227 Requirement Levels", BCP 14, RFC 2119, 1228 DOI 10.17487/RFC2119, March 1997, 1229 . 1231 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1232 Resource Identifier (URI): Generic Syntax", STD 66, 1233 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1234 . 1236 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 1237 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 1238 DOI 10.17487/RFC6901, April 2013, 1239 . 1241 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1242 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1243 May 2017, . 1245 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1246 Definition Language (CDDL): A Notational Convention to 1247 Express Concise Binary Object Representation (CBOR) and 1248 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1249 June 2019, . 1251 [SPDX] "SPDX License List", . 1253 [W3C.NOTE-curie-20101216] 1254 Birbeck, M. and S. McCarron, "CURIE Syntax 1.0", World 1255 Wide Web Consortium NOTE NOTE-curie-20101216, 16 December 1256 2010, . 1258 7.2. Informative References 1260 [I-D.irtf-t2trg-rest-iot] 1261 Keranen, A., Kovatsch, M., and K. Hartke, "RESTful Design 1262 for Internet of Things Systems", Work in Progress, 1263 Internet-Draft, draft-irtf-t2trg-rest-iot-06, 11 May 2020, 1264 . 1267 [OCF] "OCF Resource Type Specification", 1268 . 1271 [OMA] "OMA LightweightM2M (LwM2M) Object and Resource Registry", 1272 . 1275 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1276 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1277 . 1279 [ZCL] "The ZigBee Cluster Library", Zigbee Wireless 1280 Networking pp. 239-271, 1281 DOI 10.1016/b978-0-7506-8597-9.00006-9, 2008, 1282 . 1284 Appendix A. Formal Syntax of SDF 1286 This appendix describes the syntax of SDF using CDDL [RFC8610]. Note 1287 that this appendix was derived from Ari Keranen's "alt-schema" and 1288 Michael Koster's "schema", with a view of covering the syntax that is 1289 currently in use at the One Data Model "playground" repository. 1291 This appendix shows the framework syntax only, i.e., a syntax with 1292 liberal extension points. Since this syntax is nearly useless in 1293 finding typos in an SDF specification, a second syntax, the 1294 validation syntax, is defined that does not include the extension 1295 points. The validation syntax can be generated from the framework 1296 syntax by leaving out all lines containing the string "EXTENSION- 1297 POINT"; as this is trivial, the result is not shown here. 1299 start = sdf-syntax 1301 sdf-syntax = { 1302 info: sdfinfo ; don't *require* this in flexible syntax, though 1303 ? namespace: named 1304 ? defaultNamespace: text 1305 ? sdfThing: named ; Thing is a composition of objects that work together in some way 1306 ? sdfProduct: named ; Product is a composition of things and objects that can model a SKU-level instance of a product 1307 ? sdfObject: named ; Object is a set of Properties, Actions, and Events that together perform a particular function 1308 ? sdfProperty: named ; Property represents the state of an instance of an object 1309 ? sdfAction: named ; Action is a directive to invoke an application layer verb associated with an object 1310 ? sdfEvent: named ; Event represents an occurence of something associated with an object 1311 ? 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 1312 EXTENSION-POINT 1313 } 1315 sdfinfo = { 1316 title: text 1317 version: text 1318 copyright: text 1319 license: text 1320 EXTENSION-POINT 1321 } 1323 ; Shortcut for a map that gives names to instances of X (has text keys and values of type X) 1324 named = { * text => X } 1326 EXTENSION-POINT = ( * text => any ) ; only used in framework syntax 1328 sdf-pointer = text ; .regexp curie-regexp -- TO DO! 1329 pointer-list = [* sdf-pointer] ; ISSUE: no point in having an empty list, no? but used for sdfRequired in odmobject-multiple_axis_joystick.sdf.json 1331 commonqualities = ( 1332 ? description: text ; long text (no constraints) 1333 ? label: text ; short text (no constraints); default to key 1334 ? $comment: text ; source code comments only, no semantics 1335 ? sdfRef: sdf-pointer 1336 ? sdfRequired: pointer-list ; applies to qualities of properties, of data 1337 ) 1339 ; for building hierarchy 1340 thingqualities = { 1341 commonqualities, 1342 ? sdfObject: named 1343 ? sdfThing: named 1344 EXTENSION-POINT 1345 } 1347 productqualities = thingqualities ; ISSUE: get rid of sdfProduct? 1349 ; for single objects 1350 objectqualities = { 1351 commonqualities, 1352 ? sdfProperty: named 1353 ? sdfAction: named 1354 ? sdfEvent: named 1355 ? sdfData: named 1356 EXTENSION-POINT 1357 } 1359 propertyqualities = dataqualities ; the definitions in sdfData are declarations in sdfProperty 1361 actionqualities = { 1362 commonqualities, 1363 ? sdfInputData: pointer-list ; sdfRequiredInputData applies here (a bit redundant) 1364 ? sdfRequiredInputData: pointer-list 1365 ? sdfOutputData: pointer-list ; sdfRequired applies here 1366 ? sdfData: named ; zero or more named data type definitions that might be used in the above 1367 EXTENSION-POINT 1368 } 1370 eventqualities = { 1371 commonqualities 1372 ? sdfOutputData: pointer-list ; sdfRequired applies here 1373 ? sdfData: named ; zero or more named data type definitions that might be used in the above 1374 EXTENSION-POINT 1375 } 1377 dataqualities = { ; also propertyqualities 1378 commonqualities, 1379 jsonschema, 1380 ? units: text 1381 ? scaleMinimum: number 1382 ? scaleMaximum: number 1383 ? observable: bool 1384 ? readable: bool 1385 ? writable: bool 1386 ? nullable: bool 1387 ? subtype: "byte-string" / "unix-time" 1388 / text ; EXTENSION-POINT 1389 ? contentFormat: text 1390 EXTENSION-POINT 1391 } 1393 allowed-types = number / text / bool / null 1394 / [* number] / [* text] / [* bool] 1395 / any ; EXTENSION-POINT 1397 jsonschema = ( 1398 ? type: "number" / "string" / "boolean" / "integer" / "array" ; / "object" 1399 / text ; EXTENSION-POINT 1400 ? enum: [+ allowed-types] ; should validate against type 1401 ? const: allowed-types 1402 ? default: allowed-types 1403 ; number/integer constraints 1404 ? minimum: number 1405 ? maximum: number 1406 ? exclusiveMinimum: bool / number ; jso draft 4/7 1407 ? exclusiveMaximum: bool / number ; jso draft 4/7 1408 ? multipleOf: number ; ISSUE: Do we need this? 1409 ; text string constraints 1410 ? minLength: number 1411 ? maxLength: number 1412 ? pattern: text ; regexp 1413 ? format: "date-time" / "date" / "time" 1414 / "uri" / "uri-reference" / "uuid" 1415 / text ; EXTENSION-POINT 1416 ; expand on demand 1417 ; array constraints 1418 ? minItems: number 1419 ? maxItems: number 1420 ? uniqueItems: bool 1421 ? items: { ;;; ultimately, this will be mostly recursive, but, for now 1422 ;;; let's find out what we actually need 1423 ? sdfRef: sdf-pointer ; import limited to the subset that we allow here... 1424 ? description: text ; long text (no constraints) 1425 ? $comment: text ; source code comments only, no semantics 1426 ; commonqualities, ; -- ISSUE: should leave this out for non-complex data types, but need the above three 1427 ? type: "number" / "string" / "boolean" / "integer" ; no "array" / "object" 1428 / text ; EXTENSION-POINT 1429 ; jso subset 1430 ? minimum: number 1431 ? maximum: number 1432 ? enum: [+ any] 1433 ? format: text 1434 ? minLength: number 1435 ? maxLength: number 1436 EXTENSION-POINT 1437 } 1438 ) 1440 Appendix B. json-schema.org Rendition of SDF Syntax 1442 This appendix describes the syntax of SDF defined in Appendix A, but 1443 using a version of the description techniques advertised on json- 1444 schema.org [I-D.handrews-json-schema-validation]. 1446 The appendix shows both the validation and the framework syntax. 1447 Since most of the lines are the same between these two files, those 1448 lines are shown only once, with a leading space, in the form of a 1449 unified diff. Lines leading with a "-" are part of the validation 1450 syntax, and lines leading with a "+" are part of the framework 1451 syntax. 1453 { 1454 - "title": "sdf-validation.cddl", 1455 + "title": "sdf-framework.cddl", 1456 "$schema": "http://json-schema.org/draft-07/schema#", 1457 "$ref": "#/definitions/sdf-syntax", 1458 "definitions": { 1459 "sdf-syntax": { 1460 "type": "object", 1461 "required": [ 1462 "info" 1463 ], 1464 "properties": { 1465 "info": { 1466 "$ref": "#/definitions/sdfinfo" 1467 }, 1468 "namespace": { 1469 "type": "object", 1470 "additionalProperties": { 1471 "type": "string" 1472 } 1473 }, 1474 "defaultNamespace": { 1475 "type": "string" 1477 }, 1478 "sdfThing": { 1479 "type": "object", 1480 "additionalProperties": { 1481 "$ref": "#/definitions/thingqualities" 1482 } 1483 }, 1484 "sdfProduct": { 1485 "type": "object", 1486 "additionalProperties": { 1487 "$ref": "#/definitions/productqualities" 1488 } 1489 }, 1490 "sdfObject": { 1491 "type": "object", 1492 "additionalProperties": { 1493 "$ref": "#/definitions/objectqualities" 1494 } 1495 }, 1496 "sdfProperty": { 1497 "type": "object", 1498 "additionalProperties": { 1499 "$ref": "#/definitions/propertyqualities" 1500 } 1501 }, 1502 "sdfAction": { 1503 "type": "object", 1504 "additionalProperties": { 1505 "$ref": "#/definitions/actionqualities" 1506 } 1507 }, 1508 "sdfEvent": { 1509 "type": "object", 1510 "additionalProperties": { 1511 "$ref": "#/definitions/eventqualities" 1512 } 1513 }, 1514 "sdfData": { 1515 "type": "object", 1516 "additionalProperties": { 1517 "$ref": "#/definitions/dataqualities" 1518 } 1519 } 1520 }, 1521 - "additionalProperties": false 1522 + "additionalProperties": { 1523 + } 1524 }, 1525 "sdfinfo": { 1526 "type": "object", 1527 "required": [ 1528 "title", 1529 "version", 1530 "copyright", 1531 "license" 1532 ], 1533 "properties": { 1534 "title": { 1535 "type": "string" 1536 }, 1537 "version": { 1538 "type": "string" 1539 }, 1540 "copyright": { 1541 "type": "string" 1542 }, 1543 "license": { 1544 "type": "string" 1545 } 1546 }, 1547 - "additionalProperties": false 1548 + "additionalProperties": { 1549 + } 1550 + }, 1551 + "EXTENSION-POINT": { 1552 + "type": "object", 1553 + "additionalProperties": { 1554 + } 1555 }, 1556 "thingqualities": { 1557 "type": "object", 1558 "properties": { 1559 "sdfObject": { 1560 "type": "object", 1561 "additionalProperties": { 1562 "$ref": "#/definitions/objectqualities" 1563 } 1564 }, 1565 "sdfThing": { 1566 "type": "object", 1567 "additionalProperties": { 1568 "$ref": "#/definitions/thingqualities" 1569 } 1570 }, 1571 "description": { 1572 "type": "string" 1574 }, 1575 "label": { 1576 "type": "string" 1577 }, 1578 "$comment": { 1579 "type": "string" 1580 }, 1581 "sdfRef": { 1582 "$ref": "#/definitions/sdf-pointer" 1583 }, 1584 "sdfRequired": { 1585 "$ref": "#/definitions/pointer-list" 1586 } 1587 }, 1588 - "additionalProperties": false 1589 + "additionalProperties": { 1590 + } 1591 }, 1592 "commonqualities": { 1593 "type": "object", 1594 "properties": { 1595 "description": { 1596 "type": "string" 1597 }, 1598 "label": { 1599 "type": "string" 1600 }, 1601 "$comment": { 1602 "type": "string" 1603 }, 1604 "sdfRef": { 1605 "$ref": "#/definitions/sdf-pointer" 1606 }, 1607 "sdfRequired": { 1608 "$ref": "#/definitions/pointer-list" 1609 } 1610 }, 1611 "additionalProperties": false 1612 }, 1613 "sdf-pointer": { 1614 "type": "string" 1615 }, 1616 "pointer-list": { 1617 "type": "array", 1618 "items": { 1619 "$ref": "#/definitions/sdf-pointer" 1620 } 1621 }, 1622 "objectqualities": { 1623 "type": "object", 1624 "properties": { 1625 "sdfProperty": { 1626 "type": "object", 1627 "additionalProperties": { 1628 "$ref": "#/definitions/propertyqualities" 1629 } 1630 }, 1631 "sdfAction": { 1632 "type": "object", 1633 "additionalProperties": { 1634 "$ref": "#/definitions/actionqualities" 1635 } 1636 }, 1637 "sdfEvent": { 1638 "type": "object", 1639 "additionalProperties": { 1640 "$ref": "#/definitions/eventqualities" 1641 } 1642 }, 1643 "sdfData": { 1644 "type": "object", 1645 "additionalProperties": { 1646 "$ref": "#/definitions/dataqualities" 1647 } 1648 }, 1649 "description": { 1650 "type": "string" 1651 }, 1652 "label": { 1653 "type": "string" 1654 }, 1655 "$comment": { 1656 "type": "string" 1657 }, 1658 "sdfRef": { 1659 "$ref": "#/definitions/sdf-pointer" 1660 }, 1661 "sdfRequired": { 1662 "$ref": "#/definitions/pointer-list" 1663 } 1664 }, 1665 - "additionalProperties": false 1666 + "additionalProperties": { 1667 + } 1668 }, 1669 "propertyqualities": { 1670 "$ref": "#/definitions/dataqualities" 1671 }, 1672 "dataqualities": { 1673 "type": "object", 1674 "properties": { 1675 "units": { 1676 "type": "string" 1677 }, 1678 "scaleMinimum": { 1679 "type": "number" 1680 }, 1681 "scaleMaximum": { 1682 "type": "number" 1683 }, 1684 "observable": { 1685 "type": "boolean" 1686 }, 1687 "readable": { 1688 "type": "boolean" 1689 }, 1690 "writable": { 1691 "type": "boolean" 1692 }, 1693 "nullable": { 1694 "type": "boolean" 1695 }, 1696 "subtype": { 1697 - "type": "string", 1698 - "enum": [ 1699 - "byte-string", 1700 - "unix-time" 1701 + "anyOf": [ 1702 + { 1703 + "type": "string", 1704 + "const": "byte-string" 1705 + }, 1706 + { 1707 + "type": "string", 1708 + "const": "unix-time" 1709 + }, 1710 + { 1711 + "type": "string" 1712 + } 1713 ] 1714 }, 1715 "contentFormat": { 1716 "type": "string" 1717 }, 1718 "type": { 1719 - "type": "string", 1720 - "enum": [ 1721 - "number", 1722 - "string", 1723 - "boolean", 1724 - "integer", 1725 - "array" 1726 + "anyOf": [ 1727 + { 1728 + "type": "string", 1729 + "const": "number" 1730 + }, 1731 + { 1732 + "type": "string", 1733 + "const": "string" 1734 + }, 1735 + { 1736 + "type": "string", 1737 + "const": "boolean" 1738 + }, 1739 + { 1740 + "type": "string", 1741 + "const": "integer" 1742 + }, 1743 + { 1744 + "type": "string", 1745 + "const": "array" 1746 + }, 1747 + { 1748 + "type": "string" 1749 + } 1750 ] 1751 }, 1752 "enum": { 1753 "type": "array", 1754 "items": { 1755 "$ref": "#/definitions/allowed-types" 1756 }, 1757 "minItems": 1 1758 }, 1759 "const": { 1760 "$ref": "#/definitions/allowed-types" 1761 }, 1762 "default": { 1763 "$ref": "#/definitions/allowed-types" 1764 }, 1765 "minimum": { 1766 "type": "number" 1767 }, 1768 "maximum": { 1769 "type": "number" 1770 }, 1771 "exclusiveMinimum": { 1772 "anyOf": [ 1773 { 1774 "type": "boolean" 1775 }, 1776 { 1777 "type": "number" 1778 } 1779 ] 1780 }, 1781 "exclusiveMaximum": { 1782 "anyOf": [ 1783 { 1784 "type": "boolean" 1785 }, 1786 { 1787 "type": "number" 1788 } 1789 ] 1790 }, 1791 "multipleOf": { 1792 "type": "number" 1793 }, 1794 "minLength": { 1795 "type": "number" 1796 }, 1797 "maxLength": { 1798 "type": "number" 1799 }, 1800 "pattern": { 1801 "type": "string" 1802 }, 1803 "format": { 1804 - "type": "string", 1805 - "enum": [ 1806 - "date-time", 1807 - "date", 1808 - "time", 1809 - "uri", 1810 - "uri-reference", 1811 - "uuid" 1812 + "anyOf": [ 1813 + { 1814 + "type": "string", 1815 + "const": "date-time" 1816 + }, 1817 + { 1818 + "type": "string", 1819 + "const": "date" 1820 + }, 1821 + { 1822 + "type": "string", 1823 + "const": "time" 1824 + }, 1825 + { 1826 + "type": "string", 1827 + "const": "uri" 1828 + }, 1829 + { 1830 + "type": "string", 1831 + "const": "uri-reference" 1832 + }, 1833 + { 1834 + "type": "string", 1835 + "const": "uuid" 1836 + }, 1837 + { 1838 + "type": "string" 1839 + } 1840 ] 1841 }, 1842 "minItems": { 1843 "type": "number" 1844 }, 1845 "maxItems": { 1846 "type": "number" 1847 }, 1848 "uniqueItems": { 1849 "type": "boolean" 1850 }, 1851 "items": { 1852 "type": "object", 1853 "properties": { 1854 "sdfRef": { 1855 "$ref": "#/definitions/sdf-pointer" 1856 }, 1857 "description": { 1858 "type": "string" 1859 }, 1860 "$comment": { 1861 "type": "string" 1863 }, 1864 "type": { 1865 - "type": "string", 1866 - "enum": [ 1867 - "number", 1868 - "string", 1869 - "boolean", 1870 - "integer" 1871 + "anyOf": [ 1872 + { 1873 + "type": "string", 1874 + "const": "number" 1875 + }, 1876 + { 1877 + "type": "string", 1878 + "const": "string" 1879 + }, 1880 + { 1881 + "type": "string", 1882 + "const": "boolean" 1883 + }, 1884 + { 1885 + "type": "string", 1886 + "const": "integer" 1887 + }, 1888 + { 1889 + "type": "string" 1890 + } 1891 ] 1892 }, 1893 "minimum": { 1894 "type": "number" 1895 }, 1896 "maximum": { 1897 "type": "number" 1898 }, 1899 "enum": { 1900 "type": "array", 1901 "minItems": 1 1902 }, 1903 "format": { 1904 "type": "string" 1905 }, 1906 "minLength": { 1907 "type": "number" 1908 }, 1909 "maxLength": { 1910 "type": "number" 1912 } 1913 }, 1914 - "additionalProperties": false 1915 + "additionalProperties": { 1916 + } 1917 }, 1918 "description": { 1919 "type": "string" 1920 }, 1921 "label": { 1922 "type": "string" 1923 }, 1924 "$comment": { 1925 "type": "string" 1926 }, 1927 "sdfRef": { 1928 "$ref": "#/definitions/sdf-pointer" 1929 }, 1930 "sdfRequired": { 1931 "$ref": "#/definitions/pointer-list" 1932 } 1933 }, 1934 - "additionalProperties": false 1935 + "additionalProperties": { 1936 + } 1937 }, 1938 "jsonschema": { 1939 "type": "object", 1940 "properties": { 1941 "type": { 1942 - "type": "string", 1943 - "enum": [ 1944 - "number", 1945 - "string", 1946 - "boolean", 1947 - "integer", 1948 - "array" 1949 + "anyOf": [ 1950 + { 1951 + "type": "string", 1952 + "const": "number" 1953 + }, 1954 + { 1955 + "type": "string", 1956 + "const": "string" 1957 + }, 1958 + { 1959 + "type": "string", 1960 + "const": "boolean" 1961 + }, 1962 + { 1963 + "type": "string", 1964 + "const": "integer" 1965 + }, 1966 + { 1967 + "type": "string", 1968 + "const": "array" 1969 + }, 1970 + { 1971 + "type": "string" 1972 + } 1973 ] 1974 }, 1975 "enum": { 1976 "type": "array", 1977 "items": { 1978 "$ref": "#/definitions/allowed-types" 1979 }, 1980 "minItems": 1 1981 }, 1982 "const": { 1983 "$ref": "#/definitions/allowed-types" 1984 }, 1985 "default": { 1986 "$ref": "#/definitions/allowed-types" 1987 }, 1988 "minimum": { 1989 "type": "number" 1990 }, 1991 "maximum": { 1992 "type": "number" 1993 }, 1994 "exclusiveMinimum": { 1995 "anyOf": [ 1996 { 1997 "type": "boolean" 1998 }, 1999 { 2000 "type": "number" 2001 } 2002 ] 2003 }, 2004 "exclusiveMaximum": { 2005 "anyOf": [ 2006 { 2007 "type": "boolean" 2009 }, 2010 { 2011 "type": "number" 2012 } 2013 ] 2014 }, 2015 "multipleOf": { 2016 "type": "number" 2017 }, 2018 "minLength": { 2019 "type": "number" 2020 }, 2021 "maxLength": { 2022 "type": "number" 2023 }, 2024 "pattern": { 2025 "type": "string" 2026 }, 2027 "format": { 2028 - "type": "string", 2029 - "enum": [ 2030 - "date-time", 2031 - "date", 2032 - "time", 2033 - "uri", 2034 - "uri-reference", 2035 - "uuid" 2036 + "anyOf": [ 2037 + { 2038 + "type": "string", 2039 + "const": "date-time" 2040 + }, 2041 + { 2042 + "type": "string", 2043 + "const": "date" 2044 + }, 2045 + { 2046 + "type": "string", 2047 + "const": "time" 2048 + }, 2049 + { 2050 + "type": "string", 2051 + "const": "uri" 2052 + }, 2053 + { 2054 + "type": "string", 2055 + "const": "uri-reference" 2056 + }, 2057 + { 2058 + "type": "string", 2059 + "const": "uuid" 2060 + }, 2061 + { 2062 + "type": "string" 2063 + } 2064 ] 2065 }, 2066 "minItems": { 2067 "type": "number" 2068 }, 2069 "maxItems": { 2070 "type": "number" 2071 }, 2072 "uniqueItems": { 2073 "type": "boolean" 2074 }, 2075 "items": { 2076 "type": "object", 2077 "properties": { 2078 "sdfRef": { 2079 "$ref": "#/definitions/sdf-pointer" 2080 }, 2081 "description": { 2082 "type": "string" 2083 }, 2084 "$comment": { 2085 "type": "string" 2086 }, 2087 "type": { 2088 - "type": "string", 2089 - "enum": [ 2090 - "number", 2091 - "string", 2092 - "boolean", 2093 - "integer" 2094 + "anyOf": [ 2095 + { 2096 + "type": "string", 2097 + "const": "number" 2098 + }, 2099 + { 2100 + "type": "string", 2101 + "const": "string" 2102 + }, 2103 + { 2104 + "type": "string", 2105 + "const": "boolean" 2106 + }, 2107 + { 2108 + "type": "string", 2109 + "const": "integer" 2110 + }, 2111 + { 2112 + "type": "string" 2113 + } 2114 ] 2115 }, 2116 "minimum": { 2117 "type": "number" 2118 }, 2119 "maximum": { 2120 "type": "number" 2121 }, 2122 "enum": { 2123 "type": "array", 2124 "minItems": 1 2125 }, 2126 "format": { 2127 "type": "string" 2128 }, 2129 "minLength": { 2130 "type": "number" 2131 }, 2132 "maxLength": { 2133 "type": "number" 2134 } 2135 }, 2136 - "additionalProperties": false 2137 + "additionalProperties": { 2138 + } 2139 } 2140 }, 2141 "additionalProperties": false 2142 }, 2143 "allowed-types": { 2144 "anyOf": [ 2145 { 2146 "type": "number" 2147 }, 2148 { 2149 "type": "string" 2150 }, 2151 { 2152 "type": "boolean" 2154 }, 2155 { 2156 "type": "null" 2157 }, 2158 { 2159 "type": "array", 2160 "items": { 2161 "type": "number" 2162 } 2163 }, 2164 { 2165 "type": "array", 2166 "items": { 2167 "type": "string" 2168 } 2169 }, 2170 { 2171 "type": "array", 2172 "items": { 2173 "type": "boolean" 2174 } 2175 + }, 2176 + { 2177 } 2178 ] 2179 }, 2180 "actionqualities": { 2181 "type": "object", 2182 "properties": { 2183 "sdfInputData": { 2184 "$ref": "#/definitions/pointer-list" 2185 }, 2186 "sdfRequiredInputData": { 2187 "$ref": "#/definitions/pointer-list" 2188 }, 2189 "sdfOutputData": { 2190 "$ref": "#/definitions/pointer-list" 2191 }, 2192 "sdfData": { 2193 "type": "object", 2194 "additionalProperties": { 2195 "$ref": "#/definitions/dataqualities" 2196 } 2197 }, 2198 "description": { 2199 "type": "string" 2200 }, 2201 "label": { 2202 "type": "string" 2203 }, 2204 "$comment": { 2205 "type": "string" 2206 }, 2207 "sdfRef": { 2208 "$ref": "#/definitions/sdf-pointer" 2209 }, 2210 "sdfRequired": { 2211 "$ref": "#/definitions/pointer-list" 2212 } 2213 }, 2214 - "additionalProperties": false 2215 + "additionalProperties": { 2216 + } 2217 }, 2218 "eventqualities": { 2219 "type": "object", 2220 "properties": { 2221 "sdfOutputData": { 2222 "$ref": "#/definitions/pointer-list" 2223 }, 2224 "sdfData": { 2225 "type": "object", 2226 "additionalProperties": { 2227 "$ref": "#/definitions/dataqualities" 2228 } 2229 }, 2230 "description": { 2231 "type": "string" 2232 }, 2233 "label": { 2234 "type": "string" 2235 }, 2236 "$comment": { 2237 "type": "string" 2238 }, 2239 "sdfRef": { 2240 "$ref": "#/definitions/sdf-pointer" 2241 }, 2242 "sdfRequired": { 2243 "$ref": "#/definitions/pointer-list" 2244 } 2245 }, 2246 - "additionalProperties": false 2247 + "additionalProperties": { 2248 + } 2249 }, 2250 "productqualities": { 2251 "$ref": "#/definitions/thingqualities" 2252 } 2253 } 2254 } 2256 Acknowledgements 2258 This draft is based on "sdf.md" and "sdf-schema.json" in the old one- 2259 data-model "language" repository, as well as Ari Keranen's "alt- 2260 schema" from the Ericsson Research "ipso-odm" repository (which is 2261 now under subdirectory "sdflint" in the one-data model "tools" 2262 repository). 2264 Contributors 2266 Ari Keränen 2267 Ericsson 2268 FI-02420 Jorvas 2269 Finland 2271 Email: ari.keranen@ericsson.com 2273 Wouter van der Beek 2274 Cisco Systems 2275 Eastpoint Business Park 2276 Alfie Byrne Road 2277 Dublin 3 2278 Ireland 2280 Email: wovander@cisco.com 2282 Authors' Addresses 2284 Michael Koster (editor) 2285 SmartThings 2286 665 Clyde Avenue 2287 Mountain View, 94043 2288 United States of America 2290 Phone: +1-707-502-5136 2291 Email: Michael.Koster@smartthings.com 2292 Carsten Bormann (editor) 2293 Universität Bremen TZI 2294 Postfach 330440 2295 D-28359 Bremen 2296 Germany 2298 Phone: +49-421-218-63921 2299 Email: cabo@tzi.org