Using JSContact in Registration Data Access Protocol (RDAP) JSON Responses

3.1. JSContact Profile for RDAP

Since JSContact is a generalized representation of contact data, many of its capabilities are not optimized for use in RDAP responses. This document defines a usage profile for JSContact that simplifies the implementation for both clients and servers. The JSContact profile for RDAP is compliant with the rules described in [I-D.ietf-calext-jscontact-profiles]. The profile properties are formally listed in Section 3.1.14. The information required to register the profile is described in Section 6.4.¶

All types mentioned in this section refer to the JSContact specification [RFC9553] (e.g., Card is the JSContact Card type).¶

...
"jscontact_card": {
  "@type": "Card",
  "version": "2.0",
  "language": "en",
  "name": {
    "full": "Vasya Pupkin"
  },
  "organizations": {
    "org": {
      "name": "My Company"
    }
  },
  "addresses": {
    "addr": {
      "components": [
        { "kind": "name", "value": "1 Street" },
        { "kind": "locality", "value": "Kyiv" }
      ],
      "countryCode": "UA"
    }
  },
  "localizations": {
    "uk": {
      "addresses": {
        "addr": {
          "components": [
           { "kind": "name", "value": "1, Улица" },
           { "kind": "locality", "value": "Київ" }
          ],
          "countryCode": "UA"
        }
      },
      "name": {
        "full": "Вася Пупкін"
      },
      "organizations": {
        "org": {
          "name": "Моя Компанія"
        }
      }
    }
  }
}
...

   {
      "rdapConformance": [
         "rdap_level_0",
         "jscontact",
         "versioning"
      ],
      "objectClassName": "entity",
      "handle":"XXXX",
      "jscontact_card":{
        "@type": "Card",
        "version": "2.0",
        "name": {
          "full": "Joe User",
          "components": [
            { "kind": "given", "value": "Joe" },
            { "kind": "surname", "value": "User" }
          ]
        },
        "organizations": {
          "org": {
            "name": "Org Example"
          }
        },
         "addresses": {
           "addr": {
             "components": [
               { "kind": "name", "value": "Main Street 1" },
               { "kind": "locality",
                 "value": "Ludwigshafen am Rhein" },
               { "kind": "region", "value": "Rhineland-Palatinate" },
               { "kind": "postcode", "value": "67067" },
               { "kind": "country", "value": "Germany" }
             ],
             "countryCode": "DE"
           },
           "addr-1": {
             "full": "Somewhere Street 1 Mutterstadt 67112 Germany"
           }
         },
        "phones": {
          "voice": {
            "number": "tel:+49-1522-3433333"
          },
          "fax": {
            "features": { "fax": true },
            "number": "tel:+49-30-901820"
          }
        },
        "emails": {
          "email": {
            "address": "joe.user@example.com"
          }
        },
        "links": {
          "url": {
            "uri": "https://www.example.com"
          },
          "contact-uri": {
            "kind": "contact",
            "uri": "mailto:contact@example.com"
          }
        }
      },
      "roles":[ "registrar" ],
      "publicIds":[
        {
          "type":"IANA Registrar ID",
          "identifier":"1"
        }
      ],
      "links":[
        {
          "value":"https://example.com/entity/XXXX",
          "rel":"self",
          "href":"https://example.com/entity/XXXX",
          "type" : "application/rdap+json"
        }
      ],
      "events":[
        {
          "eventAction":"registration",
          "eventDate":"1990-12-31T23:59:59Z"
        }
      ],
      "asEventActor":[
        {
          "eventAction":"last changed",
          "eventDate":"1991-12-31T23:59:59Z"
        }
      ],
      "versioning_data": [
            {
          "extension": "rdap_level_0",
          "type": "opaque",
          "version": "rdap_level_0"
        },
        {
          "extension": "versioning",
          "type": "point",
          "version": "versioning-1.0"
        },
        {
          "extension": "jscontact",
          "type": "point",
          "version": "jscontact-1.0"
        }
     ]
   }

