draft-ietf-weirds-json-response-06.txt   draft-ietf-weirds-json-response-07.txt 
Network Working Group A. Newton Network Working Group A. Newton
Internet-Draft ARIN Internet-Draft ARIN
Intended status: Standards Track S. Hollenbeck Intended status: Standards Track S. Hollenbeck
Expires: April 06, 2014 Verisign Labs Expires: November 1, 2014 Verisign Labs
October 03, 2013 April 30, 2014
JSON Responses for the Registration Data Access Protocol (RDAP) JSON Responses for the Registration Data Access Protocol (RDAP)
draft-ietf-weirds-json-response-06 draft-ietf-weirds-json-response-07
Abstract Abstract
This document describes JSON data structures representing This document describes JSON data structures representing
registration information maintained by Regional Internet Registries registration information maintained by Regional Internet Registries
(RIRs) and Domain Name Registries (DNRs). These data structures are (RIRs) and Domain Name Registries (DNRs). These data structures are
used to form Registration Data Access Protocol (RDAP) query used to form Registration Data Access Protocol (RDAP) query
responses. responses.
Status of This Memo Status of This Memo
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 06, 2014. This Internet-Draft will expire on November 1, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology and Definitions . . . . . . . . . . . . . . . . . 4 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 4
3. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Signaling . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Signaling . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 6 4. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 6
5. Common Data Structures . . . . . . . . . . . . . . . . . . . 7 5. Common Data Structures . . . . . . . . . . . . . . . . . . . 8
5.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 8 5.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 8
5.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.3. Notices And Remarks . . . . . . . . . . . . . . . . . . . 9 5.3. Notices And Remarks . . . . . . . . . . . . . . . . . . . 9
5.4. Language Identifier . . . . . . . . . . . . . . . . . . . 11 5.4. Language Identifier . . . . . . . . . . . . . . . . . . . 11
5.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.7. Port 43 Whois Server . . . . . . . . . . . . . . . . . . 12 5.7. Port 43 Whois Server . . . . . . . . . . . . . . . . . . 13
5.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 13 5.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 13
5.9. An Example . . . . . . . . . . . . . . . . . . . . . . . 13 5.9. An Example . . . . . . . . . . . . . . . . . . . . . . . 13
6. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 14 6. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 15
6.1. The Entity Object Class . . . . . . . . . . . . . . . . . 15 6.1. The Entity Object Class . . . . . . . . . . . . . . . . . 15
6.2. The Nameserver Object Class . . . . . . . . . . . . . . . 21 6.2. The Nameserver Object Class . . . . . . . . . . . . . . . 22
6.3. The Domain Object Class . . . . . . . . . . . . . . . . . 25 6.3. The Domain Object Class . . . . . . . . . . . . . . . . . 26
6.4. The IP Network Object Class . . . . . . . . . . . . . . . 37 6.4. The IP Network Object Class . . . . . . . . . . . . . . . 37
6.5. Autonomous System Number Entity Object Class . . . . . . 41 6.5. Autonomous System Number Entity Object Class . . . . . . 41
7. Error Response Body . . . . . . . . . . . . . . . . . . . . . 44 7. Error Response Body . . . . . . . . . . . . . . . . . . . . . 45
8. Responding to Help Queries . . . . . . . . . . . . . . . . . 46 8. Responding to Help Queries . . . . . . . . . . . . . . . . . 46
9. Responding To Searches . . . . . . . . . . . . . . . . . . . 47 9. Responding To Searches . . . . . . . . . . . . . . . . . . . 47
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 10. Indicating Truncated Responses . . . . . . . . . . . . . . . 48
10.1. RDAP JSON Media Type Registration . . . . . . . . . . . 49 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50
10.2. JSON Values Registry . . . . . . . . . . . . . . . . . . 50 11.1. RDAP JSON Media Type Registration . . . . . . . . . . . 50
10.2.1. Status . . . . . . . . . . . . . . . . . . . . . . . 52 11.2. JSON Values Registry . . . . . . . . . . . . . . . . . . 51
10.2.2. Event Actions . . . . . . . . . . . . . . . . . . . 57 11.2.1. Status . . . . . . . . . . . . . . . . . . . . . . . 53
10.2.3. Roles . . . . . . . . . . . . . . . . . . . . . . . 60 11.2.2. Event Actions . . . . . . . . . . . . . . . . . . . 58
10.2.4. Variant Relations . . . . . . . . . . . . . . . . . 63 11.2.3. Roles . . . . . . . . . . . . . . . . . . . . . . . 60
11. Security Considerations . . . . . . . . . . . . . . . . . . . 64 11.2.4. Variant Relations . . . . . . . . . . . . . . . . . 64
12. Internationalization Considerations . . . . . . . . . . . . . 64 12. Security Considerations . . . . . . . . . . . . . . . . . . . 65
12.1. Character Encoding . . . . . . . . . . . . . . . . . . . 64 13. Internationalization Considerations . . . . . . . . . . . . . 65
12.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 64 13.1. Character Encoding . . . . . . . . . . . . . . . . . . . 65
12.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 65 13.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 65
12.4. Internationalized Domain Names . . . . . . . . . . . . . 65 13.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 65
13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 65 13.4. Internationalized Domain Names . . . . . . . . . . . . . 66
14. Contributing Authors and Acknowledgements . . . . . . . . . . 65 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 66
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 15. Contributing Authors and Acknowledgements . . . . . . . . . . 66
15.1. Normative References . . . . . . . . . . . . . . . . . . 66 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 67
15.2. Informative References . . . . . . . . . . . . . . . . . 67 16.1. Normative References . . . . . . . . . . . . . . . . . . 67
Appendix A. Suggested Data Modeling with the Entity Object Class 68 16.2. Informative References . . . . . . . . . . . . . . . . . 68
A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 68 Appendix A. Suggested Data Modeling with the Entity Object Class 69
A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 70 A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 69
Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 72 A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 71
Appendix C. Structured vs Unstructured Addresses . . . . . . . . 73 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 73
Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 76 Appendix C. Structured vs Unstructured Addresses . . . . . . . . 75
Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 77 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 77
Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . 77 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 78
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . 78
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 83
1. Introduction 1. Introduction
This document describes responses in the JSON [RFC4627] format for This document describes responses in the JSON [RFC4627] format for
the RESTful web queries as defined by the Registration Data Access the RESTful web queries as defined by the Registration Data Access
Protocol Lookup Format [I-D.ietf-weirds-rdap-query]. Protocol Lookup Format [I-D.ietf-weirds-rdap-query].
The data model for JSON responses is specified in four sections: The data model for JSON responses is specified in four sections:
1. simple data types conveyed in JSON strings 1. simple data types conveyed in JSON strings
skipping to change at page 9, line 5 skipping to change at page 9, line 7
Figure 4 Figure 4
5.2. Links 5.2. Links
The "links" array is found in data structures to signify links to The "links" array is found in data structures to signify links to
other resources on the Internet. The relationship of these links is other resources on the Internet. The relationship of these links is
defined by the IANA registry described by [RFC5988]. defined by the IANA registry described by [RFC5988].
The following is an example of the link structure: The following is an example of the link structure:
{ {
"value" : "http://example.com/context_uri", "value" : "http://example.com/context_uri",
"rel" : "self", "rel" : "self",
"href" : "http://example.com/target_uri", "href" : "http://example.com/target_uri",
"hreflang" : [ "en", "ch" ], "hreflang" : [ "en", "ch" ],
"title" : [ "title1", "title2" ], "title" : [ "title1", "title2" ],
"media" : "screen", "media" : "screen",
"type" : "application/json" "type" : "application/json"
} }
Figure 5 Figure 5
The JSON name/values of "rel", "href", "hreflang", "title", "media", The JSON name/values of "rel", "href", "hreflang", "title", "media",
and "type" correspond to values found in Section 5 of [RFC5988]. The and "type" correspond to values found in Section 5 of [RFC5988]. The
"value" JSON value is the context URI as described by [RFC5988]. The "value" JSON value is the context URI as described by [RFC5988]. The
"value", "rel", and "href" JSON values MUST be specified. All other "value", "rel", and "href" JSON values MUST be specified. All other
JSON values are optional. JSON values are optional.
This is an example of the "links" array as it might be found in an This is an example of the "links" array as it might be found in an
skipping to change at page 12, line 42 skipping to change at page 12, line 44
o 'links' -- see Section 5.2. o 'links' -- see Section 5.2.
Events can be future dated. One use case for future dating of events Events can be future dated. One use case for future dating of events
is to denote when an object expires from a registry. is to denote when an object expires from a registry.
The 'links' array in this data structure is provided for references The 'links' array in this data structure is provided for references
to the event actor. If the event actor being referenced is an RDAP to the event actor. If the event actor being referenced is an RDAP
entity, the link reference SHOULD be made with "rel" of "related" and entity, the link reference SHOULD be made with "rel" of "related" and
"type" of "application/rdap+json". "type" of "application/rdap+json".
See Section 10.2.2 for a list of values for the 'eventAction' string. See Section 11.2.2 for a list of values for the 'eventAction' string.
See Appendix B regarding the various ways events can be modeled. See Appendix B regarding the various ways events can be modeled.
5.6. Status 5.6. Status
This data structure, named 'status', is an array of strings This data structure, named 'status', is an array of strings
indicating the state of a registered object (see Section 10.2.1 for a indicating the state of a registered object (see Section 11.2.1 for a
list of values). list of values).
5.7. Port 43 Whois Server 5.7. Port 43 Whois Server
This data structure, named 'port43', is a simple string containing This data structure, named 'port43', is a simple string containing
the fully-qualified host name of the WHOIS [RFC3912] server where the the fully-qualified host name of the WHOIS [RFC3912] server where the
containing object instance may be found. Note that this is not a containing object instance may be found. Note that this is not a
URI, as there is no WHOIS URI scheme. URI, as there is no WHOIS URI scheme.
5.8. Public IDs 5.8. Public IDs
This data structure maps a public identifier to an object class. It This data structure maps a public identifier to an object class. It
is named 'publicIds' and is an array of objects, with each object is named 'publicIds' and is an array of objects, with each object
containing the following members: containing the following members:
skipping to change at page 15, line 28 skipping to change at page 15, line 31
Self links SHOULD contain a "type" element containing the Self links SHOULD contain a "type" element containing the
"application/rdap+json" media type when referencing RDAP object "application/rdap+json" media type when referencing RDAP object
instances as defined by this document. Clients SHOULD NOT assume instances as defined by this document. Clients SHOULD NOT assume
self links without this media type are represented as RDAP objects as self links without this media type are represented as RDAP objects as
defined by this document. defined by this document.
This is an example of the "links" array with a self link to an object This is an example of the "links" array with a self link to an object
class: class:
"links" : "links" :
[ [
{ {
"value" : "http://example.com/ip/2001:db8::123", "value" : "http://example.com/ip/2001:db8::123",
"rel" : "self", "rel" : "self",
"href" : "http://example.com/ip/2001:db8::123", "href" : "http://example.com/ip/2001:db8::123",
"type" : "application/rdap+json" "type" : "application/rdap+json"
} }
] ]
6.1. The Entity Object Class 6.1. The Entity Object Class
The entity object class appears throughout this document and is an The entity object class appears throughout this document and is an
appropriate response for the /entity/XXXX query defined in appropriate response for the /entity/XXXX query defined in
Registration Data Access Protocol Lookup Format Registration Data Access Protocol Lookup Format
[I-D.ietf-weirds-rdap-query]. This object class represents the [I-D.ietf-weirds-rdap-query]. This object class represents the
information of organizations, corporations, governments, non-profits, information of organizations, corporations, governments, non-profits,
clubs, individual persons, and informal groups of people. All of clubs, individual persons, and informal groups of people. All of
these representations are so similar that it is best to represent these representations are so similar that it is best to represent
skipping to change at page 19, line 32 skipping to change at page 19, line 35
This object has the following members: This object has the following members:
o handle -- a string representing an registry unique identifier of o handle -- a string representing an registry unique identifier of
the entity the entity
o vcardArray -- a JSON vCard with the entity's contact information o vcardArray -- a JSON vCard with the entity's contact information
o roles -- an array of strings, each signifying the relationship an o roles -- an array of strings, each signifying the relationship an
object would have with its closest containing object (see object would have with its closest containing object (see
Section 10.2.3 for a list of values) Section 11.2.3 for a list of values)
o publicIds - see Section 5.8 o publicIds - see Section 5.8
o entities - an array of entity objects as defined by this section. o entities - an array of entity objects as defined by this section.
o remarks -- see Section 5.3 o remarks -- see Section 5.3
o links -- see Section 5.2 o links -- see Section 5.2
o events -- see Section 5.5 o events -- see Section 5.5
skipping to change at page 20, line 4 skipping to change at page 20, line 8
o events -- see Section 5.5 o events -- see Section 5.5
o asEventActor -- this data structure takes the same form as the o asEventActor -- this data structure takes the same form as the
'events' data structure (see Section 5.5), but each object in the 'events' data structure (see Section 5.5), but each object in the
array MUST NOT have an 'eventActor' member. These objects denote array MUST NOT have an 'eventActor' member. These objects denote
that the entity is an event actor for the given events. See that the entity is an event actor for the given events. See
Appendix B regarding the various ways events can be modeled. Appendix B regarding the various ways events can be modeled.
o status -- see Section 5.6 o status -- see Section 5.6
o port43 -- see Section 5.7 o port43 -- see Section 5.7
o networks -- an array of IP network objects as defined in
Section 6.4
o autnums -- an array of autnum objects as defined in Section 6.5
The following is an example of a entity that might be served by a The following is an example of a entity that might be served by a
DNR. For illustrative purposes, it does not include rdapConformance DNR. For illustrative purposes, it does not include rdapConformance
or notices data structures. or notices data structures.
{ {
"handle":"XXXX", "handle":"XXXX",
"vcardArray":[ "vcardArray":[
"vcard", "vcard",
[ [
["version", {}, "text", "4.0"], ["version", {}, "text", "4.0"],
skipping to change at page 27, line 7 skipping to change at page 27, line 4
described in Section 4 described in Section 4
o unicodeName -- a string containing a domain name with U-labels as o unicodeName -- a string containing a domain name with U-labels as
described in Section 4 described in Section 4
o variants -- an array of objects, each containing the following o variants -- an array of objects, each containing the following
values: values:
* relation -- an array of strings, with each string denoting the * relation -- an array of strings, with each string denoting the
relationship between the variants and the containing domain relationship between the variants and the containing domain
object (see Section 10.2.4 for a list of suggested variant object (see Section 11.2.4 for a list of suggested variant
relations). relations).
* idnTable -- the name of the IDN table of codepoints, such as * idnTable -- the name of the IDN table of codepoints, such as
one listed with the IANA (see IDN tables [IANA_IDNTABLES]). one listed with the IANA (see IDN tables [IANA_IDNTABLES]).
* variantNames -- an array of objects, with each object * variantNames -- an array of objects, with each object
containing an "ldhName" member and a "unicodeName" member (see containing an "ldhName" member and a "unicodeName" member (see
Section 4). Section 4).
o nameservers -- an array of nameserver objects as defined by o nameServers -- an array of nameserver objects as defined by
Section 6.2 Section 6.2
o secureDNS -- an object with the following members: o secureDNS -- an object with the following members:
* zoneSigned -- boolean true if the zone has been signed, false * zoneSigned -- boolean true if the zone has been signed, false
otherwise. otherwise.
* delegationSigned -- boolean true if there are DS records in the * delegationSigned -- boolean true if there are DS records in the
parent, false otherwise. parent, false otherwise.
skipping to change at page 28, line 40 skipping to change at page 28, line 38
o publicIds - see Section 5.8 o publicIds - see Section 5.8
o remarks - see Section 5.3 o remarks - see Section 5.3
o links - see Section 5.2 o links - see Section 5.2
o port43 - see Section 5.7 o port43 - see Section 5.7
o events - see Section 5.5 o events - see Section 5.5
o network - represents the IP network for which a reverse DNS domain
is referenced. See Section 6.4
The following is an example of a JSON domain object representing a The following is an example of a JSON domain object representing a
reverse DNS delegation point that might be served by an RIR. For reverse DNS delegation point that might be served by an RIR. For
illustrative purposes, it does not include rdapConformance or notices illustrative purposes, it does not include rdapConformance or notices
data structures. data structures.
{ {
"handle" : "XXXX", "handle" : "XXXX",
"ldhName" : "192.in-addr.arpa", "ldhName" : "192.in-addr.arpa",
"nameServers" : "nameServers" :
[ [
skipping to change at page 29, line 15 skipping to change at page 29, line 15
], ],
"secureDNS": "secureDNS":
{ {
"delegationSigned": true, "delegationSigned": true,
"dsData": "dsData":
[ [
{ {
"keyTag": 12345, "keyTag": 12345,
"algorithm": 3, "algorithm": 3,
"digestType": 1, "digestType": 1,
"digest": "49FD46E6C4B45C55D4AC", "digest": "49FD46E6C4B45C55D4AC"
} }
] ]
}, },
"remarks" : "remarks" :
[ [
{ {
"description" : "description" :
[ [
"She sells sea shells down by the sea shore.", "She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan." "Originally written by Terry Sullivan."
skipping to change at page 31, line 30 skipping to change at page 31, line 31
"eventAction" : "registration", "eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z" "eventDate" : "1990-12-31T23:59:60Z"
}, },
{ {
"eventAction" : "last changed", "eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z", "eventDate" : "1991-12-31T23:59:60Z",
"eventActor" : "joe@example.com" "eventActor" : "joe@example.com"
} }
] ]
} }
] ],
"network" :
{
"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" ]
}
} }
The following is an example of a JSON domain object representing a The following is an example of a JSON domain object representing a
forward DNS delegation point that might be served by a DNR. For forward DNS delegation point that might be served by a DNR. For
illustrative purposes, it does not include rdapConformance or notices illustrative purposes, it does not include rdapConformance or notices
data structures. data structures.
{ {
"handle" : "XXXX", "handle" : "XXXX",
"ldhName" : "xn--fo-5ja.example", "ldhName" : "xn--fo-5ja.example",
skipping to change at page 48, line 28 skipping to change at page 48, line 30
{ {
"handle" : "2-XXXX", "handle" : "2-XXXX",
"ldhName" : "2.example.com", "ldhName" : "2.example.com",
... ...
} }
] ]
} }
search_response_example search_response_example
In addition to the arrays, the response object may contain a member 10. Indicating Truncated Responses
named "searchResultsTruncated" which is a boolean. When this value
is set to true, it indicates the accompanying array did not contain In cases where the data of a response has been truncated (i.e. not
all of the data that matched the search criteria. When this value is all of it has been included in the response), a server may indicate
true, it is recommended that servers include a textual description this by including the boolean "resultsTruncated" in the response
for the truncation in a notices structure. object. Whe this value is set to true, it indicates the data of the
response has been truncated. When this value is true, it is
recommended that servers include a textual description describing the
nature of the truncation in a notices structure.
The following is an elided example of a search response that has been The following is an elided example of a search response that has been
truncated. truncated.
{ {
"rdapConformance" : "rdapConformance" :
[ [
"rdap_level_0" "rdap_level_0"
], ],
"notices" : "notices" :
skipping to change at page 49, line 29 skipping to change at page 49, line 32
[ [
{ {
"value" : "http://example.net/help", "value" : "http://example.net/help",
"rel" : "alternate", "rel" : "alternate",
"type" : "text/html", "type" : "text/html",
"href" : "http://www.example.com/search_policy.html" "href" : "http://www.example.com/search_policy.html"
} }
] ]
} }
], ],
"searchResultsTruncated" : true "resultsTruncated" : true
"domainSearchResults" : "domainSearchResults" :
[ [
... ...
] ]
} }
search_response_truncated_example search_response_truncated_example
10. IANA Considerations Note that "resultsTruncated" can be used where a single object has
been returned and data in that object has been truncated. Such an
example might be an entity object with only a partial set of the IP
networks associated with it.
10.1. RDAP JSON Media Type Registration The following is an elided example of an entity truncated data.
{
"handle" : "ANENTITY",
"roles" : [ "registrant" ],
...
"entities" :
[
{
"handle": "ANEMBEDDEDENTITY",
"roles" : [ "technical" ],
...
},
...
],
"networks" :
[
...
],
...
"resultsTruncated": true
}
Figure 20
11. IANA Considerations
11.1. RDAP JSON Media Type Registration
This specification registers the "application/rdap+json" media type. This specification registers the "application/rdap+json" media type.
Type name: application Type name: application
Subtype name: rdap+json Subtype name: rdap+json
Required parameters: n/a Required parameters: n/a
Encoding considerations: See section 3.1 of [RFC6839]. Encoding considerations: See section 3.1 of [RFC6839].
skipping to change at page 50, line 21 skipping to change at page 51, line 14
Published specification: [[ this document ]] Published specification: [[ this document ]]
Applications that use this media type: Implementations of the Applications that use this media type: Implementations of the
Registration Data Access Protocol (RDAP) Registration Data Access Protocol (RDAP)
Additional information: This media type is a product of the IETF Additional information: This media type is a product of the IETF
WEIRDS working group. The WEIRDS charter, information on the WEIRDS working group. The WEIRDS charter, information on the
WEIRDS mailing list, and other documents produced by the WEIRDS WEIRDS mailing list, and other documents produced by the WEIRDS
working group can be found at https://datatracker.ietf.org/wg/ working group can be found at https://datatracker.ietf.org/wg/
weirds/ [1] weirds/
Person & email address to contact for further information: Andy Person & email address to contact for further information: Andy
Newton <andy@hxr.us> Newton <andy@hxr.us>
Intended usage: COMMON Intended usage: COMMON
Restrictions on usage: none Restrictions on usage: none
Author: Andy Newton Author: Andy Newton
Change controller: IETF Change controller: IETF
Provisional Registration: No (upon publication of this RFC) Provisional Registration: No (upon publication of this RFC)
10.2. JSON Values Registry 11.2. JSON Values Registry
This section requests that the IANA establish an RDAP JSON Values This section requests that the IANA establish an RDAP JSON Values
Registry for use in the status (Section 5.6), role (Section 6.1), Registry for use in the status (Section 5.6), role (Section 6.1),
event action (Section 5.5), and domain variant relation (Section 6.3) event action (Section 5.5), and domain variant relation (Section 6.3)
fields specified in RDAP. fields specified in RDAP.
Each entry in the registry should contain the following fields: Each entry in the registry should contain the following fields:
1. Value - the string value being registered. 1. Value - the string value being registered.
skipping to change at page 52, line 9 skipping to change at page 53, line 5
denote a holder of a domain name or Internet number resource. In denote a holder of a domain name or Internet number resource. In
cases where it may be reasonably argued that machine cases where it may be reasonably argued that machine
interpretation of two similar values may alter the operation of interpretation of two similar values may alter the operation of
client software, designated experts should not judge the values client software, designated experts should not judge the values
to be of significant similarity. to be of significant similarity.
4. Registrations should be relevant to the common usages of RDAP. 4. Registrations should be relevant to the common usages of RDAP.
Designated experts may rely upon the serving of the value by a Designated experts may rely upon the serving of the value by a
DNR or RIR to make this determination. DNR or RIR to make this determination.
10.2.1. Status 11.2.1. Status
This section registers the following values into the RDAP JSON Values This section registers the following values into the RDAP JSON Values
Registry: Registry:
1. 1.
* Value: validated * Value: validated
* Type: status * Type: status
skipping to change at page 57, line 22 skipping to change at page 58, line 19
* Description: A request has been received for the deletion or * Description: A request has been received for the deletion or
removal of the object instance but this action is not yet removal of the object instance but this action is not yet
complete. For domains, this might mean that the name in no complete. For domains, this might mean that the name in no
longer published in DNS but has not yet been purged from the longer published in DNS but has not yet been purged from the
registry database. registry database.
* Registrant Name: Andrew Newton * Registrant Name: Andrew Newton
* Registrant Contact Information: andy@hxr.us * Registrant Contact Information: andy@hxr.us
10.2.2. Event Actions 11.2.2. Event Actions
This section registers the following values into the RDAP JSON Values This section registers the following values into the RDAP JSON Values
Registry: Registry:
1. 1.
* Value: registration * Value: registration
* Type: event action * Type: event action
skipping to change at page 60, line 5 skipping to change at page 60, line 44
* Type: event action * Type: event action
* Description: The object instance was unlocked (see the * Description: The object instance was unlocked (see the
'locked' status). 'locked' status).
* Registrant Name: Andrew Newton * Registrant Name: Andrew Newton
* Registrant Contact Information: andy@hxr.us * Registrant Contact Information: andy@hxr.us
10.2.3. Roles 11.2.3. Roles
This section registers the following values into the RDAP JSON Values This section registers the following values into the RDAP JSON Values
Registry: Registry:
1. 1.
* Value: registrant * Value: registrant
* Type: role * Type: role
* Description: The entity object instance is the registrant of * Description: The entity object instance is the registrant of
the registration. In some registries, this is known as a the registration. In some registries, this is known as a
maintainer. maintainer.
* Registrant Name: Andrew Newton * Registrant Name: Andrew Newton
* Registrant Contact Information: andy@hxr.us * Registrant Contact Information: andy@hxr.us
skipping to change at page 63, line 4 skipping to change at page 63, line 42
* Registrant Name: Andrew Newton * Registrant Name: Andrew Newton
* Registrant Contact Information: andy@hxr.us * Registrant Contact Information: andy@hxr.us
11. 11.
* Value: noc * Value: noc
* Type: role * Type: role
* Description: The entity object instance handles * Description: The entity object instance handles
communications related to a network operations center (NOC). communications related to a network operations center (NOC).
* Registrant Name: Andrew Newton * Registrant Name: Andrew Newton
* Registrant Contact Information: andy@hxr.us * Registrant Contact Information: andy@hxr.us
10.2.4. Variant Relations 11.2.4. Variant Relations
This section registers the following values into the RDAP JSON Values This section registers the following values into the RDAP JSON Values
Registry: Registry:
1. 1.
* Value: registered * Value: registered
* Type: domain variant relation * Type: domain variant relation
skipping to change at page 64, line 32 skipping to change at page 65, line 25
* Type: domain variant relation * Type: domain variant relation
* Description: Registration of the variant names occurs * Description: Registration of the variant names occurs
automatically with the registration of the containing domain automatically with the registration of the containing domain
registration. registration.
* Registrant Name: Andrew Newton * Registrant Name: Andrew Newton
* Registrant Contact Information: andy@hxr.us * Registrant Contact Information: andy@hxr.us
11. Security Considerations 12. Security Considerations
This specification models information serialized in JSON format. As This specification models information serialized in JSON format. As
JSON is a subset of Javascript, implementations are advised to follow JSON is a subset of Javascript, implementations are advised to follow
the security considerations outlined in Section 6 of [RFC4627] to the security considerations outlined in Section 6 of [RFC4627] to
prevent code injection. prevent code injection.
12. Internationalization Considerations 13. Internationalization Considerations
12.1. Character Encoding 13.1. Character Encoding
The default text encoding for JSON and XML responses in RDAP is UTF-8 The default text encoding for JSON and XML responses in RDAP is UTF-8
[RFC3629], and all servers and clients MUST support UTF-8. Servers [RFC3629], and all servers and clients MUST support UTF-8. Servers
and clients MAY optionally support other character encodings. and clients MAY optionally support other character encodings.
12.2. URIs and IRIs 13.2. URIs and IRIs
[I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in [I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in
RDAP. RDAP.
12.3. Language Tags 13.3. Language Tags
Section 5.4 defines the use of language tags in the JSON responses Section 5.4 defines the use of language tags in the JSON responses
defined in this document. defined in this document.
12.4. Internationalized Domain Names 13.4. Internationalized Domain Names
Internationalized Domain Names (IDNs) are denoted in this Internationalized Domain Names (IDNs) are denoted in this
specification by the separation of DNS names in LDH form and Unicode specification by the separation of DNS names in LDH form and Unicode
form (see Section 4). Representation of IDNs in registries is form (see Section 4). Representation of IDNs in registries is
described by the "variants" object in Section 6.3 and the suggested described by the "variants" object in Section 6.3 and the suggested
values listed in Section 10.2.4. values listed in Section 11.2.4.
13. Privacy Considerations 14. Privacy Considerations
This specification suggests status values to denote contact and This specification suggests status values to denote contact and
registrant information that has been marked as private and/or has registrant information that has been marked as private and/or has
been redacted or obscured. See Section 10.2.1 for the list of status been redacted or obscured. See Section 11.2.1 for the list of status
values. See Appendix A.1 on guidance to apply those values to values. See Appendix A.1 on guidance to apply those values to
contacts and registrants. contacts and registrants.
14. Contributing Authors and Acknowledgements 15. Contributing Authors and Acknowledgements
This document is derived from original work on RIR responses in JSON This document is derived from original work on RIR responses in JSON
by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew L. by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew L.
Newton. Additionally, this document incorporates word on DNR Newton. Additionally, this document incorporates word on DNR
responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean
Shen. Shen.
The components of the DNR object classes are derived from a The components of the DNR object classes are derived from a
categorization of WHOIS response formats created by Ning Kong, Linlin categorization of WHOIS response formats created by Ning Kong, Linlin
Zhou, and Guangqing Deng, Steve Sheng and Francisco Arias, Ray Zhou, and Guangqing Deng, Steve Sheng and Francisco Arias, Ray
skipping to change at page 66, line 5 skipping to change at page 67, line 5
domain names. domain names.
Ernie Dainow provided the background information on the secure DNSSEC Ernie Dainow provided the background information on the secure DNSSEC
attributes and objects for domains, informative text on DNSSEC, and attributes and objects for domains, informative text on DNSSEC, and
many other attributes that appear throughout the object classes of many other attributes that appear throughout the object classes of
this draft. this draft.
The switch to and incorporation of JSON vCard was performed by Simon The switch to and incorporation of JSON vCard was performed by Simon
Perreault. Perreault.
15. References 16. References
15.1. Normative References 16.1. Normative References
[RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September
1981. 1981.
[RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet
numbers", RFC 1166, July 1990. numbers", RFC 1166, July 1990.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
skipping to change at page 67, line 12 skipping to change at page 68, line 12
Applications (IDNA): Definitions and Document Framework", Applications (IDNA): Definitions and Document Framework",
RFC 5890, August 2010. RFC 5890, August 2010.
[RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
Address Text Representation", RFC 5952, August 2010. Address Text Representation", RFC 5952, August 2010.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[I-D.ietf-jcardcal-jcard] [I-D.ietf-jcardcal-jcard]
Kewisch, P., "jCard: The JSON format for vCard", draft- Kewisch, P., "jCard: The JSON format for vCard", draft-
ietf-jcardcal-jcard-06 (work in progress), September 2013. ietf-jcardcal-jcard-07 (work in progress), October 2013.
[I-D.ietf-weirds-using-http] [I-D.ietf-weirds-using-http]
Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the
Registration Data Access Protocol (RDAP)", draft-ietf- Registration Data Access Protocol (RDAP)", draft-ietf-
weirds-using-http-07 (work in progress), July 2013. weirds-using-http-08 (work in progress), February 2014.
[I-D.ietf-weirds-rdap-query] [I-D.ietf-weirds-rdap-query]
Newton, A. and S. Hollenbeck, "Registration Data Access Newton, A. and S. Hollenbeck, "Registration Data Access
Protocol Query Format", draft-ietf-weirds-rdap-query-07 Protocol Query Format", draft-ietf-weirds-rdap-query-10
(work in progress), October 2013. (work in progress), February 2014.
[ISO.3166.1988] [ISO.3166.1988]
International Organization for Standardization, "Codes for International Organization for Standardization, "Codes for
the representation of names of countries, 3rd edition", the representation of names of countries, 3rd edition",
ISO Standard 3166, August 1988. ISO Standard 3166, August 1988.
15.2. Informative References 16.2. Informative References
[RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
September 2004. September 2004.
[RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
STD 69, RFC 5730, August 2009. STD 69, RFC 5730, August 2009.
[RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS)
Security Extensions Mapping for the Extensible Security Extensions Mapping for the Extensible
Provisioning Protocol (EPP)", RFC 5910, May 2010. Provisioning Protocol (EPP)", RFC 5910, May 2010.
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
August 2011. August 2011.
[RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type
Structured Syntax Suffixes", RFC 6839, January 2013. Structured Syntax Suffixes", RFC 6839, January 2013.
[JSON_acendancy] [JSON_acendancy]
MacVittie, ., "The Stealthy Ascendancy of JSON", 04 2011. MacVittie, , "The Stealthy Ascendancy of JSON", 04 2011.
[IANA_IDNTABLES] [IANA_IDNTABLES]
, "IANA IDN Tables", , "IANA IDN Tables",
<http://www.iana.org/domains/idn-tables>. <http://www.iana.org/domains/idn-tables>.
[JSON_performance_study] [JSON_performance_study]
Montana State University - Bozeman, Montana State Montana State University - Bozeman, Montana State
University - Bozeman, Montana State University - Bozeman, University - Bozeman, Montana State University - Bozeman,
Montana State University - Bozeman, "Comparison of JSON and Montana State University - Bozeman, "Comparison of
and XML Data Interchange Formats: A Case Study", 2009. JSON and XML Data Interchange Formats: A Case Study",
2009.
Appendix A. Suggested Data Modeling with the Entity Object Class Appendix A. Suggested Data Modeling with the Entity Object Class
A.1. Registrants and Contacts A.1. Registrants and Contacts
This document does not provide specific object classes for This document does not provide specific object classes for
registrants and contacts. Instead the entity object class may be registrants and contacts. Instead the entity object class may be
used to represent a registrant or contact. When the entity object is used to represent a registrant or contact. When the entity object is
embedded inside a containing object such as a domain name or IP embedded inside a containing object such as a domain name or IP
network, the 'roles' string array can be used to signify the network, the 'roles' string array can be used to signify the
relationship. It is recommended that the values from Section 10.2.3 relationship. It is recommended that the values from Section 11.2.3
be used. be used.
The following is an example of an elided containing object with an The following is an example of an elided containing object with an
embedded entity that is both a registrant and admin contact: embedded entity that is both a registrant and administrative contact:
{ {
... ...
"entities" : "entities" :
[ [
{ {
"handle" : "XXXX", "handle" : "XXXX",
"vcardArray":[ "vcardArray":[
"vcard", "vcard",
[ [
skipping to change at page 69, line 25 skipping to change at page 70, line 25
["tel", ["tel",
{ "type":["work", "voice"], "pref":"1" }, { "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102" "uri", "tel:+1-555-555-1234;ext=102"
], ],
["email", ["email",
{ "type":"work" }, { "type":"work" },
"text", "joe.user@example.com" "text", "joe.user@example.com"
], ],
] ]
], ],
"roles" : [ "registrant", "admin" ], "roles" : [ "registrant", "administrative" ],
"remarks" : "remarks" :
[ [
{ {
"description" : "description" :
[ [
"She sells sea shells down by the sea shore.", "She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan." "Originally written by Terry Sullivan."
] ]
} }
], ],
skipping to change at page 70, line 7 skipping to change at page 71, line 7
"eventAction" : "last changed", "eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:60Z" "eventDate" : "1991-12-31T23:59:60Z"
} }
] ]
} }
] ]
} }
In many use cases, it is necessary to hide or obscure the information In many use cases, it is necessary to hide or obscure the information
of a registrant or contact due to policy or other operational of a registrant or contact due to policy or other operational
matters. Registries can denote these situations with 'status' values matters. Registries can denote these situations with 'status' values
(see Section 10.2.1). (see Section 11.2.1).
The following is an elided example of a registrant with information The following is an elided example of a registrant with information
changed to reflect that of a third party. changed to reflect that of a third party.
{ {
... ...
"entities" : "entities" :
[ [
{ {
"handle" : "XXXX", "handle" : "XXXX",
... ...
"roles" : [ "registrant", "admin" ], "roles" : [ "registrant", "administrative" ],
"status" : [ "proxy", "private", "obscured" ] "status" : [ "proxy", "private", "obscured" ]
} }
] ]
} }
A.2. Registrars A.2. Registrars
This document does not provide a specific object class for This document does not provide a specific object class for
registrars, but like registrants and contacts (see Appendix A.1) the registrars, but like registrants and contacts (see Appendix A.1) the
'roles' string array maybe used. Additionally, many registrars have 'roles' string array maybe used. Additionally, many registrars have
skipping to change at page 72, line 47 skipping to change at page 73, line 45
This is an example of an "events" array without the 'eventActor'. This is an example of an "events" array without the 'eventActor'.
"events" : "events" :
[ [
{ {
"eventAction" : "registration", "eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:60Z" "eventDate" : "1990-12-31T23:59:60Z"
} }
] ]
Figure 20 Figure 21
For the second use case, the 'events' data structure (Section 5.5) is For the second use case, the 'events' data structure (Section 5.5) is
used with the 'eventActor' object member. used with the 'eventActor' object member.
This is an example of an "events" array with the 'eventActor'. This is an example of an "events" array with the 'eventActor'.
"events" : "events" :
[ [
{ {
"eventAction" : "registration", "eventAction" : "registration",
"eventActor" : "XYZ-NIC", "eventActor" : "XYZ-NIC",
"eventDate" : "1990-12-31T23:59:60Z" "eventDate" : "1990-12-31T23:59:60Z"
} }
] ]
Figure 21 Figure 22
For the third use case, the 'asEventActor' array is used when an For the third use case, the 'asEventActor' array is used when an
entity (Section 6.1) is embedded into another object class. The entity (Section 6.1) is embedded into another object class. The
'asEventActor' array follows the same structure as the 'events' array 'asEventActor' array follows the same structure as the 'events' array
but does not have 'eventActor' attributes. but does not have 'eventActor' attributes.
The following is an elided example of a domain object with an entity The following is an elided example of a domain object with an entity
as an event actor. as an event actor.
{ {
skipping to change at page 75, line 47 skipping to change at page 76, line 48
"uri", "http://www.example.com/joe.user/joe.asc" "uri", "http://www.example.com/joe.user/joe.asc"
], ],
["tz", {}, ["tz", {},
"utc-offset", "-05:00"], "utc-offset", "-05:00"],
["url", { "type":"home" }, ["url", { "type":"home" },
"uri", "http://example.org"] "uri", "http://example.org"]
] ]
] ]
} }
Figure 22 Figure 23
The arrays in Figure 22 with the first member of "adr" represent The arrays in Figure 23 with the first member of "adr" represent
postal addresses. In the first example, the postal address is given postal addresses. In the first example, the postal address is given
as a an array of strings and constitutes a structured address. For as a an array of strings and constitutes a structured address. For
components of the structured address that are not applicable, an components of the structured address that are not applicable, an
empty string is given. Each member of that array aligns with the empty string is given. Each member of that array aligns with the
positions of a vCard as given in [RFC6350]. In this example, the positions of a vCard as given in [RFC6350]. In this example, the
following data corresponds to the following positional meanings: following data corresponds to the following positional meanings:
1. post office box - not applicable, empty string 1. post office box - not applicable, empty string
2. extended address (e.g., apartment or suite number) - Suite 1234 2. extended address (e.g., apartment or suite number) - Suite 1234
skipping to change at page 82, line 4 skipping to change at page 83, line 11
Changed flags and protocols to integers in keyData. Changed flags and protocols to integers in keyData.
Added 'entities' to the specified list for autnum. Added 'entities' to the specified list for autnum.
Added SHOULD/SHOULD NOT language about using "type": Added SHOULD/SHOULD NOT language about using "type":
"application/rdap+json" for self links. "application/rdap+json" for self links.
Added 'port43' to ip networks and autnum. Added 'port43' to ip networks and autnum.
-06 -06
Fix search response example. Fix search response example.
Change the returned search arrays to 'domainSearchResults', Change the returned search arrays to 'domainSearchResults',
'entitySearchResults', and 'nameserverSearchResults'. 'entitySearchResults', and 'nameserverSearchResults'.
-07
'nameservers' in domain object class was changed to
'nameServers' as in the example (note the camel case)
fixed some example per email from James Mitchel
fixed an example per email from Simon Perreault
Added "network" to domain object class.
Added networks and autnums to the entity object class.
Authors' Addresses Authors' Addresses
Andrew Lee Newton Andrew Lee Newton
American Registry for Internet Numbers American Registry for Internet Numbers
3635 Concorde Parkway 3635 Concorde Parkway
Chantilly, VA 20151 Chantilly, VA 20151
US US
Email: andy@arin.net Email: andy@arin.net
URI: http://www.arin.net URI: http://www.arin.net
 End of changes. 66 change blocks. 
110 lines changed or deleted 181 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/