draft-ietf-asdf-sdf-06.txt   draft-ietf-asdf-sdf-07.txt 
ASDF M. Koster, Ed. ASDF M. Koster, Ed.
Internet-Draft Dogtiger Labs Internet-Draft Dogtiger Labs
Intended status: Standards Track C. Bormann, Ed. Intended status: Standards Track C. Bormann, Ed.
Expires: 3 December 2021 Universit├Ąt Bremen TZI Expires: 13 January 2022 Universit├Ąt Bremen TZI
1 June 2021 12 July 2021
Semantic Definition Format (SDF) for Data and Interactions of Things Semantic Definition Format (SDF) for Data and Interactions of Things
draft-ietf-asdf-sdf-06 draft-ietf-asdf-sdf-07
Abstract Abstract
The Semantic Definition Format (SDF) is a format for domain experts The Semantic Definition Format (SDF) is a format for domain experts
to use in the creation and maintenance of data and interaction models 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 in the Internet of Things. It was created as a common language for
use in the development of the One Data Model liaison organization use in the development of the One Data Model liaison organization
(OneDM) definitions. Tools convert this format to database formats (OneDM) definitions. Tools convert this format to database formats
and other serializations as needed. and other serializations as needed.
An SDF specification describes definitions of SDF Objects and their An SDF specification describes definitions of SDF Objects and their
associated interactions (Events, Actions, Properties), as well as the associated interactions (Events, Actions, Properties), as well as the
Data types for the information exchanged in those interactions. Data types for the information exchanged in those interactions.
A JSON format representation of SDF 1.0 was defined in version (-00) // A JSON format representation of SDF 1.0 was defined in version
of this document; version (-05) was designated as an _implementation // (-00) of this document; version (-05) was designated as an
draft_, labeled SDF 1.1, at the IETF110 meeting of the ASDF WG // _implementation draft_, labeled SDF 1.1, at the IETF110 meeting of
(2021-03-11). The present version (-06) is intended for discussion // the ASDF WG (2021-03-11). The present version (-07) has a few
at the ASDF interim meeting on 2021-06-02. // editorial improvements over -06, which was discussed at the ASDF
// interim meeting on 2021-06-02.
Contributing Contributing
Recent versions of this document are available at its GitHub Recent versions of this document are available at its GitHub
repository https://github.com/ietf-wg-asdf/SDF (https://github.com/ repository https://github.com/ietf-wg-asdf/SDF (https://github.com/
ietf-wg-asdf/SDF) -- this also provides an issue tracker as well as a ietf-wg-asdf/SDF) -- this also provides an issue tracker as well as a
way to supply "pull requests". way to supply "pull requests".
General discussion of this SDF Internet-Draft happens on the mailing General discussion of this SDF Internet-Draft happens on the mailing
list of the IETF ASDF Working Group, asdf@ietf.org (subscribe at list of the IETF ASDF Working Group, asdf@ietf.org (subscribe at
skipping to change at page 2, line 15 skipping to change at page 2, line 20
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 3 December 2021. This Internet-Draft will expire on 13 January 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology and Conventions . . . . . . . . . . . . . . . 4 1.1. Terminology and Conventions . . . . . . . . . . . . . . . 4
2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Example Definition . . . . . . . . . . . . . . . . . . . 5 2.1. Example Definition . . . . . . . . . . . . . . . . . . . 6
2.2. Elements of an SDF model . . . . . . . . . . . . . . . . 7 2.2. Elements of an SDF model . . . . . . . . . . . . . . . . 7
2.2.1. sdfObject . . . . . . . . . . . . . . . . . . . . . . 8 2.2.1. sdfObject . . . . . . . . . . . . . . . . . . . . . . 8
2.2.2. sdfProperty . . . . . . . . . . . . . . . . . . . . . 8 2.2.2. sdfProperty . . . . . . . . . . . . . . . . . . . . . 9
2.2.3. sdfAction . . . . . . . . . . . . . . . . . . . . . . 9 2.2.3. sdfAction . . . . . . . . . . . . . . . . . . . . . . 10
2.2.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . 10 2.2.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . 10
2.2.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . 10 2.2.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.6. sdfThing . . . . . . . . . . . . . . . . . . . . . . 11 2.2.6. sdfThing . . . . . . . . . . . . . . . . . . . . . . 11
2.2.7. sdfProduct . . . . . . . . . . . . . . . . . . . . . 11 2.2.7. sdfProduct . . . . . . . . . . . . . . . . . . . . . 11
3. SDF structure . . . . . . . . . . . . . . . . . . . . . . . . 11 3. SDF structure . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1. Information block . . . . . . . . . . . . . . . . . . . . 11 3.1. Information block . . . . . . . . . . . . . . . . . . . . 12
3.2. Namespaces section . . . . . . . . . . . . . . . . . . . 12 3.2. Namespaces section . . . . . . . . . . . . . . . . . . . 13
3.3. Definitions section . . . . . . . . . . . . . . . . . . . 13 3.3. Definitions section . . . . . . . . . . . . . . . . . . . 14
4. Names and namespaces . . . . . . . . . . . . . . . . . . . . 14 4. Names and namespaces . . . . . . . . . . . . . . . . . . . . 15
4.1. Structure . . . . . . . . . . . . . . . . . . . . . . . . 14 4.1. Structure . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2. Contributing global names . . . . . . . . . . . . . . . . 15 4.2. Contributing global names . . . . . . . . . . . . . . . . 15
4.3. Referencing global names . . . . . . . . . . . . . . . . 15 4.3. Referencing global names . . . . . . . . . . . . . . . . 16
4.4. sdfRef . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.4. sdfRef . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5. sdfRequired . . . . . . . . . . . . . . . . . . . . . . . 17 4.5. sdfRequired . . . . . . . . . . . . . . . . . . . . . . . 18
4.6. Common Qualities . . . . . . . . . . . . . . . . . . . . 18 4.6. Common Qualities . . . . . . . . . . . . . . . . . . . . 19
4.7. Data Qualities . . . . . . . . . . . . . . . . . . . . . 19 4.7. Data Qualities . . . . . . . . . . . . . . . . . . . . . 20
4.7.1. sdfType . . . . . . . . . . . . . . . . . . . . . . . 23 4.7.1. sdfType . . . . . . . . . . . . . . . . . . . . . . . 24
4.7.2. sdfChoice . . . . . . . . . . . . . . . . . . . . . . 24 4.7.2. sdfChoice . . . . . . . . . . . . . . . . . . . . . . 25
5. Keywords for definition groups . . . . . . . . . . . . . . . 26 5. Keywords for definition groups . . . . . . . . . . . . . . . 27
5.1. sdfObject . . . . . . . . . . . . . . . . . . . . . . . . 26 5.1. sdfObject . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2. sdfProperty . . . . . . . . . . . . . . . . . . . . . . . 27 5.2. sdfProperty . . . . . . . . . . . . . . . . . . . . . . . 28
5.3. sdfAction . . . . . . . . . . . . . . . . . . . . . . . . 27 5.3. sdfAction . . . . . . . . . . . . . . . . . . . . . . . . 28
5.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . . . 28 5.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . . . 29
5.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . . . 29
6. High Level Composition . . . . . . . . . . . . . . . . . . . 28 6. High Level Composition . . . . . . . . . . . . . . . . . . . 29
6.1. Paths in the model namespaces . . . . . . . . . . . . . . 29 6.1. Paths in the model namespaces . . . . . . . . . . . . . . 30
6.2. Modular Composition . . . . . . . . . . . . . . . . . . . 29 6.2. Modular Composition . . . . . . . . . . . . . . . . . . . 30
6.2.1. Use of the "sdfRef" keyword to re-use a definition . 30 6.2.1. Use of the "sdfRef" keyword to re-use a definition . 31
6.3. sdfThing . . . . . . . . . . . . . . . . . . . . . . . . 31 6.3. sdfThing . . . . . . . . . . . . . . . . . . . . . . . . 32
6.4. sdfProduct . . . . . . . . . . . . . . . . . . . . . . . 31 6.4. sdfProduct . . . . . . . . . . . . . . . . . . . . . . . 32
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33
7.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 32 7.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 33
7.2. Registries . . . . . . . . . . . . . . . . . . . . . . . 32 7.2. Registries . . . . . . . . . . . . . . . . . . . . . . . 33
8. Security Considerations . . . . . . . . . . . . . . . . . . . 32 8. Security Considerations . . . . . . . . . . . . . . . . . . . 33
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
9.1. Normative References . . . . . . . . . . . . . . . . . . 33 9.1. Normative References . . . . . . . . . . . . . . . . . . 34
9.2. Informative References . . . . . . . . . . . . . . . . . 34 9.2. Informative References . . . . . . . . . . . . . . . . . 35
Appendix A. Formal Syntax of SDF . . . . . . . . . . . . . . . . 35 Appendix A. Formal Syntax of SDF . . . . . . . . . . . . . . . . 36
Appendix B. json-schema.org Rendition of SDF Syntax . . . . . . 39 Appendix B. json-schema.org Rendition of SDF Syntax . . . . . . 40
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 77 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 78
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 79
1. Introduction 1. Introduction
The Semantic Definition Format (SDF) is a format for domain experts The Semantic Definition Format (SDF) is a format for domain experts
to use in the creation and maintenance of data and interaction models 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 in the Internet of Things. It was created as a common language for
use in the development of the One Data Model liaison organization use in the development of the One Data Model liaison organization
(OneDM) definitions. Tools convert this format to database formats (OneDM) definitions. Tools convert this format to database formats
and other serializations as needed. and other serializations as needed.
An SDF specification describes definitions of SDF Objects and their An SDF specification describes definitions of SDF Objects and their
associated interactions (Events, Actions, Properties), as well as the associated interactions (Events, Actions, Properties), as well as the
Data types for the information exchanged in those interactions. Data types for the information exchanged in those interactions.
A JSON format representation of SDF 1.0 was defined in a previous // A JSON format representation of SDF 1.0 was defined in version
(-00) version of this document. The present document has been // (-00) of this document; version (-05) was designated as an
designated as an _implementation draft_, labeled SDF 1.1, at the // _implementation draft_, labeled SDF 1.1, at the IETF110 meeting of
IETF110 meeting of the ASDF WG (2021-03-11). // the ASDF WG (2021-03-11). The present version (-07) has a few
// editorial improvements over -06, which was discussed at the ASDF
// interim meeting on 2021-06-02.
1.1. Terminology and Conventions 1.1. Terminology and Conventions
Thing: A physical item that is also made available in the Internet 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 of Things. The term is used here for Things that are notable for
their interaction with the physical world beyond interaction with their interaction with the physical world beyond interaction with
humans; a temperature sensor or a light might be a Thing, but a humans; a temperature sensor or a light might be a Thing, but a
router that employs both temperature sensors and indicator lights router that employs both temperature sensors and indicator lights
might exhibit less Thingness, as the effects of its functioning might exhibit less Thingness, as the effects of its functioning
are mostly on the digital side. are mostly on the digital side.
skipping to change at page 6, line 20 skipping to change at page 6, line 27
"license": "https://example.com/license" "license": "https://example.com/license"
}, },
"namespace": { "namespace": {
"cap": "https://example.com/capability/cap" "cap": "https://example.com/capability/cap"
}, },
"defaultNamespace": "cap", "defaultNamespace": "cap",
"sdfObject": { "sdfObject": {
"Switch": { "Switch": {
"sdfProperty": { "sdfProperty": {
"value": { "value": {
"description": "The state of the switch; false for off and true for on." "description": "The state of the switch; false for off and true for on.",
"type": "boolean" "type": "boolean"
} }
}, },
"sdfAction": { "sdfAction": {
"on": { "on": {
"description": "Turn the switch on; equivalent to setting value to true." "description": "Turn the switch on; equivalent to setting value to true."
}, },
"off": { "off": {
"description": "Turn the switch off; equivalent to setting value to false." "description": "Turn the switch off; equivalent to setting value to false."
}, },
skipping to change at page 7, line 21 skipping to change at page 7, line 25
underlying transfer protocols is not described in the SDF model but underlying transfer protocols is not described in the SDF model but
left to companion protocol bindings. Properties are often used with left to companion protocol bindings. Properties are often used with
RESTful paradigms [I-D.irtf-t2trg-rest-iot], describing state. The RESTful paradigms [I-D.irtf-t2trg-rest-iot], describing state. The
"sdfAction" group is the mechanism to describe other interactions in "sdfAction" group is the mechanism to describe other interactions in
terms of their names, input, and output data (no data are used in the 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. 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 The example "toggle" is an Action that changes the state based on the
current state of the Property named "value". (The third type of current state of the Property named "value". (The third type of
affordance is Events, which are not described in this example.) 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 (Appendix A), while the former SDF-
defined vocabulary items are often, but not always, called
_qualities_.
2.2. Elements of an SDF model 2.2. Elements of an SDF model
The SDF language uses seven predefined Class Name Keywords for The SDF language uses seven predefined Class Name Keywords for
modeling connected Things, six of which are illustrated in Figure 2 modeling connected Things, six of which are illustrated in Figure 2
(the seventh class "sdfProduct" is similar enough to "sdfThing" that (the seventh class "sdfProduct" is similar enough to "sdfThing" that
it would look the same in the figure). it would look the same in the figure).
,--------. ,--------.
|sdfThing| |sdfThing|
|--------| |--------|
skipping to change at page 9, line 41 skipping to change at page 10, line 19
updating, or observing Thing state, often resulting in some outward updating, or observing Thing state, often resulting in some outward
physical effect (which, itself, cannot be modeled in SDF). From a physical effect (which, itself, cannot be modeled in SDF). From a
programmer's perspective, they might be considered to be roughly programmer's perspective, they might be considered to be roughly
analogous to method calls. analogous to method calls.
Actions may have data parameters; these are modeled as a single item Actions may have data parameters; these are modeled as a single item
of input data and output data, each. (Where multiple parameters need of input data and output data, each. (Where multiple parameters need
to be modeled, an "object" type can be used to combine these to be modeled, an "object" type can be used to combine these
parameters into one.) Actions may be long-running, that is to say parameters into one.) Actions may be long-running, that is to say
that the effects may not take place immediately as would be expected that the effects may not take place immediately as would be expected
for an update to an "sdfPoperty"; the effects may play out over time for an update to an "sdfProperty"; the effects may play out over time
and emit action results. Actions may also not always complete and and emit action results. Actions may also not always complete and
may result in application errors, such as an item blocking the may result in application errors, such as an item blocking the
closing of an automatic door. closing of an automatic door.
Actions may have (or lack) qualities of idempotency and side-effect Actions may have (or lack) qualities of idempotency and side-effect
safety. safety.
The current version of SDF only provides data constraint modeling and The current version of SDF only provides data constraint modeling and
semantics for the input and output data of definitions in "sdfAction" semantics for the input and output data of definitions in "sdfAction"
groups. Again, data definitions for payloads of protocol messages, groups. Again, data definitions for payloads of protocol messages,
skipping to change at page 25, line 28 skipping to change at page 26, line 28
"sdfRef": "rgbVal"}} "sdfRef": "rgbVal"}}
{"type": "array", "minItems": 4, "maxItems": "4", "items": { {"type": "array", "minItems": 4, "maxItems": "4", "items": {
"sdfRef": "cmykVal"}} "sdfRef": "cmykVal"}}
] ]
in [I-D.handrews-json-schema-validation] can be more descriptively in [I-D.handrews-json-schema-validation] can be more descriptively
notated in SDF as: notated in SDF as:
"sdfChoice": { "sdfChoice": {
"rgb": {"type": "array", "minItems": 3, "maxItems": "3", "items": { "rgb": {"type": "array", "minItems": 3, "maxItems": "3", "items": {
"sdfRef": "rgbVal"}} "sdfRef": "rgbVal"}},
"cmyk": {"type": "array", "minItems": 4, "maxItems": "4", "items": { "cmyk": {"type": "array", "minItems": 4, "maxItems": "4", "items": {
"sdfRef": "cmykVal"}} "sdfRef": "cmykVal"}}
] ]
Note that there is no need in SDF for the type intersection construct Note that there is no need in SDF for the type intersection construct
"allOf" or the peculiar type-xor construct "oneOf" found in "allOf" or the peculiar type-xor construct "oneOf" found in
[I-D.handrews-json-schema-validation]. [I-D.handrews-json-schema-validation].
As a simplification for readers of SDF specifications accustomed to As a simplification for readers of SDF specifications accustomed to
the [I-D.handrews-json-schema-validation] enum keyword, this is the [I-D.handrews-json-schema-validation] enum keyword, this is
skipping to change at page 35, line 38 skipping to change at page 36, line 38
sdf-syntax = { sdf-syntax = {
? info: sdfinfo ; This will be required in most process policies, but not a syntax error ? info: sdfinfo ; This will be required in most process policies, but not a syntax error
? namespace: named<text> ? namespace: named<text>
? defaultNamespace: text ? defaultNamespace: text
? sdfThing: named<thingqualities> ; Thing is a composition of objects that work together in some way ? sdfThing: named<thingqualities> ; Thing is a composition of objects that work together in some way
? sdfProduct: named<productqualities> ; Product is a composition of things and objects that can model a SKU-level instance of a product ? sdfProduct: named<productqualities> ; Product is a composition of things and objects that can model a SKU-level instance of a product
? sdfObject: named<objectqualities> ; Object is a set of Properties, Actions, and Events that together perform a particular function ? sdfObject: named<objectqualities> ; Object is a set of Properties, Actions, and Events that together perform a particular function
? sdfProperty: named<propertyqualities> ; Property represents the state of an instance of an object ? sdfProperty: named<propertyqualities> ; Property represents the state of an instance of an object
? sdfAction: named<actionqualities> ; Action is a directive to invoke an application layer verb associated with an object ? sdfAction: named<actionqualities> ; Action is a directive to invoke an application layer verb associated with an object
? sdfEvent: named<eventqualities> ; Event represents an occurence of something associated with an object ? sdfEvent: named<eventqualities> ; Event represents an occurrence of something associated with an object
? sdfData: named<dataqualities> ; 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 ? sdfData: named<dataqualities> ; 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"> EXTENSION-POINT<"top-ext">
} }
sdfinfo = { sdfinfo = {
title: text title: text
version: text version: text
copyright: text copyright: text
license: text license: text
EXTENSION-POINT<"info-ext"> EXTENSION-POINT<"info-ext">
 End of changes. 15 change blocks. 
58 lines changed or deleted 70 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/