3.2. Request for JSContact

The client MAY request the server to include the "jscontact_card" member in the RDAP response by using only one of the following HTTP elements:¶

• the RDAP media type "versioning_list" parameter as defined in [I-D.ietf-regext-rdap-versioning];¶

• the RDAP media type "exts_list" parameter as defined in [I-D.ietf-regext-rdap-x-media-type].¶

A client MUST NOT request JSContact using both mechanisms in the same request. If a server receives a request that uses both mechanisms, it MUST process the "versioning_list" parameter and MUST ignore the "exts_list" parameter for the purpose of selecting the contact representation.¶

Their usage in the transition from jCard to JSContact is further explained in Section 4.2.2.2.¶

3.3. Reverse Search Properties

The use of JSContact updates the mappings of two reverse search properties, namely "fn" and "email", defined in [RFC9536]. Such new mappings are registered in the Reverse Search Mapping registry as described in Section 6.3.¶

4.1. RDAP Features Supporting the Transition Process

RDAP allows servers to communicate service information to clients through notices. According to Section 4.3 of [RFC9083], an RDAP response may contain one or more notice objects. Each notice may include a set of link objects, which can be used to provide clients with references. These link objects may have a "rel" member which defines the relationship between resources, as described in Section 4 of [RFC8288]. The transition process outlined in this document uses the "alternate" link relation type.¶

The information about the specifications used in the construction of the response is also described by the strings that appear in the "rdapConformance" array of the RDAP response.¶

4.2. Transition Procedure

The transition procedure consists of three contiguous stages. During the procedure, the presence of the string "jscontact" in the "rdapConformance" array indicates that JSContact is returned instead of jCard. The date and time format used to notify clients about the stages of this procedure is defined in [RFC3339].¶

"notices": [
  {
    "type": "jCard sunset end",
    "description": ["2030-12-31T23:59:59Z"],
    "links": [
      {
        "value": "https://example.net/entity/XXXX",
        "rel": "alternate",
        "type":
          "application/rdap+json;versioning_list=\"jscontact-0.4\"",
        "href": "https://example.net/entity/XXXX"
      },
      {
        "value": "https://example.net/entity/XXXX",
        "rel": "alternate",
        "type":
          "application/rdap+json;exts_list=\"rdap_level_0 jscontact\"",
        "href": "https://example.net/entity/XXXX"
      }
    ]
  }
]

"notices": [
  {
    "type": "jCard deprecation",
    "description": ["jCard has been deprecated"]
  }
]

5.1. IIT-CNR/Registro.it RDAP Server

• Responsible Organization: Institute of Informatics and Telematics of National Research Council (IIT-CNR)/Registro.it¶

• Location: https://rdap.pubtest.nic.it/¶

• Description: This implementation includes support for RDAP queries using data from the public test environment of .it ccTLD.¶

• Level of Maturity: This is an "alpha" test implementation.¶

• Coverage: This implementation includes all of the features described in this specification.¶

• Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it¶

5.2. IIT-CNR/Registro.it RDAP Client

• Responsible Organization: Institute of Informatics and Telematics of National Research Council (IIT-CNR)/Registro.it¶

• Location: https://web-rdap.pubtest.nic.it/¶

• Description: This is a JavaScript web-based RDAP client. RDAP responses are retrieved from RDAP servers by the browser, parsed into an HTML representation, and displayed in a format improving the user experience. RDAP responses containing JSContact objects are handled identically to those containing jCard objects. Raw versions of RDAP responses including either jCard or JSContact objects are provided.¶

• Level of Maturity: This is an "alpha" test implementation.¶

• Coverage: This implementation includes all of the features described in this specification.¶

• Contact Information: Francesco Donini, francesco.donini@iit.cnr.it¶

5.3. client.rdap.org

• Location: https://client.rdap.org/¶

• Description: This is a web-based "single page" RDAP client. RDAP responses are retrieved from RDAP servers by the browser, and parsed into an HTML representation. RDAP responses containing JSContact objects are handled identically to those containing jCard objects.¶

