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 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; describes how this document relates to the other SDF documents that cover those aspects.

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 Section 1.2 of , in particular the terms Class Name Keyword, Class, Quality, Definition, Declaration, Grouping, and Affordance. 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.

Limitations of Affordance-only Modeling 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.

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

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, the updated values are reported as instance information, without altering the 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, the context of the installed device is reported to facility management systems as instance information , which enables energy optimization or fault detection algorithms to adjust thresholds and logic based on known placement.
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:: Identity and certification records are reported 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.

The sdfContext Class Name Keyword This document introduces a new Class Name Keyword, sdfContext. Base SDF defines six Class Name Keywords (Section 1.2.3 of ); 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.

Definition and Semantics 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 ). 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:

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.

Placement in an SDF Model An sdfContext group can occur in an sdfObject definition (Section 5.1 of ) and in an sdfThing definition (Section 6.3 of ), extending the content model of these Groupings, which in base SDF contain Affordance declarations only. shows the resulting structure, using the notation of Figure 2 of : it reproduces the classes and relations defined there and adds sdfContext.

Placement of sdfContext in the SDF Class Structure sdfThing | +-- 0+ hasThing -----> sdfThing +-- 0+ hasObject ----> sdfObject +-- 0+ hasProperty --> sdfProperty +-- 0+ hasEvent -----> sdfEvent +-- 0+ hasAction ----> sdfAction +-- 0+ hasContext ---> sdfContext sdfObject | +-- 0+ hasProperty --> sdfProperty +-- 0+ hasEvent -----> sdfEvent +-- 0+ hasAction ----> sdfAction +-- 0+ hasContext ---> sdfContext sdfProperty | +-- 1 isInstanceOf --> sdfData sdfEvent | +-- 0+ hasOutputData -> sdfData sdfAction | +-- 0+ hasInputData --> sdfData +-- 0+ hasOutputData -> sdfData sdfContext | +-- 1 isInstanceOf --> sdfData 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 ). 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 ). 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 ).

Qualities of sdfContext The qualities of an sdfContext definition are the data qualities defined in Section 4.7 ("Data Qualities") of , which in turn include the common qualities of Section 4.6 ("Common Qualities") of . 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. SDF-defined Qualities of sdfContext

Quality	Type	Description
(common)	-	See Section 4.6 ("Common Qualities") of , including description and label
(data)	-	See Section 4.7 ("Data Qualities") of , 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

Distinction from sdfProperty 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. summarizes the difference and the criteria for choosing sdfContext. 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
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.

Processing Requirements 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.

Examples This section gives examples of non-affordance information modeling using the sdfContext construct. to correspond to the use cases described in , and 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 ; 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.

SDF Document containing a Property and Context entries { "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" } } } } }

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. 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.

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" } } } } } } }

Environmental Context Awareness This example corresponds to . 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.

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"] } } } } }

Regulatory Compliance and Certification Aligned with , 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.

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" } } } } } } } }

Referencing External Resources 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 , which models an abstract serialization of a Web Link as an SDF data definition. As specified in , 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 , 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 .

Examples of using sdfType "link" in sdfContext { "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 ) can be used to reuse that definition instead of repeating the link parameters in every model; gives examples of this pattern. Link parameters specific to constrained environments are discussed in .

Relationship to Other SDF Documents 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 , 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 ; 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 ); 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. 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. describes how non-affordance information modeled with sdfContext is used in digital twin systems.

Security Considerations TBD

IANA Considerations TBD