Internet-Draft Versioning in RDAP May 2023
Gould, et al. Expires 13 November 2023 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-gould-regext-rdap-versioning-01
Published:
Intended Status:
Standards Track
Expires:
Authors:
J.G. Gould
VeriSign, Inc.
D.K. Keathley
VeriSign, Inc.
M. Loffredo
IIT-CNR/Registro.it

Versioning in the Registration Data Access Protocol (RDAP)

Abstract

This document describes an RDAP extension for identifying RDAP extension versions supported by the server, RDAP extension versions included in an RDAP response, and enabling a client to specify the desired RDAP extension versions to include in an RDAP response using machine-parseable identifiers.

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 November 2023.

▲

Table of Contents

1. Introduction

RDAP supports identifying the RDAP extensions included in an RDAP response using the RDAP Conformance, defined in Section 4.1 of [RFC9083]. The RDAP Conformance values of RDAP extensions can informally support versioning using a machine processable, opaque identifier, but there is no standard mechanism defined in [RFC9083] that exists to support structured, machine-parseable version signaling by the server.

This document describes an RDAP extension for identifying RDAP extension versions supported by the server, RDAP extension versions included in an RDAP response, and enabling a client to specify the desired RDAP extension versions to include in an RDAP response using machine-parseable identifiers. The RDAP extension versions supported by the server is returned in an extension to the RDAP help response, defined in Section 7 of [RFC9083], using the "versioning-help" member Section 6.2. The "versioning-help" member includes the list of supported extensions, using the RDAP Conformance identifiers with a list of supported versions, an indication of the default version, and optional links to the extension version documentation. The RDAP extension versions included in an RDAP response are identified using the "versioning" member Section 6.3. The "versioning" member includes a list of extensions, using the RDAP Conformance identifiers with the extension version included in the RDAP response. The client can specify the desired RDAP extension versions to include in the RDAP response with the "versioning" query parameter Section 5. The "versioning" query parameter is set with a list of extension version identifiers Section 3, delimeted by a comma (',').

2. Conventions Used in This Document

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. Extension Version Identifier

The Extension Version Identifier is the unique versioned extension identifier that is used for extension signaling by the server and by the client. The Extension Version Identifier uses the Extension Identifier, defined in [RFC7480], along with the Extension Versioning defined in Section 3.1. The format of the Extension Version Identifier is defined in Section 3.2.

3.1. Extension Versioning

The Extension Versioning uses a subset of the Semantic Versioning [SemVer] rules, where the patch version, pre-release version, and build metadata are not used. RDAP versioning is only associated with changes to the protocol interface that is the public API of [SemVer]. Only the [SemVer] major version and minor version are used for Extension Versioning. The RDAP extension given a version number MAJOR.MINOR, increment the:

  1. MAJOR version when you make incompatible protocol interface changes
  2. MINOR version when you add functionality in a backwards compatible manner

