Semantic Definition Format (SDF) for Data and Interactions of Things
Extracted elements (32)
Base SDF deliberately excludes protocol binding details such as URL components, numeric IDs, and payload formats. These are expected in companion Augmentation Mechanism documents, keeping the semantic model protocol-agnostic and reusable across IoT ecosystems.
Base SDF does not define a version concept for the format itself. Instead, extensibility is achieved via extension points (Quality Names and Given Names) and the features quality in the info block, avoiding version negotiation complexity while allowing incremental additions.
sdfChoice unifies JSO's enum and anyOf into a single named-alternatives construct. Named keys provide descriptive identifiers for each alternative (impossible with anonymous anyOf entries) and allow placement of dataqualities such as description per alternative.
sdfObjects are intentionally kept narrow in scope to enable broad reuse. For example, a light bulb should be modeled using separate sdfObjects for on/off, dimming, and color control, so that each can be reused across diverse product types.
Given Names containing '/' or space require two-layer encoding when used in JSON Pointer fragment identifiers: tilde-encoding of '~' and '/' per RFC 6901 Section 3, followed by percent-encoding per RFC 6901 Section 6. Avoiding such characters is recommended to sidestep interoperability problems.
SDF data qualities (sdfProperty and sdfData) are not intended to constrain wire-level payload formats; they operate at the information model level. Data definitions for protocol message payloads must be defined in protocol binding companion documents.
Given Names with one or more embedded colons are reserved and MUST NOT be used in an SDF document. This reserves the space for a future extension that enables qualified Given Names.
SDF validator tools are RECOMMENDED to emit a warning when no information block is present in an SDF document, since most processing systems require an info block as a policy.
The unit quality SHOULD use a name from the SenML Units or Secondary Units registry (RFC 8428, RFC 8798). URNs from the urn:ietf:params:unit sub-namespace MUST NOT be used as unit values except where the unit name contains a colon and cannot otherwise be expressed.
The version quality in the information block is RECOMMENDED to be lexicographically increasing over the life of a model, ideally starting with a date-time or full-date as defined in RFC 3339.
To aid interworking with JSO implementations, it is RECOMMENDED that sdfType is always used in conjunction with the type quality (e.g., type: 'string' with sdfType: 'byte-string') to yield a common JSON representation.
When an sdfType value is registered, its type quality value and JSON representation MUST be consistent with each other, following the pattern established by base SDF's byte-string and unix-time definitions.
When processing sdfRef, if the target definition itself contains an sdfRef (i.e., is based on yet another definition), that nested sdfRef MUST be processed as well before applying the outer merge patch.
An SDF Document is a single JSON map containing three logical blocks: the information block (metadata about the document), the namespaces block (namespace map and defaultNamespace), and the definitions block (groups identified by Class Name Keywords). Nested maps alternate between Quality Names and Given Names.
Global names in SDF are https:// URIs with JSON Pointer fragment identifiers. The absolute-URI is the default namespace; the fragment is derived from the JSON Pointer to the definition. These URIs are not required to be dereferenceable.
Name references in sdfRef and sdfRequired values use CURIE syntax: a namespace prefix from the namespaces block followed by ':' and a JSON Pointer. Same-document references use a bare '#' followed by a JSON Pointer without a prefix.
sdfAction models commands or methods that can go beyond reading/writing state. Actions take optional sdfInputData and sdfOutputData, may be long-running, and may result in application errors; protocol binding details are excluded from base SDF.
sdfChoice provides named alternatives for data, replacing JSO's enum (for string or typed alternatives with metadata) and anyOf (for anonymous type unions). The enum keyword is syntactic sugar for string-valued sdfChoice and cannot be used simultaneously with sdfChoice.
sdfData provides reusable named data type definitions that are shared across sdfProperty, sdfAction input/output, and sdfEvent output. sdfData entries are definitions only, not declarations; they do not create affordances directly.
sdfEvent models asynchronous occurrences communicated proactively by a Thing. Unlike sdfProperty state changes, Events may have ordering, consistency, and reliability requirements; output data is described by sdfOutputData.
sdfObject is the primary atom of reusable semantics, containing declarations of sdfProperty, sdfAction, and sdfEvent affordances. The optional minItems/maxItems qualities define the sdfObject as an indexed array of affordances.
sdfProperty models elements of state within a Thing. Its qualities include readable (default true), writable (default true), and observable (default true), plus all data qualities for constraining value structure and semantics.
sdfRef copies the qualities and enclosed definitions of a referenced definition into a new definition using the JSON Merge Patch algorithm (RFC 7396). Additional qualities in the referencing definition override the copied ones; null values remove members.
sdfRequired is an array of references indicating which declarations are mandatory within a grouping. References may be JSON Pointers, referenceable-names (affordance or grouping names without ':' or '#'), or the Boolean true to require the enclosing definition itself.
sdfThing is a Grouping that allows nested Groupings (sdfThings and sdfObjects), enabling models for complex devices with hierarchical structure. It is a superset of sdfObject and may also contain affordance declarations and sdfData.
sdfType extends the JSON type system with registered named types. Base SDF defines byte-string (base64url without padding, JSON type 'string') and unix-time (POSIX time, JSON type 'number'). Additional types may be registered in the sdfType Values registry.
The features quality in the information block lists names of critical SDF extension features that must be understood to process the document. Feature names are either registered (no colon) or URIs; SDF processors SHOULD NOT dereference URI feature names.
IANA has established four registries in the 'Semantic Definition Format (SDF)' registry group: SDF Quality Names, SDF Quality Name Prefixes, sdfType Values, and SDF Feature Names. Quality Name Prefixes follow the pattern '[a-z][a-z0-9]*'.
IANA has established the IETF URN sub-namespace urn:ietf:params:unit for unit names that require URI form due to containing a colon character. Ordinary unit names (without colons) MUST be used directly rather than through this sub-namespace.
IANA has registered CoAP Content-Format ID 434 for content type application/sdf+json (no content coding) in the CoAP Content-Formats registry within the CoRE Parameters registry group.
IANA has registered the media type application/sdf+json for SDF documents, with file extension .sdf.json. Fragment identifiers use JSON Pointer syntax per RFC 6901. Intended usage is COMMON.
Security considerations for SDF are addressed in Section 8 of RFC 9880, referenced from the application/sdf+json media type registration. As SDF documents are JSON-encoded data modeling artifacts, standard JSON processing security considerations apply to implementors.