Protocol Mapping for SDF

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 24 July 2026.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

The Semantic Definition Format (SDF) [I-D.ietf-asdf-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 [BLE53] and [Zigbee22]. The protocol mapping mechanism is designed to be extensible, allowing future specifications to define mappings for IP-based protocols such as HTTP [RFC2616] or CoAP [RFC7252].¶

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

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3. 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 Section 8.1.¶

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

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:¶

{
  "sdfObject": {
    "healthsensor": {
      "sdfProperty": {
        "heartrate": {
          "description": "The current measured heart rate",
          "type": "number",
          "unit": "beat/min",
          "observable": false,
          "writable": false,
          "sdfProtocolMap": {
            "ble": {
              "serviceID": "12345678-1234-5678-1234-56789abcdef4",
              "characteristicID":
                "12345678-1234-5678-1234-56789abcdef4"
            }
          }
        }
      }
    }
  }
}

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

{
  "sdfObject": {
    "healthsensor": {
      "sdfProperty": {
        "heartrate": {
          "description": "The current measured heart rate",
          "type": "number",
          "unit": "beat/min",
          "observable": false,
          "sdfProtocolMap": {
            "ble": {
              "read": {
                "serviceID": "12345678-1234-5678-1234-56789abcdef4",
                "characteristicID":
                  "12345678-1234-5678-1234-56789abcdef5"
              },
              "write": {
                "serviceID": "12345678-1234-5678-1234-56789abcdef4",
                "characteristicID":
                  "12345678-1234-5678-1234-56789abcdef6"
              }
            }
          }
        }
      }
    }
  }
}

4. 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 [I-D.ietf-asdf-sdf] 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.¶

5. Examples

$$SDF-PROTOCOL-MAP //= (
  ble: ble-protocol-map
)

ble-protocol-map = {
  ? ble-property,
  ? read: { ble-property },
  ? write: { ble-property }
}

ble-property = (
  serviceID: text,
  characteristicID: text
)

{
  "sdfProperty": {
    "temperature": {
      "sdfProtocolMap": {
        "ble": {
          "serviceID": "12345678-1234-5678-1234-56789abcdef4",
          "characteristicID": "12345678-1234-5678-1234-56789abcdef5"
        }
      }
    }
  }
}

{
  "sdfProperty": {
    "temperature": {
      "sdfProtocolMap": {
        "ble": {
          "read": {
            "serviceID": "12345678-1234-5678-1234-56789abcdef4",
            "characteristicID": "12345678-1234-5678-1234-56789abcdef5"
          },
          "write": {
            "serviceID": "12345678-1234-5678-1234-56789abcdef4",
            "characteristicID": "12345678-1234-5678-1234-56789abcdef6"
          }
        }
      }
    }
  }
}

$$SDF-PROTOCOL-MAP //= (
  ble: ble-event-map
)

ble-event-map = {
  type: "gatt" / "advertisements" / "connection_events",
  ? serviceID: text,
  ? characteristicID: text
}

{
  "sdfEvent": {
    "heartRate": {
      "sdfOutputData": {
        "sdfProtocolMap": {
          "ble": {
            "type": "gatt",
            "serviceID": "12345678-1234-5678-1234-56789abcdef4",
            "characteristicID": "12345678-1234-5678-1234-56789abcdef5"
          }
        }
      }
    }
  }
}

{
  "sdfEvent": {
    "isPresent": {
      "sdfOutputData": {
        "sdfProtocolMap": {
          "ble": {
            "type": "advertisements"
          }
        }
      }
    }
  }
}

$$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
)

{
  "sdfProperty": {
    "temperature": {
      "sdfProtocolMap": {
        "zigbee": {
          "endpointID": 1,
          "clusterID": 1026, // 0x0402
          "attributeID": 0, // 0x0000
          "type": 41 // 0x29
        }
      }
    }
  }
}

$$SDF-PROTOCOL-MAP //= (
  zigbee: zigbee-action-map
)

zigbee-action-map = {
  endpointID: uint,
  manufacturerCode: uint,
  clusterID: uint,
  commandID: uint,
}

{
  "sdfAction": {
    "setTemperature": {
      "sdfProtocolMap": {
        "zigbee": {
          "endpointID": 1,
          "clusterID": 1026, // 0x0402
          "commandID": 0 // 0x0000
        }
      }
    }
  }
}

6. 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 [I-D.ietf-scim-device-model] in Figure 8. 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 [RFC7643].¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{
    "id": "urn:ietf:params:scim:schemas:extension:sdf:2.0:Device",
    "name": "SDFExtension",
    "description": "Device extension schema for SDF.",
    "attributes": [
        {
            "name": "sdf",
            "type": "string",
            "description": "SDF models supported by the device.",
            "multiValued": true,
            "required": true,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "none"
        }
    ],
    "meta": {
        "resourceType": "Schema",
        "location": "/v2/Schemas/urn:ietf:params:scim:schemas:extens\
ion:sdf:2.0:Device"
    }
}

