draft-ietf-weirds-json-response-11.txt   draft-ietf-weirds-json-response-12.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 30, 2015 Verisign Labs Expires: May 23, 2015 Verisign Labs
October 27, 2014 November 19, 2014
JSON Responses for the Registration Data Access Protocol (RDAP) JSON Responses for the Registration Data Access Protocol (RDAP)
draft-ietf-weirds-json-response-11 draft-ietf-weirds-json-response-12
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 30, 2015. This Internet-Draft will expire on May 23, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 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
skipping to change at page 3, line 4 skipping to change at page 3, line 4
10.2.4. Roles . . . . . . . . . . . . . . . . . . . . . . . 66 10.2.4. Roles . . . . . . . . . . . . . . . . . . . . . . . 66
10.2.5. Variant Relations . . . . . . . . . . . . . . . . . 69 10.2.5. Variant Relations . . . . . . . . . . . . . . . . . 69
11. Security Considerations . . . . . . . . . . . . . . . . . . . 70 11. Security Considerations . . . . . . . . . . . . . . . . . . . 70
12. Internationalization Considerations . . . . . . . . . . . . . 71 12. Internationalization Considerations . . . . . . . . . . . . . 71
12.1. Character Encoding . . . . . . . . . . . . . . . . . . . 71 12.1. Character Encoding . . . . . . . . . . . . . . . . . . . 71
12.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 71 12.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 71
12.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 71 12.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 71
12.4. Internationalized Domain Names . . . . . . . . . . . . . 71 12.4. Internationalized Domain Names . . . . . . . . . . . . . 71
13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 71 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 71
14. Contributing Authors and Acknowledgements . . . . . . . . . . 72 14. Contributing Authors and Acknowledgements . . . . . . . . . . 72
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 72 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 73
15.1. Normative References . . . . . . . . . . . . . . . . . . 72 15.1. Normative References . . . . . . . . . . . . . . . . . . 73
15.2. Informative References . . . . . . . . . . . . . . . . . 74 15.2. Informative References . . . . . . . . . . . . . . . . . 74
Appendix A. Suggested Data Modeling with the Entity Object Class 74 Appendix A. Suggested Data Modeling with the Entity Object Class 75
A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 74 A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 75
A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 77 A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 77
Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 79 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 79
Appendix C. Structured vs Unstructured Addresses . . . . . . . . 81 Appendix C. Structured vs Unstructured Addresses . . . . . . . . 81
Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 83 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 84
Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 84 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 84
Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . 84 Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . 85
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 91
1. Introduction 1. Introduction
This document describes responses in the JSON [RFC7159] format for This document describes responses in the JSON [RFC7159] format for
the queries as defined by the Registration Data Access Protocol the queries as defined by the Registration Data Access Protocol
Lookup Format [I-D.ietf-weirds-rdap-query]. Lookup Format [I-D.ietf-weirds-rdap-query].
[I-D.ietf-weirds-using-http] describes a communication protocol for [I-D.ietf-weirds-using-http] describes a communication protocol for
exchanging queries and responses. exchanging queries and responses.
1.1. Terminology and Definitions 1.1. Terminology and Definitions
skipping to change at page 10, line 45 skipping to change at page 10, line 45
}, },
{ {
"value" : "http://example.com/ip/2001:db8::123", "value" : "http://example.com/ip/2001:db8::123",
"rel" : "up", "rel" : "up",
"href" : "http://example.com/ip/2001:db8::/48", "href" : "http://example.com/ip/2001:db8::/48",
"type" : "application/rdap+json" "type" : "application/rdap+json"
} }
] ]
Figure 6
4.3. Notices And Remarks 4.3. Notices And Remarks
The "notices" and "remarks" data structures take the same form. The The "notices" and "remarks" data structures take the same form. The
"notices" structure denotes information about the service providing "notices" structure denotes information about the service providing
RDAP information and/or information about the entire response, RDAP information and/or information about the entire response,
whereas the "remarks" structure denotes information about the object whereas the "remarks" structure denotes information about the object
class that contains it (see Section 5 regarding object classes). class that contains it (see Section 5 regarding object classes).
Both are arrays of objects. Each object contains an optional "title" Both are arrays of objects. Each object contains an optional "title"
string representing the title of the object, an optional "type" string representing the title of the object, an optional "type"
skipping to change at page 11, line 35 skipping to change at page 11, line 37
{ {
"value" : "http://example.net/entity/XXXX", "value" : "http://example.net/entity/XXXX",
"rel" : "alternate", "rel" : "alternate",
"type" : "text/html", "type" : "text/html",
"href" : "http://www.example.com/terms_of_use.html" "href" : "http://www.example.com/terms_of_use.html"
} }
] ]
} }
] ]
Figure 6 Figure 7
It is the job of the clients to determine line breaks, spacing and It is the job of the clients to determine line breaks, spacing and
display issues for sentences within the character strings of the display issues for sentences within the character strings of the
"description" array. Each string in the "description" array contains "description" array. Each string in the "description" array contains
a single complete division of human readable text indicating to a single complete division of human readable text indicating to
clients where there are semantic breaks. clients where there are semantic breaks.
An example of the remarks data structure: An example of the remarks data structure:
"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."
] ]
} }
] ]
Figure 7 Figure 8
Note that objects in the "remarks" array may also have a "links" Note that objects in the "remarks" array may also have a "links"
array. array.
While the "title" and "description" fields are intended primarily for While the "title" and "description" fields are intended primarily for
human consumption, the "type" string contains a well-known value to human consumption, the "type" string contains a well-known value to
be registered with IANA (see Section 10.2.1) for programmatic use. be registered with IANA (see Section 10.2.1) for programmatic use.
An example of the remarks data structure: An example of the remarks data structure:
skipping to change at page 12, line 41 skipping to change at page 12, line 41
{ {
"type" : "object truncated due to authorization", "type" : "object truncated due to authorization",
"description" : "description" :
[ [
"Some registration data may not have been given.", "Some registration data may not have been given.",
"Use proper authorization credentials to see all of it." "Use proper authorization credentials to see all of it."
] ]
} }
] ]
Figure 8 Figure 9
While the "remarks" array will appear in many object classes in a While the "remarks" array will appear in many object classes in a
response, the "notices" array appears only in the top most object of response, the "notices" array appears only in the top most object of
a response. a response.
4.4. Language Identifier 4.4. Language Identifier
This data structure consists solely of a name/value pair, where the This data structure consists solely of a name/value pair, where the
name is "lang" and the value is a string containing a language name is "lang" and the value is a string containing a language
identifier as described in [RFC5646]. identifier as described in [RFC5646].
"lang" : "mn-Cyrl-MN" "lang" : "mn-Cyrl-MN"
Figure 9 Figure 10
The 'lang' attribute may appear anywhere in an object class or data The 'lang' attribute may appear anywhere in an object class or data
structure except for in jCard objects. structure except for in jCard objects.
4.5. Events 4.5. Events
This data structure represents events that have occurred on an This data structure represents events that have occurred on an
instance of an object class (see Section 5 regarding object classes). instance of an object class (see Section 5 regarding object classes).
This is an example of an "events" array. This is an example of an "events" array.
skipping to change at page 13, line 33 skipping to change at page 13, line 33
"eventActor" : "SOMEID-LUNARNIC", "eventActor" : "SOMEID-LUNARNIC",
"eventDate" : "1990-12-31T23:59:59Z" "eventDate" : "1990-12-31T23:59:59Z"
}, },
{ {
"eventAction" : "last changed", "eventAction" : "last changed",
"eventActor" : "OTHERID-LUNARNIC", "eventActor" : "OTHERID-LUNARNIC",
"eventDate" : "1991-12-31T23:59:59Z" "eventDate" : "1991-12-31T23:59:59Z"
} }
] ]
Figure 10 Figure 11
The "events" array consists of objects, each with the following The "events" array consists of objects, each with the following
members: members:
o 'eventAction' -- a string denoting the reason for the event o 'eventAction' -- a string denoting the reason for the event
o 'eventActor' -- an optional identifier denoting the actor o 'eventActor' -- an optional identifier denoting the actor
responsible for the event responsible for the event
o 'eventDate' -- a string containing the time and date the event o 'eventDate' -- a string containing the time and date the event
skipping to change at page 14, line 43 skipping to change at page 14, line 43
The following is an example of a 'publicIds' structure. The following is an example of a 'publicIds' structure.
"publicIds": "publicIds":
[ [
{ {
"type":"IANA Registrar ID", "type":"IANA Registrar ID",
"identifier":"1" "identifier":"1"
} }
] ]
Figure 11 Figure 12
4.9. Object Class Name 4.9. Object Class Name
This data structure, a member named "objectClassName", gives the This data structure, a member named "objectClassName", gives the
object class name of a particular object as a string. This object class name of a particular object as a string. This
identifies the type of object being processed. An objectClassName is identifies the type of object being processed. An objectClassName is
REQUIRED in all RDAP response objects so that the type of the object REQUIRED in all RDAP response objects so that the type of the object
can be interpreted. can be interpreted.
4.10. An Example 4.10. An Example
skipping to change at page 16, line 50 skipping to change at page 16, line 50
{ {
"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."
] ]
} }
] ]
} }
Figure 12 Figure 13
5. Object Classes 5. Object Classes
Object classes represent structures appropriate for a response from Object classes represent structures appropriate for a response from
the queries specified in [I-D.ietf-weirds-rdap-query]. the queries specified in [I-D.ietf-weirds-rdap-query].
Each object class contains a "links" array as specified in Each object class contains a "links" array as specified in
Section 4.2. For every object class instance in a response, whether Section 4.2. For every object class instance in a response, whether
the object class instance is directly representing the response to a the object class instance is directly representing the response to a
query or is embedded in other object class instances or is an item in query or is embedded in other object class instances or is an item in
skipping to change at page 17, line 46 skipping to change at page 17, line 46
"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"
} }
] ]
Figure 14
5.1. The Entity Object Class 5.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
them in JSON [RFC7159] with one construct, the entity object class, them in JSON [RFC7159] with one construct, the entity object class,
to aid in the re-use of code by implementers. to aid in the re-use of code by implementers.
The entity object class uses jCard [RFC7095] to represent contact
information, such as postal addresses, email addresses, phone numbers
and names of organizations and individuals. Many of the types of
information that can be represented with jCard have no use in RDAP,
such as birthdays, anniversaries, and gender.
The entity object is served by both RIRs and DNRs. The following is The entity object is served by both RIRs and DNRs. The following is
an example of an entity that might be served by an RIR. an example of an entity that might be served by an RIR.
{ {
"objectClassName" : "entity", "objectClassName" : "entity",
"handle":"XXXX", "handle":"XXXX",
"vcardArray":[ "vcardArray":[
"vcard", "vcard",
[ [
["version", {}, "text", "4.0"], ["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"], ["fn", {}, "text", "Joe User"],
["n", {}, "text", ["n", {}, "text",
["User", "Joe", "", "", ["ing. jr", "M.Sc."]] ["User", "Joe", "", "", ["ing. jr", "M.Sc."]]
], ],
["bday", {}, "date-and-or-time", "--02-03"],
["anniversary",
{}, "date-and-or-time", "2009-08-08T14:30:00-05:00"
],
["gender", {}, "text", "M"],
["kind", {}, "text", "individual"], ["kind", {}, "text", "individual"],
["lang", { ["lang", {
"pref":"1" "pref":"1"
}, "language-tag", "fr"], }, "language-tag", "fr"],
["lang", { ["lang", {
"pref":"2" "pref":"2"
}, "language-tag", "en"], }, "language-tag", "en"],
["org", { ["org", {
"type":"work" "type":"work"
}, "text", "Example"], }, "text", "Example"],
skipping to change at page 20, line 37 skipping to change at page 20, line 40
} }
], ],
"asEventActor":[ "asEventActor":[
{ {
"eventAction":"last changed", "eventAction":"last changed",
"eventDate":"1991-12-31T23:59:59Z" "eventDate":"1991-12-31T23:59:59Z"
} }
] ]
} }
Figure 15
This object has the following members: This object has the following members:
o objectClassName -- the string "entity" o objectClassName -- the string "entity"
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 jCard with the entity's contact information o vcardArray -- a jCard 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.4 for a list of values) Section 10.2.4 for a list of values)
o publicIds - see Section 4.8 o publicIds - see Section 4.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 4.3 o remarks -- see Section 4.3
o links -- see Section 4.2 o links -- see Section 4.2
o events -- see Section 4.5 o events -- see Section 4.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 4.5), but each object in the 'events' data structure (see Section 4.5), but each object in the
skipping to change at page 22, line 26 skipping to change at page 22, line 26
"objectClassName" : "entity", "objectClassName" : "entity",
"handle": "ANEMBEDDEDENTITY", "handle": "ANEMBEDDEDENTITY",
"roles" : [ "technical" ], "roles" : [ "technical" ],
... ...
}, },
... ...
], ],
... ...
} }
Figure 13 Figure 16
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. DNR.
{ {
"objectClassName" : "entity", "objectClassName" : "entity",
"handle":"XXXX", "handle":"XXXX",
"vcardArray":[ "vcardArray":[
"vcard", "vcard",
[ [
skipping to change at page 24, line 11 skipping to change at page 24, line 11
"eventDate":"1990-12-31T23:59:59Z" "eventDate":"1990-12-31T23:59:59Z"
}, },
{ {
"eventAction":"last changed", "eventAction":"last changed",
"eventDate":"1991-12-31T23:59:59Z", "eventDate":"1991-12-31T23:59:59Z",
"eventActor":"joe@example.com" "eventActor":"joe@example.com"
} }
] ]
} }
Figure 17
See Appendix A for use of the entity object class to model various See Appendix A for use of the entity object class to model various
types of entities found in both RIRs and DNRs. See Appendix C types of entities found in both RIRs and DNRs. See Appendix C
regarding structured vs. unstructured postal addresses in entities. regarding structured vs. unstructured postal addresses in entities.
5.2. The Nameserver Object Class 5.2. The Nameserver Object Class
The nameserver object class represents information regarding DNS name The nameserver object class represents information regarding DNS name
servers used in both forward and reverse DNS. RIRs and some DNRs servers used in both forward and reverse DNS. RIRs and some DNRs
register or expose nameserver information as an attribute of a domain register or expose nameserver information as an attribute of a domain
name, while other DNRs model nameservers as "first class objects". name, while other DNRs model nameservers as "first class objects".
skipping to change at page 25, line 50 skipping to change at page 25, line 50
"eventDate" : "1990-12-31T23:59:59Z" "eventDate" : "1990-12-31T23:59:59Z"
}, },
{ {
"eventAction" : "last changed", "eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z", "eventDate" : "1991-12-31T23:59:59Z",
"eventActor" : "joe@example.com" "eventActor" : "joe@example.com"
} }
] ]
} }
Figure 14 Figure 18
Figure 14 is an example of a nameserver object with all values given. Figure 18 is an example of a nameserver object with all values given.
Registries using a first-class nameserver data model would embed this Registries using a first-class nameserver data model would embed this
in domain objects as well as allowing references to it with the in domain objects as well as allowing references to it with the
"/nameserver" query type (all depending on the registry operators "/nameserver" query type (all depending on the registry operators
policy). Other registries may pare back the information as needed. policy). Other registries may pare back the information as needed.
Figure 15 is an example of a nameserver object as would be found in Figure 19 is an example of a nameserver object as would be found in
RIRs and some DNRs, while Figure 16 is an example of a nameserver RIRs and some DNRs, while Figure 20 is an example of a nameserver
object as would be found in other DNRs. object as would be found in other DNRs.
The following is an example of the simplest nameserver object: The following is an example of the simplest nameserver object:
{ {
"objectClassName" : "nameserver", "objectClassName" : "nameserver",
"ldhName" : "ns1.example.com" "ldhName" : "ns1.example.com"
} }
Figure 15 Figure 19
The following is an example of a simple nameserver object that might The following is an example of a simple nameserver object that might
be commonly used by DNRs: be commonly used by DNRs:
{ {
"objectClassName" : "nameserver", "objectClassName" : "nameserver",
"ldhName" : "ns1.example.com", "ldhName" : "ns1.example.com",
"ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] }
} }
Figure 16 Figure 20
As nameservers can be modeled by some registries to be first-class As nameservers can be modeled by some registries to be first-class
objects, they may also have an array of entities (Section 5.1) objects, they may also have an array of entities (Section 5.1)
embedded to signify parties responsible for the maintenance, embedded to signify parties responsible for the maintenance,
registrations, etc. of the nameservers. registrations, etc. of the nameservers.
The following is an elided example of a nameserver with embedded The following is an elided example of a nameserver with embedded
entities. entities.
{ {
skipping to change at page 27, line 20 skipping to change at page 27, line 20
"handle" : "XXXX", "handle" : "XXXX",
"ldhName" : "ns1.xn--fo-5ja.example", "ldhName" : "ns1.xn--fo-5ja.example",
... ...
"entities" : "entities" :
[ [
... ...
], ],
... ...
} }
Figure 17 Figure 21
The nameserver object class has the following members: The nameserver object class has the following members:
o objectClassName - the string "nameserver" o objectClassName - the string "nameserver"
o handle -- a string representing an registry unique identifier of o handle -- a string representing an registry unique identifier of
the nameserver the nameserver
o ldhName -- a string containing the LDH name of the nameserver (see o ldhName -- a string containing the LDH name of the nameserver (see
Section 3) Section 3)
skipping to change at page 28, line 39 skipping to change at page 28, line 39
[ [
... ...
], ],
... ...
"entities" : "entities" :
[ [
... ...
] ]
} }
Figure 22
The following is a description of the members of this object: The following is a description of the members of this object:
o objectClassName -- the string "domain" o objectClassName -- the string "domain"
o handle -- a string representing a registry unique identifier of o handle -- a string representing a registry unique identifier of
the domain object instance the domain object instance
o ldhName -- a string describing a domain name in LDH form as o ldhName -- a string describing a domain name in LDH form as
described in Section 3 described in Section 3
skipping to change at page 34, line 13 skipping to change at page 34, line 13
"endAddress" : "192.0.2.255", "endAddress" : "192.0.2.255",
"ipVersion" : "v6", "ipVersion" : "v6",
"name": "NET-RTR-1", "name": "NET-RTR-1",
"type" : "DIRECT ALLOCATION", "type" : "DIRECT ALLOCATION",
"country" : "AU", "country" : "AU",
"parentHandle" : "YYYY-RIR", "parentHandle" : "YYYY-RIR",
"status" : [ "active" ] "status" : [ "active" ]
} }
} }
Figure 23
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. forward DNS delegation point that might be served by a DNR.
{ {
"objectClassName" : "domain", "objectClassName" : "domain",
"handle" : "XXXX", "handle" : "XXXX",
"ldhName" : "xn--fo-5ja.example", "ldhName" : "xn--fo-5ja.example",
"unicodeName" : "foo.example", "unicodeName" : "foo.example",
"variants" : "variants" :
[ [
skipping to change at page 40, line 5 skipping to change at page 39, line 51
}, },
{ {
"eventAction" : "last changed", "eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z" "eventDate" : "1991-12-31T23:59:59Z"
} }
] ]
} }
] ]
} }
Figure 24
5.4. The IP Network Object Class 5.4. The IP Network Object Class
The IP Network object class models IP network registrations found in The IP Network object class models IP network registrations found in
RIRs and is the expected response for the "/ip" query as defined by RIRs and is the expected response for the "/ip" query as defined by
[I-D.ietf-weirds-rdap-query]. There is no equivalent object class [I-D.ietf-weirds-rdap-query]. There is no equivalent object class
for DNRs. The high level structure of the IP network object class for DNRs. The high level structure of the IP network object class
consists of information about the network registration and entities consists of information about the network registration and entities
related to the IP network (e.g. registrant information, contacts, related to the IP network (e.g. registrant information, contacts,
etc...). etc...).
skipping to change at page 40, line 28 skipping to change at page 40, line 28
{ {
"objectClassName" : "ip network", "objectClassName" : "ip network",
"handle" : "XXX", "handle" : "XXX",
... ...
"entities" : "entities" :
[ [
... ...
] ]
} }
Figure 25
The following is an example of the JSON object for the network The following is an example of the JSON object for the network
registration information. registration information.
{ {
"objectClassName" : "ip network", "objectClassName" : "ip network",
"handle" : "XXXX-RIR", "handle" : "XXXX-RIR",
"startAddress" : "2001:db8::0", "startAddress" : "2001:db8::0",
"endAddress" : "2001:db8:0:FFFF:FFFF:FFFF:FFFF:FFFF", "endAddress" : "2001:db8:0:FFFF:FFFF:FFFF:FFFF:FFFF",
"ipVersion" : "v6", "ipVersion" : "v6",
"name": "NET-RTR-1", "name": "NET-RTR-1",
skipping to change at page 43, line 16 skipping to change at page 43, line 19
}, },
{ {
"eventAction" : "last changed", "eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z" "eventDate" : "1991-12-31T23:59:59Z"
} }
] ]
} }
] ]
} }
Figure 26
The following is a description of the members of this object: The following is a description of the members of this object:
o objectClassName -- the string "ip network" o objectClassName -- the string "ip network"
o handle -- a string representing an RIR unique identifier of the o handle -- a string representing an RIR unique identifier of the
network registration network registration
o startAddress -- the starting IP address of the network, either o startAddress -- the starting IP address of the network, either
IPv4 or IPv6 IPv4 or IPv6
skipping to change at page 46, line 47 skipping to change at page 47, line 4
"eventDate" : "1990-12-31T23:59:59Z" "eventDate" : "1990-12-31T23:59:59Z"
}, },
{ {
"eventAction" : "last changed", "eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z" "eventDate" : "1991-12-31T23:59:59Z"
} }
] ]
} }
] ]
} }
Figure 27
The following is a description of the members of this object: The following is a description of the members of this object:
o objectClassName -- the string "autnum" o objectClassName -- the string "autnum"
o handle -- a string representing an RIR-unique identifier of the o handle -- a string representing an RIR-unique identifier of the
autnum registration autnum registration
o startAutnum -- a number representing the starting number [RFC5396] o startAutnum -- a number representing the starting number [RFC5396]
in the block of autonomous system numbers in the block of autonomous system numbers
o endAutnum -- a number representing the ending number [RFC5396] in o endAutnum -- a number representing the ending number [RFC5396] in
the block of autonomous system numbers the block of autonomous system numbers
o name -- an identifier assigned to the autnum registration by the o name -- an identifier assigned to the autnum registration by the
skipping to change at page 48, line 17 skipping to change at page 48, line 17
{ {
"errorCode": 418, "errorCode": 418,
"title": "Your beverage choice is not available", "title": "Your beverage choice is not available",
"description": "description":
[ [
"I know coffee has more ummppphhh.", "I know coffee has more ummppphhh.",
"Sorry, dude!" "Sorry, dude!"
] ]
} }
Figure 18 Figure 28
This is an example of the common response body with and This is an example of the common response body with and
rdapConformance and notices data structures: rdapConformance and notices data structures:
{ {
"rdapConformance" : "rdapConformance" :
[ [
"rdap_level_0" "rdap_level_0"
], ],
"notices" : "notices" :
skipping to change at page 49, line 42 skipping to change at page 49, line 42
"lang" : "en", "lang" : "en",
"errorCode": 418, "errorCode": 418,
"title": "Your beverage choice is not available", "title": "Your beverage choice is not available",
"description": "description":
[ [
"I know coffee has more ummppphhh.", "I know coffee has more ummppphhh.",
"Sorry, dude!" "Sorry, dude!"
] ]
} }
Figure 19 Figure 29
7. Responding to Help Queries 7. Responding to Help Queries
The appropriate response to /help queries as defined by The appropriate response to /help queries as defined by
[I-D.ietf-weirds-rdap-query] is to use the notices structure as [I-D.ietf-weirds-rdap-query] is to use the notices structure as
defined in Section 4.3. defined in Section 4.3.
This is an example of a response to a /help query including the This is an example of a response to a /help query including the
rdapConformance data structure. rdapConformance data structure.
skipping to change at page 50, line 34 skipping to change at page 50, line 34
"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/auth_policy.html" "href" : "http://www.example.com/auth_policy.html"
} }
] ]
} }
] ]
} }
Figure 20 Figure 30
8. Responding To Searches 8. Responding To Searches
[I-D.ietf-weirds-rdap-query] specifies three types of searches: [I-D.ietf-weirds-rdap-query] specifies three types of searches:
domains, nameservers, and entities. Responses to these searches take domains, nameservers, and entities. Responses to these searches take
the form of an array of object instances where each instance is an the form of an array of object instances where each instance is an
appropriate object class for the search (i.e. a search for /domains appropriate object class for the search (i.e. a search for /domains
yields an array of domain object instances). These arrays are yields an array of domain object instances). These arrays are
contained within the response object. contained within the response object.
skipping to change at page 51, line 34 skipping to change at page 51, line 34
"ldhName" : "2.example.com", "ldhName" : "2.example.com",
... ...
} }
] ]
} }
search_response_example search_response_example
9. Indicating Truncated Responses 9. Indicating Truncated Responses
In cases where the data of a response has been truncated (i.e. not In cases where the data of a response needs to be limited or parts of
all of it has been included in the response), a server may indicate the data need to be omitted, the response is considered "truncated".
this by including a typed notice in the response object. A truncated response is still valid JSON, but some of the results in
a search set or some of the data in an object are not provided by the
server. A server may indicate this by including a typed notice in
the response object.
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 53, line 49 skipping to change at page 53, line 49
"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/data_policy.html" "href" : "http://www.example.com/data_policy.html"
} }
] ]
} }
] ]
} }
Figure 21 Figure 31
10. IANA Considerations 10. IANA Considerations
10.1. RDAP JSON Media Type Registration 10.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
skipping to change at page 72, line 5 skipping to change at page 71, line 48
values listed in Section 10.2.5. values listed in Section 10.2.5.
13. Privacy Considerations 13. 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.2 for the list of status been redacted or obscured. See Section 10.2.2 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.
This specification suggests status values to denote contact and
registrant information that has been marked as private and/or has
been redacted or obscured. See Section 10.2.2 for the complete list
of status values. A few of the status values indicate that there are
privacy concerns associated with the object instance. For the
following status codes, the RECOMMENDED actions include:
private - The object is not be shared in query responses, unless
the user is authorized to view this information.
redacted - Data elements within the object have been collected,
but have been omitted from the response. This option can be used
to prevent unauthorized access to associated object instances
without the need to mark them as private.
obscured - Data elements within the object have been collected,
but the response value has been altered so that values are not
easily discernible. A value changed from "1212" to "XXXX" is an
example of obscured data. This option may reveal privacy
sensitive information and should only be used when data
sensitivity does not require a more protective option like
"private" or "redacted".
See Appendix A.1 for an example applying those values to contacts and
registrants.
14. Contributing Authors and Acknowledgements 14. 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 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew
L. Newton. Additionally, this document incorporates work on DNR L. Newton. Additionally, this document incorporates work 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
skipping to change at page 73, line 37 skipping to change at page 74, line 11
[RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095,
January 2014. January 2014.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[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-13 (work in progress), October 2014. weirds-using-http-14 (work in progress), October 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-15 Protocol Query Format", draft-ietf-weirds-rdap-query-16
(work in progress), October 2014. (work in progress), October 2014.
[I-D.ietf-weirds-rdap-sec] [I-D.ietf-weirds-rdap-sec]
Hollenbeck, S. and N. Kong, "Security Services for the Hollenbeck, S. and N. Kong, "Security Services for the
Registration Data Access Protocol", draft-ietf-weirds- Registration Data Access Protocol", draft-ietf-weirds-
rdap-sec-09 (work in progress), September 2014. rdap-sec-10 (work in progress), October 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 15.2. Informative References
[RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
September 2004. September 2004.
skipping to change at page 76, line 28 skipping to change at page 77, line 4
"eventDate" : "1990-12-31T23:59:59Z" "eventDate" : "1990-12-31T23:59:59Z"
}, },
{ {
"eventAction" : "last changed", "eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z" "eventDate" : "1991-12-31T23:59:59Z"
} }
] ]
} }
] ]
} }
Figure 32
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.2). (see Section 10.2.2).
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.
{ {
skipping to change at page 77, line 22 skipping to change at page 77, line 28
{ {
"objectClassName" : "entity", "objectClassName" : "entity",
"handle" : "XXXX", "handle" : "XXXX",
... ...
"roles" : [ "registrant", "administrative" ], "roles" : [ "registrant", "administrative" ],
"status" : [ "proxy", "private", "obscured" ] "status" : [ "proxy", "private", "obscured" ]
} }
] ]
} }
Figure 33
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
publicly assigned identifiers. The 'publicIds' structure publicly assigned identifiers. The 'publicIds' structure
(Section 4.8) represents that information. (Section 4.8) represents that information.
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 a registrar: embedded entity that is a registrar:
skipping to change at page 79, line 13 skipping to change at page 79, line 22
"value":"http://example.net/entity/XXXX", "value":"http://example.net/entity/XXXX",
"rel":"alternate", "rel":"alternate",
"type":"text/html", "type":"text/html",
"href":"http://www.example.com" "href":"http://www.example.com"
} }
] ]
} }
] ]
} }
Figure 34
Appendix B. Modeling Events Appendix B. Modeling Events
Events represent actions that have taken place against a registered Events represent actions that have taken place against a registered
object at a certain date and time. Events have three properties: the object at a certain date and time. Events have three properties: the
action, the actor, and the date and time of the event (which is action, the actor, and the date and time of the event (which is
sometimes in the future). In some cases the identity of the actor is sometimes in the future). In some cases the identity of the actor is
not captured. not captured.
Events can be modeled in three ways: Events can be modeled in three ways:
skipping to change at page 79, line 42 skipping to change at page 80, line 15
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:59Z" "eventDate" : "1990-12-31T23:59:59Z"
} }
] ]
Figure 22 Figure 35
For the second use case, the 'events' data structure (Section 4.5) is For the second use case, the 'events' data structure (Section 4.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:59Z" "eventDate" : "1990-12-31T23:59:59Z"
} }
] ]
Figure 23 Figure 36
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 5.1) is embedded into another object class. The entity (Section 5.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 81, line 5 skipping to change at page 81, line 30
[ [
{ {
"eventAction" : "last changed", "eventAction" : "last changed",
"eventDate" : "1990-12-31T23:59:59Z" "eventDate" : "1990-12-31T23:59:59Z"
} }
] ]
} }
] ]
} }
Figure 37
Appendix C. Structured vs Unstructured Addresses Appendix C. Structured vs Unstructured Addresses
The entity (Section 5.1) object class uses jCard [RFC7095] to The entity (Section 5.1) object class uses jCard [RFC7095] to
represent contact information, including postal addresses. jCard has represent contact information, including postal addresses. jCard has
the ability to represent multiple language preferences, multiple the ability to represent multiple language preferences, multiple
email address and phone numbers, and multiple postal addresses in email address and phone numbers, and multiple postal addresses in
both a structured and unstructured format. This section describes both a structured and unstructured format. This section describes
the use of jCard for representing structured and unstructured the use of jCard for representing structured and unstructured
addresses. addresses.
skipping to change at page 81, line 23 skipping to change at page 82, line 4
addresses. addresses.
The following is an example of a jCard. The following is an example of a jCard.
{ {
"vcardArray":[ "vcardArray":[
"vcard", "vcard",
[ [
["version", {}, "text", "4.0"], ["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"], ["fn", {}, "text", "Joe User"],
["n", {}, "text", ["n", {}, "text",
["User", "Joe", "", "", ["ing. jr", "M.Sc."]] ["User", "Joe", "", "", ["ing. jr", "M.Sc."]]
], ],
["bday", {}, "date-and-or-time", "--02-03"],
["anniversary",
{}, "date-and-or-time", "2009-08-08T14:30:00-05:00"
],
["gender", {}, "text", "M"],
["kind", {}, "text", "individual"], ["kind", {}, "text", "individual"],
["lang", { ["lang", {
"pref":"1" "pref":"1"
}, "language-tag", "fr"], }, "language-tag", "fr"],
["lang", { ["lang", {
"pref":"2" "pref":"2"
}, "language-tag", "en"], }, "language-tag", "en"],
["org", { ["org", {
"type":"work" "type":"work"
}, "text", "Example"], }, "text", "Example"],
skipping to change at page 82, line 48 skipping to change at page 83, line 25
"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 24 Figure 38
The arrays in Figure 24 with the first member of "adr" represent The arrays in Figure 38 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 90, line 40 skipping to change at page 91, line 13
Addressing many AD comments. Addressing many AD comments.
Changed IANA registrations to IESG. Changed IANA registrations to IESG.
'href' is now the only MUST in the a link. 'href' is now the only MUST in the a link.
-11 -11
Changes to address IETF Last Call comments. Changes to address IETF Last Call comments.
-12
Changes to address IESG comments.
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. 57 change blocks. 
51 lines changed or deleted 109 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/