]> 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 specific IP and non-IP protocols such as Bluetooth Low Energy, Zigbee or HTTP and CoAP. 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). However, when implementing these affordances on actual devices using specific communication protocols, there needs to be a mechanism to map the protocol-agnostic SDF definitions to protocol-specific operations. These protocols can be non-IP protocols that are commonly used in IoT environments, such as and , or IP-based protocols, such as HTTP or CoAP . To leverage an SDF model to perform protocol-specific operations on an instance of a device, a mapping of the SDF affordance to a protocol-specific attribute is required. This document defines the protocol mapping mechanism using the sdfProtocolMap keyword, which allows SDF models to include protocol-specific mapping information alongside the protocol-agnostic definitions.

Conventions and Definitions 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.

Structure Protocol mapping is required to map a protocol-agnostic affordance to a protocol-specific operation, as implementations of the same affordance will differ between protocols. For example, BLE will address a property as a service characteristic, while a property in Zigbee is addressed as an attribute in a cluster of an endpoint. A protocol mapping object is a JSON object identified by the sdfProtocolMap keyword. Protocol-specific properties are embedded within this object, organized by protocol name, e.g., "ble" or "zigbee". The protocol name MUST be specified in the IANA registry requested in .

Property Mapping ble | | | +--> BLE-specific mapping | +-----> zigbee | | | +--> Zigbee-specific mapping | +-----> openapi | +--> OpenAPI-specific mapping ]]>

As shown in , protocol-specific properties must be embedded in an sdfProtocolMap object, for example a "ble" or a "zigbee" object. Protocol objects

Attribute	Type	Example
ble	object	an object with BLE-specific attributes
zigbee	object	an object with Zigbee-specific attributes
openapi	object	an object with OpenAPI-specific attributes

where-

• "ble" is an object containing properties that are specific to the BLE protocol.
• "zigbee" is an object containing properties that are specific to the Zigbee protocol.
• Other protocol mapping objects can be added by creating a new protocol object

Example protocol mapping:

Example property mapping

For properties that have a different protocol mapping for read and write operations, the protocol mapping can be specified as such:

Example property mapping

Usage A protocol map MAY be provided as part of the SDF model, specifically in the SDF affordance definition. The extension points in the SDF affordance definition defined in are used to specify the protocol mapping information as a part of the SDF model. For SDF properties, the protocol mapping is specified as an extension to a named property quality using the sdfProtocolMap keyword. For SDF actions and events, the protocol mapping can be specified as an extension to the named quality or as part of the sdfInputData or sdfOutputData objects.

Examples

BLE Protocol Mapping The BLE protocol mapping allows SDF models to specify how properties, actions, 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.

BLE Protocol Mapping Structure For SDF properties and actions, the BLE protocol mapping structure is defined as follows:

CDDL definition for BLE Protocol Mapping for properties and actions

Where:

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

For example, a BLE protocol mapping for a temperature property might look like: For a temperature property that has different mappings for read and write operations, the BLE protocol mapping might look like: For SDF events, the BLE protocol mapping structure is similar, but it may include additional attributes such as the type of the event.

BLE Protocol Mapping for events

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 are optional attributes that are specified if the type is "gatt".

For example, a BLE event mapping for a heart rate measurement event might look like: Another example of an isPresent event using BLE advertisements:

Zigbee Protocol Mapping 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.

Zigbee Protocol Mapping Structure For SDF properties and events, the Zigbee protocol mapping structure is defined as follows:

CDDL definition for Zigbee Protocol Mapping for properties and actions

Where:

• endpointID is the Zigbee endpoint ID that corresponds to the SDF affordance.
• clusterID is the Zigbee cluster ID that corresponds to the SDF affordance.
• attributeID is the Zigbee attribute ID that corresponds to the SDF affordance.
• type is the Zigbee data type of the attribute.