An example SCIM device schema extension might look like:¶

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Device",
        "urn:ietf:params:scim:schemas:extension:sdf:2.0:Device"
    ],
    "id": "e9e30dba-f08f-4109-8486-d5c6a3316111",
    "displayName": "Heart Monitor",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:sdf:2.0:Device": {
        "sdf": [
            "https://example.com/thermometer#/sdfThing/thermometer",
            "https://example.com/heartrate#/sdfObject/healthsensor"
        ]
    }
}

7. Security Considerations

The security considerations of [I-D.ietf-asdf-sdf] 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.¶

8. IANA Considerations

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

9. References

Appendix A. CDDL Definition

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

<CODE BEGINS> 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,
}
<CODE ENDS>

Appendix B. OpenAPI Definition

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

<CODE BEGINS> file "ProtocolMap.yaml"

=============== NOTE: '\' line wrapping per RFC 8792 ================

openapi: 3.0.3
info:
  title: SDF Protocol Mapping
  description: |-
    SDF Protocol Mapping. When adding a
    new protocol mapping please add a reference to the protocol map
    for all the schemas in this file.
  version: 0.10.0
externalDocs:
  description: SDF Protocol Mapping IETF draft
  url: https://datatracker.ietf.org/doc/draft-ietf-asdf-sdf-protocol\
-mapping/

paths: {}

components:
  schemas:
## Protocol Map for a property
    ProtocolMap-Property:
      type: object
      properties:
        sdfProtocolMap:
          oneOf:
            - $ref: './ProtocolMap-BLE.yaml#/components/schemas/Prot\
ocolMap-BLE-Propmap'
            - $ref: './ProtocolMap-Zigbee.yaml#/components/schemas/P\
rotocolMap-Zigbee-Propmap'

## Protocol Map for an event
    ProtocolMap-Event:
      type: object
      properties:
        sdfProtocolMap:
          oneOf:
            - $ref: './ProtocolMap-BLE.yaml#/components/schemas/Prot\
ocolMap-BLE-Event'
            - $ref: './ProtocolMap-Zigbee.yaml#/components/schemas/P\
rotocolMap-Zigbee-Event'


<CODE ENDS>

<CODE BEGINS> file "ProtocolMap-BLE.yaml"

=============== NOTE: '\' line wrapping per RFC 8792 ================

openapi: 3.0.3
info:
  title: SDF Protocol Mapping for BLE
  description: |-
    SDF Protocol Mapping for BLE devices.
  version: 0.10.0
externalDocs:
  description: SDF Protocol Mapping IETF draft
  url: https://datatracker.ietf.org/doc/draft-ietf-asdf-sdf-protocol\
-mapping/

paths: {}

components:
  schemas:
## Protocol Mapping for BLE Property
    ProtocolMap-BLE-Propmap:
      required:
        - ble
      type: object
      properties:
        ble:
          required:
            - serviceID
            - characteristicID
          type: object
          properties:
            serviceID:
              type: string
              format: uuid
              example: 00001809-0000-1000-8000-00805f9b34fb
            characteristicID:
              type: string
              format: uuid
              example: 00002a1c-0000-1000-8000-00805f9b34fb

## Defines different types of BLE events
    ProtocolMap-BLE-Event:
      required:
        - ble
      type: object
      properties:
        ble:
          required:
            - type
          type: object
          properties:
            type:
              type: string
              example: gatt
              enum:
                - gatt
                - connection_events
                - advertisements
            serviceID:
              type: string
              example: 00001809-0000-1000-8000-00805f9b34fb
            characteristicID:
              type: string
              example: 00002a1c-0000-1000-8000-00805f9b34fb

<CODE ENDS>

<CODE BEGINS> file "ProtocolMap-Zigbee.yaml"

=============== NOTE: '\' line wrapping per RFC 8792 ================

openapi: 3.0.3
info:
  title: SDF Protocol Mapping for Zigbee
  description: |-
    SDF Protocol Mapping for Zigbee devices.
  version: 0.10.0
externalDocs:
  description: SDF Protocol Mapping IETF draft
  url: https://datatracker.ietf.org/doc/draft-ietf-asdf-sdf-protocol\
-mapping/

paths: {}

components:
  schemas:
## Protocol mapping for Zigbee property
    ProtocolMap-Zigbee-Propmap:
      required:
        - zigbee
      type: object
      properties:
        zigbee:
          required:
            - endpointID
            - clusterID
            - attributeID
          type: object
          properties:
            endpointID:
              type: integer
              format: int32
              example: 1
            clusterID:
              type: integer
              format: int32
              example: 6
            attributeID:
              type: integer
              format: int32
              example: 16
            type:
              type: integer
              format: int32
              example: 1

    ProtocolMap-Zigbee-Event:
      allOf:
        - $ref: '#/components/schemas/ProtocolMap-Zigbee-Propmap'

<CODE ENDS>

Acknowledgments

TODO acknowledge.¶

Authors' Addresses