Semantic Definition Format (SDF) Extension for Non-Affordance Information

The Semantic Definition Format (SDF) has been instrumental in standardizing the representation of affordances - properties, actions, and events - of Things . 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.

Terminology and Conventions 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 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).

Example of static model definition (sdfNonAffordance) { "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.

Example of contextSnapshot { "contextSnapshot": { "thingId": "sensor-001", "timestamp": "2025-06-18T04:00:00Z", "context": { "installationInfo": { "floor": 3, "mountType": "wall" }, "location": { "lat": 37.5665, "lon": 126.9780 } } } }

Example of identityManifest { "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" } ] } } }

Example of contextPatch { "contextPatch": { "thingId": "sensor-001", "patchTime": "2025-06-20T11:30:00Z", "changes": { "installationInfo": { "mountType": "ceiling" }, "location": { "lat": 37.5670, "lon": 126.9790 } } } }

Security Considerations TBD

IANA Considerations TBD