RDAP Extensions

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

Copyright Notice

Copyright (c) 2023 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. Background

The Registration Data Access Protocol (RDAP) defines a uniform means to access data from Internet operations registries, specifically Domain Name Registries (DNRs) and Internet Number Registries (INRs). The queries for DNRs and INRs are defined in [RFC9082] and the responses for DNRs and INRs are defined in [RFC9083].¶

RDAP contains a means to define extensions for queries not found in [RFC9082] and responses not found in [RFC9083]. RDAP extensions are also described in [RFC7480]. This document uniformly describes RDAP extensions, clarifies their usage, and defines additional semantics that were previously undefined.¶

2. The RDAP Extension Identifier

Section 6 of [RFC7480] describes the identifier used to signify RDAP extensions and the IANA registry into which RDAP extensions are to be registered.¶

In brief, RDAP extensions identifiers start with an alphabetic character and may contain alphanumeric characters and "_" (underscore) characters. This formulation was explicitly chosen to allow compatibility with variable names in programming languages and transliteration with XML.¶

When in use in RDAP, extension identifiers are prepended to URL path segments, URL query parameters, and JSON object member names (herein further referred to as "JSON names"). In all cases, the extension identifier acts as a namespace preventing collisions between extension elements.¶

Additionally, implementers and operators can use the extension identifiers to find an extensions definition (via the IANA registry).¶

RDAP extension identifiers have no explicit structure and are opaque in that no inner-meaning can be "seen" in them. This document restricts the syntax of RDAP extension identifiers from containing two consecutive "_" (underscore) characters and reserves their use for the future definition of structure (such as to define a versioning scheme). That is, RDAP extensions MUST NOT define an identifier with two consecutive underscore characters ("__") unless explicitly adhering to an RFC describing such usage.¶

RDAP extensions MUST NOT define an extension identifier that when prepended to an underscore character may collide with an existing extension identifier. For example, if there were a pre-existing identifier of "foo_bar", another extension could not define the identifier "foo". Likewise, if there were a pre-existing identifier of "foo_bar", another extension could not define the identifier "foo_bar_buzz". However, an extension could define "foo" if "foobar" pre-existed and vice versa.¶

For this reason, usage of an underscore character in RDAP extension identifiers is NOT RECOMMENDED. Implementers should be aware that many existing extension identifiers do contain underscore characters.¶

3. Usage in Queries

Section 5 of [RFC9082] describes the use of extension identifiers in formulating URIs to query RDAP servers. The extension identifiers are to be prepended to the path segments they use. For example, if an extension uses the identifier foobar, then the path segments used in that extension are prepended with foobar_. If the foobar extension defines paths fizz and fazz, the URIs for this extension might take the following form:¶

https://base.example/foobar_fizz
https://base.example/foobar_fazz

Although [RFC9082] describes the use of URI query strings, it does not define their use with extensions. [RFC7480] instructs servers to ignore unknown query parameters. Therefore, the use of query parameters, prefixed or not with an extension identifier, is undefined as defined in [RFC9082] and [RFC7480].¶

Despite this, there are several extensions that do specify query parameters. This document updates [RFC9082] with regard to the use of RDAP extension identifiers in URL query parameters.¶

When an RDAP extension defines query parameters to be used with a URL path that is not defined by that RDAP extension, those query parameter names SHOULD be constructed in the same manner as URL path segments (that is, extensions ID + '_' + parameter name). See section Section 6 regarding when usage of an extension identifier is required.¶

When an RDAP extension defines query parameters to be used with a URL path defined by that RDAP extension, prefixing of query parameters is not required.¶

4. Usage in JSON

Section 2 of [RFC9083] describes the use of extension identifiers in the JSON returned by RDAP servers. Just as in URIs, the extension identifier is prepended to JSON names to create a namespace so that the JSON name from one extension will not collide with the JSON name of another extension. And just as with URIs, clients are to ignore unknown JSON names.¶

The example given in [RFC9083] is as follows:¶

{
  "handle" : "ABC123",
  "lunarNIC_beforeOneSmallStep" : "TRUE THAT!",
  "remarks" :
  [
    {
      "description" :
      [
        "She sells sea shells down by the sea shore.",
        "Originally written by Terry Sullivan."
      ]
    }
  ],
  "lunarNIC_harshMistressNotes" :
  [
    "In space,",
    "nobody can hear you scream."
  ]
}

In this example, the extension identified by lunarNIC is prepended to the names of both a JSON string and a JSON array.¶

{
  "handle" : "ABC123",
  "remarks" :
  [
    {
      "description" :
      [
        "She sells sea shells down by the sea shore.",
        "Originally written by Terry Sullivan."
      ]
    }
  ],
  "lunarNIC_author" :
  {
    "firstInitial": "J",
    "lastName": "Heinlein"
  }
}

