]> Cisco Systems

170 West Tasman Drive San Jose 95134 USA rohitmo@cisco.com

Cisco Systems

170 West Tasman Drive San Jose 95134 USA bbrinckm@cisco.com

Ericsson

Hirsalantie 11 Jorvas 1296 Finland lorenzo.corneo@ericsson.com

Applications and Real-Time A Semantic Definition Format for Data and Interactions of Things IoT This document defines protocol mapping extensions for the Semantic Definition Format (SDF) to enable mapping of protocol-agnostic SDF affordances to protocol-specific operations. The protocol mapping mechanism allows SDF models to specify how properties, actions, and events should be accessed using a specific protocol. This document defines protocol mappings for Bluetooth Low Energy and Zigbee, and the mechanism can be extended to other protocols such as HTTP and CoAP. This document also describes a method to extend SCIM with an SDF model mapping. About This Document Status information for this document may be found at . Discussion of this document takes place on the A Semantic Definition Format for Data and Interactions of Things Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The Semantic Definition Format (SDF) provides a protocol-agnostic way to describe IoT devices and their capabilities through properties, actions, and events (collectively called affordances). A device described by an SDF model, however, is accessed over a specific communication protocol. To interact with such a device based on its SDF model, there needs to be a mechanism to map the protocol-agnostic SDF definitions to the protocol-specific operations that access the device. Moreover, such a mechanism needs to be extensible for enabling implementers to provide novel SDF protocol mappings to expand the SDF ecosystem. SDF protocol mappings may target a variety of protocols spanning from non-IP protocols commonly used in IoT environments, such as and , to IP-based protocols such as HTTP and CoAP . This document provides the required mechanism by defining:

• The sdfProtocolMap quality, which allows SDF models to include protocol-specific mapping information attached to the protocol-agnostic definitions, see . An sdfProtocolMap MAY be applied to an SDF affordance, be it an sdfProperty, sdfEvent or sdfAction. The mapping enables use cases such as application gateways or multi-protocol gateways that translate between different IoT protocols, automated generation of protocol-specific implementations from SDF models, and interoperability across heterogeneous device ecosystems.
• Two SDF protocol mappings for Bluetooth and Zigbee protocols, see and respectively.
• An SDF model extension for SCIM. While SDF provides a way to describe a class of devices, SCIM describes a device instance. The SDF model extension for SCIM enables the inclusion of SDF models for the class of devices a device belongs to in the SCIM object, see .
• An IANA registry for defining additional SDF protocol mappings (in addition to the BLE and Zigbee provided in this document), see .

Conventions and Definitions The syntax extensions to are shown in the Concise Data Definition Language (CDDL) , which describes their JSON representation. 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.

SDF Protocol Mapping Structure This section defines the structure of an sdfProtocolMap. Because each protocol has its own addressing model, a single SDF affordance requires a distinct mapping per protocol. For example, BLE addresses a property as a service characteristic, while Zigbee addresses it as an attribute in a cluster of an endpoint. The value of the sdfProtocolMap quality is a JSON object nested inside an SDF affordance definition (sdfProperty, sdfAction, or sdfEvent). Protocol-specific attributes are embedded within this object, keyed by a protocol name registered in the IANA "SDF Protocol Mapping" registry (), e.g., "ble" or "zigbee".

SDF Protocol Mapping Structure sdfProtocolMap | +-----> ble | | | +--> BLE-specific mapping | +-----> zigbee | | | +--> Zigbee-specific mapping | +-----> ... ]]>

SDF Extension Points The sdfProtocolMap quality is introduced into SDF affordance definitions through the extension points defined in the formal syntax of . For each affordance type, an sdfProtocolMap entry is added via the corresponding CDDL group socket. The contents of the sdfProtocolMap object are in turn extensible through a protocol-mapping-specific group socket. A protocol MAY choose to extend only the affordance types that are applicable to it. For example, the BLE protocol mapping defines extensions for properties and events but not for actions.

Property Extension The $$SDF-EXTENSION-PROPERTY group socket in the propertyqualities rule of is used to add protocol mapping to sdfProperty definitions:

SDF Property Extension Point for Protocol Mapping = ( name => props / { read: read-props, write: write-props } ) ]]>

The property-protocol-map generic () captures the common structure of property protocol mappings. The name parameter is the protocol name and props is the protocol-specific map of attributes. A protocol can provide either:

• A single mapping that applies to both read and write operations, or
• Separate read and write mappings when the protocol uses different attributes for each direction.

