Versioning in the Registration Data Access Protocol
(RDAP)VeriSign, Inc.12061 Bluemont WayRestonVA20190USjgould@verisign.comhttp://www.verisigninc.comVeriSign, Inc.12061 Bluemont WayRestonVA20190USdkeathley@verisign.comhttp://www.verisigninc.comIIT-CNR/Registro.itVia Moruzzi,1PisaIT56124mario.loffredo@iit.cnr.ithttp://www.iit.cnr.itVersionVersioningExtensionThis 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.IntroductionRDAP supports identifying the RDAP extensions included in an RDAP response
using the RDAP Conformance, defined in . 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 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 , using
the "versioning-help" member . 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 .
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 . The "versioning" query parameter is set with a list of extension version identifiers ,
delimeted by a comma (',').
Conventions Used in This DocumentThe 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
when, and only when, they
appear in all capitals, as shown here.Extension Version IdentifierThe 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 , along with the Extension Versioning defined in .
The format of the Extension Version Identifier is defined in .Extension Versioning
The Extension Versioning uses a subset of the Semantic Versioning 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 . Only the
major version and minor version are used for Extension Versioning. The RDAP extension given a version number MAJOR.MINOR, increment the:
MAJOR version when you make incompatible protocol interface changes
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 rules:
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.
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.
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.
Minor version Y (x.Y | x > 0) MUST be incremented if new, backwards compatible interface changes are introduced in the extension interface.
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.
Precedence refers to how versions are compared to each other when ordered.
Precedence MUST be calculated by seperating the version into major and minor identifiers in that order.
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.
Extension Version Identifier SyntaxThe Augmented Backus-Naur Form (ABNF) grammar format for the Extension Version Identifier is below, with
the "identifier" rule matching the Extension Identifer in and returned in the "rdapConformance" data structure of :Extension Version Identifier ABNF
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
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.
Profile Extension Versioning ConsiderationsProfile extensions represent existing entries in the RDAP Extensions Registry, defined
in ,
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.Versioning Extension Version IndentierThe Extension Version Identifier associated with this version of the "versioning" extension is "versioning-0.1".Versioning RDAP Query ParameterThis 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 , seperated by commas.
The Augmented Backus-Naur Form (ABNF) grammar format for the "versioning" query parameter, using the "extension-version-identifier" rule from
, is:Versioning Query Parameter ABNF
versioning = "versioning="
extension-version-identifier *("," extension-version-identifier)
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:
Domain query using extensions "ext1-0.1" and "versioning-0.0". The response can be found in figure .
Versioning RDAP ResponseRDAP ConformanceRDAP responses that contain values described in this document MUST
indicate conformance with this specification by including an
"rdapConformance" () value of "versioning".
The "versioning" extension identifier is described in .Example "rdapConformance" member with the versioning extension:"rdapConformance" with Versioning Extension
"rdapConformance": [
"rdap_level_0",
"versioning"
]
"versioning-help" MemberThe "versioning-help" member MUST be added to a response of a RDAP help query, defined in , 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 , and returned in the "rdapConformance" data structure of . 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 .
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 .
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 .
"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 .
"links:"
OPTIONAL "links" array to extension version documentation. The relationship of these links is defined by the IANA registry described in .
The JSON name/values of "rel", "href", "hreflang", "title", "media", and "type" correspond to values found in .
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 of "links" Member
"links": [
{
"value": "https://ext2.example/doc/html/ext2-01.txt",
"rel": "describedby",
"href": "https://ext2.example/doc/html/ext2-01.txt",
"type": "text/plain"
}
]
Example help response with "versioning-help" and "versioning" members and no client specified versioning
in the help query "https://example.com/rdap/help":RDAP Help Response with No Client Specified Versioning
{
"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"
}
]
}
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.RDAP Help Response with "versioning-0.0" Extension Version
{
"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"
}
]
}
"versioning" MemberThe "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 , and
as a member of the object instances in a search response, such as the object instances defined in . The "versioning" member contains an array
of versioning objects with the following child members:
"extension":
The Extension Identifer, defined in , and returned in the "rdapConformance" data structure of . An example is the "versioning" extension identifier.
"version":
The Extension Version Identifier, defined in , 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":RDAP Domain Lookup Response with No Client Specified Versioning
{
"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"
}
]
}
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":RDAP Domain Lookup Response with "ext1-0.1" Extension Version
{
"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"
}
]
}
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":RDAP Domain Lookup Response with "ext1-0.1" and "versioning-0.0" Extension Versions
{
"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"
}
]
}
IANA ConsiderationsRDAP Extensions RegistryIANA is requested to register the following value in the RDAP
Extensions Registry:
Extension identifier:
versioning
Registry operator:
Any
Published specification:
This document.
Contact:
IESG <iesg@ietf.org>
Intended usage:
This extension identifies RDAP extension versioning.
Security ConsiderationsThe 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 , of the RDAP help response and inclusion
of the RDAP extensions in the RDAP response with the "versioning" member,
defined in ,
can be dependent on authentication and authorization of the client by the server.
AcknowledgementsThe authors wish to thank the following persons for their feedback and suggestions:
,
,
and .
ReferencesNormative ReferencesInformative ReferencesSemantic Versioning 2.0.0 (text from June 19, 2020)Change HistoryChange from 00 to 01
Updated the Abstract to reference the use of machine-parseable identifiers.
Updated the Introduction to reference the informal support for versioning in RFC9083.
Removed rule "An extension using Extension Versioning MUST declare the extension in a specification." from Section 3.1 "Extension Versioning".