{
  "handle" : "ABC123",
  "remarks" :
  [
    {
      "description" :
      [
        "She sells sea shells down by the sea shore.",
        "Originally written by Terry Sullivan."
      ]
    }
  ],
  "lunarNIC" :
  {
    "firstInitial": "J",
    "lastName": "Heinlein"
  }
}

5. Camel Casing

The styling convention used in [RFC9083] for JSON names is often called "camel casing", in reference to the hump of a camel. In this style, the first letter of every word, except the first word, composing a name is capitalized. This convention was adopted to visually separate the namespace from the name, with an underscore between them.¶

Though there is no explicit guidance to use camel case names, extensions would be wise to continue the style.¶

6. Two Classes of Extensions

Though all RDAP extensions are to be registered in the IANA RDAP extensions registry, there is an implicit two-class system of extensions that comes from the inherit ownership of the RDAP specifications by the IETF: extensions created by the IETF and extensions not created by the IETF.¶

In the perspective of how extensions identifiers are used as namespace separators, extensions created by the IETF are not required to be prefixed with an extension identifier as the IETF can coordinate its own activities to avoid name collisions. In practice, most extensions owned by the IETF do use extension identifiers.¶

RDAP extensions not defined by the IETF MUST use the extension identifier as a prefix in accordance with this document, [RFC7480], [RFC9082], and [RFC9083]. And RDAP extensions defined by the IETF SHOULD use the extension identifier as a prefix or as a bare extension identifier (see Section 4.2) IETF defined RDAP extensions that do not follow this guidance MUST describe the necessity to do so.¶

7. Profile and Marker Extensions

Extensions are not required to extend the JSON or URL components of RDAP.¶

While the RDAP extension mechanism was created to extend RDAP queries and/or responses, extensions can also be used to signal server policy (for example, specifying the conditions of use for existing response structures). Extensions that are primarily about signalling server policy are often called "profiles".¶

Some extensions exist to denote the usage of values placed into an IANA registry, such as the IANA RDAP registries, or the usage of extensions to technologies used by RDAP such as extended vCard/jCard properties. Such extensions exist to "mark" these usages and are often called "marker" extensions.¶

Regardless of the category of these extensions, their usage may also leverage the appearance of their identifiers in the rdapConformance array. Clients may use the /help query as defined in [RFC9082] to discover the extensions available. This document updates the guidance of [RFC9083] with respect to /help queries: servers SHOULD place an rdapConformance array in the response to a /help query.¶

8. Extension Versioning

As stated in Section 2, RDAP extensions are opaque and they posses no explicit version despite the fact that some extension identifiers include trailing numbers. That is, RDAP extensions without an explicitly defined versioning scheme are opaquely versioned.¶

For example, fizzbuzz_1 may be the successor to fizzbuzz_0, but it may also be an extension for a completely separate purpose. Only consultation of the definition of fizzbuzz_1 will determine its relationship with fizzbuzz_0. Additionally, fizzbuzz_99 may be the predecessor of fizzbuzz_0.¶

If a future RFC defines a versioning scheme (such as using the mechanims defined in section Section 2), an RDAP extension definition MUST explicitly denote this compliance.¶

9. Extension Definitions

Extensions must be documented in an RFC or in some other permanent and readily available reference, in sufficient detail that interoperability between independent implementations is possible.¶

Though RDAP gives each extension its own namespace, the definition of an extension may re-use definitions found in the base RDAP specification or in any other properly registered extension.¶

[RFC9083] notes that the extension identifiers provide a "hint" to the client as to how to interpret the response. This wording does not intentionally restrict the extension to defining only JSON values within the extensions namespace. Therefore, an extension may define the use of its own JSON values together with the use of JSON values from other extensions or RDAP specifications. As with the ICANN profile or RIR profile extensions, the extension may simply signal policy applied to already defined RDAP structures.¶

10. Existing Extension Registrations

The following extensions have been registered with IANA, but do not comply with the requirements set out in the base specifications, as clarified by this document:¶

• Extension identifier: fred¶

  • RDAP conformance value: fred_version_0¶
  • Field/path prefix: fred¶

• Extension identifier: artRecord¶

  • RDAP conformance value: artRecord_level_0¶
  • Field/path prefix: artRecord¶

• Extension identifier: platformNS¶

  • RDAP conformance value: platformNS_level_0¶
  • Field/path prefix: platformNS¶

• Extension identifier: regType¶

  • RDAP conformance value: regType_level_0¶
  • Field/path prefix: regType¶

Client authors should be aware that responses that make use of these extensions may require special handling on the part of the client. Also, while these extensions will be retained in the registry, future extensions that are similarly noncompliant will not be registered.¶

To avoid any confusion with the operation of the existing entries, an extension registration that attempts to use one of the RDAP conformance values given in this section as an extension identifier (and so as an RDAP conformance value also) will be rejected.¶

11. Acknowledgements

The following individuals have provided feedback and contributions to the content and direction of this document: James Gould, Daniel Keathley, and Ties de Kock.¶

Authors' Addresses