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

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 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 Supplements provide a mechanism to represent this augmentation. 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 (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 Supplements provide a mechanism to represent this augmentation. In this revision, we have renamed the map quality to amend since the underlying data structure changed from an object to an array. For this reason, we also change the term "Mapping File" to "Supplement" to also reflect the fact that the file does not actually contain a map for describing the augmentation anymore.

Terminology and Conventions The definitions of apply. The term "byte" is used in its now-customary sense as a synonym for "octet". 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.

Overview An SDF Supplement provides augmentation information for one or more SDF models. Its main contents are an array of patches that are applied using SDF name references () as the respective target. When processing the Supplement together with one or more SDF models, the qualities from the array elements are added to the SDF model at the referenced name, as in a merge-patch operation . Note that this is somewhat similar to the way sdfRef () works, but in a Supplement the arrows point in the inverse direction (from the augmenter to the augmented). The order of the application of patches is that of the elements within the array (which is deterministic in contrast to the order of entries of an object).

Example Model 1 (ecosystem: IPSO/OMA) An example for an SDF Supplement is given in . This Supplement is meant to attach to an SDF specification published by OneDM, and to add qualities relevant to the IPSO/OMA ecosystem.
Note that this example uses namespaces to identify elements of the referenced specification(s), but has un-namespaced quality names. These two kinds of namespaces are unrelated in SDF, and a more robust example may need to make use of Quality Name Prefixes as defined in (independent of a potential feature to add namespace references to definitions that are not intended to go into the default namespace — these are SDF definition namespaces and not quality namespaces, which are one meta-level higher).

• Start of a Supplement for certain OneDM playground models:

A simple example of an SDF Supplement

Example Model 2 (ecosystem: W3C WoT) This example shows a translation of a hypothetical W3C WoT Thing Model (as defined in Section 10 of ) into an SDF model plus a Supplement to catch Thing Model attributes that don't currently have SDF qualities defined (namely, titles and descriptions members used for internationalization). A second Supplement is more experimental in that it captures information that is actually instance-specific, in this case a forms member that binds the status property to an instance-specific CoAP resource.
Namespaces are all wrong in this example. The form really should be part of the class level; defining the entire form instead of just the link in the instance information is a symptom of not yet getting the class/instance boundary right.

• The input: WoT Thing Model

Input: WoT Thing Model

• The output: SDF model

Output 1: SDF Model

• The other output: SDF Supplement for class information

Output 2: SDF Supplement

• A third output: SDF Supplement for Protocol Bindings

Output 3: SDF Supplement for Protocol Bindings

Formal Syntax of SDF Supplements An SDF Supplement has three optional components that are taken unchanged from SDF: The info block, the namespace declaration, and the default namespace. The mandatory fourth component, the amend block, contains the list of amendments that are supposed to be applied to the target model, using an SDF name reference (usually a namespace and a JSON pointer) as the target to which a specified quality is applied to. describes the syntax of SDF Supplements using CDDL .

CDDL definition of SDF Supplements ? defaultNamespace: text amend: [ * amendments ] } amendments = { + global-sdf-pointer => additionalqualities, } ; we can't really be much more specific here: additionalqualities = named ; --------------------------------- import from SDF-base: sdfinfo = { ? title: text ? description: text ? version: text ? copyright: text ? license: text ? modified: modified-date-time ? features: [ * (any .feature "feature-name") ; EXTENSION-POINT ] optional-comment EXTENSION-POINT<"info-ext"> } ; Shortcut for a map that gives names to instances of X ; (has keys of type text and values of type X) named = { * text => X } ; EXTENSION-POINT is only used in framework syntax EXTENSION-POINT = ( * (quality-name .feature f) => any ) quality-name = text .regexp "([a-z][a-z0-9]*:)?[a-z$][A-Za-z$0-9]*" ; rough CURIE or JSON Pointer syntax: global-sdf-pointer = text .regexp ".*[:#].*" optional-comment = ( ? $comment: text ; source code comments only, no semantics ) modified-date-time = text .abnf modified-dt-abnf modified-dt-abnf = "modified-dt" .det rfc3339z ; RFC 3339 sans time-numoffset, slightly condensed rfc3339z = ' date-fullyear = 4DIGIT date-month = 2DIGIT ; 01-12 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on ; month/year time-hour = 2DIGIT ; 00-23 time-minute = 2DIGIT ; 00-59 time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap sec ; rules time-secfrac = "." 1*DIGIT DIGIT = %x30-39 ; 0-9 partial-time = time-hour ":" time-minute ":" time-second [time-secfrac] full-date = date-fullyear "-" date-month "-" date-mday modified-dt = full-date ["T" partial-time "Z"] ' ]]>

