One document matched: draft-ietf-weirds-json-response-00.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 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 RFC5952 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5952.xml'>
]>
<?rfc toc="true"?>
<rfc category="std" docName="draft-ietf-weirds-json-response-00" ipr="trust200902">
<front>
<title abbrev="RDAP JSON RESPONSES">JSON Responses for the Registy 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 responses in the JSON format to the Registry Data Access Protocol (RDAP) queries
described in draft-ietf-weirds-rdap-query.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
This document describes responses in the <xref target="RFC4627">JSON</xref> format
for the RESTful web queries as defined by <xref target="I-D.ietf-weirds-rdap-query">UNIFIED-RDAP-QUERY</xref>.
The signalling for JSON, JSON naming scheme, JSON namespace and extension mechanism and normalized
references to other specifications are documented in
<xref target="I-D.ietf-weirds-using-http">RDAP-HTTP</xref>.
</t>
<t>
The data model for the responses consists of two major categories: 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. Where overlap exists between RIR
and DNR reponse object classes, the RIR object classes are a proper subset of the DNR object
classes. The current division between RIR and DNR object classes is given to illustrate an
expectation of what data may be expected from an RIR vs a DNR. However, implementers
should be aware that RIRs are not limited to the data in the RIR object classes
(as an example, some RIRs have a notion of "status" for entities as defined in the
DNR entity object class and may at some point start publishing that data).
</t>
<t>
Object classes defined in this document do not represent the full range of data
that any registry may wish to publish. <xref target="I-D.ietf-weirds-using-http">RDAP-HTTP</xref>
defines a JSON extension mechanism that maybe used by registries to insert registry
specific data values.
</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="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:">"Registry Data Access Protocol".</t>
<t hangText="RIR:">"Regional Internet Registry".</t>
</list>
</t>
</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">
<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 synomous 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"></xref>. 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"></xref>. 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"></xref>.
The alpha-2 representation is used because it is freely available whereas the
alpha-3 and numeric-3 standards are not.</t>
<t hangText="domain names: ">Textual representations of DNS names follow the
rules set forth in <xref target="RFC4343"></xref>, specifically the case
insensitivity and character escaping rules. Trailing periods are optional for both input and output.</t>
<t hangText="email addresses: ">Textual representations of email addresses follow
the syntax defined in <xref target="RFC5322"></xref>.</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"></xref>.</t>
</list>
</t>
</section>
<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">UNIFIED-RDAP-QUERY</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>
Many of the members of the entity object class are repeated in other
object classes described later in this document.
</t>
<section title="The RIR Entity Object Class" anchor="rir_entity_object_class">
<figure>
<preamble>The following is an example of an RIR entity:</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
"roles" : [ "registrant" ],
"postalAddress" :
[
"123 Maple Ave",
"Suite 90001",
"Vancouver",
"BC",
"12393"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" :
{
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/contact/xxxx"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "1990-12-31T23:59:60Z",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "joe@bob.com"
}
</artwork>
</figure>
<t> This object as the following members. <list style="symbols">
<t>handle -- a string representing an registry unique identifier of the
entity</t>
<t>names -- an array of strings, each signifying the name of the
entity</t>
<t>roles -- an array of strings, each signifying the relationship
an object would have with its closest containing object.</t>
<t>postalAddress -- an array of string, each representing a line
in a postal address.</t>
<t>emails -- an array of strings, each containing an email address for
the entity</t>
<t>phones -- an object containg telephone information associated with
the entity, with the following members: <list style="symbols">
<t>office -- an array of strings, each being a telephone
number</t>
<t>fax -- an array of strings, each being a telephone number</t>
<t>mobile -- an array of strings, each being a telephone
number</t>
</list></t>
<t>remarks -- an array of strings, each containing comments about the
entity</t>
<t>uris -- an array of objects, each object having the following
members: <list style="symbols">
<t>type -- a string denoting the application type of the "uri"
value</t>
<t>uri -- a string containing a <xref target="RFC3986">URI</xref></t>
</list></t>
<t>registrationDate -- a string containing the date the entity was
registered</t>
<t>lastChangedDate -- a string containing the date of last change made
to the entity</t>
<t>lastChangedBy -- a string containing an identifier of the party
responsible for the last change made to the entity registration</t>
</list>
</t>
</section>
<section title="The DNR Entity Object Class" anchor="dnr_entity_object_class">
<t>
The DNR entity object class is a superset of the
<xref target="rir_entity_object_class">RIR entity object class</xref>.
It has the following additional members:
<list style="symbols">
<t>registrationBy -- a string containing an identifier of the party
responsible for the registration of the entity</t>
<t>sponsoredBy -- a string containing an identifier of the party
through which the registration was made, such as an IANA approved registrar</t>
<t>resoldBy -- a string containing an identifier of the party
originating the registration of the entity.</t>
<t>status -- an array of strings indicating the state of the entity</t>
<t>port43 -- a string containing the fully-qualified host name of the WHOIS <xref target="RFC3912"/> server
where the object instance may be found.</t>
</list>
</t>
<figure>
<preamble>The following is an example of a DNR entity:</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
"status" : [ "validated", "locked" ],
"postalAddress" :
[
"123 Maple Ave",
"Suite 90001",
"Vancouver",
"BC",
"12393"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" :
{
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/entity/xxxx"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"port43" : "whois.example.net",
"registrationDate" : "1990-12-31T23:59:60Z",
"registrationBy" : "ABC123",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "ABC123",
"sponsoredBy" : "SponsorXYZ",
"resoldBy" : "ResellerPDQ"
}
</artwork>
</figure>
</section>
</section>
<section title="The Nameserver Object Class" anchor="nameserver_object_class">
<t>
The nameserver object class is used by both RIRs and DNRs. Unlike
other object classes used by both registries where the RIR object class
is a subset of the DNR object class, a clear delineation is not
made with the nameserver object class because some DNRs have the
same or a similar registration model as the RIRs.
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 accomodates 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",
"name" : "ns1.example.com",
"status" : "active",
"ipAddresses" : [ "192.0.2.0", "192.0.2.1" ],
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://example.net/nameserver/xxxx"
}
],
"port43" : "whois.example.net",
"registrationDate" : "1990-12-31T23:59:60Z",
"registrationBy" : "ABC123",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "ABC123",
"sponsoredBy" : "SponsorXYZ",
"resoldBy" : "ResellerPDQ"
}
</artwork>
</figure>
<t>
<xref target="full_nameserver_example"></xref> 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"></xref>
is an example of a nameserver object as would be found in RIRs and some
DNRs, while <xref target="near_simplest_nameserver_example"></xref> 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">
{
"name" : "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">
{
"name" : "ns1.example.com",
"ipAddresses" : [ "192.0.2.0", "192.0.2.1" ]
}
</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>name -- a string containing the DNS name of the nameserver</t>
<t>ipAddresses -- an array of strings containing IPv4 and/or IPv6 addresses
of the nameserver</t>
</list>
The members "status", "remarks", "uris", "port43", "sponsoredBy", "resoldBy",
"registrationBy", "registrationDate", "lastChangedDate", and
"lastChangedBy" take the same form of the members of the same name of the
<xref target="entity_object_class">entity object</xref>.
</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. The
RIR domain object class is a subset of the DNR object class.
</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",
"name" : "blah.example.com",
...
"nameServers" :
[
...
],
...
"entities" :
[
...
]
}
</artwork>
</figure>
<section title="The RIR Domain Object Class" anchor="rir_domain_object_class">
<figure>
<preamble>The following is an example of a JSON object representing
a reverse DNS delegation point or the RIR domain object class.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"name" : "192.in-addr.arpa",
"nameServers" :
[
{ "name" : "ns1.rir.net" },
{ "name" : "ns2.rir.net" }
],
"delegationKeys" :
[
{
"algorithm": 7,
"digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C",
"digestType" : 1,
"keyTag" : 53814
}
],
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/network/xxxx"
},
{
"type" : "parent",
"uri" : "http://whois-rws.net/network/yyyy"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "1990-12-31T23:59:60Z",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "joe@bob.com",
"entities" :
[
{
"handle" : "XXXX",
"names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
"roles" : [ "registrant" ],
"postalAddress" :
[
"123 Maple Ave",
"Suite 90001",
"Vancouver",
"BC",
"12393"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" :
{
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/entity/xxxx"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "1990-12-31T23:59:60Z",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "joe@bob.com"
}
]
}
</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>name -- a string denoting the DNS zone name, which is a domain name</t>
<t>nameservers -- an array of nameserver objects as defined by <xref target="nameserver_object_class"></xref></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 presetnation 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="rir_entity_object_class"></xref>.</t>
</list>
The members "remarks", "uris", "registrationDate", "lastChangedDate", and
"lastChangedBy" take the same form of the members of the same name of the
<xref target="entity_object_class">entity object</xref>.
</t>
</section>
<section title="The DNR Domain Object Class" anchor="dnr_domain_object_class">
<t>
The DNR domain object class is a superset of the <xref target="rir_domain_object_class">RIR domain object class</xref>
and has the following additional members.
<list style="symbols">
<t>variants -- an array of strings, each containing a domain name that is a variant of
this domain name object instance.
</t>
<t>expirationDate -- a string containing the date and time this domain name registration will expire</t>
<t>registrationBy -- a string containing an identifier of the party
responsible for the registration of the domain name</t>
<t>sponsoredBy -- a string containing an identifier of the party
through which the registration was made, such as an IANA approved registrar</t>
<t>resoldBy -- a string containing an identifier of the party
originating the registration of the domain name</t>
<t>status -- an array of strings indicating the state of the domain name</t>
<t>transferDate -- a string containing the date and time this domain name was transferred</t>
<t>port43 -- a string containing the fully-qualified host name of the WHOIS <xref target="RFC3912"/> server
where the object instance may be found.</t>
</list>
</t>
<figure>
<preamble>The following is an example of a JSON object representing
a forward DNS delegation point or the DNR domain object class.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"name" : "blah.example.com",
"variants" : [ "blah2.example.com", "blah3.example.com" ],
"status" : [ "locked", "transferProhibited" ],
"nameServers" :
[
{
"handle" : "XXXX",
"name" : "ns1.example.com",
"status" : "active",
"ipAddresses" : [ "192.0.2.0", "192.0.2.1" ],
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://example.net/nameserver/xxxx"
}
],
"registrationDate" : "1990-12-31T23:59:60Z",
"registrationBy" : "ABC123",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "ABC123",
"sponsoredBy" : "SponsorXYZ",
"resoldBy" : "ResellerPDQ"
},
{
"handle" : "XXXX",
"name" : "ns2.example.com",
"status" : "active",
"ipAddresses" : [ "192.0.2.2", "192.0.2.3" ],
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://example.net/nameserver/xxxx"
}
],
"registrationDate" : "1990-12-31T23:59:60Z",
"registrationBy" : "ABC123",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "ABC123",
"sponsoredBy" : "SponsorXYZ",
"resoldBy" : "ResellerPDQ"
}
]
"delegationKeys" :
[
{
"algorithm": 7,
"digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C",
"digestType" : 1,
"keyTag" : 53814
}
],
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://example.net/domain/xxxx"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"port43" : "whois.example.net",
"registrationDate" : "1990-12-31T23:59:60Z",
"registrationBy" : "ABC123",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "ABC123",
"sponsoredBy" : "SponsorXYZ",
"resoldBy" : "ResellerPDQ",
"expirationDate" : "2016-12-31T23:59:60Z",
"transferDate" : "1990-12-31T23:59:60Z",
"entities" :
[
{
"handle" : "XXXX",
"names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
"status" : [ "validated", "locked" ],
"postalAddress" :
[
"123 Maple Ave",
"Suite 90001",
"Vancouver",
"BC",
"12393"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" :
{
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/entity/xxxx"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "1990-12-31T23:59:60Z",
"registrationBy" : "ABC123",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "ABC123",
"sponsoredBy" : "SponsorXYZ",
"resoldBy" : "ResellerPDQ"
}
]
}
</artwork>
</figure>
</section>
</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"></xref>.
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" : "10.0.0.0",
"endAddress" : "10.0.0.255",
"ipVersion" : 4,
"name": "NET-RTR-1",
"description" : [ "A network used for routing" ],
"type" : "DIRECT ALLOCATION",
"country" : "AU",
"parentHandle" : "YYYY-RIR",
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/network/xxxx"
},
{
"type" : "parent",
"uri" : "http://whois-rws.net/network/yyyy"
},
],
"registrationDate" : "20110509",
"lastChangedDate" : "20110509",
"lastChangedBy" : "joe@bob.com",
"entities" :
[
{
"handle" : "XXXX",
"names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
"roles" : [ "registrant" ],
"postalAddress" :
[
"123 Maple Ave",
"Suite 90001",
"Vancouver",
"BC",
"12393"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" :
{
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/contact/xxxx"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "1990-12-31T23:59:60Z",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "joe@bob.com"
}
]
}
</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 integer signifying the IP protocol version of the
network: 4 signifying an IPv4 network, 6 signifing 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>entities -- an array of entity objects as defined by <xref target="rir_entity_object_class"></xref>.</t>
</list>
The members "remarks", "uris", "registrationDate", "lastChangedDate", and
"lastChangedBy" take the same form of the members of the same name of the
<xref target="rir_entity_object_class">entity object</xref>.
</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"></xref>.
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" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/autnum/xxxx"
},
{
"type" : "parent",
"uri" : "http://whois-rws.net/autnum/yyyy"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "20110509",
"lastChangedDate" : "20110509",
"lastChangedBy" : "joe@bob.com",
"entities" :
[
{
"handle" : "XXXX",
"names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
"roles" : [ "registrant" ],
"postalAddress" :
[
"123 Maple Ave",
"Suite 90001",
"Vancouver",
"BC",
"12393"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" :
{
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"uris" :
[
{
"type" : "source",
"uri" : "http://whois-rws.net/autnum/xxxx"
}
],
"registrationDate" : "1990-12-31T23:59:60Z",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "joe@bob.com"
}
]
}
</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>
</list>
The members "remarks", "uris", "registrationDate", "lastChangedDate", and
"lastChangedBy" take the same form of the members of the same name of the
<xref target="rir_entity_object_class">entity object</xref>.
</t>
</section>
<section title="Contributing Authors and Acknowledgements">
<t>
This document is derived from original work on RIR response in JSON by Byron J. Ellacott of APNIC,
Arturo L. Servin of LACNIC, Kaveh Ranjbar of the RIPE NCC, and Andrew L. Newton of ARIN.
Additionally, this document incorporates word on DNR responses in JSON by Ning Kong,
Linlin Zhou, Jiagui Xie, and Sean Shen of CNNIC.
</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 of CNNIC,
Steve Sheng and Francisco Arias of ICANN, Ray Bellis of Nominet, and Frederico Neves of NIC.BR.
</t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC0791;
&RFC1166;
&RFC2616;
&RFC3339;
&RFC3986;
&RFC4034;
&RFC4343;
&RFC4627;
&RFC5322;
&RFC5396;
&RFC5952;
<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;
</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">
<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>
</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 registraton.</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>
</list>
</t>
</section>
<section title="URI Types" anchor="suggested_uri_types">
<t>
Many of the object classes have a member named 'uris', which is an array of objects with
each object containing a 'type' string and a 'uri' string. These URIs represent a location
to find information about the containing object. The following is a list of suggested values
to use as a 'type' string for an associated URI.
<list style="symbols">
<t>'self' -- Indicates the URI is a direct reference to the object instance via an RDAP query.</t>
<t>'parent' -- Indicates a direct reference to an object instance's parent via an RDAP query.
Such a reference might be used in an IP network to reference the next IP network up the tree
of IP address hierarchies.</t>
<t>'source' -- Signifies a direct reference to the registration in another RESTful protocol. As an example,
both ARIN and the RIPE NCC have RESTful web services for WHOIS data that pre-exists RDAP. This type
of URI would be used to reference the same data in such a system.</t>
<t>'web' -- Signifies the web site of the containing object instance. The expectation is that
a web browser would be needed to use this URI.</t>
<t>'rdap' -- Signifies the RDAP service where RDAP queries can be issued.</t>
<t>'held' -- Signifies a HELD location service for the registered object.</t>
<t>'geo' -- Signifies that the URI is a geo URI related to the location of the 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"></xref> 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",
"names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
"roles" : [ "registrant", "admin" ],
"postalAddress" :
[
"123 Maple Ave",
"Suite 90001",
"Vancouver",
"BC",
"12393"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" :
{
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" :
[
"she sells seas shells",
"down by the seashore"
],
"registrationDate" : "1990-12-31T23:59:60Z",
"lastChangedDate" : "1990-12-31T23:59:60Z",
"lastChangedBy" : "joe@bob.com"
}
]
}
</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"></xref>) the 'roles'
string array maybe used. Additionally, a URI type can signify the registrars point of
service (see <xref target="suggested_uri_types"></xref>).
</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",
"names": [ "RegistrarsRUS" ],
"roles" : [ "registrar" ],
"postalAddress" :
[
"1212 Tulip Ave",
"Suite 1",
"Marina Del Rey",
"CA",
"12393-2193"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" :
{
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" :
[
"we registrar for less!"
],
"uris" :
[
{
"type" : "rdap",
"uri" : "http://rdap.exmaple.com"
},
{
"type" : "web",
"uri" : "http://www.example.com"
}
]
}
]
}
</artwork>
</figure>
</section>
</section>
<section title="IDN Query and Response Model">
<t>
Internationalized Domain Names (IDNs) differ from other types of domain
names because multiple domain names as would be represented by a name in
Master File format (see <xref target="RFC4343"></xref>) may be registered
by a single IDN. IDNs are based on Unicode, and Unicode can have multiple
means for encoding the same word depending on the character set and language
being used. And the rules for determining which IDN encoding maps to a
"wire-format" domain name vary from DNR to DNR.
</t>
<t>
When an IDN maps to multiple domain names, the various mappings are called
variants. The <xref target="dnr_domain_object_class">DNR Domain object class</xref>
represents the variants using a string array.
</t>
<figure>
<preamble>The following is an example of an elided DNR domain object with variants.</preamble>
<artwork xml:space="preserve">
{
"handle" : "XXXX",
"name" : "blah.example.com",
"variants" : [ "blah2.example.com", "blah3.example.com" ],
...
}
</artwork>
</figure>
<t>
Because IDNs can have multiple targets in a mapping and due to the
variance in DNR mapping rules, it is up to the client to reduce an IDN
to a domain name in Master File format so as to narrow the lookup of the
domain name to the proper subset. A query of a DNR using the IDN itself
might map across multiple registrations depending on the mapping rules
of the DNR.
</t>
</section>
<section title="Postal Addresses vs Location">
<t>
The postal address data listed in the <xref target="entity_object_class">entity object class</xref>
does not necessarily represent location. The intent of this information is to provide a means
to send postal mail to an entity. While in some cases it may also be the location of the entity,
there is no gaurantee that the two are the same. Accurate representation of location is topic
unto itself, and registries wishing to show location of object instances should use the
'geo' or 'held' URI types as meantioned in <xref target="suggested_uri_types"></xref>.
</t>
<t>
Additionally, the postal address data represented in this document does not follow any
specific standard for postal addresses because many registries do not keep postal address
data in an internationalized standard form. Publication of such data in a format that
suggests an internationalized standard form when such data is not known to be well-formed
for that purpose would be misleading.
</t>
</section>
<section title="Changelog">
<t>
<list style="hanging">
<t hangText="Initial -00">
Adopted as working group document 2012-September-18.
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 16:23:59 |