Semantic Definition Format (SDF) for Data and Interactions of Things

1.1. Terminology and Conventions

Thing:

A physical device that is also made available in the Internet of Things. The term is used here for Things that are notable for their interaction with the physical world beyond interaction with humans; a temperature sensor or a light might be a Thing, but a router that employs both temperature sensors and indicator lights might exhibit less Thingness, as the effects of its functioning are mostly on the digital side.¶

Affordance:

An element of an interface offered for interaction, defining its possible uses or making clear how it can or should be used. The term is used here for the digital interfaces of a Thing only; it might also have physical affordances such as buttons, dials, and displays.¶

Quality:

A metadata item in a definition or declaration which says something about that definition or declaration. A quality is represented in SDF as an entry in a JSON map (object) that serves as a definition or declaration.¶

Entry:

A key-value pair in a map. (In JSON maps, sometimes also called "member".)¶

Block:

One or more entries in a JSON map that is part of an SDF specification; these entries together serve a specific function.¶

Group:

An entry in the main SDF map and in certain nested definitions that has a Class Name Keyword as its key and a map of definition entries (Definition Group) as a value.¶

Class Name Keyword:

One of sdfThing, sdfProduct, sdfObject, sdfProperty, sdfAction, sdfEvent, or sdfData; the Classes for these type keywords are capitalized and prefixed with sdf.¶

Class:

Abstract term for the information that is contained in groups identified by a Class Name Keyword.¶

Property:

An affordance that can potentially be used to read, write, and/or observe state on an Object. (Note that Entries are often called properties in other environments; in this document, the term Property is specifically reserved for affordances, even if the map key "properties" might be imported from a data definition language with the other semantics.)¶

Action:

An affordance that can potentially be used to perform a named operation on an Object.¶

Event:

An affordance that can potentially be used to obtain information about what happened to an Object.¶

Object:

A grouping of Property, Action, and Event definitions; the main "atom" of reusable semantics for model construction. (Note that JSON maps are often called JSON objects due to JSON's JavaScript heritage; in this document, the term Object is specifically reserved for the above grouping, even if the type name "object" might be imported from a data definition language with the other semantics.)¶

Element:

A part or an aspect of something abstract; used here in its usual English definition. (Occasionally, also used specifically for the elements of JSON arrays.)¶

Definition:

An entry in a Definition Group; the entry creates a new semantic term for use in SDF models and associates it with a set of qualities.¶

Declaration:

A reference to and a use of a definition within an enclosing definition, intended to create component instances within that enclosing definition. Every declaration can also be used as a definition for reference in a different place.¶

Protocol Binding:

A companion document to an SDF specification that defines how to map the abstract concepts in the specification into the protocols in use in a specific ecosystem. Might supply URL components, numeric IDs, and similar details.¶

Conventions:¶

• The singular form is chosen as the preferred one for the keywords defined here.¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

2.1. Example Definition

We start with an example for the SDF definition of a simple Object called "Switch" (Figure 1).¶

{
    "info": {
        "title": "Example file for OneDM Semantic Definition Format",
        "version": "2019-04-24",
        "copyright": "Copyright 2019 Example Corp. All rights reserved.",
        "license": "https://example.com/license"
    },
    "namespace": {
        "cap": "https://example.com/capability/cap"
    },
    "defaultNamespace": "cap",
    "sdfObject": {
        "Switch": {
            "sdfProperty": {
                "value": {
                    "description": "The state of the switch; false for off and true for on."
                    "type": "boolean"
                }
            },
            "sdfAction": {
                "on": {
                    "description": "Turn the switch on; equivalent to setting value to true."
                },
                "off": {
                    "description": "Turn the switch off; equivalent to setting value to false."
                },
                "toggle": {
                    "description": "Toggle the switch; equivalent to setting value to its complement."
                }
            }
        }
    }
}

This is a model of a switch. The state value declared in the sdfProperty group, represented by a Boolean, will be true for "on" and will be false for "off". The actions on or off declared in the sdfAction group are redundant with setting the value and are in the example to illustrate that there are often different ways of achieving the same effect. The action toggle will invert the value of the sdfProperty value, so that 2-way switches can be created; having such action will avoid the need for first retrieving the current value and then applying/setting the inverted value.¶

The sdfObject group lists the affordances of instances of this object. The sdfProperty group lists the property affordances described by the model; these represent various perspectives on the state of the object. Properties can have additional qualities to describe the state more precisely. Properties can be annotated to be read, write or read/write; how this is actually done by the underlying transfer protocols is not described in the SDF model but left to companion protocol bindings. Properties are often used with RESTful paradigms [I-D.irtf-t2trg-rest-iot], describing state. The sdfAction group is the mechanism to describe other interactions in terms of their names, input, and output data (no data are used in the example), as in a POST method in REST or in a remote procedure call. The example toggle is an Action that changes the state based on the current state of the Property named value. (The third type of affordance is Events, which are not described in this example.)¶

2.2. Elements of an SDF model

The SDF language uses seven predefined Class Name Keywords for modeling connected Things, six of which are illustrated in Figure 2 (the seventh class sdfProduct is exactly like sdfThing).¶

The seven main Class Name Keywords are discussed below.¶

3.1. Information block

The information block contains generic meta data for the file itself and all included definitions.¶

The keyword (map key) that defines an information block is "info". Its value is a JSON map in turn, with a set of entries that represent qualities that apply to the included definition.¶

Qualities of the information block are shown in Table 1.¶

While the format of the version string is marked as TBD, it is intended to be lexicographically increasing over the life of a model: a newer model always has a version string that string-compares higher than all previous versions. This is easily achieved by following the convention to start the version with an [RFC3339] date-time or, if new versions are generated less frequently than once a day, just the full-date (i.e., YYYY-MM-DD); in many cases, that will be all that is needed (see Figure 1 for an example).¶

The license string is preferably either a URI that points to a web page with an unambiguous definition of the license, or an [SPDX] license identifier. (For models to be handled by the One Data Model liaison group, this will typically be "BSD-3-Clause".)¶

3.2. Namespaces section

The namespaces section contains the namespace map and the defaultNamespace setting.¶

The namespace map is a map from short names for URIs to the namespace URIs themselves.¶

The defaultNamespace setting selects one of the entries in the namespace map by giving its short name. The associated URI (value of this entry) becomes the default namespace for the SDF definition file.¶

The following example declares a set of namespaces and defines cap as the default namespace. By convention, the values in the namespace map contain full URIs without a fragment identifier, and the fragment identifier is then added, if needed, where the namespace entry is used.¶

"namespace": {
  "cap": "https://example.com/capability/cap",
  "zcl": "https://zcl.example.com/sdf"
},
"defaultNamespace": "cap",

If no defaultNamespace setting is given, the SDF definition file does not contribute to a global namespace. As the defaultNamespace is set by giving a namespace short name, its presence requires a namespace map that contains a mapping for that namespace short name.¶

If no namespace map is given, no short names for namespace URIs are set up, and no defaultNamespace can be given.¶

3.3. Definitions section

The Definitions section contains one or more groups, each identified by a Class Name Keyword (there can only be one group per keyword; the actual grouping is just a shortcut and does not carry any specific semantics). The value of each group is a JSON map (object), the keys of which serve for naming the individual definitions in this group, and the corresponding values provide a set of qualities (name-value pairs) for the individual definition. (In short, we speak of the map entries as "named sets of qualities".)¶

Each group may contain zero or more definitions. Each identifier defined creates a new type and term in the target namespace. Declarations have a scope of the current definition block.¶

A definition may in turn contain other definitions. Each definition is a named set of qualities, i.e., it consists of the newly defined identifier and a set of key-value pairs that represent the defined qualities and contained definitions.¶

An example for an Object definition is given in Figure 3:¶

"sdfObject": {
  "foo": {
    "sdfProperty": {
      "bar": {
        "type": "boolean"
      }
    }
  }
}

This example defines an Object "foo" that is defined in the default namespace (full address: #/sdfObject/foo), containing a property that can be addressed as #/sdfObject/foo/sdfProperty/bar, with data of type boolean.¶

Some of the definitions are also declarations: the definition of the entry "bar" in the property "foo" means that each instance of a "foo" can have zero or one instance of a "bar". Entries within sdfProperty, sdfAction, and sdfEvent, within sdfObject entries, are declarations. Similarly, entries within an sdfThing describe instances of sdfObject (or nested sdfThing) that form part of instances of the Thing.¶

4.1. Structure

Global names look exactly like https:// URIs with attached fragment identifiers.¶

There is no intention to require that these URIs can be dereferenced. (However, as future versions of SDF might find a use for dereferencing global names, the URI should be chosen in such a way that this may become possible in the future.)¶

The absolute URI of a global name should be a URI as per Section 3 of [RFC3986], with a scheme of "https" and a path (hier-part in [RFC3986]). For the present version of this specification, the query part should not be used (it might be used in later versions).¶

The fragment identifier is constructed as per Section 6 of [RFC6901].¶

4.2. Contributing global names

The fragment identifier part of a global name defined in an SDF definition file is constructed from a JSON pointer that selects the element defined for this name in the SDF definition file.¶

The absolute URI part is a copy of the default namespace, i.e., the default namespace is always the target namespace for a name for which a definition is contributed. When emphasizing that name definitions are contributed to the default namespace, we therefore also call it the "target namespace" of the SDF definition file.¶

E.g., in Figure 1, definitions for the following global names are contributed:¶

• https://example.com/capability/cap#/sdfObject/Switch¶
• https://example.com/capability/cap#/sdfObject/Switch/sdfProperty/value¶
• https://example.com/capability/cap#/sdfObject/Switch/sdfAction/on¶
• https://example.com/capability/cap#/sdfObject/Switch/sdfAction/off¶

Note the #, which separates the absolute-URI part (Section 4.3 of [RFC3986]) from the fragment identifier part.¶

4.3. Referencing global names

A name reference takes the form of the production curie in [W3C.NOTE-curie-20101216] (note that this excludes the production safe-curie), but also limiting the IRIs involved in that production to URIs as per [RFC3986] and the prefixes to ASCII characters [RFC0020].¶

A name that is contributed by the current SDF definition file can be referenced by a Same-Document Reference as per section 4.4 of [RFC3986]. As there is little point in referencing the entire SDF definition file, this will be a # followed by a JSON pointer. This is the only kind of name reference to itself that is possible in an SDF definition file that does not set a default namespace.¶

Name references that point outside the current SDF definition file need to contain curie prefixes. These then reference namespace declarations in the namespaces section.¶

For example, if a namespace prefix is defined:¶

"namespace": {
  "foo": "https://example.com/"
}

Then this reference to that namespace:¶

{ "sdfRef": "foo:#/sdfData/temperatureData" }

references the global name:¶

"https://example.com/#/sdfData/temperatureData"

Note that there is no way to provide a URI scheme name in a curie, so all references outside of the document need to go through the namespace map.¶

Name references occur only in specific elements of the syntax of SDF:¶

• copying elements via sdfRef values¶
• pointing to elements via sdfRequired value elements¶

4.4. sdfRef

In a JSON map establishing a definition, the keyword "sdfRef" is used to copy all of the qualities of the referenced definition, indicated by the included name reference, into the newly formed definition. (This can be compared to the processing of the "$ref" keyword in [I-D.handrews-json-schema-validation].)¶

For example, this reference:¶

"temperatureProperty": {
  "sdfRef": "#/sdfData/temperatureData"
}

creates a new definition "temperatureProperty" that contains all of the qualities defined in the definition at /sdfData/temperatureData.¶

4.5. sdfRequired

The value of "sdfRequired" is an array of name references, each pointing to one declaration the instantiation of which is declared mandatory.¶

{
  "sdfObject": {
    "temperatureWithAlarm": {
      "sdfRequired": [
        "#/sdfObject/temperatureWithAlarm/sdfData/temperatureData",
        "#/sdfObject/temperatureWithAlarm/sdfEvent/overTemperatureEvent"
      ],
      "sdfData":{
        "temperatureData": {
          "type": "number"
        }
      },
      "sdfEvent": {
        "overTemperatureEvent": {
          "sdfOutputData": {
            "type": "object",
            "properties": {
              "alarmType": {
                "sdfRef": "cap:/sdfData/alarmTypes/quantityAlarms",
                "const": "OverTemperatureAlarm"
              },
              "temperature": {
                "sdfRef": "#/sdfObject/temperatureWithAlarm/sdfData/temperatureData"
              }
            }
          }
        }
      }
    }
  }
}

4.6. Common Qualities

Definitions in SDF share a number of qualities that provide metadata for them. These are listed in Table 3. None of these qualities are required or have default values that are assumed if the quality is absent. If a label is required for an application and no label is given in the SDF model, the last part (reference-token, Section 3 of [RFC6901]) of the JSON pointer to the definition can be used.¶

4.7. Data Qualities

Data qualities are used in sdfData and sdfProperty definitions, which are named sets of data qualities (abbreviated as named-sdq).¶

Table 4 lists data qualities borrowed from [I-D.handrews-json-schema-validation]; the intention is that these qualities retain their semantics from the versions of the json-schema.org proposal they were imported from. A description that starts with a parenthesized term means the quality is only applicable when type has the value of the term.¶

Table 5 lists data qualities defined specifically for the present specification.¶

The term "allowed types" stands for primitive JSON types, JSON maps ("objects")" as well as homogeneous arrays of numbers, text, Booleans, or maps. (This list might be extended in a future version of SDF.) An "allowed value" is a value allowed for one of these types.¶

(1) A type value of integer means that only integral values of JSON numbers can be used.¶

(2) Note that the term "properties" as used for map entries in [I-D.handrews-json-schema-validation] is unrelated to sdfProperty.¶

(3) note that the quality unit was called units in SDF 1.0.¶

5.1. sdfObject

The sdfObject keyword denotes a group of zero or more Object definitions. Object definitions may contain or include definitions of Properties, Actions, Events declared for the object, as well as data types (sdfData group) to be used in this or other Objects.¶

The qualities of an sdfObject include the common qualities, additional qualities are shown in Table 6. None of these qualities are required or have default values that are assumed if the quality is absent.¶

5.2. sdfProperty

The sdfProperty keyword denotes a group of zero or more Property definitions.¶

Properties are used to model elements of state.¶

The qualities of a Property definition include the data qualities (and thus the common qualities), see Section 4.7.¶

5.3. sdfAction

The sdfAction keyword denotes a group of zero or more Action definitions.¶

Actions are used to model commands and methods which are invoked. Actions have parameter data that are supplied upon invocation.¶

The qualities of an Action definition include the common qualities, additional qualities are shown in Table 7.¶

sdfInputData defines the input data of the action. sdfOutputData defines the output data of the action. As discussed in Section 2.2.3, a set of data qualities with type "object" can be used to substructure either data item, with optionality indicated by the data quality required.¶

5.4. sdfEvent

The sdfEvent keyword denotes zero or more Event definitions.¶

Events are used to model asynchronous occurrences that may be communicated proactively. Events have data elements which are communicated upon the occurrence of the event.¶

The qualities of sdfEvent include the common qualities, additional qualities are shown in Table 8.¶

sdfOutputData defines the output data of the action. As discussed in Section 2.2.4, a set of data qualities with type "object" can be used to substructure the output data item, with optionality indicated by the data quality required.¶

5.5. sdfData

The sdfData keyword denotes a group of zero or more named data type definitions (named-sdq).¶

An sdfData definition provides a reusable semantic identifier for a type of data item and describes the constraints on the defined type. It is not itself a declaration, i.e., it does not cause any of these data items to be included in an affordance definition.¶

The qualities of sdfData include the data qualities (and thus the common qualities), see Section 4.7.¶

6.1. Paths in the model namespaces

The model namespace is organized according to terms that are defined in the definition files that are present in the namespace. For example, definitions that originate from an organization or vendor are expected to be in a namespace that is specific to that organization or vendor. There is expected to be an SDF namespace for common SDF definitions used in OneDM.¶

The structure of a path in a namespace is defined by the JSON Pointers to the definitions in the files in that namespace. For example, if there is a file defining an object "Switch" with an action "on", then the reference to the action would be "ns:/sdfObject/Switch/sdfAction/on" where ns is the namespace prefix (short name for the namespace).¶

6.2. Modular Composition

Modular composition of definitions enables an existing definition (could be in the same file or another file) to become part of a new definition by including a reference to the existing definition within the model namespace.¶

"sdfData":
  "length" : {
    "type": "number",
    "minimum": 0,
    "unit": "m"
    "description": "There can be no negative lengths."
  }
...
  "cable-length" : {
    "sdfRef": "#/sdfData/length"
    "minimum": 0.05,
    "description": "Cables must be at least 5 cm."
  }

6.3. sdfThing

An sdfThing is a set of declarations and qualities that may be part of a more complex model. For example, the object declarations that make up the definition of a single socket of an outlet strip could be encapsulated in an sdfThing, and the socket-thing itself could be used in a declaration in the sdfThing definition for the outlet strip.¶

sdfThing definitions carry semantic meaning, such as a defined refrigerator compartment and a defined freezer compartment, making up a combination refrigerator-freezer product.¶

An sdfThing may be composed of sdfObjects and other sdfThings.¶

The qualities of sdfThing are shown in Table 9.¶

6.4. sdfProduct

An sdfProduct provides the level of abstraction for representing a unique product or a profile for a standardized type of product, for example a "device type" definition with required minimum functionality.¶

Products may be composed of Objects and Things at the high level, and may include their own definitions of Properties, Actions, and Events that can be used to extend or complete the included Object definitions.¶

Product definitions may set optional defaults and constant values for specific use cases, for example units, range, and scale settings for properties, or available parameters for Actions.¶

The qualities of sdfProduct are the same as for sdfThing and are shown in Table 9.¶