The JSON pointer that is used a the target can point to a JSON map in the SDF model to be augmented by adding or replacing map entries. If necessary, the JSON map is created at the position indicated with the contents of the patch (add examples). Alternatively, the JSON pointer can point to an array (also possibly created if not existing before) and add an element to that array by using the "‑" syntax introduced in the penultimate paragraph of .

Augmentation Mechanism An SDF model and a compatible Supplement can be combined to create an augmented SDF model. (This process can be repeated with multiple Supplements by using the outcome of one augmentation as the input of the next one.) As augmentation is not equal to instantiation, augmented SDF models are still abstract in nature, but are enriched with ecosystem-specific information. The augmentation mechanism is related to the resolution mechanism defined in , but fundamentally different: Instead of a model file reaching out to other model files and integrating aspects into itself via sdfRef (pull approach), the Supplement pushes information into a new copy of a specific given SDF model. The original SDF model does not need to know which Supplements it will be used with and can be used with several such Supplements independently of each other. An augmented SDF model is produced from two inputs: An SDF model and a compatible Supplement, i.e. every JSON pointer key within elements of the amend array points to a location that already exists within the SDF model or has been created by a previous augmentation step. To perform the augmentation, a processor needs to create a copy of the original SDF model. It then iterates over all entries within the Supplement's amend array elements. During each iteration, the processor first obtains a reference to the target referred to by the JSON pointer in the respective key. This reference is then used as the Target argument of the JSON Merge Patch algorithm and the entry's value as the Patch argument; the target is replaced with the result of the merge-patch. Once the iteration has finished, the processor returns the resulting augmented SDF model. Should the resolution of a JSON pointer or an application of the JSON Merge Patch algorithm fail, an error is thrown instead. An example for an augmented SDF model can be seen in . This is the result of applying the WoT-specific Supplement from to the SDF model shown in . This augmented SDF model is one step away from being converted to a WoT Thing Model or Thing Description, which requires some information that cannot be provided in an SDF model that is limited to the vocabulary defined in the SDF base specification.

An SDF model that has been augmented with WoT-specific vocabulary.

Logging Augmentation Since an augmented model is not fundamentally different from any other SDF model, it may be necessary to trace the provenance of the information that flowed into it, e.g., in the info block. For this purpose, a new quality called augmentationLog is introduced that contains an array of URIs pointing to the Supplements that have been used to augment the original SDF file (which can also be indicated via the originalSdfModel quality). These additional qualities allow for reproducing the augmentation process. For logging while performing an augmentation, the processor has to perform the following steps:

1. If the info block is not present in the model that is being augmented, the processor creates it.
2. If the info block does not contain an augmentationLog quality, the processor performs the following steps:
   1. If the originalSdfModel quality is not present in the info block, the processor adds it with a URI that can be used to access the SDF model that is currently being augmented as its value.
   2. The processor creates the augmentationLog quality with an array containing URIs that can be used to access the current Supplement as its sole item.
3. Otherwise, if augmentationLog does not contain an array, stop and throw an error.
4. Otherwise, the processor adds a URI that can be used to access the current Supplement to the array of the augmentationLog quality.

An augmented SDF model with an augmentation log and information regarding the original SDF model.

IANA Considerations

Media Type IANA is requested to add the following Media-Type to the "Media Types" registry. A media type for SDF Supplements

Name	Template	Reference
sdf-mapping+json	application/sdf-supplement+json	RFC XXXX,

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

Type name:

application

Subtype name:

sdf-mapping+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 that describes Things, i.e., physical objects that are available for interaction over a network

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

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

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

References Normative References JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document. 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. 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. 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. 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 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).

List of Figures

:

:

:

:

:

:

:

List of Tables

:

Acknowledgements This draft is based on discussions in the Thing-to-Thing Research Group (T2TRG) and the SDF working group. Input for was provided by .