rfc9880v3.txt   rfc9880.txt 
Internet Engineering Task Force (IETF) M. Koster, Ed. Internet Engineering Task Force (IETF) M. Koster, Ed.
Request for Comments: 9880 KTC Control AB Request for Comments: 9880 KTC Control AB
Category: Standards Track C. Bormann, Ed. Category: Standards Track C. Bormann, Ed.
ISSN: 2070-1721 Universität Bremen TZI ISSN: 2070-1721 Universität Bremen TZI
A. Keränen A. Keränen
Ericsson Ericsson
December 2025 January 2026
Semantic Definition Format (SDF) for Data and Interactions of Things Semantic Definition Format (SDF) for Data and Interactions of Things
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
that describe Things, i.e., physical objects that are available for that describe Things, i.e., physical objects that are available for
interaction over a network. An SDF specification describes interaction over a network. An SDF specification describes
definitions of SDF Objects/SDF Things and their associated definitions of SDF Objects/SDF Things and their associated
skipping to change at line 40 skipping to change at line 40
received public review and has been approved for publication by the received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841. Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata, Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9880. https://www.rfc-editor.org/info/rfc9880.
Copyright Notice Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the Copyright (c) 2026 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 Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Revised BSD License text as described in Section 4.e of the include Revised BSD License text as described in Section 4.e of the
Trust Legal Provisions and are provided without warranty as described Trust Legal Provisions and are provided without warranty as described
skipping to change at line 268 skipping to change at line 268
SDF Document: Container for SDF Definitions, together with data SDF Document: Container for SDF Definitions, together with data
about the SDF Document itself (information block). Represented as about the SDF Document itself (information block). Represented as
a JSON text representing a single JSON map, which is built from a JSON text representing a single JSON map, which is built from
nested maps. nested maps.
SDF Model: Definitions and declarations that model the digital SDF Model: Definitions and declarations that model the digital
interaction opportunities offered by one or more kinds of Things, interaction opportunities offered by one or more kinds of Things,
represented by Groupings (sdfObjects and sdfThings). An SDF Model represented by Groupings (sdfObjects and sdfThings). An SDF Model
can be fully contained in a single SDF Document, or it can be can be fully contained in a single SDF Document, or it can be
built from an SDF Document that references definitions and built from an SDF Document that references definitions and
declarations from additional SDF documents. declarations from additional SDF documents. The term SDF
Specification can be used when the distinction between the
distribution into individual SDF Documents and the abstract nature
of the SDF Model is not of interest.
Block: One or more entries in a JSON map that is part of an SDF Block: One or more entries in a JSON map that is part of an SDF
specification. These entries can be described as a Block to specification. These entries can be described as a Block to
emphasize that they serve a specific function together. emphasize that they serve a specific function together.
Group: An entry in the top-level JSON map that represents the SDF Group: An entry in the top-level JSON map that represents the SDF
document. Groups also can be used in certain nested definitions. document. Groups also can be used in certain nested definitions.
A group has a Class Name Keyword as its key and a map of named A group has a Class Name Keyword as its key and a map of named
definition entries (Definition Group) as a value. definition entries (Definition Group) as a value.
skipping to change at line 308 skipping to change at line 311
enclosing definition. enclosing definition.
Declaration: A definition within an enclosing definition that is Declaration: A definition within an enclosing definition that is
intended to create a component item within that enclosing intended to create a component item within that enclosing
definition. Every declaration can also be used as a definition definition. Every declaration can also be used as a definition
for reference elsewhere. for reference elsewhere.
Grouping: An sdfThing or sdfObject, i.e., (directly or indirectly) a Grouping: An sdfThing or sdfObject, i.e., (directly or indirectly) a
description for a combination of Affordances. description for a combination of Affordances.
Object, sdfObject: A Grouping that contains Affordance declarations Object, sdfObject: A Grouping where the declarations that it
(Property, Action, and Event declarations) only. It serves as the contains are for Affordances only (Property, Action, and Event
main "atom" of reusable semantics for model construction, declarations). It serves as the main "atom" of reusable semantics
representing the interaction model for a Thing that is simple for model construction, representing the interaction model for a
enough to not require a nested structure. Therefore, sdfObjects Thing that is simple enough to not require a nested structure.
are similar to sdfThings, but do not allow nesting, i.e., they Therefore, sdfObjects are similar to sdfThings, but do not allow
cannot contain other Groupings (sdfObjects or sdfThings). nesting, i.e., they cannot contain other Groupings (sdfObjects or
sdfThings).
sdfThing: A Grouping that can contain nested Groupings (sdfThings sdfThing: A Grouping that can contain nested Groupings (sdfThings
and sdfObjects). Like sdfObject, it can also contain Affordance and sdfObjects). Like sdfObject, it can also contain Affordance
declarations (Property, Action, and Event declarations). (Note declarations (Property, Action, and Event declarations). (Note
that "Thing" has a different meaning from sdfThing and is that "Thing" has a different meaning from sdfThing and is
therefore not available as a colloquial shorthand of sdfThing.) therefore not available as a colloquial shorthand of sdfThing.)
Augmentation Mechanism: A companion document to a base SDF Model Augmentation Mechanism: A companion document to a base SDF Model
that provides additional information ("augments" the base that provides additional information ("augments" the base
specification). The information may be for use in a specific specification). The information may be for use in a specific
skipping to change at line 445 skipping to change at line 449
names, input, and output data (no data are used in the example), as 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 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 toggle is an Action that changes the state based on the current state
of the Property named value. (The third type of affordance is of the Property named value. (The third type of affordance is
Events, which are not described in this example.) Events, which are not described in this example.)
In the JSON representation, the info group is an exception in that In the JSON representation, the info group is an exception in that
this group's map has keys taken from the SDF vocabulary. All other this group's map has keys taken from the SDF vocabulary. All other
groups (such as namespace and sdfObject) have maps with keys that are groups (such as namespace and sdfObject) have maps with keys that are
freely defined by the model writer (Switch, value, on, etc.). These freely defined by the model writer (Switch, value, on, etc.). These
map keys are therefore called _given names_. The groups made up of map keys are therefore called _Given Names_. The groups made up of
entries with given names as keys usually use the named<> production entries with Given Names as keys usually use the named<> production
in the formal syntax of SDF (Appendix A). Where the values of these in the formal syntax of SDF (Appendix A). Where the values of these
entries are maps, these again use SDF vocabulary keys, and so on, entries are maps, these again use SDF vocabulary keys, and so on,
generally alternating in further nesting. The SDF-defined vocabulary generally alternating in further nesting. The SDF-defined vocabulary
items used in the hierarchy of such groups are often, but not always, items used in the hierarchy of such groups are often, but not always,
called _Quality Names_ or _qualities_. See Section 2.3 for more called _Quality Names_ or _qualities_. See Section 2.3 for more
information about naming in SDF. information about naming in SDF.
2.2. Elements of an SDF Model 2.2. Elements of an SDF Model
The SDF language uses six predefined Class Name Keywords for modeling The SDF language uses six predefined Class Name Keywords for modeling
skipping to change at line 500 skipping to change at line 504
Figure 2: Main Classes Used in SDF Models Figure 2: Main Classes Used in SDF Models
The six main Class Name Keywords are discussed below. The six main Class Name Keywords are discussed below.
2.2.1. sdfObject 2.2.1. sdfObject
sdfObjects, the items listed in an sdfObject definition group, are sdfObjects, the items listed in an sdfObject definition group, are
the main "atom" of reusable semantics for model construction. The the main "atom" of reusable semantics for model construction. The
concept aligns in scope with common definition items from many IoT concept aligns in scope with common definition items from many IoT
modeling systems, e.g., ZigBee Clusters [ZCL], OMA SpecWorks LwM2M modeling systems, e.g., ZigBee Clusters [ZCL], OMA SpecWorks LwM2M
Objects [OMA], OCF Resource Types [OCF], and W3C Web of Things [WoT]. Objects [OMA], OCF Resource Types [OCF], and W3C Web of Things Thing
Descriptions [WoT].
An sdfObject definition contains a set of sdfProperty, sdfAction, and An sdfObject definition contains a set of sdfProperty, sdfAction, and
sdfEvent definitions that describe the interaction affordances sdfEvent definitions that describe the interaction affordances
associated with some scope of functionality. associated with some scope of functionality.
For the granularity of definition, sdfObject definitions are meant to For the granularity of definition, sdfObject definitions are meant to
be kept narrow enough in scope to enable broad reuse and be kept narrow enough in scope to enable broad reuse and
interoperability. For example, defining a light bulb using separate interoperability. For example, defining a light bulb using separate
sdfObject definitions for on/off control, dimming, and color control sdfObject definitions for on/off control, dimming, and color control
affordances will enable interoperable functionality to be configured affordances will enable interoperable functionality to be configured
skipping to change at line 748 skipping to change at line 753
A nonqualified Quality Name is composed of ASCII letters, digits, and A nonqualified Quality Name is composed of ASCII letters, digits, and
$ signs, starting with a lower case letter or a $ sign (i.e., using a $ signs, starting with a lower case letter or a $ sign (i.e., using a
pattern of "[a-z$][A-Za-z$0-9]*"). Names with $ signs are intended pattern of "[a-z$][A-Za-z$0-9]*"). Names with $ signs are intended
to be used for functions separate from most other names; for to be used for functions separate from most other names; for
instance, $comment is used for the comment quality in this instance, $comment is used for the comment quality in this
specification (the presence or absence of a $comment quality does not specification (the presence or absence of a $comment quality does not
change the meaning of the SDF model). Names that are composed of change the meaning of the SDF model). Names that are composed of
multiple English words can use the "lowerCamelCase" convention multiple English words can use the "lowerCamelCase" convention
[CamelCase] for indicating the word boundaries; no other use is [CamelCase] for indicating the word boundaries; no other use is
intended for upper case letters in quality names. intended for upper case letters in Quality Names.
A qualified Quality Name is composed of a Quality Name Prefix, a : A qualified Quality Name is composed of a Quality Name Prefix, a :
(colon) character, and a nonqualified Quality Name. Quality Name (colon) character, and a nonqualified Quality Name. Quality Name
Prefixes are registered in the "Quality Name Prefixes" registry in Prefixes are registered in the "Quality Name Prefixes" registry in
the "Semantic Definition Format (SDF)" registry group the "Semantic Definition Format (SDF)" registry group
(Section 7.5.2). They are composed of lower case ASCII letters and (Section 7.5.2). They are composed of lower case ASCII letters and
digits, starting with a lowercase ASCII letter (i.e., using a pattern digits, starting with a lowercase ASCII letter (i.e., using a pattern
of "[a-z][a-z0-9]*"). of "[a-z][a-z0-9]*").
Given Names are not restricted by the formal SDF syntax. To enable Given Names are not restricted by the formal SDF syntax. To enable
non-surprising name translations in tools, combinations of ASCII non-surprising name translations in tools, combinations of ASCII
alphanumeric characters and - (ASCII hyphen/minus) are preferred, alphanumeric characters and - (ASCII hyphen/minus) are preferred,
typically employing kebab-case for names constructed out of multiple typically employing kebab-case for names constructed out of multiple
words [KebabCase]. ASCII hyphen/minus can then unambiguously be words [KebabCase]. ASCII hyphen/minus can then unambiguously be
translated to an ASCII _ underscore character and back depending on translated to an ASCII _ underscore character and back depending on
the programming environment. Some styles also allow a dot (".") in the programming environment. Some styles also allow a dot (".") in
given names. Given Names are often sufficiently self-explanatory Given Names. Given Names are often sufficiently self-explanatory
that they can be used in place of the label quality if that is not that they can be used in place of the label quality if that is not
given. In turn, if a given name turns out too complicated, a more given. In turn, if a Given Name turns out too complicated, a more
elaborate label can be given and the given name kept simple. As elaborate label can be given and the Given Name kept simple. As
given names are "programmers' names", base SDF does not address Given Names are "programmers' names", base SDF does not address
internationalization of given names. (More likely qualities to internationalization of Given Names. (More likely qualities to
receive localizable equivalents by exercising the Quality Name receive localizable equivalents by exercising the Quality Name
extension point are label and description). extension point are label and description).
Further, to enable Given Names to have a more powerful role in Further, to enable Given Names to have a more powerful role in
building global hierarchical names, an extension is planned that building global hierarchical names, an extension is foreseen that
makes use of qualified names for Given Names. So, until that makes use of qualified names for Given Names. So, until that
extension is defined, Given Names with one or more embedded colons extension is defined, Given Names with one or more embedded colons
are reserved and MUST NOT be used in an SDF document. are reserved and MUST NOT be used in an SDF document.
All names in SDF are case-sensitive. All names in SDF are case-sensitive.
3. SDF Structure 3. SDF Structure
SDF definitions are contained in SDF documents together with data SDF definitions are contained in SDF documents together with data
about the SDF document itself (information block). Definitions and about the SDF document itself (information block). Definitions and
skipping to change at line 1049 skipping to change at line 1054
* https://example.com/capability/cap#/sdfObject/Switch * https://example.com/capability/cap#/sdfObject/Switch
* https://example.com/capability/cap#/sdfObject/Switch/sdfProperty/ * https://example.com/capability/cap#/sdfObject/Switch/sdfProperty/
value value
* https://example.com/capability/cap#/sdfObject/Switch/sdfAction/on * https://example.com/capability/cap#/sdfObject/Switch/sdfAction/on
* https://example.com/capability/cap#/sdfObject/Switch/sdfAction/off * https://example.com/capability/cap#/sdfObject/Switch/sdfAction/off
* https://example.com/capability/cap#/sdfObject/Switch/sdfAction/
toggle
Note the #, which separates the absolute-URI part (Section 4.3 of RFC Note the #, which separates the absolute-URI part (Section 4.3 of RFC
3986 [STD66]) from the fragment identifier part (including the #, a 3986 [STD66]) from the fragment identifier part (including the #, a
JSON Pointer as in Section 6 of [RFC6901]). JSON Pointer as in Section 6 of [RFC6901]).
4.3. Referencing Global Names 4.3. Referencing Global Names
A name reference takes the form of the production curie in Section 3 A name reference takes the form of the production curie in Section 3
of [W3C.NOTE-curie-20101216], but limiting the IRIs involved in that of [W3C.NOTE-curie-20101216], but limiting the IRIs involved in that
grammar to URIs as per [STD66] and the prefixes to ASCII characters grammar to URIs as per [STD66] and the prefixes to ASCII characters
[STD80]. (Note that this definition does not make use of the [STD80]. (Note that this definition does not make use of the
skipping to change at line 1371 skipping to change at line 1379
Table 3: Common Qualities Table 3: Common Qualities
4.7. Data Qualities 4.7. Data Qualities
Data qualities are used in sdfData and sdfProperty definitions, which Data qualities are used in sdfData and sdfProperty definitions, which
are named sets of data qualities (abbreviated as named-sdq). are named sets of data qualities (abbreviated as named-sdq).
These qualities include the common qualities, JSO-inspired qualities These qualities include the common qualities, JSO-inspired qualities
(see below), and data qualities defined specifically for the present (see below), and data qualities defined specifically for the present
specification; the latter are shown in Table 4. None of these specification; the latter are shown in Table 4.
qualities are required or have default values that are assumed if the
quality is absent.
Appendix C lists data qualities inspired by the various proposals at Appendix C lists data qualities inspired by the various proposals at
json-schema.org; the intention is that these (information model- json-schema.org; the intention is that these (information model-
level) qualities are compatible with the (data model) semantics from level) qualities are compatible with the (data model) semantics from
the versions of the json-schema.org proposal they were imported from. the versions of the json-schema.org proposal they were imported from.
+===============+================+====================+=========+ +===============+================+====================+=========+
| Quality | Type | Description | Default | | Quality | Type | Description | Default |
+===============+================+====================+=========+ +===============+================+====================+=========+
| (common) | | Section 4.6 | | | (common) | | Section 4.6 | |
skipping to change at line 1673 skipping to change at line 1679
definitions. definitions.
Actions are used to model commands and methods that are invoked. Actions are used to model commands and methods that are invoked.
Actions may have parameter data that is supplied upon invocation and Actions may have parameter data that is supplied upon invocation and
output data that is provided as a direct result of the invocation of output data that is provided as a direct result of the invocation of
the action (note that "action objects" may also be created to furnish the action (note that "action objects" may also be created to furnish
ongoing information during a long-running action; these would be ongoing information during a long-running action; these would be
pointed to by the output data). pointed to by the output data).
The qualities of an Action definition include the common qualities. The qualities of an Action definition include the common qualities.
Additional qualities are shown in Table 8. Additional qualities are shown in Table 8. None of these qualities
are required or have default values that are assumed if the quality
is absent.
+===============+===========+============================+ +===============+===========+============================+
| Quality | Type | Description | | Quality | Type | Description |
+===============+===========+============================+ +===============+===========+============================+
| (common) | | Section 4.6 | | (common) | | Section 4.6 |
+---------------+-----------+----------------------------+ +---------------+-----------+----------------------------+
| sdfInputData | map | data qualities of the | | sdfInputData | map | data qualities of the |
| | | input data for an Action | | | | input data for an Action |
+---------------+-----------+----------------------------+ +---------------+-----------+----------------------------+
| sdfOutputData | map | data qualities of the | | sdfOutputData | map | data qualities of the |
skipping to change at line 1708 skipping to change at line 1716
5.4. sdfEvent 5.4. sdfEvent
The sdfEvent keyword denotes zero or more Event definitions. The sdfEvent keyword denotes zero or more Event definitions.
Events are used to model asynchronous occurrences that may be Events are used to model asynchronous occurrences that may be
communicated proactively. Events have data elements that are communicated proactively. Events have data elements that are
communicated upon the occurrence of the event. communicated upon the occurrence of the event.
The qualities of sdfEvent include the common qualities. Additional The qualities of sdfEvent include the common qualities. Additional
qualities are shown in Table 9. qualities are shown in Table 9. None of these qualities are required
or have default values that are assumed if the quality is absent.
+===============+===========+============================+ +===============+===========+============================+
| Quality | Type | Description | | Quality | Type | Description |
+===============+===========+============================+ +===============+===========+============================+
| (common) | | Section 4.6 | | (common) | | Section 4.6 |
+---------------+-----------+----------------------------+ +---------------+-----------+----------------------------+
| sdfOutputData | map | data qualities of the | | sdfOutputData | map | data qualities of the |
| | | output data for an Event | | | | output data for an Event |
+---------------+-----------+----------------------------+ +---------------+-----------+----------------------------+
| sdfData | named-sdq | zero or more named data | | sdfData | named-sdq | zero or more named data |
skipping to change at line 1846 skipping to change at line 1855
Figure 5: Using an Override to Further Restrict the Set of Data Figure 5: Using an Override to Further Restrict the Set of Data
Values Values
6.3. sdfThing 6.3. sdfThing
An sdfThing is a set of declarations and qualities that may be part An sdfThing is a set of declarations and qualities that may be part
of a more complex model. For example, the sdfObject declarations of a more complex model. For example, the sdfObject declarations
that make up the definition of a single socket of an outlet strip that make up the definition of a single socket of an outlet strip
could be encapsulated in an sdfThing, which itself could be used in a could be encapsulated in an sdfThing, which itself could be used in a
declaration in the sdfThing definition for the outlet strip. (See declaration in the sdfThing definition for the outlet strip. (See
Figure 7 in Appendix D.1 for parts of an SDF model for this example). Figure 7 in Appendix D.1 for parts of an SDF model for this example.)
sdfThing definitions carry semantic meaning, such as a defined sdfThing definitions carry semantic meaning, such as a defined
refrigerator compartment and a defined freezer compartment, making up refrigerator compartment and a defined freezer compartment, making up
a combination refrigerator-freezer product. An sdfThing may be a combination refrigerator-freezer product. An sdfThing may be
composed of sdfObjects and other sdfThings. It can also contain composed of sdfObjects and other sdfThings. It can also contain
sdfData definitions, as well as declarations of interaction sdfData definitions, as well as declarations of interaction
affordances itself, such as a status (on/off) for the refrigerator- affordances itself, such as a status (on/off) for the refrigerator-
freezer as a whole (see Figure 8 in Appendix D.2 for an example SDF freezer as a whole (see Figure 8 in Appendix D.2 for an example SDF
model illustrating these aspects). model illustrating these aspects).
The qualities of sdfThing are shown in Table 10. Analogous to The qualities of sdfThing are shown in Table 10. None of these
sdfObject, the presence of one or both of the optional qualities qualities are required or have default values that are assumed if the
"minItems" and "maxItems" defines the sdfThing as an array. quality is absent. Analogous to sdfObject, the presence of one or
both of the optional qualities "minItems" and "maxItems" defines the
sdfThing as an array.
+=============+===========+=============================+ +=============+===========+=============================+
| Quality | Type | Description | | Quality | Type | Description |
+=============+===========+=============================+ +=============+===========+=============================+
| (common) | | Section 4.6 | | (common) | | Section 4.6 |
+-------------+-----------+-----------------------------+ +-------------+-----------+-----------------------------+
| sdfThing | thing | | | sdfThing | thing | |
+-------------+-----------+-----------------------------+ +-------------+-----------+-----------------------------+
| sdfObject | object | | | sdfObject | object | |
+-------------+-----------+-----------------------------+ +-------------+-----------+-----------------------------+
 End of changes. 16 change blocks. 
29 lines changed or deleted 40 lines changed or added

This html diff was produced by rfcdiff 1.48.