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 an extensible set of versioning types with
the features of identifying the RDAP extension versions supported by the server, the RDAP extension versions included in an RDAP
response, and enabling a client to specify the desired RDAP extension versions to include in the RDAP query and RDAP response.IntroductionRDAP supports identifying the RDAP extensions included in an RDAP response
using the RDAP Conformance data structure, defined in .
The RDAP Conformance values are identifiers with no standard mechanism to support structured, machine-parseable version signaling by the server.
This document describes an RDAP extension for an extensible set of versioning types, with the pre-defined versioning types of Opaque Versioning and Semantic Versioning, that have the following features:
Enabling a client to specify the desired RDAP extension versions to include in the RDAP query and RDAP response, using the Extension Versioning Request. The client can specify the desired RDAP extension versions to include in the RDAP query and RDAP response with
the "versioning" query parameter or the RDAP-X media type "extensions" parameter.
Identifying the RDAP extension versions supported by the server. 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 and additional extension information, such the available set of extension versions and the extension version document.
Identifying the RDAP extension versions included in an RDAP response. The RDAP extension versions included in an RDAP response are identified using the "versioning" member.
The "versioning" member includes a list of extension versions included in the RDAP response that extends the extension identifiers in the RDAP Conformance to include versioning information.
There are two predefined versioning types that include:
Opaque Versioning, as defined in Section 8 of , to support RDAP extensions that are identified using the Extension Identifier included in the RDAP Conformance.
Semantic Versioning to support RDAP extensions that include a major and minor version with the Extension Identifier.
The versioning types are registered in the JSON Values Registry, where new versioning types can be defined and registered in the future. The specification of
a versioning type defines how the base set of features of the versioning extension are used for the versioning type.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.Versioning RDAP FeaturesThe extension includes a base set of features that can be used for any defined versioning type. The features enable the client to discover what extension versions is supported by the server,
enable the client to specify what extension versions are desired in an RDAP query and RDAP response, and provide the extension versions included in the RDAP response by the server. Examples are provided using the two predefined
versioning types in . The format of the Extension Version Indentifier is general enough to support
a broad range of future versioning types.
Extension Version IdentifierThe Extension Version Identifier adds support for versioning to the Extension Identifer in that is returned in the RDAP Conformance data structure of .
Each versioning type will define the scheme and the meaning of the "versioning" Augmented Backus-Naur Form (ABNF) grammar rule.
The Extension Version Identifier is used to uniquely identify a version of an RDAP extension in the Extension Versioning Request, the members of the "versioning-help" Member, and
the members of the "versioning" Member.Extension Version Identifier ABNF
extension-version-identifier = identifier versioning
identifier = ALPHA *( ALPHA / DIGIT / "_") ; Extension Identifer
versioning = ["-" 1*VCHAR]
Example Extension Version Identifiers:
"versioning"
Opaque versioning of the "versioning" extension.
"versioning-0.2"
Semantic versioning of the "versioning" extension.
"semantic_ext1-1.0"
Semantic versioning of the "semantic_ext1" extension.
"opaque_ext1"
Opaque versioning of the "opaque_ext1" extension.
"dated_ext1-20231129"
Use of potential dated versioning with the format YYYYMMDD.
Extension Versioning RequestThe client MAY provide an Extension Versioning Request to indicate the desired extension versions to include in the RDAP query and RDAP response. There are two Extension Versioning Request methods with the Versioning Query Parameter
and the Versioning Extensions Media Type Parameter. The server MUST support both methods of Extension Versioning Request methods and the client MUST use at most a single Extension Versioning Request method in the RDAP query.The Extension Versioning Request provides a hint from the client what extension versions to include in the RDAP query by the client and RDAP response by the server.
It is up to server policy what extension versions to support in the RDAP query and the extension versions to include in the RDAP response, based
on the supported set of extensions, the default extension versions, and the hint provided by the client using the Extension Versioning Request.Versioning Query ParameterThe "versioning" query parameter MAY be used with RDAP queries to specify the RDAP extension versions to include in the RDAP query and the RDAP response.
The "versioning" query parameter is a list of one or more Extension Version Identifiers, as defined in , seperated by commas.
The ABNF 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)
Example RDAP queries using the "versioning" query parameter:
Domain query using extensions "semantic_ext1-0.1" and "opaque_ext2". The response can be found in .
Versioning Extensions Media Type ParameterThe Extensions Media Type Parameter MAY be used with RDAP queries to specify the RDAP extension versions to include in the RDAP query and the RDAP response.
The RDAP extensions included in the "extensions" parameter are Extension Version Identifiers, as defined in .
The "extensions" Versioning Extensions Type Parameter is a list of one or more Extension Version Identifiers, as defined in , seperated by whitespace (%x20).
The use of the "-" character in the Extension Version Identifier ABNF ensures that an Extension Version Identifier with a non-empty "versioning" ABNF rule will not conflict with
an Extension Identifier. The ABNF format for the "extensions" parameter, using the "extension-version-identifier" rule from
, is:Versioning Extensions Media Type Parameter ABNF
extensions = "extensions="
DQUOTE
extension-version-identifier
*(SP extension-version-identifier)
DQUOTE
Example Versioning Extensions Media Type Parameter values:
extensions="versioning-0.2"
Versioning Extensions Media Type Parameter for the "versioning" extension with the semantic versioning of "versioning-0.2".
The response for the /help query "https://example.com/rdap/help" with the Versioning Extensions Media Type Parameter value can be found in .
extensions="semantic_ext1-0.1"
Versioning Extensions Media Type Parameter for the "semantic_ext1" extension with the semantic versioning of "semantic_ext1-0.1". The domain query "https://example.com/rdap/domain/versioning.example" response with the Versioning Extensions Media Type Parameter value can be found in .
extensions="semantic_ext1-0.1 opaque_ext2"
Versioning Extensions Media Type Parameter for the "semantic_ext1" and "opaque_ext2" extensions with the semantic versioning of "semantic_ext1-0.1" and opaque versioning of "opaque_ext2", respectively. The domain query "https://example.com/rdap/domain/versioning.example" response with the Versioning Extensions Media Type Parameter value can be found in .
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 the response of a /help query, defined in , to indicate the extension versions that are supported by the server.
This extends the information provided by the guidance in Section 7 of , with inclusion of the all supported
extension identifiers in the RDAP Conformance to the response of a /help query.
The "versioning-help" member contains an array of extension objects with the following child members:
"extension":
REQUIRED Extension Identifer, defined in , and returned in the "rdapConformance" data structure of . An example is the "versioning" extension identifier.
"type":
REQUIRED versioning type used by the extension. The versioning types are registered using the "versioning" type in the JSON Values Registry.
There are two predefined versioning types, including "opaque" (see Opaque Versioning) and
"semantic" (see Semantic Versioning)
"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.2" 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 only 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/ext2-01.txt",
"rel": "describedby",
"href": "https://ext2.example/ext2-01.txt",
"type": "text/plain"
}
]
Example response to /help query with "versioning-help" and "versioning" members and no client specified versioning
in the /help query "https://example.com/rdap/help":Response to /help Query with No Client Specified Versioning
{
"rdapConformance": [
"rdap_level_0",
"versioning",
"opaque_ext1",
"opaque_ext2",
"semantic_ext1",
"semantic_ext2",
"semantic_ext3"
],
"versioning-help": [
{
"extension": "versioning",
"type": "semantic",
"versions": [
{
"version": "versioning-0.1"
},
{
"version": "versioning-0.2",
"default": true
}
]
},
{
"extension": "opaque_ext1",
"type": "opaque",
"versions": [
{
"version": "opaque_ext1"
"default": true
}
],
"end": "2023-12-31T23:59:59Z"
},
{
"extension": "opaque_ext2",
"type": "opaque",
"versions": [
{
"version": "opaque_ext2"
"default": true
}
],
"links": [
{
"value": "https://ext2.example/paque_ext2.txt",
"rel": "describedby",
"href": "https://ext2.example/paque_ext2.txt",
"type": "text/plain"
}
]
},
{
"extension": "semantic_ext1",
"type": "semantic",
"versions": [
{
"version": "semantic_ext1-0.1",
"end": "2023-12-31T23:59:59Z"
},
{
"version": "semantic_ext1-1.0",
"default": true
},
{
"version": "semantic_ext1-1.1",
"start": "2023-12-31T23:59:59Z"
}
]
},
{
"extension": "semantic_ext2",
"type": "semantic",
"versions": [
{
"version": "semantic_ext2-0.1",
"end": "2023-12-31T23:59:59Z",
"links": [
{
"value": "https://ext2.example/semantic_ext2-01.txt",
"rel": "describedby",
"href": "https://ext2.example/semantic_ext2-01.txt",
"type": "text/plain"
}
]
}
]
},
{
"extension": "semantic_ext3",
"type": "semantic",
"versions": [
{
"version": "semantic_ext3-1.0",
"start": "2023-12-31T23:59:59Z"
}
]
}
],
"versioning": [
{
"extension": "versioning",
"type": "semantic",
"version": "versioning-0.2"
}
]
}
Example response to /help query with the "versioning-help" and "versioning" members and client specified "versioning-0.1" extension version
in the /help query "https://example.com/rdap/help?versioning=versioning-0.1". The "versioning-0.1" extension version does
not include support for the "type" member.Response to /help Query with "versioning-0.1" Extension Version
{
"rdapConformance": [
"rdap_level_0",
"versioning",
"opaque_ext1",
"opaque_ext2",
"semantic_ext1",
"semantic_ext2",
"semantic_ext3"
],
"versioning-help": [
{
"extension": "versioning",
"versions": [
{
"version": "versioning-0.1"
},
{
"version": "versioning-0.2",
"default": true
}
]
},
{
"extension": "opaque_ext1",
"versions": [
{
"version": "opaque_ext1-1.0",
"default": true
}
]
},
{
"extension": "opaque_ext2",
"versions": [
{
"version": "opaque_ext2-1.0",
"default": true
}
]
},
{
"extension": "semantic_ext1",
"versions": [
{
"version": "semantic_ext1-0.1",
"end": "2023-12-31T23:59:59Z"
},
{
"version": "semantic_ext1-1.0",
"default": true
},
{
"version": "semantic_ext1-1.1",
"start": "2023-12-31T23:59:59Z"
}
]
},
{
"extension": "semantic_ext2",
"versions": [
{
"version": "semantic_ext2-0.1",
"end": "2023-12-31T23:59:59Z",
"links": [
{
"value": "https://ext2.example/semantic_ext2-01.txt",
"rel": "describedby",
"href": "https://ext2.example/semantic_ext2-01.txt",
"type": "text/plain"
}
]
}
]
},
{
"extension": "semantic_ext3",
"versions": [
{
"version": "semantic_ext3-1.0",
"start": "2023-12-31T23:59:59Z"
}
]
}
],
"versioning": [
{
"extension": "versioning",
"version": "versioning-0.1"
}
]
}
"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 , and as a member of the response to a /help query, such as shown in Response to /help Query with No Client Specified Versioning.
The "versioning" member contains an array
of versioning objects with the following child members:
"extension":
REQUIRED Extension Identifer, defined in , and returned in the "rdapConformance" data structure of . An example is the "versioning" extension identifier.
"type":
REQUIRED versioning type used by the extension. The versioning types are registered using the "versioning" type in the JSON Values Registry.
There are two predefined versioning types, including "opaque" (see Opaque Versioning) and
"semantic" (see Semantic Versioning)
"version":
REQUIRED Extension Version Identifier, defined in , that is included in the response. An example is the "versioning-0.2" 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",
"semantic_ext1",
"opaque_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"
}
],
"semantic_ext1": {
"value": "example 1",
"newoptionalstring": "new value"
},
"opaque_ext2": {
"name": "example 2"
},
"versioning": [
{
"extension": "versioning",
"type": "semantic",
"version": "versioning-0.2"
},
{
"extension": "semantic_ext1",
"type": "semantic",
"version": "semantic_ext1-1.0"
},
{
"extension": "opaque_ext2",
"type": "opaque",
"version": "opaque_ext2"
}
]
}
Example domain lookup response with "versioning" member and client specified "semantic_ext1-0.1" extension version
in the lookup query "https://example.com/rdap/domain/versioning.example?versioning=semantic_ext1-0.1":RDAP Domain Lookup Response with "semantic_ext1-0.1" Extension Version
{
"rdapConformance": [
"rdap_level_0",
"versioning",
"semantic_ext1",
"opaque_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"
}
],
"semantic_ext1": {
"value": "example 1"
},
"opaque_ext2": {
"name": "example 2"
},
"versioning": [
{
"extension": "versioning",
"type": "semantic",
"version": "versioning-0.2"
},
{
"extension": "semantic_ext1",
"type": "semantic",
"version": "semantic_ext1-0.1"
},
{
"extension": "opaque_ext2",
"type": "opaque",
"version": "opaque_ext2"
}
]
}
Example domain lookup response with "versioning" member and client specified "semantic_ext1-0.1" and "opaque_ext2" extension versions
in the lookup query "https://example.com/rdap/domain/versioning.example?versioning=semantic_ext1-0.1,opaque_ext2":RDAP Domain Lookup Response with "semantic_ext1-0.1" and "opaque_ext2" Extension Versions
{
"rdapConformance": [
"rdap_level_0",
"versioning",
"semantic_ext1",
"opaque_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"
}
],
"semantic_ext1": {
"value": "example 1"
},
"opaque_ext2": {
"name": "example 2"
},
"versioning": [
{
"extension": "versioning",
"type": "semantic",
"version": "versioning-0.2"
},
{
"extension": "semantic_ext1",
"type": "semantic",
"version": "semantic_ext1-0.1"
},
{
"extension": "opaque_ext2",
"type": "opaque",
"version": "opaque_ext2"
}
]
}
Versioning TypesVersioning types are extensible by formally defining the extension version identifer, how the versioning type is
represented in the "versioning-help" member, and how the versioning type
is represented in the "versioning" member. The definition of the
extension version identifier determines how the versioning type is represented in the Extension Versioning Request. Each
versioning type needs to have a unique "versioning" RDAP JSON Values Registry Type field value. This document pre-defines two versioning types with Opaque Versioning and
Semantic Versioning. Other versioning types can be defined and registered in the RDAP JSON Values Registry.Opaque VersioningOpaque Versioning is defined in Section 8 of , to support RDAP extensions that are identified using the Extension Identifier included in the RDAP Conformance
and is the base versioning type that can be applied to any RDAP extension. All RDAP extensions are registered in the RDAP Extensions Registry using the Extension Identifier in , which is the basis for other versioning types.
An RDAP Extension that supports another versioning type, such as the Semantic Versioning,
MAY be referred to using Opaque Versioning in the Extension Versioning Request and
the server returns the extension version with the "default" member set to true.Opaque Versioning IdentifierThe Opaque Versioning Identifier directly matches the Extension Identifier registered in the RDAP Extensions Registry.
The ABNF for the Extension Identifier is defined in "Figure 1: ABNF for JSON Names" of .Example Opaque Extension Versioning Identifiers:
"versioning"
Opaque versioning of the "versioning" extension.
"opaque_ext1"
Opaque versioning of the "opaque_ext1" extension.
Opaque Versioning "versioning-help" MemberFor an RDAP extension that only supports Opaque Extension Versioning, there is only a single extension version. All of the
members of the "versioning-help" member is supported wth Opaque Versioning, but there will
be only a single "versions" member object that has the "version" member matching the "extension" member value. Clients can leverage
the Extension Version Identifier value in the Extension Versioning Request for Opaque Versioning.Example response to /help query with "versioning-help" and "versioning" members with support for only Opaque Versioning
in the /help query "https://example.com/rdap/help":Response to /help Query with only Opaque Versioning
{
"rdapConformance": [
"rdap_level_0",
"versioning",
"opaque_ext1",
"opaque_ext2",
],
"versioning-help": [
{
"extension": "versioning",
"type": "opaque",
"versions": [
{
"version": "versioning"
},
]
},
{
"extension": "opaque_ext1",
"type": "opaque",
"versions": [
{
"version": "opaque_ext1"
}
],
"end": "2023-12-31T23:59:59Z"
},
{
"extension": "opaque_ext2",
"type": "opaque",
"versions": [
{
"version": "opaque_ext2"
}
],
"start": "2023-12-31T23:59:59Z",
"links": [
{
"value": "https://ext2.example/opaque_ext2.txt",
"rel": "describedby",
"href": "https://ext2.example/paque_ext2.txt",
"type": "text/plain"
}
]
}
],
"versioning": [
{
"extension": "versioning",
"type": "opaque",
"version": "versioning"
}
]
}
Opaque Versioning "versioning" MemberAll of the members of the "versioning" member is supported wth Opaque Versioning,
where the "extension" and "version" member are both set with the Extension Identifier and the "type" is set to "opaque". The Response to /help Query with only Opaque Versioning
includes an example of of the "versioning" extension represented using Opaque Versioning.Semantic VersioningThe Semantic 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 , so there is no concept of
patching, pre-release, and build metadata information. Only the
major version and minor version are used for Extension Versioning, and is based on the stability of the extension as opposed to backward compatibility.
The RDAP extension given a version number MAJOR.MINOR, increment the:
MAJOR version when the extension interface is considered stable and complete
MINOR version includes an update to the extension interface that is not considered stable and complete
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 interface changes are introduced in the extension interface from the last major version.
Major version X (X.y | X > 0) MUST be incremented once the new interface is considered stable and complete. 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.
Semantic Extension Version IdentifierThe Semantic Versioning Identifier defines the versioning ABNF rule in Extension Version Identifier ABNF to include the major and minor version of the extension that
follows the modified Semantic Versioning rules.Semantic Versioning Identifier ABNF
semantic-version-identifier = identifier versioning
identifier = ALPHA *( ALPHA / DIGIT / "_") ; Extension Identifier
versioning = ; "-" major "." minor
major = numeric-identifer
minor = numeric-identifer
numeric-identifer = "0" / positive-digit *DIGIT
positive-digit = %x31-39 ; 1-9
Example Semantic Extension Versioning Identifiers:
"versioning-0.2"
The "versioning" extension version identifier that is not considered stable.
"semantic_ext1-1.0
First stable version of the "semantic_ext1" extension.
"semantic_ext1-1.1"
Update to "semantic_ext1-1.0" of the "semantic_ext1" extension that is not considered stable.
"semantic_ext1-2.0"
New stable version of the "semantic_ext1" extension.
Semantic Versioning "versioning-help" MemberFor an RDAP extension that supports Semantic Extension Versioning, there can be many Extension Versioning Identifiers associated with the Extension Identifier,
so the "versions" member of the "versioning-help" member can include a list of more than one extension version object. All of the
members of the "versioning-help" member is supported wth Semantic Versioning.Example response to /help query with "versioning-help" and "versioning" members with support for Semantic Versioning
in the /help query "https://example.com/rdap/help":Response to /help Query with only Semantic Versioning
{
"rdapConformance": [
"rdap_level_0",
"versioning",
"semantic_ext1",
"semantic_ext2",
"semantic_ext3"
] ],
"versioning-help": [
{
"extension": "versioning",
"type": "semantic",
"versions": [
{
"version": "versioning-0.1"
},
{
"version": "versioning-0.2",
"default": true
}
]
},
{
"extension": "semantic_ext1",
"type": "semantic",
"versions": [
{
"version": "semantic_ext1-0.1",
"end": "2023-12-31T23:59:59Z"
},
{
"version": "semantic_ext1-1.0",
"default": true
},
{
"version": "semantic_ext1-1.1",
"start": "2023-12-31T23:59:59Z"
}
]
},
{
"extension": "semantic_ext2",
"type": "semantic",
"versions": [
{
"version": "semantic_ext2-0.1",
"end": "2023-12-31T23:59:59Z",
"links": [
{
"value": "https://ext2.example/semantic_ext2-01.txt",
"rel": "describedby",
"href": "https://ext2.example/semantic_ext2-01.txt",
"type": "text/plain"
}
]
}
]
},
{
"extension": "semantic_ext3",
"type": "semantic",
"versions": [
{
"version": "semantic_ext3-1.0",
"start": "2023-12-31T23:59:59Z"
}
]
}
],
"versioning": [
{
"extension": "versioning",
"type": "opaque",
"version": "versioning-0.2"
}
]
}
Semantic Versioning "versioning" MemberAll of the members of the "versioning" member is supported wth Semantic Versioning,
where the "extension" member is set with the Extension Identifier, the "version" member of the extension included in the response is set with Semantic Extension Version Identifier, and the "type" is set to "semantic".
The Response to /help Query with only Semantic Versioning includes an example of of the "versioning" extension represented using Semantic Versioning with "versioning-0.2".Versioning ConsiderationsThis section covers considerations for extensions that support the versioning extension and for defining new versioning types.Versioning Extension ConsiderationsAll extensions support Opaque Versioning by default and MAY support other forms for versioning types, such as the Semantic Versioning.
The following are considerations for the extensions an servers that support the versioning extension:
An extension document SHOULD define an "Extension Version Identifier" section that includes the versioning types supported by the extension with the associated extension version identifier.
A server MUST ignore Extension Version Identifiers that are unknown in the Extension Versioning Request.
A server SHOULD first process the Extension Versioning Request prior to processing the query parameters of other extensions to implement the client's extension versioning hint.
A server MAY define the policy of the extension versions that are supported and the timing of the extension versions, such as how many overlapping extension versions to support in parallel.
Versioning Type ConsiderationsThe following are considerations for the definition of new versioning types in a Versioning Type Specification.
The Opaque Versioning and Semantic Versioning with the associated RDAP JSON Values Registry registrations are concrete examples of a Versioning Type Specification.
The Versioning Type Specification MUST include the following:
Definition of a unique RDAP JSON Values Registry "versioning" value.
Definition of the format of the Extension Versioning identifier.
Definition of the members of the "versioning-help" member that apply.
Definition of the members of the "versioning" memeber that apply.
Extension Version IdentifierThis extension supports the following versioning types:
Opaque Versioning:
The Opaque Extension Versioning Identifier is "versioning".
Semantic Versioning:
The Semantic Extension Versioning Identifier is "versioning-0.2".
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:
IETF <iesg@ietf.org>
Intended usage:
This extension identifies RDAP extension versioning.
RDAP JSON Values RegistrySection 10.2 of defines the
RDAP JSON Values Registry with pre-defined Type field values and the use of the
"Expert Review" policy defined in .
This specification defines a new "versioning" RDAP JSON Values Registry Type field
value that can be used to register pre-defined versioning types values.
The registered "versioning" value is referenced using the "type" field of the "versioning" field
or "versioning-help" field object.
IANA is instructed to update the RDAP JSON Values
Registry to accept the additional "versioning" type field values.The following values should be registered by the IANA in the RDAP JSON Values Registry described in :
Value:
opaque
Type:
versioning
Description:
Opaque extension versioning type, where the rdapConformance value directly indicates the extension version.
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Value:
semantic
Type:
versioning
Description:
Semantic extension versioning type, where the rdapConformance value is appended with a semantic version number.
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
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".
Change from 01 to 02
Restructure the draft to support the features of providing versioning meta-data in the help response, providing extension versioning information in the query response,
and provide the ability for the client to specify the desired set of extension versions in the query with an extensible set of versioning types. The following changes apply:
Added the "Versioning RDAP Features" section to define the base set of features of the extension that applies to an extensible set of versioning types.
Updated the Extension Version Identifier to be more generic to support an extensible set of extension version identifiers by the set of versioning types.
Created the "Extension Versioning Request" section to support client extension versioning hints using either the "versioning" query parameter or the versioning extensions media type parameter in .
Updated the ""versioning-help" Member" section to include the versioning type for each extension and to reference the guidance in Section 7 of and extending it by the versioning extension.
Updated the ""versioning" Member" section to include the versioning type for returned RDAP response extensions.
Created the "Versioning Types" section to define the two pre-defined versioning types of Opaque Versioning and Semantic Versioning following a common template.
Created the "Versioning Extension Considerations" section to provide guidance on the use of the versioning extension by RDAP extensions and servers, and to provide guidance on the definition of new versioning types.
In the "IANA Considerations" section, add a new RDAP JSON Values Type of "versioning" to support defining multiple versioning types that can be used by RDAP extensions.
In the "IANA Considerations" section, Pre-register the RDAP JSON Values "versioning" types defined in the draft, including "opaque" and "semantic".
Change from 02 to REGEXT 00
Changed to regext working group draft by changing draft-gould-regext-rdap-versioning to draft-ietf-regext-rdap-versioning.
Change from REGEXT 00 to REGEXT 01
Replaced I-D.newton-regext-rdap-x-media-type with I-D.ietf-regext-rdap-x-media-type and I-D.newton-regext-rdap-extensions with I-D.ietf-regext-rdap-extensions.