Semantic Definition Format (SDF) for API translation

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 6 March 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

In many cases, a service needed by an application can be provided through APIs by several suppliers. Semantic matching can be used to map the needs of the applications and adapt API calls to what the service suppliers could provide. The main purpose of this document is to describe methods that enable the translation of one device or application API to another equivalent API, utilizing syntax understandable by the deploying party.¶

An API translator from the original API to the updated one or even mapping to a new service would allow an automatic adaptation to the target API. Also, it would enable the possibility to adapt to multiple APIs with the same data model, enabling the deployment of services from multiple sources. This feature enables use cases such as the usage of the cheapest or most robust service, deployment of national services when traveling, and execution of device services even from a different ecosystem origin.¶

This document provides enabling elements for communication from devices or applications belonging to different ecosystems that do not share the same semantic modelling. Utilizing SDF syntax enhanced with an API format depiction, it is possible to provide an API description that is understandable with the syntax known by the device or application, if such semantics are defined in their data model. The final result uses a navigable description of the API's functions to provide the necessary information that is required by a device application to map external required services, their parameters, and results to an application logic using ontologically defined objects that can be matched to remote calls in another device application, for example.¶

The API requires a mapping in applications functions by matching syntax in addition to the actual discovery of the API; therefore, the importance of the translation to an understandable model. This matching could be enabled by several mechanisms described, and it is dynamically adjusted to every new interface faced. Using SDF in conjunction with the given schema allows an automated way to match functionality to application intents.¶

┌──────────────────────┐                  ┌──────────────────────┐
│                      │                  │                      │
│  Service platform    │                  │  Service platform    │
│        #1            │                  │        #2            │
│                      │                  │                      │
│       ┌──────────────┐                  │       ┌──────────────┐
│       │ Service API  ┼──┐               │       │ Service API  │
└───────└─────▲────────┘  │               └───────└─────▲──┬─────┘
              │           │                             │  │
              │           │         ┌───────────┐       │  │
              │           ▼───┐     │ SDF-API   │       │  │
              └───────────┤   │     │TRANSLATION│       │  │
                          │   ┼─────►  MODEL    ├───────┘  │
                          │   ◄─────┐           ◄──────────┘
                          └───┘     └───────────┘
                         Device

Example of a device using the API translation model to access the same service in a different platform with a different API¶

2. Discoverable API interfaces

A device or application may expose its capabilities as an API list. This could be acquired in real-time by calling a command that provides such a list of commands. For example, the resource “.well-known/commands” [RFC8615] could be used as a specific way to request all the commands available. The reply then includes a list of the different API supported calls, which would be called in a hierarchical way from the root domain that is provided by the device, an application, or a mediating platform. The reply would contain a description of the supported API with a semantic definition attached. Using the Semantic Definition Format (SDF), a reply for two commands may include what is given in the following example:¶

