]> Universität Bremen TZI

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

Universität Bremen

Germany jan.romann@uni-bremen.de

ASDF IoT Link Information Model Interaction Model Data Model This document discusses types of Instance Information to be used in conjunction with the Semantic Definition Format (SDF) for Data and Interactions of Things (draft-ietf-asdf-sdf) and will ultimately define Representation Formats for them as well as ways to use SDF Models to describe them. The present revision –05 is intended as input for IETF 123, with a few observations from the Hackathon addressed and this status paragraph updated. About This Document Status information for this document may be found at . Discussion of this document takes place on the »A Semantic Definition Format for Data and Interactions of Things« (ASDF) Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The Semantic Definition Format for Data and Interactions of Things (SDF, ) is a format for domain experts to use in the creation and maintenance of data and interaction models in the Internet of Things. SDF is an Interaction Modeling format, enabling a modeler to describe the digital interactions that a class of Things (devices) offers, including the abstract data types of messages used in these interactions. SDF is designed to be independent of specific ecosystems that specify conventions for performing these interactions, e.g., over Internet protocols or over ecosystem-specific protocol stacks. SDF does not define representation formats for the Instance Information that is exchanged in, or the subject of such, interactions; this is left to the specific ecosystems, which tend to have rather different ways to represent this information. This document discusses types of Instance Information and will ultimately define Abstract (eco-system independent) Representation Formats for them as well as ways to use SDF Models to describe them.

Conventions and Definitions The definitions of , , and apply. Terminology may need to be imported from .

Representation:

As defined in Section of RFC 9110 , but understood to analogously apply to other interaction styles than Representational State Transfer as well.

Message:

A Representation that is exchanged in, or is the subject of, an Interaction. Messages are "data in flight", not instance "data at rest" (the latter are called "Instance" and are modeled by the interaction model). Depending on the specific message, an abstract data model for the message may be provided by the sdfData definitions (or of declarations that look like these, such as sdfProperty) of an SDF model. Deriving an ecosystem specific representation of a message may be aided by mapping files that apply to the SDF model providing the abstract data model.

Instantiation:

Instantiation is a process that takes a Model, some Context Information, and possibly information from a Device and creates an Instance.

Instance:

Anything that can be interacted with based on the SDF model. E.g., the Thing itself (device), a Digital Twin, an Asset Management system... Instances are modeled as "data at rest", not "data in flight" (the latter are called "Message" and actually are/have a Representation). Instances that relate to a single Thing are bound together by some form of identity. Instances become useful if they are "situated", i.e., with a physical or digital "address" that they can be found at and made the subject of an interaction.

Proofshot:

A message that attempts to describe the state of an Instance at a particular moment (which may be part of the context). We are not saying that the Proofshot is the instance because there may be different ways to make one from an Instance (or to consume one in updating the state of the Instance), and because the proofshot, being a message, is not situated. Proofshots are snapshots, and they are "proofs" in the photographic sense, i.e., they may not be of perfect quality. Not all state that is characteristic of an Instance may be included in a Proofshot (e.g., information about an active action that is not embedded in an action resource). Proofshots may depend on additional context (such as the identity of the Instance and a Timestamp). An interaction affordance to obtain a Proofshot may not be provided by every Instance. An Instance may provide separate Construction affordances instead of simply setting a Proofshot. Discuss Proofshots of a Thing (device) and of other components. Discuss concurrency problems with getting and setting Proofshots. Discuss Timestamps appropriate for Things (, ).

Construction:

Construction messages enable the creation of a digital Instance, e.g., initialization/commissioning of a device or creation of its digital twins. They are like proofshots, in that they embody a state, however this state needs to be precise so the construction can actually happen. Discuss YANG config=true approach.

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 () () when, and only when, they appear in all capitals, as shown here.

Terms we are trying not to use

Non-affordance:

Originally a term for information that is the subject of interactions with other Instances than the Thing (called "offDevice" now), this term is now considered confusing as it would often just be an affordance of another Instance than the Thing.

Instance Information and SDF Instantiation doesn't produce an instance (ouch), which is the device, twin, etc., but a message.

Pre-structured types of messages Pre-structured types of messages are those that relate to an SDF model in a way that, together with context and model, they are fully self-describing.

Input and output data of specific interactions Messages always have context, typically describing the "me" and the "you" of the interaction, the "now" and "here", allowing deictic statements ("the temperature here", "my current draw")... Messages may have to be complemented by this context for interpretation, i.e., the context needed may need to be reified in the message (compare the use of SenML "n"). TODO: Use NIPC as an example how this could be used, including SCIM as a source of context information. TODO: explain how could be used to obtain device names (using urn:dev:org in the example). (Describe how protocol bindings can be used to convert these messages to/from concrete serializations...)

