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

Introduction The Semantic Definition Format (SDF) standardizes the representation of affordances of Things, namely Properties, Actions, and Events . 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 keyword, sdfContext, defined alongside the existing affordance classes, and provides a mechanism for expressing descriptive information that complements interactive definitions.

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. This document uses the SDF terminology defined in . In addition, the following term is used in this document:

Non-Affordance:: information about a Thing that is not directly related to its interactive capabilities. Non-affordance information does not define how external entities can act upon the Thing, but instead provides descriptive metadata useful for interpretation, management, or integration. Examples include location, manufacturer details, calibration parameters, or deployment context.

Motivation and Use Cases 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.

Motivation 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 top-level 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. While the primary focus of this document is the introduction of a static model extension via sdfContext, practical use of such metadata in real-world deployments often requires run-time mechanisms for metadata exchange. Use cases such as device onboarding, dynamic environment configuration, and regulatory audits benefit from the ability to transmit static context data as part of operational protocols. To that end, this document also introduces optional run-time messages (contextSnapshot, identityManifest, and contextPatch) that can convey non-affordance attributes at appropriate times. These messages are not the core of the SDF extension but are essential for practical interoperability, especially in systems where device metadata needs to be programmatically discovered, validated, or synchronized. Their inclusion supports real-world use cases that rely on the seamless integration of descriptive metadata into operational contexts. Thus, the proposal reflects both a modeling advancement for SDF and a run-time integration pattern to enable widespread adoption. This design accommodates ecosystem-specific metadata such as regulatory certifications, deployment regions, or vendor-specific constraints by allowing flexible attributes to be included and mapped according to the needs of each ecosystem.

Use Cases This section illustrates how non-affordance information modeled via sdfContext, contextSnapshot, identityManifest, and contextPatch 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.

Asset Management and Tracking

Scenario:: In logistics and warehouse systems, physical containers and pallets are often equipped with IoT sensors to monitor conditions such as temperature, vibration, and location. In addition, each container possesses immutable physical attributes (such as size, weight, manufacturer, and maximum load capacity) that directly influence deployment, transportation, and regulatory compliance.
Concrete Example:: For instance, a 20-foot shipping container manufactured in August 2025 would be registered with length, width, height, manufacturer name, and maximum permitted load, which never change throughout its lifecycle. These non-affordance data fields are recorded using sdfContext and are referenced whenever containers are assigned to shipping routes, loaded with cargo, or inspected by authorities.
Data Flow:: During onboarding, these static attributes are retrieved from the device's digital representation or management registry and stored in the asset management system, enabling automated planning and compliance checks. Because they are immutable, they prevent errors in cargo assignment and support maintenance audits. If placement or ownership changes are required, an update can be provided using a contextPatch message without altering the interactive model.
Value of Separation:: By distinguishing non-affordance metadata from dynamic sensor properties, the SDF model ensures that static context is protected against accidental modification, enhancing system reliability and regulatory integrity.

Environmental Context Awareness

Scenario:: Environmental sensors in smart buildings, such as temperature sensors or CO2 monitors, are installed across diverse locations (such as underground ventilation ducts or third-floor windows), which dramatically affect how sensor values should be interpreted.
Concrete Example:: A motion sensor installed on the ceiling of a conference room on the third floor would declare 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.
Data Flow:: At installation, the deployment technician registers this context information; during operation, a contextSnapshot message provides complete context to facility management systems and enables energy optimization or fault detection algorithms to adjust thresholds and logic based on known placement. This aligns with the instance-level snapshot structure discussed in , limited to static contextual data.
Value of Separation:: Separating static environmental context from dynamic sensor data streamlines calibration, reduces errors in data interpretation, and enables automated system adaptation to environmental changes without manual oversight.

Regulatory Compliance and Certification

