Network Working Group J.G. Gould Internet-Draft D.K. Keathley Intended status: Standards Track VeriSign, Inc. Expires: 2 June 2023 M. Loffredo IIT-CNR/Registro.it 29 November 2022 Versioning in the Registration Data Access Protocol (RDAP) draft-gould-regext-rdap-versioning-00 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. 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 2 June 2023. Copyright Notice Copyright (c) 2022 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. Gould, et al. Expires 2 June 2023 [Page 1] Internet-Draft Versioning in RDAP November 2022 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 3. Extension Version Identifier . . . . . . . . . . . . . . . . 3 3.1. Extension Versioning . . . . . . . . . . . . . . . . . . 3 3.2. Extension Version Identifier Syntax . . . . . . . . . . . 4 3.3. Profile Extension Versioning Considerations . . . . . . . 5 4. Versioning Extension Version Indentier . . . . . . . . . . . 6 5. Versioning RDAP Query Parameter . . . . . . . . . . . . . . . 6 6. Versioning RDAP Response . . . . . . . . . . . . . . . . . . 7 6.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 7 6.2. "versioning-help" Member . . . . . . . . . . . . . . . . 7 6.3. "versioning" Member . . . . . . . . . . . . . . . . . . . 12 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 7.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 16 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 9.1. Normative References . . . . . . . . . . . . . . . . . . 16 9.2. Informative References . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 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, but there is no standard mechanism defined in [RFC9083] that exists to support extension version signaling by the server. RDAP does not support the server providing the extension versions that are supported by the server and does not support the ability for a client to identify the desired RDAP extension versions to include in an RDAP response. 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. 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 Gould, et al. Expires 2 June 2023 [Page 2] Internet-Draft Versioning in RDAP November 2022 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. An extension using Extension Versioning MUST declare the extension in a specification. Gould, et al. Expires 2 June 2023 [Page 3] Internet-Draft Versioning in RDAP November 2022 2. 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. 3. 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. 4. 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. 5. Minor version Y (x.Y | x > 0) MUST be incremented if new, backwards compatible interface changes are introduced in the extension interface. 6. 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. 7. 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]: Gould, et al. Expires 2 June 2023 [Page 4] Internet-Draft Versioning in RDAP November 2022 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". Gould, et al. Expires 2 June 2023 [Page 5] Internet-Draft Versioning in RDAP November 2022 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. Gould, et al. Expires 2 June 2023 [Page 6] Internet-Draft Versioning in RDAP November 2022 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 Gould, et al. Expires 2 June 2023 [Page 7] Internet-Draft Versioning in RDAP November 2022 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: "links": [ { "value": "https://ext2.example/doc/html/ext2-01.txt", "rel": "describedby", "href": "https://ext2.example/doc/html/ext2-01.txt", "type": "text/plain" } ] Figure 7: Example of "links" Member Gould, et al. Expires 2 June 2023 [Page 8] Internet-Draft Versioning in RDAP November 2022 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", Gould, et al. Expires 2 June 2023 [Page 9] Internet-Draft Versioning in RDAP November 2022 "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" }, { Gould, et al. Expires 2 June 2023 [Page 10] Internet-Draft Versioning in RDAP November 2022 "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": [ Gould, et al. Expires 2 June 2023 [Page 11] Internet-Draft Versioning in RDAP November 2022 { "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" } Gould, et al. Expires 2 June 2023 [Page 12] Internet-Draft Versioning in RDAP November 2022 ], "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": Gould, et al. Expires 2 June 2023 [Page 13] Internet-Draft Versioning in RDAP November 2022 { "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", Gould, et al. Expires 2 June 2023 [Page 14] Internet-Draft Versioning in RDAP November 2022 "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": { Gould, et al. Expires 2 June 2023 [Page 15] Internet-Draft Versioning in RDAP November 2022 "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 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. References 9.1. Normative References Gould, et al. Expires 2 June 2023 [Page 16] Internet-Draft Versioning in RDAP November 2022 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [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, March 2015, . [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the Registration Data Access Protocol (RDAP)", RFC 7483, DOI 10.17487/RFC7483, March 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8288] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, . [RFC9082] Hollenbeck, S. and A. Newton, "Registration Data Access Protocol (RDAP) Query Format", STD 95, RFC 9082, DOI 10.17487/RFC9082, June 2021, . [RFC9083] Hollenbeck, S. and A. Newton, "JSON Responses for the Registration Data Access Protocol (RDAP)", STD 95, RFC 9083, DOI 10.17487/RFC9083, June 2021, . 9.2. Informative References [SemVer] "Semantic Versioning 2.0.0 (text from June 19, 2020)", . Gould, et al. Expires 2 June 2023 [Page 17] Internet-Draft Versioning in RDAP November 2022 Authors' Addresses James Gould VeriSign, Inc. 12061 Bluemont Way Reston, VA 20190 United States of America Email: jgould@verisign.com URI: http://www.verisigninc.com Daniel Keathley VeriSign, Inc. 12061 Bluemont Way Reston, VA 20190 United States of America Email: dkeathley@verisign.com URI: http://www.verisigninc.com Mario Loffredo IIT-CNR/Registro.it Via Moruzzi,1 56124 Pisa Italy Email: mario.loffredo@iit.cnr.it URI: http://www.iit.cnr.it Gould, et al. Expires 2 June 2023 [Page 18]