RDAP Extensions
draft-newton-regext-rdap-extensions-00

Registration Protocols Extensions (regext)                     A. Newton
Internet-Draft                                                     ICANN
Intended status: Informational                                  J. Singh
Expires: 25 December 2023                                           ARIN
                                                            23 June 2023

                            RDAP Extensions
                 draft-newton-regext-rdap-extensions-00

Abstract

   This document describes the usage of extensions in RDAP.

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 25 December 2023.

Copyright Notice

   Copyright (c) 2023 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Newton & Singh          Expires 25 December 2023                [Page 1]
Internet-Draft               rdap-extensions                   June 2023

Table of Contents

   1.  Background  . . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  The RDAP Extension Identifier . . . . . . . . . . . . . . . .   2
   3.  Usage in Queries  . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Usage in JSON . . . . . . . . . . . . . . . . . . . . . . . .   3
   5.  Camel Casing  . . . . . . . . . . . . . . . . . . . . . . . .   5
   6.  Two Classes of Extensions . . . . . . . . . . . . . . . . . .   5
   7.  Extension Versioning  . . . . . . . . . . . . . . . . . . . .   5
   8.  Extension Definitions . . . . . . . . . . . . . . . . . . . .   5
   9.  Normative References  . . . . . . . . . . . . . . . . . . . .   6
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   6

1.  Background

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

   RDAP contains a means to define extensions for queries not found in
   [RFC9082] and responses not found in [RFC9083].

2.  The RDAP Extension Identifier

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

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

   RDAP extension identifiers have no explicit structure and are opaque
   in that no inner-meaning can be "seen" in them.

   When in use in RDAP, extension identifiers are prepended to both URL
   path segments and JSON attribute names.  In both cases, the extension
   identifier acts as a namespace preventing collisions between
   extension elements.

Newton & Singh          Expires 25 December 2023                [Page 2]
Internet-Draft               rdap-extensions                   June 2023

3.  Usage in Queries

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

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

   Although [RFC9082] describes the use of URI query strings, it does
   not define their use with extensions.  [RFC7480] instructs servers to
   ignore unknown query parameters.  Therefore, the use of query
   parameters, prefixed or not with an extension identifier, is
   undefined.  Despite this, there are several extensions that do
   specify query parameters.

4.  Usage in JSON

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

   The example given in [RFC9083] is as follows:

Newton & Singh          Expires 25 December 2023                [Page 3]
Internet-Draft               rdap-extensions                   June 2023

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

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

   The following example shows this use with a JSON object.

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

   Here the JSON name "lunarNic_author" will separate the JSON from
   other extensions that may have an "author" structure.  But the JSON
   contained within "lunarNIC_author" need not be prepended as the
   extension collision is avoided by "lunarNIC_author".

Newton & Singh          Expires 25 December 2023                [Page 4]
Internet-Draft               rdap-extensions                   June 2023

5.  Camel Casing

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

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

6.  Two Classes of Extensions

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

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

7.  Extension Versioning

   Because RDAP extensions are opaque, they posses no explicit version
   despite the fact that some extension identifiers include trailing
   numbers.  That is, RDAP extensions are opaquely versioned.

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

8.  Extension Definitions

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

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

Newton & Singh          Expires 25 December 2023                [Page 5]
Internet-Draft               rdap-extensions                   June 2023

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

9.  Normative References

   [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,
              <https://www.rfc-editor.org/info/rfc7480>.

   [RFC9082]  Hollenbeck, S. and A. Newton, "Registration Data Access
              Protocol (RDAP) Query Format", STD 95, RFC 9082,
              DOI 10.17487/RFC9082, June 2021,
              <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, June 2021,
              <https://www.rfc-editor.org/info/rfc9083>.

Authors' Addresses

   Andy Newton
   ICANN
   Email: andy@hxr.us

   Jasdip Singh
   ARIN
   Email: jasdips@arin.net

Newton & Singh          Expires 25 December 2023                [Page 6]