Examples for context information

Example for an SDF instance with context information

Proofshots (read device, other component) (See defn above.) The following examples are based on Figure 2 of , separated into an SDF proofshot and an SDF model. A proofshot that captures the state of a boat with a heater is shown in . Here, every property of the corresponding SDF model (see ) is mapped to a concrete value that corresponds with the associated schema information. The alternating structure of the SDF model (e. g., sdfThing/boot007/sdfObject/heater/sdfProperty/isHeating) is repeated in the proofshot, with sdfObject and sdfThing being replaced by sdfInstance. While earlier approaches avoided the additional level of nesting by omitting the affordance quality names (i.e., sdfProperty, sdfAction, sdfEvent), including them explicitly avoids problems with namespace clashes and allows for a cleaner integration of meta data (via the $context keyword). As in any instance message, information from the model is not repeated but referenced via a pointer into the model tree (sdfInstanceOf); the namespace needed for this is set up in the usual namespace section that we also have in model files. Note that in this example, the proofshot also contains values for the implicit (offDevice) properties that are static (e.g., the physical location assigned to the instance) but are still part of the instance's proofshot as its location is fixed -- this boat apparently never leaves the harbor.

SDF proofshot proposal for Figure 2 in [I-D.lee-asdf-digital-twin-08]

Corresponding SDF Model shows a model like the one that could have been pointed to by the sdfInstanceOf pointers in the instance message. Note how the namespace is managed here to export the model components into models:#/sdfThing/boat and models:#/sdfThing/boat/sdfObject/heater. (This example model only specifies structure; it also could come with semantic information such as the units that are used for wgs84 etc. In practice, the definition of wgs84 etc. probably would come from a common library and just be referenced via sdfRef.)

Revised SDF model proposal for Figure 2 of [I-D.lee-asdf-digital-twin-08]

Construction Construction messages enable the creation of the digital instance, e.g., initialization/commissioning of a device or creation of its digital twins. They are like proofshots, in that they embody a state, however this state needs to be precise so the construction can actually happen. A construction message for a temperature sensor might assign an identity and/or complement it by temporary identity information (e.g., an IP address); its processing might also generate construction output (e.g., a public key or an IP address if those are generated on device). Construction messages need to refer to some kind of constructor in order to be able to start the actual construction process. It is still up for discussion whether this concept justifies a new keyword or whether construction and other lifecycle management processes should be modeled as sdfActions instead. (Note that it is not quite clear what a destructor would be for a physical instance -- apart from a scrap metal press, but according to RFC 8576 we would want to move a system to a re-usable initial state, which is pretty much a constructor.)

Examples for SDF Constructors This section contains examples for both approaches discussed above: introduces an sdfConstructor keyword which allows for defining both mandatory (in this example: temperatureUnit) and optional constructor parameters (in this example: ipAddress). The example shows that the names of constructor parameters may deviate from the quality names in the model (temperatureUnit vs unit) as the target quality is specified via a JSON pointer. Additionally, this constructor example explicitly labels the ipAddress as information that belongs to the $context of the proofshot.

Example for SDF model with constructors

The alternative approach is shown in . Here, the constructor is modeled as an sdfAction that contains the same set of parameters in its sdfInputData. While this approach has advantages – we do not need to introduce new keywords to achieve a similar functionality and can simply use a plain JSON object as the construction message – a few things in this example are still unclear, especially when it comes to the mapping of constructor parameters to target affordances in the model and the designation of parameters as context information. Lastly, it is currently unclear what kind of schema information should be provided for the action's sdfOutputData. As a return value, a pointer to the instantiated device and/or the models describing it could make sense.

Example for SDF model with constructors

Example for an SDF construction message shows a potential SDF construction message that allows for the creation of a proofshot from a constructor that is contained within an SDF model. Note that the ipAddress can be considered context information or an off-device property. TODO: Needs more discussion how to model this kind of information.

Example for an SDF construction message

Deltas and Default/Base messages What changed since the last proofshot? What is different from the base status of the device? Can I get the same (equivalent, not identical) coffee I just ordered but with 10 % more milk? (Think merge-patch.) A construction message may be a delta, or it may have parameters that algorithmically influence the elements of state that one would find in a proofshot.

Example for an SDF construction message for proofshot delta

