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