Scenario:: In regulated environments such as healthcare, aviation, or industrial automation, each device must report immutable identification (manufacturer, model, production date) and traceable certification information to governing authorities and compliance systems.
Concrete Example:: Upon commissioning a hospital-grade infusion pump, its 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.
Data Flow:: identityManifest messages are sent during device onboarding and updates, often as the output of a construction or commissioning process, verifying compliance status. Regulatory systems query these static records to check policy enforcement, recall campaigns, and security patch eligibility.
Value of Separation:: Non-affordance identity and certification data, managed as immutable context, guarantee regulatory and operational traceability and prevent unauthorized device modifications, forming the backbone of trustworthy automated compliance.

SDF Extension for Non-Affordance Information 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, SDF does not provide a construct to represent non-affordance information, which covers attributes not directly related to interaction but needed to describe a Thing's context and characteristics. This section specifies how non-affordance information is added to an SDF model and how that information can be exchanged at run time. The description is split into two complementary subsections:

shows how contextual metadata is embedded directly in the SDF document under the new sdfContext class. These definitions are authored once, validated like any other SDF schema fragment, and travel with the model wherever it is stored or published.
introduces three JSON envelopes (contextSnapshot, identityManifest, and 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.

To address this need, this document introduces a new class keyword, sdfContext. The sdfContext keyword is a peer to sdfProperty, sdfAction, and sdfEvent, and is used to represent non-affordance information when authoring the SDF model (i.e., at design time). Definitions under sdfContext are read-only in any generated interface. Examples include location, manufacturer details, calibration parameters, installation attributes, and static identifiers. It is important to note that ecosystem-specific details can alternatively be layered onto an SDF model via an external mapping mechanism; SDF mapping files 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. The qualities of an sdfContext definition include the common qualities defined in Section 4.6 ("Common Qualities") of . Additional qualities are shown in . None of these qualities are required or have default values that are assumed if the quality is absent. SDF-defined Qualities of sdfContext

Quality	Type	Description
(common)	-	See Section 4.6 ("Common Qualities") of
type	string/object	Data type of the context item (e.g., string, number, object)
description	string	Human-readable explanation of the context item
required	array	List of mandatory context entries

Practical scenarios where sdfContext may be applied include:

Asset Management: associating static metadata such as manufacturing date, supplier, or warranty information with a device in a fleet.
Commissioning Tools: storing parameters injected during deployment (e.g., room assignment, installation coordinates) that are not otherwise observable through interactive affordances.
Calibration Metadata: describing accuracy classes or calibration factors used by the device when reporting measurements. These values are typically read-only and not exposed via a protocol interface.
Identity and Traceability: capturing serial numbers, SKU identifiers, or web resource references that uniquely characterize a device but remain constant throughout its lifecycle.

The following example defines an sdfObject that contains 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.

SDF Object containing a Property and a Context entry { "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" } } } } } To align with the use cases described in , this section introduces detailed examples of non-affordance information modeling using the sdfContext construct. Each subsection demonstrates how contextual metadata can be represented in an SDF model corresponding to a specific use case.

Static Model Definition (sdfContext) 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.

Comparison Between sdfContext and sdfProperty Although both sdfProperty and sdfContext may describe characteristics of a Thing, they differ fundamentally in purpose, mutability, and system interaction behavior. summarizes these differences. Comparison of sdfProperty and sdfContext

Aspect	sdfProperty	sdfContext
Purpose	Represents observable or modifiable affordances	Represents static descriptive information
Mutability	Typically mutable or changeable over time	Immutable after deployment
Protocol Mapping	Generates REST/CoAP/other interface endpoints	Does not generate interactive endpoints
UI Representation	Interactive elements (sliders, inputs)	Read-only fields (labels, metadata panels)
Tooling Behavior	Polled, observed, or updated via APIs	Displayed statically; excluded from interaction logic
Migration Criteria	N/A	Use if: (1) immutable, (2) non-pollable, (3) descriptive

The distinction between sdfProperty and sdfContext is important for toolchain behavior, interface generation, and user interface clarity. While both may contain descriptive data, sdfProperty is intended for values that are dynamic, observable, or settable at run time. In contrast, sdfContext is reserved for metadata that is immutable after deployment and does not participate in interaction protocols. 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. 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.

