One document matched: draft-ietf-weirds-json-response-03.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "http://xml.resource.org/authoring/rfc2629.dtd"
[
<!ENTITY RFC0791 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.0791.xml'>
<!ENTITY RFC1166 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.1166.xml'>
<!ENTITY RFC2616 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml'>
<!ENTITY RFC3339 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml'>
<!ENTITY RFC3730 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3730.xml'>
<!ENTITY RFC3912 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3912.xml'>
<!ENTITY RFC3986 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
<!ENTITY RFC4034 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4034.xml'>
<!ENTITY RFC4343 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4343.xml'>
<!ENTITY RFC4627 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml'>
<!ENTITY RFC5322 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5322.xml'>
<!ENTITY RFC5396 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5396.xml'>
<!ENTITY RFC5646 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5646.xml'>
<!ENTITY RFC5890 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5890.xml'>
<!ENTITY RFC5952 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5952.xml'>
<!ENTITY RFC5988 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml'>
<!ENTITY I-D.draft-kewisch-vcard-in-json-01 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-kewisch-vcard-in-json-01.xml'>
]>
<?rfc toc="true"?>
<rfc category="std" docName="draft-ietf-weirds-json-response-03" ipr="trust200902">
<front>
<title abbrev="RDAP JSON RESPONSES">JSON Responses for the Registration Data Access Protocol
(RDAP)</title>
<author fullname="Andrew Lee Newton" initials="A.L." surname="Newton">
<organization abbrev="ARIN">American Registry for Internet Numbers</organization>
<address>
<postal>
<street>3635 Concorde Parkway</street>
<city>Chantilly</city>
<region>VA</region>
<country>US</country>
<code>20151</code>
</postal>
<email>andy@arin.net</email>
<uri>http://www.arin.net</uri>
</address>
</author>
<author initials="S." surname="Hollenbeck" fullname="Scott Hollenbeck">
<organization>Verisign Labs</organization>
<address>
<postal>
<street>12061 Bluemont Way</street>
<city>Reston</city>
<region>VA</region>
<code>20190</code>
<country>US</country>
</postal>
<email>shollenbeck@verisign.com</email>
<uri>http://www.verisignlabs.com/</uri>
</address>
</author>
<date/>
<abstract>
<t> 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. </t>
</abstract>
</front>
<middle>
<section title="Introduction" anchor="introduction">
<t> This document describes responses in the <xref target="RFC4627">JSON</xref> format
for the RESTful web queries as defined by the <xref target="I-D.ietf-weirds-rdap-query"
>Registration Data Access Protocol Lookup Format</xref>.
</t>
<t>
The data model for JSON responses is specified in four sections:
<list style="numbers">
<t>simple data types conveyed in JSON strings</t>
<t>data structures specified as JSON arrays or objects that are used repeatedly when building up larger objects</t>
<t>object classes representing structured data corresponding to a given query</t>
<t>the response to an error</t>
</list>
</t>
<t>
The object classes represent responses for two major categories of data: responses
returned by Regional Internet Registries (RIRs) for registrations data related to IP
addresses, reverse DNS names, and Autonomous System numbers; and responses returned
by Domain Name Registries (DNRs) for registration data related to forward DNS names.
The following object classes are served by both RIRs and DNRs:
<list style="numbers">
<t>domains</t>
<t>nameservers</t>
<t>entities</t>
</list>
The information served by both RIRs and DNRs for these object classes overlap
extensively and are given in this document as a unified model for both classes of
service.
</t>
<t>
In addition to the object classes listed above, RIRs also serve the following
object classes:
<list style="numbers">
<t>IP networks</t>
<t>Autonomous System numbers</t>
</list>
</t>
<t>
Object classes defined in this document represent a minimal set of what a
compliant client/server MUST understand to function correctly, however
some deployments may want to include additional object classes to suit
individual needs. Anticipating this
need for extension, <xref target="json_naming"></xref> of this document defines a mechanism for
extending the JSON objects that are described in this document.
</t>
</section>
<section title="Terminology and Definitions" anchor="terminology_definitions">
<t>The following list describes terminology and definitions used throughout this
document: <list style="hanging" hangIndent="18">
<t hangText="DNR:">"Domain Name Registry".</t>
<t hangText="LDH:">"Letters, Digits, Hyphen".</t>
<t hangText="member:">data found with in an object as defined by <xref
target="RFC4627">JSON</xref>.</t>
<t hangText="object:">a data structure as defined by <xref target="RFC4627"
>JSON</xref>.</t>
<t hangText="object class:">the definition of members that may be found in JSON
objects described in this document.</t>
<t hangText="object instance:">an instantiation or specific instance of an
object class.</t>
<t hangText="RDAP:">"Registration Data Access Protocol".</t>
<t hangText="RIR:">"Regional Internet Registry".</t>
</list>
</t>
</section>
<section title="Use of JSON">
<section title="Signaling">
<t>
Media type signaling for the JSON data specified in this document is
specified in <xref target="I-D.ietf-weirds-using-http"></xref>.
</t>
</section>
<section title="Naming" anchor="json_naming">
<t>
Clients processing <xref target="RFC4627">JSON</xref> responses are under
no obligation to process unrecognized JSON attributes but SHOULD NOT treat them as an error.
Servers MAY insert values signified
by names into the JSON responses which are not specified in this document.
Insertion of unspecified values into JSON responses SHOULD have names prefixed
with a short identifier followed by an underscore followed by a meaningful name.
The full JSON name, the prefix plus the underscore plus the meaningful name,
SHOULD adhere to the character and name limitations of the prefix registry
described in <xref target="I-D.ietf-weirds-using-http"/>.</t>
<figure anchor="json_example_no_extra_values">
<preamble> Consider the following JSON response with JSON names. some of which are
not specified in this document. </preamble>
<artwork xml:space="preserve">
{
"handle" : "ABC123",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
]
}
</artwork>
</figure>
<t> If The Registry of the Moon desires to express information not found in this
specification, it might select "lunarNic" as its identifying prefix and insert,
as an example, the name "lunarNic_beforeOneSmallStep" to signify registrations
occurring before the first moon landing and the name
"lunarNic_harshMistressNotes" containing other descriptive text. </t>
<figure anchor="json_example_with_extra_values">
<preamble> Consider the following JSON response with JSON names, some of which
should be ignored by clients without knowledge of their meaning. </preamble>
<artwork xml:space="preserve">
{
"handle" : "ABC123",
"lunarNic_beforeOneSmallStep" : "TRUE THAT!",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"lunarNic_harshMistressNotes" :
[
"In space,",
"nobody can hear you scream."
]
}
</artwork>
</figure>
<t> Insertion of unrecognized names ignored by clients may also be used for future
revisions to this specification. </t>
<t> Clients processing JSON responses MUST be prepared for values specified in this
document to be absent from a response as no JSON value listed is required to
appear in a response. In other words, servers MAY remove values as is needed by
the policies of the server operator.</t>
<t>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.</t>
</section>
</section>
<section title="Common Data Types" anchor="common_data_types">
<t><xref target="RFC4627">JSON</xref> defines the data types of a number, character
string, boolean, array, object and null. This section describes the semantics and/or
syntax reference for data types used in this document derived from the JSON
character string.</t>
<t>
<list style="hanging" hangIndent="18">
<t hangText="'handle': ">DNRs and RIRs have registry-unique identifiers that may
be used to specifically reference an object instance. The semantics of this
data type as found in this document is to be a registry-unique reference to
the closest enclosing object where the value is found. The data type names
'registryId', 'roid', 'nic-handle', 'registrationNo', etc. are terms often
synonymous with this data type. In this document, the term 'handle' is used.
The term exposed to users by clients is a presentation issue beyond the
scope of this document.</t>
<t hangText="IPv4 addresses: ">The representation of IPv4 addresses in this
document uses the dotted-decimal notation described in <xref
target="RFC1166"/>. An example of this textual representation is
'192.0.2.0'.</t>
<t hangText="IPv6 addresses: ">The representation of IPv6 addresses in this
document follow the forms outlined in <xref target="RFC5952"/>. An example
of this textual representation is '2001:db8::1:0:0:1'.</t>
<t hangText="country codes: ">Where the identity of a geopolitical nation or
country is needed, these identities are represented with the alpha-2 or 2
character country code designation as defined in <xref
target="ISO.3166.1988"/>. The alpha-2 representation is used because it
is freely available whereas the alpha-3 and numeric-3 standards are not.</t>
<t hangText="LDH names: ">Textual representations of DNS names where the labels
of the domain are all "letters, digits, hyphen" labels as described by <xref target="RFC5890"></xref>.
Trailing periods are optional.</t>
<t hangText="Unicode names: ">Textual representations of DNS names were one or
more of the labels are u-labels as described by <xref target="RFC5890"></xref>.
Trailing periods are optional.</t>
<t hangText="dates and times: ">The syntax for values denoting dates and times
is defined in <xref target="RFC3339"/>.</t>
<t hangText="URIs: ">The syntax for values denoting a Uniform Resource
Identifier (URI) is defined by <xref target="RFC3986"/>.</t>
</list>
</t>
<t>Contact information is defined using JSON vCards as described in <xref target="I-D.kewisch-vcard-in-json"></xref></t>
</section>
<section title="Common Data Structures">
<t> This section defines common data structures to be used in response. Each of
these structures MAY appear within any object class of a response. </t>
<section title="RDAP Conformance" anchor="rdap_conformance">
<t> The first data structure is named "rdapConformance" and is simply 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 top most object of
a response.</t>
<figure anchor="rdapConformance">
<preamble>An example rdapConformance data structure:</preamble>
<artwork xml:space="preserve">
"rdapConformance" :
[
"rdap_level_0"
]
</artwork>
</figure>
<t>
The string literal "rdap_level_0" signifies conformance with this specification.
When custom JSON values are inserted into responses, conformance to those custom
specifications should use a string prefixed with the appropriate identifier from
the IANA prefix identifier registry specified in <xref target="I-D.ietf-weirds-using-http"></xref>.
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".
</t>
<figure anchor="rdapConformance_lunarNic">
<preamble>Example rdapConformance structure with custom extensions noted:</preamble>
<artwork xml:space="preserve">
"rdapConformance" :
[
"rdap_level_0",
"lunarNic_level_0"
]
</artwork>
</figure>
</section>
<section title="Links" anchor="links">
<t> The "links" array is found in data structures to signify links to other
resources on the Internet.
The relationship of these links is defined by the IANA registry described
by <xref target="RFC5988"/>. </t>
<figure anchor="link_example">
<preamble>The following is an example of the link structure:</preamble>
<artwork xml:space="preserve">
{
"value" : "http://example.com/context_uri",
"rel" : "self",
"href" : "http://example.com/target_uri",
"hreflang" : [ "en", "ch" ],
"title" : [ "title1", "title2" ],
"media" : "screen",
"type" : "application/json"
}
</artwork>
</figure>
<t> The JSON name/values of "rel", "href", "hreflang", "title", "media", and "type"
correspond to values found in Section 5 of <xref target="RFC5988"/>. The "value"
JSON value is the context URI as described by <xref target="RFC5988"/>. The "value",
"rel", and "href" JSON values MUST be specified. All other JSON values are optional. </t>
<figure>
<preamble>This is an example of the "links" array as it might be found in an object
class:</preamble>
<artwork xml:space="preserve">
"links" :
[
{
"value" : "http://example.com/ip/2001:db8::123",
"rel" : "self",
"href" : "http://example.com/ip/2001:db8::123"
},
{
"value" : "http://example.com/ip/2001:db8::123",
"rel" : "up",
"href" : "http://example.com/ip/2001:db8::/48"
}
]
</artwork>
</figure>
</section>
<section title="Notices And Remarks" anchor="notices_and_remarks">
<t> The "notices" and "remarks" data structures take the same form.
The "notices" structure denotes information about the service
providing RDAP information, whereas the "remarks" structure denotes
information about the object class it is contained within
(see <xref target="object_classes"></xref> regarding object classes).
</t>
<t>
Both are an array of objects. Each
object contains an optional "title" string representing the title of the object, an
array of strings named "description" for the purposes of conveying any
descriptive text, and an optional "links" array as described
in <xref target="links"/>. </t>
<figure anchor="notices_example">
<preamble>An example of the notices data structure:</preamble>
<artwork xml:space="preserve">
"notices" :
[
{
"title" : "Terms of Use",
"description" :
[
"Service subject to The Registry of the Moon's TOS.",
"Copyright (c) 2020 LunarNIC"
],
"links" :
[
{
"value" : "http://example.net/entity/XXXX",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/terms_of_use.html"
}
]
}
]
</artwork>
</figure>
<t>
It is the job of the clients to determine line breaks, spacing
and display issues for sentences within the character strings
of the "description" array. Servers SHOULD NOT split sentences
across multiple strings of this array. Each string is to represent
a semantic division in the descriptive text.
</t>
<figure anchor="remarks_example">
<preamble>An example of the remarks data structure:</preamble>
<artwork xml:space="preserve">
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
]
</artwork>
</figure>
<t>
Note that objects in the "remarks" array may also have a "links" array.
</t>
<t>
While the "remarks" array will appear in many object classes in a response, the
"notices" array appears only in the top most object of a response.
</t>
</section>
<section title="Language Identifier" anchor="language_identifier">
<t> This data structure is a simple JSON name/value of "lang" with a string
containing a language identifier as described by <xref target="RFC5646"/>. </t>
<figure anchor="language_example">
<artwork xml:space="preserve">
"lang" : "mn-Cyrl-MN"
</artwork>
</figure>
<t>The 'lang' attribute may appear anywhere in an object class or data structure.</t>
</section>
<section title="Events" anchor="events">
<t>
This data structure represents events that have occurred on an instance of
an object class (see <xref target="object_classes"></xref> regarding object classes).
</t>
<figure anchor="events_example">
<preamble>This is an example of an "events" array.</preamble>
<artwork xml:space="preserve">
"events" :
[
{
"eventAction" : "registration",
"eventActor" : "SOMEID-LUNARNIC",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventActor" : "OTHERID-LUNARNIC",
"eventDate" : "1991-12-31T23:59:60Z"
}
]
</artwork>
</figure>
<t>
The "events" array consists of objects, each with the following members:
<list style="symbols">
<t>'eventAction' -- a string denoting the reason for the event</t>
<t>'eventActor' -- an optional identifier denoting the actor responsible for the event</t>
<t>'eventDate' -- a string containing the time and date the event occurred.</t>
</list>
</t>
<t>
Events can be future dated. One use case for future dating of events is to
denote when an object expires from a registry.
</t>
<t>
See <xref target="suggested_event_actions"></xref> for a list of suggested
values for the 'eventAction' string. See <xref target="modeling_events"></xref>
regarding the various ways events can be modeled.
</t>
</section>
<section title="Status" anchor="status">
<t>This data structure, named 'status', is an array of strings indicating the state of a registered object
(see <xref target="suggested_status"></xref> for suggested values).</t>
</section>
<section title="Port 43 Whois Server" anchor="port43">
<t>
This data stricture, named 'port43', is a simple string containing the
fully-qualified host name of the WHOIS
<xref target="RFC3912"/> server where the containing object instance may be
found. Note that this is not a URI, as there is not Whois URI scheme.
</t>
</section>
<section title="An Example">
<figure anchor="json_example_with_notices_and_rdapConformance">
<preamble> This is an example response with both rdapConformance and notices
embedded:</preamble>
<artwork xml:space="preserve">
{
"rdapConformance" :
[
"rdap_level_0"
],
"notices" :
[
{
"title" : "Content Redacted",
"description" :
[
"Without full authorization, content has been redacted.",
"Sorry, dude!"
],
"links" :
[
{
"value" : "http://example.net/ip/192.0.2.0/24",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/redaction_policy.html"
}
]
}
],
"lang" : "en",
"startAddress" : "192.0.2.0",
"endAddress" : "192.0.2.255",
"handle" : "XXXX-RIR",
"ipVersion" : "v4",
"name": "NET-RTR-1",
"description" : [ "A network used for example documentation" ],
"parentHandle" : "YYYY-RIR",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
]
}
</artwork>
</figure>
</section>
</section>
<section title="Object Classes" anchor="object_classes">
<t>
Object classes represent structures appropriate for a response from the
queries specified in <xref target="I-D.ietf-weirds-rdap-query"></xref>.
</t>
<t>
Each object class contains a "links" array as specified in <xref target="links"></xref>.
For every object class in a response, whether the object class is directly
representing the response to a query or is embedded in other object classes,
servers SHOULD provide a link representing a URI for that object class using the
"self" relationship as specified in the IANA registry specified by <xref target="RFC5988"></xref>.
As explained in <xref target="nameserver_object_class"></xref>, this may be not
always be possible for name server data. Clients MUST be able to process object
instances without a "self" link. When present, clients MAY use the self link
for caching data. Servers MAY provide more than one "self" link for any given
object instance.
</t>
<figure>
<preamble>This is an example of the "links" array with a self link to an object class:</preamble>
<artwork xml:space="preserve">
"links" :
[
{
"value" : "http://example.com/ip/2001:db8::123",
"rel" : "self",
"href" : "http://example.com/ip/2001:db8::123"
}
]
</artwork>
</figure>
<section title="The Entity Object Class" anchor="entity_object_class">
<t> The entity object class appears throughout this document and is an appropriate
response for the /entity/XXXX query defined in <xref
target="I-D.ietf-weirds-rdap-query">Registration Data Access Protocol Lookup Format</xref>.
This object class
represents the information of organizations, corporations, governments, non-profits,
clubs, individual persons, and informal groups of people. All of these
representations are so similar that it is best to represent them in <xref
target="RFC4627">JSON</xref> with one construct, the entity object class, to aid
in the re-use of code by implementers. </t>
<t> Some of the members of the entity object class are repeated in other object classes
described later in this document. </t>
<figure>
<preamble>The entity object is served by both RIRs and DNRs.
The following is an example of an entity that might be served
by an RIR:</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"vCard" :
[
[ "version", {}, "text", "4.0" ],
[ "fn", {}, "text", "Joe Bob, Inc." ],
[ "fn", {}, "text", "Bobby Joe Shopping" ],
[ "label", {}, "text", "123 Maple Ave\n",
"Suite 90001\n",
"Vancouver\n",
"BC\n",
"1239\n" ],
[ "email", {}, "text", "joe at bob.com" ],
[ "email", {}, "text", "bob at joe.com" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ],
[ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ],
[ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ],
],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.com/entity/XXXX",
"rel" : "self",
"href" : "http://example.com/entity/XXXX"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
}
],
"asEventActor" :
[
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z"
}
]
}
</artwork>
</figure>
<t> This object has the following members:<list style="symbols">
<t>handle -- a string representing an registry unique identifier of the
entity</t>
<t>vCard -- a JSON vCard with the entity's contact information</t>
<t>roles -- an array of strings, each signifying the relationship an object
would have with its closest containing object
(see <xref target="suggested_roles"></xref> for suggested values)
</t>
<t>remarks -- see <xref target="notices_and_remarks"></xref></t>
<t>links -- see <xref target="links"/></t>
<t>events -- see <xref target="events"></xref></t>
<t>asEventActor -- this data structure takes the same form as the
'events' data structure (see <xref target="events"></xref>), but
each object in the array MUST NOT have an 'eventActor' member.
These objects denote that the entity is an event actor for the
given events. See <xref target="modeling_events"></xref>
regarding the various ways events can be modeled.</t>
<t>status -- see <xref target="status"></xref></t>
<t>port43 -- see <xref target="port43"></xref></t>
</list>
</t>
<figure>
<preamble>The following is an example of a entity that might be served by a DNR:</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"vCard" :
[
[ "version", {}, "text", "4.0" ],
[ "fn", {}, "text", "Joe Bob, Inc." ],
[ "fn", {}, "text", "Bobby Joe Shopping" ],
[ "label", {}, "text", "123 Maple Ave\n",
"Suite 90001\n",
"Vancouver\n",
"BC\n",
"1239\n" ],
[ "email", {}, "text", "joe at bob.com" ],
[ "email", {}, "text", "bob at joe.com" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ],
[ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ],
[ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ],
],
"status" : [ "validated", "locked" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.com/entity/XXXX",
"rel" : "self",
"href" : "http://example.com/entity/XXXX"
}
],
"port43" : "whois.example.net",
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z",
"eventActor" : "joe@bob.com"
}
]
}
</artwork>
</figure>
</section>
<section title="The Nameserver Object Class" anchor="nameserver_object_class">
<t> The nameserver object class represents information regarding DNS name servers
used in both forward and reverse DNS.
RIRs and some DNRs register or expose nameserver information as an attribute of a domain
name, while other DNRs model nameservers as "first class objects". </t>
<t> The nameserver object class accommodates both models and degrees of variation in
between. </t>
<figure anchor="full_nameserver_example">
<preamble>The following is an example of a nameserver object.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"ldhName" : "ns1.xn--fo-5ja.example",
"unicodeName" : "fóo.example",
"status" : [ "active" ],
"ipAddresses" :
{
"v4": [ "192.0.2.1", "192.0.2.2" ],
"v6": [ "2001:db8::123" ]
},
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/nameserver/xxxx",
"rel" : "self",
"href" : "http://example.net/nameserver/xxxx"
}
],
"port43" : "whois.example.net",
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z",
"eventActor" : "joe@bob.com"
}
]
}
</artwork>
</figure>
<t>
<xref target="full_nameserver_example"/> is an example of a nameserver object with
all values given. Registries using a first-class nameserver data model would embed
this in domain objects as well as allowing references to it with the "/nameserver"
query type (all depending on the registry operators policy). Other registries may
pare back the information as needed. <xref target="simplest_nameserver_example"/> is
an example of a nameserver object as would be found in RIRs and some DNRs, while
<xref target="near_simplest_nameserver_example"/> is an example of a nameserver
object as would be found in other DNRs. </t>
<figure anchor="simplest_nameserver_example">
<preamble>The following is an example of the simplest nameserver object:</preamble>
<artwork xml:space="preserve">
{
"ldhName" : "ns1.example.com"
}
</artwork>
</figure>
<figure anchor="near_simplest_nameserver_example">
<preamble>The following is an example of a simple nameserver object that might be
commonly used by DNRs:</preamble>
<artwork xml:space="preserve">
{
"ldhName" : "ns1.example.com",
"ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] }
}
</artwork>
</figure>
<t> The nameserver object class has the following members: <list style="symbols">
<t>handle -- a string representing an registry unique identifier of the
nameserver</t>
<t>ldhName -- a string containing the LDH name of the nameserver
(see <xref target="common_data_types"></xref>)</t>
<t>unicodeName -- a string containing a DNS unicode name of the nameserver
(see <xref target="common_data_types"></xref>)</t>
<t>ipAddresses -- an object containing the following members:
<list style="symbols">
<t>v6 -- an array of strings containing IPv6 addresses of the nameserver</t>
<t>v4 -- an array of strings containing IPv4 addresses of the nameserver</t>
</list>
</t>
<t>status - see <xref target="status"></xref></t>
<t>remarks - see <xref target="notices_and_remarks"></xref></t>
<t>links - see <xref target="links"></xref></t>
<t>port43 - see <xref target="port43"></xref></t>
<t>events - see <xref target="events"></xref></t>
</list>
</t>
</section>
<section title="The Domain Object Class" anchor="domain_object_class">
<t> The domain object class represents a DNS name and point of delegation. For RIRs
these delegation points are in the reverse DNS tree, whereas for DNRs these
delegation points are in the forward DNS tree.
</t>
<t> In both cases, the high level structure of the domain object class consists of
information about the domain registration, nameserver information related to the
domain name, and entities related to the domain name (e.g. registrant information,
contacts, etc.). </t>
<figure>
<preamble>The following is an elided example of the domain object showing the high
level structure:</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXX",
"ldhName" : "blah.example.com",
...
"nameServers" :
[
...
],
...
"entities" :
[
...
]
}
</artwork>
</figure>
<t> The following is a description of the members of this object: <list
style="symbols">
<t>handle -- a string representing a registry unique identifier of the
domain object instance</t>
<t>ldhName -- a string describing an domain name in LDH form as
described in <xref target="common_data_types"></xref></t>
<t>unicodeName -- a string containing a domain name with u-labels as
described in <xref target="common_data_types"></xref></t>
<t>variants -- an array of objects, each containing the following values:
<list style="symbols">
<t>relation -- an array of strings, with each string denoting the
relationship between the variants and the containing domain
object (see <xref target="variant_relations"></xref> for a
list of suggested variant relations).</t>
<t>variantNames -- an array of objects, with each object containing
an "ldhName" member and a "unicodeName" member
(see <xref target="common_data_types"></xref>).</t>
</list>
</t>
<t>nameservers -- an array of nameserver objects as defined by <xref
target="nameserver_object_class"/></t>
<t>delegationKeys -- an array of objects, each with the following members:
<list style="symbols">
<t>algorithm -- an integer as specified by the algorithm field of a
DNS DS record as specified by <xref target="RFC4034">RFC
4034</xref> in presentation format</t>
<t>digest -- an string as specified by the digest field of a DNS DS
record as specified by RFC 4034 in presentation format</t>
<t>digestType -- an integer as specified by the digest type field of
a DNS DS record as specified by RFC 4034 in presentation
format</t>
<t>keyTag -- an integer as specified by the key tag field of a DNS
DS record as specified by RFC 4034 in presentation format</t>
</list></t>
<t>entities -- an array of entity objects as defined by <xref
target="entity_object_class"/>.</t>
<t>status - see <xref target="status"></xref></t>
<t>remarks - see <xref target="notices_and_remarks"></xref></t>
<t>links - see <xref target="links"></xref></t>
<t>port43 - see <xref target="port43"></xref></t>
<t>events - see <xref target="events"></xref></t>
</list>
</t>
<figure>
<preamble>The following is an example of a JSON domain object representing a reverse
DNS delegation point that might be served by an RIR:</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"ldhName" : "192.in-addr.arpa",
"nameServers" :
[
{ "ldhName" : "ns1.rir.example" },
{ "ldhName" : "ns2.rir.example" }
],
"delegationKeys" :
[
{
"algorithm": 7,
"digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C",
"digestType" : 1,
"keyTag" : 53814
}
],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value": "http://example.net/domain/XXXX",
"rel" : "self",
"href" : "http://example.net/domain/XXXXX"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z",
"eventActor" : "joe@bob.com"
}
],
"entities" :
[
{
"handle" : "XXXX",
"vCard" :
[
[ "version", {}, "text", "4.0" ],
[ "fn", {}, "text", "Joe Bob, Inc." ],
[ "fn", {}, "text", "Bobby Joe Shopping" ],
[ "label", {}, "text", "123 Maple Ave\n",
"Suite 90001\n",
"Vancouver\n",
"BC\n",
"1239\n" ],
[ "email", {}, "text", "joe at bob.com" ],
[ "email", {}, "text", "bob at joe.com" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ],
[ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ],
[ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ],
],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value": "http://example.net/entity/xxxx",
"rel" : "self",
"href" : "http://example.net/entity/xxxx"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z",
"eventActor" : "joe@bob.com"
}
]
}
]
}
</artwork>
</figure>
<figure>
<preamble>The following is an example of a JSON domain object representing a forward
DNS delegation point that might be served by a DNR:</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"ldhName" : "xn--fo-5ja.example",
"unicodeName" : "fóo.example",
"variants" :
[
{
"relation" : [ "registered", "conjoined" ],
"variantNames" :
[
{
"ldhName" : "xn--fo-cka.example",
"unicodeName" : "fõo.example"
},
{
"ldhName" : "xn--fo-fka.example",
"unicodeName" : "föo.example"
}
]
},
{
"relation" : [ "unregistered", "restricted registration" ],
"variantNames" :
[
{
"ldhName": "xn--fo-8ja.example",
"unicodeName" : "fôo.example"
}
]
}
],
"status" : [ "locked", "transferProhibited" ],
"nameServers" :
[
{
"handle" : "XXXX",
"ldhName" : "ns1.example.com",
"status" : [ "active" ],
"ipAddresses" :
{
"v6": [ "2001:db8::123", "2001:db8::124" ],
"v4": [ "192.0.2.1", "192.0.2.2" ]
},
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/nameserver/XXXX",
"rel" : "self",
"href" : "http://example.net/nameserver/XXXX"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z"
}
]
},
{
"handle" : "XXXX",
"ldhName" : "ns2.example.com",
"status" : [ "active" ],
"ipAddresses" :
{
"v6" : [ "2001:db8::125", "2001:db8::126" ],
"v4" : [ "192.0.2.3", "192.0.2.4" ]
},
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/nameserver/XXXX",
"rel" : "self",
"href" : "http://example.net/nameserver/XXXX"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z"
}
]
}
],
"delegationKeys" :
[
{
"algorithm": 7,
"digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C",
"digestType" : 1,
"keyTag" : 53814
}
],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value": "http://example.net/domain/XXXX",
"rel" : "self",
"href" : "http://example.net/domain/XXXX"
}
],
"port43" : "whois.example.net",
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z",
"eventActor" : "joe@bob.com"
},
{
"eventAction" : "transfer",
"eventDate" : "1991-12-31T23:59:60Z",
"eventActor" : "joe@bob.com"
},
{
"eventAction" : "expiration",
"eventDate" : "2016-12-31T23:59:60Z",
"eventActor" : "joe@bob.com"
}
],
"entities" :
[
{
"handle" : "XXXX",
"vCard" :
[
[ "version", {}, "text", "4.0" ],
[ "fn", {}, "text", "Joe Bob, Inc." ],
[ "fn", {}, "text", "Bobby Joe Shopping" ],
[ "label", {}, "text", "123 Maple Ave\n",
"Suite 90001\n",
"Vancouver\n",
"BC\n",
"1239\n" ],
[ "email", {}, "text", "joe at bob.com" ],
[ "email", {}, "text", "bob at joe.com" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ],
[ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ],
[ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ],
],
"status" : [ "validated", "locked" ],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/entity/xxxx",
"rel" : "self",
"href" : "http://example.net/entity/xxxx"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z"
}
]
}
]
}
</artwork>
</figure>
</section>
<section title="The IP Network Object Class" anchor="ip_network_object_class">
<t> The IP Network object class models IP network registrations found in RIRs and is the
expected response for the "/ip" query as defined by <xref
target="I-D.ietf-weirds-rdap-query"/>. There is no equivalent object class for
DNRs. The high level structure of the IP network object class consists of
information about the network registration and entities related to the IP network
(e.g. registrant information, contacts, etc...). </t>
<figure>
<preamble>The following is an elided example of the IP network object type showing
the high level structure:</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXX",
...
"entities" :
[
...
]
}
</artwork>
</figure>
<figure>
<preamble>The following is an example of the JSON object for the network
registration information</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX-RIR",
"startAddress" : "2001:db8::0",
"endAddress" : "2001:db8::0:FFFF:FFFF:FFFF:FFFF:FFFF",
"ipVersion" : "v6",
"name": "NET-RTR-1",
"description" : [ "A network used for routing" ],
"type" : "DIRECT ALLOCATION",
"country" : "AU",
"parentHandle" : "YYYY-RIR",
"status" : [ "allocated" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.ent/ip/2001:db8::/48",
"rel" : "self",
"href" : "http://example.net/ip/2001:db8::/48"
},
{
"value" : "http://example.net/ip/2001:db8::/48",
"rel" : "up",
"href" : "http://example.net/ip/2001:C00::/23"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z"
}
],
"entities" :
[
{
"handle" : "XXXX",
"vCard" :
[
[ "version", {}, "text", "4.0" ],
[ "fn", {}, "text", "Joe Bob, Inc." ],
[ "fn", {}, "text", "Bobby Joe Shopping" ],
[ "label", {}, "text", "123 Maple Ave\n",
"Suite 90001\n",
"Vancouver\n",
"BC\n",
"1239\n" ],
[ "email", {}, "text", "joe at bob.com" ],
[ "email", {}, "text", "bob at joe.com" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ],
[ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ],
[ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ],
],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/entity/xxxx",
"rel" : "self",
"href" : "http://example.net/entity/xxxx"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z"
}
]
}
]
}
</artwork>
</figure>
<t> The following is a description of the members of this object: <list style="symbols">
<t>handle -- a string representing an RIR unique identifier of the network
registration</t>
<t>startAddress -- the starting IP address of the network, either IPv4 or
IPv6</t>
<t>endAddress -- the ending IP address of the network, either IPv4 or IPv6</t>
<t>ipVersion -- an string signifying the IP protocol version of the network: "v4"
signifying an IPv4 network, "v6" signifying an IPv6 network</t>
<t>name -- an identifier assigned to the network registration by the
registration holder</t>
<t>description -- an array of strings containing descriptive text about the
network registration</t>
<t>type -- a string containing an RIR-specific classification of the network</t>
<t>country -- a string containing the name of the 2 character country code of
the network </t>
<t>parentHandle -- a string containing an RIR-unique identifier of the parent
network of this network registration</t>
<t>status -- an array of strings indicating the state of the IP network</t>
<t>entities -- an array of entity objects as defined by <xref
target="entity_object_class"/>.</t>
<t>remarks - see <xref target="notices_and_remarks"></xref></t>
<t>links - see <xref target="links"></xref></t>
<t>events - see <xref target="events"></xref></t>
</list>
</t>
</section>
<section title="Autonomous System Number Entity Object Class"
anchor="as_entity_object_class">
<t> 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 <xref target="I-D.ietf-weirds-rdap-query"/>. 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 entity object class.</t>
<figure>
<preamble>The following is an example of a JSON object representing an
autnum.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX-RIR",
"startAutnum" : "10",
"endAutnum" : "15",
"name": "AS-RTR-1",
"description" : [ "AS for Exchange" ],
"type" : "DIRECT ALLOCATION",
"country": "AU",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/autnum/xxxx",
"rel" : "self",
"href" : "http://example.net/autnum/xxxx"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z"
}
],
"entities" :
[
{
"handle" : "XXXX",
"vCard" :
[
[ "version", {}, "text", "4.0" ],
[ "fn", {}, "text", "Joe Bob, Inc." ],
[ "fn", {}, "text", "Bobby Joe Shopping" ],
[ "label", {}, "text", "123 Maple Ave\n",
"Suite 90001\n",
"Vancouver\n",
"BC\n",
"1239\n" ],
[ "email", {}, "text", "joe at bob.com" ],
[ "email", {}, "text", "bob at joe.com" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ],
[ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ],
[ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ],
],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/entity/XXXX",
"rel" : "self",
"href" : "http://example.net/entity/XXXX"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z"
}
]
}
]
}
</artwork>
</figure>
<t> The following is a description of the members of this object: <list style="symbols">
<t>handle -- a string representing an RIR-unique identifier of the autnum
registration</t>
<t>startAutnum -- the <xref target="RFC5396">starting number</xref> in the block
of autonomous system numbers</t>
<t>endAutnum -- the <xref target="RFC5396">ending number</xref> in the block of
autonomous system numbers</t>
<t>name -- an identifier assigned to the autnum registration by the registration
holder</t>
<t>description -- an array of strings containing descriptive text about the
autnum registration</t>
<t>type -- a string containing an RIR-specific classification of the autnum</t>
<t>country -- a string containing the name of the 2 character country code of
the autnum </t>
<t>remarks - see <xref target="notices_and_remarks"></xref></t>
<t>links - see <xref target="links"></xref></t>
<t>events - see <xref target="events"></xref></t>
</list></t>
</section>
</section>
<section title="Error Response Body" anchor="error_body">
<t> Some non-answer responses may return entity bodies with information that could be
more descriptive. </t>
<t> 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"
followed by an array of strings named "description". </t>
<figure anchor="json_error">
<preamble>This is an example of the JSON version of the common response
body:</preamble>
<artwork xml:space="preserve">
{
"errorCode": 418,
"title": "Your beverage choice is not available",
"description":
[
"I know coffee has more ummppphhh.",
"But I cannot provide."
]
}
</artwork>
</figure>
<t> A client MAY simply use the HTTP response code as the server is not required to
include error data in the response body. However, if a client wishes to parse the
error data, it SHOULD first check that the Content-Type header contains the
appropriate media type. </t>
</section>
<section title="IANA Considerations" anchor="iana_considerations">
<t>
None.
</t>
</section>
<section title="Security Considerations" anchor="security_considerations">
<t>
This specification models information serialized in JSON format.
As JSON is a subset of Javascript, implementations are advised to
follow the security considerations outlined in Section 6 of <xref target="RFC4627"></xref>
to prevent code injection.
</t>
</section>
<section title="Internationalization Considerations"
anchor="internationalization_considerations">
<section title="Character Encoding">
<t> The default text encoding for JSON and XML responses in RDAP is UTF-8, and all
servers and clients MUST support UTF-8. Servers and clients MAY optionally
support other character encodings. </t>
</section>
<section title="URIs and IRIs">
<t>
<xref target="I-D.ietf-weirds-using-http"/> defines the use of URIs and IRIs in
RDAP. </t>
</section>
<section title="Language Tags">
<t>
<xref target="language_identifier"/> defines the use of language tags in the
JSON responses defined in this document. </t>
</section>
<section title="Internationalized Domain Names">
<t>
Internationalized Domain Names (IDNs) are denoted in this specification by
the separation of DNS names in LDH form and Unicode form (see <xref target="common_data_types"></xref>).
Representation of IDNs in registries is described by the "variants" object in
<xref target="domain_object_class"></xref> and the suggested values
listed in <xref target="variant_relations"></xref>.
</t>
</section>
</section>
<section title="Privacy Considerations" anchor="privacy_considerations">
<t>
This specification suggests status values to denote contact and registrant
information that has been marked as private and/or has been redacted or
obscured. See <xref target="suggested_status"></xref> for the list of
status values. See <xref target="suggested_registrant_contact_modeling"></xref>
on guidance to apply those values to contacts and registrants.
</t>
</section>
<section title="Contributing Authors and Acknowledgements">
<t> 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 word on DNR
responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean Shen. </t>
<t> The components of the DNR object classes are derived from a categorization of WHOIS
response formats created by Ning Kong, Linlin Zhou, and Guangqing Deng,
Steve Sheng and Francisco Arias, Ray Bellis, and Frederico Neves. </t>
<t>
Ed Lewis contributed significant review comments and provided
clarifying text. James Mitchel 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.
</t>
<t>
The switch to and incorporation of JSON vCard was performed by Simon Perreault.
</t>
</section>
</middle>
<back>
<references title="Normative References"> &RFC0791; &RFC1166; &RFC2616; &RFC3339; &RFC3986;
&RFC4034; &RFC4343; &RFC4627; &RFC5322; &RFC5396; &RFC5646; &RFC5890; &RFC5952; &RFC5988;
&I-D.draft-kewisch-vcard-in-json-01;
<reference anchor="ISO.3166.1988">
<front>
<title>Codes for the representation of names of countries, 3rd edition</title>
<author>
<organization>International Organization for Standardization</organization>
</author>
<date day="15" month="August" year="1988"/>
</front>
<seriesInfo name="ISO" value="Standard 3166"/>
</reference>
<reference anchor="I-D.ietf-weirds-rdap-query">
<front>
<title>RDAP Query Format</title>
<author initials="A" surname="Newton" fullname="Andrew Newton">
<organization/>
</author>
<author initials="S." surname="Hollenbeck" fullname="Scott Hollenbeck"> </author>
<date month="September" day="21" year="2011"/>
<abstract>
<t>This document describes uniform patterns to construct HTTP URLs that may
be used to retrieve registration information from registries (including
both Regional Internet Registries (RIRs) and Domain Name Registries
(DNRs)) using "RESTful" web access patterns.</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-weirds-rdap-query-00"/>
<format type="TXT"
target="http://www.ietf.org/internet-drafts/draft-weirds-rdap-query-00.txt"/>
</reference>
<reference anchor="I-D.ietf-weirds-using-http">
<front>
<title>Using HTTP for RESTful Whois Services by Internet Registries</title>
<author initials="A" surname="Newton" fullname="Andrew Newton">
<organization/>
</author>
<author initials="B" surname="Ellacott" fullname="Byron Ellacott">
<organization/>
</author>
<author initials="N" surname="Kong" fullname="Ning Kong">
<organization/>
</author>
<date month="May" day="10" year="2012"/>
<abstract>
<t>This document describes the use of HTTP in Whois services using RESTful
web methodologies.</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-weirds-using-http-01"/>
<format type="TXT"
target="http://www.ietf.org/internet-drafts/draft-ietf-weirds-using-http-01.txt"
/>
</reference>
</references>
<references title="Informative References"> &RFC3912; &RFC3730; <reference
anchor="JSON_acendancy">
<front>
<title>The Stealthy Ascendancy of JSON</title>
<author surname="MacVittie" fullname="Lori MacVittie">
<organization>F5 Dev Central</organization>
</author>
<date month="04" year="2011"/>
</front>
<format type="HTML"
target="https://devcentral.f5.com/weblogs/macvittie/archive/2011/04/27/the-stealthy-ascendancy-of-json.aspx"
/>
</reference>
<reference anchor="JSON_performance_study">
<front>
<title>Comparison of JSON and XML Data Interchange Formats: A Case Study</title>
<author fullname="Nurzhan Nurseitov">
<organization>Montana State University - Bozeman</organization>
</author>
<author fullname="Michael Paulson">
<organization>Montana State University - Bozeman</organization>
</author>
<author fullname="Randall Reynolds">
<organization>Montana State University - Bozeman</organization>
</author>
<author fullname="Clemente Izurieta">
<organization>Montana State University - Bozeman</organization>
</author>
<date year="2009"/>
</front>
<format type="PDF" target="http://www.cs.montana.edu/izurieta/pubs/caine2009.pdf"/>
</reference>
</references>
<section title="Suggested Values">
<t> Due to the wide variation between the hundreds of registry operators and the
on-going policy refinement by registry communities, values of some data cannot be
formally standardized. This section lists suggested values for such data but is not
nor will ever be a complete list of values and their meanings. </t>
<section title="Status" anchor="suggested_status">
<t> Many of the object classes have a member named 'status'. This member is an array
of strings, with each string denoting a status associated with the containing
object. The following is a list of suggested values to use in the 'status'
array: <list style="symbols">
<t>'validated' -- Signifies that the data of the object instance has been
found to be accurate. This type of status is usually found on entity
object instances to note the validity of identifying contact
information.</t>
<t>'update prohibited' -- Updates to the object instance are forbidden.</t>
<t>'transfer prohibited' -- Transfers of the registration from one registrar
to another are forbidden. This type of status normally applies to DNR
domain names.</t>
<t>'delete prohibited' -- Deletion of the registration of the object
instance is forbidden. This type of status normally applies to DNR
domain names.</t>
<t>'proxy' -- The registration of the object instance has been performed
by a third party. This is most commonly applied to entities.</t>
<t>'private' -- The information of the object instance is not designated
for public consumption. This is most commonly applied to entities.</t>
<t>'redacted' -- Some of the information of the object instance has not
been made available. This is most commonly applied to entities.</t>
<t>'obscured' -- Some of the information of the object instance has been
altered for the purposes of not readily revealing the actual information
of the object instance. This is most commonly applied to entities.</t>
</list>
</t>
</section>
<section title="Event Actions" anchor="suggested_event_actions">
<t>
<xref target="events"></xref> describes a data structure for denoting events
against object classes. Each event can have an event action, which is a string.
The following is a list of suggested values to use for event actions:
<list style="symbols">
<t>'registration' -- the object instance was initially registered</t>
<t>'reregistration' -- the object instance was registered subsequently to initial registration</t>
<t>'last changed' -- when the information in the object instance was last changed</t>
<t>'expiration' -- the object instance has been removed or will be removed at a pre-determined
date and time from the registry</t>
<t>'deletion' -- the object instance was removed from the registry at a point in time that was not pre-determined</t>
<t>'reinstantation' -- the object instance was reregistered after having been
removed from the registry</t>
<t>'transfer' -- the object instance was transfered from one registrant to another</t>
</list>
</t>
</section>
<section title="Roles" anchor="suggested_roles">
<t> Entity object classes have a member named 'roles'. This member is an array of
strings, with each string indicating the role or relationship the entity object
instance has with a containing object, such as a domain name or IP network. An
entity object instance can have more than one type of relationship with a
containing object. The following is a list of suggested values to use in the
'roles' array: <list style="symbols">
<t>'registrant' -- The entity object instance is the registrant of the
registration.</t>
<t>'tech' -- The entity object instance is a technical contact for the
registration.</t>
<t>'admin' -- The entity object instance is an administrative contact for
the registration.</t>
<t>'abuse' -- The entity object instance handles network abuse issues on
behalf of the registrant of the registration.</t>
<t>'billing' -- The entity object instance handles payment and billing
issues on behalf of the registrant of the registration.</t>
<t>'registrar' -- The entity object instance represents the authority
responsible for the registration in the registry.</t>
<t>'reseller' -- The entity object instance represents a third party
through which the registration was conducted (i.e. not the registry or registrar).</t>
<t>'sponsor' -- The entity object instance represents a domain policy
sponsor, such as an ICANN approved sponsor</t>
</list>
</t>
</section>
<section title="Variant Relations" anchor="variant_relations">
<t>
<xref target="domain_object_class"/> describes a structure for noting
variants of domain names and the relationship those variants have with a
registered domain name. The following is a list of suggested values to use as
the variant relation values: <list style="symbols">
<t>'registered' -- the variant names are registered in the registry.</t>
<t>'unregistered' -- the variant names are not found in the registry.</t>
<t>'restricted registration' -- registration of the variant names is
restricted to certain parties or within certain rules.</t>
<t>'open registration' -- registration of the variant names is available to
generally qualified registrants.</t>
<t>'conjoined' -- registration of the variant names is occurs automatically with the
registration of the containing domain registration.</t>
</list>
</t>
</section>
</section>
<section title="Suggested Data Modeling with the Entity Object Class">
<section title="Registrants and Contacts" anchor="suggested_registrant_contact_modeling">
<t> 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 <xref
target="suggested_roles"/> be used. </t>
<figure>
<preamble>The following is an example of an elided containing object with an
embedded entity that is both a registrant and admin contact:</preamble>
<artwork xml:space="preserve">
{
...
"entities" :
[
{
"handle" : "XXXX",
"vCard" :
[
[ "version", {}, "text", "4.0" ],
[ "fn", {}, "text", "Joe Bob, Inc." ],
[ "fn", {}, "text", "Bobby Joe Shopping" ],
[ "label", {}, "text", "123 Maple Ave\n",
"Suite 90001\n",
"Vancouver\n",
"BC\n",
"1239\n" ],
[ "email", {}, "text", "joe at bob.com" ],
[ "email", {}, "text", "bob at joe.com" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ],
[ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ],
[ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ],
],
"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"
}
]
}
]
}
</artwork>
</figure>
<t>
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 <xref target="suggested_status"></xref>).
</t>
<figure>
<preamble>The following is an elided example of a registrant with information
changed to reflect that of a third party.</preamble>
<artwork xml:space="preserve">
{
...
"entities" :
[
{
"handle" : "XXXX",
...
"roles" : [ "registrant", "admin" ],
"status" : [ "proxy", "private", "obscured" ]
}
]
}
</artwork>
</figure>
</section>
<section title="Registrars">
<t> This document does not provide a specific object class for registrars, but like
registrants and contacts (see <xref
target="suggested_registrant_contact_modeling"/>) the 'roles' string array
maybe used. </t>
<figure>
<preamble>The following is an example of an elided containing object with an
embedded entity that is a registrar:</preamble>
<artwork xml:space="preserve">
{
...
"entities" :
[
{
"handle" : "XXXX",
"vCard" :
[
[ "version", {}, "text", "4.0" ],
[ "fn", {}, "text", "RegistrarsRUS" ],
[ "label", {}, "text", "1212 Tulip Ave\n",
"Suite 1\n",
"Marina Del Rey\n",
"CA\n",
"12393-2193" ],
[ "email", {}, "text", "joe at bob.com" ],
[ "email", {}, "text", "bob at joe.com" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ],
[ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ],
[ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ],
[ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ],
],
"roles" : [ "registrar" ],
"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"
}
]
}
]
}
</artwork>
</figure>
</section>
</section>
<section title="Modeling Events" anchor="modeling_events">
<t>
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.
</t>
<t>
Events can be modeled in three ways:
<list style="numbers">
<t>events with no designated actor</t>
<t>events where the actor is only designated by an identifier</t>
<t>events where the actor can be modeled as an entity</t>
</list>
</t>
<t>
For the first use case, the 'events' data structure (<xref target="events"></xref>)
is used without the 'eventActor' object member.
</t>
<figure anchor="event_example_without_actor">
<preamble>This is an example of an "events" array without the 'eventActor'.</preamble>
<artwork xml:space="preserve">
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z"
}
]
</artwork>
</figure>
<t>
For the second use case, the 'events' data structure (<xref target="events"></xref>)
is used with the 'eventActor' object member.
</t>
<figure anchor="event_example_with_actor">
<preamble>This is an example of an "events" array with the 'eventActor'.</preamble>
<artwork xml:space="preserve">
"events" :
[
{
"eventAction" : "registration",
"eventActor" : "XYZ-NIC",
"eventDate" : "1990-12-31T23:59:60Z"
}
]
</artwork>
</figure>
<t>
For the third use case, the 'asEventActor' array is used when an entity
(<xref target="entity_object_class"></xref>) is embedded into another
object class. The 'asEventActor' array follows the same structure as the
'events' array but does not have 'eventActor' attributes.
</t>
<figure>
<preamble>The following is an elided example of a domain object with
an entity as an event actor.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"ldhName" : "foo.example",
"status" : [ "locked", "transfer Prohibited" ],
...
"entities" :
[
{
"handle" : "XXXX",
...
"asEventActor" :
[
{
"eventAction" : "last changed",
"eventDate" : "1990-12-31T23:59:60Z"
}
]
}
]
}
</artwork>
</figure>
</section>
<section title="Motivations for Using JSON">
<t> This section addresses a common question regarding the use of JSON over other data
formats, most notably XML. </t>
<t> It is often pointed out that many DNRs and one RIR support the <xref
target="RFC3730">EPP</xref> 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. </t>
<t> 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. </t>
<t> 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. </t>
<t> 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 <xref target="JSON_acendancy"/>). Studies have also found that JSON is
generally less bulky and consequently faster to parse (see <xref
target="JSON_performance_study"/>). </t>
</section>
<section title="Changelog">
<t>
<list style="hanging">
<t hangText="Initial -00"> Adopted as working group document 2012-September-18. </t>
<t hangText="-01">
<list>
<t>Minor spelling corrections. Changed "Registry Data" to "Registration
Data" for the sake of consistency.</t>
<t>Transitioned to RFC 5988 links and relationship types from our own
custom "uris" structure.</t>
<t>Some examples had 'status' as a string. Those have been corrected as
'status' is always an array of strings.</t>
<t>Domain variants can now have a multi-valued relationship with domain
registrations.</t>
<t>"names" in the entity object class was changed to "entityNames".</t>
<t>Some IP address examples change to IPv6.</t>
<t>Change phone number examples and added reference to E.164.</t>
<t>Added section on motivations for using JSON.</t>
<t>Added error response body section.</t>
<t>Added JSON naming section.</t>
<t>Added common data structures section.</t>
<t>Added the IANA Considerations section and the media type
registration.</t>
<t>Added 'lang' name/value.</t>
<t>Added internationalization considerations section.</t>
</list>
</t>
<t hangText="-02">
<list>
<t>Removed level from media type registration.</t>
<t>Textual changes as given by Ed Lewis.</t>
<t>Fixed object class linking example noted by Francisco Obispo</t>
<t>Fixed a lot of other examples called out by Alex Sergeyev</t>
<t>Added a note that JSON names are case sensitive</t>
<t>Added 'status' to IP networks as suggested by Alex Sergeyev</t>
</list>
</t>
<t hangText="-03">
<list>
<t>Added jCard verbiage and examples and deleted overlapping contact information
and the appendix on postal addresses</t>
<t>Removed the IANA considerations as they have been moved to another document</t>
<t>Changed the remarks structure to be like notices</t>
<t>Reordering and rewording some of the sections so they flow better</t>
<t>Added note about object class "self" links</t>
<t>Changed ipAddresses in nameserver object class to separate out v6 from v4</t>
<t>Changed IP network version identifier from integer to string to be more consistent with ipAddresses
identifier in nameserver object classes</t>
<t>Changed DNS names to LDH names and Unicode names</t>
<t>Modified the definition of 'conjoined' variant relationship so it was circular</t>
<t>Added 'proxy', 'private', 'redacted', and 'obscured' status values (most useful for entities).</t>
<t>Added a privacy considerations section</t>
<t>Added a security considerations section</t>
<t>Added 'reseller' and 'sponsor' to the list of entity roles</t>
<t>Added the 'events' common data structure</t>
<t>Added 'asEventActor' to entities</t>
<t>Added appendix on event modeling</t>
<t>Removed the subclasses/superclassing between RIRs/DNRs for entity and domain object classes</t>
<t>Change suggested status/relation/etc values to be case/spacing consistent</t>
<t>Normalized some of the definitions of object class members</t>
<t>Modifying the JSON signaling section to reference the guidance in draft-ietf-weirds-using-http</t>
<t>Changed the text regarding the process of unknown JSON attributes</t>
</list>
<!-- TO DO
8. update acknowledgements
9. spell check
-->
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 16:20:50 |