Registration Protocols Extensions (regext) A. Newton Internet-Draft ICANN Intended status: Standards Track T. Harrison Expires: 6 January 2024 APNIC 5 July 2023 RDAP Simple Contact draft-newton-regext-rdap-simple-contact-00 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 6 January 2024. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. Newton & Harrison Expires 6 January 2024 [Page 1] Internet-Draft rdap-simple-contact July 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.2.1. Individual Names . . . . . . . . . . . . . . . . . . 4 2.2.2. Role Names . . . . . . . . . . . . . . . . . . . . . 5 2.2.3. Organization Names . . . . . . . . . . . . . . . . . 5 2.3. Postal Addresses . . . . . . . . . . . . . . . . . . . . 6 2.4. Email Addresses . . . . . . . . . . . . . . . . . . . . . 7 2.5. Telephones . . . . . . . . . . . . . . . . . . . . . . . 8 2.6. Web Contacts . . . . . . . . . . . . . . . . . . . . . . 9 2.7. Geographic Locations . . . . . . . . . . . . . . . . . . 9 3. EPP Int/Loc Data . . . . . . . . . . . . . . . . . . . . . . 9 4. No jCard Extension and Identifier . . . . . . . . . . . . . . 9 5. Normative References . . . . . . . . . . . . . . . . . . . . 10 6. 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 6 January 2024 [Page 2] Internet-Draft rdap-simple-contact July 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 two common, optional JSON members of these child members: "lang" and "masked". The JSON member "lang" is the same as that defined by RDAP in Section 4.4. The JSON member "masked" is a boolean. When true, this indicates that the data of the JSON object provided is to facilitate communication with the entity in a manner that hides or obfuscates the identity of the entity. This serves the same purpose as the vCard properties defined in [RFC8605]. 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" 2.2. Names Names may be expressed as unstructured text and as structured data. When names are given as structured data, it is RECOMMENDED to also give unstructured names. This may require servers which store names in structured data to synthesize the unstructured names. Servers which store only unstructured names SHOULD NOT attempt to synthesize and provide structured names from those values, because of the difficulty of doing this correctly for all types of names. Newton & Harrison Expires 6 January 2024 [Page 3] Internet-Draft rdap-simple-contact July 2023 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". Each type of name is expressed as a JSON array in which each item is an object with the following optional members: * "name" - the unstructured name as a string * "lang" - see above * "masked" - see above * "parts" - a JSON object that varies for each type of name. | The co-authors of this specification are skeptical of the need | for structured names in RDAP. None of the references in | Section 1 indicate that names are collected or published | structurally. Additionally, attempts to structure names for | all contexts and languages is unlikely to yield a complete | solution (see https://mailarchive.ietf.org/arch/msg/ | calsify/3MR_gLO-1NuyQvE8DIl88KNglSs/ | (https://mailarchive.ietf.org/arch/msg/calsify/3MR_gLO- | 1NuyQvE8DIl88KNglSs/)). 2.2.1. Individual Names The name of an individual may be expressed with the JSON member named "individualNames". The "parts" object for "individualNames" has the following optional members: * "prefixes" - an array of strings holding honorifics, titles, and other signifiers that are typically prefixed to a name. * "firstNames" - an array of strings holding the set of names that preceed other names. These are often called "given" names. * "middleNames" - an array of strings holding the set of names that succeed first names and preceed last names. These are often referred to as "additional" names. * "lastNames" - an array of strings holding the set of names that succeed other names. These are often called "sur" names. * "suffixes" - an array of strings holding honorifics, titles, and other signifiers that are typically suffixed to a name. The following is an example: Newton & Harrison Expires 6 January 2024 [Page 4] Internet-Draft rdap-simple-contact July 2023 "individualNames" : [ { "name" : "Dr. Bob Lee Aloysius Smurd, Ph.d.", "lang" : "en-AU", "parts" : { "prefixes": [ "Dr."], "firstNames": [ "Bob" ], "middleNames" : [ "Lee", "Aloysius" ], "lastNames" : [ "Smurd" ], "suffixes" : [ "Ph.d." ] } } ] 2.2.2. Role Names The name of a role may be expressed with the JSON member named "roleNames". The "parts" object for "roleNames" has one member named "roles" which is an array of strings. The following is an example: "roleNames" : [ { "name" : "Abuse Prevention, Trust and Safety", "lang" : "en-AU", "parts" : { "roles" : [ "Abuse Prevention", "Trust and Safety"], } } ] 2.2.3. Organization Names The name of an organization may be expressed with the JSON member named "organizationNames". The "parts" object for "organizationNames" has the following optional members: * "name" - a string holding the name of the organization without other qualifiers. * "subDivisions" - an array of strings, each the name of a subdivision of the organization. * "suffixes" - an array of strings, each signifying a legal status of the organization. * "legalId" - an array of strings, each containing a legal identifier of the organization. The following is an example: Newton & Harrison Expires 6 January 2024 [Page 5] Internet-Draft rdap-simple-contact July 2023 "organizationNames" : [ { "name" : "ACME Pty, Floors and Windows, Direct Sales", "lang" : "en-AU", "parts" : { "name" : "ACME", "subDivisions": [ "Floors and Windows", "Direct Sales" ], "suffixes" : [ "Pty" ], } } ] 2.3. Postal Addresses Like names, postal addresses can be expressed as either structured or unstructured. When postal addresses are given as structured data, it is RECOMMENDED to also give unstructured addresses. This may require servers which store addresses in structured data to synthesize the unstructured addresses. Servers which store only unstructured addresses SHOULD NOT attempt to synthesize and provide structured addresses from those values, because of the difficulty of doing this correctly for all types of addresses. Postal addresses are expressed with the "postalAddresses" JSON member, which is an array of objects each with the following optional members: * "completeAddress" - holds the unstructured postal address as an array of strings in which each string represents a line of a postal address. * "deliveryLines" - an array of strings in which each string represents a line of a postal address specific to delivery within the locality of the address. This information typically contains street names and numbers, apartment or suite names, and other information necessary for the delivery of postal mail within a locality. * "locality" - a string representing the village, city, municipality, or similar part of a postal address. * "regionName" - a string of the region name of a country, such as a state, province, or department. * "regionCode" - a string representing the ISO-3166-3 two letter code. * "countryName" - a string containing the country name. * "countryCode" - a string containing the ISO-3166-2 two letter code for the country. * "postalCode" - a string containing the postal code, sometimes referred to as a zip code or post code. * "lang" - see above Newton & Harrison Expires 6 January 2024 [Page 6] Internet-Draft rdap-simple-contact July 2023 * "masked" - see above The following is an example of a postal address: "postalAddresses" : [ { "completeAddress" : [ "Suite 300", "123 Random Tree Name Street", "Kalamazoo, MI 90125 US" ] "deliveryLines" : [ "Suite 300", "123 Random Tree Name Street", ], "locality" : "Kalamazoo", "regionName" : "Michigan", "regionCode" : "MI", "countryName" : "United States of America", "countryCode" : "US", "postalCode" : "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 * "masked" - 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.4. This JSON value is optional. Newton & Harrison Expires 6 January 2024 [Page 7] Internet-Draft rdap-simple-contact July 2023 "emails" : [ { "email": "山田太郎 ", "lang" : ja }, { "email" : "Yamada Taro " "lang" : "ja-Latn" } ] 2.5. Telephones Telephones to be used for voice communication can be expressed in a JSON array of objects named "voicePhones". Telephones to be used for facsimile machine communications can be expressed in a JSON array of objects named "faxPhones". Each object has the following members: * "phone" - a string holding the phone number * "masked" - optional, see above If the string in "phone" 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" : [ { "phone": "tel:+1-201-555-0123", "masked" : false }, { "phone" : "+447040202", } ], "faxPhones" : [ { "phone" : "tel:+1-201-555-9999;ext=123", "masked" : false } ] Newton & Harrison Expires 6 January 2024 [Page 8] Internet-Draft rdap-simple-contact July 2023 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 objects called "webContacts". Each object has the following members: * "uri" - a string with an HTTPS URI as specified by Section 4.2.2. * "masked" - optional, see above. An example: "webContacts" : [ { "uri" : "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". 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. 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 Newton & Harrison Expires 6 January 2024 [Page 9] Internet-Draft rdap-simple-contact July 2023 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. 5. 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-00, 21 May 2023, . [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, . [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008, . [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009, . [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Contact Mapping", STD 69, RFC 5733, DOI 10.17487/RFC5733, August 2009, . [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource Identifier for Geographic Locations ('geo' URI)", RFC 5870, DOI 10.17487/RFC5870, June 2010, . Newton & Harrison Expires 6 January 2024 [Page 10] Internet-Draft rdap-simple-contact July 2023 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, . [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, . [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: ICANN Extensions for the Registration Data Access Protocol (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, . [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, . [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . 6. Informative References [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, DOI 10.17487/RFC6350, August 2011, . [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, DOI 10.17487/RFC7095, January 2014, . Authors' Addresses Andy Newton ICANN Email: andy@hxr.us Tom Harrison APNIC Email: tomh@apnic.net Newton & Harrison Expires 6 January 2024 [Page 11]