Skip to main content

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]