ASDF Working Group                                              E. RamosInternet-Draft                                                  EricssonIntended status: Standards Track                        9 September 2025Expires: 13 March 2026          Semantic Definition Format (SDF) for API translation                  draft-ramos-asdf-api-translation-01Abstract   This document defines an extension to the Semantic Definition Format   (SDF) that enables API translation between applications and devices.   The translation enables clarification of complex syntax for a service   or device to utilize a different API from the one that was first   designed to use.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 13 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.Ramos                     Expires 13 March 2026                 [Page 1]Internet-Draft           SDF for API translation          September 2025Table of Contents   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3   2.  Discoverable API interfaces . . . . . . . . . . . . . . . . .   3   3.  Inputting parameters to the API . . . . . . . . . . . . . . .   6   4.  Methods on the API calls  . . . . . . . . . . . . . . . . . .   8   5.  Matching API to application logic . . . . . . . . . . . . . .  10   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10     6.1.  Media Type  . . . . . . . . . . . . . . . . . . . . . . .  10   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  11   8.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  11   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  11     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  11     9.2.  Informative References  . . . . . . . . . . . . . . . . .  11   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  121.  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.Ramos                     Expires 13 March 2026                 [Page 2]Internet-Draft           SDF for API translation          September 2025   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*1.1.  Terminology   The definitions of [I-D.ietf-asdf-sdf] apply.   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and   "OPTIONAL" in this document is to be interpreted as described in   [BCP14] (RFC2119) (RFC8174) when, and only when, they appear in all   capitals, as shown here.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 aRamos                     Expires 13 March 2026                 [Page 3]Internet-Draft           SDF for API translation          September 2025   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"                    ]                     }                   },Ramos                     Expires 13 March 2026                 [Page 4]Internet-Draft           SDF for API translation          September 2025                   "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"             }           }         }       }     }   }Ramos                     Expires 13 March 2026                 [Page 5]Internet-Draft           SDF for API translation          September 2025   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 canRamos                     Expires 13 March 2026                 [Page 6]Internet-Draft           SDF for API translation          September 2025   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}",Ramos                     Expires 13 March 2026                 [Page 7]Internet-Draft           SDF for API translation          September 2025         "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.  Methods on the API calls   Sometimes, only calling an API is not enough.  For example, in some   cases, the API call requires additional actions such as submitting a   payload.  To handle this dimension on the API calls, the *method*   command has been introduced.  This command enables the requested   device to understand how to handle the API call, since in the   previous example, the API URL has all the information required in the   call itself.  However, in some cases, the action necessary with the   API may need to be specified in a manner that the requested device   can understand.  The keyword *method* is meant to describe how to   handle the API URL and what to expect of it.  In some other examples,   the *method* could result in an OBSERVE or another type of new action   not yet specified, for example, how to address an XR-type   application.Ramos                     Expires 13 March 2026                 [Page 8]Internet-Draft           SDF for API translation          September 2025   An example could be the use of an LWM2M camera [lwm2m-cameraObject].   To use this model, a payload has to be submitted in the POST method.   The following example describes such a translation from one camera   API to the LWM2M model.   {       "info": {         "title": "LwM2M Camera Device to Requester dev. Application API mapping"       },       "namespace": {         "sdm": "https://sdm.wide.ad.jp/sdmo/#/",         "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns",         "oma": "https://onedm.org/ecosystem/oma",         "dev": "http://traffic-light202125.traffic-center.fi/10340/0/",         "app": "http://owner.mycar.fi/"       },       "defaultNamespace": "dev",       "map": {         "#/sdfObject/video/sdfAction/playStream": {           "cmd:template-href": "http://traffic-light202125.traffic-center.fi/10340/0/101",           "cmd:method":"POST",           "description": "Starts the recording of the camera",           "sdfInputData": {               "type": "number",               "const":1            },           "sdfRelation": {               "FeedType": {               "relType": "rdf:type",                "target": [                   "dev:#/sdfObject/Camera/sdfAction/Local_Recording_Control",                   "oma:#/sdfObject/10340/101",                   "sdm:playStream"              ]               }             }         },         "#/sdfObject/video/sdfAction/StopStream": {           "cmd:template-href": "http://traffic-light202125.traffic-center.fi/10340/0/101",           "cmd:method":"POST",           "description": "Stops the recording of the camera",           "sdfInputData": {                 "type": "number",                 "const":0           },           "sdfRelation": {             "FeedType": {             "relType": "rdf:type",             "target": [Ramos                     Expires 13 March 2026                 [Page 9]Internet-Draft           SDF for API translation          September 2025               "dev:#/sdfObject/Camera/sdfAction/Local_Recording_Control",               "oma:#/sdfObject/10340/101",               "sdm:stopStream"             ]             }           }         },         "#/sdfObject/Camera/sdfProperty/Input-video-stream":{           "cmd:template-href": "http://traffic-light202125.traffic-center.fi/10340/0/9",           "sdfRelation": {             "FeedType": {               "relType": "rdf:type",               "target": [                 "dev:#/sdfObject/Camera/sdfProperty/Recording_Location",                 "sdm:VideoMedia"               ]             }          }        }       }    }5.  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.6.  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.1.  Media Type   IANA is requested to add the following Media-Type to the "Media Types   registry [IANA.media-types]. -->Ramos                     Expires 13 March 2026                [Page 10]Internet-Draft           SDF for API translation          September 2025   +==================+===============================+=============+   | Name             | Template                      | Reference   |   +==================+===============================+=============+   | sdf-mapping+json | application/ sdf-mapping+json | RFC XXXX,   |   |                  |                               | section 5.1 |   +------------------+-------------------------------+-------------+              Table 1: A media type for SDF mapping files7.  Security Considerations   Some wider issues are discussed in [RFC8576].8.  Acknowledgements   Thanks to Ari Keränen for the support in realizing this idea.9.  References9.1.  Normative References   [I-D.ietf-asdf-sdf]              Koster, M., Bormann, C., and A. Keränen, "Semantic              Definition Format (SDF) for Data and Interactions of              Things", Work in Progress, Internet-Draft, draft-ietf-              asdf-sdf-24, 27 July 2025,              <https://datatracker.ietf.org/doc/html/draft-ietf-asdf-              sdf-24>.   [IANA.media-types]              IANA, "Media Types",              <https://www.iana.org/assignments/media-types>.   [RFC7396]  Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,              DOI 10.17487/RFC7396, October 2014,              <https://www.rfc-editor.org/rfc/rfc7396>.9.2.  Informative References   [bormann-mapping]              Bormann, C. and J. Romann, "Semantic Definition Format              (SDF): Mapping files", n.d.,              <https://datatracker.ietf.org/doc/draft-bormann-asdf-sdf-              mapping/>.Ramos                     Expires 13 March 2026                [Page 11]Internet-Draft           SDF for API translation          September 2025   [lwm2m-cameraObject]              "Camera - OMAobjectId: 10340 V1.0", n.d.,              <https://raw.githubusercontent.com/OpenMobileAlliance/              lwm2m-registry/prod/10340.xml>.   [RFC6570]  Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,              and D. Orchard, "URI Template", RFC 6570,              DOI 10.17487/RFC6570, March 2012,              <https://www.rfc-editor.org/rfc/rfc6570>.   [RFC8615]  Nottingham, M., "Well-Known Uniform Resource Identifiers              (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,              <https://www.rfc-editor.org/rfc/rfc8615>.Author's Address   Edgar Ramos   Ericsson   Hirsalantie 11   FI- 02420 Jorvas, Kirkkonummi   Finland   Email: edgar.ramos@ericsson.comRamos                     Expires 13 March 2026                [Page 12]