To keep these two forms unambiguous, the protocol-specific attribute map (the props type) MUST NOT define members named read or write. To extend $$SDF-PROPERTY-PROTOCOL-MAP for a new protocol (e.g., "new-protocol"), implementers MUST use the property-protocol-map generic with the protocol name and a map type defining the protocol-specific attributes. It is to be noted that the protocol name (e.g., "new-protocol") MUST be registered in the IANA registry defined in . For example:

Example Property Protocol Map Extension ) new-protocol-property = { attributeA: text, attributeB: uint } ]]>

An SDF model using this extension could look like:

Example Property Protocol Map in JSON

When a property uses different protocol attributes for read and write operations, the mapping can be split:

Example Property Protocol Map with Read/Write in JSON

Action Extension The $$SDF-EXTENSION-ACTION group socket in the actionqualities rule of is used to add protocol mapping to sdfAction definitions:

SDF Action Extension Point for Protocol Mapping

Actions use a simpler structure than properties, as they do not require the read/write distinction. To extend $$SDF-ACTION-PROTOCOL-MAP for a new protocol, implementers MUST add a group entry that maps the protocol name to the protocol-specific attributes. For example, an extension for a fictitious "new-protocol" could be defined as:

Example Action Protocol Map Extension

An SDF model using this extension could look like:

Example Action Protocol Map in JSON

Event Extension The $$SDF-EXTENSION-EVENT group socket in the eventqualities rule of is used to add protocol mapping to sdfEvent definitions:

SDF Event Extension Point for Protocol Mapping

Events follow the same simple pattern as actions. To extend $$SDF-EVENT-PROTOCOL-MAP for a new protocol, implementers add a group entry that maps the protocol name to the protocol-specific attributes. For example, an extension for a fictitious "new-protocol" could be defined as:

Example Event Protocol Map Extension

An SDF model using this extension could look like:

Example Event Protocol Map in JSON

New Protocol Registration Procedure Protocol names used as keys in the sdfProtocolMap object (e.g., "ble", "zigbee") MUST be registered in the IANA registry defined in . A new SDF protocol mapping MUST be defined by a specification that mandatorily includes:

• A CDDL definition that extends at least one of the group sockets defined in this document: $$SDF-PROPERTY-PROTOCOL-MAP (), $$SDF-ACTION-PROTOCOL-MAP (), or $$SDF-EVENT-PROTOCOL-MAP (). Property mappings MUST use the property-protocol-map generic () to ensure a consistent structure.
• A description of the protocol-specific attributes introduced by the CDDL extension, including their semantics and how they relate to the underlying protocol operations.

Registered Protocol Mappings This section defines the protocol mappings registered by this document.

BLE The BLE protocol mapping allows SDF models to specify how properties and events should be accessed using Bluetooth Low Energy (BLE) protocol . The mapping includes details such as service IDs and characteristic IDs that are used to access the corresponding SDF affordances.

Properties For sdfProperty, the BLE protocol mapping structure is defined as follows:

CDDL definition for BLE Protocol Mapping for sdfProperty ) ble-property = { serviceID: text, characteristicID: text } ]]>

Where:

• serviceID is the BLE service ID that corresponds to the SDF property.
• characteristicID is the BLE characteristic ID that corresponds to the SDF property.

For example, a BLE protocol mapping for a temperature property: For a temperature property that has different mappings for read and write operations, here is an example of the BLE protocol mapping:

Events For sdfEvents, the BLE protocol mapping structure is similar to sdfProperties, but it MUST include additional attributes such as the type of the event.

BLE Protocol Mapping for sdfEvents

Where:

• type specifies the type of BLE event, such as "gatt" for GATT events, "advertisements" for advertisement events, or "connection_events" for connection-related events.
• serviceID and characteristicID identify the GATT service and characteristic. They MUST be present when type is "gatt", and MUST be absent when type is "advertisements" or "connection_events".

For example, a BLE event mapping for a heart rate measurement event: Here is an example of an isPresent event using BLE advertisements:

Zigbee The Zigbee protocol mapping allows SDF models to specify how properties, actions, and events should be accessed using the Zigbee protocol . The mapping includes details such as cluster IDs and attribute IDs that are used to access the corresponding SDF affordances.

Properties An sdfProperty is mapped to a Zigbee cluster attribute. The Zigbee property protocol mapping structure is defined as follows:

CDDL definition for Zigbee Protocol Mapping for sdfProperty ) zigbee-property = { endpointID: uint, clusterID: uint, attributeID: uint, attributeType: uint, ? profileID: uint, ? manufacturerCode: uint, } ]]>

Where:

• endpointID is the Zigbee endpoint ID that corresponds to the SDF property.
• clusterID is the Zigbee cluster ID that corresponds to the SDF property.
• attributeID is the Zigbee attribute ID that corresponds to the SDF property.
• attributeType is the Zigbee data type of the attribute.
• profileID is the Zigbee application profile ID (optional). If not provided, it defaults to the Home Automation profile (0x0104), which is the default profile in Zigbee 3.0.
• manufacturerCode is the Zigbee manufacturer code of the attribute (optional).

For example, a Zigbee protocol mapping for a temperature property may look as follows:

Events An sdfEvent is mapped to a Zigbee cluster event such as attribute reporting or a device-initiated write to an attribute on the gateway. The Zigbee event protocol mapping structure is defined as follows. The "attribute_reporting" and "write_event" variants reuse the zigbee-property definition from to identify the underlying Zigbee attribute:

CDDL definition for Zigbee Protocol Mapping for sdfEvents

Where:

• type is the type of Zigbee event. It MUST be one of:
  • "attribute_reporting": the event is triggered by Zigbee attribute reporting.
  • "write_event": the event is triggered by the device writing to an attribute on the gateway.
  • "connection_events": the event is triggered when a Zigbee end device joins or leaves the Zigbee network.
• endpointID, clusterID, attributeID, attributeType, profileID, and manufacturerCode have the same meaning as described for sdfProperty in . These fields are present when type is "attribute_reporting" or "write_event", and MUST be absent when type is "connection_events".
• minReportingInterval is the minimum reporting interval in seconds (optional). It is the minimum time between issued attribute reports and only applies when type is "attribute_reporting".
• maxReportingInterval is the maximum reporting interval in seconds (optional). It is the maximum time between issued attribute reports and only applies when type is "attribute_reporting".
• reportableChange is the minimum change to the attribute value that triggers a report (optional). It only applies when type is "attribute_reporting" and to attributes whose attributeType is one of the "analog" data types defined by the Zigbee Cluster Library, part of (e.g., unsigned and signed integers, floating point numbers), as opposed to "discrete" data types (e.g., booleans, enumerations, bitmaps), for which reporting a minimum change is not meaningful. The encoded value MUST use the same Zigbee data type as the reported attribute's attributeType.

For example, a Zigbee event mapping for a temperature change report: Here is an example of an isPresent event using Zigbee connection events:

Actions An sdfAction is mapped to a Zigbee cluster command. The Zigbee protocol mapping structure for actions is defined as follows:

CDDL definition for Zigbee Protocol Mapping for sdfAction

Where:

• endpointID is the Zigbee endpoint ID that corresponds to the SDF action.
• clusterID is the Zigbee cluster ID that corresponds to the SDF action.
• commandID is the Zigbee command ID that corresponds to the SDF action.
• profileID is the Zigbee application profile ID (optional). If not provided, it defaults to the Home Automation profile (0x0104), which is the default profile in Zigbee 3.0.
• manufacturerCode is the Zigbee manufacturer code of the command (optional).

For example, a Zigbee protocol mapping to set a temperature:

SCIM SDF Extension While SDF provides a way to describe a device class and SCIM defines a device instance, a method is needed to associate a mapping between an instance of a device and its associated SDF models. To accomplish so, this document defines a SCIM extension that MAY be used in conjunction with in . Implementation of this SCIM extension is OPTIONAL and independent of the protocol mapping functionality defined in the rest of this document. The SCIM schema attributes used here are described in Section 7 of .

SCIM SDF Extension Schema

Here is an example SCIM device schema extension with SDF models: An SDF model MUST be referenced with the sdf keyword inside the SCIM device schema as described in .

Security Considerations The security considerations of apply to this document as well. Each protocol mapped using this mechanism has its own security model. The protocol mapping mechanism defined in this document does not provide additional security beyond what is offered by the underlying protocols. Implementations MUST ensure that appropriate protocol-level security mechanisms are employed when accessing affordances through the mapped protocol operations.

IANA Considerations This section provides guidance to the Internet Assigned Numbers Authority (IANA) regarding registration of values related to this document, in accordance with .

Protocol Mapping IANA is requested to create a new registry called "SDF Protocol Mapping" in the "Semantic Definition Format (SDF)" registry group , with the following template:

• Protocol map name, as per sdfProtocolMap
• Protocol name
• Description
• Reference of the specification describing the protocol mapping.

The registration policy for this registry is "Specification Required" as defined in Section 4.6 of . The specification requirements for a registration request are defined in . The designated expert(s) MUST verify that the protocol map name is appropriate and not likely to cause confusion with existing entries. The registrant of an existing entry may request updates to that entry, subject to the same expert review. They should verify that updates preserve backward compatibility with deployed implementations, or if breaking changes are necessary, consider whether a new registry entry is more appropriate. The following protocol mappings are described in this document: Protocol Mapping Registry