• Level of Maturity: This is an "alpha" test implementation.¶

• Coverage: This implementation implements client support for parsing JSContact objects in RDAP responses.¶

• Contact Information: Gavin Brown, feedback@rdap.org¶

5.4. CentralNic Registry

• Responsible Organization: CentralNic Group PLC¶

• Location: https://rdap.centralnic.com/{tld}¶

• Description: This server is the product RDAP service for all top-level domains on the CentralNic registry platform.¶

• Level of Maturity: Production quality.¶

• Coverage: This implementation includes all of the features described in this specification.¶

• Contact Information: support@centralnic.com¶

5.5. ICANN RDAP

• Responsible Organization: ICANN¶

• Location: https://github.com/icann/icann-rdap¶

• Description: ICANN RDAP contains an RDAP client, server, and common libraries.¶

• Level of Maturity: Mature.¶

• Coverage: This implementation includes all the features described in this specification, except support for Point Versioning and the provision of reverse search mapping.¶

• Contact Information: globalsupport@icann.org¶

6.1. RDAP Extensions Registry

IANA is requested to register the following values in the RDAP Extensions Registry [IANA.rdap-extensions]:¶

• Extension identifier: jscontact¶

• Registry operator: Any¶

• Published specification: This document.¶

• Contact: IETF <iesg@ietf.org>¶

• Intended usage: This extension identifier is used as prefix for the "jscontact_card" member returned in the JSON response [RFC9553].¶

• Extension identifier: noJcard¶

• Registry operator: Any¶

• Published specification: This document.¶

• Contact: IETF <iesg@ietf.org>¶

• Intended usage: This extension identifier is used by the server to signal clients that jCard is no longer returned.¶

6.2. RDAP JSON Values Registry

IANA is requested to add the following entries to the RDAP JSON Values Registry [IANA.rdap-json-values]. The registrations introduce the new Type values "JSContact version value" and "JSContact Id value".¶

Value:

jCard sunset end¶

Type:

notice and remark type¶

Description:

This notice signals clients that JSContact can be returned upon request.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

jCard deprecation¶

Type:

notice and remark type¶

Description:

This notice signals clients that jCard is no longer returned.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

2.0¶

Type:

JSContact version value¶

Description:

The JSContact version [RFC9982] to use in implementing this specification.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

org¶

Type:

JSContact Id value¶

Description:

The key in the JSContact "organizations" map identifying the contact organization.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

addr¶

Type:

JSContact Id value¶

Description:

The key in the JSContact "addresses" map identifying the unique or preferred contact postal address.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

email¶

Type:

JSContact Id value¶

Description:

The key in the JSContact "emails" map identifying the unique or preferred contact email address.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

voice¶

Type:

JSContact Id value¶

Description:

The key in the JSContact "phones" map identifying the unique or preferred contact voice number.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

fax¶

Type:

JSContact Id value¶

Description:

The key in the JSContact "phones" map identifying the unique or preferred contact fax number.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

url¶

Type:

JSContact Id value¶

Description:

The key in the JSContact "links" map identifying the unique or preferred URL.¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Value:

contact-uri¶

Type:

JSContact Id value¶

Description:

The key in the JSContact "links" map identifying the contact URI as defined in [RFC8605].¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

6.3. RDAP Reverse Search Mapping Registry

IANA is requested to register the following entries in the RDAP Reverse Search Mapping Registry [IANA.rdap-reverse-search-mapping]:¶

Searchable Resource Type:

domains, nameservers, entities, ips, autnums¶

Related Resource Type:

entity¶

Property:

fn¶

Property Path:

$.entities[*].jscontact_card.name.full¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Searchable Resource Type:

domains, nameservers, entities, ips, autnums¶

Related Resource Type:

entity¶

Property:

fn¶

Property Path:

$.entities[*].jscontact_card.localizations.*.name.full¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Searchable Resource Type:

domains, nameservers, entities¶

Related Resource Type:

entity¶

Property:

email¶

