One document matched: draft-ietf-weirds-json-response-04.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 RFC3629 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.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 RFC5910 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5910.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 RFC6530 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6530.xml'>
<!ENTITY I-D.draft-kewisch-vcard-in-json PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.kewisch-vcard-in-json.xml'>
<!ENTITY I-D.ietf-weirds-rdap-query PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-weirds-rdap-query.xml'>
<!ENTITY I-D.ietf-weirds-using-http PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-weirds-using-http.xml'>
]>
<?rfc toc="yes"?>
<rfc category="std" docName="draft-ietf-weirds-json-response-04" 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, all of which are
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 where 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 used commonly in object classes.</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="event_action_registrations"></xref> for a list of
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="status_registrations"></xref> for a list of values).</t>
</section>
<section title="Port 43 Whois Server" anchor="port43">
<t>
This data structure, 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 no WHOIS URI scheme.
</t>
</section>
<section title="Public IDs" anchor="public_ids">
<t>
This data structure maps a public identifier to an object class.
It is named 'publicIds' and is an array of objects, with each object containing the
following members:
<list style="symbols">
<t>type - a string denoting the type of public identifier</t>
<t>identifier - a public identifier of the type denoted by 'type'</t>
</list>
</t>
<figure anchor="publicids_example">
<preamble>The following is an example of a 'publicIds' structure.</preamble>
<artwork xml:space="preserve">
"publicIds":
[
{
"type":"IANA Registrar ID",
"identifier":"1"
}
]
</artwork>
</figure>
</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",
"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>
<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. For illustrative purposes, it does not include rdapConformance or notices
data structures.</preamble>
<artwork xml:space="preserve">
{
"handle":"XXXX",
"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"
]
],
["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-4321"
],
["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"]
]
],
"roles":[ "registrar" ],
"publicIds":[
{
"type":"IANA Registrar ID",
"identifier":"1"
}
],
"remarks":[
{
"description":[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links":[
{
"value":"http://example.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>
Entities may also have other entities embedded with them in an array. This can be used
to model an organization with specific individuals fulfilling designated roles of responsibility.
</t>
<figure anchor="entity_with_entities_example">
<preamble>The following is an elided example of an entity with embedded entities.</preamble>
<artwork xml:space="preserve">
{
"handle" : "ANENTITY",
"roles" : [ "registrar" ],
...
"entities" :
[
{
"handle": "ANEMBEDDEDENTITY",
"roles" : [ "technical" ],
...
},
...
],
...
}
</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>vcardArray -- 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="role_registrations"></xref> for a list of values)
</t>
<t>publicIds - see <xref target="public_ids"></xref></t>
<t>entities - an array of entity objects as defined by this section.</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.
For illustrative purposes, it does not include rdapConformance or notices
data structures.</preamble>
<artwork xml:space="preserve">
{
"handle":"XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
],
]
],
"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@example.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. For illustrative purposes, it does not include rdapConformance or notices
data structures.</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@example.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>
As nameservers can be modeled by some registries to be first-class objects,
they may also have an array of <xref target="entity_object_class">entities</xref>
embedded to signify parties responsible for the maintenance, registrations, etc.
of the nameservers.
</t>
<figure anchor="nameserver_with_entities_example">
<preamble>The following is an elided example of a nameserver with embedded entities.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"ldhName" : "ns1.xn--fo-5ja.example",
...
"entities" :
[
...
],
...
}
</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>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>
</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 a 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>idnTable -- the name of the IDN table of codepoints, such as
one listed with the IANA (see <eref target="http://www.iana.org/domains/idn-tables">IDN tables</eref>).</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>
secureDNS -- an object with the following members:
<list style="symbols">
<t>zoneSigned -- boolean true if the zone has been signed, false otherwise.</t>
<t>delegationSigned -- boolean true if there are DS records in the
parent, false otherwise.</t>
<t>maxSigLife -- an integer representing the signature life time in seconds to be used when creating
the RRSIG DS record in the parent zone <xref target="RFC5910"></xref>.</t>
<t>dsData - an array of objects, each with the following members:
<list style="symbols">
<t>keyTag -- an integer as specified by the key tag field of a DNS
DS record as specified by RFC 4034 <xref target="RFC4034">RFC 4034</xref> in presentation format</t>
<t>algorithm -- an integer as specified by the algorithm field of a
DNS DS record as specified by RFC 4034 in presentation format</t>
<t>digest -- a 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>events - see <xref target="events"></xref></t>
</list></t>
<t>keyData - an array of objects, each with the following members:
<list style="symbols">
<t>flags -- a string representing the flags field value in the <xref target="RFC4034">DNSKEY record</xref>
in presentation format.</t>
<t>protocol - a string representation of the protocol field value of the
<xref target="RFC4034">DNSKEY record</xref> in presentation format.</t>
<t>publicKey - a string representation of the public key in the <xref target="RFC4034">DNSKEY record</xref>
in presentation format.</t>
<t>algorithm -- an integer as specified by the algorithm field of a
DNSKEY record as specified by <xref target="RFC4034">RFC 4034</xref> in presentation format</t>
<t>events - see <xref target="events"></xref></t>
</list>
</t>
</list>
See <xref target="secure_dns"></xref> for background information on these objects.
</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>publicIds - see <xref target="public_ids"></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. For illustrative purposes, it does not include rdapConformance or notices
data structures.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"ldhName" : "192.in-addr.arpa",
"nameServers" :
[
{ "ldhName" : "ns1.rir.example" },
{ "ldhName" : "ns2.rir.example" }
],
"secureDNS":
{
"delegationSigned": true,
"dsData":
[
{
"keyTag": 12345,
"algorithm": 3,
"digestType": 1,
"digest": "49FD46E6C4B45C55D4AC",
}
]
},
"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@example.com"
}
],
"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",
[
"",
"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" ],
"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@example.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. For illustrative purposes, it does not include rdapConformance or notices
data structures.</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" ],
"idnTable": ".EXAMPLE Swedish",
"variantNames" :
[
{
"ldhName": "xn--fo-8ja.example",
"unicodeName" : "fôo.example"
}
]
}
],
"status" : [ "locked", "transferProhibited" ],
"publicIds":[
{
"type":"ENS_Auth ID",
"identifier":"1234567890"
}
],
"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"
}
]
}
],
"secureDNS":
[
"zoneSigned": true,
"delegationSigned": true,
"maxSigLife": 604800,
"keyData":
[
{
"flags": 257,
"protocol": 3,
"algorithm": 1,
"publicKey": "AQPJ////4Q==",
"events":
[
{
"eventAction": "last changed",
"eventDate": "2012-07-23T05:15:47Z"
}
]
}
]
],
"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@example.com"
},
{
"eventAction" : "transfer",
"eventDate" : "1991-12-31T23:59:60Z",
"eventActor" : "joe@example.com"
},
{
"eventAction" : "expiration",
"eventDate" : "2016-12-31T23:59:60Z",
"eventActor" : "joe@example.com"
}
],
"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",
[
"",
"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"
],
]
],
"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. For illustrative purposes, it does not include rdapConformance or notices
data structures.</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",
"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",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
],
]
],
"roles" : [ "registrant" ],
"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 -- a 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>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. For illustrative purposes, it does not include rdapConformance or notices
data structures.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX-RIR",
"startAutnum" : 10,
"endAutnum" : 15,
"name": "AS-RTR-1",
"type" : "DIRECT ALLOCATION",
"status" : [ "allocated" ],
"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",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
],
]
],
"roles" : [ "registrant" ],
"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 -- a number representing the <xref target="RFC5396">starting number</xref> in the block
of autonomous system numbers</t>
<t>endAutnum -- a number representing 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>type -- a string containing an RIR-specific classification of the autnum</t>
<t>status -- an array of strings indicating the state 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 common response
body. For illustrative purposes, it does not include rdapConformance or notices
data structures.</preamble>
<artwork xml:space="preserve">
{
"errorCode": 418,
"title": "Your beverage choice is not available",
"description":
[
"I know coffee has more ummppphhh.",
"Sorry, dude!"
]
}
</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>
<figure anchor="json_error_full">
<preamble>This is an example of the common response
body with and rdapConformance and notices data structures:</preamble>
<artwork xml:space="preserve">
{
"rdapConformance" :
[
"rdap_level_0"
],
"notices" :
[
{
"title" : "Beverage policy",
"description" :
[
"Beverages with caffeine for keeping horses awake."
],
"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",
"errorCode": 418,
"title": "Your beverage choice is not available",
"description":
[
"I know coffee has more ummppphhh.",
"Sorry, dude!"
]
}
</artwork>
</figure>
</section>
<section title="Responding to Help Queries">
<t>
The appropriate response to /help queries as defined by <xref target="I-D.ietf-weirds-rdap-query"/>
is to use the notices structure as defined in <xref target="notices_and_remarks"></xref>.
</t>
<figure anchor="help_full_example">
<preamble>This is an example of a response to a /help query including the rdapConformance data structure.</preamble>
<artwork xml:space="preserve">
{
"rdapConformance" :
[
"rdap_level_0"
],
"notices" :
[
{
"title" : "Authentication Policy",
"description" :
[
"Access to sensitive data for users with proper credentials."
],
"links" :
[
{
"value" : "http://example.net/help",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/auth_policy.html"
}
]
}
]
}
</artwork>
</figure>
</section>
<section title="IANA Considerations" anchor="iana_considerations">
<t>
This section requests that the IANA establish an RDAP JSON Values Registry
for use in the <xref target="status">status</xref>, <xref target="entity_object_class">role</xref>,
<xref target="events">event action</xref>, and <xref target="domain_object_class">domain variant relation</xref>
fields specified in RDAP.
</t>
<t>
Each entry in the registry should contain the following fields:
<list style="numbers">
<t>Value - the string value being registered.</t>
<t>Type - the type of value being registered. It should be one of the following:
<list style="symbols">
<t>'status' - denotes a value for the 'status' object member as defined by <xref target="status"></xref>.</t>
<t>'role' - denotes a value for the 'role' array as defined in <xref target="entity_object_class"></xref>.</t>
<t>'event action' - denotes a value for an event action as defined in <xref target="events"></xref>.</t>
<t>'domain variant relation' - denotes a relationship between a domain and a domain variant as
defined in <xref target="domain_object_class"></xref>.</t>
</list>
</t>
<t>Description - a one or two sentence description regarding the meaning of the value, how it might be used, and/or
how it should be interpreted by clients.</t>
<t>Registrant Name - the name of the person registering the value.</t>
<t>Registrant Contact Information - an email address, postal address, or some other information to be used
to contact the registrant.</t>
</list>
</t>
<t>
This registry should be governed by a designated expert or multiple designated experts. Registration of values into
this registry should be accomplished by providing the information above to the designated expert(s).
</t>
<t>
Review of registrations into this registry by the designated expert(s) should be narrowly judged on the following
criteria:
<list style="numbers">
<t>
Values in need of being placed into multiple types must be assigned a separate registration
for each type.
</t>
<t>Values must be strings. They can be multiple words separated by single space characters. Every character
should be lowercased. If possible, every word should be given in English and each character should be US ASCII.</t>
<t>
Registrations should not duplicate the meaning of any existing registration. That is, if a request for
a registration is significantly similar in nature to an existing registration, the request should be denied.
For example, the terms 'maintainer' and 'registrant' are significantly similar in nature as they both
denote a holder of a domain name or Internet number resource. In cases where it may be reasonably argued
that machine interpretation of two similar values may alter the operation of client software, designated experts
should not judge the values to be of significant similarity.
</t>
<t>
Registrations should be relevant to the common usages of RDAP. Designated experts may rely upon the serving
of the value by a DNR or RIR to make this determination.
</t>
</list>
</t>
<section title="Status" anchor="status_registrations">
<t>This section registers the following values into the RDAP JSON Values Registry:
<list style="numbers">
<t>
<list style="symbols">
<t>Value: validated</t>
<t>Type: status</t>
<t>Description: 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>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: update prohibited</t>
<t>Type: status</t>
<t>Description: Updates to the object instance are forbidden.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: transfer prohibited</t>
<t>Type: status</t>
<t>Description: Transfers of the registration from one registrar
to another are forbidden. This type of status normally applies to DNR
domain names.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: delete prohibited</t>
<t>Type: status</t>
<t>Description: Deletion of the registration of the object
instance is forbidden. This type of status normally applies to DNR
domain names.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: proxy</t>
<t>Type: status</t>
<t>Description: The registration of the object instance has been performed
by a third party. This is most commonly applied to entities.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: private</t>
<t>Type: status</t>
<t>Description: The information of the object instance is not designated
for public consumption. This is most commonly applied to entities.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: redacted</t>
<t>Type: status</t>
<t>Description: Some of the information of the object instance has not
been made available. This is most commonly applied to entities.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: obscured</t>
<t>Type: status</t>
<t>Description: 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>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
</list>
</t>
</section>
<section title="Event Actions" anchor="event_action_registrations">
<t>This section registers the following values into the RDAP JSON Values Registry:
<list style="numbers">
<t>
<list style="symbols">
<t>Value: registration</t>
<t>Type: event action</t>
<t>Description: The object instance was initially registered.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: reregistration</t>
<t>Type: event action</t>
<t>Description: The object instance was registered subsequently to initial registration.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: last changed</t>
<t>Type: event action</t>
<t>Description: An action noting when the information in the object instance was last changed.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: expiration</t>
<t>Type: event action</t>
<t>Description: The object instance has been removed or will be removed at a pre-determined
date and time from the registry.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: deletion</t>
<t>Type: event action</t>
<t>Description: The object instance was removed from the registry at a point in time that was not pre-determined.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: reinstantiation</t>
<t>Type: event action</t>
<t>Description: The object instance was reregistered after having been
removed from the registry.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: transfer</t>
<t>Type: event action</t>
<t>Description: The object instance was transferred from one registrant to another.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
</list>
</t>
</section>
<section title="Roles" anchor="role_registrations">
<t>This section registers the following values into the RDAP JSON Values Registry:
<list style="numbers">
<t>
<list style="symbols">
<t>Value: registrant</t>
<t>Type: role</t>
<t>Description: The entity object instance is the registrant of the
registration. In some registries, this is known as a maintainer.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: tech</t>
<t>Type: role</t>
<t>Description: The entity object instance is a technical contact for the
registration.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: administrative</t>
<t>Type: role</t>
<t>Description: The entity object instance is an administrative contact for
the registration.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: abuse</t>
<t>Type: role</t>
<t>Description: The entity object instance handles network abuse issues on
behalf of the registrant of the registration.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: billing</t>
<t>Type: role</t>
<t>Description: The entity object instance handles payment and billing
issues on behalf of the registrant of the registration.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: registrar</t>
<t>Type: role</t>
<t>Description: The entity object instance represents the authority
responsible for the registration in the registry.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: reseller</t>
<t>Type: role</t>
<t>Description: The entity object instance represents a third party
through which the registration was conducted (i.e. not the registry or registrar).</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: sponsor</t>
<t>Type: role</t>
<t>Description: The entity object instance represents a domain policy
sponsor, such as an ICANN approved sponsor.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: proxy</t>
<t>Type: role</t>
<t>Description: The entity object instance represents a proxy for another
entity object, such as a registrant.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
</list>
</t>
</section>
<section title="Variant Relations" anchor="variant_relations">
<t>This section registers the following values into the RDAP JSON Values Registry:
<list style="numbers">
<t>
<list style="symbols">
<t>Value: registered</t>
<t>Type: domain variant relation</t>
<t>Description: The variant names are registered in the registry.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: unregistered</t>
<t>Type: domain variant relation</t>
<t>Description: The variant names are not found in the registry.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: registration restricted</t>
<t>Type: domain variant relation</t>
<t>Description: Registration of the variant names is
restricted to certain parties or within certain rules.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: open registration</t>
<t>Type: domain variant relation</t>
<t>Description: Registration of the variant names is available to
generally qualified registrants.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
<t>
<list style="symbols">
<t>Value: conjoined</t>
<t>Type: domain variant relation</t>
<t>Description: Registration of the variant names occurs automatically with the
registration of the containing domain registration.</t>
<t>Registrant Name: Andrew Newton</t>
<t>Registrant Contact Information: andy@hxr.us</t>
</list>
</t>
</list>
</t>
</section>
</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 <xref target="RFC3629"/>, 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="status_registrations"></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 Mitchell provided text regarding the processing of unknown
JSON attributes and identified issues leading to the remodeling of events. Ernie Dainow
and Francisco Obispo provided concrete suggestions that led to a better variant
model for domain names.
</t>
<t>
Ernie Dainow provided the background information on the secure DNSSEC attributes
and objects for domains, informative text on DNSSEC, and many other attributes
that appear throughout the object classes of this draft.
</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; &RFC3629; &RFC3986;
&RFC4034; &RFC4343; &RFC4627; &RFC5322; &RFC5396; &RFC5646; &RFC5890; &RFC5952; &RFC5988;
&I-D.draft-kewisch-vcard-in-json; &I-D.ietf-weirds-using-http; &I-D.ietf-weirds-rdap-query;
<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>
</references>
<references title="Informative References"> &RFC3912; &RFC3730; &RFC5910; &RFC6530;<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 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="role_registrations"/> 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",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
],
]
],
"roles" : [ "registrant", "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="status_registrations"></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. Additionally, many registrars have publicly assigned identifiers.
The 'publicIds' structure (<xref target="public_ids"></xref>) represents that
information.
</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",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{
"type":["work", "voice"],
"pref":"1"
},
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
],
]
],
"roles":[ "registrar" ],
"publicIds":[
{
"type":"IANA Registrar ID",
"identifier":"1"
}
],
"remarks":[
{
"description":[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links":[
{
"value":"http://example.net/entity/XXXX",
"rel":"alternate",
"type":"text/html",
"href":"http://www.example.com"
}
]
}
]
}
</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 anchor="structured_unstructured_addresses" title="Structured vs Unstructured Addresses">
<t>
The <xref target="entity_object_class">entity</xref> object class uses <xref target="I-D.kewisch-vcard-in-json">jCard</xref>
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.
</t>
<figure anchor="jcard_exmaple">
<preamble>The following is an example of a jCard.</preamble>
<artwork xml:space="preserve">
{
"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"
]
],
["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"]
]
]
}
</artwork>
</figure>
<t>
The arrays in <xref target="jcard_exmaple"></xref> 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 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 <xref target="RFC6530"></xref>. In this example, the following
data corresponds to the following positional meanings:
<list style="numbers">
<t>post office box - not applicable, empty string</t>
<t>extended address (e.g., apartment or suite number) - Suite 1234</t>
<t>street address - 4321 Rue Somewhere</t>
<t>locality (e.g., city) - Quebec</t>
<t>region (e.g., state or province) - QC</t>
<t>postal code - G1V 2M2</t>
<t>country name (full name) - Canada</t>
</list>
</t>
<t>
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.
</t>
</section>
<section title="Secure DNS" anchor="secure_dns">
<t><xref target="domain_object_class"></xref> defines the "secureDNS" member to represent
secure DNS information about domain names.</t>
<t>
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), <xref target="RFC4034">"Resource Records for the DNS Security
Extensions"</xref>. Creating the DS records in the parent zone can be
done by the registration authority, <xref target="RFC5910">"Domain Name System (DNS) Security
Extensions Mapping for the Extensible Provisioning Protocol (EPP)"</xref>.
</t>
<t>
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.
</t>
<t>The <xref target="domain_object_class">domain object class</xref> 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.</t>
</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>
</t>
<t hangText="-04">
<list>
<t>'description' removed from IP network and autnum because it is redundant with the remarks structure.</t>
<t>Added 'entities' array to nameservers.</t>
<t>Added 'status' to autnum.</t>
<t>Added 'publicIds' to entity and domain.</t>
<t>Added embedded entities to the entity object class.</t>
<t>Added 'idnTable' to variants objects in domain object class.</t>
<t>Changed the numbers for startNum and endNum in autnum to numbers instead of strings.</t>
<t>Added an example for error response with full rdapConformance and notices.</t>
<t>Added a section discussing help.</t>
<t>Changed entities to use vcardArray and changed the examples to be current with jCard.</t>
<t>Added a section on structured vs unstructured addresses.</t>
<t>Added associated to the list of status values.</t>
<t>Added a secure DNS section changed the 'delegationKey' object into the 'secureDNS' object.</t>
<t>Changed the suggested values to an IANA registry.</t>
<t>Added 'proxy' to the list of entity roles.</t>
</list>
<!-- TO DO
'-' denotes not done, '*' denotes done
* remove description from ip networks and autnum
* add entities to nameservers
* add status to autnum
* add a policy body ID to entities
* add idn table indicator to domains
* add entities to entities
* add secDNS stuff
* change vCard examples to use vcardArray
* make examples better
* appendix on structured vs unstructured addresses in jCard
* setup a registry for values
* make sure the error response example has notices and rdapConformance
* add section for /help
* change autnum start and end to numbers
-->
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 16:20:56 |