{
  "namespace": {
    "name": "Relevant_URL_or_namespace_used_as_semantic_reference_(example)",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns",
    "demo": "https://example.com/iss-demo-setup/#",
  },
  "defaultNamespace": "demo",
  "sdfObject": {
    "target_object": {
      "sdfProperty": {
        "target_property": {
          "description": "possible description of the property",
          "sdfRelation": {
            "FeedType": {
              "relType": "rdf:type",
              "target": [
                "demo:Output"
              ]
            }
          },
          "contentFormat": "application/typeofcontent-info"
        }
      },
      "sdfAction": {
        "Name_of_the_command_1": {
          "description": "Description of the command and input required",
          "sdfRelation": {
            "FeedType": {
              "relType": "rdf:type",
              "target": "demo:command1"
            }
          },
          "sdfInputData": {
            "type": "object",
            "properties": {
              "input_1_required": {
                "description": "Description of what element is needed as first input",
                "sdfRelation": {
                  "FeedType": {
                    "relType": "rdf:type",
                    "target": [
                      "demo:input1"                    ]
                  }
                },
                "type": "number",
                "sdfChoice": {
                  "input_2_required": {
                    "description": "A number needed as an input of the command",
                    "const":"0",
                    "sdfRelation": {
                      "FeedType": {
                        "relType": "rdf:type",
                        "target": [
                          "demo":"input2",
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "sdfOutputData": {
            "contentFormat": "application/typeofcontent-info"
          }
        },
        "Name_of_the_command_2": {
          "sdfRelation": {
            "FeedType": {
              "relType": "rdf:type",
              "target": "demo:command2"
            }
          },
          "sdfInputData": {
            "description": "Description of input required for second command",
            "sdfRelation": {
              "FeedType": {
                "relType": "rdf:type",
                "target": "demo:secondInput"
              }
            },
            "type": "typeoftheinput",
            "contentFormat": "application/typeofinput-info"
          }
        }
      }
    }
  }
}

In this example, one service is defined with a command1, which requires an input1 (an object) and input2 (a number). The other service requires a different call (command2), which requires only one input (secondInput).¶

Further interaction capabilities can be included either in the initial response, as shown above in the "sdfAction" block, or could be discovered by further requests. For example, the descriptions of the two actions detailed above show if they require input, what the details of such input and the output are, and if there is additional information related to the nature of the output. Also, the description field could be tailor-made to provide a URI to a vocabulary that is understandable by the device or application. In this way, the device or application could make sense of the possible options, parameters, and actions that the command provides or requires.¶

3. Inputting parameters to the API

Once the available function calls and input parameters required by the API have been provisioned to the requester device or application, it can make calls to the API when required by its application logic. The application would map the “need for a capability” to the concrete capability provided by the provider application or device through matching the syntax and data model. The functions are then mapped to the calls that the application can handle and has defined syntax. The parts of the API that are not understood by the requester device are normally ignored. The mapping semantics from a target device or application may be communicated to the application of the requesting device using an SDF mapping extension draft [bormann-mapping]. In such mapping, the actions and data can be expressed using the data model that are understandable by the requester and allows it to produce the API call and provide the required data. The only problem with this mapping is that if the API call structure is different, the logic required to call the target API might be complicated for certain device applications.¶

With SDF notation, it is possible to explain the data model but not the mapping for a specific API call. That would require, in some cases, mapping of values and, depending on the API definition, reshuffling of the parameters or even the URI utilized.¶

To tackle those challenges, we introduced a new SDF quality that can express URL template patterns from [RFC6570]. The quality "template-href", includes the URL or the URL pattern that matches the command known by the requester device application. As explained in [RFC6570], the pattern may have variable terms, which are also given an SDF definition and relationship so the requested device can understand how to map its own data model to what the target API requires. Also, we introduce a value mapper "template-value" that enables mapping of values to parameters in the target API. The sdfRelation [I-D.ietf-asdf-sdf] is used as a vehicle to support the mapping between APIs.¶

The namespace "cmd" is also utilized to provide this API mapping values. In this example, we map a command_1 with several inputs to a command_2 that utilizes the inputs in a different way. The schema maps semantically the inputs and instructs the system how to make the API call based on the previously known API.¶

  {
 "info":{
    "title": "API mapping of two systems"
  },
  "namespace": {
    "targetSem": "https://example.org/targetSemantics/#",
    "targetDev": "https://example.org/targetDevice",
    "requestDev": "https://example.com/requesterDevice",
    "requestSem": "https://example.com/destinationSemantics/#"
  },
  "defaultNamespace": "requestSem",
  "sdfData": {
    "input_2_required": {
      "type": "number",
      "sdfChoice": {
        "requesterSemantic_1": {
          "const": 1
        },
        "requesterSemantic_2": {
          "const": 2
        }
      },
      "sdfRelation": {
        "FeedType": {
          "relType": "rdf:type",
          "target": [
            "targetDev:#/sdfObject/target_object/sdfAction/Name_of_the_command_1/sdfInputData/input2",
            "requestDev:#/sdfObject/request_object/sdfAction/requester_command/sdfInputData/semanticRequesterInput"
          ]
        }
      }
    }
  },
  "map": {
    "#/sdfObject/request_object/sdfAction/requester_command": {
      "cmd:template-href": "https://example.org/targetDevice/control/Name_of_the_command_1?input1={input_2_required}&input2={input_1}",
      "sdfRelation": {
        "FeedType": {
          "relType": "rdf:type",
          "target": [
            "targetDev:#/sdfObject/target_object/sdfAction/Name_of_the_command_1",
            "requestSem:requester_command"
          ]
        }
      }
    },
    "cmd :template-values": {
      "input2": "#/sdfData/input_1_required",
      "input1": "#/sdfObject/target_object/sdfAction/name_of_command1/sdfInputData/input_1"
    },
    "#/sdfObject/request_object/sdfAction/requester_command_2": {
      "cmd:template-href": "https://example.org/targetDevice/control/Name_of_the_command_2?secondInput={requesterSecondInput}",
      "sdfRelation": {
        "FeedType": {
          "relType": "rdf:type",
          "target": "targetDev:#/sdfObject/target_object/sdfAction/Name_of_the_command_2"
        }
      }
    },
    "cmd:template-values": {
      "secondInput": "#/sdfObject/request_object/sdfAction/requester_command_2/sdfInputData/requesterSecondInput"
    }
  }
}

4. Matching API to application logic

Each application has a logic that requires either information from the API call or the execution of a service. With this translation tool, the application logic may need to consider the different types of APIs that may be present. For example, if the API requires a payload or the info is directly appended to the call. Also, on the way the API produces the output, and how to handle it.¶

5. IANA Considerations

This document has the following actions for IANA.¶

Note to RFC Editor: Please replace all occurrences of "{XXXX}" with the RFC number of this specification and delete this paragraph.¶

6. Security Considerations

Some wider issues are discussed in [RFC8576].¶

7. Acknowledgements

Thanks to Ari Keränen for the support in realizing this idea.¶

8. References

Author's Address