--- 1/draft-ietf-regext-rfc7483bis-00.txt 2020-06-30 11:13:10.448762950 -0700 +++ 2/draft-ietf-regext-rfc7483bis-01.txt 2020-06-30 11:13:10.576766224 -0700 @@ -1,19 +1,19 @@ REGEXT Working Group S. Hollenbeck Internet-Draft Verisign Labs Intended status: Standards Track A. Newton -Expires: 10 December 2020 AWS - 8 June 2020 +Expires: 1 January 2021 AWS + 30 June 2020 JSON Responses for the Registration Data Access Protocol (RDAP) - draft-ietf-regext-rfc7483bis-00 + draft-ietf-regext-rfc7483bis-01 Abstract This document describes JSON data structures representing registration information maintained by Regional Internet Registries (RIRs) and Domain Name Registries (DNRs). These data structures are used to form Registration Data Access Protocol (RDAP) query responses. Status of This Memo @@ -24,21 +24,21 @@ 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 10 December 2020. + This Internet-Draft will expire on 1 January 2021. Copyright Notice Copyright (c) 2020 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 @@ -64,21 +64,21 @@ 4.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.7. Port 43 WHOIS Server . . . . . . . . . . . . . . . . . . 14 4.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 14 4.9. Object Class Name . . . . . . . . . . . . . . . . . . . . 14 4.10. An Example . . . . . . . . . . . . . . . . . . . . . . . 14 5. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 16 5.1. The Entity Object Class . . . . . . . . . . . . . . . . . 17 5.2. The Nameserver Object Class . . . . . . . . . . . . . . . 23 5.3. The Domain Object Class . . . . . . . . . . . . . . . . . 26 5.4. The IP Network Object Class . . . . . . . . . . . . . . . 38 - 5.5. Autonomous System Number Object Class . . . . . . . . . . 43 + 5.5. The Autonomous System Number Object Class . . . . . . . . 43 6. Error Response Body . . . . . . . . . . . . . . . . . . . . . 46 7. Responding to Help Queries . . . . . . . . . . . . . . . . . 48 8. Responding To Searches . . . . . . . . . . . . . . . . . . . 48 9. Indicating Truncated Responses . . . . . . . . . . . . . . . 49 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 10.1. RDAP JSON Media Type Registration . . . . . . . . . . . 52 10.2. JSON Values Registry . . . . . . . . . . . . . . . . . . 53 10.2.1. Notice and Remark Types . . . . . . . . . . . . . . 54 10.2.2. Status . . . . . . . . . . . . . . . . . . . . . . . 56 10.2.3. Event Actions . . . . . . . . . . . . . . . . . . . 60 @@ -126,39 +126,40 @@ document are to be interpreted as described in [RFC2119] when specified in their uppercase forms. The following list describes terminology and definitions used throughout this document: DNR: Domain Name Registry or Domain Name Registrar LDH: letters, digits, hyphen - member: data found within an object as defined by JSON [RFC8259]. + member: data found within an object as defined by JSON [RFC8259] - object: a data structure as defined by JSON [RFC8259]. + object: a data structure as defined by JSON [RFC8259] object class: the definition of members that may be found in JSON - objects described in this document. + objects described in this document object instance: an instantiation or specific instance of an object - class. + class RDAP: Registration Data Access Protocol RIR: Regional Internet Registry 1.2. Data Model The data model for JSON responses is specified in five sections: - 1. simple data types conveyed in JSON strings + 1. simple data types conveyed in JSON primitive types (strings, + numbers, booleans, and null) 2. data structures specified as JSON arrays or objects that are used repeatedly when building up larger objects 3. object classes representing structured data corresponding to a lookup of a single object 4. arrays of objects representing structured data corresponding to a search for multiple objects @@ -235,59 +236,59 @@ "She sells sea shells down by the sea shore.", "Originally written by Terry Sullivan." ] } ] } Figure 1 If The Registry of the Moon desires to express information not found - in this specification, it might select "lunarNic" as its identifying + in this specification, it might select "lunarNIC" as its identifying prefix and insert, as an example, the member named - "lunarNic_beforeOneSmallStep" to signify registrations occurring + "lunarNIC_beforeOneSmallStep" to signify registrations occurring before the first moon landing and the member named - "lunarNic_harshMistressNotes" that contains other descriptive text. + "lunarNIC_harshMistressNotes" that contains other descriptive text. Consider the following JSON response with JSON names, some of which should be ignored by clients without knowledge of their meaning. { "handle" : "ABC123", - "lunarNic_beforeOneSmallStep" : "TRUE THAT!", + "lunarNIC_beforeOneSmallStep" : "TRUE THAT!", "remarks" : [ { "description" : [ "She sells sea shells down by the sea shore.", "Originally written by Terry Sullivan." ] } ], - "lunarNic_harshMistressNotes" : + "lunarNIC_harshMistressNotes" : [ "In space,", "nobody can hear you scream." ] } Figure 2 Insertion of unrecognized members ignored by clients may also be used for future revisions to this specification. Clients processing JSON responses need to be prepared for members representing registration data specified in this document to be - absent from a response. In other words, servers are free to not - include JSON members containing registration data based on their own - policies. + absent from a response. In other words, servers are free to omit + unrequired/optional JSON members containing registration data based + on their own policies. Finally, all JSON names specified in this document are case sensitive. Both servers and clients MUST transmit and process them using the specified character case. 3. Common Data Types JSON [RFC8259] defines the data types of a number, character string, boolean, array, object, and null. This section describes the semantics and/or syntax reference for common, JSON character strings @@ -350,29 +345,30 @@ 4. Common Data Structures This section defines common data structures used in responses and object classes. 4.1. RDAP Conformance The data structure named "rdapConformance" is an array of strings, each providing a hint as to the specifications used in the - construction of the response. This data structure appears only in - the topmost JSON object of a response. + construction of the response. This data structure MUST appear in the + topmost JSON object of a response. An example rdapConformance data structure: "rdapConformance" : [ "rdap_level_0" ] + Figure 3 The string literal "rdap_level_0" signifies conformance with this specification. When custom JSON values are inserted into responses, conformance to those custom specifications MUST be indicated by including a unique string literal value registered in the IANA RDAP Extensions registry specified in [RFC7480]. For example, if the fictional Registry of the Moon wants to signify that their JSON responses are conformant with their registered extensions, the string used might be "lunarNIC_level_0". These registered values aid the @@ -529,22 +525,24 @@ 4.4. Language Identifier This data structure consists solely of a name/value pair, where the name is "lang" and the value is a string containing a language identifier as described in [RFC5646]. "lang" : "mn-Cyrl-MN" Figure 10 - The "lang" attribute may appear anywhere in an object class or data - structure except for in jCard objects. + The "lang" attribute as defined in this section MAY appear anywhere + in an object class or data structure, except for in jCard objects. + jCard supports similar functionality by way of the LANGUAGE property + parameter (see Section 5.1 of RFC 6350 [RFC6350]). 4.5. Events This data structure represents events that have occurred on an instance of an object class (see Section 5 regarding object classes). This is an example of an "events" array. "events" : [ @@ -565,21 +563,21 @@ The "events" array consists of objects, each with the following members: * "eventAction" -- a REQUIRED string denoting the reason for the event * "eventActor" -- an OPTIONAL identifier denoting the actor responsible for the event * "eventDate" -- a REQUIRED string containing the time and date the - event occurred. + event occurred * "links" -- OPTIONAL; see Section 4.2 Events can be future dated. One use case for future dating of events is to denote when an object expires from a registry. The "links" array in this data structure is provided for references to the event actor. In order to reference an RDAP entity, a "rel" of "related" and a "type" of "application/rdap+json" is used in the link reference. @@ -862,21 +860,21 @@ "eventDate":"1991-12-31T23:59:59Z" } ] } Figure 15 The entity object class can contain the following members: * objectClassName -- the string "entity" - * handle -- a string representing a registry unique identifier of + * handle -- a string representing a registry-unique identifier of the entity * vcardArray -- a jCard with the entity's contact information * roles -- an array of strings, each signifying the relationship an object would have with its closest containing object (see Section 10.2.4 for a list of values) * publicIds -- see Section 4.8 @@ -1120,21 +1118,21 @@ ... ], ... } Figure 21 The nameserver object class can contain the following members: * objectClassName -- the string "nameserver" - * handle -- a string representing a registry unique identifier of + * handle -- a string representing a registry-unique identifier of the nameserver * ldhName -- a string containing the LDH name of the nameserver (see Section 3) * unicodeName -- a string containing a DNS Unicode name of the nameserver (see Section 3) * ipAddresses -- an object containing the following members: @@ -1186,21 +1184,21 @@ ... ] } Figure 22 The domain object class can contain the following members: * objectClassName -- the string "domain" - * handle -- a string representing a registry unique identifier of + * handle -- a string representing a registry-unique identifier of the domain object instance * ldhName -- a string describing a domain name in LDH form as described in Section 3 * unicodeName -- a string containing a domain name with U-labels as described in Section 3 * variants -- an array of objects, each containing the following values: @@ -1285,21 +1283,21 @@ * remarks -- see Section 4.3 * links -- see Section 4.2 * port43 -- see Section 4.7 * events -- see Section 4.5 * network -- represents the IP network for which a reverse DNS - domain is referenced. See Section 5.4 + domain is referenced; see Section 5.4 The following is an example of a JSON domain object representing a reverse DNS delegation point that might be served by an RIR. { "objectClassName" : "domain", "handle" : "XXXX", "ldhName" : "0.2.192.in-addr.arpa", "nameservers" : [ @@ -1929,30 +1927,31 @@ * entities -- an array of entity objects as defined by Section 5.1 * remarks -- see Section 4.3 * links -- see Section 4.2 * port43 -- see Section 4.7 * events -- see Section 4.5 -5.5. Autonomous System Number Object Class +5.5. The Autonomous System Number Object Class The Autonomous System number (autnum) object class models Autonomous System number registrations found in RIRs and represents the expected response to an "/autnum" query as defined by [I-D.ietf-regext-rfc7482bis]. There is no equivalent object class for DNRs. The high-level structure of the autnum object class - consists of information about the network registration and entities - related to the autnum registration (e.g., registrant information, - contacts, etc.) and is similar to the IP network object class. + consists of information about the autonomous system number + registration and entities related to the autnum registration (e.g., + registrant information, contacts, etc.) and is similar to the IP + network object class. The following is an example of a JSON object representing an autnum. { "objectClassName" : "autnum", "handle" : "XXXX-RIR", "startAutnum" : 10, "endAutnum" : 15, "name": "AS-RTR-1", "type" : "DIRECT ALLOCATION", @@ -2024,23 +2024,23 @@ "Canada" ] ], ["tel", { "type":["work", "voice"], "pref":"1" }, "uri", "tel:+1-555-555-1234;ext=102" ], ["email", { "type":"work" }, "text", "joe.user@example.com" - ] ] + ] ], "roles" : [ "registrant" ], "remarks" : [ { "description" : [ "She sells sea shells down by the sea shore.", "Originally written by Terry Sullivan." ] @@ -2104,27 +2104,27 @@ * remarks -- see Section 4.3 * links -- see Section 4.2 * port43 -- see Section 4.7 * events -- see Section 4.5 6. Error Response Body - Some non-answer responses may return entity bodies with information + Some non-answer responses MAY return entity bodies with information that could be more descriptive. - The basic structure of that response is an object class containing an - error code number (corresponding to the HTTP response code) followed - by a string named "title" and an array of strings named - "description". + The basic structure of that response is an object class containing a + REQUIRED error code number (corresponding to the HTTP response code) + followed by an OPTIONAL string named "title" and an OPTIONAL array of + strings named "description". This is an example of the common response body. { "errorCode": 418, "title": "Your Beverage Choice is Not Available", "description": [ "I know coffee has more ummppphhh.", "Sorry, dude!" @@ -3218,23 +3218,23 @@ See Appendix A.1 for an example of applying those values to contacts and registrants. 15. References 15.1. Normative References [I-D.ietf-regext-rfc7482bis] Hollenbeck, S. and A. Newton, "Registration Data Access Protocol (RDAP) Query Format", Work in Progress, Internet- - Draft, draft-ietf-regext-rfc7482bis-00, 5 June 2020, + Draft, draft-ietf-regext-rfc7482bis-01, 29 June 2020, . + rfc7482bis-01.txt>. [ISO.3166.1988] International Organization for Standardization, "Codes for the representation of names of countries, 3rd edition", ISO Standard 3166, August 1988. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . @@ -3857,33 +3857,71 @@ expectations in Section 4.1. Changed "lunarNic_level_0" to "lunarNIC_level_0". Clarified that the "value", "rel" and "href" JSON values MUST be specified in the "links" array. Clarified that the "description" array is required in the Notices and Remarks data structures and other values are OPTIONAL. Noted that all members of the "events" and "Public IDs" arrays are REQUIRED. Fix "self" link values in examples. Changed "http" to "https" link values in examples. Noted that Figure 18 is an example of a nameserver object with all "appropriate" values given. In appendix C, quoted the word "label" in "label attribute". Added - referencce to "status" definition in the descriptions for IP + reference to "status" definition in the descriptions for IP networks and autnums. Fixed a 404 for the informative reference to "The Stealthy Ascendancy of JSON". Added "boolean" to the definition of zoneSigned. Clarified REQUIRED and OPTIONAL members of the "events" array. Changed "SHOULD not" to "SHOULD NOT" in Section 5. Updated normative references (5226-8126, 5988-8288, 7159-8259). Changed examples using "ns1.xn--fo-5ja.example" to split URLs to avoid long lines. 00: Initial working group version. Added acknowledgements. -Authors' Addresses + 01: Changed "The "lang" attribute may appear anywhere in an object + class or data structure except for in jCard objects" to "The + "lang" attribute as defined in this section MAY appear anywhere in + an object class or data structure, except for in jCard objects. + jCard supports similar functionality by way of the LANGUAGE + property parameter (see Section 5.1 of RFC 6350 [RFC6350]". + Changed "simple data types conveyed in JSON strings" to "simple + data types conveyed in JSON primitive types (strings, numbers, + booleans, and null)". Changed "In other words, servers are free + to not include JSON members containing registration data based on + their own policies" to "In other words, servers are free to omit + unrequired/optional JSON members containing registration data + based on their own policies". Changed "This data structure + appears only in the topmost JSON object of a response" to "This + data structure MUST appear in the topmost JSON object of a + response". Changed "Some non-answer responses may return entity + bodies with information that could be more descriptive" to "Some + non-answer responses MAY return entity bodies with information + that could be more descriptive". Changed "The basic structure of + that response is an object class containing an error code number + (corresponding to the HTTP response code) followed by a string + named "title" and an array of strings named "description"" to "The + basic structure of that response is an object class containing a + REQUIRED error code number (corresponding to the HTTP response + code) followed by an OPTIONAL string named "title" and an OPTIONAL + array of strings named "description"". Changed the "Autonomous + System Number Object Class" section title to "The Autonomous + System Number Object Class" for consistency with other section + titles. Removed trailing periods in the "Terminology and + Definitions" section for consistency. Changed instances of + "lunarNic" to "lunarNIC" for consistency. Removed an extraneous + trailing period after the eventDate description. Changed a "." to + ";" in the description of the "network" member of the domain + object class. Changed "The high-level structure of the autnum + object class consists of information about the network + registration" to "The high-level structure of the autnum object + class consists of information about the autonomous system number + registration". Changed "registry unique" to "registry-unique". +Authors' Addresses Scott Hollenbeck Verisign Labs 12061 Bluemont Way Reston, VA 20190 United States Email: shollenbeck@verisign.com URI: https://www.verisignlabs.com/ Andy Newton