JSON Responses for the Registration Data Access Protocol (RDAP)
draft-ietf-weirds-json-response-06
The information below is for an old version of the document.
Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 7483.
Expired & archived
|
|
---|---|---|---|
Authors | Andy Newton , Scott Hollenbeck | ||
Last updated | 2014-04-06 (Latest revision 2013-10-03) | ||
Replaces | draft-newton-weirds-unified-json-response | ||
RFC stream | Internet Engineering Task Force (IETF) | ||
Formats | |||
Reviews | |||
Additional resources | Mailing list discussion | ||
Stream | WG state | WG Consensus: Waiting for Write-Up | |
Document shepherd | Murray Kucherawy | ||
IESG | IESG state | Became RFC 7483 (Proposed Standard) | |
Consensus boilerplate | Yes | ||
Telechat date | (None) | ||
Responsible AD | (None) | ||
Send notices to | (None) |
draft-ietf-weirds-json-response-06
quot;, draft-ietf-weirds-rdap-query-07 (work in progress), October 2013. [ISO.3166.1988] International Organization for Standardization, "Codes for the representation of names of countries, 3rd edition", ISO Standard 3166, August 1988. 15.2. Informative References [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, September 2004. [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", STD 69, RFC 5730, August 2009. [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) Security Extensions Mapping for the Extensible Provisioning Protocol (EPP)", RFC 5910, May 2010. [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, August 2011. [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", RFC 6839, January 2013. [JSON_acendancy] MacVittie, ., "The Stealthy Ascendancy of JSON", 04 2011. [IANA_IDNTABLES] , "IANA IDN Tables", , <http://www.iana.org/domains/idn-tables>. Newton & Hollenbeck Expires April 06, 2014 [Page 67] Internet-Draft RDAP JSON RESPONSES October 2013 [JSON_performance_study] Montana State University - Bozeman, Montana State University - Bozeman, Montana State University - Bozeman, Montana State University - Bozeman, "Comparison of JSON and XML Data Interchange Formats: A Case Study", 2009. Appendix A. Suggested Data Modeling with the Entity Object Class A.1. Registrants and Contacts This document does not provide specific object classes for registrants and contacts. Instead the entity object class may be used to represent a registrant or contact. When the entity object is embedded inside a containing object such as a domain name or IP network, the 'roles' string array can be used to signify the relationship. It is recommended that the values from Section 10.2.3 be used. The following is an example of an elided containing object with an embedded entity that is both a registrant and admin contact: { ... "entities" : [ { "handle" : "XXXX", "vcardArray":[ "vcard", [ ["version", {}, "text", "4.0"], ["fn", {}, "text", "Joe User"], ["kind", {}, "text", "individual"], ["lang", { "pref":"1" }, "language-tag", "fr"], ["lang", { "pref":"2" }, "language-tag", "en"], ["org", { "type":"work" }, "text", "Example"], ["title", {}, "text", "Research Scientist"], ["role", {}, "text", "Project Lead"], ["adr", { "type":"work" }, "text", Newton & Hollenbeck Expires April 06, 2014 [Page 68] Internet-Draft RDAP JSON RESPONSES October 2013 [ "", "Suite 1234", "4321 Rue Somewhere", "Quebec", "QC", "G1V 2M2", "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", "admin" ], "remarks" : [ { "description" : [ "She sells sea shells down by the sea shore.", "Originally written by Terry Sullivan." ] } ], "events" : [ { "eventAction" : "registration", "eventDate" : "1990-12-31T23:59:60Z" }, { "eventAction" : "last changed", "eventDate" : "1991-12-31T23:59:60Z" } ] } ] } Newton & Hollenbeck Expires April 06, 2014 [Page 69] Internet-Draft RDAP JSON RESPONSES October 2013 In many use cases, it is necessary to hide or obscure the information of a registrant or contact due to policy or other operational matters. Registries can denote these situations with 'status' values (see Section 10.2.1). The following is an elided example of a registrant with information changed to reflect that of a third party. { ... "entities" : [ { "handle" : "XXXX", ... "roles" : [ "registrant", "admin" ], "status" : [ "proxy", "private", "obscured" ] } ] } A.2. Registrars This document does not provide a specific object class for registrars, but like registrants and contacts (see Appendix A.1) the 'roles' string array maybe used. Additionally, many registrars have publicly assigned identifiers. The 'publicIds' structure (Section 5.8) represents that information. The following is an example of an elided containing object with an embedded entity that is a registrar: { ... "entities":[ { "handle":"XXXX", "vcardArray":[ "vcard", [ ["version", {}, "text", "4.0"], ["fn", {}, "text", "Joe's Fish, Chips and Domains"], ["kind", {}, "text", "org"], ["lang", { Newton & Hollenbeck Expires April 06, 2014 [Page 70] Internet-Draft RDAP JSON RESPONSES October 2013 "pref":"1" }, "language-tag", "fr"], ["lang", { "pref":"2" }, "language-tag", "en"], ["org", { "type":"work" }, "text", "Example"], ["adr", { "type":"work" }, "text", [ "", "Suite 1234", "4321 Rue Somewhere", "Quebec", "QC", "G1V 2M2", "Canada" ] ], ["tel", { "type":["work", "voice"], "pref":"1" }, "uri", "tel:+1-555-555-1234;ext=102" ], ["email", { "type":"work" }, "text", "joes_fish_chips_and_domains@example.com" ], ] ], "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." ] } Newton & Hollenbeck Expires April 06, 2014 [Page 71] Internet-Draft RDAP JSON RESPONSES October 2013 ], "links":[ { "value":"http://example.net/entity/XXXX", "rel":"alternate", "type":"text/html", "href":"http://www.example.com" } ] } ] } Appendix B. Modeling Events Events represent actions that have taken place against a registered object at a certain date and time. Events have three properties: the action, the actor, and the date and time of the event (which is sometimes in the future). In some cases the identity of the actor is not captured. Events can be modeled in three ways: 1. events with no designated actor 2. events where the actor is only designated by an identifier 3. events where the actor can be modeled as an entity For the first use case, the 'events' data structure (Section 5.5) is used without the 'eventActor' object member. This is an example of an "events" array without the 'eventActor'. "events" : [ { "eventAction" : "registration", "eventDate" : "1990-12-31T23:59:60Z" } ] Figure 20 For the second use case, the 'events' data structure (Section 5.5) is used with the 'eventActor' object member. Newton & Hollenbeck Expires April 06, 2014 [Page 72] Internet-Draft RDAP JSON RESPONSES October 2013 This is an example of an "events" array with the 'eventActor'. "events" : [ { "eventAction" : "registration", "eventActor" : "XYZ-NIC", "eventDate" : "1990-12-31T23:59:60Z" } ] Figure 21 For the third use case, the 'asEventActor' array is used when an entity (Section 6.1) is embedded into another object class. The 'asEventActor' array follows the same structure as the 'events' array but does not have 'eventActor' attributes. The following is an elided example of a domain object with an entity as an event actor. { "handle" : "XXXX", "ldhName" : "foo.example", "status" : [ "locked", "transfer Prohibited" ], ... "entities" : [ { "handle" : "XXXX", ... "asEventActor" : [ { "eventAction" : "last changed", "eventDate" : "1990-12-31T23:59:60Z" } ] } ] } Appendix C. Structured vs Unstructured Addresses Newton & Hollenbeck Expires April 06, 2014 [Page 73] Internet-Draft RDAP JSON RESPONSES October 2013 The entity (Section 6.1) object class uses jCard [I-D.ietf-jcardcal-jcard] to represent contact information, including postal addresses. jCard has the ability to represent multiple language preferences, multiple email address and phone numbers, and multiple postal addresses in both a structured and unstructured format. This section describes the use of jCard for representing structured and unstructured addresses. The following is an example of a jCard. { "vcardArray":[ "vcard", [ ["version", {}, "text", "4.0"], ["fn", {}, "text", "Joe User"], ["n", {}, "text", ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] ], ["bday", {}, "date-and-or-time", "--02-03"], ["anniversary", {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" ], ["gender", {}, "text", "M"], ["kind", {}, "text", "individual"], ["lang", { "pref":"1" }, "language-tag", "fr"], ["lang", { "pref":"2" }, "language-tag", "en"], ["org", { "type":"work" }, "text", "Example"], ["title", {}, "text", "Research Scientist"], ["role", {}, "text", "Project Lead"], ["adr", { "type":"work" }, "text", [ "", "Suite 1234", "4321 Rue Somewhere", "Quebec", "QC", "G1V 2M2", "Canada" Newton & Hollenbeck Expires April 06, 2014 [Page 74] Internet-Draft RDAP JSON RESPONSES October 2013 ] ], ["adr", { "type":"home", "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" }, "text", [ "", "", "", "", "", "", "" ] ], ["tel", { "type":["work", "voice"], "pref":"1" }, "uri", "tel:+1-555-555-1234;ext=102" ], ["tel", { "type":["work", "cell", "voice", "video", "text"] }, "uri", "tel:+1-555-555-1234" ], ["email", { "type":"work" }, "text", "joe.user@example.com" ], ["geo", { "type":"work" }, "uri", "geo:46.772673,-71.282945"], ["key", { "type":"work" }, "uri", "http://www.example.com/joe.user/joe.asc" ], ["tz", {}, "utc-offset", "-05:00"], ["url", { "type":"home" }, "uri", "http://example.org"] ] ] } Figure 22 The arrays in Figure 22 with the first member of "adr" represent postal addresses. In the first example, the postal address is given as a an array of strings and constitutes a structured address. For Newton & Hollenbeck Expires April 06, 2014 [Page 75] Internet-Draft RDAP JSON RESPONSES October 2013 components of the structured address that are not applicable, an empty string is given. Each member of that array aligns with the positions of a vCard as given in [RFC6350]. In this example, the following data corresponds to the following positional meanings: 1. post office box - not applicable, empty string 2. extended address (e.g., apartment or suite number) - Suite 1234 3. street address - 4321 Rue Somewhere 4. locality (e.g., city) - Quebec 5. region (e.g., state or province) - QC 6. postal code - G1V 2M2 7. country name (full name) - Canada The second example is an unstructured address. It uses the label attribute, which is a string containing a newline (\n) character to separate address components in an unordered, unspecified manner. Note that in this example the structured address array is still given but that each string is an empty string. Appendix D. Secure DNS Section 6.3 defines the "secureDNS" member to represent secure DNS information about domain names. DNSSEC provides data integrity for DNS through digital signing of resource records. To enable DNSSEC, the zone is signed by one or more private keys and the signatures stored as RRSIG records. To complete the chain of trust in the DNS zone hierarchy, a digest of each DNSKEY record (which contains the public key) must be loaded into the parent zone, stored as Delegation Signer (DS) records and signed by the parent's private key (RRSIG DS record), "Resource Records for the DNS Security Extensions" [RFC4034]. Creating the DS records in the parent zone can be done by the registration authority, "Domain Name System (DNS) Security Extensions Mapping for the Extensible Provisioning Protocol (EPP)" [RFC5910]. Only DS related information is provided by RDAP, since other information is not generally stored in the registration database. Other DNSSEC related information can be retrieved with other DNS tools such as dig. Newton & Hollenbeck Expires April 06, 2014 [Page 76] Internet-Draft RDAP JSON RESPONSES October 2013 The domain object class (Section 6.3) can represent this information using either the 'dsData' or 'keyData' object arrays. Client implementers should be aware that some registries do not collect or do not publish all of the secure DNS meta-information. Appendix E. Motivations for Using JSON This section addresses a common question regarding the use of JSON over other data formats, most notably XML. It is often pointed out that many DNRs and one RIR support the EPP [RFC5730] standard, which is an XML serialized protocol. The logic is that since EPP is a common protocol in the industry it follows that XML would be a more natural choice. While EPP does influence this specification quite a bit, EPP serves a different purpose which is the provisioning of Internet resources between registries and accredited registrars and serves a much narrower audience than that envisioned for RDAP. By contrast, RDAP has a broader audience and is designed for public consumption of data. Experience from RIRs with first generation RESTful web services for Whois indicate a large percentage of clients operate within browsers and other platforms where full-blown XML stacks are not readily available and where JSON is a better fit. Additionally, while EPP is used in much of the DNR community it is not a universal constant in that industry. And finally, EPP's use of XML predates the specification of JSON. If EPP had been defined today, it may very well have used JSON instead of XML. Beyond the specific DNR and RIR communities, the trend in the broader Internet industry is also switching to JSON over XML, especially in the area of RESTful web services (see [JSON_acendancy]). Studies have also found that JSON is generally less bulky and consequently faster to parse (see [JSON_performance_study]). Appendix F. Changelog Initial -00 Adopted as working group document 2012-September-18. -01 Minor spelling corrections. Changed "Registry Data" to "Registration Data" for the sake of consistency. Transitioned to RFC 5988 links and relationship types from our own custom "uris" structure. Newton & Hollenbeck Expires April 06, 2014 [Page 77] Internet-Draft RDAP JSON RESPONSES October 2013 Some examples had 'status' as a string. Those have been corrected as 'status' is always an array of strings. Domain variants can now have a multi-valued relationship with domain registrations. "names" in the entity object class was changed to "entityNames". Some IP address examples change to IPv6. Change phone number examples and added reference to E.164. Added section on motivations for using JSON. Added error response body section. Added JSON naming section. Added common data structures section. Added the IANA Considerations section and the media type registration. Added 'lang' name/value. Added internationalization considerations section. -02 Removed level from media type registration. Textual changes as given by Ed Lewis. Fixed object class linking example noted by Francisco Obispo Fixed a lot of other examples called out by Alex Sergeyev Added a note that JSON names are case sensitive Added 'status' to IP networks as suggested by Alex Sergeyev -03 Added jCard verbiage and examples and deleted overlapping contact information and the appendix on postal addresses Newton & Hollenbeck Expires April 06, 2014 [Page 78] Internet-Draft RDAP JSON RESPONSES October 2013 Removed the IANA considerations as they have been moved to another document Changed the remarks structure to be like notices Reordering and rewording some of the sections so they flow better Added note about object class "self" links Changed ipAddresses in nameserver object class to separate out v6 from v4 Changed IP network version identifier from integer to string to be more consistent with ipAddresses identifier in nameserver object classes Changed DNS names to LDH names and Unicode names Modified the definition of 'conjoined' variant relationship so it was circular Added 'proxy', 'private', 'redacted', and 'obscured' status values (most useful for entities). Added a privacy considerations section Added a security considerations section Added 'reseller' and 'sponsor' to the list of entity roles Added the 'events' common data structure Added 'asEventActor' to entities Added appendix on event modeling Removed the subclasses/superclassing between RIRs/DNRs for entity and domain object classes Change suggested status/relation/etc values to be case/spacing consistent Normalized some of the definitions of object class members Modifying the JSON signaling section to reference the guidance in draft-ietf-weirds-using-http Newton & Hollenbeck Expires April 06, 2014 [Page 79] Internet-Draft RDAP JSON RESPONSES October 2013 Changed the text regarding the process of unknown JSON attributes -04 'description' removed from IP network and autnum because it is redundant with the remarks structure. Added 'entities' array to nameservers. Added 'status' to autnum. Added 'publicIds' to entity and domain. Added embedded entities to the entity object class. Added 'idnTable' to variants objects in domain object class. Changed the numbers for startNum and endNum in autnum to numbers instead of strings. Added an example for error response with full rdapConformance and notices. Added a section discussing help. Changed entities to use vcardArray and changed the examples to be current with jCard. Added a section on structured vs unstructured addresses. Added associated to the list of status values. Added a secure DNS section changed the 'delegationKey' object into the 'secureDNS' object. Changed the suggested values to an IANA registry. Added 'proxy' to the list of entity roles. -05 Added IANA registration for RDAP JSON Media Type Added 'associated' status type. This was done earlier but got dropped during a reorganization of the document. Added the following status types: Newton & Hollenbeck Expires April 06, 2014 [Page 80] Internet-Draft RDAP JSON RESPONSES October 2013 active inactive locked pending create pending renew pending update pending transfer pending delete renew prohibited Added the following event actions: locked unlocked Added the following roles: notifications noc Changed the 'tech' role to 'technical' Many document reference changes. Many examples have been fixed. Added links to dsData and keyData. Changed flags and protocols to integers in keyData. Added 'entities' to the specified list for autnum. Added SHOULD/SHOULD NOT language about using "type": "application/rdap+json" for self links. Added 'port43' to ip networks and autnum. -06 Newton & Hollenbeck Expires April 06, 2014 [Page 81] Internet-Draft RDAP JSON RESPONSES October 2013 Fix search response example. Change the returned search arrays to 'domainSearchResults', 'entitySearchResults', and 'nameserverSearchResults'. Authors' Addresses Andrew Lee Newton American Registry for Internet Numbers 3635 Concorde Parkway Chantilly, VA 20151 US Email: andy@arin.net URI: http://www.arin.net Scott Hollenbeck Verisign Labs 12061 Bluemont Way Reston, VA 20190 US Email: shollenbeck@verisign.com URI: http://www.verisignlabs.com/ Newton & Hollenbeck Expires April 06, 2014 [Page 82]