Semantic Definition Format (SDF): Semantic Enhancements for sdfRef

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 3 September 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) for Data and Interactions of Things allows for referencing and importing definitions from other documents via the sdfRef quality. In the base SDF specification [RFC9880], these references are only structural in nature and do not consider semantic aspects such as the version of the referenced model.¶

In this memo, we are proposing an extension for SDF's namespace concept that makes it possible to take into account semantic aspects when using sdfRef, but also in other scenarios when referring to external definitions.¶

2. Conventions and Definitions

The definitions of [RFC9880] and [RFC9535] apply.¶

SDF Repository:

A web server hosting SDF models. In accordance to [RFC9880], one or more SDF models may belong to the same namespace. The SDF Repository is responsible to return the correct models that satisfy a SDF Consumer's request. For this purpose, the SDF Repository might combine multiple individual models that belong to the same namespace into one.¶

SDF Consumer:

A client that retrieves and processes SDF models (e.g., for translation purposes or to interact with a device that implements an SDF model).¶

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. Namespace Extensions

SDF's namespace concept maps shorthands such as foo to URIs that identify global names. These URIs use the https scheme and a path. Using JSON pointers as fragement identifiers, it is possible to refer to concrete definitions from other SDF models.¶

In base SDF, the query part of the URIs is deliberately left out and reserved for extensions. This memo utilizes query parameters to enhance the namespacing concept with additional semantic capabilities, especially when it comes to referring to specific versions or version ranges of SDF models.¶

For this purpose, this memo introduces two standardized query parameters (see Table 1) that¶

1. allow for such version-dependent references (using the version parameter),¶

2. make it possible to restrict the part of the namespace that should be returned when deferencing a namespace URI (using the subtree parameter).¶

The version constraints used for the version parameter SHOULD follow Semantic Versioning or a similar approach for semantic version numbers. An SDF Repository SHOULD adhere to the version constraints indicated via the version parameter and return a model with either the exact or a compatible version number.¶

The introduction of the subtree parameter is motivated by the fact that multiple models may contribute to the same SDF namespace (and fragment identifiers are not transferred) Using a JSON Path query with this paramter allows for giving the SDF Repository hosting the namespace definitions a hint on which parts of the target namespace should be included in the output. When an SDF Consumer specifies a set of sdfObjects and/or sdfThings in its request, the SDF Repository MAY leave out definitions that are not needed to fulfill the request. Similarly, the SDF Repository MAY combine multiple models from the same namespace into one to satisfy the Consumer's request.¶

4. Examples

A simple example for a model that uses the version parameter is shown in Figure 1. Here, the caret character (^, percent-encoded as %5E) in the parameter value ^1.1.0 indicates that a version compatible with version 1.0.0 should be provided by the SDF repository. The ^ indicates that this should be a compatible patch version (i.e., the third digit may be greater than 0), while a ~ would indicate the same for the _ minor_ version or second digit. As the first digit stands for major versions, these updates are considered non-backwards-compatible and should not be retrieved automatically.¶

namespace:
  cap: https://example.com/capability/cap?version=%5E1.1.0
  lamps: https://example.com/lamps
defaultNamespace: lamps
sdfObject:
  LightSwitch:
    sdfAction:
      toggle:
        sdfRef: cap:/sdfObject/Switch/sdfAction/toggle

The parametrization of URIs can also be used to use different version ranges for certain parts of a referenced namespace. In the example shown in Figure 2, a version 2.0.0 of the models hosted under https://example.com/capability/cap has added a new status property that has not been part of previous versions. At the same time, a non-backwards-compatible change has been applied to the referenced toggle action. To keep using the old toggle action while already incorporating the new status property, the namespacing concept allows referring to different versions via the new query parameters that have been introduced.¶

namespace:
  cap11: https://example.com/capability/cap?version=%5E1.1.0
  cap2: https://example.com/capability/cap?version=%5E2.0.0
  lamps: https://example.com/lamps
defaultNamespace: lamps
sdfObject:
  LightSwitch:
    sdfAction:
      toggle:
        sdfRef: cap11:/sdfObject/Switch/sdfAction/toggle
    sdfProperty:
      status:
        sdfRef: cap:/sdfObject/Switch/sdfProperty/status

Lastly, since we are only using definitions from the sdfObject Switch in the referenced namespace, we can limit the subtree that we are referring to via the subtree parameter. Figure 3 shows a simple example where a JSONPatch expression is being used for this purpose. As JSONPath is very expressive, this approach allows for fine-grained control for limiting how much of the target namespace will actually be retrived when dereferencing the namespace URI.¶

namespace:
  cap: https://example.com/capability/cap?version=%5E1.1.0&subtree=%24.sdfObject.Switch
  lamps: https://example.com/lamps
defaultNamespace: lamps
sdfObject:
  LightSwitch:
    sdfAction:
      toggle:
        sdfRef: cap:/sdfObject/Switch/sdfAction/toggle

Note that the use of both the version and the subtree parameters may require the values to be percent-encoded, which decreases the human-readability of the namespace URIs.¶

5. Security Considerations

The security considerations of [RFC9880] and [RFC9535] apply to this document as well.¶

TODO More security¶

6. IANA Considerations

This document has no IANA actions.¶

7. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC9535]

Gössner, S., Ed., Normington, G., Ed., and C. Bormann, Ed., "JSONPath: Query Expressions for JSON", RFC 9535, DOI 10.17487/RFC9535, February 2024, <https://www.rfc-editor.org/rfc/rfc9535>.

[RFC9880]

Koster, M., Ed., Bormann, C., Ed., and A. Keränen, "Semantic Definition Format (SDF) for Data and Interactions of Things", RFC 9880, DOI 10.17487/RFC9880, January 2026, <https://www.rfc-editor.org/rfc/rfc9880>.

Acknowledgments

TODO acknowledge.¶

Author's Address