SDF properties are mapped to Zigbee cluster attributes and events are mapped to Zigbee cluster attribute reporting. For example, a Zigbee protocol mapping for a temperature property might look like: SDF actions are mapped to Zigbee cluster commands. The Zigbee protocol mapping structure for actions is defined as follows:

CDDL definition for Zigbee Protocol Mapping for actions

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.

For example, a Zigbee protocol mapping to set a temperature might look like:

IP based Protocol Mapping The protocol mapping mechanism can potentially also be used for IP-based protocols such as HTTP or CoAP. In the case of HTTP, SDF protocol mappings towards an SDF quality MAY be expressed by directly pointing to OpenAPI schema and/or component. An example of a protocol mapping for a property using HTTP might look like: The operationRef points to the OpenAPI operation that retrieves the current heart rate, and the $ref points to the OpenAPI schema that defines the heart rate property. An example of the OpenAPI schema might look like: We assume that the readable properties will map to GET operations and the writable properties will map to PUT operations. If this is not the case, or if the API is different, the protocol mapping can be specified as such:

SCIM SDF Extension While SDF provides a way to describe a device, a method is needed to associate a mapping between an instance of a device and its associated SDF models. To accomplish this, we define a SCIM extension that can 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

An example SCIM device schema extension might look like:

Security Considerations TODO Security

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". The registry must contain the following attributes:

• Protocol map name
• Protocol name
• Description
• Reference of the specification describing the protocol mapping. This specification must be reviewed by an expert.

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. Following protocol mappings are described in this document: Protocol Mapping Registry

Protocol map	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
openapi	OpenAPI	Protocol mapping for OpenAPI	This document

SCIM Device Schema SDF Extension IANA is requested to create the following extensions in the SCIM Server-Related Schema URIs registry as described in :

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

References Normative References KTC Control AB Universität Bremen TZI Ericsson The Semantic Definition Format (SDF) is concerned with Things, namely physical objects that are available for interaction over a network. SDF is a format for domain experts to use in the creation and maintenance of data and interaction models that describe Things. An SDF specification describes definitions of SDF Objects/SDF Things and their associated interactions (Events, Actions, 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. 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. North Carolina State University North Carolina State University Cisco Systems The initial core schema for SCIM (System for Cross-domain Identity Management) was designed for provisioning users. This memo specifies schema extensions that enables provisioning of devices, using various underlying bootstrapping systems, such as Wi-fi Easy Connect, FIDO device onboarding vouchers, BLE passcodes, and MAC authenticated bypass. 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. Informative References Bluetooth SIG Zigbee Alliance HTTP has been in use by the World-Wide Web global information initiative since 1990. This specification defines the protocol referred to as "HTTP/1.1", and is an update to RFC 2068. [STANDARDS-TRACK] 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. file "sdf-protocol-map.cddl" $$SDF-EXTENSION-DATA //= ( sdfProtocolMap: { * $$SDF-PROTOCOL-MAP } ) $$SDF-PROTOCOL-MAP //= ( ble: ble-protocol-map ) ble-protocol-map = { ? ble-property, ? read: { ble-property }, ? write: { ble-property } } ble-property = ( serviceID: text, characteristicID: text ) $$SDF-PROTOCOL-MAP //= ( ble: ble-event-map ) ble-event-map = { type: "gatt" / "advertisements" / "connection_events", ? serviceID: text, ? characteristicID: text } $$SDF-PROTOCOL-MAP //= ( zigbee: zigbee-protocol-map ) zigbee-protocol-map = { ? zigbee-property, ? read: { zigbee-property }, ? write: { zigbee-property } } zigbee-property = ( endpointID: uint, manufacturerCode: uint, clusterID: uint, attributeID: uint, type: uint ) $$SDF-PROTOCOL-MAP //= ( zigbee: zigbee-action-map ) zigbee-action-map = { endpointID: uint, manufacturerCode: uint, clusterID: uint, commandID: uint, } ]]>

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

Protocol map for BLE

Protocol map for Zigbee

Acknowledgments TODO acknowledge.