| Internet-Draft | SDF Extension for Non-Affordance Info | June 2025 |
| Hong & Lee | Expires 20 December 2025 | [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, sdfNonAffordance, 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 20 December 2025.¶
Copyright (c) 2025 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) has been instrumental in standardizing the representation of affordances - properties, actions, and events - of Things [I-D.ietf-asdf-sdf]. However, there exists a gap in representing non-affordance information, such as location, contextual metadata, and other descriptive elements that do not directly pertain to device interactions. Addressing this gap is crucial for comprehensive device modeling, especially in applications like digital twins where holistic representations are essential.¶
This document describes a framework to extend the SDF by incorporating non-affordance information. Integrating these extensions allows SDF to provide a more comprehensive representation of Things, thereby enhancing semantic descriptions.¶
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.¶
Non-Affordance: attributes of a Thing that are not directly related to its interactive capabilities. This includes descriptive metadata such as location, manufacturer details, and other contextual information.¶
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 interactive 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 standardized representation for such information can lead to fragmented device models, hindering interoperability and the seamless integration of devices across diverse IoT ecosystems.¶
3.2.1. Asset Management and Tracking¶
Scenario: A logistics company utilizes IoT-enabled containers equipped with sensors to monitor shipments.¶
Requirement: To effectively manage and track these assets, it's crucial to have standardized data on each container's physical dimensions, weight capacity, and current location.¶
Solution: Incorporating non-affordance information into SDF allows for the uniform representation of these attributes, facilitating efficient asset tracking, optimizing load planning, and ensuring compliance with transportation regulations.¶
3.2.2. Environmental Context Awareness¶
Scenario: A smart building management system integrates various sensors and devices to monitor and control environmental conditions.¶
Requirement: Understanding the installation environment of each device, such as room location, mounting position, and surrounding materials, is essential for accurate data interpretation and optimal system performance.¶
Solution: By extending SDF to include environmental context as non-affordance information, the system can dynamically adjust operations based on device placement and environmental factors, enhancing occupant comfort and energy efficiency.¶
3.2.3. Regulatory Compliance and Certification¶
Scenario: Medical devices deployed in healthcare facilities must adhere to stringent regulatory standards and certifications.¶
Requirement: Detailed documentation of each device's manufacturer, model number, serial number, and certification information is necessary for compliance audits and maintenance schedules.¶
Solution: Embedding this non-affordance information within SDF ensures that all relevant metadata is consistently available, simplifying compliance reporting and facilitating timely maintenance and recalls when necessary.¶
By integrating non-affordance information into SDF, these use cases demonstrate how a more holistic device model enhances interoperability, operational efficiency, and compliance across various IoT applications.¶
In the SDF, the primary focus has been on defining affordances - interactive elements such as Properties, Actions, and Events - that specify how external entities can interact with a Thing. However, to achieve a more comprehensive representation of a Thing, it's essential to include non-affordance information, which encompasses attributes not directly related to interaction but crucial for understanding the Thing's context and characteristics.¶
To address this need, we propose introducing a new class named sdfNonAffordance within the SDF architecture. This class allows for the inclusion of metadata such as physical dimensions, location, environmental context, and manufacturer details.¶
This section specifies how non-affordance information is added to an SDF model and how that information can be exchanged at runtime. We deliberately split the description into two complementary subsections:¶
4.1 Static model Definition – shows how contextual metadata is embedded directly in the SDF document under the new sdfNonAffordance class. These definitions are authored once, validated like any other SDF schema fragment, and travel with the model wherever it is stored or published.¶
4.2 Run-Time Context Messaging – introduces three JSON envelopes (contextSnapshot, identityManifest, contextPatch) that let a deployed device or its digital twin report changes to that metadata over time. Keeping these messages outside the affordance model preserves the core principle that non-affordance data is descriptive, not interactive, while still allowing systems to keep the context up-to-date.¶
sdfNonAffordance is introduced as a peer to sdfProperty, sdfAction, and sdfEvent. It exists solely at design-time and captures metadata that must remain read-only in any generated interface. The construct may appear either at the sdfThing level (global context) or inside an individual sdfObject (component-specific context).¶
{
"sdfObject": {
"device": {
"description": "Environment sensor cluster",
"sdfNonAffordance": {
"installationInfo": {
"description": "Fixed deployment context (non-interactive).",
"type": "object",
"properties": {
"floor": {
"description": "Floor number where the sensor is mounted.",
"type": "integer",
"minimum": 0
},
"mountType": {
"description": "Mounting method (wall, ceiling, pole…).",
"type": "string",
"enum": ["wall", "ceiling", "pole", "desktop"]
}
},
"required": ["floor", "mountType"]
}
}
}
}
}
The model above informs tooling that floor and mountType are strictly contextual. They may be displayed in asset dashboards, but no REST or CoAP handlers should be auto-generated for them.¶
During operation, some contextual values change (e.g., a device is moved to a new room) or must be declared for audit purposes. To communicate those facts without re-classifying them as affordances, three transport-agnostic JSON envelopes for run-time context exchange are defined:¶
contextSnapshot: conveys the full, current set of non-affordance fields-such as installation information or geographic coordinates-and is typically sent at boot, on request, or during periodic audits.¶
identityManifest: declares immutable identity data (model, manufacturer, capability tags, certifications) and is normally issued once at commissioning or whenever a permanent attribute is added, for example after a firmware upgrade that introduces a new capability.¶
contextPatch: transmits only the keys that have changed since the last snapshot, minimising bandwidth when a device is moved, re-mounted, or otherwise updated in context.¶
All envelopes carry a thingId and an timestamp.¶
{
"contextSnapshot": {
"thingId": "sensor-001",
"timestamp": "2025-06-18T04:00:00Z",
"context": {
"installationInfo": {
"floor": 3,
"mountType": "wall"
},
"location": { "lat": 37.5665, "lon": 126.9780 }
}
}
}
{
"identityManifest": {
"thingId": "sensor-001",
"declaredAt": "2025-06-18T00:00:00Z",
"manifest": {
"deviceClass": "environment-sensor",
"model": "KSX-200",
"manufacturer": "KOSMOS Tech",
"capabilityTags": ["temperature", "humidity"],
"certifications": [
{ "scheme": "CE", "id": "CE-2024-12345" },
{ "scheme": "FCC", "id": "FCC-B-987654" }
]
}
}
}
{
"contextPatch": {
"thingId": "sensor-001",
"patchTime": "2025-06-20T11:30:00Z",
"changes": {
"installationInfo": {
"mountType": "ceiling"
},
"location": {
"lat": 37.5670,
"lon": 126.9790
}
}
}
}