Deltas and Default/Base messages could be used in the Series Transfer Pattern , which may be one way to model a telemetry stream from a device. A potential example for the use of proofshot deltas is shown in . Here, the proofshot delta refers to the previous example in via its proofshotId, which is included in the previousProofshot quality. Compared to the previous proofshot, only the status property of the boat's heater has changed from error to operational. Via an algorithm such as JSON Merge Patch , the actual proofshot can be resolved by applying the delta to the previous version. In future versions of this document, we will evaluate whether JSON Merge Patch is sufficient to fulfill the requirements for the resolution algorithm which have to formulated and refined themselves.

Example for an SDF proofshot delta that overrides the status property of the boat's heater.

Metadata One interesting piece of offDevice information is the model itself, including sdfinfo and the defaultnamespace. This is of course not about the device or its twin (or even its asset management), because models and devices may want to associate freely. Multiple models may apply to the same device (including but not only revisions of the models).

Discussion (TODO)

Security Considerations (TODO)

IANA Considerations (TODO)

References Normative References KTC Control AB Universität Bremen TZI Ericsson The Semantic Definition Format (SDF) is concerned with Things, namely physical objects that are available for interaction over a network. SDF is a format for domain experts to use in the creation and maintenance of data and interaction models that describe Things. An SDF specification describes definitions of SDF Objects/SDF Things and their associated interactions (Events, Actions, Properties), as well as the Data types for the information exchanged in those interactions. Tools convert this format to database formats and other serializations as needed. This specification defines a model for the relationships between resources on the Web ("links") and the type of those relationships ("link relation types"). It also defines the serialisation of such links in HTTP headers with the Link header field. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. 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. Informative References University of California, Irvine This specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK] 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. Universität Bremen TZI Universität Bremen The Semantic Definition Format (SDF) is a format for domain experts to use in the creation and maintenance of data and interaction models that describe Things, i.e., physical objects that are available for interaction over a network. It was created as a common language for use in the development of the One Data Model liaison organization (OneDM) models. Tools convert this format to database formats and other serializations as needed. An SDF specification often needs to be augmented by additional information that is specific to its use in a particular ecosystem or application. SDF mapping files provide a mechanism to represent this augmentation. Universität Bremen TZI Ericsson Universitat Politecnica de Catalunya The Internet Protocol Suite is increasingly used on small devices with severe constraints on power, memory, and processing resources, creating constrained-node networks. This document provides a number of basic terms that have been useful in the standardization work for constrained-node networks. When devices are deployed in locations with no real-time access to the Internet, obtaining a trusted time for validation of time limited tokens and certificates is sometimes not possible. This document explores the options for deployments in which the trade-off between availability and security needs to be made in favor of availability. While considerations are general, terminology and examples primarily focus on the ACE framework. Electronics and Telecommunications Research Institute Electronics and Telecommunications Research Institute DONG-EUI University Daejeon University This memo specifies SDF modeling for a digital twin, i.e. a digital twin system, and its Things. An SDF is a format that is used to create and maintain data and interaction, and to represent the various kinds of data that is exchanged for these interactions. The SDF format can be used to model the characteristics, behavior and interactions of Things, i.e. physical objects, in a digital twin that contain Things as components. WISHI Wiki Universität Bremen TZI Ericsson Many applications make use of Series of data items, i.e., an array of data items where new items can be added over time. Where such Series are to be made available using REST protocols such as CoAP or HTTP, the Series has to be mapped into a structure of one or more resources and a protocol for a client to obtain the Series and to learn about new items. Various protocols have been standardized that make Series-shaped data available, with rather different properties and objectives. The present document is an attempt to extract a common underlying pattern and to define media types and an access scheme that can be used right away for further protocols that provide Series-shaped data. This document describes a new Uniform Resource Name (URN) namespace for hardware device identifiers. A general representation of device identity can be useful in many applications, such as in sensor data streams and storage or in equipment inventories. A URN-based representation can be passed along in applications that need the information.

Roads Not Taken This appendix documents previous modelling approaches that we eventually decided against pursuing further. Its main purpose is to illustrate our development process, showing which kind of alternatives we considered before choosing a particular way to describe instance information. We will remove this appendix as soon as this document is about to be finished.

Using SDF Models as Proofshots As shown in , the proofshot format could have also been modeled via SDF models where all sdfProperty definitions are given constvalues. However, this concept is not capable of capturing actions and events.

SDF instance proposal for Figure 2 in [I-D.lee-asdf-digital-twin-08]

Alternative Instance Keys Below you can see an alternative instance modelling approach with IDs as (part of the) instance keys.

SDF instance proposal (with IDs as part of the instance keys) for Figure 2 in [I-D.lee-asdf-digital-twin-08]

Acknowledgments (TODO)