Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7483

JSON Responses for the Registration Data Access Protocol (RDAP)

Pages: 78
Obsoleted by:  9083
Part 4 of 4 – Pages 65 to 78
First   Prev   None

Top   ToC   RFC7483 - Page 65   prevText

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>.
Top   ToC   RFC7483 - Page 66
   [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>.
Top   ToC   RFC7483 - Page 67
   [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>.
Top   ToC   RFC7483 - Page 68

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",
Top   ToC   RFC7483 - Page 69
                 "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).
Top   ToC   RFC7483 - Page 70
   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 35

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 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"],
Top   ToC   RFC7483 - Page 71
             ["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",
Top   ToC   RFC7483 - Page 72
             "type":"text/html",
             "href":"http://www.example.com"
           }
         ]
       }
     ]
   }

                                 Figure 36

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 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.
Top   ToC   RFC7483 - Page 73
   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
Top   ToC   RFC7483 - Page 74

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", {
Top   ToC   RFC7483 - Page 75
             "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:
Top   ToC   RFC7483 - Page 76
   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.
Top   ToC   RFC7483 - Page 77

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
Top   ToC   RFC7483 - Page 78
   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/