Practical Use Cases for sdfContext This section presents SDF examples that statically describe non-affordance information associated with different types of devices and use cases. Each example corresponds to a use case described in .

Example: Asset Management and Tracking The following example corresponds to the use case in . It models static metadata for a shipping container, including physical dimensions and capacity.

Asset Management and Tracking Example { "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" } } } } } } }

Example: Environmental Context Awareness This example corresponds to . It describes installation-related metadata for a building-mounted environmental sensor.

Environmental Context Awareness Example { "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"] } } } } }

Example: Regulatory Compliance and Certification Aligned with , the following SDF model defines immutable identity and certification data of a regulated device.

Regulatory Compliance and Certification Example { "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" } } } } } } } }

Using sdfType "link" for External Resource References Some context entries may refer to external documentation or digital artifacts. In such cases, it is beneficial to annotate the field with sdfType "link", as defined in . This signals that the field's value is a resolvable URI or hyperlink. Use of sdfType "link" enhances clarity and enables tools to render these values as clickable links, validate their format, or connect the SDF model to a broader ecosystem of cloud or documentation platforms. The following example illustrates how external references can be expressed within the sdfContext section using the sdfType "link" construct. Each field in this example represents a URI or hyperlink that points to an external digital resource relevant to the device but not directly part of its run-time interface. Tools and user interfaces can render such a field accordingly (e.g., as a clickable URL or embedded resource reference). The optional readable qualifier is included to emphasize that these fields are intended for display or documentation purposes.

datasheetUrl: Points to the manufacturer's datasheet, which typically contains technical specifications, electrical parameters, and physical characteristics of the device.
certificationLink: Refers to a publicly accessible certification document such as safety approvals (e.g., CE, FCC) or compliance reports.
digitalTwinUrl: Provides a reference to an external digital twin instance of the device, typically hosted in a cloud-based platform or digital thread system, allowing for visualization, monitoring, or synchronization.

These fields are not meant to be exposed through run-time protocol affordances such as CoAP or HTTP, but they enhance the expressiveness of the model for tooling, documentation, and system integration purposes.

Examples of using sdfType "link" { "sdfContext": { "datasheetUrl": { "type": "string", "sdfType": "link", "description": "Manufacturer datasheet with specifications", "readable": true }, "certificationLink": { "type": "string", "sdfType": "link", "description": "Link to the product safety certification", "readable": true }, "digitalTwinUrl": { "type": "string", "sdfType": "link", "description": "External digital twin instance", "readable": true } } }

Run-Time Context Messages 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, minimizing bandwidth when a device is moved, re-mounted, or otherwise updated in context.

Every envelope carries a thingId and a timestamp.

contextSnapshot Message The contextSnapshot message provides a complete view of a device's static non-affordance metadata. This message is typically sent upon onboarding or registration to inform the system of all contextual properties.

Example of contextSnapshot Message { "thingId": "envSensor:abc123", "timestamp": "2025-07-01T12:00:00Z", "contextSnapshot": { "installationInfo": { "floor": 3, "mountType": "ceiling", "indoorOutdoor": "indoor" } } }

identityManifest Message The identityManifest message describes immutable identity attributes of a device or asset. It can be used for device authentication or registry lookup.

Example of identityManifest Message { "thingId": "medDevice:unit42", "timestamp": "2025-07-01T08:15:00Z", "identityManifest": { "manufacturer": "HealthTech Inc.", "model": "HT-2025-M", "firmwareVersion": "1.4.3", "certifications": [ { "scheme": "FDA", "certId": "FDA123456", "region": "US" }, { "scheme": "CE", "certId": "CE987654", "region": "EU" } ] } }

contextPatch Message The contextPatch message reports changes to specific non-affordance attributes. This allows for efficient partial updates without resending the entire snapshot.

Example of contextPatch Message { "thingId": "assetContainer:box001", "timestamp": "2025-07-01T14:23:00Z", "contextPatch": { "location": { "lat": 37.5665, "lon": 126.9780 } } }

Security Considerations TBD

IANA Considerations TBD