| Internet-Draft | SDF Extension for Non-Affordance Info | October 2026 |
| Hong & Lee | Expires 30 April 2027 | [Page] |
This document describes an extension to the Semantic Definition Format (SDF)
for representing non-affordance information of Things, such as physical,
contextual, and descriptive metadata. This extension introduces a new
Class Name Keyword, sdfContext, that enables comprehensive modeling of
Things and improves semantic clarity.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 30 April 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The Semantic Definition Format (SDF) standardizes the representation of affordances of Things, namely Properties, Actions, and Events [RFC9880]. However, SDF does not currently define a way to represent non-affordance information, such as location, contextual metadata, identifiers, and other descriptive elements that are not directly related to device interactions. The absence of such constructs limits the ability to model devices and systems in use cases that require both interactive behavior and descriptive metadata.¶
This document specifies an extension to SDF to represent non-affordance
information in a consistent and interoperable way. The extension is
introduced as a new Class Name Keyword, sdfContext, defined alongside
the existing affordance classes, and provides a mechanism for expressing
descriptive information that complements interactive definitions.¶
The scope of this document is the SDF model, that is, the class level. The values that context entries take for an individual Thing, and the messages that report them, are instance information and are out of scope here; Section 6 describes how this document relates to the other SDF documents that cover those aspects.¶
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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This document uses the SDF terminology defined in Section 1.2 of [RFC9880], in particular the terms Class Name Keyword, Class, Quality, Definition, Declaration, Grouping, and Affordance. In addition, the following term is used in this document:¶
The integration of non-affordance information into the Semantic Definition Format (SDF) addresses several critical needs in the modeling of Internet of Things (IoT) devices. The key motivations and corresponding use cases in the following subsections illustrate the importance of this extension.¶
In the current SDF framework, the primary focus is on defining affordances
(interactive elements such as Properties, Actions, and Events). While this
approach effectively captures the dynamic capabilities of a Thing, it
overlooks essential non-interactive attributes that are vital for a comprehensive
device representation. These non-affordance attributes encompass contextual
information and descriptive metadata, including dimensions, weight, location,
manufacturer details, and operational constraints. The absence of a standardized
representation for such static information can lead to fragmented device models,
hindering interoperability and seamless integration across diverse IoT
ecosystems. Although it is technically possible to model such information
using sdfProperty, this approach introduces several forms of semantic confusion:¶
Users may misinterpret the field as observable or interactive: When interactive properties (e.g., sensor readings or actuators) and fixed attributes (e.g., a device's physical dimensions or serial number) are all represented as properties, it becomes unclear which elements are meant to change or be acted upon and which are immutable context. This ambiguity forces developers and tools to infer intent manually, making models harder to interpret and maintain. Over time, such models require extra documentation and care to ensure that static fields are not mistakenly treated as dynamic, adding to the maintenance burden.¶
Developers may implement unnecessary run-time I/O interfaces: Many IoT
frameworks and tools automatically create API handlers (e.g., REST
endpoints or CoAP resources) for each defined Property. If static
metadata like a device's model name or install location is modeled as
a property, a tool might erroneously generate read/write accessors for
it. This is problematic because such metadata is meant to be read-only
context, not an interactive affordance. The result is superfluous or
misleading interface endpoints that do not reflect the device's real
capabilities, potentially causing confusion or security issues. In short,
using sdfProperty for static fields violates the expectation that those
fields remain non-interactive, since the default affordance treatment
would imply they can be polled or even written to.¶
Tools and UIs may treat static metadata as operational data: SDF is meant to clearly convey a Thing's interactive capabilities versus its contextual attributes. When both are blended under the same construct, developers and automated tools may misinterpret the purpose of a given field. For example, a field representing location or manufacturer might be misconstrued as an operational parameter rather than informative metadata. This blurring of semantics makes it harder to build consistent tooling and to map SDF models to platform implementations, since one cannot reliably distinguish which elements require interactive handling. In essence, the lack of separation between affordances and non-affordances dilutes the semantic clarity of SDF models, undermining the SDF goal of an unambiguous, self-descriptive device model.¶
To address these concerns, this document introduces sdfContext as a
dedicated keyword to define static, descriptive, and non-interactive
metadata. This construct enables a clear semantic distinction from sdfProperty,
making the data model more expressive, machine-readable, and robust to
implementation assumptions.¶
This section illustrates how non-affordance information modeled with
sdfContext supports interoperability, lifecycle traceability, and
accurate interpretation of data across domains.¶
By integrating non-affordance information into SDF as described in the following use cases, a more holistic device model can be achieved: one that enhances interoperability, operational efficiency, and compliance across diverse IoT applications.¶
sdfContext and are referenced whenever containers are assigned to shipping routes, loaded with cargo, or inspected by authorities.¶
floor: 3, mountType: ceiling, and indoorOutdoor: indoor in its sdfContext. This static context enables analytics tools to filter and adjust real-time readings, for instance distinguishing between typical fluctuations due to conference room activity versus anomalies that indicate faults.¶
sdfContext includes manufacturer, model, firmwareVersion, and a set of certification records (for example, FDA certification ID, CE mark, and regulatory region). These remain unchanged during operational use and appear in device management dashboards, audit logs, and automated compliance reporting workflows.¶
This document introduces a new Class Name Keyword, sdfContext.
Base SDF defines six Class Name Keywords (Section 1.2.3 of
[RFC9880]); sdfContext is added as a peer of the affordance
keywords sdfProperty, sdfAction, and sdfEvent, and is used to
represent non-affordance information when authoring the SDF model (i.e., at
design time). Examples include location, manufacturer details, calibration
parameters, installation attributes, and static identifiers.¶
The sdfContext keyword denotes a group of zero or more Context
definitions. A Context definition is a named set of data qualities, as are
sdfData and sdfProperty definitions (Section 4.7 of
[RFC9880]).¶
The sdfContext class is intended for non-affordance information that is
static or metadata-oriented. These are values that are expected to be
known at design time, provisioned at deployment time, or extracted from
static documentation or identity stores. Examples include manufacturer
name, model number, location of deployment, or contact email for support.¶
A Context definition describes what a value means and how it is
structured; it does not declare an interaction. Entries under
sdfContext are not Affordances, they do not take part in interaction
protocols, and they are read-only in any generated interface.¶
Practical scenarios where sdfContext may be applied include:¶
An sdfContext group can occur in an sdfObject definition
(Section 5.1 of [RFC9880]) and in an sdfThing definition
(Section 6.3 of [RFC9880]), extending the content model of these
Groupings, which in base SDF contain Affordance declarations only.
Figure 1 shows the resulting structure, using the
notation of Figure 2 of [RFC9880]: it reproduces the classes and
relations defined there and adds sdfContext.¶
Context definitions are named in the same way as other SDF definitions, and
a Context definition can reuse an existing definition through the
sdfRef quality (Section 4.4 of [RFC9880]).¶
An sdfContext group occurs only in sdfObject and sdfThing
definitions; sdfContext is not among the keywords that can be used at the
top level of a definitions block (Section 3.4 of [RFC9880]).
A Context definition that is intended for reuse across models is factored out
as an sdfData definition and referenced with sdfRef.¶
This document does not define the use of Context definitions in
sdfRequired (Section 4.5 of [RFC9880]).¶
The qualities of an sdfContext definition are the data qualities defined
in Section 4.7 ("Data Qualities") of [RFC9880], which in turn
include the common qualities of Section 4.6 ("Common Qualities") of
[RFC9880]. Table 1 summarizes the qualities
that are most relevant for non-affordance information. None of these qualities
are required or have default values that are assumed if the quality is absent.¶
| Quality | Type | Description |
|---|---|---|
| (common) | - | See Section 4.6 ("Common Qualities") of [RFC9880], including description and label |
| (data) | - | See Section 4.7 ("Data Qualities") of [RFC9880], including type, unit, contentFormat, sdfType, and enum |
| const | (as per type) | Fixed value of the context entry, for information that is already known when the model is authored or provisioned |
A Context definition and a Property definition are both named sets of data
qualities, and both may describe characteristics of a Thing. The question of
which one to use is answered by what the value does, not by how it is
written. Table 2 summarizes the difference and
the criteria for choosing sdfContext.¶
| Aspect | sdfProperty | sdfContext |
|---|---|---|
| Purpose | Represents observable or modifiable affordances | Represents static descriptive information |
| Mutability | Typically mutable or changeable over time | Immutable after deployment |
| Migration Criteria | N/A | Use if: (1) immutable, (2) non-pollable, (3) descriptive |
For example, a sensor's temperature reading should be modeled as an
sdfProperty since it changes over time and clients may want to poll or
subscribe to it. However, a serial number or installation date should
be modeled as sdfContext, as these are assigned once and do not change
or require polling.¶
Some values sit between the two. A firmware version does change, but only when the device is updated, and clients do not poll it as part of normal operation. The criterion is not how often a value changes, but whether a client is expected to read or write it through an interface of the Thing: where it is, the value is a Property; where it is not, it is context. Where both are needed, a model can define a Context entry for the descriptive record and a Property for the value that clients interact with.¶
From an implementation perspective, tools MUST NOT generate GET/PUT
endpoints for sdfContext, and UI frameworks SHOULD render these values
as static labels or metadata panels. If an existing model contains
sdfProperty entries that are read-only and represent metadata,
they MAY be migrated to sdfContext for semantic clarity.¶
Entries under sdfContext are not exposed through run-time protocol
affordances such as CoAP or HTTP; they enhance the expressiveness of the
model for tooling, documentation, and system integration purposes.¶
This section gives examples of non-affordance information modeling using the
sdfContext construct. Section 5.1 to
Section 5.3 correspond to the use cases described in
Section 3.2, and Section 5.4 shows how an entry
can point to an external resource. Several of the examples use the data
qualities properties and required of the type "object", which are
defined in Appendix C.5 of [RFC9880]; as noted there, the
quality properties is unrelated to sdfProperty.¶
The following example is a complete SDF document that defines an
sdfObject containing both an affordance
and several non-affordance attributes. The affordance is represented as a
temperature property, which is a numeric value in degrees Celsius.
The non-affordance attributes are grouped under sdfContext. These include
a serialNumber, which is a factory-assigned identifier; an installationLocation,
which indicates where the device is deployed within a building;
and a calibrationOffset, which specifies a correction value applied
to raw sensor measurements. Together, these definitions illustrate how sdfContext
can capture descriptive metadata that is not directly interactive but still
essential for interpretation and integration. The examples in the following
subsections show only the definitions themselves, without the information
block and the namespaces block.¶
{
"info": {
"title": "Example document for sdfContext",
"version": "2026-10-27",
"copyright": "Copyright 2026 Example Corp. All rights reserved.",
"license": "https://example.com/license"
},
"namespace": {
"cap": "https://example.com/capability/cap"
},
"defaultNamespace": "cap",
"sdfObject": {
"deviceWithContext": {
"sdfProperty": {
"temperature": {
"type": "number",
"unit": "°C"
}
},
"sdfContext": {
"serialNumber": {
"type": "string",
"description": "Unique factory-assigned identifier"
},
"installationLocation": {
"type": "string",
"description": "Installation location in the building"
},
"calibrationOffset": {
"type": "number",
"unit": "°C",
"description": "Offset applied to raw measurements"
}
}
}
}
}
The following example corresponds to the use case in Section 3.2.1.
It models static metadata for a shipping container, including physical
dimensions and capacity. The entry physicalSpecs is an object whose four
members are all listed in required, while the members of location
are not, so that a model can carry the dimensions of a container without
fixing where it is.¶
{
"sdfObject": {
"assetContainer": {
"description": "Shipping container with embedded sensors",
"sdfContext": {
"physicalSpecs": {
"description": "Physical dimensions and capacity",
"type": "object",
"properties": {
"length": { "type": "number", "unit": "m" },
"width": { "type": "number", "unit": "m" },
"height": { "type": "number", "unit": "m" },
"maxLoadKg": { "type": "number", "unit": "kg" }
},
"required": ["length", "width", "height", "maxLoadKg"]
},
"location": {
"type": "object",
"properties": {
"lat": { "type": "number" },
"lon": { "type": "number" }
}
}
}
}
}
}
This example corresponds to Section 3.2.2. It describes installation-related
metadata for a building-mounted environmental sensor. The enum quality
restricts how a mounting position and an indoor or outdoor placement can be
expressed, so that analytics tools can rely on a fixed set of values.¶
{
"sdfObject": {
"envSensor": {
"description": "Environmental sensor unit",
"sdfContext": {
"installationInfo": {
"type": "object",
"properties": {
"floor": { "type": "integer" },
"mountType": {
"type": "string",
"enum": ["wall", "ceiling", "window"]
},
"indoorOutdoor": {
"type": "string",
"enum": ["indoor", "outdoor"]
}
},
"required": ["floor", "mountType"]
}
}
}
}
}
Aligned with Section 3.2.3, the following SDF model defines immutable
identity and certification data of a regulated device. Here the information
describes the device as a whole rather than one of its functional blocks, so
the sdfContext group is placed in an sdfThing definition; the
certification records are modeled as an array of objects, since a device can
carry several of them.¶
{
"sdfThing": {
"deviceMetadata": {
"sdfContext": {
"identity": {
"type": "object",
"properties": {
"manufacturer": { "type": "string" },
"model": { "type": "string" },
"firmwareVersion": { "type": "string" }
}
},
"certifications": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scheme": { "type": "string" },
"certId": { "type": "string" },
"region": { "type": "string" }
}
}
}
}
}
}
}
Some context entries do not carry a value of their own but point to an
external resource, such as a manufacturer datasheet, a certification
document, or a digital twin instance hosted on another platform. Such
entries are modeled with the sdfType "link" defined in
[I-D.ietf-asdf-sdftype-link], which models an abstract
serialization of a Web Link [RFC8288] as an SDF data
definition.¶
As specified in [I-D.ietf-asdf-sdftype-link], a definition
using sdfType "link" is used with the SDF type "object".
The members of that object are named after the link parameter (attribute)
names of [RFC8288], and the special member name href
carries the link target. Only the link parameters that the model constrains
need to be declared. A context entry that identifies an external resource
declares href alone; further parameters, such as a link relation type
or a media type, can be added where the model constrains them, and the
const quality can be used to pin a parameter whose value is fixed when
the model is authored.¶
The following example defines three external references in the
sdfContext of a device. Each entry is an object-typed definition with
sdfType "link" and declares href as the link target; the
description quality carries the human-readable explanation of what
the link points to.¶
datasheetLink: the manufacturer's datasheet, which typically contains
technical specifications, electrical parameters, and physical
characteristics of the device.¶
certificationLink: a publicly accessible certification document such as
a safety approval (e.g., CE, FCC) or a compliance report.¶
digitalTwinLink: an external digital twin instance of the device,
typically hosted in a cloud-based platform or digital thread system,
used for visualization, monitoring, or synchronization
[I-D.ietf-asdf-digital-twin].¶
{
"sdfObject": {
"deviceWithLinks": {
"description": "Device with references to external resources",
"sdfContext": {
"datasheetLink": {
"type": "object",
"sdfType": "link",
"description": "Link to the manufacturer's datasheet",
"properties": {
"href": {
"type": "string"
}
}
},
"certificationLink": {
"type": "object",
"sdfType": "link",
"description": "Link to the product safety certification",
"properties": {
"href": {
"type": "string"
}
}
},
"digitalTwinLink": {
"type": "object",
"sdfType": "link",
"description": "Link to an external digital twin",
"properties": {
"href": {
"type": "string"
}
}
}
}
}
}
}
Where an ecosystem already publishes a link definition, the sdfRef
quality (Section 4.4 of [RFC9880]) can be used to reuse that
definition instead of repeating the link parameters in every model;
[I-D.ietf-asdf-sdftype-link] gives examples of this pattern.
Link parameters specific to constrained environments are discussed in
[RFC6690].¶
This document defines class-level modeling only. The value that a context
entry takes for an individual Thing is instance information: it is
established when the Thing is deployed and can change over its lifetime,
for example when a device is moved to another room or when a certification
is renewed. Reporting and updating such values is specified in
[I-D.ietf-asdf-instance-information], which defines
instance-related messages for SDF models. An sdfContext definition
governs the context values carried in those messages: the names and the data
qualities of the definitions determine what a conforming instance may report.¶
The general semantics of the sdfType "link" are specified in
[I-D.ietf-asdf-sdftype-link]; Section 5.4 only
shows how such a definition is used within an sdfContext group.¶
Ecosystem-specific details can alternatively be layered onto an SDF model
by an Augmentation Mechanism (Section 1.2.3 of [RFC9880]); SDF
mapping files [I-D.ietf-asdf-sdf-mapping] provide a way to augment
a base model with additional qualities or metadata. The sdfContext
extension defined in this document complements that approach by providing
a first-class construct within the model for static context, ensuring
that such metadata is uniformly available and semantically distinguished
in the core specification of a Thing. Ecosystem-specific metadata such as
regulatory certifications, deployment regions, or vendor-specific
constraints can be included and mapped according to the needs of each
ecosystem.¶
[I-D.ietf-asdf-digital-twin] describes how non-affordance
information modeled with sdfContext is used in digital twin systems.¶