RFC 7483
JSON Responses for the Registration Data Access Protocol (RDAP)
5. Object Classes
Object classes represent structures appropriate for a response from the queries specified in [RFC7482]. Each object class contains a "links" array as specified in Section 4.2. For every object class instance in a response, whether 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 a search result set, servers SHOULD provide a link representing a URI for that object class instance using the "self" relationship as described in 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. When present, clients can use the self link for caching data. Servers MAY provide more than one self link for any given object instance. Failure to provide any self link by a server may result in clients being unable to cache object class instances. 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. Failing to do so might result in cache poisoning. Self links MUST contain a "type" element containing the "application/ rdap+json" media type when referencing RDAP object instances as defined by this document.
This is 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 145.1. The Entity Object Class
The entity object class appears throughout this document and is an appropriate response for the /entity/XXXX query defined in "Registration Data Access Protocol (RDAP) Query Format" [RFC7482]. This object class represents the information of organizations, corporations, governments, non-profits, clubs, individual persons, and informal groups of people. All of these representations are so similar that it is best to represent them in JSON [RFC7159] with one construct, the entity object class, to aid in the reuse 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 an example of an entity that might be served by an RIR. { "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 15 The entity object class can contain the following members: o objectClassName -- the string "entity" o handle -- a string representing a registry unique identifier of the entity o vcardArray -- a jCard with the entity's contact information o 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) o publicIds -- see Section 4.8 o entities -- an array of entity objects as defined by this section o remarks -- see Section 4.3 o links -- see Section 4.2 o events -- see Section 4.5 o 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. o status -- see Section 4.6 o port43 -- see Section 4.7 o networks -- an array of IP network objects as defined in Section 5.4 o autnums -- an array of autnum objects as defined in Section 5.5
Entities may also have other entities embedded with them in an array. This can be used to model an organization with specific individuals fulfilling designated roles of responsibility. The following is an elided example of an entity with embedded entities. { "objectClassName" : "entity", "handle" : "ANENTITY", "roles" : [ "registrar" ], ... "entities" : [ { "objectClassName" : "entity", "handle": "ANEMBEDDEDENTITY", "roles" : [ "technical" ], ... }, ... ], ... } Figure 16 The following is an example of an entity that might be served by a DNR. { "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 17 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 regarding structured vs. unstructured postal addresses in entities.5.2. The Nameserver Object Class
The nameserver object class represents information regarding DNS nameservers used in both forward and reverse DNS. RIRs and some DNRs register or expose nameserver information as an attribute of a domain name, while other DNRs model nameservers as "first class objects". The nameserver object class accommodates both models and degrees of variation in between. The following is an example of a nameserver object.
{ "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 an example of a nameserver object with all values given. Registries using a first-class nameserver data model would embed this in domain objects as well as allowing references to it with the "/nameserver" query type (all depending on the registry operators policy). Other registries may pare back the information as needed. Figure 19 is an example of a nameserver object as would be found in RIRs and some DNRs, while Figure 20 is an example of a nameserver object as would be found in other DNRs. The following is an example of the simplest nameserver object: { "objectClassName" : "nameserver", "ldhName" : "ns1.example.com" } Figure 19 The following is an example of a simple nameserver object that might be commonly used by DNRs: { "objectClassName" : "nameserver", "ldhName" : "ns1.example.com", "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } } Figure 20 As nameservers can be modeled by some registries to be first-class objects, they may also have an array of entities (Section 5.1) embedded to signify parties responsible for the maintenance, registrations, etc., of the nameservers. The following is 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 the following members: o objectClassName -- the string "nameserver" o handle -- a string representing a registry unique identifier of the nameserver o ldhName -- a string containing the LDH name of the nameserver (see Section 3) o unicodeName -- a string containing a DNS Unicode name of the nameserver (see Section 3) o ipAddresses -- an object containing the following members: * v6 -- an array of strings containing IPv6 addresses of the nameserver * v4 -- an array of strings containing IPv4 addresses of the nameserver o entities -- an array of entity objects as defined by Section 5.1 o status -- see Section 4.6 o remarks -- see Section 4.3 o links -- see Section 4.2 o port43 -- see Section 4.7 o events -- see Section 4.5
5.3. The Domain Object Class
The domain object class represents a DNS name and point of delegation. For RIRs, these delegation points are in the reverse DNS tree, whereas for DNRs, these delegation points are in the forward DNS tree. In both cases, the high-level structure of the domain object class consists of information about the domain registration, nameserver information related to the domain name, and entities related to the domain name (e.g., registrant information, contacts, etc.). The following is an elided example of the domain object showing the high-level structure: { "objectClassName" : "domain", "handle" : "XXX", "ldhName" : "blah.example.com", ... "nameservers" : [ ... ], ... "entities" : [ ... ] } Figure 22 The domain object class can contain the following members: o objectClassName -- the string "domain" o handle -- a string representing a registry unique identifier of the domain object instance o ldhName -- a string describing a domain name in LDH form as described in Section 3 o unicodeName -- a string containing a domain name with U-labels as described in Section 3
o variants -- 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).
o nameservers -- an array of nameserver objects as defined by
Section 5.2
o secureDNS -- 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
format
+ algorithm -- an integer as specified by the algorithm field
of a DNS DS record as described by RFC 4034 in presentation
format
+ digest -- a string as specified by the digest field of a DNS
DS record as specified by RFC 4034 in presentation format
+ digestType -- an integer as specified by the digest type
field of a DNS DS record as specified by RFC 4034 in
presentation format
+ events -- see Section 4.5
+ links -- 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 format
+ protocol -- an integer representation of the protocol field
value of the DNSKEY record [RFC4034] in presentation format
+ publicKey -- a string representation of the public key in
the DNSKEY record [RFC4034] in presentation format
+ algorithm -- an integer as specified by the algorithm field
of a DNSKEY record as specified by [RFC4034] in presentation
format
+ events -- see Section 4.5
+ links -- see Section 4.2
See Appendix D for background information on these objects.
o entities -- an array of entity objects as defined by Section 5.1
o status -- see Section 4.6
o publicIds -- see Section 4.8
o remarks -- see Section 4.3
o links -- see Section 4.2
o port43 -- see Section 4.7
o events -- see Section 4.5
o network -- represents the IP network for which a reverse DNS
domain is referenced. See Section 5.4
The following is an example of a JSON domain object representing a
reverse DNS delegation point that might be served by an RIR.
{
"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"
]
],
["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 23 The following is an example of a JSON domain object representing a forward DNS delegation point that might be served by a DNR. { "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 24
(next page on part 3)
