RFC 7483
JSON Responses for the Registration Data Access Protocol (RDAP)
14. References
14.1. Normative References
[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, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002, <http://www.rfc-editor.org/info/rfc3339>. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003, <http://www.rfc-editor.org/info/rfc3629>. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005, <http://www.rfc-editor.org/info/rfc3986>. [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, "Resource Records for the DNS Security Extensions", RFC 4034, March 2005, <http://www.rfc-editor.org/info/rfc4034>. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008, <http://www.rfc-editor.org/info/rfc5226>. [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of Autonomous System (AS) Numbers", RFC 5396, December 2008, <http://www.rfc-editor.org/info/rfc5396>. [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009, <http://www.rfc-editor.org/info/rfc5646>. [RFC5890] Klensin, J., "Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework", RFC 5890, August 2010, <http://www.rfc-editor.org/info/rfc5890>. [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 Address Text Representation", RFC 5952, August 2010, <http://www.rfc-editor.org/info/rfc5952>. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010, <http://www.rfc-editor.org/info/rfc5988>. [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, January 2014, <http://www.rfc-editor.org/info/rfc7095>. [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the Registration Data Access Protocol (RDAP)", RFC 7480, March 2015, <http://www.rfc-editor.org/info/rfc7480>. [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the Registration Data Access Protocol (RDAP)", RFC 7481, March 2015, <http://www.rfc-editor.org/info/rfc7481>. [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access Protocol (RDAP) Query Format", RFC 7482, March 2015, <http://www.rfc-editor.org/info/rfc7482>.14.2. Informative References
[IANA_IDNTABLES] IANA, "Repository of IDN Practices", <http://www.iana.org/domains/idn-tables>. [JSON_ascendancy] MacVittie, L., "The Stealthy Ascendancy of JSON", April 2011, <https://devcentral.f5.com/weblogs/macvittie/ archive/2011/04/27/the-stealthy-ascendancy-of-json.aspx>. [JSON_performance_study] Nurseitov, N., Paulson, M., Reynolds, R., and C. Izurieta, "Comparison of JSON and XML Data Interchange Formats: A Case Study", 2009, <http://www.cs.montana.edu/izurieta/pubs/caine2009.pdf>. [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, September 2004, <http://www.rfc-editor.org/info/rfc3912>. [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", STD 69, RFC 5730, August 2009, <http://www.rfc-editor.org/info/rfc5730>. [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) Security Extensions Mapping for the Extensible Provisioning Protocol (EPP)", RFC 5910, May 2010, <http://www.rfc-editor.org/info/rfc5910>. [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, August 2011, <http://www.rfc-editor.org/info/rfc6350>. [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", RFC 6839, January 2013, <http://www.rfc-editor.org/info/rfc6839>.
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.4 be used. The following is an example of an elided containing object with an embedded entity that is both a registrant and administrative contact: { ... "entities" : [ { "objectClassName" : "entity", "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", [ "", "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", "administrative" ], "remarks" : [ { "description" : [ "She sells sea shells down by the sea shore.", "Originally written by Terry Sullivan." ] } ], "events" : [ { "eventAction" : "registration", "eventDate" : "1990-12-31T23:59:59Z" }, { "eventAction" : "last changed", "eventDate" : "1991-12-31T23:59:59Z" } ] } ] } Figure 34 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.2).
The following is an elided example of a registrant with information changed to reflect that of a third party. { ... "entities" : [ { "objectClassName" : "entity", "handle" : "XXXX", ... "roles" : [ "registrant", "administrative" ], "status" : [ "proxy", "private", "obscured" ] } ] } Figure 35A.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 4.8) represents that information. The following is an example of an elided containing object with an embedded entity that is a registrar: { ... "entities":[ { "objectClassName" : "entity", "handle":"XXXX", "vcardArray":[ "vcard", [ ["version", {}, "text", "4.0"], ["fn", {}, "text", "Joe's Fish, Chips, and Domains"], ["kind", {}, "text", "org"], ["lang", { "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."
]
}
],
"links":[
{
"value":"http://example.net/entity/XXXX",
"rel":"alternate",
"type":"text/html", "href":"http://www.example.com" } ] } ] } Figure 36Appendix 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 4.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:59Z" } ] Figure 37 For the second use case, the events data structure (Section 4.5) is used with the "eventActor" object member.
This is an example of an "events" array with the "eventActor". "events" : [ { "eventAction" : "registration", "eventActor" : "XYZ-NIC", "eventDate" : "1990-12-31T23:59:59Z" } ] Figure 38 For the third use case, the "asEventActor" array is used when an entity (Section 5.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. { "objectClassName" : "domain", "handle" : "XXXX", "ldhName" : "foo.example", "status" : [ "locked", "transfer prohibited" ], ... "entities" : [ { "handle" : "XXXX", ... "asEventActor" : [ { "eventAction" : "last changed", "eventDate" : "1990-12-31T23:59:59Z" } ] } ] } Figure 39
Appendix C. Structured vs. Unstructured Addresses
The entity (Section 5.1) object class uses jCard [RFC7095] 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."]] ], ["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" ] ], ["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 40 The arrays in Figure 40 with the first member of "adr" represent postal addresses. In the first example, the postal address is given as an array of strings and constitutes a structured address. For 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 5.3 defines the "secureDNS" member to represent secure DNS information about domain names. DNSSEC provides data integrity for DNS through the digital signing of resource records. To enable DNSSEC, the zone is signed by one or more private keys and the signatures are 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 DS records, and signed by the parent's private key (RRSIG DS record), as indicated in "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. The domain object class (Section 5.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 serving 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 that 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_ascendancy]). Studies have also found that JSON is generally less bulky and consequently faster to parse (see [JSON_performance_study]).Acknowledgements
This document is derived from original work on RIR responses in JSON by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew L. Newton. Additionally, this document incorporates work on DNR responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean Shen. The components of the DNR object classes are derived from a categorization of WHOIS response formats created by Ning Kong, Linlin Zhou, Guangqing Deng, Steve Sheng, Francisco Arias, Ray Bellis, and Frederico Neves. Tom Harrison, Murray Kucherawy, Ed Lewis, Audric Schiltknecht, Naoki Kambe, and Maarten Bosteels contributed significant review comments and provided clarifying text. James Mitchell provided text regarding the processing of unknown JSON attributes and identified issues
leading to the remodeling of events. Ernie Dainow and Francisco Obispo provided concrete suggestions that led to a better variant model for domain names. Ernie Dainow provided the background information on the secure DNS attributes and objects for domains, informative text on DNSSEC, and many other attributes that appear throughout the object classes of this document. The switch to and incorporation of jCard was performed by Simon Perreault. Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working group from which this document has been created.Authors' Addresses
Andrew Lee Newton American Registry for Internet Numbers 3635 Concorde Parkway Chantilly, VA 20151 United States EMail: andy@arin.net URI: http://www.arin.net Scott Hollenbeck Verisign Labs 12061 Bluemont Way Reston, VA 20190 United States EMail: shollenbeck@verisign.com URI: http://www.verisignlabs.com/