RFC 7483
JSON Responses for the Registration Data Access Protocol (RDAP)
Part 1 of 12 🎀
JSON Responses for the Registration Data Access Protocol (RDAP) 💖
Okay bestie, the title block is giving everything we need up front 💅. This is RFC 7483, called JSON Responses for the Registration Data Access Protocol (RDAP). The authors are A. Newton from ARIN and S. Hollenbeck from Verisign Labs 🫶. It's a Standards Track doc dated March 2015, with ISSN 2070-1721. The header doesn't list anything it obsoletes or updates, so it's a standalone thing 🌸.
Abstract ✨
So this doc describes the JSON data structures that hold registration info kept by Regional Internet Registries (RIRs) and Domain Name Registries (DNRs) 🌍. Those structures are what get built into Registration Data Access Protocol (RDAP) query responses, and honestly it's the whole point 😭.
Status of This Memo 🦋
Yasss, this is an Internet Standards Track document 🔥.
It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the whole IETF community 🫶. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 5741 💜.
For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7483 🧚.
Copyright Notice 🌈
Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved ✨.
This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stood on the date of publication. Please actually read these, because they spell out your rights and restrictions for this document 🙈. Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, same as the Simplified BSD License says 💅.
Table of Contents 🍓
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology and Definitions . . . . . . . . . . . . . . . 3
1.2. Data Model . . . . . . . . . . . . . . . . . . . . . . . 4
2. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 7
4. Common Data Structures . . . . . . . . . . . . . . . . . . . 8
4.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 8
4.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.3. Notices and Remarks . . . . . . . . . . . . . . . . . . . 10
4.4. Language Identifier . . . . . . . . . . . . . . . . . . . 11
4.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.7. Port 43 WHOIS Server . . . . . . . . . . . . . . . . . . 13
4.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 13
4.9. Object Class Name . . . . . . . . . . . . . . . . . . . . 14
4.10. An Example . . . . . . . . . . . . . . . . . . . . . . . 14
5. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 15
5.1. The Entity Object Class . . . . . . . . . . . . . . . . . 16
5.2. The Nameserver Object Class . . . . . . . . . . . . . . . 22
5.3. The Domain Object Class . . . . . . . . . . . . . . . . . 26
5.4. The IP Network Object Class . . . . . . . . . . . . . . . 38
5.5. Autonomous System Number Entity Object Class . . . . . . 42
6. Error Response Body . . . . . . . . . . . . . . . . . . . . . 45
7. Responding to Help Queries . . . . . . . . . . . . . . . . . 48
8. Responding To Searches . . . . . . . . . . . . . . . . . . . 48
9. Indicating Truncated Responses . . . . . . . . . . . . . . . 49
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52
10.1. RDAP JSON Media Type Registration . . . . . . . . . . . 52
10.2. JSON Values Registry . . . . . . . . . . . . . . . . . . 53
10.2.1. Notice and Remark Types . . . . . . . . . . . . . . 54
10.2.2. Status . . . . . . . . . . . . . . . . . . . . . . . 56
10.2.3. Event Actions . . . . . . . . . . . . . . . . . . . 49
10.2.4. Roles . . . . . . . . . . . . . . . . . . . . . . . 61
10.2.5. Variant Relations . . . . . . . . . . . . . . . . . 63
11. Security Considerations . . . . . . . . . . . . . . . . . . . 64
12. Internationalization Considerations . . . . . . . . . . . . . 64
12.1. Character Encoding . . . . . . . . . . . . . . . . . . . 64
12.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 64
12.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 64
12.4. Internationalized Domain Names . . . . . . . . . . . . . 65
13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 65
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 65
14.1. Normative References . . . . . . . . . . . . . . . . . . 65
14.2. Informative References . . . . . . . . . . . . . . . . . 67
Appendix A. Suggested Data Modeling with the Entity Object Class 68
A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 68
A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 70
Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 72
Appendix C. Structured vs. Unstructured Addresses . . . . . . . 74
Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 76
Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 77
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 77
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 781. Introduction 🌸
This doc describes the responses in the JSON [RFC7159] format for the queries defined by the Registration Data Access Protocol Query Format [RFC7482]. The communication protocol for swapping queries and responses is described in [RFC7480] 🦋.
1.1. Terminology and Definitions 💜
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] when they are specified in their uppercase forms. So the capital ones are the real rules, periodt 💅.
Here's the terminology the doc uses all over the place 🧚:
- DNR: Domain Name Registry
- LDH: letters, digits, hyphen
- member: data found within an object as defined by JSON [RFC7159].
- object: a data structure as defined by JSON [RFC7159].
- object class: the definition of members that may be found in JSON objects described in this document.
- object instance: an instantiation or specific instance of an object class.
- RDAP: Registration Data Access Protocol
- RIR: Regional Internet Registry
1.2. Data Model 🍓
The data model for JSON responses is split into five sections 💖:
- simple data types conveyed in JSON strings
- data structures specified as JSON arrays or objects that are used repeatedly when building up larger objects
- object classes representing structured data corresponding to a lookup of a single object
- arrays of objects representing structured data corresponding to a search for multiple objects
- the response to an error
The object classes cover two big categories of data 🌍. RIRs return registration data for IP addresses, reverse DNS names, and Autonomous System numbers. DNRs return registration data for forward DNS names. These three object classes are returned by both RIRs and DNRs:
- domains
- nameservers
- entities
The info that RIRs and DNRs serve for these object classes overlaps a LOT, so this doc gives them as one unified model for both kinds of service 🫶.
On top of those, RIRs also serve these object classes:
- IP networks
- Autonomous System numbers
The object classes in this doc are a minimal set of what a compliant client/server needs to understand to work correctly. Some deployments might want extra object classes for their own needs 👑. Knowing that, Section 2.1 of this document defines a way to extend the JSON objects described here ✨.
Positive responses come in two forms 🌈. A response to a lookup of a single object gives a JSON object, which is the thing that got looked up. A response to a search for multiple objects gives a JSON object containing an array of JSON objects, which are the things that were searched for. In each type of response, other data structures live inside that topmost JSON object 🎀.
2. Use of JSON 💅
To be continued in Part 2, bestie 🫶✨
2.1. Naming 💖
Okay so, clients reading these JSON responses SHOULD ignore any JSON members they don't recognize 🙈 Servers are allowed to slip in extra members that aren't in this spec, and that's not an error ✨
Servers that add those unspecified members SHOULD prefix the name with a short identifier, then an underscore, then a meaningful name 🎀 The short identifier helps implementers figure out which spec a member belongs to. Skip it and someone might think the server is misusing a name from this spec 💀 This allowance doesn't cover jCard [RFC7095] objects 🚫 The full JSON name (prefix, underscore, meaningful name) SHOULD adhere to the character and name limitations of the prefix registry described in [RFC7480]. Ignoring those limits could mean slower adoption, since they've been seen to help some client programming models 🧚
Here's a JSON response with members that are all specified in this document:
{
"handle" : "ABC123",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
]
}Figure 1
If The Registry of the Moon wants to express info that isn't in this specification, it might pick "lunarNic" as its identifying prefix 🌙 It could then insert, for example, the member "lunarNic_beforeOneSmallStep" to signify registrations made before the first moon landing 🚀, and the member "lunarNic_harshMistressNotes" that holds other descriptive text 😭
Here's a JSON response with names where some should be ignored by clients that don't know what they mean:
{
"handle" : "ABC123",
"lunarNic_beforeOneSmallStep" : "TRUE THAT!",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"lunarNic_harshMistressNotes" :
[
"In space,",
"nobody can hear you scream."
]
}Figure 2
Clients can ignore unrecognized members like these, and that same trick may also be used for future revisions to this specification 🦋
Clients processing JSON responses need to be ready for members holding registration data from this document to be missing from a response 🫶 In other words, servers are free to leave out JSON members containing registration data based on their own policies 💅
Finally, all JSON names in this document are case sensitive 👑 Both servers and clients MUST transmit and process them using the specified character case. No exceptions, bestie ✨
3. Common Data Types ✨
JSON [RFC7159] defines the data types of a number, character string, boolean, array, object, and null 🍓 This section explains the semantics and/or syntax reference for the common JSON character strings used in this document 🌸
handle: DNRs and RIRs have registry-unique identifiers that
may be used to specifically reference an object
instance. The semantics of this data type as found
in this document are to be a registry-unique
reference to the closest enclosing object where the
value is found. The data type names "registryId",
"roid", "nic-handle", "registrationNo", etc., are
terms often synonymous with this data type. In
this document, the term "handle" is used. The term
exposed to users by clients is a presentation issue
beyond the scope of this document.
IPv4 addresses: The representation of IPv4 addresses in this
document uses the dotted-decimal notation. An
example of this textual representation is
"192.0.2.0".
IPv6 addresses: The representation of IPv6 addresses in this
document follow the forms outlined in [RFC5952].
An example of this textual representation is
"2001:db8::1:0:0:1".
country codes: Where the identity of a geopolitical nation or
country is needed, these identities are represented
with the alpha-2 or two-character country code
designation as defined in [ISO.3166.1988]. The
alpha-2 representation is used because it is freely
available, whereas the alpha-3 and numeric-3
standards are not.
LDH names: Textual representations of DNS names where the
labels of the domain are all "letters, digits,
hyphen" labels as described by [RFC5890]. Trailing
periods are optional.
Unicode names: Textual representations of DNS names where one or
more of the labels are U-labels as described by
[RFC5890]. Trailing periods are optional.
dates and times: The syntax for values denoting dates and times is
defined in [RFC3339].
URIs: The syntax for values denoting a Uniform Resource
Identifier (URI) is defined by [RFC3986].Contact information is defined using jCards as described in [RFC7095] 📇
4. Common Data Structures 🎀
This section defines the common data structures used in responses and object classes 🦋
4.1. RDAP Conformance 🌈
The data structure named "rdapConformance" is an array of strings, and each one gives a hint about the specifications used to build the response 🧚 It only shows up in the topmost JSON object of a response, so don't go looking for it anywhere else 🙈
Here's an example rdapConformance data structure:
"rdapConformance" :
[
"rdap_level_0"
]Figure 3
The string literal "rdap_level_0" means the response conforms with this specification ✨ When custom JSON values get inserted into responses, conformance to those custom specifications MUST use a string prefixed with the appropriate identifier from the IANA RDAP Extensions registry specified in [RFC7480]. For example, if the fictional Registry of the Moon wants to show that its JSON responses follow its registered extensions, the string might be "lunarNIC_level_0" 🌙 These prefixes help software implementers identify specifications, and skipping them could mean slower adoption of extensions 😭
Here's an rdapConformance structure with custom extensions noted:
"rdapConformance" :
[
"rdap_level_0",
"lunarNic_level_0"
]Figure 4
4.2. Links 🔗
The "links" array shows up in data structures to point at other resources on the Internet 🌸 The relationship of these links is defined by the IANA registry described in [RFC5988] 💅
Here's an example of the link structure:
{
"value" : "http://example.com/context_uri",
"rel" : "self",
"href" : "http://example.com/target_uri",
"hreflang" : [ "en", "ch" ],
"title" : "title",
"media" : "screen",
"type" : "application/json"
}Figure 5
The JSON names and values "rel", "href", "hreflang", "title", "media", and "type" correspond to values found in Section 5 of [RFC5988]. The "value" JSON value is the context URI as described by [RFC5988]. The "href" JSON value MUST be specified. All other JSON values are OPTIONAL 🫶
Here's what the "links" array can look like inside an object class:
"links" :
[
{
"value" : "http://example.com/ip/2001:db8::123",
"rel" : "self",
"href" : "http://example.com/ip/2001:db8::123",
"type" : "application/rdap+json"
},
{
"value" : "http://example.com/ip/2001:db8::123",
"rel" : "up",
"href" : "http://example.com/ip/2001:db8::/48",
"type" : "application/rdap+json"
}
]Figure 6
4.3. Notices and Remarks 📝
The "notices" and "remarks" data structures take the same form 💖 The notices structure carries information about the service providing RDAP information and/or information about the entire response ✨ The remarks structure carries information about the object class that contains it (see Section 5 regarding object classes) 🧚
Both are arrays of objects. Each object can hold an optional "title" string with the title of the object, an optional "type" string naming a registered type of remark or notice (see Section 10.2.1), an array of strings named "description" for any descriptive text, and an optional "links" array as described in Section 4.2 🎀
Here's an example of the notices data structure:
"notices" :
[
{
"title" : "Terms of Use",
"description" :
[
"Service subject to The Registry of the Moon's TOS.",
"Copyright (c) 2020 LunarNIC"
],
"links" :
[
{
"value" : "http://example.net/entity/XXXX",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/terms_of_use.html"
}
]
}
]Figure 7
Clients are the ones who decide line breaks, spacing, and display stuff for sentences inside the "description" strings 💅 Each string in the "description" array holds one complete chunk of human-readable text, which tells clients where the semantic breaks are 🌸
Here's an example of the remarks data structure:
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
]Figure 8
Objects in the "remarks" array may also have a "links" array 🔗
The "title" and "description" fields are mainly for humans, but the "type" string holds a well-known value that gets registered with IANA (see Section 10.2.1) for programs to use 🤖
Here's another example of the remarks data structure:
"remarks" :
[
{
"type" : "object truncated due to authorization",
"description" :
[
"Some registration data may not have been given.",
"Use proper authorization credentials to see all of it."
]
}
]Figure 9
The "remarks" array shows up in lots of object classes in a response, but the "notices" array only appears in the topmost object of a response 👑
4.4. Language Identifier 🌍
This data structure is just a single name/value pair, where the name is "lang" and the value is a string holding a language identifier as described in [RFC5646] 🍓
"lang" : "mn-Cyrl-MN"Figure 10
The "lang" attribute may appear anywhere in an object class or data structure except in jCard objects 💜
4.5. Events 🎀
okay so events are basically the receipts of what's happened to an object class instance 🧾✨ (see Section 5 for the object class deets). Here's what an "events" array looks like:
"events" :
[
{
"eventAction" : "registration",
"eventActor" : "SOMEID-LUNARNIC",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventActor" : "OTHERID-LUNARNIC",
"eventDate" : "1991-12-31T23:59:59Z"
}
]Figure 11
Each object in the "events" array has these members, and yes, they're all giving main character energy 💖:
"eventAction"💅 a string saying why the event happened"eventActor"🫶 an optional identifier for the actor who was responsible for the event"eventDate"🗓️ a string with the time and date the event happened"links"🔗 see Section 4.2
Events can be future dated 🔮 and honestly that's iconic, because one big use case is marking when an object expires from a registry ⏳.
The "links" array in this structure is there to reference the event actor 🧚. To point at an RDAP entity, you use a "rel" of "related" and a "type" of "application/rdap+json" in the link reference. Periodt 💜.
See Section 10.2.3 for the list of values for the "eventAction" string. And see Appendix B for the different ways events can be modeled 🌈.
4.6. Status ✨
This one's named "status", and it's an array of strings that tell you the state of a registered object 🦋 (check Section 10.2.2 for the list of values).
4.7. Port 43 WHOIS Server 🌸
This structure is a member called "port43". It's a simple string with the fully qualified host name or IP address of the WHOIS [RFC3912] server where the object instance you're looking for might be hiding 🕵️♀️. Quick reminder: this is NOT a URI, because there's no WHOIS URI scheme, so don't go looking for one 🙈.
4.8. Public IDs 🍓
This structure maps a public identifier to an object class 🗺️. It's named "publicIds" and it's an array of objects, and each object has these two members:
type🏷️ a string describing the type of public identifieridentifier🔑 a public identifier of the type named by"type"
Here's an example of a publicIds structure 💅:
"publicIds":
[
{
"type":"IANA Registrar ID",
"identifier":"1"
}
]Figure 12
4.9. Object Class Name 🧚♀️
This one's a member called "objectClassName", and it gives the object class name of a particular object as a string 🎀. It tells you what kind of object you're dealing with. An objectClassName is REQUIRED in all RDAP response objects, so the type of the object can always be interpreted. No cap, this one is non-negotiable 💀.
4.10. An Example 🦋
Here's a full example response with both rdapConformance and notices tucked inside it 🫶:
{
"rdapConformance" :
[
"rdap_level_0"
],
"notices" :
[
{
"title" : "Content Removed",
"description" :
[
"Without full authorization, content has been removed.",
"Sorry, dude!"
],
"links" :
[
{
"value" : "http://example.net/ip/192.0.2.0/24",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/redaction_policy.html"
}
]
}
],
"lang" : "en",
"objectClassName" : "ip network",
"startAddress" : "192.0.2.0",
"endAddress" : "192.0.2.255",
"handle" : "XXXX-RIR",
"ipVersion" : "v4",
"name": "NET-RTR-1",
"parentHandle" : "YYYY-RIR",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
]
}Figure 13
5. Object Classes 🦋
Object classes are the structures that show up in a response to the queries specified in [RFC7482]. Think of them as the main characters of the whole protocol 👑.
Every object class has a "links" array, as described in Section 4.2. For every object class instance in a response, whether it's answering the query directly, embedded inside other object class instances, or sitting in a search result set, servers SHOULD provide a link that represents a URI for that instance, using the "self" relationship from the IANA registry specified by [RFC5988] 🔗. As explained in Section 5.2, this may be not always be possible for nameserver data 🙈. Clients MUST be able to process object instances without a self link, so no drama if one is missing 🫶. When a self link IS there, clients can use it for caching data 💾. Servers MAY provide more than one self link for any given object instance 🌈. Failing to provide any self link might mean clients can't cache object class instances, and that's a real bummer 😭.
Clients using self links for caching SHOULD not cache any object class instances where the authority of the self link is different than the authority of the server returning the data. If they do, it might lead to cache poisoning ☠️, so be careful, bestie 🚨.
Self links MUST contain a "type" element with the "application/rdap+json" media type when they reference RDAP object instances as defined by this document 💜.
Here's an example of the "links" array with a self link to an object class 🧚:
"links" :
[
{
"value" : "http://example.com/ip/2001:db8::123",
"rel" : "self",
"href" : "http://example.com/ip/2001:db8::123",
"type" : "application/rdap+json"
}
]Figure 14
5.1. The Entity Object Class 🎀
okay so the entity object class is literally EVERYWHERE in this doc 💅 It's the perfect match for the /entity/XXXX query from "Registration Data Access Protocol (RDAP) Query Format" [RFC7482]. It's the one construct for organizations, corporations, governments, non-profits, clubs, individual people, and informal groups of people 🫶 They're all sooo similar that it's best to represent them in JSON [RFC7159] with ONE construct, so implementers can reuse their code. Iconic, right? ✨
The entity object class uses jCard [RFC7095] for contact info, like postal addresses, email addresses, phone numbers, and the names of orgs and individuals 📇 Lowkey a lot of what jCard can hold is useless for RDAP, like birthdays, anniversaries, and gender. Not me being like "why would anyone need that here" 💀
The entity object is served by both RIRs and DNRs 🌸 Here's an example of an entity an RIR might serve:
{
"objectClassName" : "entity",
"handle":"XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["n", {}, "text",
["User", "Joe", "", "", ["ing. jr", "M.Sc."]]
],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["adr",
{
"type":"home",
"label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n"
},
"text",
[
"", "", "", "", "", "", ""
]
],
["tel",
{
"type":["work", "voice"],
"pref":"1"
},
"uri",
"tel:+1-555-555-1234;ext=102"
],
["tel",
{ "type":["work", "cell", "voice", "video", "text"] },
"uri",
"tel:+1-555-555-4321"
],
["email",
{ "type":"work" },
"text",
"joe.user@example.com"
],
["geo", {
"type":"work"
}, "uri", "geo:46.772673,-71.282945"],
["key",
{ "type":"work" },
"uri",
"http://www.example.com/joe.user/joe.asc"
],
["tz", {},
"utc-offset", "-05:00"],
["url", { "type":"home" },
"uri", "http://example.org"]
]
],
"roles":[ "registrar" ],
"publicIds":[
{
"type":"IANA Registrar ID",
"identifier":"1"
}
],
"remarks":[
{
"description":[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links":[
{
"value":"http://example.com/entity/XXXX",
"rel":"self",
"href":"http://example.com/entity/XXXX",
"type" : "application/rdap+json"
}
],
"events":[
{
"eventAction":"registration",
"eventDate":"1990-12-31T23:59:59Z"
}
],
"asEventActor":[
{
"eventAction":"last changed",
"eventDate":"1991-12-31T23:59:59Z"
}
]
}
Figure 15The entity object class can contain these members 👑
- objectClassName -- the string "entity"
- handle -- a string representing a registry unique identifier of the entity
- vcardArray -- a jCard with the entity's contact information
- roles -- an array of strings, each signifying the relationship an object would have with its closest containing object (see Section 10.2.4 for a list of values)
- publicIds -- see Section 4.8
- entities -- an array of entity objects as defined by this section
- remarks -- see Section 4.3
- links -- see Section 4.2
- events -- see Section 4.5
- asEventActor -- this data structure takes the same form as the events data structure (see Section 4.5), but each object in the array MUST NOT have an "eventActor" member. These objects denote that the entity is an event actor for the given events. See Appendix B regarding the various ways events can be modeled.
- status -- see Section 4.6
- port43 -- see Section 4.7
- networks -- an array of IP network objects as defined in Section 5.4
- autnums -- an array of autnum objects as defined in Section 5.5
Entities can also have other entities embedded inside them in an array 🧚 This is super useful for modeling an organization with specific individuals filling designated roles of responsibility. Main character energy for sure 🦋
Here's an elided example of an entity with embedded entities:
{
"objectClassName" : "entity",
"handle" : "ANENTITY",
"roles" : [ "registrar" ],
...
"entities" :
[
{
"objectClassName" : "entity",
"handle": "ANEMBEDDEDENTITY",
"roles" : [ "technical" ],
...
},
...
],
...
}
Figure 16And here's an entity that a DNR might serve 🍓
{
"objectClassName" : "entity",
"handle":"XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
]
]
],
"status":[ "validated", "locked" ],
"remarks":[
{
"description":[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links":[
{
"value":"http://example.com/entity/XXXX",
"rel":"self",
"href":"http://example.com/entity/XXXX",
"type":"application/rdap+json"
}
],
"port43":"whois.example.net",
"events":[
{
"eventAction":"registration",
"eventDate":"1990-12-31T23:59:59Z"
},
{
"eventAction":"last changed",
"eventDate":"1991-12-31T23:59:59Z",
"eventActor":"joe@example.com"
}
]
}
Figure 17See Appendix A for how the entity object class models the different kinds of entities found in both RIRs and DNRs. And see Appendix C for the structured vs. unstructured postal address stuff in entities. Go read them, bestie 🫶
5.2. The Nameserver Object Class ✨
okay so the nameserver object class is all about DNS nameservers, the ones used in both forward and reverse DNS 🌸 RIRs and some DNRs store nameserver info as an attribute hanging off a domain name, while other DNRs treat nameservers as "first class objects" that stand on their own 💅
the nameserver object class fits both models, plus all the in-between versions 🫶
here's a nameserver object with everything filled in 🎀
{
"objectClassName" : "nameserver",
"handle" : "XXXX",
"ldhName" : "ns1.xn--fo-5ja.example",
"unicodeName" : "ns1.foo.example",
"status" : [ "active" ],
"ipAddresses" :
{
"v4": [ "192.0.2.1", "192.0.2.2" ],
"v6": [ "2001:db8::123" ]
},
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/nameserver/xxxx",
"rel" : "self",
"href" : "http://example.net/nameserver/xxxx",
"type" : "application/rdap+json"
}
],
"port43" : "whois.example.net",
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z",
"eventActor" : "joe@example.com"
}
]
}Figure 18
Figure 18 is the maximal version, with every value given 🦋 Registries running a first-class nameserver model would embed this inside domain objects, and they could also let you look it up with the "/nameserver" query type (whatever the registry operator's policy says, obvi) ✨ Other registries can pare it back to whatever they need. Figure 19 shows a nameserver object like the ones RIRs and some DNRs use, and Figure 20 shows one like the ones other DNRs use 💜
here's the simplest nameserver object possible 🧚
{
"objectClassName" : "nameserver",
"ldhName" : "ns1.example.com"
}Figure 19
and here's a simple one that DNRs commonly use 🍓
{
"objectClassName" : "nameserver",
"ldhName" : "ns1.example.com",
"ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] }
}Figure 20
since some registries model nameservers as first-class objects, they can also have an array of entities (Section 5.1) embedded in them 🫶 Those entities show who's responsible for maintaining the nameservers, handling their registrations, and so on.
here's an elided example of a nameserver with embedded entities 👑
{
"objectClassName" : "nameserver",
"handle" : "XXXX",
"ldhName" : "ns1.xn--fo-5ja.example",
...
"entities" :
[
...
],
...
}Figure 21
the nameserver object class can contain these members 💅
objectClassName-- the string"nameserver"handle-- a string representing a registry unique identifier of the nameserverldhName-- a string containing the LDH name of the nameserver (see Section 3)unicodeName-- a string containing a DNS Unicode name of the nameserver (see Section 3)ipAddresses-- an object containing the following members:v6-- an array of strings containing IPv6 addresses of the nameserverv4-- an array of strings containing IPv4 addresses of the nameserver
entities-- an array of entity objects as defined by Section 5.1status-- see Section 4.6remarks-- see Section 4.3links-- see Section 4.2port43-- see Section 4.7events-- see Section 4.5
5.3. The Domain Object Class 🎀
the domain object class represents a DNS name and its point of delegation 🌈 For RIRs, those delegation points live in the reverse DNS tree, while for DNRs they live in the forward DNS tree 🦋
in both cases, the big picture of the domain object class is pretty much the same: info about the domain registration, nameserver info related to the domain name, and entities linked to the domain name (like registrant info, contacts, and so on) 💖
here's an elided example showing the high-level structure of a domain object ✨
{
"objectClassName" : "domain",
"handle" : "XXX",
"ldhName" : "blah.example.com",
...
"nameservers" :
[
...
],
...
"entities" :
[
...
]
}Figure 22
the domain object class can contain these members 🧚
objectClassName-- the string"domain"handle-- a string representing a registry unique identifier of the domain object instanceldhName-- a string describing a domain name in LDH form as described in Section 3unicodeName-- a string containing a domain name with U-labels as described in Section 3variants-- an array of objects, each containing the following values:relation-- an array of strings, with each string denoting the relationship between the variants and the containing domain object (see Section 10.2.5 for a list of suggested variant relations).idnTable-- the name of the Internationalized Domain Name (IDN) table of codepoints, such as one listed with the IANA (see IDN tables [IANA_IDNTABLES]).variantNames-- an array of objects, with each object containing an"ldhName"member and a"unicodeName"member (see Section 3).
nameservers-- an array of nameserver objects as defined by Section 5.2secureDNS-- an object with the following members:zoneSigned-- true if the zone has been signed, false otherwise.delegationSigned-- boolean true if there are DS records in the parent, false otherwise.maxSigLife-- an integer representing the signature lifetime in seconds to be used when creating the RRSIG DS record in the parent zone [RFC5910].dsData-- an array of objects, each with the following members:keyTag-- an integer as specified by the key tag field of a DNS DS record as specified by [RFC4034] in presentation formatalgorithm-- an integer as specified by the algorithm field of a DNS DS record as described by RFC 4034 in presentation formatdigest-- a string as specified by the digest field of a DNS DS record as specified by RFC 4034 in presentation formatdigestType-- an integer as specified by the digest type field of a DNS DS record as specified by RFC 4034 in presentation formatevents-- see Section 4.5links-- see Section 4.2
keyData-- an array of objects, each with the following members:flags-- an integer representing the flags field value in the DNSKEY record [RFC4034] in presentation formatprotocol-- an integer representation of the protocol field value of the DNSKEY record [RFC4034] in presentation formatpublicKey-- a string representation of the public key in the DNSKEY record [RFC4034] in presentation formatalgorithm-- an integer as specified by the algorithm field of a DNSKEY record as specified by [RFC4034] in presentation formatevents-- see Section 4.5links-- see Section 4.2
See Appendix D for background information on these objects.
entities-- an array of entity objects as defined by Section 5.1status-- see Section 4.6publicIds-- see Section 4.8remarks-- see Section 4.3links-- see Section 4.2port43-- see Section 4.7events-- see Section 4.5network-- represents the IP network for which a reverse DNS domain is referenced. See Section 5.4
here's an example of a JSON domain object for a reverse DNS delegation point that an RIR might serve 🌸
{
"objectClassName" : "domain",
"handle" : "XXXX",
"ldhName" : "0.2.192.in-addr.arpa",
"nameservers" :
[
{
"objectClassName" : "nameserver",
"ldhName" : "ns1.rir.example"
},
{
"objectClassName" : "nameserver",
"ldhName" : "ns2.rir.example"
}
],
"secureDNS":
{
"delegationSigned": true,
"dsData":
[
{
"keyTag": 12345,
"algorithm": 3,
"digestType": 1,
"digest": "49FD46E6C4B45C55D4AC"
}
]
},
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value": "http://example.net/domain/XXXX",
"rel" : "self",
"href" : "http://example.net/domain/XXXXX",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z",
"eventActor" : "joe@example.com"
}
],
"entities" :
[
{
"objectClassName" : "entity",
"handle" : "XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]okay so this next bit finishes off the network example 🌸 The tail end of that JSON is right here, bestie 💅
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
]
]
],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value": "http://example.net/entity/xxxx",
"rel" : "self",
"href" : "http://example.net/entity/xxxx",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z",
"eventActor" : "joe@example.com"
}
]
}
],
"network" :
{
"objectClassName" : "ip network",
"handle" : "XXXX-RIR",
"startAddress" : "192.0.2.0",
"endAddress" : "192.0.2.255",
"ipVersion" : "v6",
"name": "NET-RTR-1",
"type" : "DIRECT ALLOCATION",
"country" : "AU",
"parentHandle" : "YYYY-RIR",
"status" : [ "active" ]
}
}
Figure 23Next up is a domain example 🧚 This is a JSON domain object for a forward DNS delegation point that a DNR might serve. Yes, it's giving real-world vibes 🦋
{
"objectClassName" : "domain",
"handle" : "XXXX",
"ldhName" : "xn--fo-5ja.example",
"unicodeName" : "foo.example",
"variants" :
[
{
"relation" : [ "registered", "conjoined" ],
"variantNames" :
[
{
"ldhName" : "xn--fo-cka.example",
"unicodeName" : "foo.example"
},
{
"ldhName" : "xn--fo-fka.example",
"unicodeName" : "foo.example"
}
]
},
{
"relation" : [ "unregistered", "registration restricted" ],
"idnTable": ".EXAMPLE Swedish",
"variantNames" :
[
{
"ldhName": "xn--fo-8ja.example",
"unicodeName" : "foo.example"
}
]
}
],
"status" : [ "locked", "transfer prohibited" ],
"publicIds":[
{
"type":"ENS_Auth ID",
"identifier":"1234567890"
}
],
"nameservers" :
[
{
"objectClassName" : "nameserver",
"handle" : "XXXX",
"ldhName" : "ns1.example.com",
"status" : [ "active" ],
"ipAddresses" :
{
"v6": [ "2001:db8::123", "2001:db8::124" ],
"v4": [ "192.0.2.1", "192.0.2.2" ]
},
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/nameserver/XXXX",
"rel" : "self",
"href" : "http://example.net/nameserver/XXXX",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z"
}
]
},
{
"objectClassName" : "nameserver",
"handle" : "XXXX",
"ldhName" : "ns2.example.com",
"status" : [ "active" ],
"ipAddresses" :
{
"v6" : [ "2001:db8::125", "2001:db8::126" ],
"v4" : [ "192.0.2.3", "192.0.2.4" ]
},
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/nameserver/XXXX",
"rel" : "self",
"href" : "http://example.net/nameserver/XXXX",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z"
}
]
}
],
"secureDNS":
{
"zoneSigned": true,
"delegationSigned": true,
"maxSigLife": 604800,
"keyData":
[
{
"flags": 257,
"protocol": 3,
"algorithm": 1,
"publicKey": "AQPJ////4Q==",
"events":
[
{
"eventAction": "last changed",
"eventDate": "2012-07-23T05:15:47Z"
}
]
}
]
},
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value": "http://example.net/domain/XXXX",
"rel" : "self",
"href" : "http://example.net/domain/XXXX",
"type" : "application/rdap+json"
}
],
"port43" : "whois.example.net",
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z",
"eventActor" : "joe@example.com"
},
{
"eventAction" : "transfer",
"eventDate" : "1991-12-31T23:59:59Z",
"eventActor" : "joe@example.com"
},
{
"eventAction" : "expiration",
"eventDate" : "2016-12-31T23:59:59Z",
"eventActor" : "joe@example.com"
}
],
"entities" :
[
{
"objectClassName" : "entity",
"handle" : "XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
]
]
],
"status" : [ "validated", "locked" ],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/entity/xxxx",
"rel" : "self",
"href" : "http://example.net/entity/xxxx",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z"
}
]
}
]
}
Figure 245.4. The IP Network Object Class ✨
okay so the IP network object class is how RIRs show their IP network registrations, and it's the expected answer to the "/ip" query from [RFC7482] 💅 there's no equivalent for DNRs, so it's RIR-only vibes 🌍 the big picture is info about the network registration plus the entities tied to it (like registrant info, contacts, etc.) 🫶
here's an elided peek at the IP network object type so you can see the overall shape 👀
{
"objectClassName" : "ip network",
"handle" : "XXX",
...
"entities" :
[
...
]
}Figure 25
and here's a full example of the JSON object for the network registration info 😍
{
"objectClassName" : "ip network",
"handle" : "XXXX-RIR",
"startAddress" : "2001:db8::",
"endAddress" : "2001:db8:0:ffff:ffff:ffff:ffff:ffff",
"ipVersion" : "v6",
"name": "NET-RTR-1",
"type" : "DIRECT ALLOCATION",
"country" : "AU",
"parentHandle" : "YYYY-RIR",
"status" : [ "active" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/ip/2001:db8::/48",
"rel" : "self",
"href" : "http://example.net/ip/2001:db8::/48",
"type" : "application/rdap+json"
},
{
"value" : "http://example.net/ip/2001:db8::/48",
"rel" : "up",
"href" : "http://example.net/ip/2001:C00::/23",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z"
}
],
"entities" :
[
{
"objectClassName" : "entity",
"handle" : "XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
]
]
],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/entity/xxxx",
"rel" : "self",
"href" : "http://example.net/entity/xxxx",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z"
}
]
}
]
}Figure 26
so the IP network object class can hold these members 🧚
- objectClassName -- the string "ip network" 💜
- handle -- a string representing an RIR-unique identifier of the network registration 🪪
- startAddress -- the starting IP address of the network, either IPv4 or IPv6 🌸
- endAddress -- the ending IP address of the network, either IPv4 or IPv6 🌸
- ipVersion -- a string signifying the IP protocol version of the network: "v4" signifies an IPv4 network, and "v6" signifies an IPv6 network 🦋
- name -- an identifier assigned to the network registration by the registration holder 🎀
- type -- a string containing an RIR-specific classification of the network 🍓
- country -- a string containing the two-character country code of the network 🌈
- parentHandle -- a string containing an RIR-unique identifier of the parent network of this network registration 👑
- status -- an array of strings indicating the state of the IP network ⭐
- entities -- an array of entity objects as defined by Section 5.1 🫶
- remarks -- see Section 4.3 📝
- links -- see Section 4.2 🔗
- port43 -- see Section 4.7 🛰️
- events -- see Section 4.5 📅
5.5. Autonomous System Number Entity Object Class 🦄
the Autonomous System number (autnum) object class is the RIR-side model for Autonomous System number registrations, and it's the expected response to an "/autnum" query from [RFC7482] 💖 no equivalent for DNRs, sorry bestie 🙈 the structure is basically info about the network registration plus the entities linked to the autnum registration (e.g., registrant info, contacts, etc.), and it's giving the same energy as the IP network entity object class 🫶
here's an example JSON object representing an autnum 🌟
{
"objectClassName" : "autnum",
"handle" : "XXXX-RIR",
"startAutnum" : 10,
"endAutnum" : 15,
"name": "AS-RTR-1",
"type" : "DIRECT ALLOCATION",
"status" : [ "active" ],
"country": "AU",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/autnum/xxxx",
"rel" : "self",
"href" : "http://example.net/autnum/xxxx",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z"
}
],
"entities" :
[
{
"objectClassName" : "entity",
"handle" : "XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
]
]
],
"roles" : [ "registrant" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links" :
[
{
"value" : "http://example.net/entity/XXXX",
"rel" : "self",
"href" : "http://example.net/entity/XXXX",
"type" : "application/rdap+json"
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z"
}
]
}
]
}Figure 27
the Autonomous System number object class can contain these members 🌷
- objectClassName -- the string "autnum" 💜
- handle -- a string representing an RIR-unique identifier of the autnum registration 🪪
- startAutnum -- a number representing the starting number [RFC5396] in the block of Autonomous System numbers 🔢
- endAutnum -- a number representing the ending number [RFC5396] in the block of Autonomous System numbers 🔢
- name -- an identifier assigned to the autnum registration by the registration holder 🎀
- type -- a string containing an RIR-specific classification of the autnum 🍓
- status -- an array of strings indicating the state of the autnum ⭐
- country -- a string containing the name of the two-character country code of the autnum 🌈
- entities -- an array of entity objects as defined by Section 5.1 🫶
- remarks -- see Section 4.3 📝
- links -- see Section 4.2 🔗
- port43 -- see Section 4.7 🛰️
- events -- see Section 4.5 📅
6. Error Response Body ✨
okay so some non-answer responses can still come back with an entity body that explains things way better 🧐
the basic structure is an object class that holds an error code number (matching the HTTP response code), then a string called "title", then an array of strings called "description" 💅
here's the common response body in action 🙃
{
"errorCode": 418,
"title": "Your Beverage Choice is Not Available",
"description":
[
"I know coffee has more ummppphhh.",
"Sorry, dude!"
]
}Figure 28
and here's the common response body with rdapConformance and notices data structures tossed in 🎀
{
"rdapConformance" :
[
"rdap_level_0"
],
"notices" :
[
{
"title" : "Beverage Policy",
"description" :
[
"Beverages with caffeine for keeping horses awake."
],
"links" :
[
{
"value" : "http://example.net/ip/192.0.2.0/24",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/redaction_policy.html"
}
]
}
],
"lang" : "en",
"errorCode": 418,
"title": "Your beverage choice is not available",
"description":
[
"I know coffee has more ummppphhh.",
"Sorry, dude!"
]
}Figure 29
7. Responding to Help Queries ✨
okay so the right way to answer /help queries (as defined by [RFC7482]) is to use the notices structure from Section 4.3 🎀 it's the notices thing, literally the same vibe, no cap
here's a cute example of a /help response that includes the rdapConformance data structure 🦋
{
"rdapConformance" :
[
"rdap_level_0"
],
"notices" :
[
{
"title" : "Authentication Policy",
"description" :
[
"Access to sensitive data for users with proper credentials."
],
"links" :
[
{
"value" : "http://example.net/help",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/auth_policy.html"
}
]
}
]
}Figure 30
8. Responding To Searches 🔍
okay bestie, [RFC7482] gives us three kinds of searches: domains, nameservers, and entities 💜 the response to each one is an array of object instances, and each instance is the right object class for that search (so a /domains search gives you an array of domain object instances, obviously 💅). those arrays get tucked inside the response object.
the array names go like this:
- for /domains searches, the array is
domainSearchResults - for /nameservers searches, the array is
nameserverSearchResults - for /entities searches, the array is
entitySearchResults
here's an elided example of a /domains search response 🌸
{
"rdapConformance" :
[
"rdap_level_0"
],
...
"domainSearchResults" :
[
{
"objectClassName" : "domain",
"handle" : "1-XXXX",
"ldhName" : "1.example.com",
...
},
{
"objectClassName" : "domain",
"handle" : "2-XXXX",
"ldhName" : "2.example.com",
...
}
]
}Figure 31
9. Indicating Truncated Responses ✂️
okay so sometimes the data in a response has to be limited, or parts of it have to be left out 🙈 that makes the response "truncated". a truncated response is still valid JSON, just that some results in a search set, or some data in an object, aren't being handed over by the server. the server can flag this by putting a typed notice in the response object 🎀
here's an elided example of a truncated search response 💖
{
"rdapConformance" :
[
"rdap_level_0"
],
"notices" :
[
{
"title" : "Search Policy",
"type" : "result set truncated due to authorization",
"description" :
[
"Search results are limited to 25 per day per querying IP."
],
"links" :
[
{
"value" : "http://example.net/help",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/search_policy.html"
}
]
}
],
"domainSearchResults" :
[
...
]
}Figure 32
a similar move works with a typed remark when a single object came back but some of its data got cut 🧚 think an entity object that only has some of its IP networks attached.
here's an elided example of truncated entity data 💜
{
"objectClassName" : "entity",
"handle" : "ANENTITY",
"roles" : [ "registrant" ],
...
"entities" :
[
{
"objectClassName" : "entity",
"handle": "ANEMBEDDEDENTITY",
"roles" : [ "technical" ],
...
},
...
],
"networks" :
[
...
],
...
"remarks" :
[
{
"title" : "Data Policy",
"type" : "object truncated due to unexplainable reason",
"description" :
[
"Some of the data in this object has been removed."
],
"links" :
[
{
"value" : "http://example.net/help",
"rel" : "alternate",
"type" : "text/html",
"href" : "http://www.example.com/data_policy.html"
}
]
}
]
}Figure 33
10. IANA Considerations 🌈
10.1. RDAP JSON Media Type Registration 📝
okay so this spec registers the application/rdap+json media type ✨ here are the registration details:
Type name: application
Subtype name: rdap+json
Required parameters: n/a
Encoding considerations: See Section 3.1 of [RFC6839].
Security considerations: The media represented by this identifier
does not have security considerations beyond that found in
Section 6 of [RFC7159].
Interoperability considerations: There are no known
interoperability problems regarding this media format.
Published specification: RFC 7483
Applications that use this media type: Implementations of the
Registration Data Access Protocol (RDAP).
Additional information: This media type is a product of the IETF
WEIRDS working group. The WEIRDS charter, information on the
WEIRDS mailing list, and other documents produced by the WEIRDS
working group can be found at
<https://datatracker.ietf.org/wg/weirds/>.
Person & email address to contact for further information: IESG
<iesg@ietf.org>
Intended usage: COMMON
Restrictions on usage: none
Author: Andy Newton
Change controller: IETF
Provisional Registration: No (upon publication of this RFC)10.2. JSON Values Registry 🗂️
IANA has set up a category in the protocol registries called "Registration Data Access Protocol (RDAP)" 💅 inside it there's a stand-alone registry called "RDAP JSON Values", and it has its own URL so you can reference it directly. this registry is for the notices and remarks (Section 4.3), status (Section 4.6), role (Section 5.1), event action (Section 4.5), and domain variant relation (Section 5.3) fields in RDAP. it's giving organized 🫶
every entry in the registry has these fields:
- Value -- the string value being registered.
- Type -- the type of value being registered. It should be one of the following:
- "notice or remark type" -- denotes a type of notice or remark.
- "status" -- denotes a value for the "status" object member as defined by Section 4.6.
- "role" -- denotes a value for the "role" array as defined in Section 5.1.
- "event action" -- denotes a value for an event action as defined in Section 4.5.
- "domain variant relation" -- denotes a relationship between a domain and a domain variant as defined in Section 5.3.
- Description -- a one- or two-sentence description of what the value means, how it might be used, and/or how clients should interpret it.
- Registrant Name -- the name of the person registering the value.
- Registrant Contact Information -- an email address, postal address, or some other info to reach the registrant.
this registry runs on the "Expert Review" policy from [RFC5226] 🔥 when designated expert(s) review a registration, they should judge it narrowly against these criteria:
- Values that need to go into multiple types must get a separate registration for each type.
- Values must be strings. They should be multiple words separated by single space characters. Every character should be lowercased. If possible, every word should be in English and each character should be US-ASCII.
- Registrations should not duplicate the meaning of any existing registration. That is, if a request is significantly similar in nature to an existing registration, the request should be denied. For example, the terms "maintainer" and "registrant" are significantly similar in nature, as they both denote a holder of a domain name or Internet number resource. In cases where it may be reasonably argued that machine interpretation of two similar values may alter the operation of client software, designated experts should not judge the values to be of significant similarity.
- Registrations should be relevant to the common usages of RDAP. Designated experts may rely upon the serving of the value by a DNR or RIR to make this determination.
the following sections make the initial registrations into this registry 🎀
10.2.1. Notice and Remark Types 🧁
these values have been registered in the "RDAP JSON Values" registry 💖
Value: result set truncated due to authorization
Type: notice and remark type
Description: The list of results does not contain all results due
to lack of authorization. This may indicate to some clients
that proper authorization will yield a longer result set.
Registrant Name: IESG
Registrant Contact Information: iesg@ietf.org
Value: result set truncated due to excessive load
Type: notice and remark type
Description: The list of results does not contain all results due
to an excessively heavy load on the server. This may indicate
to some clients that requerying at a later time will yield a
longer result set.
Registrant Name: IESG
Registrant Contact Information: iesg@ietf.org
Value: result set truncated due to unexplainable reasons
Type: notice and remark type
Description: The list of results does not contain all results for
an unexplainable reason. This may indicate to some clients
that requerying for any reason will not yield a longer result
set.
Registrant Name: IESG
Registrant Contact Information: iesg@ietf.org
Value: object truncated due to authorization
Type: notice and remark type
Description: The object does not contain all data due to lack of
authorization.
Registrant Name: IESG
Registrant Contact Information: iesg@ietf.org
Value: object truncated due to excessive load
Type: notice and remark type
Description: The object does not contain all data due to an
excessively heavy load on the server. This may indicate to
some clients that requerying at a later time will yield all
data of the object.
Registrant Name: IESG
Registrant Contact Information: iesg@ietf.org
Value: object truncated due to unexplainable reasons
Type: notice and remark type
Description: The object does not contain all data for an
unexplainable reason.
Registrant Name: IESG
Registrant Contact Information: iesg@ietf.org10.2.2. Status
okay so the IESG has registered these status values in the "RDAP JSON Values" registry, and they are literally the vibe check for every object instance 💅✨
validated🧚- Type:
status - Description: this one means the object instance's data has been checked and found to be accurate 🫶 You'll usually see it on entity object instances, where it confirms the identifying contact info is legit.
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
renew prohibited🔒- Type:
status - Description: renewing or re-registering the object instance is forbidden. no renewing for you, bestie 🙅♀️
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
update prohibited🚫- Type:
status - Description: nobody is allowed to update the object instance. hands off, it's giving untouchable 👑
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
transfer prohibited🦋- Type:
status - Description: moving the registration from one registrar to another is forbidden. this one normally shows up on DNR domain names, so they stay put and don't get passed around 🏠
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
delete prohibited🛡️- Type:
status - Description: deleting the registration of the object instance is forbidden. this one normally applies to DNR domain names too, so they're protected from being removed 💜
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
proxy🎭- Type:
status - Description: a third party did the registration for the object instance. this is most commonly applied to entities 🧑🤝🧑
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
private🤫- Type:
status - Description: the information in the object instance is not meant for public consumption. this is most commonly applied to entities, so it's giving "keep it on the down low" 🌙
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
removed🫥- Type:
status - Description: some of the object instance's information hasn't been made available and has been taken out. this is most commonly applied to entities 🍂
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
obscured🌫️- Type:
status - Description: some of the object instance's information has been changed on purpose so it doesn't readily reveal the actual information. this is most commonly applied to entities, and it's very "blurred photo" energy 📸
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
associated🔗- Type:
status - Description: the object instance is linked to other object instances in the registry. this is most commonly used to show that a nameserver is associated with a domain, or that an entity is associated with a network resource or domain 💞
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
active🌸- Type:
status - Description: the object instance is in use! for domain names, this means the domain is published in DNS. for network and autnum registrations, it means they're allocated or assigned for use in operational networks. this maps to the "OK" status of the Extensible Provisioning Protocol (EPP) [RFC5730] ✨
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
inactive😴- Type:
status - Description: the object instance is not in use. see "active" 💤
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
locked🔐- Type:
status - Description: nothing can be changed on the object instance, and that includes associating other object instances with it 🚪
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
pending create⏳- Type:
status - Description: a request to create the object instance has come in, but it isn't finished yet. still cooking 🍳
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
pending renew⏳- Type:
status - Description: a request to renew the object instance has come in, but it isn't finished yet 🔄
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
pending transfer⏳- Type:
status - Description: a request to transfer the object instance has come in, but it isn't finished yet 🚚
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
pending update⏳- Type:
status - Description: a request to update or modify the object instance has come in, but it isn't finished yet ✏️
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
pending delete⏳- Type:
status - Description: a request to delete or remove the object instance has come in, but it isn't finished yet. for domains, this might mean the name is no longer published in DNS but hasn't been purged from the registry database yet 👻
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
10.2.3. Event Actions
okay, now the IESG has registered these event action values in the "RDAP JSON Values" registry. these are the timestamps-and-moments of an object's life, and they're iconic 🕰️
registration🎉- Type:
event action - Description: the object instance was registered for the very first time. the origin story! 🌱
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
reregistration🔁- Type:
event action - Description: the object instance was registered again after its initial registration. a comeback arc 💫
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
last changed📝- Type:
event action - Description: marks when the information in the object instance was last changed. the "last seen" of data 👀
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
expiration⌛- Type:
event action - Description: the object instance has been removed, or will be removed at a predetermined date and time from the registry. it has a scheduled exit 🚪✨
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
deletion💀- Type:
event action - Description: the object instance was removed from the registry at a point in time that wasn't predetermined. no warning, just gone 😭
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
reinstantiation🧚♀️- Type:
event action - Description: the object instance was re-registered after having been removed from the registry. it's back from the dead, and it's iconic 🔥
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
transfer📦- Type:
event action - Description: the object instance was moved from one registrant to another 🤝
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
locked🔒- Type:
event action - Description: the object instance was locked (see the "locked" status) 🗝️
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
unlocked🔓- Type:
event action - Description: the object instance was unlocked (see the "locked" status) 🎀
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
10.2.4. Roles
the IESG registered these role values in the "RDAP JSON Values" registry too! these tell you what an entity is doing for the registration, and it's giving job titles 💼
registrant👑- Type:
role - Description: the entity object instance is the registrant of the registration. in some registries, this is known as a maintainer 🧑💻
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
technical🛠️- Type:
role - Description: the entity object instance is a technical contact for the registration 🤓
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
administrative📋- Type:
role - Description: the entity object instance is an administrative contact for the registration 🗂️
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
abuse🚨- Type:
role - Description: the entity object instance handles network abuse issues on behalf of the registrant of the registration. the one you call when something's sus 🕵️
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
billing💸- Type:
role - Description: the entity object instance handles payment and billing issues on behalf of the registrant of the registration 🧾
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
registrar🏛️- Type:
role - Description: the entity object instance represents the authority responsible for the registration in the registry. the boss of the registration 👩⚖️
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
reseller🛍️- Type:
role - Description: the entity object instance represents a third party through which the registration was conducted (i.e., not the registry or registrar). the middle-person, but make it iconic 🎁
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
sponsor🌟- Type:
role - Description: the entity object instance represents a domain policy sponsor, such as an ICANN-approved sponsor 🏅
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
proxy🎭- Type:
role - Description: the entity object instance represents a proxy for another entity object, such as a registrant. it's the plus-one who shows up on behalf of someone else 🫂
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
notifications📬- Type:
role - Description: an entity object instance designated to receive notifications about association object instances. the inbox 💌
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
noc🖥️- Type:
role - Description: the entity object instance handles communications related to a network operations center (NOC). the 24/7 crew keeping the lights on 🌙⚡
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
10.2.5. Variant Relations
last one for this batch! the IESG registered these domain variant relation values in the "RDAP JSON Values" registry, and they describe how variant names relate to the registry 🌈
registered✅- Type:
domain variant relation - Description: the variant names are registered in the registry 🎟️
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
unregistered❌- Type:
domain variant relation - Description: the variant names are not found in the registry 🫥
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
registration restricted🚧- Type:
domain variant relation - Description: registration of the variant names is restricted to certain parties or within certain rules. not everyone gets in, bestie 🎫
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
open registration🌷- Type:
domain variant relation - Description: registration of the variant names is available to generally qualified registrants. the doors are open for qualified folks 🚪💖
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
conjoined👯- Type:
domain variant relation - Description: registration of the variant names happens automatically along with the registration of the containing domain. they come as a set, no separating them 🫶
- Registrant Name:
IESG - Registrant Contact Information:
iesg@ietf.org
- Type:
11. Security Considerations 🔐
Okay bestie, this spec models info serialized in JSON format 🧾 And since JSON is a subset of JavaScript, implementations are advised to follow the security considerations in Section 6 of [RFC7159] to prevent code injection. Super important, no cap 💅
Not JSON-specific, but RDAP implementers should also be aware of the security considerations in [RFC7480] and the security requirements and considerations in [RFC7481]. Read those too, they're the real tea 🍵
Clients caching data should have safeguards to prevent cache poisoning, especially clients using RDAP-specific caches instead of HTTP-layer caches 🛡️ Look at Section 5 for advice on using the self links for caching.
Finally, service operators should be aware of the privacy mechanisms in Section 13 🙈
12. Internationalization Considerations 🌍
12.1. Character Encoding
The default text encoding for JSON responses in RDAP is UTF-8 [RFC3629], and all servers and clients MUST support UTF-8. Non-negotiable, bestie 💜
12.2. URIs and IRIs
[RFC7480] defines the use of URIs and IRIs in RDAP 🔗
12.3. Language Tags
Section 4.4 defines the use of language tags in the JSON responses defined in this document 🗣️
12.4. Internationalized Domain Names
IDNs are denoted in this spec by separating DNS names in LDH form from their Unicode form (see Section 3) ✨ Representation of IDNs in registries is described by the variants object in Section 5.3, plus the suggested values listed in Section 10.2.5. It's giving organized 📚
13. Privacy Considerations 🫣
This spec suggests status values to denote contact and registrant info that has been marked as private, removed, or obscured 🙈 See Section 10.2.2 for the complete list of status values. A few of them mean there are privacy concerns tied to the object instance. The following status codes SHOULD be used to describe data elements of a response when appropriate:
private: The object is not to be shared in query responses, unless the user is authorized to view this information 🔒removed: 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"removed". Use it carefully, bestie 💀
See Appendix A.1 for an example of applying those values to contacts and registrants 🎀
14. References 📚
14.1. Normative References
[ISO.3166.1988]
International Organization for Standardization, "Codes for
the representation of names of countries, 3rd edition",
ISO Standard 3166, August 1988.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002,
<http://www.rfc-editor.org/info/rfc3339>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003,
<http://www.rfc-editor.org/info/rfc3629>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S.
Rose, "Resource Records for the DNS Security Extensions",
RFC 4034, March 2005,
<http://www.rfc-editor.org/info/rfc4034>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008, <http://www.rfc-editor.org/info/rfc5226>.
[RFC5396] Huston, G. and G. Michaelson, "Textual Representation of
Autonomous System (AS) Numbers", RFC 5396, December 2008,
<http://www.rfc-editor.org/info/rfc5396>.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
Languages", BCP 47, RFC 5646, September 2009,
<http://www.rfc-editor.org/info/rfc5646>.
[RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework",
RFC 5890, August 2010,
<http://www.rfc-editor.org/info/rfc5890>.
[RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
Address Text Representation", RFC 5952, August 2010,
<http://www.rfc-editor.org/info/rfc5952>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>.
[RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095,
January 2014, <http://www.rfc-editor.org/info/rfc7095>.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014,
<http://www.rfc-editor.org/info/rfc7159>.
[RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the
Registration Data Access Protocol (RDAP)", RFC 7480, March
2015, <http://www.rfc-editor.org/info/rfc7480>.
[RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the
Registration Data Access Protocol (RDAP)", RFC 7481, March
2015, <http://www.rfc-editor.org/info/rfc7481>.
[RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access
Protocol (RDAP) Query Format", RFC 7482, March 2015,
<http://www.rfc-editor.org/info/rfc7482>.14.2. Informative References
[IANA_IDNTABLES]
IANA, "Repository of IDN Practices",
<http://www.iana.org/domains/idn-tables>.
[JSON_ascendancy]
MacVittie, L., "The Stealthy Ascendancy of JSON", April
2011, <https://devcentral.f5.com/weblogs/macvittie/
archive/2011/04/27/the-stealthy-ascendancy-of-json.aspx>.
[JSON_performance_study]
Nurseitov, N., Paulson, M., Reynolds, R., and C. Izurieta,
"Comparison of JSON and XML Data Interchange Formats: A
Case Study", 2009,
<http://www.cs.montana.edu/izurieta/pubs/caine2009.pdf>.
[RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
September 2004, <http://www.rfc-editor.org/info/rfc3912>.
[RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
STD 69, RFC 5730, August 2009,
<http://www.rfc-editor.org/info/rfc5730>.
[RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS)
Security Extensions Mapping for the Extensible
Provisioning Protocol (EPP)", RFC 5910, May 2010,
<http://www.rfc-editor.org/info/rfc5910>.
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
August 2011, <http://www.rfc-editor.org/info/rfc6350>.
[RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type
Structured Syntax Suffixes", RFC 6839, January 2013,
<http://www.rfc-editor.org/info/rfc6839>.Appendix A. Suggested Data Modeling with the Entity Object Class 🧩
A.1. Registrants and Contacts
This doc doesn't provide specific object classes for registrants and contacts 🙃 Instead, the entity object class may be used to represent a registrant or contact. When the entity object is embedded inside a containing object such as a domain name or IP network, the "roles" string array can be used to signify the relationship. It is recommended that the values from Section 10.2.4 be used 💖
Here's an elided containing object with an embedded entity that is both a registrant and administrative contact. Iconic, bestie 👑
{
...
"entities" :
[
{
"objectClassName" : "entity",
"handle" : "XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
]
]
],
"roles" : [ "registrant", "administrative" ],
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
},
{
"eventAction" : "last changed",
"eventDate" : "1991-12-31T23:59:59Z"
}
]
}
]
}Figure 34
In lots of use cases, it's necessary to hide or obscure a registrant's or contact's info because of policy or other operational matters 🫣 Registries can flag these situations with "status" values (see Section 10.2.2) 🚩
Here's an elided example of a registrant with info changed to reflect that of a third party 🕵️♀️
{
...
"entities" :
[
{
"objectClassName" : "entity",
"handle" : "XXXX",
...
"roles" : [ "registrant", "administrative" ],
"status" : [ "proxy", "private", "obscured" ]
}
]
}Figure 35
A.2. Registrars ✨
okay so this doc doesn't give registrars their own object class 🙈 but just like registrants and contacts (see Appendix A.1), you can use the "roles" string array for them 💅 Lots of registrars also have publicly assigned identifiers, and the publicIds structure (Section 4.8) is where that info goes 🦋
Here's an example of an elided containing object with an embedded entity that's a registrar 🎀
{
...
"entities":[
{
"objectClassName" : "entity",
"handle":"XXXX",
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe's Fish, Chips, and Domains"],
["kind", {}, "text", "org"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{
"type":["work", "voice"],
"pref":"1"
},
"uri", "tel:+1-555-555-1234;ext=102"
],
["email",
{ "type":"work" },
"text", "joes_fish_chips_and_domains@example.com"
]
]
],
"roles":[ "registrar" ],
"publicIds":[
{
"type":"IANA Registrar ID",
"identifier":"1"
}
],
"remarks":[
{
"description":[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"links":[
{
"value":"http://example.net/entity/XXXX",
"rel":"alternate",
"type":"text/html",
"href":"http://www.example.com"
}
]
}
]
}Figure 36
Appendix B. Modeling Events ✨
okay events are basically actions that happened to a registered object at a certain date and time 📅 (sometimes that date is in the future, bestie, wild 😭). Every event has three properties: the action, the actor, and the date and time. Sometimes the actor just isn't captured at all 🌸
There are three ways to model events 👑
- events with no designated actor
- events where the actor is only designated by an identifier
- events where the actor can be modeled as an entity
For the first use case, you use the events data structure (Section 4.5) but leave out the "eventActor" object member ✨ Here's an example of an "events" array without the "eventActor":
"events" :
[
{
"eventAction" : "registration",
"eventDate" : "1990-12-31T23:59:59Z"
}
]Figure 37
For the second use case, you still use the events data structure (Section 4.5), but this time you include the "eventActor" object member 🧚 Here's an "events" array with the "eventActor":
"events" :
[
{
"eventAction" : "registration",
"eventActor" : "XYZ-NIC",
"eventDate" : "1990-12-31T23:59:59Z"
}
]Figure 38
For the third use case, the "asEventActor" array comes in clutch when an entity (Section 5.1) is embedded into another object class 💖 It follows the same structure as the "events" array, but it doesn't have "eventActor" attributes. Here's an elided domain object with an entity as the event actor:
{
"objectClassName" : "domain",
"handle" : "XXXX",
"ldhName" : "foo.example",
"status" : [ "locked", "transfer prohibited" ],
...
"entities" :
[
{
"handle" : "XXXX",
...
"asEventActor" :
[
{
"eventAction" : "last changed",
"eventDate" : "1990-12-31T23:59:59Z"
}
]
}
]
}Figure 39
Appendix C. Structured vs. Unstructured Addresses 🏡
So the entity (Section 5.1) object class uses jCard [RFC7095] for contact info, including postal addresses 💌 jCard can handle multiple language preferences, multiple email addresses and phone numbers, and multiple postal addresses, in both structured and unstructured formats. This appendix shows how jCard does both 🫶 Here's an example of a jCard:
{
"vcardArray":[
"vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Joe User"],
["n", {}, "text",
["User", "Joe", "", "", ["ing. jr", "M.Sc."]]
],
["kind", {}, "text", "individual"],
["lang", {
"pref":"1"
}, "language-tag", "fr"],
["lang", {
"pref":"2"
}, "language-tag", "en"],
["org", {
"type":"work"
}, "text", "Example"],
["title", {}, "text", "Research Scientist"],
["role", {}, "text", "Project Lead"],
["adr",
{ "type":"work" },
"text",
[
"",
"Suite 1234",
"4321 Rue Somewhere",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["adr",
{
"type":"home",
"label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n"
},
"text",
[
"", "", "", "", "", "", ""
]
],
["tel",
{ "type":["work", "voice"], "pref":"1" },
"uri", "tel:+1-555-555-1234;ext=102"
],
["tel",
{
"type":["work", "cell", "voice", "video", "text"]
},
"uri",
"tel:+1-555-555-1234"
],
["email",
{ "type":"work" },
"text", "joe.user@example.com"
],
["geo", {
"type":"work"
}, "uri", "geo:46.772673,-71.282945"],
["key",
{ "type":"work" },
"uri", "http://www.example.com/joe.user/joe.asc"
],
["tz", {},
"utc-offset", "-05:00"],
["url", { "type":"home" },
"uri", "http://example.org"]
]
]
}Figure 40
okay so the "adr" entries in Figure 40 with the first member of "adr" are the postal addresses 📮 The first one is a structured address, given as an array of strings. If a component doesn't apply to you, you put in an empty string. Each member of the array lines up with the positions of a vCard as given in [RFC6350]. In this example, the positions mean:
- post office box -- not applicable; empty string
- extended address (e.g., apartment or suite number) -- Suite 1234
- street address -- 4321 Rue Somewhere
- locality (e.g., city) -- Quebec
- region (e.g., state or province) -- QC
- postal code -- G1V 2M2
- country name (full name) -- Canada
The second one is an unstructured address 🌀 It uses the label attribute, which is a string with a newline (\n) character separating the address components in an unordered, unspecified way. Notice that the structured address array is still there in this one, but every string in it is empty 🙃
Appendix D. Secure DNS 🔐
Section 5.3 defines the "secureDNS" member, which represents secure DNS info about domain names 🦋
DNSSEC gives DNS data integrity by digitally signing resource records 🔏 To turn it on, the zone gets signed by one or more private keys, and the signatures get stored as RRSIG records. To complete the chain of trust in the DNS zone hierarchy, a digest of each DNSKEY record (which holds the public key) has to be loaded into the parent zone, stored as DS records, and signed by the parent's private key (RRSIG DS record). This is described in "Resource Records for the DNS Security Extensions" [RFC4034]. Creating the DS records in the parent zone can be done by the registration authority, as covered in "Domain Name System (DNS) Security Extensions Mapping for the Extensible Provisioning Protocol (EPP)" [RFC5910] 💅
Only the DS-related info comes through RDAP, since the other info usually isn't stored in the registration database 🙈 You can grab the other DNSSEC-related info with other DNS tools, like dig.
The domain object class (Section 5.3) can represent this info using either the "dsData" or "keyData" object arrays. Client implementers should know that some registries don't collect, or don't publish, all of the secure DNS meta-information ⭐
Appendix E. Motivations for Using JSON 💜
This appendix answers a common question: why JSON instead of other data formats, especially XML? 🌈
People often point out that many DNRs and one RIR support the EPP [RFC5730] standard, which is serialized in XML. The logic goes that since EPP is common in the industry, XML must be the more natural pick. EPP does influence this spec a lot, but EPP is for a different job: provisioning Internet resources between registries and accredited registrars, so its audience is way narrower than what RDAP is aiming for 🎯
RDAP, on the other hand, has a broader audience and is built for public consumption of data 📣 Experience from RIRs with first generation RESTful web services for WHOIS shows that a big chunk of clients run in browsers and other platforms where full-blown XML stacks aren't readily available, and where JSON is a better fit 🍓
Also, EPP isn't a universal constant even in the DNR world 🤷♀️ And finally, EPP's XML came out before JSON was specified. If EPP had been defined today, it might very well have used JSON instead 😭
Beyond the DNR and RIR communities, the broader Internet industry is also moving from XML to JSON, especially for RESTful web services (see [JSON_ascendancy]) ✨ Studies have also found that JSON is generally less bulky and therefore faster to parse (see [JSON_performance_study]) 🚀
Acknowledgements 🙏✨
This document grew out of original work on RIR responses in JSON by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew L. Newton. It also brings in work on DNR responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean Shen. 🌸
The pieces of the DNR object classes come from a categorization of WHOIS response formats made by Ning Kong, Linlin Zhou, Guangqing Deng, Steve Sheng, Francisco Arias, Ray Bellis, and Frederico Neves. Iconic research, honestly. 🧚
Tom Harrison, Murray Kucherawy, Ed Lewis, Audric Schiltknecht, Naoki Kambe, and Maarten Bosteels gave significant review comments and clarifying text, and they absolutely carried this doc. 💅 James Mitchell wrote the text on how unknown JSON attributes get processed, and also spotted the issues that led to remodeling events. Ernie Dainow and Francisco Obispo offered concrete suggestions that gave us a better variant model for domain names. 🫶
Ernie Dainow also gave the background on the secure DNS attributes and objects for domains, the informative text on DNSSEC, and a whole lot of other attributes that show up across the object classes. Not me being dramatic, this was a major contribution. 🔥
The switch to jCard, and its incorporation into the document, was done by Simon Perreault. 🎀
Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working group, which is where this document came from. Bestie, the whole thing started there. 🌈
Authors' Addresses 🦋
Here are the authors, with their contact details exactly as they appear in the original. Slide into their inbox respectfully. 💌
Andrew Lee Newton
American Registry for Internet Numbers
3635 Concorde Parkway
Chantilly, VA 20151
United States
EMail: andy@arin.net
URI: http://www.arin.netScott Hollenbeck
Verisign Labs
12061 Bluemont Way
Reston, VA 20190
United States
EMail: shollenbeck@verisign.com
URI: http://www.verisignlabs.com/📦 where this page comes from
- ietf: rfc7483 2015-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms