]> PassiveLogic

524 H Street Antioch, CA 94509 USA +1-707-502-5136 michaeljohnkoster@gmail.com

Universität Bremen TZI

Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org

Applications ASDF Internet-Draft The Semantic Definition Format (SDF) is a format for domain experts to use in the creation and maintenance of data and interaction models in the Internet of Things. It was created as a common language for use in the development of the One Data Model liaison organization (OneDM) definitions. Tools convert this format to database formats and other serializations as needed. An SDF specification describes definitions of SDF Objects and their associated interactions (Events, Actions, Properties), as well as the Data types for the information exchanged in those interactions. A JSON format representation of SDF 1.0 was defined in version (-00) of this document; version (-05) was designated as an implementation draft, labeled SDF 1.1, at the IETF110 meeting of the ASDF WG (2021-03-11). The present version (-09) adds a URN namespace for registered measurement unit names. Contributing Recent versions of this document are available at its GitHub repository https://github.com/ietf-wg-asdf/SDF -- this also provides an issue tracker as well as a way to supply "pull requests". General discussion of this SDF Internet-Draft happens on the mailing list of the IETF ASDF Working Group, asdf@ietf.org (subscribe at https://www.ietf.org/mailman/listinfo/asdf). The IETF Note Well applies (https://www.ietf.org/about/note-well/).

Introduction The Semantic Definition Format (SDF) is a format for domain experts to use in the creation and maintenance of data and interaction models in the Internet of Things. It was created as a common language for use in the development of the One Data Model liaison organization (OneDM) definitions. Tools convert this format to database formats and other serializations as needed. An SDF specification describes definitions of SDF Objects and their associated interactions (Events, Actions, Properties), as well as the Data types for the information exchanged in those interactions. A JSON format representation of SDF 1.0 was defined in version (-00) of this document; version (-05) was designated as an implementation draft, labeled SDF 1.1, at the IETF110 meeting of the ASDF WG (2021-03-11). The present version (-09) adds a URN namespace for registered measurement unit names.

Terminology and Conventions

Thing:

A physical item 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.

The term "byte" is used in its now-customary sense as a synonym for "octet". 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 when, and only when, they appear in all capitals, as shown here.

Overview

Example Definition We start with an example for the SDF definition of a simple Object called "Switch" ().

A simple example of an SDF definition file

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 , 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.) In the JSON representation, note how (with the exception of the info group) maps that have keys taken from the SDF vocabulary (info, namespace, sdfObject) alternate in nesting with maps that have keys that are freely defined by the model writer (Switch, value, on, etc.); the latter usually use the named<> production in the formal syntax of SDF, while the former SDF-defined vocabulary items are often, but not always, called qualities.

Elements of an SDF model The SDF language uses seven predefined Class Name Keywords for modeling connected Things, six of which are illustrated in (the seventh class sdfProduct is similar enough to sdfThing that it would look the same in the figure).

Main classes used in SDF models

The seven main Class Name Keywords are discussed below.

sdfObject Objects, the items listed in an sdfObject group, are the main "atom" of reusable semantics for model construction. It aligns in scope with common definition items from many IoT modeling systems, for example ZigBee Clusters , OMA SpecWorks LwM2M Objects , and OCF Resource Types . An sdfObject contains a set of sdfProperty, sdfAction, and sdfEvent definitions that describe the interaction affordances associated with some scope of functionality. For the granularity of definition, sdfObject definitions are meant to be kept narrow enough in scope to enable broad reuse and interoperability. For example, defining a light bulb using separate sdfObject definitions for on/off control, dimming, and color control affordances will enable interoperable functionality to be configured for diverse product types. An sdfObject definition for a common on/off control may be used to control may different kinds of Things that require on/off control. Optional qualities "minItems" and "maxItems" can be used to define sdfObjects as arrays.

sdfProperty sdfProperty is used to model elements of state within sdfObject instances. An instance of sdfProperty may be associated with some protocol affordance to enable the application to obtain the state variable and, optionally, modify the state variable. Additionally, some protocols provide for in-time reporting of state changes. (These three aspects are described by the qualities readable, writable, and observable defined for an sdfProperty.) Definitions in sdfProperty groups look like definitions in sdfData groups, however, they actually also declare a Property with the given qualities to be potentially present in the containing Object. (Qualities beyond those of sdfData definitions could be defined for sdfProperty declarations but currently aren't; this means that even Property qualities such as readable and writable can be associated with definitions in sdfData groups, as well.) For definitions in sdfProperty and sdfData, SDF provides qualities that can constrain the structure and values of data allowed in an instance of these data, as well as qualities that associate semantics to these data, for engineering units and unit scaling information. For the data definition within sdfProperty or sdfData, SDF borrows some vocabulary proposed for the drafts 4 and 7 of the json-schema.org "JSON Schema" format (collectively called JSO here), enhanced by qualities that are specific to SDF. Details about the former are in . For the current version of SDF, data are constrained to be of simple types (number, string, Boolean), JSON maps composed of named data ("objects"), and arrays of these types. Syntax extension points are provided that can be used to provide richer types in future versions of this specification (possibly more of which can be borrowed from json-schema.org). Note that sdfProperty definitions (and sdfData definitions in general) are not intended to constrain the formats of data used for communication over network interfaces. Where needed, data definitions for payloads of protocol messages are expected to be part of the protocol binding.

sdfAction The sdfAction group contains declarations of Actions, model affordances that, when triggered, have more effect than just reading, updating, or observing Thing state, often resulting in some outward physical effect (which, itself, cannot be modeled in SDF). From a programmer's perspective, they might be considered to be roughly analogous to method calls. Actions may have data parameters; these are modeled as a single item of input data and output data, each. (Where multiple parameters need to be modeled, an "object" type can be used to combine these parameters into one.) Actions may be long-running, that is to say that the effects may not take place immediately as would be expected for an update to an sdfProperty; the effects may play out over time and emit action results. Actions may also not always complete and may result in application errors, such as an item blocking the closing of an automatic door. Actions may have (or lack) qualities of idempotency and side-effect safety. The current version of SDF only provides data constraint modeling and semantics for the input and output data of definitions in sdfAction groups. Again, data definitions for payloads of protocol messages, and detailed protocol settings for invoking the action, are expected to be part of the protocol binding.

sdfEvent The sdfEvent group contains declarations of Events, which can model affordances that inform about "happenings" associated with an instance of an Object; these may result in a signal being stored or emitted as a result. Note that there is a trivial overlap with sdfProperty state changes, which may also be defined as events but are not generally required to be defined as such. However, Events may exhibit certain ordering, consistency, and reliability requirements that are expected to be supported in various implementations of sdfEvent that do distinguish sdfEvent from sdfProperty. For instance, while a state change may simply be superseded by another state change, some events are "precious" and need to be preserved even if further events follow. The current version of SDF only provides data constraint modeling and semantics for the output data of Event affordances. Again, data definitions for payloads of protocol messages, and detailed protocol settings for invoking the action, are expected to be part of the protocol binding.

sdfData Definitions in sdfData groups are provided separately from those in sdfProperty groups to enable common modeling patterns, data constraints, and semantic anchor concepts to be factored out for data items that make up sdfProperty items and serve as input and output data for sdfAction and sdfEvent items. It is a common use case for such a data definition to be shared between an sdfProperty item and input or output parameters of an sdfAction or output data provided by an sdfEvent. sdfData definitions also enable factoring out extended application data types such as mode and machine state enumerations to be reused across multiple definitions that have similar basic characteristics and requirements.

sdfThing Back at the top level, the sdfThing groups enables definition of models for complex devices that will use one or more sdfObject definitions. A definition in an sdfThing group can refine the metadata of the definitions it is composed from: other definitions in sdfThing groups definitions in sdfObject groups.

sdfProduct sdfThing has a derived class sdfProduct, which can be used to indicate a top level inventory item with a Stock-Keeping Unit (SKU) identifier and other particular metadata. Structurally, there is no difference between definitions in either group; semantically, a definition in an sdfProduct group is intended to describe a class of complete Things.

SDF structure SDF definitions are contained in SDF files. One or more SDF files can work together to provide the definitions and declarations that are the payload of the SDF format. A SDF definition file contains a single JSON map (JSON object). This object has three sections: the information block, the namespaces section, and the definitions section.

Information block The information block contains generic meta data for the file itself and all included definitions. To enable tool integration, the information block is optional in the grammar of SDF; most processes for working with SDF files will have policies that only SDF models with an info block can be processed. It is therefore RECOMMENDED that SDF validator tools emit a warning when no information block is found. 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 . Qualities of the Information Block

Quality	Type	Required	Description
title	string	yes	A short summary to be displayed in search results, etc.
version	string	yes	The incremental version of the definition, format TBD
copyright	string	yes	Link to text or embedded text containing a copyright notice
license	string	yes	Link to text or embedded text containing license terms

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 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 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 license identifier. (For models to be handled by the One Data Model liaison group, this will typically be "BSD-3-Clause".)

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. Namespaces Section

Quality	Type	Required	Description
namespace	map	no	Defines short names mapped to namespace URIs, to be used as identifier prefixes
defaultNamespace	string	no	Identifies one of the prefixes in the namespace map to be used as a default in resolving identifiers

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. 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.

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 :

Example Object definition

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.

Names and namespaces SDF definition files may contribute to a global namespace, and may reference elements from that global namespace. (An SDF definition file that does not set a defaultNamespace does not contribute to a global namespace.)

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 , with a scheme of "https" and a path (hier-part in ). 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 .

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 , 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 ) from the fragment identifier part.

Referencing global names A name reference takes the form of the production curie in (note that this excludes the production safe-curie), but also limiting the IRIs involved in that production to URIs as per and the prefixes to ASCII characters . 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 . 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: Then this reference to that namespace: references the global name: 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

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 .) For example, this reference: creates a new definition "temperatureProperty" that contains all of the qualities defined in the definition at /sdfData/temperatureData. The sdfRef member need not be the only member of a map. Additional members may be present with the intention to override parts of the referenced map. More formally, for a JSON map that contains an sdfRef member, the semantics is defined to be as if the following steps were performed:

1. The JSON map that contains the sdfRef member is copied into a variable named "patch".
2. The sdfRef member of the copy in "patch" is removed.
3. the JSON pointer that is the value of the sdfRef member is dereferenced and the result is copied into a variable named "original".
4. The JSON Merge Patch algorithm is applied to patch the contents of "original" with the contents of "patch".
5. The result of the Merge Patch is used in place of the value of the original JSON map.

TODO: Make sure that the grammar in allows specifying the null values that are necessary to remove members in a merge-patch.

sdfRequired The keyword "sdfRequired" is provided to apply a constraint that defines for which declarations corresponding data are mandatory in an instance conforming the current definition. The value of "sdfRequired" is an array of name references (JSON pointers), each indicating one declaration that is mandatory to be represented. The example in shows two required elements in the sdfObject definition for "temperatureWithAlarm", the sdfProperty "currentTemperature", and the sdfEvent "overTemperatureEvent". The example also shows the use of JSON pointer with "sdfRef" to use a pre-existing definition in this definition, for the "alarmType" data (sdfOutputData) produced by the sdfEvent "overTemperatureEvent".

Using sdfRequired

Common Qualities Definitions in SDF share a number of qualities that provide metadata for them. These are listed in . 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 ) of the JSON pointer to the definition can be used. Common Qualities

Quality	Type	Description
description	text	long text (no constraints)
label	text	short text (no constraints)
$comment	text	source code comments only, no semantics
sdfRef	sdf-pointer	(see )
sdfRequired	pointer-list	(see , applies to qualities of properties, of data)

Data Qualities Data qualities are used in sdfData and sdfProperty definitions, which are named sets of data qualities (abbreviated as named-sdq). lists data qualities inspired by the various proposals at json-schema.org; the intention is that these (information model level) qualities are compatible with the (data model) semantics from the versions of the json-schema.org proposal they were imported from. lists data qualities defined specifically for the present specification. SDF-defined Qualities of sdfProperty and sdfData

Quality	Type	Description	Default
(common)
unit	string	unit name (note 1)	N/A
scaleMinimum	number	lower limit of value in units given by unit (note 2)	N/A
scaleMaximum	number	upper limit of value in units given by unit (note 2)	N/A
readable	boolean	Reads are allowed	true
writable	boolean	Writes are allowed	true
observable	boolean	flag to indicate asynchronous notification is available	true
nullable	boolean	indicates a null value is available for this type	true
contentFormat	string	content type (IANA media type string plus parameters), encoding	N/A
sdfType	string ()	sdfType enumeration (extensible)	N/A
sdfChoice	named set of data qualities ()	named alternatives	N/A
enum	array of strings	abbreviation for string-valued named alternatives	N/A

1. Note that the quality unit was called units in SDF 1.0. The unit name SHOULD be as per the Registry or the Registry in as specified by Sections and of and , respectively. Exceptionally, if a registration in these registries cannot be obtained or would be inappropriate, the unit name can also be a URI that is pointing to a definition of the unit. Note that SDF processors are not expected to (and normally SHOULD NOT) dereference these URIs; they may be useful to humans, though. A URI unit name is distinguished from a registered unit name by the presence of a colon; registered unit names that contain a colon (at the time of writing, none) can therefore not be used in SDF. For use by translators into ecosystems that require URIs for unit names, the URN sub-namespace "urn:ietf:params:unit" is provided (); URNs from this sub-namespace MUST NOT be used in a unit quality, in favor of simply notating the unit name (e.g., kg instead of urn:ietf:params:unit:kg).
2. these qualities were included in SDF 1.0, but were not fully defined; they are not included in SDF 1.1. In 1.next, they will be replaced by qualities to express scaling that are more aligned with the processes that combine ecosystem and instance specific information with an SDF model.

sdfType SDF defines a number of basic types beyond those provided by JSON or JSO. These types are identified by the sdfType quality, which is a text string from a set of type names defined by SDF. To aid interworking with implementations, it is RECOMMENDED that sdfType is always used in conjunction with the type quality inherited from , in such a way as to yield a common representation of the type's values in JSON. Values for sdfType that are defined in SDF 1.1 are shown in . This table also gives a description of the semantics of the sdfType, the conventional value for type to be used with the sdfType value, and a conventional JSON representation for values of the type. Values defined in SDF 1.1 for sdfType quality

sdfType	Description	type	JSON Representation
byte-string	A sequence of zero or more bytes	string	base64url without padding ()
unix-time	A point in civil time (note 1)	number	POSIX time ()

(1) Note that the definition of unix-time does not imply the capability to represent points in time that fall on leap seconds. More date/time-related sdfTypes are likely to be added in future versions of this specification. In SDF 1.0, a similar concept was called subtype.

sdfChoice Data can be a choice of named alternatives, called sdfChoice. Each alternative is identified by a name (string, key in the JSON object used to represent the choice) and a set of dataqualities (object, the value in the JSON object used to represent the choice). sdfChoice merges the functions of two constructs found in :

• enum What would have been in SDF 1.0, is often best represented as: This allows the placement of other dataqualities such as description in the example. If an enum needs to use a data type different from text string, e.g. what would have been in SDF 1.0, is represented as: where the string names obviously would be chosen in a way that is descriptive for what these numbers actually stand for; sdfChoice also makes it easy to add number ranges into the mix. (Note that const can also be used for strings as in the previous example, e.g., if the actual string value is indeed a crucial element for the data model.)
• anyOf provides a type union called anyOf, which provides a choice between anonymous alternatives. What could have been in can be more descriptively notated in SDF as:

Note that there is no need in SDF for the type intersection construct allOf or the peculiar type-xor construct oneOf found in . As a simplification for readers of SDF specifications accustomed to the enum keyword, this is retained, but limited to a choice of text string values, such that is syntactic sugar for

Keywords for definition groups The following SDF keywords are used to create definition groups in the target namespace. All these definitions share some common qualities as discussed in .

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 . None of these qualities are required or have default values that are assumed if the quality is absent. Qualities of sdfObject

Quality	Type	Description
(common)
sdfProperty	property	zero or more named property definitions for this object
sdfAction	action	zero or more named action definitions for this object
sdfEvent	event	zero or more named event definitions for this object
sdfData	named-sdq	zero or more named data type definitions that might be used in the above
minItems	number	(array) Minimum number of sdfObject instances in array
maxItems	number	(array) Maximum number of sdfObject instances in array

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 .

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 . Qualities of sdfAction

Quality	Type	Description
(common)
sdfInputData	map	data qualities of the input data for an Action
sdfOutputData	map	data qualities of the output data for an Action
sdfData	named-sdq	zero or more named data type definitions that might be used in the above

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

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 . Qualities of sdfEvent

Quality	Type	Description
(common)
sdfOutputData	map	data qualities of the output data for an Event
sdfData	named-sdq	zero or more named data type definitions that might be used in the above

sdfOutputData defines the output data of the action. As discussed in , 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.

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 .

High Level Composition The requirements for high level composition include the following:

• The ability to represent products, standardized product types, and modular products while maintaining the atomicity of Objects.
• The ability to compose a reusable definition block from Objects, for example a single plug unit of an outlet strip with on/off control, energy monitor, and optional dimmer objects, while retaining the atomicity of the individual objects.
• The ability to compose Objects and other definition blocks into a higher level thing that represents a product, while retaining the atomicity of objects.
• The ability to enrich and refine a base definition to have product-specific qualities and quality values, e.g. unit, range, and scale settings.
• The ability to reference items in one part of a complex definition from another part of the same definition, for example to summarize the energy readings from all plugs in an outlet strip.

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).

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.

Use of the "sdfRef" keyword to re-use a definition An existing definition may be used as a template for a new definition, that is, a new definition is created in the target namespace which uses the defined qualities of some existing definition. This pattern will use the keyword "sdfRef" as a quality of a new definition with a value consisting of a reference to the existing definition that is to be used as a template. In the definition that uses "sdfRef", new qualities may be added and existing qualities from the referenced definition may be overridden. (Note that JSON maps (objects) do not have a defined order, so the SDF processor may see these overrides before seeing the sdfRef.) As a convention, overrides are intended to be used only for further restricting the set of data values, as shown in : any value for a cable-length also is a valid value for a length, with the additional restriction that the length cannot be smaller than 5 cm. (This is labeled as a convention as it cannot be checked in the general case; a quality of implementation consideration for a tool might be to provide at least some form of checking.) Note that a description is provided that overrides the description of the referenced definition; as this quality is intended for human consumption there is no conflict with the intended goal.

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 . Qualities of sdfThing and sdfProduct

Quality	Type	Description
(common)
sdfThing	thing
sdfObject	object

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 .

IANA Considerations

Media Type IANA is requested to add the following Media-Type to the "Media Types" registry.

Name	Template	Reference
sdf+json	application/sdf+json	RFC XXXX,

// RFC Ed.: please replace RFC XXXX with this RFC number and remove this note.

Type name:

application

Subtype name:

sdf+json

Required parameters:

none

Optional parameters:

none

Encoding considerations:

binary (JSON is UTF-8-encoded text)

Security considerations:

of RFC XXXX

Interoperability considerations:

none

Published specification:

of RFC XXXX

Applications that use this media type:

Tools for data and interaction modeling in the Internet of Things

Fragment identifier considerations:

A JSON Pointer fragment identifier may be used, as defined in .

Person & email address to contact for further information:

ASDF WG mailing list (asdf@ietf.org), or IETF Applications and Real-Time Area (art@ietf.org)

Intended usage:

COMMON

Restrictions on usage:

none

Author/Change controller:

IETF

Provisional registration:

no

IETF URN Sub-namespace for Unit Names (urn:ietf:params:unit) IANA is requested to register the following value in the "" registry, following the template in :

Registry name:

unit

Specification:

RFC XXXX

Repository:

combining the symbol values from the Registry and the Registry in as specified by Sections and of and , respectively (which by the registration policy are guaranteed to be non-overlapping).

Index value:

Percent-encoding () is required of any characters in unit names as required by ABNF rule "pchar" in , specifically at the time of writing for the unit names "%" (deprecated in favor of "/"), "%RH", "%EL".

Registries (TBD: After future additions, check if we need any.)

Security Considerations Some wider issues are discussed in . (Specifics: TBD.)

References Normative References IANA IANA This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. This specification defines a format for representing simple sensor measurements and device parameters in Sensor Measurement Lists (SenML). Representations are defined in JavaScript Object Notation (JSON), Concise Binary Object Representation (CBOR), Extensible Markup Language (XML), and Efficient XML Interchange (EXI), which share the common SenML data model. A simple sensor, such as a temperature sensor, could use one of these media types in protocols such as HTTP or the Constrained Application Protocol (CoAP) to transport the measurements of the sensor or to be configured. The Sensor Measurement Lists (SenML) media type supports the indication of units for a quantity represented. This short document registers a number of additional unit names in the IANA registry for units in SenML. It also defines a registry for secondary units that cannot be in SenML's main registry, as they are derived by linear transformation from units already in that registry. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] This specification defines a Uniform Resource Name namespace for UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally Unique IDentifier). A UUID is 128 bits long, and can guarantee uniqueness across space and time. UUIDs were originally used in the Apollo Network Computing System and later in the Open Software Foundation\'s (OSF) Distributed Computing Environment (DCE), and then in Microsoft Windows platforms. This specification is derived from the DCE specification with the kind permission of the OSF (now known as The Open Group). Information from earlier versions of the DCE specification have been incorporated into this document. [STANDARDS-TRACK] JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document. This specification defines the JSON merge patch format and processing rules. The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. Universität Bremen TZI The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. The present document defines a number of control operators that were not yet ready at the time RFC 8610 was completed: .plus, .cat and .det for the construction of constants, .abnf/.abnfb for including ABNF (RFC 5234/RFC 7405) in CDDL specifications, and .feature for indicating the use of a non-basic feature in an instance. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document describes a new sub-delegation for the 'ietf' URN namespace for registered protocol items. The 'ietf' URN namespace is defined in RFC 2648 as a root for persistent URIs that refer to IETF- defined resources. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Informative References Wellcome Sanger Institute JSON Schema (application/schema+json) has several purposes, one of which is JSON instance validation. This document specifies a vocabulary for JSON Schema to describe the meaning of JSON documents, provide hints for user interfaces working with JSON data, and to make assertions about what a valid document must look like. JSON Schema defines the media type "application/schema+json", a JSON- based format for describing the structure of JSON data. JSON Schema asserts what a JSON document must look like, ways to extract information from it, and how to interact with it, ideal for annotating existing JSON APIs that would not otherwise have hypermedia controls or be machine-readable. Ericsson Huawei Technologies This document gives guidance for designing Internet of Things (IoT) systems that follow the principles of the Representational State Transfer (REST) architectural style. This document is a product of the IRTF Thing-to-Thing Research Group (T2TRG). The Internet of Things (IoT) concept refers to the usage of standard Internet protocols to allow for human-to-thing and thing-to-thing communication. The security needs for IoT systems are well recognized, and many standardization steps to provide security have been taken -- for example, the specification of the Constrained Application Protocol (CoAP) secured with Datagram Transport Layer Security (DTLS). However, security challenges still exist, not only because there are some use cases that lack a suitable solution, but also because many IoT devices and systems have been designed and deployed with very limited security capabilities. In this document, we first discuss the various stages in the lifecycle of a thing. Next, we document the security threats to a thing and the challenges that one might face to protect against these threats. Lastly, we discuss the next steps needed to facilitate the deployment of secure IoT systems. This document can be used by implementers and authors of IoT specifications as a reference for details about security considerations while documenting their specific security challenges, threat models, and mitigations. This document is a product of the IRTF Thing-to-Thing Research Group (T2TRG). Ecma International Universität Bremen TZI "Regular expressions" (regexps) are a set of related, widely implemented pattern languages used in data modeling formats and query languages that is available in many dialects. This specification defines an interoperable flavor of regexps, I-Regexp. The present version -00 of this document is a trial balloon, meant to determine whether this approach is useful for the JSONPath WG.

Formal Syntax of SDF This appendix describes the syntax of SDF using CDDL . Note that this appendix was derived from Ari Keranen's "alt-schema" and Michael Koster's "schema", with a view of covering the syntax that is currently in use at the One Data Model playground repository. This appendix shows the framework syntax only, i.e., a syntax with liberal extension points. Since this syntax is nearly useless in finding typos in an SDF specification, a second syntax, the validation syntax, is defined that does not include the extension points. The validation syntax can be generated from the framework syntax by leaving out all lines containing the string EXTENSION-POINT; as this is trivial, the result is not shown here. This appendix makes use of CDDL "features" as defined in Section 4 of . A feature named "1.0" is used to indicate parts of the syntax being deprecated towards SDF 1.1, and a feature named "1.1" is used to indicate new syntax intended for SDF 1.1. Features whose names end in "-ext" indicate extension points for further evolution. ? defaultNamespace: text ? sdfThing: named ; Thing is a composition of objects that work together in some way ? sdfProduct: named ; Product is a composition of things and objects that can model a SKU-level instance of a product ? sdfObject: named ; Object is a set of Properties, Actions, and Events that together perform a particular function ? sdfProperty: named ; Property represents the state of an instance of an object ? sdfAction: named ; Action is a directive to invoke an application layer verb associated with an object ? sdfEvent: named ; Event represents an occurrence of something associated with an object ? 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 EXTENSION-POINT<"top-ext"> } sdfinfo = { title: text version: text copyright: text license: text EXTENSION-POINT<"info-ext"> } ; Shortcut for a map that gives names to instances of X (has text keys and values of type X) named = { * text => X } EXTENSION-POINT = ( * (text .feature f) => any ) ; only used in framework syntax sdf-pointer = text ; .regexp curie-regexp -- TO DO! pointer-list = [* sdf-pointer] ; ISSUE: no point in having an empty list, no? but used for sdfRequired in odmobject-multiple_axis_joystick.sdf.json commonqualities = ( ? description: text ; long text (no constraints) ? label: text ; short text (no constraints); default to key ? $comment: text ; source code comments only, no semantics ? sdfRef: sdf-pointer ? sdfRequired: pointer-list ; applies to qualities of properties, of data ) ; for building hierarchy thingqualities = { commonqualities, ? sdfObject: named ? sdfThing: named EXTENSION-POINT<"thing-ext"> } productqualities = thingqualities ; ISSUE: get rid of sdfProduct? ; for single objects, or for arrays of objects (1.2) objectqualities = { commonqualities, ? ("minItems" .feature "1.2") => number ? ("maxItems" .feature "1.2") => number ? sdfProperty: named ? sdfAction: named ? sdfEvent: named ? sdfData: named EXTENSION-POINT<"object-ext"> } propertyqualities = dataqualities ; the definitions in sdfData are declarations in sdfProperty parameter-list = pointer-list .feature (["1.0", "pointerlist-as-parameter"]) / dataqualities .feature (["1.1", "dataqualities-as-parameter"]) actionqualities = { commonqualities, ? sdfInputData: parameter-list ; sdfRequiredInputData applies here (a bit redundant) ? ("sdfRequiredInputData" .feature "1.0") => pointer-list ? sdfOutputData: parameter-list ; sdfRequired applies here ? sdfData: named ; zero or more named data type definitions that might be used in the above EXTENSION-POINT<"action-ext"> } eventqualities = { commonqualities ? sdfOutputData: parameter-list ; sdfRequired applies here ? sdfData: named ; zero or more named data type definitions that might be used in the above EXTENSION-POINT<"event-ext"> } dataqualities = { ; also propertyqualities commonqualities, jsonschema, ? ("units" .feature "1.0") => text ? ("unit" .feature "1.1") => text ? ("scaleMinimum" .feature "1.0") => number ? ("scaleMaximum" .feature "1.0") => number ? observable: bool ? readable: bool ? writable: bool ? nullable: bool ? ("subtype" .feature "1.0") => "byte-string" / "unix-time" / (text .feature "subtype-ext") ; EXTENSION-POINT ? ("sdfType" .feature "1.1") => "byte-string" / "unix-time" / (text .feature "sdftype-ext") ; EXTENSION-POINT ? contentFormat: text EXTENSION-POINT<"data-ext"> } allowed-types = number / text / bool / null / [* number] / [* text] / [* bool] / {* text => any} / (any .feature "allowed-ext") ; EXTENSION-POINT compound-type = ( "type" => ("object" .feature "1.1"), ? required: [+text], ? properties: named, ) choice-type = ( ("sdfChoice" .feature "1.1") => named ) jsonschema = ( ? (("type" => "number" / "string" / "boolean" / "integer" / "array") // compound-type // choice-type // (type: text .feature "type-ext") ; EXTENSION-POINT ) ? "enum" => [+ text] ; limited to text strings in SDF 1.1 ? ("enum" .feature "1.0") => [+ allowed-types] ; should validate against type ? const: allowed-types ; should validate against type ? default: allowed-types ; should validate against type ; number/integer constraints ? minimum: number ? maximum: number ? exclusiveMinimum: bool / number ; jso draft 4/7 ? exclusiveMaximum: bool / number ; jso draft 4/7 ? multipleOf: number ; ISSUE: Do we need this? ; text string constraints ? minLength: number ? maxLength: number ? pattern: text ; regexp ? format: "date-time" / "date" / "time" / "uri" / "uri-reference" / "uuid" / (text .feature "format-ext") ; EXTENSION-POINT ; array constraints ? minItems: number ? maxItems: number ? uniqueItems: bool ? items: { ;;; ultimately, this will be mostly recursive, but, for now ;;; let's find out what we actually need ? sdfRef: sdf-pointer ; import limited to the subset that we allow here... ? description: text ; long text (no constraints) ? $comment: text ; source code comments only, no semantics ; commonqualities, ; -- ISSUE: should leave this out for non-complex data types, but need the above three ? ((type: "number" / "string" / "boolean" / "integer") ; no "array" // compound-type // choice-type ; do we really need arrays of choices? // (type: text .feature "itemtype-ext") ; EXTENSION-POINT ) ; jso subset ? minimum: number ? maximum: number ? "enum" => [+ text] ; limited to text strings in SDF 1.1 ? ("enum" .feature "1.0") => [+ any] ? format: text ? minLength: number ? maxLength: number EXTENSION-POINT<"items-ext"> } ) ]]>

json-schema.org Rendition of SDF Syntax This appendix describes the syntax of SDF defined in , but using a version of the description techniques advertised on json-schema.org . The appendix shows both the validation and the framework syntax. Since most of the lines are the same between these two files, those lines are shown only once, with a leading space, in the form of a unified diff. Lines leading with a - are part of the validation syntax, and lines leading with a + are part of the framework syntax.

Data Qualities inspired by json-schema.org Data qualities define data used in SDF affordances at an information model level. A popular way to describe JSON data at a data model level is proposed by a number of drafts on json-schema.org (which collectively are abbreviated JSO here)); for reference to a popular version we will point here to . As the vocabulary used by JSO is familiar to many JSON modellers, the present specification borrows some of the terms and ports their semantics to the information model level needed for SDF. The main data quality imported is the "type". In SDF, this can take one of six (text string) values, which are discussed in the following subsections (note that the JSO type "null" is not supported as a value of this data quality in SDF). The additional quality "const" restricts the data to one specific value (given as the value of the const quality). Similarly, the additional quality "default" provides data that can be used in the absence of the data (given as the value of the const quality); this is mainly documentary and not very well-defined for SDF as no process is defined that would add default values to an instance of something.

type "number", type "integer" The types "number" and "integer" are associated with floating point and integer numbers, as they are available in JSON. A type value of integer means that only integer values of JSON numbers can be used (note that 10.0 is an integer value, even if it is in a notation that would also allow non-zero decimal fractions). The additional data qualities "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum" provide number values that serve as inclusive/exclusive lower/upper bounds for the number. (Note that the Boolean form of "exclusiveMinimum"/"exclusiveMaximum" found in earlier JSO drafts is not used.) The data quality "multipleOf" gives a positive number that constrains the data value to be an integer multiple of the number given. (Type "integer" can also be expressed as a "multipleOf" quality of value 1, unless another "multipleOf" quality is present.)

type "string" The type "string" is associated with Unicode text string values as they are available in JSON. The length (as measured in characters) can be constrained by the additional data qualities "minLength" and "maxLength", which are inclusive bounds. Note that the previous version of the present document explained text string length values in bytes, which however is not meaningful unless bound to a specific encoding (which could be UTF-8, if this unusual behavior is to be restored). The data quality "pattern" takes a string value that is interpreted as an regular expression in Unicode mode that constrain the string (note that these are not anchored by default, so unless ^ and $ anchors are employed, ECMA-262 regular expressions match any string that contains a match). The JSO proposals acknowledge that regular expression support is rather diverse in various platforms, so the suggestion is to limit them to:

• characters;
• character classes in square brackets, including ranges; their complements;
• simple quantifiers *, +, ?, and range quantifiers {n}, {n,m}, and {n,};
• grouping parentheses;
• the choice operator |;
• and anchors (beginning-of-input ^ and end-of-input $).

Note that this subset is somewhat similar to the subset introduced by iregexps , which however are anchored regular expressions, and which include certain backslash escapes for characters and character classes. The additional data quality "format" can take one of the following values. Note that, at an information model level, the presence of this data quality changes the type from being a simple text string to the abstract meaning of the format given (i.e., the format "date-time" is less about the specific syntax employed in than about the usage as an absolute point in civil time).

• "date-time", "date", "time": An date-time, full-date, or full-time, respectively.
• "uri", "uri-reference": An URI or URI Reference, respectively.
• "uuid": An UUID.

type "boolean" The type "boolean" can take the values "true" or "false".

type "array" The type "array" is associated with arrays as they are available in JSON. The additional quality "items" gives the type that each of the elements of the array must match. The number of elements in the array can be constrained by the additional data qualities "minItems" and "maxItems", which are inclusive bounds. The additional data quality "uniqueItems" gives a Boolean value that, if true, requires the elements to be all different.

type "object" The type "object" is associated with maps, from strings to values, as they are available in JSON ("objects"). The additional quality "properties" is a map the entries of which describe entries in the specified JSON object: The key gives an allowable map key for the specified JSON object, and the value is a map with a named set of data qualities giving the type for the corresponding value in the specified JSON object. All entries specified this way are optional, unless they are listed in the value of the additional quality "required", which is an array of string values that give the key names of required entries. Note that the term "properties" as an additional quality for defining map entries is unrelated to sdfProperty.

Implementation notes JSO-based keywords are also used in the specification techniques of a number of ecosystems, but some adjustments may be required. E.g., is based on Swagger 2.0 which appears to be based on "draft-4" (also called draft-5, but semantically intended to be equivalent to draft-4). The "exclusiveMinimum" and "exclusiveMaximum" keywords use the Boolean form there, so on import to SDF their values have to be replaced by the values of the respective "minimum"/"maximum" keyword, which are themselves then removed; the reverse transformation applies on export. TBD: add any useful implementation notes we can find for other ecosystems that use JSO.

Acknowledgements This draft is based on sdf.md and sdf-schema.json in the old one-data-model language repository, as well as 's "alt-schema" from the Ericsson Research ipso-odm repository (which is now under subdirectory sdflint in the one-data model tools repository).

Contributors Ericsson

Jorvas 02420 Finland ari.keranen@ericsson.com

Cascoda Ltd.

Threefield House Threefield Lane Southampton United Kingdom w.vanderbeek@cascoda.com