Property Path:

$.entities[*].jscontact_card.emails.*.address¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

Searchable Resource Type:

domains, nameservers, entities¶

Related Resource Type:

entity¶

Property:

email¶

Property Path:

$.entities[*].jscontact_card.localizations.*.emails.*.address¶

Registrant Name:

IETF¶

Registrant Contact Information:

iesg@ietf.org¶

Reference:

This document¶

6.4. JSContact Profile Registry

IANA is requested to register the following entry in the "JSContact Profile" registry [I-D.ietf-calext-jscontact-profiles]:¶

Name:

rdap¶

Version:

1¶

Reference:

Section 3.1.14 of this document¶

7.1. Representation Selection

As described in Section 3.2, clients can request the "jscontact_card" member using either the RDAP media type "versioning_list" or "exts_list" parameters.¶

Servers are expected to return a representation that is consistent with both the client request and the applicable transition stage defined in Section 4.2.2.¶

In particular, jCard is returned in Stage 1, jCard is the default in Stage 2 with JSContact available upon request, and JSContact is the only representation returned in Stage 3.¶

If a request for JSContact cannot be satisfied (e.g., due to unsupported or unknown extension parameters), the request is processed according to general RDAP behavior, and the default representation is returned.¶

7.2. rdapConformance Signaling

The "rdapConformance" array provides an indication of the representation used, as described in Section 3.1.1 and Section 4.2.¶

Servers are expected to ensure that the presence or absence of the "jscontact" identifier accurately reflects the response content and is consistent across all endpoints, including help responses as required in Section 4.2.2.2 and Section 4.2.2.3.¶

7.3. Data Consistency

JSContact and jCard represent the same information in different ways. As described in Appendix A, mapping between the two formats is not always structurally equivalent.¶

Operators should ensure that both representations are derived from a consistent data source and that the semantic meaning of the data is preserved, even when structural differences exist.¶

Particular attention may be needed for localized data (Section 3.1.13) and for the use of map keys (Section 3.1.12), to avoid inconsistencies.¶

7.4. Transition Monitoring

As stated in Section 4.2.2.4, the duration of the transition is not fixed.¶

Operators are encouraged to monitor service usage (e.g., server logs) to assess client adoption of JSContact and to determine whether adjustments to the transition timeline are appropriate.¶

7.5. Caching

During Stage 2, different representations of the same RDAP resource can be returned depending on the RDAP media type parameters included in the Accept header field. Servers MUST therefore include "Accept" in the Vary response header field as defined in [RFC9110] when representation selection depends on that field.¶

Servers SHOULD ensure that the freshness lifetime of a cached response does not extend beyond the announced jCard sunset end date. If the caching infrastructure cannot reliably distinguish responses based on the Accept header field, servers SHOULD prevent their storage by using an appropriate Cache-Control directive, such as "no-store".¶

7.6. Error Handling

Error handling follows the general RDAP principles defined in [RFC9083] and the extension versioning behavior described in Section 3.2 of [I-D.ietf-regext-rdap-versioning] and Section 3 of [I-D.ietf-regext-rdap-x-media-type].¶

In particular, requests for unsupported or unknown extensions or extension versions do not result in an error response and are instead ignored.¶

If a request for JSContact cannot be satisfied, the server behavior is determined by the applicable transition stage defined in Section 4.2.2. In Stage 2, the server returns the default representation (jCard), while in Stage 3 JSContact is always returned.¶

More generally, when extension negotiation does not succeed, servers may return the default representation in accordance with RDAP specifications.¶

7.7. Interoperability

Interoperability issues may arise during the transition due to differences in client support for request mechanisms (Section 3.2) or interpretation of rdapConformance signaling and notices (Section 4.1).¶

Testing with multiple client implementations can help identify and mitigate such issues.¶

7.8. Operational Resilience

The transition procedure described in Section 4.2 allows servers and clients to evolve independently.¶

Operators may adjust deployment strategies, including the duration of transition stages, based on operational experience and client behavior.¶