Protocol Map Name	Protocol Name	Description	Reference
ble	Bluetooth Low Energy (BLE)	Protocol mapping for BLE devices	This document,
zigbee	Zigbee	Protocol mapping for Zigbee devices	This document,

SCIM Device Schema SDF Extension IANA is requested to create the following extension in the "SCIM Server-Related Schema URIs" registry, within the "System for Cross-domain Identity Management (SCIM) Schema URIs" registry group , as described in : SCIM Device Schema SDF Extension

URN	Description	Resource Type	Reference
urn:ietf:params:scim: schemas:extension: sdf:2.0:Device	SDF Extension	Device	This document,

References Normative References This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. The Semantic Definition Format (SDF) is a format for domain experts to use in the creation and maintenance of data and interaction models that describe Things, i.e., physical objects that are available for interaction over a network. An SDF specification describes definitions of SDF Objects/SDF Things and their associated interactions (Events, Actions, and Properties), as well as the Data types for the information exchanged in those interactions. Tools convert this format to database formats and other serializations as needed. The initial core schema for the System for Cross-domain Identity Management (SCIM) was designed for provisioning users. This memo specifies schema extensions that enable provisioning of devices using various underlying bootstrapping systems such as Wi-Fi Easy Connect, FIDO device onboarding vouchers, Bluetooth Low Energy (BLE) passcodes, and MAC Authenticated Bypass (MAB). In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The System for Cross-domain Identity Management (SCIM) specifications are designed to make identity management in cloud-based applications and services easier. The specification suite builds upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. Its intent is to reduce the cost and complexity of user management operations by providing a common user schema and extension model as well as binding documents to provide patterns for exchanging this schema using HTTP. This document provides a platform-neutral schema and extension model for representing users and groups and other resource types in JSON format. This schema is intended for exchange and use with cloud service providers. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. IANA IANA Informative References Bluetooth SIG CSA IoT The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments.

CDDL Definition This appendix contains the combined CDDL definitions for the SDF protocol mappings.

CDDL for SDF protocol mappings = ( name => props / { read: read-props, write: write-props } ) $$SDF-EXTENSION-ACTION //= ( sdfProtocolMap: { * $$SDF-ACTION-PROTOCOL-MAP } ) $$SDF-EXTENSION-EVENT //= ( sdfProtocolMap: { * $$SDF-EVENT-PROTOCOL-MAP } ) $$SDF-PROPERTY-PROTOCOL-MAP //= ( property-protocol-map<"ble", ble-property, ble-property, ble-\ property> ) ble-property = { serviceID: text, characteristicID: text } $$SDF-EVENT-PROTOCOL-MAP //= ( ble: ble-event-map ) ble-event-map = { type: "gatt", serviceID: text, characteristicID: text } / { type: "advertisements" } / { type: "connection_events" } $$SDF-PROPERTY-PROTOCOL-MAP //= ( property-protocol-map<"zigbee", zigbee-property, zigbee-property, \ zigbee-property> ) zigbee-property = { endpointID: uint, clusterID: uint, attributeID: uint, attributeType: uint, ? profileID: uint, ? manufacturerCode: uint, } $$SDF-EVENT-PROTOCOL-MAP //= ( zigbee: zigbee-event-map ) zigbee-event-map = zigbee-attribute-reporting / zigbee-write-event \ / zigbee-connection-event zigbee-attribute-reporting = { type: "attribute_reporting", ~zigbee-property, ? minReportingInterval: uint, ? maxReportingInterval: uint, ? reportableChange: number, } zigbee-write-event = { type: "write_event", ~zigbee-property, } zigbee-connection-event = { type: "connection_events", } $$SDF-ACTION-PROTOCOL-MAP //= ( zigbee: zigbee-action-map ) zigbee-action-map = { endpointID: uint, clusterID: uint, commandID: uint, ? profileID: uint, ? manufacturerCode: uint, } ]]>

OpenAPI Definition The following non-normative model is provided for convenience of the implementer.

OpenAPI model

Protocol map for BLE

OpenAPI model for BLE

Protocol map for Zigbee

OpenAPI model for Zigbee

Acknowledgements This document relies on SDF models described in , as such, we are grateful to the authors of this document for putting their time and effort into defining SDF in depth, allowing us to make use of it. The authors are grateful to Carsten Bormann, Jan Romann, Ari Keränen, and Eliot Lear for their reviews and contributions to this document, in particular Jan Romann for his help with the CDDL definitions () and Eliot Lear for his contributions to .