The following are the Extension Versioning rules based on modifications to the Semantic Versioning [SemVer] rules:

  1. A normal version MUST take the form X.Y where X.Y are non-negative integers, and MUST NOT contain leading zeroes. X is the major version and Y is the minor version. Each element MUST increase numerically. For instance: 1.1 -> 1.2 -> 1.3.
  2. Major version zero (0.y) is for initial definition. Anything MAY change at any time. The extension interface SHOULD NOT be considered stable. An extension that is an initial Internet Draft prior to Working Group Last Call (WGLC) SHOULD use a zero major version.
  3. Version 1.0 defines the extension interface. The way in which the version number is incremented after this is dependent on this extension interface and how it changes. An extension that is an initial Internet Draft that has passed Working Group Last Call (WGLC) SHOULD use version 1.0.
  4. Minor version Y (x.Y | x > 0) MUST be incremented if new, backwards compatible interface changes are introduced in the extension interface.
  5. Major version X (X.y | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the extension interface. It MAY also include minor level changes. The minor version MUST be reset to 0 when major version is incremented.

  6. Precedence refers to how versions are compared to each other when ordered.

    1. Precedence MUST be calculated by seperating the version into major and minor identifiers in that order.
    2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major and minor are always compared numerically. Example: 1.0 < 2.0 < 2.1.

3.2. Extension Version Identifier Syntax

The Augmented Backus-Naur Form (ABNF) grammar [RFC5234] format for the Extension Version Identifier is below, with the "identifier" rule matching the Extension Identifer in [RFC7480] and returned in the "rdapConformance" data structure of [RFC7483]:

extension-version-identifier = identifier ["-" major "." minor]
identifier = ALPHA *( ALPHA / DIGIT / "_")
major = numeric-identifer
minor = numeric-identifer
numeric-identifer = "0" / positive-digit *DIGIT
positive-digit = %x31-39 ; 1-9
Figure 1: Extension Version Identifier ABNF

Example Extension Version Identifiers:

"versioning-0.0"
Initial "versioning" extension version identifier that is not considered stable.
"ext1-1.0"
First stable version of the "ext1" extension.
"ext1-1.1"
Backward compatible change to the "ext1-1.0" extension version identifier.
"ext1-2.0"
Incompatible change to the "ext1-1.0" or "ext1-1.1" extension version identifier.

3.3. Profile Extension Versioning Considerations

Profile extensions represent existing entries in the RDAP Extensions Registry, defined in Section 8.1 of [RFC7480], that embed versioning information to signal policy implementation by the server. The RDAP Extensions Registry was not designed to support versioning, so the profile extensions represent a corner case that can be better handled using this extension. Examples include "icann_rdap_response_profile_0" and "icann_rdap_technical_implementation_guide_0", where the version "0" is included as a suffix of the extension identifier. The goal for the "versioning" extension is to handle the versioning consistently for all RDAP extensions, so the Extension Version Identifier MAY duplicate some of the version information included in the extension identifier initially. For example, for the extension identifier "icann_rdap_response_profile_0", the recommendation is to set the Extension Version Identifier of the "icann_rdap_response_profile_0" extension identifier to "icann_rdap_response_profile_0-1.0" to reflect it as the first stable version. Similarly, a future "icann_rdap_response_profile_1" extension identifier would have the Extension Version Identifier set to "icann_rdap_response_profile_1-2.0".

The profile extension identifiers can be transitioned to leverage this extension to fully handle the versioning of the extension by removing the versioning information from the extension identifiers and consolidating a set of profile extension identifiers with a single profile extension identifier. For example, the set of profile extension identifiers "icann_rdap_response_profile_0" and "icann_rdap_response_profile_1" can be consolidated to the single extension identifier "icann_rdap_response_profile" and the "versioning" extension can include the Extension Version Identifier values of "icann_rdap_response_profile-1.0" and "icann_rdap_response_profile-2.0". Embedding of versioning into the extension identifers was the only option available prior to the use of the "versioning" extension, which can be used to signal the versioning of all RDAP extensions.

4. Versioning Extension Version Indentier

The Extension Version Identifier (Section 3) associated with this version of the "versioning" extension is "versioning-0.1".

5. Versioning RDAP Query Parameter

This specification describes an OPTIONAL "versioning" query parameter for use with RDAP queries to specify the version of the RDAP extensions to include in the RDAP response. The "versioning" query parameter is a list of one or more Extension Version Identifiers, as defined in Section 3, seperated by commas. The Augmented Backus-Naur Form (ABNF) grammar [RFC5234] format for the "versioning" query parameter, using the "extension-version-identifier" rule from Figure 1, is:

versioning = "versioning="
  extension-version-identifier *("," extension-version-identifier)
Figure 2: Versioning Query Parameter ABNF

To bootstrap the use of the "versioning" extension, the client SHOULD use the "versioning" query parameter with the desired version of the "versioning" extension; otherwise it will be up to server policy what version of the "versioning" extension to return in the RDAP response.

Example RDAP queries using the "versioning" query parameter:

https://example.com/rdap/help?versioning=versioning-0.0
Help query using extension "versioning-0.0". The response can be found in figure Figure 9.
https://example.com/rdap/domain/versioning.example?versioning=ext1-0.1
Domain query using extension "ext1-0.1". The response can be found in figure Figure 5.
https://example.com/rdap/domain/versioning.example?versioning=ext1-0.1,versioning-0.0
Domain query using extensions "ext1-0.1" and "versioning-0.0". The response can be found in figure Figure 6.

6. Versioning RDAP Response

6.1. RDAP Conformance

RDAP responses that contain values described in this document MUST indicate conformance with this specification by including an "rdapConformance" ([RFC9083]) value of "versioning". The "versioning" extension identifier is described in Section 7.1.

Example "rdapConformance" member with the versioning extension:

"rdapConformance": [
  "rdap_level_0",
  "versioning"
]
Figure 3: "rdapConformance" with Versioning Extension

6.2. "versioning-help" Member

The "versioning-help" member MUST be added to a response of a RDAP help query, defined in [RFC9082], to indicate the RDAP extensions that are supported by the server. The "versioning-help" member contains an array of extension objects with the following child members:

"extension":
The Extension Identifer, defined in [RFC7480], and returned in the "rdapConformance" data structure of [RFC7483]. An example is the "versioning" extension identifier.
"versions":

An array of extension version objects with the following child members:

"version:"
The Extension Version Identifier, defined in Section 3. An example is the "versioning-0.1" extension version identifier.
"default:"
OPTIONAL boolean value indicating which of the extension version objects is the default returned by the server when the client doesn't specify the version using the "versioning" query parameter, defined in Section 5. When there is a single extension version object, then the "default" member value is true by default. When there is more than one extension version object, the server MUST include one extension version object with the "default" member set to true, and the remaining extension version objects "default" member value is false by default.
"start:"
OPTIONAL date and time that the extension version will be supported. When the member is not included, the extension version object is supported. Once the date and time has passed, the "start" member MUST be removed. The syntax for the date and time is defined in [RFC3339].
"end:"
OPTIONAL date and time that the extension version will stop being supported. When the member is not included, the extension version object has no planned support expiry. Once the date and time has passed, the extension version object MUST be removed and the extension object MUST be removed if the last extension version object is removed. The syntax for the date and time is defined in [RFC3339].
"links:"

OPTIONAL "links" array to extension version documentation. The relationship of these links is defined by the IANA registry described in [RFC8288]. The JSON name/values of "rel", "href", "hreflang", "title", "media", and "type" correspond to values found in Section 3 of [RFC8288]. The "value", "rel", and "href" JSON values MUST be specified. All other JSON values are OPTIONAL.

Example "links" member for the "ext2-0.1" extension version identifier:

Example help response with "versioning-help" and "versioning" members and no client specified versioning in the help query "https://example.com/rdap/help":

{
  "rdapConformance": [
    "rdap_level_0",
    "versioning"
  ],
  "versioning-help": [
    {
      "extension": "versioning",
      "versions": [
        {
          "version": "versioning-0.0"
        },
        {
          "version": "versioning-0.1",
          "default": true
        }
      ]
    },
    {
      "extension": "ext1",
      "versions": [
        {
          "version": "ext1-0.1",
          "end": "2022-12-31T23:59:59Z"
        },
        {
          "version": "ext1-1.0",
          "default": true
        },
        {
          "version": "ext1-1.1",
          "start": "2022-12-31T23:59:59Z"
        }
      ]
    },
    {
      "extension": "ext2",
      "versions": [
        {
          "version": "ext2-0.1",
          "end": "2022-12-31T23:59:59Z",
          "links": [
            {
              "value": "https://ext2.example/doc/html/ext2-01.txt",
              "rel": "describedby",
              "href": "https://ext2.example/doc/html/ext2-01.txt",
              "type": "text/plain"
            }
          ]
        }
      ]
    },
    {
      "extension": "ext3",
      "versions": [
        {
          "version": "ext3-1.0",
          "start": "2022-12-31T23:59:59Z"
        }
      ]
    }
  ],
  "versioning": [
    {
      "extension": "versioning",
      "version": "versioning-0.1"
    }
  ]
}
Figure 8: RDAP Help Response with No Client Specified Versioning

Example help response with the "versioning-help" and "versioning" members and client specified "versioning-0.0" extension version in the help query "https://example.com/rdap/help?versioning=versioning-0.0". The "versioning-0.0" extension version does not include support for the "default" member and uses the "ext" member instead of the "extension" member.

{
  "rdapConformance": [
    "rdap_level_0",
    "versioning"
  ],
  "versioning-help": [
    {
      "ext": "versioning",
      "versions": [
        {
          "version": "versioning-0.0"
        },
        {
          "version": "versioning-0.1"
        }
      ]
    },
    {
      "ext": "ext1",
      "versions": [
        {
          "version": "ext1-0.1",
          "end": "2022-12-31T23:59:59Z"
        },
        {
          "version": "ext1-1.0"
        },
        {
          "version": "ext1-1.1",
          "start": "2022-12-31T23:59:59Z"
        }
      ]
    },
    {
      "ext": "ext2",
      "versions": [
        {
          "version": "ext2-0.1",
          "end": "2022-12-31T23:59:59Z",
          "links": [
            {
              "value": "https://ext2.example/doc/html/ext2-01.txt",
              "rel": "describedby",
              "href": "https://ext2.example/doc/html/ext2-01.txt",
              "type": "text/plain"
            }
          ]
        }
      ]
    },
    {
      "ext": "ext3",
      "versions": [
        {
          "version": "ext3-1.0",
          "start": "2022-12-31T23:59:59Z"
        }
      ]
    }
  ],
  "versioning": [
    {
      "ext": "versioning",
      "version": "versioning-0.0"
    }
  ]
}
Figure 9: RDAP Help Response with "versioning-0.0" Extension Version

6.3. "versioning" Member

The "versioning" member MUST be added to the RDAP response when there is one or more RDAP extension fields. The "versioning" member is included as a member of the object class in a lookup response, such as the object classes defined in [RFC9083], and as a member of the object instances in a search response, such as the object instances defined in [RFC9083]. The "versioning" member contains an array of versioning objects with the following child members:

"extension":
The Extension Identifer, defined in [RFC7480], and returned in the "rdapConformance" data structure of [RFC7483]. An example is the "versioning" extension identifier.
"version":
The Extension Version Identifier, defined in Section 3, that is included in the response. An example is the "versioning-0.1" extension version identifier.

Example domain lookup response with "versioning" member and no client specified versioning in the lookup query "https://example.com/rdap/domain/versioning.example":

{
  "rdapConformance": [
    "rdap_level_0",
    "versioning",
    "ext1",
    "ext2"
  ],
  "objectClassName": "domain",
  "handle": "XXXX",
  "ldhName": "versioning.example",
  "links": [
    {
      "value": "https://example.net/domain/versioning.example",
      "rel": "self",
      "href": "https://example.net/domain/versioning.example",
      "type": "application/rdap+json"
    }
  ],
  "status": [
    "ok"
  ],
  "events": [
    {
      "eventAction": "registration",
      "eventDate": "1990-12-31T23:59:59Z"
    },
    {
      "eventAction": "expiration",
      "eventDate": "2023-12-31T23:59:59Z"
    }
  ],
  "ext1": {
    "value": "example 1",
    "newoptionalstring": "new value"
  },
  "ext2": {
    "name": "example 2"
  },
  "versioning": [
    {
      "extension": "versioning",
      "version": "versioning-0.1"
    },
    {
      "extension": "ext1",
      "version": "ext1-1.0"
    },
    {
      "extension": "ext2",
      "version": "ext2-0.1"
    }
  ]
}
Figure 4: RDAP Domain Lookup Response with No Client Specified Versioning

Example domain lookup response with "versioning" member and client specified "ext1-0.1" extension version in the lookup query "https://example.com/rdap/domain/versioning.example?versioning=ext1-0.1":

{
  "rdapConformance": [
    "rdap_level_0",
    "versioning",
    "ext1",
    "ext2"
  ],
  "objectClassName": "domain",
  "handle": "XXXX",
  "ldhName": "versioning.example",
  "links": [
    {
      "value": "https://example.net/domain/versioning.example",
      "rel": "self",
      "href": "https://example.net/domain/versioning.example",
      "type": "application/rdap+json"
    }
  ],
  "status": [
    "ok"
  ],
  "events": [
    {
      "eventAction": "registration",
      "eventDate": "1990-12-31T23:59:59Z"
    },
    {
      "eventAction": "expiration",
      "eventDate": "2023-12-31T23:59:59Z"
    }
  ],
  "ext1": {
    "value": "example 1"
  },
  "ext2": {
    "name": "example 2"
  },
  "versioning": [
    {
      "extension": "versioning",
      "version": "versioning-0.1"
    },
    {
      "extension": "ext1",
      "version": "ext1-0.1"
    },
    {
      "extension": "ext2",
      "version": "ext2-0.1"
    }
  ]
}
Figure 5: RDAP Domain Lookup Response with "ext1-0.1" Extension Version

Example domain lookup response with "versioning" member and client specified "ext1-0.1" and "versioning-0.0" extension versions in the lookup query "https://example.com/rdap/domain/versioning.example?versioning=ext1-0.1,versioning-0.0":

{
  "rdapConformance": [
    "rdap_level_0",
    "versioning",
    "ext1",
    "ext2"
  ],
  "objectClassName": "domain",
  "handle": "XXXX",
  "ldhName": "versioning.example",
  "links": [
    {
      "value": "https://example.net/domain/versioning.example",
      "rel": "self",
      "href": "https://example.net/domain/versioning.example",
      "type": "application/rdap+json"
    }
  ],
  "status": [
    "ok"
  ],
  "events": [
    {
      "eventAction": "registration",
      "eventDate": "1990-12-31T23:59:59Z"
    },
    {
      "eventAction": "expiration",
      "eventDate": "2023-12-31T23:59:59Z"
    }
  ],
  "ext1": {
    "value": "example 1"
  },
  "ext2": {
    "name": "example 2"
  },
  "versioning": [
    {
      "ext": "versioning",
      "version": "versioning-0.0"
    },
    {
      "ext": "ext1",
      "version": "ext1-0.1"
    },
    {
      "ext": "ext2",
      "version": "ext2-0.1"
    }
  ]
}
Figure 6: RDAP Domain Lookup Response with "ext1-0.1" and "versioning-0.0" Extension Versions

7. IANA Considerations

7.1. RDAP Extensions Registry

IANA is requested to register the following value in the RDAP Extensions Registry:

Extension identifier:
versioning
Registry operator:
Any
Published specification:
This document.
Contact:
IESG <[email protected]>
Intended usage:
This extension identifies RDAP extension versioning.

8. Security Considerations

The RDAP extensions available to clients can be subject to server disclosure and authorization policies. Inclusion of available RDAP extensions and their available versions in the "versioning-help" member, defined in Section 6.2, of the RDAP help response and inclusion of the RDAP extensions in the RDAP response with the "versioning" member, defined in Section 6.3, can be dependent on authentication and authorization of the client by the server.

9. Acknowledgements

The authors wish to thank the following persons for their feedback and suggestions: Scott Hollenbeck, Andy Newton, and Jasdip Singh.

10. References

10.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3339]
Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, , <https://www.rfc-editor.org/info/rfc3339>.
[RFC5234]
Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, , <https://www.rfc-editor.org/info/rfc5234>.
[RFC7480]
Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the Registration Data Access Protocol (RDAP)", STD 95, RFC 7480, DOI 10.17487/RFC7480, , <https://www.rfc-editor.org/info/rfc7480>.
[RFC7483]
Newton, A. and S. Hollenbeck, "JSON Responses for the Registration Data Access Protocol (RDAP)", RFC 7483, DOI 10.17487/RFC7483, , <https://www.rfc-editor.org/info/rfc7483>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8288]
Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/info/rfc8288>.
[RFC9082]
Hollenbeck, S. and A. Newton, "Registration Data Access Protocol (RDAP) Query Format", STD 95, RFC 9082, DOI 10.17487/RFC9082, , <https://www.rfc-editor.org/info/rfc9082>.
[RFC9083]
Hollenbeck, S. and A. Newton, "JSON Responses for the Registration Data Access Protocol (RDAP)", STD 95, RFC 9083, DOI 10.17487/RFC9083, , <https://www.rfc-editor.org/info/rfc9083>.

10.2. Informative References

[SemVer]
"Semantic Versioning 2.0.0 (text from June 19, 2020)", <https://github.com/semver/semver/blob/8b2e8eec394948632957639dfa99fc7ec6286911/semver.md>.

Appendix A. Change History

A.1. Change from 00 to 01

  1. Updated the Abstract to reference the use of machine-parseable identifiers.
  2. Updated the Introduction to reference the informal support for versioning in RFC9083.
  3. Removed rule "An extension using Extension Versioning MUST declare the extension in a specification." from Section 3.1 "Extension Versioning".

Authors' Addresses

James Gould
VeriSign, Inc.
12061 Bluemont Way
Reston, VA 20190
United States of America
URI: http://www.verisigninc.com
Daniel Keathley
VeriSign, Inc.
12061 Bluemont Way
Reston, VA 20190
United States of America
URI: http://www.verisigninc.com
Mario Loffredo
IIT-CNR/Registro.it
Via Moruzzi,1
56124 Pisa
Italy
URI: http://www.iit.cnr.it