Internet DRAFT - draft-newton-regext-rdap-simple-contact
draft-newton-regext-rdap-simple-contact
Registration Protocols Extensions (regext) A. Newton
Internet-Draft ICANN
Intended status: Standards Track T. Harrison
Expires: 3 March 2024 APNIC
31 August 2023
RDAP Simple Contact
draft-newton-regext-rdap-simple-contact-01
Abstract
This document describes an extension to the Registry Data Access
Protocol for entity contact data using basic JSON values, objects,
and arrays. The data model defined by this document is purposefully
limited to the data in-use by Internet Number Registries and Domain
Name Registries and does not attempt to model the full data-set that
can be expressed with other contact models such as jCard or
JSContact.
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 3 March 2024.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
Newton & Harrison Expires 3 March 2024 [Page 1]
Internet-Draft rdap-simple-contact August 2023
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.
Table of Contents
1. Background . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Simple Contact Extension And Identifier . . . . . . . . . . . 3
2.1. Kind . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Names . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3. Postal Addresses . . . . . . . . . . . . . . . . . . . . 4
2.4. Email Addresses . . . . . . . . . . . . . . . . . . . . . 5
2.5. Telephones . . . . . . . . . . . . . . . . . . . . . . . 6
2.6. Web Contacts . . . . . . . . . . . . . . . . . . . . . . 6
2.7. Geographic Locations . . . . . . . . . . . . . . . . . . 6
2.8. An Entity Example . . . . . . . . . . . . . . . . . . . . 7
3. EPP Int/Loc Data . . . . . . . . . . . . . . . . . . . . . . 9
4. Links to Other Contact Formats . . . . . . . . . . . . . . . 9
5. The No jCard Extension and Identifier . . . . . . . . . . . . 10
6. Normative References . . . . . . . . . . . . . . . . . . . . 10
7. Informative References . . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
1. Background
[RFC9083] defines the contact data of an entity using jCard
([RFC7095]), which is a JSON format for vCard ([RFC6350]).
Experience has shown that jCard is unsuitable for RDAP because its
"jagged" array style is unlike any other JSON in RDAP; it is more
difficutl to deserialize into objects that are easy to work with, it
is error prone and difficult to debug, and it can express far more
information than is necessary for RDAP.
This document defines the SimpleContact extension for RDAP. This
extension intends to model JSON in the same style and manner as other
RDAP structures and is purposefully limited to the data in-use by
Internet Number Registries and Domain Name Registries.
Newton & Harrison Expires 3 March 2024 [Page 2]
Internet-Draft rdap-simple-contact August 2023
The purposeful limitation of the contact data model defined in this
document is informed by [RFC5733], the ICANN gTLD RDAP Response
Profile (https://www.icann.org/en/system/files/files/rdap-response-
profile-15feb19-en.pdf), the NRO RDAP Profile
(https://bitbucket.org/nroecg/nro-rdap-profile/raw/v1/nro-rdap-
profile.txt), and [RFC7495].
2. Simple Contact Extension And Identifier
The RDAP extension identifier for this extension is "sc". This
extension defines one JSON member named "sc_data" to be found in RDAP
responses. "sc_data" is a JSON object, and it has child members
described in the following sections. Each child member of "sc_data"
is optional.
There are is one common, optional JSON member of these child members:
"lang". The JSON member "lang" is the same as that defined by RDAP
in Section 4.4.
Most of the child members are arrays allowing the expression of
multiple variants of the same information. The order in which items
appear in these arrays denotes preference order for the variants.
2.1. Kind
The "kind" JSON value is a string, that is either "individual",
"role" or "organization". An example:
"kind" : "role"
There is no equivalent to the "role" value in either jCard or
JSContact, though role entities are common in RDAP registries.
2.2. Names
Names can be expressed for each kind of the entity, as described in
the "kind" string. When describing an "individual", the name of the
individual's role and organization may also be expressed. When
describing a "role", the name of the role's organization may also be
expressed. It is NOT RECOMMENDED to express the name of a role or
individual when the kind is "organization".
Names are expressed using the "individualNames", "roleNames", and
"organizationNames" JSON members for individuals, roles, and
organizations respectively. The value of each is an array in which
each item is an object with the following members:
* "name" - unstructured textual name as a string
Newton & Harrison Expires 3 March 2024 [Page 3]
Internet-Draft rdap-simple-contact August 2023
* "lang" - optional, see above
The following is an example:
"individualNames" : [
{
"name" : "Dr. Bob Lee Aloysius Smurd, Ph.d.",
"lang" : "en-AU"
}
],
"roleNames" : [
{
"name" : "Abuse Prevention, Trust and Safety",
"lang" : "en-AU"
}
],
"organizationNames" : [
{
"name" : "ACME Pty",
"lang" : "en-AU"
}
]
RDAP allows the expression of nested entities as the entity object
class has its own entities array. Some servers express the
relationship of individuals to roles and/or organizations by nesting
entities inside other entities. SimpleContact does not remove this
capability nor prohibit it. However, nesting of entities is NOT
RECOMMENDED if the expression of a relationship between an individual
and a role or an organization can be accomplished using names alone
due to the complexity in representation of those relationships by a
client. If a server is to express an individual with a relationship
to a role and/or organization and each have differences other than
names (e.g. separate postal addresses), then nesting is RECOMMENDED.
2.3. Postal Addresses
Postal addresses can be expressed as a series of strings, each
representing a separate line of text as it would appear on an item
for delievery in a postal system. Additionally, postal addresses may
be augmented with some of the common fields found in postal systems
for the purposes of processing these addresses in non-postal systems.
Postal addresses are expressed with the "postalAddresses" JSON
member, which is an array of objects each with the following optional
members:
Newton & Harrison Expires 3 March 2024 [Page 4]
Internet-Draft rdap-simple-contact August 2023
* "address" - holds the unstructured postal address as an array of
strings in which each string represents a line of a postal
address.
* "cc" - a string containing the ISO-3166-2 code.
* "pc" - a string containing the postal code, sometimes referred to
as a zip code or post code.
* "lang" - see above
The following is an example of a postal address:
"postalAddresses" : [
{
"address" : [
"Suite 300",
"123 Random Tree Name Street",
"Kalamazoo, MI 90125 US"
]
"cc" : "US-MI",
"pc" : "90215",
"lang" : "en-US"
}
]
2.4. Email Addresses
Email addresses can be expressed in a JSON array of objects named
"emails". Each object contains the following members:
* "email" - a string containing the email address.
* "lang" - optional, see above
If the string in "email" begins with "mailto:", the string MUST be
conformant to the mailto URI specified in [RFC6068]. Otherwise, the
string MUST be conformant to the address specification of
Section 3.3. This JSON value is optional.
"emails" : [
{
"email": "山田太郎@example.net",
"lang" : "ja"
},
{
"email" : "yamada.taro@example.net",
"lang" : "ja-Latn"
}
]
Newton & Harrison Expires 3 March 2024 [Page 5]
Internet-Draft rdap-simple-contact August 2023
2.5. Telephones
Telephones to be used for voice communication can be expressed in a
JSON array of strings named "voicePhones". Telephones to be used for
facsimile machine communications can be expressed in a JSON array of
strings named "faxPhones".
If the string in the array begins with "tel:", the string MUST be
conformant to the tel URI specified in [RFC3966]. Otherwise the
string is considered unstructured text. If possible, the
unstructurued text SHOULD be conformant to the [ITU.E161.2001] format
and the [ITU.E164.1991] numbering plan.
The following are examples:
"voicePhones" : [
"tel:+1-201-555-0123",
"+447040202"
],
"faxPhones" : [
"tel:+1-201-555-9999;ext=123"
]
2.6. Web Contacts
Communications with the entity using a web browser, often by
submitting data via a web form, can be expressed using a JSON array
of strings called "webContacts". Each string in the array is an
HTTPS URI as specified by Section 4.2.2.
An example:
"webContacts" : [
"https://example.com/contact-me"
]
2.7. Geographic Locations
Geographic locations can be expressed using the "geo" JSON value,
which is an array of strings. Each string MUST be conformant to the
geo URI scheme as defined in [RFC5870].
"geo" : [
"geo:37.786971,-122.399677"
]
"geo" values SHOULD NOT be used with contact data when "kind" is
"individual".
Newton & Harrison Expires 3 March 2024 [Page 6]
Internet-Draft rdap-simple-contact August 2023
2.8. An Entity Example
The following is an example of an RDAP entity using SimpleContact:
{
"objectClassName" : "entity",
"handle":"XXXX",
"sc_data": {
"kind" : "individual",
"individualNames" : [
{
"name" : "山田太郎",
"lang" : "ja"
},
{
"name" : "Yomada Taro",
"lang" : "ja-Latn"
}
],
"roleNames" : [
{
"name" : "登録サービス ヘルプデスク",
"lang" : "ja"
},
{
"name" : "Registration Services Help Desk",
"lang" : "en"
}
],
"organizationNames" : [
{
"name" : "アクメ",
"lang" : "ja"
},
{
"name" : "ACME",
"lang" : "en"
}
],
"postalAddresses" : [
{
"address" : [
"〒150-2345 東京都渋谷区本町2丁目4-7サニーマンション203",
]
"cc" : "JP-13",
"pc" : "150-2345",
"lang" : "ja"
},
Newton & Harrison Expires 3 March 2024 [Page 7]
Internet-Draft rdap-simple-contact August 2023
{
"address" : [
"Sunny Mansion #203",
"4-7 Hommachi 2-choume",
"Shibuya-ku, TOKYO 150-2345"
]
"cc" : "JP-13",
"pc" : "150-2345",
"lang" : "ja-Latn"
}
],
"emails" : [
{
"email": "山田太郎@example.net",
"lang" : "ja"
},
{
"email" : "yamada.taro@example.net",
"lang" : "ja-Latn"
}
],
"voicePhones" : [
"+81(03) 1234-5678"
],
"faxPhones" : [
"tel:+810312345679"
],
"webContacts" : [
"https://example.net/contact-me"
]
},
"roles":[ "registrar" ],
"publicIds":[
{
"type":"IANA Registrar ID",
"identifier":"1"
}
],
"remarks":[
{
"description":[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links":[
{
Newton & Harrison Expires 3 March 2024 [Page 8]
Internet-Draft rdap-simple-contact August 2023
"value":"https://example.com/entity/XXXX",
"rel":"self",
"href":"https://example.com/entity/XXXX",
"type" : "application/rdap+json"
},
{
"value":"https://example.com/entity/XXXX",
"rel":"about",
"href":"https://example.com/entity/XXXX.vcard",
"type" : "text/vcard"
}
],
"events":[
{
"eventAction":"registration",
"eventDate":"1990-12-31T23:59:59Z"
}
],
"asEventActor":[
{
"eventAction":"last changed",
"eventDate":"1991-12-31T23:59:59Z"
}
]
}
3. EPP Int/Loc Data
[RFC5733] defines mechanisms to indicate data is "localized" or
"internationalized" using "int" and "loc" types. The "int"
designates data as being 7-bit ASCII. To express contact data with
the "int" designation in SimpleContact, it is RECOMMENDED that a
language tag with the "Latn" script subtag (see [RFC5646]) be used.
4. Links to Other Contact Formats
SimpleContact does not attempt to model all possible forms of contact
formats or data. Where an RDAP server can provide a more extensive
form such as vCard, jCard, or JSContact, these can be expressed in an
RDAP link using the "about" rel type and the media type appropriate
to that form. section Section 2.8 contains an example using vCard.
RDAP servers MUST place the same access restrictions upon these
resources as they do on the RDAP entity from which they are
referenced. It is NOT RECOMMENDED to link to contact data provided
by other servers or servers under separate authorities.
Newton & Harrison Expires 3 March 2024 [Page 9]
Internet-Draft rdap-simple-contact August 2023
5. The No jCard Extension and Identifier
This document also defines a second RDAP extension to signal the non-
use of jCard in RDAP responses. The identifier for this extension is
"noJCard". When used with the RDAP-X media type
[I-D.newton-regext-rdap-x-media-type] and the SimpleContact
identifier, a client can signal to a server that entities should
substitute SimpleContact data for jCard data. When used with queries
containing large amounts of entity data, such as RDAP searches, this
can reduce the payload significantly (instead of sending both jCard
and SimpleContact).
Use of the "noJCard" extension is independent of the SimpleContact
extension, and may be used for other purposes as is appropriate to
server policy.
6. Normative References
[I-D.newton-regext-rdap-x-media-type]
Newton, A. and J. Singh, "An RDAP With Extensions Media
Type", Work in Progress, Internet-Draft, draft-newton-
regext-rdap-x-media-type-01, 29 August 2023,
<https://datatracker.ietf.org/doc/html/draft-newton-
regext-rdap-x-media-type-01>.
[ITU.E161.2001]
International Telecommunications Union, "Arrangement of
digits, letters and symbols on telephones and other
devices that can be used for gaining access to a telephone
network", ITU-T Recommendation E.161, 2001.
[ITU.E164.1991]
International Telecommunications Union, "The International
Public Telecommunication Numbering Plan",
ITU-T Recommendation E.164, 1991.
[RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers",
RFC 3966, DOI 10.17487/RFC3966, December 2004,
<https://www.rfc-editor.org/info/rfc3966>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
Contact Mapping", STD 69, RFC 5733, DOI 10.17487/RFC5733,
August 2009, <https://www.rfc-editor.org/info/rfc5733>.
Newton & Harrison Expires 3 March 2024 [Page 10]
Internet-Draft rdap-simple-contact August 2023
[RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource
Identifier for Geographic Locations ('geo' URI)",
RFC 5870, DOI 10.17487/RFC5870, June 2010,
<https://www.rfc-editor.org/info/rfc5870>.
[RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto'
URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010,
<https://www.rfc-editor.org/info/rfc6068>.
[RFC6531] Yao, J. and W. Mao, "SMTP Extension for Internationalized
Email", RFC 6531, DOI 10.17487/RFC6531, February 2012,
<https://www.rfc-editor.org/info/rfc6531>.
[RFC7495] Montville, A. and D. Black, "Enumeration Reference Format
for the Incident Object Description Exchange Format
(IODEF)", RFC 7495, DOI 10.17487/RFC7495, March 2015,
<https://www.rfc-editor.org/info/rfc7495>.
[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>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.
7. Informative References
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
DOI 10.17487/RFC6350, August 2011,
<https://www.rfc-editor.org/info/rfc6350>.
[RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095,
DOI 10.17487/RFC7095, January 2014,
<https://www.rfc-editor.org/info/rfc7095>.
Authors' Addresses
Andy Newton
ICANN
Email: andy@hxr.us
Tom Harrison
APNIC
Email: tomh@apnic.net
Newton & Harrison Expires 3 March 2024 [Page 11]
