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 8 February 2026.¶

Copyright Notice

Copyright (c) 2025 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], 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.¶

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

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

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

4. SDF Protocol Mapping structure

ble-protocol-map = {
  serviceID: text
  characteristicID: text
}

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

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

zigbee-protocol-map = {
  endpointID: uint
  clusterID: uint
  attributeID: uint
  type: uint
}

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

5. IP based Protocol Mapping

The protocol mapping mechanism can potentially also be used for IP-based protocols such as HTTP or CoAP. An example of a protocol mapping for a property using HTTP might look like:¶

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

{
  "sdfProperty": {
    "heartrate": {
      "sdfProtocolMap": {
        "openapi": {
            "operationRef": "https://example.com/openapi.json#/paths\
/~1heartrate~1{id}~1current/get",
            "$ref": "https://example.com/openapi.json#/components/sc\
hema/HeartRate/properties/pulse"
        }
      }
    }
  }
}

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

paths:
  /heartrate/{id}/current:
    get:
      summary: Get current heart rate
      description: |-
        Retrieve the current heart rate for a specific user
        identified by {id}.
      parameters:
        - name: id
          in: path
          required: true
          description: |-
            The ID of the user whose heart rate is being queried.
          schema:
            type: string
      responses:
        "200":
          description: |-
            Successful response with current heart rate data.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HeartRate/properties/pulse"

components:
  schemas:
    HeartRate:
      type: object
      properties:
        pulse:
          type: integer
          description: The current heart rate in beats per minute.
        spo2:
          type: number
          format: float
          description: |-
            The current body temperature in degrees Celsius.

6. Security Considerations

TODO Security¶

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

8. References

Acknowledgments

TODO acknowledge.¶

Authors' Addresses