1 Internet Engineering Task Force (IETF) S. Hollenbeck
2 Request for Comments: 9083 Verisign Labs
3 STD: 95 A. Newton
4 Obsoletes: 7483 AWS
5 Category: Standards Track June 2021
6 ISSN: 2070-1721
7
8
9 JSON Responses for the Registration Data Access Protocol (RDAP)
10
11 Abstract
12
13 This document describes JSON data structures representing
14 registration information maintained by Regional Internet Registries
15 (RIRs) and Domain Name Registries (DNRs). These data structures are
16 used to form Registration Data Access Protocol (RDAP) query
17 responses. This document obsoletes RFC 7483.
18
19 Status of This Memo
20
21 This is an Internet Standards Track document.
22
23 This document is a product of the Internet Engineering Task Force
24 (IETF). It represents the consensus of the IETF community. It has
25 received public review and has been approved for publication by the
26 Internet Engineering Steering Group (IESG). Further information on
27 Internet Standards is available in Section 2 of RFC 7841.
28
29 Information about the current status of this document, any errata,
30 and how to provide feedback on it may be obtained at
31 https://www.rfc-editor.org/info/rfc9083.
32
33 Copyright Notice
34
35 Copyright (c) 2021 IETF Trust and the persons identified as the
36 document authors. All rights reserved.
37
38 This document is subject to BCP 78 and the IETF Trust's Legal
39 Provisions Relating to IETF Documents
40 (https://trustee.ietf.org/license-info) in effect on the date of
41 publication of this document. Please review these documents
42 carefully, as they describe your rights and restrictions with respect
43 to this document. Code Components extracted from this document must
44 include Simplified BSD License text as described in Section 4.e of
45 the Trust Legal Provisions and are provided without warranty as
46 described in the Simplified BSD License.
47
48 Table of Contents
49
50 1. Introduction
51 1.1. Terminology and Definitions
52 1.2. Data Model
53 2. Use of JSON
54 2.1. Naming
55 3. Common Data Types
56 4. Common Data Structures
57 4.1. RDAP Conformance
58 4.2. Links
59 4.3. Notices and Remarks
60 4.4. Language Identifier
61 4.5. Events
62 4.6. Status
63 4.7. Port 43 WHOIS Server
64 4.8. Public IDs
65 4.9. Object Class Name
66 4.10. An Example
67 5. Object Classes
68 5.1. The Entity Object Class
69 5.2. The Nameserver Object Class
70 5.3. The Domain Object Class
71 5.4. The IP Network Object Class
72 5.5. The Autonomous System Number Object Class
73 6. Error Response Body
74 7. Responding to Help Queries
75 8. Responding To Searches
76 9. Indicating Truncated Responses
77 10. IANA Considerations
78 10.1. RDAP JSON Media Type Registration
79 10.2. JSON Values Registry
80 10.2.1. Notice and Remark Types
81 10.2.2. Status
82 10.2.3. Event Actions
83 10.2.4. Roles
84 10.2.5. Variant Relations
85 11. Security Considerations
86 12. Internationalization Considerations
87 12.1. Character Encoding
88 12.2. URIs and IRIs
89 12.3. Language Tags
90 12.4. Internationalized Domain Names
91 13. Privacy Considerations
92 14. References
93 14.1. Normative References
94 14.2. Informative References
95 Appendix A. Suggested Data Modeling with the Entity Object Class
96 A.1. Registrants and Contacts
97 A.2. Registrars
98 Appendix B. Modeling Events
99 Appendix C. Structured vs. Unstructured Addresses
100 Appendix D. Secure DNS
101 Appendix E. Motivations for Using JSON
102 Appendix F. Changes from RFC 7483
103 Acknowledgments
104 Authors' Addresses
105
106 1. Introduction
107
108 This document describes responses in the JSON [RFC8259] format for
109 the queries as defined by the Registration Data Access Protocol Query
110 Format [RFC9082]. A communication protocol for exchanging queries
111 and responses is described in [RFC7480]. This document obsoletes RFC
112 7483.
113
114 1.1. Terminology and Definitions
115
116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
118 "OPTIONAL" in this document are to be interpreted as described in
119 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
120 capitals, as shown here.
121
122 The following list describes terminology and definitions used
123 throughout this document:
124
125 DNR: Domain Name Registry or Domain Name Registrar
126
127 LDH: letters, digits, hyphen
128
129 member: data found within an object as defined by JSON [RFC8259]
130
131 object: a data structure as defined by JSON [RFC8259]
132
133 object class: the definition of members that may be found in JSON
134 objects described in this document
135
136 object instance: an instantiation or specific instance of an object
137 class
138
139 RDAP: Registration Data Access Protocol
140
141 RIR: Regional Internet Registry
142
143 1.2. Data Model
144
145 The data model for JSON responses is specified in five sections:
146
147 1. simple data types conveyed in JSON primitive types (strings,
148 numbers, booleans, and null)
149
150 2. data structures specified as JSON arrays or objects that are used
151 repeatedly when building up larger objects
152
153 3. object classes representing structured data corresponding to a
154 lookup of a single object
155
156 4. arrays of objects representing structured data corresponding to a
157 search for multiple objects
158
159 5. the response to an error
160
161 The object classes represent responses for two major categories of
162 data: responses returned by RIRs for registration data related to IP
163 addresses, reverse DNS names, and Autonomous System numbers and
164 responses returned by DNRs for registration data related to forward
165 DNS names. The following object classes are returned by both RIRs
166 and DNRs:
167
168 1. domains
169
170 2. nameservers
171
172 3. entities
173
174 The information served by both RIRs and DNRs for these object classes
175 overlap extensively and are given in this document as a unified model
176 for both classes of service.
177
178 In addition to the object classes listed above, RIRs also serve the
179 following object classes:
180
181 1. IP networks
182
183 2. Autonomous System numbers
184
185 Object classes defined in this document represent a minimal set of
186 what a compliant client/server needs to understand to function
187 correctly; however, some deployments may want to include additional
188 object classes to suit individual needs. Anticipating this need for
189 extension, Section 2.1 of this document defines a mechanism for
190 extending the JSON objects that are described in this document.
191
192 Positive responses take two forms. A response to a lookup of a
193 single object in the registration system yields a JSON object, which
194 is the subject of the lookup. A response to a search for multiple
195 objects yields a JSON object that contains an array of JSON objects
196 that are the subject of the search. In each type of response, other
197 data structures are present within the topmost JSON object.
198
199 2. Use of JSON
200
The IETF is responsible for the creation and maintenance of the DNS RFCs. The ICANN DNS RFC annotation project provides a forum for collecting community annotations on these RFCs as an aid to understanding for implementers and any interested parties. The annotations displayed here are not the result of the IETF consensus process.
This RFC is included in the DNS RFCs annotation project whose home page is here.
201 2.1. Naming
202
203 Clients of these JSON responses SHOULD ignore unrecognized JSON
204 members in responses. Servers can insert members into the JSON
205 responses, which are not specified in this document, but that does
206 not constitute an error in the response. Servers that insert such
207 unspecified members into JSON responses SHOULD have member names
208 prefixed with a short identifier followed by an underscore followed
209 by a meaningful name. It has been observed that these short
210 identifiers aid software implementers with identifying the
211 specification of the JSON member, and failure to use one could cause
212 an implementer to assume the server is erroneously using a name from
213 this specification. This allowance does not apply to jCard [RFC7095]
214 objects. The full JSON name (the prefix plus the underscore plus the
215 meaningful name) SHOULD adhere to the character and name limitations
216 of the prefix registry described in [RFC7480]. Failure to use these
217 limitations could result in slower adoption as these limitations have
218 been observed to aid some client programming models.
219
220 Consider the following JSON response with JSON members, all of which
221 are specified in this document.
222
223 {
224 "handle" : "ABC123",
225 "remarks" :
226 [
227 {
228 "description" :
229 [
230 "She sells sea shells down by the sea shore.",
231 "Originally written by Terry Sullivan."
232 ]
233 }
234 ]
235 }
236
237 Figure 1
238
239 If The Registry of the Moon desires to express information not found
240 in this specification, it might select "lunarNIC" as its identifying
241 prefix and insert, as an example, the member named
242 "lunarNIC_beforeOneSmallStep" to signify registrations occurring
243 before the first moon landing and the member named
244 "lunarNIC_harshMistressNotes" that contains other descriptive text.
245
246 Consider the following JSON response with JSON names, some of which
247 should be ignored by clients without knowledge of their meaning.
248
249 {
250 "handle" : "ABC123",
251 "lunarNIC_beforeOneSmallStep" : "TRUE THAT!",
252 "remarks" :
253 [
254 {
255 "description" :
256 [
257 "She sells sea shells down by the sea shore.",
258 "Originally written by Terry Sullivan."
259 ]
260 }
261 ],
262 "lunarNIC_harshMistressNotes" :
263 [
264 "In space,",
265 "nobody can hear you scream."
266 ]
267 }
268
269 Figure 2
270
271 Insertion of unrecognized members ignored by clients may also be used
272 for future revisions to this specification.
273
274 Clients processing JSON responses need to be prepared for members
275 representing registration data specified in this document to be
276 absent from a response. In other words, servers are free to omit
277 unrequired/optional JSON members containing registration data based
278 on their own policies.
279
280 Finally, all JSON names specified in this document are case
281 sensitive. Both servers and clients MUST transmit and process them
282 using the specified character case.
283
284 3. Common Data Types
285
286 JSON [RFC8259] defines the data types of a number, character string,
287 boolean, array, object, and null. This section describes the
288 semantics and/or syntax reference for common, JSON character strings
289 used in this document.
290
291 handle: DNRs and RIRs have registry-unique identifiers that
292 may be used to specifically reference an object
293 instance. The semantics of this data type as found
294 in this document are to be a registry-unique
295 reference to the closest enclosing object where the
296 value is found. The data type names "registryId",
297 "roid", "nic-handle", "registrationNo", etc., are
298 terms often synonymous with this data type. In
299 this document, the term "handle" is used. The term
300 exposed to users by clients is a presentation issue
301 beyond the scope of this document. This value is a
302 simple character string.
303
304 IPv4 addresses: The representation of IPv4 addresses in this
305 document uses the dotted-decimal notation. An
306 example of this textual representation is
307 "192.0.2.0".
308
309 IPv6 addresses: The representation of IPv6 addresses in this
310 document follow the forms outlined in [RFC5952].
311 An example of this textual representation is
312 "2001:db8::1:0:0:1".
313
314 country codes: Where the identity of a geopolitical nation or
315 country is needed, these identities are represented
316 with the alpha-2 or two-character country code
317 designation as defined in [ISO.3166.2020]. The
318 alpha-2 representation is used because it is freely
319 available, whereas the alpha-3 and numeric-3
320 standards are not.
321
322 LDH names: Textual representations of DNS names where the
323 labels of the domain are all "letters, digits,
324 hyphen" labels as described by [RFC5890]. Trailing
325 periods are optional.
326
327 Unicode names: Textual representations of DNS names where one or
328 more of the labels are U-labels as described by
329 [RFC5890]. Trailing periods are optional.
330
331 dates and times: The syntax for values denoting dates and times is
332 defined in [RFC3339].
333
334 URIs: The syntax for values denoting a Uniform Resource
335 Identifier (URI) is defined by [RFC3986].
336
337 Contact information is defined using jCards as described in
338 [RFC7095]. The "fn" member is required and MUST NOT be null
339 according to [RFC6350]. An empty "fn" member MAY be used when the
340 contact name does not exist or is redacted.
341
342 4. Common Data Structures
343
344 This section defines common data structures used in responses and
345 object classes.
346
If The Registry of the Moon desires to express information not found
in this specification, it might select "lunarNIC" as its identifying
prefix and insert, as an example, the member named
"lunarNIC_beforeOneSmallStep" to signify registrations occurring
before the first moon landing and the member named
"lunarNIC_harshMistressNotes" that contains other descriptive text.
Consider the following JSON response with JSON names, some of which
should be ignored by clients without knowledge of their meaning.
{
"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
If The Registry of the Moon desires to express information not found
in this specification, it might select "lunarNIC_level_0" as its
identifying prefix and insert, as an example, the member named
"lunarNIC_level_0_beforeOneSmallStep" to signify registrations occurring
before the first moon landing and the member named
"lunarNIC_level_0_harshMistressNotes" that contains other descriptive
text.
Consider the following JSON response with JSON names, some of which
should be ignored by clients without knowledge of their meaning.
{
"handle" : "ABC123",
"lunarNIC_level_0_beforeOneSmallStep" : "TRUE THAT!",
"remarks" :
[
{
"description" :
[
"She sells sea shells down by the sea shore.",
"Originally written by Terry Sullivan."
]
}
],
"lunarNIC_level_0_harshMistressNotes" :
[
"In space,",
"nobody can hear you scream."
]
}
Figure 2
The original text uses the string identifier "lunarNIC" as the prefix for an example extension. This is inconsistent with the example given in Section 4.1, where "lunarNIC_level_0" is used as an example of a registered identifier for an RDAP extension. This inconsistency can lead implementers to believe that the registered identifier and the extension prefix can be inconsistent, when the intent of the specification is that they should be consistent. This inconsistency can cause significant misunderstanding of the technical specification and might result in faulty implementations if not corrected. Changing the examples in Section 2.1 aligns the text with the example in Section 4.1, demonstrating that the extension prefix and the registered identifier should be one and the same.
347 4.1. RDAP Conformance
348
349 The data structure named "rdapConformance" is an array of strings,
350 each providing a hint as to the specifications used in the
351 construction of the response. This data structure MUST appear in the
352 topmost JSON object of a response and MUST NOT appear anywhere else.
353 A response to a "help" request will include identifiers for all of
354 the specifications supported by the server. A response to any other
355 request will include only identifiers for the specifications used in
356 the construction of the response. The set of returned identifiers
357 MAY vary depending on the authorization level of the client.
358
359 An example rdapConformance data structure:
360
361 "rdapConformance" :
362 [
363 "rdap_level_0"
364 ]
365
366 Figure 3
367
368 The string literal "rdap_level_0" signifies conformance with this
369 specification. When custom JSON values are inserted into responses,
370 conformance to those custom specifications MUST be indicated by
371 including a unique string literal value registered in the IANA RDAP
372 Extensions registry specified in [RFC7480]. For example, if the
373 fictional Registry of the Moon wants to signify that their JSON
374 responses are conformant with their registered extensions, the string
375 used might be "lunarNIC_level_0". These registered values aid the
376 identification of specifications for software implementers, and
377 failure to use them could result in slower adoption of extensions.
378
379 Example rdapConformance structure with custom extensions noted:
380
381 "rdapConformance" :
382 [
383 "rdap_level_0",
384 "lunarNIC_level_0"
385 ]
386
387 Figure 4
388
389 4.2. Links
390
391 The "links" array is found in data structures to signify links to
392 other resources on the Internet. The relationship of these links is
393 defined by the IANA registry described by [RFC8288].
394
395 The following is an example of the link structure:
396
397 {
398 "value" : "https://example.com/context_uri",
399 "rel" : "self",
400 "href" : "https://example.com/target_uri",
401 "hreflang" : [ "en", "ch" ],
402 "title" : "title",
403 "media" : "screen",
404 "type" : "application/json"
405 }
406
407 Figure 5
408
409 The JSON name/values of "rel", "href", "hreflang", "title", "media",
410 and "type" correspond to values found in Section 3 of [RFC8288]. The
411 "value" JSON value is the context URI as described by [RFC8288]. The
412 "value", "rel", and "href" JSON values MUST be specified. All other
413 JSON values are OPTIONAL. A "related" link relation MUST NOT include
414 an "href" URI that is the same as the "self" link relation "href" URI
415 to reduce the risk of infinite client processing loops.
416 Internationalized Domain Names (IDNs) returned in URIs SHOULD be
417 consistently returned in LDH name format to allow clients to process
418 these IDNs according to their capabilities.
419
420 This is an example of the "links" array as it might be found in an
421 object class:
422
423 "links" :
424 [
425 {
426 "value" : "https://example.com/ip/2001:db8::123",
427 "rel" : "self",
428 "href" : "https://example.com/ip/2001:db8::123",
429 "type" : "application/rdap+json"
430 },
431 {
432 "value" : "https://example.com/ip/2001:db8::123",
433 "rel" : "up",
434 "href" : "https://example.com/ip/2001:db8::/48",
435 "type" : "application/rdap+json"
436 }
437
438 ]
439
440 Figure 6
441
442 4.3. Notices and Remarks
443
444 The "notices" and "remarks" data structures take the same form. The
445 notices structure denotes information about the service providing
446 RDAP information and/or information about the entire response,
447 whereas the remarks structure denotes information about the object
448 class that contains it (see Section 5 regarding object classes).
449
450 Both are arrays of objects. Each object contains a "title" string
451 representing the title of the object, a "type" string denoting a
452 registered type of remark or notice (see Section 10.2.1), an array of
453 strings named "description" for the purposes of conveying any
454 descriptive text, and a "links" array as described in Section 4.2.
455 The "description" array MUST be included. All other JSON values are
456 OPTIONAL.
457
458 An example of the notices data structure:
459
460 "notices" :
461 [
462 {
463 "title" : "Terms of Use",
464 "description" :
465 [
466 "Service subject to The Registry of the Moon's TOS.",
467 "Copyright (c) 2020 LunarNIC"
468 ],
469 "links" :
470 [
471 {
472 "value" : "https://example.net/entity/XXXX",
473 "rel" : "alternate",
474 "type" : "text/html",
475 "href" : "https://www.example.com/terms_of_use.html"
476 }
477 ]
478 }
479 ]
480
481 Figure 7
482
483 It is the job of the clients to determine line breaks, spacing, and
484 display issues for sentences within the character strings of the
485 "description" array. Each string in the "description" array contains
486 a single complete division of human-readable text indicating to
487 clients where there are semantic breaks.
488
489 An example of the remarks data structure:
490
491 "remarks" :
492 [
493 {
494 "description" :
495 [
496 "She sells sea shells down by the sea shore.",
497 "Originally written by Terry Sullivan."
498 ]
499 }
500 ]
501
502 Figure 8
503
504 Note that objects in the "remarks" array may also have a "links"
505 array.
506
507 While the "title" and "description" fields are intended primarily for
508 human consumption, the "type" string contains a well-known value to
509 be registered with IANA (see Section 10.2.1) for programmatic use.
510
511 An example of the remarks data structure:
512
513 "remarks" :
514 [
515 {
516 "type" : "object truncated due to authorization",
517 "description" :
518 [
519 "Some registration data may not have been given.",
520 "Use proper authorization credentials to see all of it."
521 ]
522 }
523 ]
524
525 Figure 9
526
527 While the "remarks" array will appear in many object classes in a
528 response, the "notices" array appears only in the topmost object of a
529 response.
530
531 4.4. Language Identifier
532
533 This data structure consists solely of a name/value pair, where the
534 name is "lang" and the value is a string containing a language
535 identifier as described in [RFC5646].
536
537 "lang" : "mn-Cyrl-MN"
538
539 Figure 10
540
541 The "lang" attribute as defined in this section MAY appear anywhere
542 in an object class or data structure, except for in jCard objects.
543 vCard supports similar functionality by way of the LANGUAGE property
544 parameter (see Section 5.1 of RFC 6350 [RFC6350]).
545
546 4.5. Events
547
548 This data structure represents events that have occurred on an
549 instance of an object class (see Section 5 regarding object classes).
550
551 This is an example of an "events" array.
552
553 "events" :
554 [
555 {
556 "eventAction" : "registration",
557 "eventActor" : "SOMEID-LUNARNIC",
558 "eventDate" : "1990-12-31T23:59:59Z"
559 },
560 {
561 "eventAction" : "last changed",
562 "eventActor" : "OTHERID-LUNARNIC",
563 "eventDate" : "1991-12-31T23:59:59Z"
564 }
565 ]
566
567 Figure 11
568
569 The "events" array consists of objects, each with the following
570 members:
571
572 * "eventAction" -- a REQUIRED string denoting the reason for the
573 event
574
575 * "eventActor" -- an OPTIONAL identifier denoting the actor
576 responsible for the event
577
578 * "eventDate" -- a REQUIRED string containing the time and date the
579 event occurred
580
581 * "links" -- OPTIONAL; see Section 4.2
582
583 Events can be future dated. One use case for future dating of events
584 is to denote when an object expires from a registry.
585
586 The "links" array in this data structure is provided for references
587 to the event actor. In order to reference an RDAP entity, a "rel" of
588 "related" and a "type" of "application/rdap+json" is used in the link
589 reference.
590
591 See Section 10.2.3 for a list of values for the "eventAction" string.
592 See Appendix B regarding the various ways events can be modeled.
593
594 4.6. Status
595
596 This data structure, named "status", is an array of strings
597 indicating the state of a registered object (see Section 10.2.2 for a
598 list of values).
599
600 4.7. Port 43 WHOIS Server
601
602 This data structure, a member named "port43", is a simple character
603 string containing the fully qualified host name or IP address of the
604 WHOIS [RFC3912] server where the containing object instance may be
605 found. Note that this is not a URI, as there is no WHOIS URI scheme.
606
607 4.8. Public IDs
608
609 This data structure maps a public identifier to an object class. It
610 is named "publicIds" and is an array of objects, with each object
611 containing the following REQUIRED members:
612
613 * type -- a string denoting the type of public identifier
614
615 * identifier -- a string denoting a public identifier of the type
616 related to "type"
617
618 The following is an example of a publicIds structure.
619
620 "publicIds":
621 [
622 {
623 "type":"IANA Registrar ID",
624 "identifier":"1"
625 }
626 ]
627
628 Figure 12
629
630 4.9. Object Class Name
631
632 This data structure, a member named "objectClassName", gives the
633 object class name of a particular object as a string. This
634 identifies the type of object being processed. An objectClassName is
635 REQUIRED in all RDAP response objects so that the type of the object
636 can be interpreted.
637
638 4.10. An Example
639
640 This is an example response with both rdapConformance and notices
641 embedded:
642
643 {
644 "rdapConformance" :
645 [
646 "rdap_level_0"
647 ],
648 "notices" :
649 [
650 {
651 "title" : "Content Removed",
652 "description" :
653 [
654 "Without full authorization, content has been removed.",
655 "Sorry, dude!"
656 ],
657 "links" :
658 [
659 {
660 "value" : "https://example.net/ip/192.0.2.0/24",
661 "rel" : "alternate",
662 "type" : "text/html",
663 "href" : "https://www.example.com/redaction_policy.html"
664 }
665 ]
666 }
667 ],
668 "lang" : "en",
669 "objectClassName" : "ip network",
670 "startAddress" : "192.0.2.0",
671 "endAddress" : "192.0.2.255",
672 "handle" : "XXXX-RIR",
673 "ipVersion" : "v4",
674 "name": "NET-RTR-1",
675 "parentHandle" : "YYYY-RIR",
676 "remarks" :
677 [
678
679 {
680 "description" :
681 [
682 "She sells sea shells down by the sea shore.",
683 "Originally written by Terry Sullivan."
684 ]
685 }
686 ]
687 }
688
689 Figure 13
690
691 5. Object Classes
692
693 Object classes represent structures appropriate for a response from
694 the queries specified in [RFC9082].
695
696 Each object class contains a "links" array as specified in
697 Section 4.2. For every object class instance in a response, whether
698 the object class instance is directly representing the response to a
699 query or is embedded in other object class instances or is an item in
700 a search result set, servers SHOULD provide a link representing a URI
701 for that object class instance using the "self" relationship as
702 described in the IANA registry specified by [RFC8288]. As explained
703 in Section 5.2, this may be not always be possible for nameserver
704 data. Clients MUST be able to process object instances without a
705 self link. When present, clients can use the self link for caching
706 data. Servers MAY provide more than one self link for any given
707 object instance. Failure to provide any self link by a server may
708 result in clients being unable to cache object class instances.
709
710 Clients using self links for caching SHOULD NOT cache any object
711 class instances where the authority of the self link is different
712 than the authority of the server returning the data. Failing to do
713 so might result in cache poisoning.
714
715 Self links MUST contain a "type" element containing the "application/
716 rdap+json" media type when referencing RDAP object instances as
717 defined by this document.
718
719 This is an example of the "links" array with a self link to an object
720 class:
721
722 "links" :
723 [
724 {
725 "value" : "https://example.com/ip/2001:db8::123",
726 "rel" : "self",
727 "href" : "https://example.com/ip/2001:db8::123",
728 "type" : "application/rdap+json"
729 }
730 ]
731
732 Figure 14
733
734 5.1. The Entity Object Class
735
736 The entity object class appears throughout this document and is an
737 appropriate response for the /entity/XXXX query defined in
738 "Registration Data Access Protocol (RDAP) Query Format" [RFC9082].
739 This object class represents the information of organizations,
740 corporations, governments, non-profits, clubs, individual persons,
741 and informal groups of people. All of these representations are so
742 similar that it is best to represent them in JSON [RFC8259] with one
743 construct, the entity object class, to aid in the reuse of code by
744 implementers.
745
746 The entity object class uses jCard [RFC7095] to represent contact
747 information, such as postal addresses, email addresses, phone numbers
748 and names of organizations and individuals. Many of the types of
749 information that can be represented with jCard have little or no use
750 in RDAP, such as birthdays, anniversaries, and gender.
751
752 The entity object is served by both RIRs and DNRs. The following is
753 an example of an entity that might be served by an RIR.
754
755 {
756 "objectClassName" : "entity",
757 "handle":"XXXX",
758 "vcardArray":[
759 "vcard",
760 [
761 ["version", {}, "text", "4.0"],
762 ["fn", {}, "text", "Joe User"],
763 ["n", {}, "text",
764 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]]
765 ],
766 ["kind", {}, "text", "individual"],
767 ["lang", {
768 "pref":"1"
769 }, "language-tag", "fr"],
770 ["lang", {
771 "pref":"2"
772 }, "language-tag", "en"],
773 ["org", {
774 "type":"work"
775 }, "text", "Example"],
776 ["title", {}, "text", "Research Scientist"],
777 ["role", {}, "text", "Project Lead"],
778 ["adr",
779 { "type":"work" },
780 "text",
781 [
782 "",
783 "Suite 1234",
784 "4321 Rue Somewhere",
785 "Quebec",
786 "QC",
787 "G1V 2M2",
788 "Canada"
789 ]
790 ],
791 ["adr",
792 {
793 "type":"home",
794 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n"
795 },
796 "text",
797 [
798 "", "", "", "", "", "", ""
799 ]
800 ],
801 ["tel",
802 {
803 "type":["work", "voice"],
804 "pref":"1"
805 },
806 "uri",
807 "tel:+1-555-555-1234;ext=102"
808 ],
809 ["tel",
810 { "type":["work", "cell", "voice", "video", "text"] },
811 "uri",
812 "tel:+1-555-555-4321"
813 ],
814 ["email",
815 { "type":"work" },
816 "text",
817 "joe.user@example.com"
818 ],
819 ["geo", {
820 "type":"work"
821 }, "uri", "geo:46.772673,-71.282945"],
822 ["key",
823 { "type":"work" },
824 "uri",
825 "https://www.example.com/joe.user/joe.asc"
826 ],
827 ["tz", {},
828 "utc-offset", "-05:00"],
829 ["url", { "type":"home" },
830 "uri", "https://example.org"]
831 ]
832 ],
833 "roles":[ "registrar" ],
834 "publicIds":[
835 {
836 "type":"IANA Registrar ID",
837 "identifier":"1"
838 }
839 ],
840 "remarks":[
841 {
842 "description":[
843 "She sells sea shells down by the sea shore.",
844 "Originally written by Terry Sullivan."
845 ]
846 }
847 ],
848 "links":[
849 {
850 "value":"https://example.com/entity/XXXX",
851 "rel":"self",
852 "href":"https://example.com/entity/XXXX",
853 "type" : "application/rdap+json"
854 }
855 ],
856 "events":[
857 {
858 "eventAction":"registration",
859 "eventDate":"1990-12-31T23:59:59Z"
860 }
861 ],
862 "asEventActor":[
863
864 {
865 "eventAction":"last changed",
866 "eventDate":"1991-12-31T23:59:59Z"
867 }
868 ]
869 }
870
871 Figure 15
872
873 The entity object class can contain the following members:
874
875 * objectClassName -- the string "entity"
876
877 * handle -- a string representing a registry-unique identifier of
878 the entity
879
880 * vcardArray -- a jCard with the entity's contact information
881
882 * roles -- an array of strings, each signifying the relationship an
883 object would have with its closest containing object (see
884 Section 10.2.4 for a list of values)
885
886 * publicIds -- see Section 4.8
887
888 * entities -- an array of entity objects as defined by this section
889
890 * remarks -- see Section 4.3
891
892 * links -- see Section 4.2
893
894 * events -- see Section 4.5
895
896 * asEventActor -- this data structure takes the same form as the
897 events data structure (see Section 4.5), but each object in the
898 array MUST NOT have an "eventActor" member. These objects denote
899 that the entity is an event actor for the given events. See
900 Appendix B regarding the various ways events can be modeled.
901
902 * status -- see Section 4.6
903
904 * port43 -- see Section 4.7
905
906 * networks -- an array of IP network objects as defined in
907 Section 5.4
908
909 * autnums -- an array of autnum objects as defined in Section 5.5
910
911 Entities may also have other entities embedded with them in an array.
912 This can be used to model an organization with specific individuals
913 fulfilling designated roles of responsibility.
914
915 The following is an elided example of an entity with embedded
916 entities.
917
918 {
919 "objectClassName" : "entity",
920 "handle" : "ANENTITY",
921 "roles" : [ "registrar" ],
922 ...
923 "entities" :
924 [
925 {
926 "objectClassName" : "entity",
927 "handle": "ANEMBEDDEDENTITY",
928 "roles" : [ "technical" ],
929 ...
930 },
931 ...
932 ],
933 ...
934 }
935
936 Figure 16
937
938 The following is an example of an entity that might be served by a
939 DNR.
940
941 {
942 "objectClassName" : "entity",
943 "handle":"XXXX",
944 "vcardArray":[
945 "vcard",
946 [
947 ["version", {}, "text", "4.0"],
948 ["fn", {}, "text", "Joe User"],
949 ["kind", {}, "text", "individual"],
950 ["lang", {
951 "pref":"1"
952 }, "language-tag", "fr"],
953 ["lang", {
954 "pref":"2"
955 }, "language-tag", "en"],
956 ["org", {
957 "type":"work"
958 }, "text", "Example"],
959 ["title", {}, "text", "Research Scientist"],
960 ["role", {}, "text", "Project Lead"],
961 ["adr",
962 { "type":"work" },
963 "text",
964 [
965 "",
966 "Suite 1234",
967 "4321 Rue Somewhere",
968 "Quebec",
969 "QC",
970 "G1V 2M2",
971 "Canada"
972 ]
973 ],
974 ["tel",
975 { "type":["work", "voice"], "pref":"1" },
976 "uri", "tel:+1-555-555-1234;ext=102"
977 ],
978 ["email",
979 { "type":"work" },
980 "text", "joe.user@example.com"
981 ]
982 ]
983 ],
984 "status":[ "validated", "locked" ],
985 "remarks":[
986 {
987 "description":[
988 "She sells sea shells down by the sea shore.",
989 "Originally written by Terry Sullivan."
990 ]
991 }
992 ],
993 "links":[
994 {
995 "value":"https://example.com/entity/XXXX",
996 "rel":"self",
997 "href":"https://example.com/entity/XXXX",
998 "type":"application/rdap+json"
999 }
1000 ],
1001 "port43":"whois.example.net",
1002 "events":[
1003 {
1004 "eventAction":"registration",
1005 "eventDate":"1990-12-31T23:59:59Z"
1006 },
1007 {
1008 "eventAction":"last changed",
1009 "eventDate":"1991-12-31T23:59:59Z",
1010 "eventActor":"joe@example.com"
1011 }
1012 ]
1013 }
1014
1015 Figure 17
1016
1017 See Appendix A for use of the entity object class to model various
1018 types of entities found in both RIRs and DNRs. See Appendix C
1019 regarding structured vs. unstructured postal addresses in entities.
1020
1021 5.2. The Nameserver Object Class
1022
1023 The nameserver object class represents information regarding DNS
1024 nameservers used in both forward and reverse DNS. RIRs and some DNRs
1025 register or expose nameserver information as an attribute of a domain
1026 name, while other DNRs model nameservers as "first class objects".
1027 Please note that some of the examples in this section include lines
1028 that have been wrapped for reading clarity.
1029
1030 The nameserver object class accommodates both models and degrees of
1031 variation in between.
1032
1033 The following is an example of a nameserver object.
1034
1035 {
1036 "objectClassName" : "nameserver",
1037 "handle" : "XXXX",
1038 "ldhName" : "ns1.xn--fo-5ja.example",
1039 "unicodeName" : "ns.fóo.example",
1040 "status" : [ "active" ],
1041 "ipAddresses" :
1042 {
1043 "v4": [ "192.0.2.1", "192.0.2.2" ],
1044 "v6": [ "2001:db8::123" ]
1045 },
1046 "remarks" :
1047 [
1048 {
1049 "description" :
1050 [
1051 "She sells sea shells down by the sea shore.",
1052 "Originally written by Terry Sullivan."
1053 ]
1054 }
1055 ],
1056 "links" :
1057 [
1058 {
1059 "value" : "https://example.net/nameserver/
1060 ns1.xn--fo-5ja.example",
1061 "rel" : "self",
1062 "href" : "https://example.net/nameserver/
1063 ns1.xn--fo-5ja.example",
1064 "type" : "application/rdap+json"
1065 }
1066 ],
1067 "port43" : "whois.example.net",
1068 "events" :
1069 [
1070 {
1071 "eventAction" : "registration",
1072 "eventDate" : "1990-12-31T23:59:59Z"
1073 },
1074 {
1075 "eventAction" : "last changed",
1076 "eventDate" : "1991-12-31T23:59:59Z",
1077 "eventActor" : "joe@example.com"
1078 }
1079 ]
1080 }
1081
1082 Figure 18
1083
1084 Figure 18 is an example of a nameserver object with all appropriate
1085 values given. Registries using a first-class nameserver data model
1086 would embed this in domain objects as well as allowing references to
1087 it with the "/nameserver" query type (all depending on the registry
1088 operators policy). Other registries may pare back the information as
1089 needed. Figure 19 is an example of a nameserver object as would be
1090 found in RIRs and some DNRs, while Figure 20 is an example of a
1091 nameserver object as would be found in other DNRs.
1092
1093 The following is an example of the simplest nameserver object:
1094
1095 {
1096 "objectClassName" : "nameserver",
1097 "ldhName" : "ns1.example.com"
1098 }
1099
1100 Figure 19
1101
1102 The following is an example of a simple nameserver object that might
1103 be commonly used by DNRs:
1104
1105 {
1106 "objectClassName" : "nameserver",
1107 "ldhName" : "ns1.example.com",
1108 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] }
1109 }
1110
1111 Figure 20
1112
1113 As nameservers can be modeled by some registries to be first-class
1114 objects, they may also have an array of entities (Section 5.1)
1115 embedded to signify parties responsible for the maintenance,
1116 registrations, etc., of the nameservers.
1117
1118 The following is an elided example of a nameserver with embedded
1119 entities.
1120
1121 {
1122 "objectClassName" : "nameserver",
1123 "handle" : "XXXX",
1124 "ldhName" : "ns.xn--fo-5ja.example",
1125 ...
1126 "entities" :
1127 [
1128 ...
1129 ],
1130 ...
1131 }
1132
1133 Figure 21
1134
1135 The nameserver object class can contain the following members:
1136
1137 * objectClassName -- the string "nameserver"
1138
1139 * handle -- a string representing a registry-unique identifier of
1140 the nameserver
1141
1142 * ldhName -- a string containing the LDH name of the nameserver (see
1143 Section 3)
1144
1145 * unicodeName -- a string containing a DNS Unicode name of the
1146 nameserver (see Section 3)
1147
1148 * ipAddresses -- an object containing the following members:
1149
1150 - v6 -- an array of strings containing IPv6 addresses of the
1151 nameserver
1152
1153 - v4 -- an array of strings containing IPv4 addresses of the
1154 nameserver
1155
1156 * entities -- an array of entity objects as defined by Section 5.1
1157
1158 * status -- see Section 4.6
1159
1160 * remarks -- see Section 4.3
1161
1162 * links -- see Section 4.2
1163
1164 * port43 -- see Section 4.7
1165
1166 * events -- see Section 4.5
1167
1168 5.3. The Domain Object Class
1169
1170 The domain object class represents a DNS name and point of
1171 delegation. For RIRs, these delegation points are in the reverse DNS
1172 tree, whereas for DNRs, these delegation points are in the forward
1173 DNS tree.
1174
1175 In both cases, the high-level structure of the domain object class
1176 consists of information about the domain registration, nameserver
1177 information related to the domain name, and entities related to the
1178 domain name (e.g., registrant information, contacts, etc.).
1179
1180 The following is an elided example of the domain object showing the
1181 high-level structure:
1182
1183 {
1184 "objectClassName" : "domain",
1185 "handle" : "XXX",
1186 "ldhName" : "blah.example.com",
1187 ...
1188 "nameservers" :
1189 [
1190 ...
1191 ],
1192 ...
1193 "entities" :
1194 [
1195 ...
1196 ]
1197 }
1198
1199 Figure 22
1200
1201 The domain object class can contain the following members:
1202
1203
1204 * objectClassName -- the string "domain"
1205
1206 * handle -- a string representing a registry-unique identifier of
1207 the domain object instance
1208
1209 * ldhName -- a string describing a domain name in LDH form as
1210 described in Section 3
1211
1212 * unicodeName -- a string containing a domain name with U-labels as
1213 described in Section 3
1214
1215 * variants -- an array of objects, each containing the following
1216 values:
1217
1218 - relation -- an array of strings, with each string denoting the
1219 relationship between the variants and the containing domain
1220 object (see Section 10.2.5 for a list of suggested variant
1221 relations).
1222
1223 - idnTable -- the character string literal that represents the
1224 Internationalized Domain Name (IDN) table that has been
1225 registered in the IANA Repository of IDN Practices
1226 [IANA_IDNTABLES].
1227
1228 - variantNames -- an array of objects, with each object
1229 containing an "ldhName" member and a "unicodeName" member (see
1230 Section 3).
1231
1232 * nameservers -- an array of nameserver objects as defined by
1233 Section 5.2
1234
1235 * secureDNS -- an object with the following members:
1236
1237 - zoneSigned -- boolean true if the zone has been signed, false
1238 otherwise.
1239
1240 - delegationSigned -- boolean true if there are DS records in the
1241 parent, false otherwise.
1242
1243 - maxSigLife -- an integer representing the signature lifetime in
1244 seconds to be used when creating the RRSIG DS record in the
1245 parent zone [RFC5910].
1246
1247 - dsData -- an array of objects, each with the following members:
1248
1249 o keyTag -- an integer as specified by the key tag field of a
1250 DNS DS record as specified by [RFC4034] in presentation
1251 format
1252
1253 o algorithm -- an integer as specified by the algorithm field
1254 of a DNS DS record as described by RFC 4034 in presentation
1255 format
1256
1257 o digest -- a string as specified by the digest field of a DNS
1258 DS record as specified by RFC 4034 in presentation format
1259
1260 o digestType -- an integer as specified by the digest type
1261 field of a DNS DS record as specified by RFC 4034 in
1262 presentation format
1263
1264 o events -- see Section 4.5
1265
1266 o links -- see Section 4.2
1267
1268 - keyData -- an array of objects, each with the following
1269 members:
1270
1271 o flags -- an integer representing the flags field value in
1272 the DNSKEY record [RFC4034] in presentation format
1273
1274 o protocol -- an integer representation of the protocol field
1275 value of the DNSKEY record [RFC4034] in presentation format
1276
1277 o publicKey -- a string representation of the public key in
1278 the DNSKEY record [RFC4034] in presentation format
1279
1280 o algorithm -- an integer as specified by the algorithm field
1281 of a DNSKEY record as specified by [RFC4034] in presentation
1282 format
1283
1284 o events -- see Section 4.5
1285
1286 o links -- see Section 4.2
1287
1288 See Appendix D for background information on these objects.
1289
1290 * entities -- an array of entity objects as defined by Section 5.1
1291
1292 * status -- see Section 4.6
1293
1294 * publicIds -- see Section 4.8
1295
1296 * remarks -- see Section 4.3
1297
1298 * links -- see Section 4.2
1299
1300 * port43 -- see Section 4.7
1301
1302 * events -- see Section 4.5
1303
1304 * network -- represents the IP network for which a reverse DNS
1305 domain is referenced; see Section 5.4
1306
1307 The following is an example of a JSON domain object representing a
1308 reverse DNS delegation point that might be served by an RIR (note
1309 that the dsData digest value has been modified to fit on one line).
1310
1311 {
1312 "objectClassName" : "domain",
1313 "handle" : "XXXX",
1314 "ldhName" : "0.2.192.in-addr.arpa",
1315 "nameservers" :
1316 [
1317 {
1318 "objectClassName" : "nameserver",
1319 "ldhName" : "ns1.rir.example"
1320 },
1321 {
1322 "objectClassName" : "nameserver",
1323 "ldhName" : "ns2.rir.example"
1324 }
1325 ],
1326 "secureDNS":
1327 {
1328 "delegationSigned": true,
1329 "dsData":
1330 [
1331 {
1332 "keyTag": 25345,
1333 "algorithm": 8,
1334 "digestType": 2,
1335 "digest": "2788970E18EA14...C890C85B8205B94"
1336 }
1337 ]
1338 },
1339 "remarks" :
1340 [
1341 {
1342 "description" :
1343 [
1344 "She sells sea shells down by the sea shore.",
1345 "Originally written by Terry Sullivan."
1346 ]
1347 }
1348 ],
1349 "links" :
1350 [
1351 {
1352 "value": "https://example.net/domain/0.2.192.in-addr.arpa",
1353 "rel" : "self",
1354 "href" : "https://example.net/domain/0.2.192.in-addr.arpa",
1355 "type" : "application/rdap+json"
1356
1357 }
1358 ],
1359 "events" :
1360 [
1361 {
1362 "eventAction" : "registration",
1363 "eventDate" : "1990-12-31T23:59:59Z"
1364 },
1365 {
1366 "eventAction" : "last changed",
1367 "eventDate" : "1991-12-31T23:59:59Z",
1368 "eventActor" : "joe@example.com"
1369 }
1370 ],
1371 "entities" :
1372 [
1373 {
1374 "objectClassName" : "entity",
1375 "handle" : "XXXX",
1376 "vcardArray":[
1377 "vcard",
1378 [
1379 ["version", {}, "text", "4.0"],
1380 ["fn", {}, "text", "Joe User"],
1381 ["kind", {}, "text", "individual"],
1382 ["lang", {
1383 "pref":"1"
1384 }, "language-tag", "fr"],
1385 ["lang", {
1386 "pref":"2"
1387 }, "language-tag", "en"],
1388 ["org", {
1389 "type":"work"
1390 }, "text", "Example"],
1391 ["title", {}, "text", "Research Scientist"],
1392 ["role", {}, "text", "Project Lead"],
1393 ["adr",
1394 { "type":"work" },
1395 "text",
1396 [
1397 "",
1398 "Suite 1234",
1399 "4321 Rue Somewhere",
1400 "Quebec",
1401 "QC",
1402 "G1V 2M2",
1403 "Canada"
1404 ]
1405
1406 ],
1407 ["tel",
1408 { "type":["work", "voice"], "pref":"1" },
1409 "uri", "tel:+1-555-555-1234;ext=102"
1410 ],
1411 ["email",
1412 { "type":"work" },
1413 "text", "joe.user@example.com"
1414 ]
1415 ]
1416 ],
1417 "roles" : [ "registrant" ],
1418 "remarks" :
1419 [
1420 {
1421 "description" :
1422 [
1423 "She sells sea shells down by the sea shore.",
1424 "Originally written by Terry Sullivan."
1425 ]
1426 }
1427 ],
1428 "links" :
1429 [
1430 {
1431 "value": "https://example.net/entity/XXXX",
1432 "rel" : "self",
1433 "href" : "https://example.net/entity/XXXX",
1434 "type" : "application/rdap+json"
1435 }
1436 ],
1437 "events" :
1438 [
1439 {
1440 "eventAction" : "registration",
1441 "eventDate" : "1990-12-31T23:59:59Z"
1442 },
1443 {
1444 "eventAction" : "last changed",
1445 "eventDate" : "1991-12-31T23:59:59Z",
1446 "eventActor" : "joe@example.com"
1447 }
1448 ]
1449 }
1450 ],
1451 "network" :
1452 {
1453 "objectClassName" : "ip network",
1454 "handle" : "XXXX-RIR",
1455 "startAddress" : "192.0.2.0",
1456 "endAddress" : "192.0.2.255",
1457 "ipVersion" : "v4",
1458 "name": "NET-RTR-1",
1459 "type" : "DIRECT ALLOCATION",
1460 "country" : "AU",
1461 "parentHandle" : "YYYY-RIR",
1462 "status" : [ "active" ]
1463 }
1464 }
1465
1466 Figure 23
1467
1468 The following is an example of a JSON domain object representing a
1469 forward DNS delegation point that might be served by a DNR. Note
1470 that the secureDNS keyData publicKey value has been modified to fit
1471 on a single line.
1472
1473 {
1474 "objectClassName" : "domain",
1475 "handle" : "XXXX",
1476 "ldhName" : "xn--fo-5ja.example",
1477 "unicodeName" : "fóo.example",
1478 "variants" :
1479 [
1480 {
1481 "relation" : [ "registered", "conjoined" ],
1482 "variantNames" :
1483 [
1484 {
1485 "ldhName" : "xn--fo-cka.example",
1486 "unicodeName" : "fõo.example"
1487 },
1488 {
1489 "ldhName" : "xn--fo-fka.example",
1490 "unicodeName" : "föo.example"
1491 }
1492 ]
1493 },
1494 {
1495 "relation" : [ "unregistered", "registration restricted" ],
1496 "idnTable": ".EXAMPLE Swedish",
1497 "variantNames" :
1498 [
1499 {
1500 "ldhName": "xn--fo-8ja.example",
1501 "unicodeName" : "fôo.example"
1502 }
1503 ]
1504
1505 }
1506 ],
1507 "status" : [ "locked", "transfer prohibited" ],
1508 "publicIds":[
1509 {
1510 "type":"ENS_Auth ID",
1511 "identifier":"1234567890"
1512 }
1513 ],
1514 "nameservers" :
1515 [
1516 {
1517 "objectClassName" : "nameserver",
1518 "handle" : "XXXX",
1519 "ldhName" : "ns1.example.com",
1520 "status" : [ "active" ],
1521 "ipAddresses" :
1522 {
1523 "v6": [ "2001:db8::123", "2001:db8::124" ],
1524 "v4": [ "192.0.2.1", "192.0.2.2" ]
1525 },
1526 "remarks" :
1527 [
1528 {
1529 "description" :
1530 [
1531 "She sells sea shells down by the sea shore.",
1532 "Originally written by Terry Sullivan."
1533 ]
1534 }
1535 ],
1536 "links" :
1537 [
1538 {
1539 "value" : "https://example.net/nameserver/ns1.example.com",
1540 "rel" : "self",
1541 "href" : "https://example.net/nameserver/ns1.example.com",
1542 "type" : "application/rdap+json"
1543 }
1544 ],
1545 "events" :
1546 [
1547 {
1548 "eventAction" : "registration",
1549 "eventDate" : "1990-12-31T23:59:59Z"
1550 },
1551 {
1552 "eventAction" : "last changed",
1553 "eventDate" : "1991-12-31T23:59:59Z"
1554 }
1555 ]
1556 },
1557 {
1558 "objectClassName" : "nameserver",
1559 "handle" : "XXXX",
1560 "ldhName" : "ns2.example.com",
1561 "status" : [ "active" ],
1562 "ipAddresses" :
1563 {
1564 "v6" : [ "2001:db8::125", "2001:db8::126" ],
1565 "v4" : [ "192.0.2.3", "192.0.2.4" ]
1566 },
1567 "remarks" :
1568 [
1569 {
1570 "description" :
1571 [
1572 "She sells sea shells down by the sea shore.",
1573 "Originally written by Terry Sullivan."
1574 ]
1575 }
1576 ],
1577 "links" :
1578 [
1579 {
1580 "value" : "https://example.net/nameserver/ns2.example.com",
1581 "rel" : "self",
1582 "href" : "https://example.net/nameserver/ns2.example.com",
1583 "type" : "application/rdap+json"
1584 }
1585 ],
1586 "events" :
1587 [
1588 {
1589 "eventAction" : "registration",
1590 "eventDate" : "1990-12-31T23:59:59Z"
1591 },
1592 {
1593 "eventAction" : "last changed",
1594 "eventDate" : "1991-12-31T23:59:59Z"
1595 }
1596 ]
1597 }
1598 ],
1599 "secureDNS":
1600 {
1601
1602 "zoneSigned": true,
1603 "delegationSigned": true,
1604 "maxSigLife": 604800,
1605 "keyData":
1606 [
1607 {
1608 "flags": 257,
1609 "protocol": 3,
1610 "algorithm": 8,
1611 "publicKey": "AwEAAa6eDzronzjEDbT...Jg1M5N rBSPkuXpdFE=",
1612 "events":
1613 [
1614 {
1615 "eventAction": "last changed",
1616 "eventDate": "2012-07-23T05:15:47Z"
1617 }
1618 ]
1619 }
1620 ]
1621 },
1622 "remarks" :
1623 [
1624 {
1625 "description" :
1626 [
1627 "She sells sea shells down by the sea shore.",
1628 "Originally written by Terry Sullivan."
1629 ]
1630 }
1631 ],
1632 "links" :
1633 [
1634 {
1635 "value": "https://example.net/domain/xn--fo-5ja.example",
1636 "rel" : "self",
1637 "href" : "https://example.net/domain/xn--fo-5ja.example",
1638 "type" : "application/rdap+json"
1639 }
1640 ],
1641 "port43" : "whois.example.net",
1642 "events" :
1643 [
1644 {
1645 "eventAction" : "registration",
1646 "eventDate" : "1990-12-31T23:59:59Z"
1647 },
1648 {
1649 "eventAction" : "last changed",
1650 "eventDate" : "1991-12-31T23:59:59Z",
1651 "eventActor" : "joe@example.com"
1652 },
1653 {
1654 "eventAction" : "transfer",
1655 "eventDate" : "1991-12-31T23:59:59Z",
1656 "eventActor" : "joe@example.com"
1657 },
1658 {
1659 "eventAction" : "expiration",
1660 "eventDate" : "2016-12-31T23:59:59Z",
1661 "eventActor" : "joe@example.com"
1662 }
1663 ],
1664 "entities" :
1665 [
1666 {
1667 "objectClassName" : "entity",
1668 "handle" : "XXXX",
1669 "vcardArray":[
1670 "vcard",
1671 [
1672 ["version", {}, "text", "4.0"],
1673 ["fn", {}, "text", "Joe User"],
1674 ["kind", {}, "text", "individual"],
1675 ["lang", {
1676 "pref":"1"
1677 }, "language-tag", "fr"],
1678 ["lang", {
1679 "pref":"2"
1680 }, "language-tag", "en"],
1681 ["org", {
1682 "type":"work"
1683 }, "text", "Example"],
1684 ["title", {}, "text", "Research Scientist"],
1685 ["role", {}, "text", "Project Lead"],
1686 ["adr",
1687 { "type":"work" },
1688 "text",
1689 [
1690 "",
1691 "Suite 1234",
1692 "4321 Rue Somewhere",
1693 "Quebec",
1694 "QC",
1695 "G1V 2M2",
1696 "Canada"
1697 ]
1698
1699 ],
1700 ["tel",
1701 { "type":["work", "voice"], "pref":"1" },
1702 "uri", "tel:+1-555-555-1234;ext=102"
1703 ],
1704 ["email",
1705 { "type":"work" },
1706 "text", "joe.user@example.com"
1707 ]
1708 ]
1709 ],
1710 "status" : [ "validated", "locked" ],
1711 "roles" : [ "registrant" ],
1712 "remarks" :
1713 [
1714 {
1715 "description" :
1716 [
1717 "She sells sea shells down by the sea shore.",
1718 "Originally written by Terry Sullivan."
1719 ]
1720 }
1721 ],
1722 "links" :
1723 [
1724 {
1725 "value" : "https://example.net/entity/XXXX",
1726 "rel" : "self",
1727 "href" : "https://example.net/entity/XXXX",
1728 "type" : "application/rdap+json"
1729 }
1730 ],
1731 "events" :
1732 [
1733 {
1734 "eventAction" : "registration",
1735 "eventDate" : "1990-12-31T23:59:59Z"
1736 },
1737 {
1738 "eventAction" : "last changed",
1739 "eventDate" : "1991-12-31T23:59:59Z"
1740 }
1741 ]
1742 }
1743 ]
1744 }
1745
1746 Figure 24
1747
1748 5.4. The IP Network Object Class
1749
1750 The IP network object class models IP network registrations found in
1751 RIRs and is the expected response for the "/ip" query as defined by
1752 [RFC9082]. There is no equivalent object class for DNRs. The high-
1753 level structure of the IP network object class consists of
1754 information about the network registration and entities related to
1755 the IP network (e.g., registrant information, contacts, etc.).
1756
1757 The following is an elided example of the IP network object type
1758 showing the high-level structure:
1759
1760 {
1761 "objectClassName" : "ip network",
1762 "handle" : "XXX",
1763 ...
1764 "entities" :
1765 [
1766 ...
1767 ]
1768 }
1769
1770 Figure 25
1771
1772 The following is an example of the JSON object for the network
1773 registration information.
1774
1775 {
1776 "objectClassName" : "ip network",
1777 "handle" : "XXXX-RIR",
1778 "startAddress" : "2001:db8::",
1779 "endAddress" : "2001:db8:0:ffff:ffff:ffff:ffff:ffff",
1780 "ipVersion" : "v6",
1781 "name": "NET-RTR-1",
1782 "type" : "DIRECT ALLOCATION",
1783 "country" : "AU",
1784 "parentHandle" : "YYYY-RIR",
1785 "status" : [ "active" ],
1786 "remarks" :
1787 [
1788 {
1789 "description" :
1790 [
1791 "She sells sea shells down by the sea shore.",
1792 "Originally written by Terry Sullivan."
1793 ]
1794 }
1795 ],
1796 "links" :
1797 [
1798 {
1799 "value" : "https://example.net/ip/2001:db8::/48",
1800 "rel" : "self",
1801 "href" : "https://example.net/ip/2001:db8::/48",
1802 "type" : "application/rdap+json"
1803 },
1804 {
1805 "value" : "https://example.net/ip/2001:db8::/48",
1806 "rel" : "up",
1807 "href" : "https://example.net/ip/2001:db8::/32",
1808 "type" : "application/rdap+json"
1809 }
1810 ],
1811 "events" :
1812 [
1813 {
1814 "eventAction" : "registration",
1815 "eventDate" : "1990-12-31T23:59:59Z"
1816 },
1817 {
1818 "eventAction" : "last changed",
1819 "eventDate" : "1991-12-31T23:59:59Z"
1820 }
1821 ],
1822 "entities" :
1823 [
1824 {
1825 "objectClassName" : "entity",
1826 "handle" : "XXXX",
1827 "vcardArray":[
1828 "vcard",
1829 [
1830 ["version", {}, "text", "4.0"],
1831 ["fn", {}, "text", "Joe User"],
1832 ["kind", {}, "text", "individual"],
1833 ["lang", {
1834 "pref":"1"
1835 }, "language-tag", "fr"],
1836 ["lang", {
1837 "pref":"2"
1838 }, "language-tag", "en"],
1839 ["org", {
1840 "type":"work"
1841 }, "text", "Example"],
1842 ["title", {}, "text", "Research Scientist"],
1843 ["role", {}, "text", "Project Lead"],
1844 ["adr",
1845 { "type":"work" },
1846 "text",
1847 [
1848 "",
1849 "Suite 1234",
1850 "4321 Rue Somewhere",
1851 "Quebec",
1852 "QC",
1853 "G1V 2M2",
1854 "Canada"
1855 ]
1856 ],
1857 ["tel",
1858 { "type":["work", "voice"], "pref":"1" },
1859 "uri", "tel:+1-555-555-1234;ext=102"
1860 ],
1861 ["email",
1862 { "type":"work" },
1863 "text", "joe.user@example.com"
1864 ]
1865 ]
1866 ],
1867 "roles" : [ "registrant" ],
1868 "remarks" :
1869 [
1870 {
1871 "description" :
1872 [
1873 "She sells sea shells down by the sea shore.",
1874 "Originally written by Terry Sullivan."
1875 ]
1876 }
1877 ],
1878 "links" :
1879 [
1880 {
1881 "value" : "https://example.net/entity/xxxx",
1882 "rel" : "self",
1883 "href" : "https://example.net/entity/xxxx",
1884 "type" : "application/rdap+json"
1885 }
1886 ],
1887 "events" :
1888 [
1889 {
1890 "eventAction" : "registration",
1891 "eventDate" : "1990-12-31T23:59:59Z"
1892
1893 },
1894 {
1895 "eventAction" : "last changed",
1896 "eventDate" : "1991-12-31T23:59:59Z"
1897 }
1898 ]
1899 }
1900 ]
1901 }
1902
1903 Figure 26
1904
1905 The IP network object class can contain the following members:
1906
1907 * objectClassName -- the string "ip network"
1908
1909 * handle -- a string representing the RIR-unique identifier of the
1910 network registration
1911
1912 * startAddress -- a string representing the starting IP address of
1913 the network, either IPv4 or IPv6
1914
1915 * endAddress -- a string representing the ending IP address of the
1916 network, either IPv4 or IPv6
1917
1918 * ipVersion -- a string signifying the IP protocol version of the
1919 network: "v4" signifies an IPv4 network, and "v6" signifies an
1920 IPv6 network
1921
1922 * name -- a string representing an identifier assigned to the
1923 network registration by the registration holder
1924
1925 * type -- a string containing an RIR-specific classification of the
1926 network per that RIR's registration model
1927
1928 * country -- a string containing the two-character country code of
1929 the network
1930
1931 * parentHandle -- a string containing an RIR-unique identifier of
1932 the parent network of this network registration
1933
1934 * status -- an array of strings indicating the state of the IP
1935 network as defined by Section 4.6
1936
1937 * entities -- an array of entity objects as defined by Section 5.1
1938
1939 * remarks -- see Section 4.3
1940
1941 * links -- see Section 4.2
1942
1943 * port43 -- see Section 4.7
1944
1945 * events -- see Section 4.5
1946
1947 5.5. The Autonomous System Number Object Class
1948
1949 The Autonomous System number (autnum) object class models Autonomous
1950 System number registrations found in RIRs and represents the expected
1951 response to an "/autnum" query as defined by [RFC9082]. There is no
1952 equivalent object class for DNRs. The high-level structure of the
1953 autnum object class consists of information about the Autonomous
1954 System number registration and entities related to the autnum
1955 registration (e.g., registrant information, contacts, etc.) and is
1956 similar to the IP network object class.
1957
1958 The following is an example of a JSON object representing an autnum.
1959
1960 {
1961 "objectClassName" : "autnum",
1962 "handle" : "XXXX-RIR",
1963 "startAutnum" : 65536,
1964 "endAutnum" : 65541,
1965 "name": "AS-RTR-1",
1966 "type" : "DIRECT ALLOCATION",
1967 "status" : [ "active" ],
1968 "country": "AU",
1969 "remarks" :
1970 [
1971 {
1972 "description" :
1973 [
1974 "She sells sea shells down by the sea shore.",
1975 "Originally written by Terry Sullivan."
1976 ]
1977 }
1978 ],
1979 "links" :
1980 [
1981 {
1982 "value" : "https://example.net/autnum/65537",
1983 "rel" : "self",
1984 "href" : "https://example.net/autnum/65537",
1985 "type" : "application/rdap+json"
1986 }
1987 ],
1988 "events" :
1989
1990 [
1991 {
1992 "eventAction" : "registration",
1993 "eventDate" : "1990-12-31T23:59:59Z"
1994 },
1995 {
1996 "eventAction" : "last changed",
1997 "eventDate" : "1991-12-31T23:59:59Z"
1998 }
1999 ],
2000 "entities" :
2001 [
2002 {
2003 "objectClassName" : "entity",
2004 "handle" : "XXXX",
2005 "vcardArray":[
2006 "vcard",
2007 [
2008 ["version", {}, "text", "4.0"],
2009 ["fn", {}, "text", "Joe User"],
2010 ["kind", {}, "text", "individual"],
2011 ["lang", {
2012 "pref":"1"
2013 }, "language-tag", "fr"],
2014 ["lang", {
2015 "pref":"2"
2016 }, "language-tag", "en"],
2017 ["org", {
2018 "type":"work"
2019 }, "text", "Example"],
2020 ["title", {}, "text", "Research Scientist"],
2021 ["role", {}, "text", "Project Lead"],
2022 ["adr",
2023 { "type":"work" },
2024 "text",
2025 [
2026 "",
2027 "Suite 1234",
2028 "4321 Rue Somewhere",
2029 "Quebec",
2030 "QC",
2031 "G1V 2M2",
2032 "Canada"
2033 ]
2034 ],
2035 ["tel",
2036 { "type":["work", "voice"], "pref":"1" },
2037 "uri", "tel:+1-555-555-1234;ext=102"
2038 ],
2039 ["email",
2040 { "type":"work" },
2041 "text", "joe.user@example.com"
2042 ]
2043 ]
2044 ],
2045 "roles" : [ "registrant" ],
2046 "remarks" :
2047 [
2048 {
2049 "description" :
2050 [
2051 "She sells sea shells down by the sea shore.",
2052 "Originally written by Terry Sullivan."
2053 ]
2054 }
2055 ],
2056 "links" :
2057 [
2058 {
2059 "value" : "https://example.net/entity/XXXX",
2060 "rel" : "self",
2061 "href" : "https://example.net/entity/XXXX",
2062 "type" : "application/rdap+json"
2063 }
2064 ],
2065 "events" :
2066 [
2067 {
2068 "eventAction" : "registration",
2069 "eventDate" : "1990-12-31T23:59:59Z"
2070 },
2071 {
2072 "eventAction" : "last changed",
2073 "eventDate" : "1991-12-31T23:59:59Z"
2074 }
2075 ]
2076 }
2077 ]
2078 }
2079
2080 Figure 27
2081
2082 The Autonomous System number object class can contain the following
2083 members:
2084
2085 * objectClassName -- the string "autnum"
2086
2087 * handle -- a string representing the RIR-unique identifier of the
2088 autnum registration
2089
2090 * startAutnum -- an unsigned 32-bit integer representing the
2091 starting number [RFC5396] in the block of Autonomous System
2092 numbers
2093
2094 * endAutnum -- an unsigned 32-bit integer representing the ending
2095 number [RFC5396] in the block of Autonomous System numbers
2096
2097 * name -- a string representing an identifier assigned to the autnum
2098 registration by the registration holder
2099
2100 * type -- a string containing an RIR-specific classification of the
2101 autnum per that RIR's registration model
2102
2103 * status -- an array of strings indicating the state of the autnum
2104 as defined by Section 4.6
2105
2106 * country -- a string containing the two-character country code of
2107 the autnum
2108
2109 * entities -- an array of entity objects as defined by Section 5.1
2110
2111 * remarks -- see Section 4.3
2112
2113 * links -- see Section 4.2
2114
2115 * port43 -- see Section 4.7
2116
2117 * events -- see Section 4.5
2118
The data structure named "rdapConformance" is an array of strings, each providing a hint as to the specifications used in the construction of the response.
The data structure named "rdapConformance" is an array of strings, each identifying a registered specification used in the construction of the response.
The original text uses the word "hint", which some people have interpreted to mean "not normative" and/or "can be ignored". This misinterpretation will likely cause significant misunderstanding of the technical specification and might result in faulty implementations if not corrected. The intention and meaning of this sentence is more clearly specified with the corrected text, noting that the array of string identifiers is directly associated with the set of specifications used to construct an RDAP response.
2119 6. Error Response Body
2120
2121 Some non-answer responses MAY return entity bodies with information
2122 that could be more descriptive.
2123
2124 The basic structure of that response is an object class containing a
2125 REQUIRED error code number (corresponding to the HTTP response code)
2126 followed by an OPTIONAL string named "title" and an OPTIONAL array of
2127 strings named "description".
2128
2129 This is an example of the common response body.
2130
2131 {
2132 "errorCode": 418,
2133 "title": "Your Beverage Choice is Not Available",
2134 "description":
2135 [
2136 "I know coffee has more ummppphhh.",
2137 "Sorry, dude!"
2138 ]
2139 }
2140
2141 Figure 28
2142
2143 This is an example of the common response body with an
2144 rdapConformance and notices data structures:
2145
2146 {
2147 "rdapConformance" :
2148 [
2149 "rdap_level_0"
2150 ],
2151 "notices" :
2152 [
2153 {
2154 "title" : "Beverage Policy",
2155 "description" :
2156 [
2157 "Beverages with caffeine for keeping horses awake."
2158 ],
2159 "links" :
2160 [
2161 {
2162 "value" : "https://example.net/ip/192.0.2.0/24",
2163 "rel" : "alternate",
2164 "type" : "text/html",
2165 "href" : "https://www.example.com/redaction_policy.html"
2166 }
2167 ]
2168 }
2169 ],
2170 "lang" : "en",
2171 "errorCode": 418,
2172 "title": "Your beverage choice is not available",
2173 "description":
2174 [
2175 "I know coffee has more ummppphhh.",
2176 "Sorry, dude!"
2177 ]
2178 }
2179
2180 Figure 29
2181
2182 7. Responding to Help Queries
2183
2184 The appropriate response to /help queries as defined by [RFC9082] is
2185 to use the notices structure as defined in Section 4.3.
2186
2187 This is an example of a response to a /help query including the
2188 rdapConformance data structure.
2189
2190 {
2191 "rdapConformance" :
2192 [
2193 "rdap_level_0"
2194 ],
2195 "notices" :
2196 [
2197 {
2198 "title" : "Authentication Policy",
2199 "description" :
2200 [
2201 "Access to sensitive data for users with proper credentials."
2202 ],
2203 "links" :
2204 [
2205 {
2206 "value" : "https://example.net/help",
2207 "rel" : "alternate",
2208 "type" : "text/html",
2209 "href" : "https://www.example.com/auth_policy.html"
2210 }
2211 ]
2212 }
2213 ]
2214 }
2215
2216 Figure 30
2217
2218 8. Responding To Searches
2219
2220 [RFC9082] specifies three types of searches: domains, nameservers,
2221 and entities. Responses to these searches take the form of an array
2222 of object instances where each instance is an appropriate object
2223 class for the search (i.e., a search for /domains yields an array of
2224 domain object instances). These arrays are contained within the
2225 response object.
2226
2227 The names of the arrays are as follows:
2228
2229 * for /domains searches, the array is "domainSearchResults"
2230
2231 * for /nameservers searches, the array is "nameserverSearchResults"
2232
2233 * for /entities searches, the array is "entitySearchResults"
2234
2235 The following is an elided example of a response to a /domains
2236 search.
2237
2238 {
2239 "rdapConformance" :
2240 [
2241 "rdap_level_0"
2242 ],
2243 ...
2244 "domainSearchResults" :
2245 [
2246 {
2247 "objectClassName" : "domain",
2248 "handle" : "1-XXXX",
2249 "ldhName" : "1.example.com",
2250 ...
2251 },
2252 {
2253 "objectClassName" : "domain",
2254 "handle" : "2-XXXX",
2255 "ldhName" : "2.example.com",
2256 ...
2257 }
2258 ]
2259 }
2260
2261 Figure 31
2262
This is an example of the common response body.
{
"errorCode": 418,
"title": "Your Beverage Choice is Not Available",
"description":
[
"I know coffee has more ummppphhh.",
"Sorry, dude!"
]
}
This is an example of the common response body.
{
"rdapConformance" :
[
"rdap_level_0"
],
"errorCode": 418,
"title": "Your Beverage Choice is Not Available",
"description":
[
"I know coffee has more ummppphhh.",
"Sorry, dude!"
]
}
RFC 9083 4.1 states that the rdapConformance data structure MUST appear in the topmost JSON object of RDAP responses. The example error response provided in Figure 28 should include the rdapConformance property but does not. --VERIFIER NOTES-- The example cited in Figure 28 is described in the text as a "common response body", not a complete RDAP response. The error response body is described in the context of a complete RDAP response in Figure 29, which includes an rdapConformance data structure. As such, the examples in the two figures are fine as-is.
2263 9. Indicating Truncated Responses
2264
2265 In cases where the data of a response needs to be limited or parts of
2266 the data need to be omitted, the response is considered "truncated".
2267 A truncated response is still valid JSON, but some of the results in
2268 a search set or some of the data in an object are not provided by the
2269 server. A server may indicate this by including a typed notice in
2270 the response object.
2271
2272 The following is an elided example of a search response that has been
2273 truncated.
2274
2275 {
2276 "rdapConformance" :
2277 [
2278 "rdap_level_0"
2279 ],
2280 "notices" :
2281 [
2282 {
2283 "title" : "Search Policy",
2284 "type" : "result set truncated due to authorization",
2285 "description" :
2286 [
2287 "Search results are limited to 25 per day per querying IP."
2288 ],
2289 "links" :
2290 [
2291 {
2292 "value" : "https://example.net/help",
2293 "rel" : "alternate",
2294 "type" : "text/html",
2295 "href" : "https://www.example.com/search_policy.html"
2296 }
2297 ]
2298 }
2299 ],
2300 "domainSearchResults" :
2301 [
2302 ...
2303 ]
2304 }
2305
2306 Figure 32
2307
2308 A similar technique can be used with a typed remark where a single
2309 object has been returned and data in that object has been truncated.
2310 Such an example might be an entity object with only a partial set of
2311 the IP networks associated with it.
2312
2313 The following is an elided example of an entity truncated data.
2314
2315 {
2316 "objectClassName" : "entity",
2317 "handle" : "ANENTITY",
2318 "roles" : [ "registrant" ],
2319 ...
2320 "entities" :
2321 [
2322 {
2323 "objectClassName" : "entity",
2324 "handle": "ANEMBEDDEDENTITY",
2325 "roles" : [ "technical" ],
2326 ...
2327 },
2328 ...
2329 ],
2330 "networks" :
2331 [
2332 ...
2333 ],
2334 ...
2335 "remarks" :
2336 [
2337 {
2338 "title" : "Data Policy",
2339 "type" : "object truncated due to unexplainable reason",
2340 "description" :
2341 [
2342 "Some of the data in this object has been removed."
2343 ],
2344 "links" :
2345 [
2346 {
2347 "value" : "https://example.net/help",
2348 "rel" : "alternate",
2349 "type" : "text/html",
2350 "href" : "https://www.example.com/data_policy.html"
2351 }
2352 ]
2353 }
2354 ]
2355 }
2356
2357 Figure 33
2358
2359 10. IANA Considerations
2360
2361 IANA has updated the description of the "transfer" event action as
2362 described in Section 10.2.3.
2363
2364 10.1. RDAP JSON Media Type Registration
2365
2366 IANA has updated the media type registration as described below.
2367
2368 This specification registers the "application/rdap+json" media type.
2369
2370 Type name: application
2371
2372 Subtype name: rdap+json
2373
2374 Required parameters: n/a
2375
2376 Encoding considerations: See Section 3.1 of [RFC6839].
2377
2378 Security considerations: The media represented by this identifier
2379 does not have security considerations beyond that found in
2380 Section 12 of [RFC8259].
2381
2382 Interoperability considerations: There are no known interoperability
2383 problems regarding this media format.
2384
2385 Published specification: RFC 9083
2386
2387 Applications that use this media type: Implementations of the
2388 Registration Data Access Protocol (RDAP).
2389
2390 Additional information: This media type is a product of the IETF
2391 REGEXT Working Group. The REGEXT charter, information on the
2392 REGEXT mailing list, and other documents produced by the REGEXT
2393 Working Group can be found at https://datatracker.ietf.org/wg/
2394 regext/.
2395
2396 Person & email address to contact for further information:
2397 IESG <iesg@ietf.org>
2398
2399 Intended usage: COMMON
2400
2401 Restrictions on usage: none
2402
2403 Author: Andy Newton
2404
2405 Change controller: IETF
2406
2407 Provisional Registration: No
2408
2409 10.2. JSON Values Registry
2410
2411 IANA has created a category in the protocol registries labeled
2412 "Registration Data Access Protocol (RDAP)", and within that category,
2413 IANA has established a URL-referenceable, stand-alone registry
2414 labeled "RDAP JSON Values". This new registry is for use in the
2415 notices and remarks (Section 4.3), status (Section 4.6), role
2416 (Section 5.1), event action (Section 4.5), and domain variant
2417 relation (Section 5.3) fields specified in RDAP.
2418
2419 Each entry in the registry contains the following fields:
2420
2421 1. Value -- the string value being registered.
2422
2423 2. Type -- the type of value being registered. It should be one of
2424 the following:
2425
2426 * "notice or remark type" -- denotes a type of notice or remark.
2427
2428 * "status" -- denotes a value for the "status" object member as
2429 defined by Section 4.6.
2430
2431 * "role" -- denotes a value for the "role" array as defined in
2432 Section 5.1.
2433
2434 * "event action" -- denotes a value for an event action as
2435 defined in Section 4.5.
2436
2437 * "domain variant relation" -- denotes a relationship between a
2438 domain and a domain variant as defined in Section 5.3.
2439
2440 3. Description -- a one- or two-sentence description regarding the
2441 meaning of the value, how it might be used, and/or how it should
2442 be interpreted by clients.
2443
2444 4. Registrant Name -- the name of the person registering the value.
2445
2446 5. Registrant Contact Information -- an email address, postal
2447 address, or some other information to be used to contact the
2448 registrant.
2449
2450 This registry is operated under the "Expert Review" policy defined in
2451 [RFC8126].
2452
2453 Review of registrations into this registry by the designated
2454 expert(s) should be narrowly judged on the following criteria:
2455
2456 1. Values in need of being placed into multiple types must be
2457 assigned a separate registration for each type.
2458
2459 2. Values must be strings. They should be multiple words separated
2460 by single space characters. Every character should be
2461 lowercased. If possible, every word should be given in English
2462 and each character should be US-ASCII.
2463
2464 3. Registrations should not duplicate the meaning of any existing
2465 registration. That is, if a request for a registration is
2466 significantly similar in nature to an existing registration, the
2467 request should be denied. For example, the terms "maintainer"
2468 and "registrant" are significantly similar in nature as they both
2469 denote a holder of a domain name or Internet number resource. In
2470 cases where it may be reasonably argued that machine
2471 interpretation of two similar values may alter the operation of
2472 client software, designated experts should not judge the values
2473 to be of significant similarity.
2474
2475 4. Registrations should be relevant to the common usages of RDAP.
2476 Designated experts may rely upon the serving of the value by a
2477 DNR or RIR to make this determination.
2478
2479 The following sections provide initial registrations into this
2480 registry.
2481
2482 10.2.1. Notice and Remark Types
2483
2484 The following values have been registered in the "RDAP JSON Values"
2485 registry:
2486
2487 Value: result set truncated due to authorization
2488 Type: notice and remark type
2489 Description: The list of results does not contain all results due to
2490 lack of authorization. This may indicate to some clients that
2491 proper authorization will yield a longer result set.
2492 Registrant Name: IESG
2493 Registrant Contact Information: iesg@ietf.org
2494
2495 Value: result set truncated due to excessive load
2496 Type: notice and remark type
2497 Description: The list of results does not contain all results due to
2498 an excessively heavy load on the server. This may indicate to
2499 some clients that requerying at a later time will yield a longer
2500 result set.
2501 Registrant Name: IESG
2502 Registrant Contact Information: iesg@ietf.org
2503
2504 Value: result set truncated due to unexplainable reasons
2505 Type: notice and remark type
2506 Description: The list of results does not contain all results for an
2507 unexplainable reason. This may indicate to some clients that
2508 requerying for any reason will not yield a longer result set.
2509 Registrant Name: IESG
2510 Registrant Contact Information: iesg@ietf.org
2511
2512 Value: object truncated due to authorization
2513 Type: notice and remark type
2514 Description: The object does not contain all data due to lack of
2515 authorization.
2516 Registrant Name: IESG
2517 Registrant Contact Information: iesg@ietf.org
2518
2519 Value: object truncated due to excessive load
2520 Type: notice and remark type
2521 Description: The object does not contain all data due to an
2522 excessively heavy load on the server. This may indicate to some
2523 clients that requerying at a later time will yield all data of the
2524 object.
2525 Registrant Name: IESG
2526 Registrant Contact Information: iesg@ietf.org
2527
2528 Value: object truncated due to unexplainable reasons
2529 Type: notice and remark type
2530 Description: The object does not contain all data for an
2531 unexplainable reason.
2532 Registrant Name: IESG
2533 Registrant Contact Information: iesg@ietf.org
2534
2535 10.2.2. Status
2536
2537 The following values have been registered in the "RDAP JSON Values"
2538 registry:
2539
2540 Value: validated
2541 Type: status
2542 Description: Signifies that the data of the object instance has been
2543 found to be accurate. This type of status is usually found on
2544 entity object instances to note the validity of identifying
2545 contact information.
2546 Registrant Name: IESG
2547 Registrant Contact Information: iesg@ietf.org
2548
2549 Value: renew prohibited
2550 Type: status
2551 Description: Renewal or reregistration of the object instance is
2552 forbidden.
2553 Registrant Name: IESG
2554 Registrant Contact Information: iesg@ietf.org
2555
2556 Value: update prohibited
2557 Type: status
2558 Description: Updates to the object instance are forbidden.
2559 Registrant Name: IESG
2560 Registrant Contact Information: iesg@ietf.org
2561
2562 Value: transfer prohibited
2563 Type: status
2564 Description: Transfers of the registration from one registrar to
2565 another are forbidden. This type of status normally applies to
2566 DNR domain names.
2567 Registrant Name: IESG
2568 Registrant Contact Information: iesg@ietf.org
2569
2570 Value: delete prohibited
2571 Type: status
2572 Description: Deletion of the registration of the object instance is
2573 forbidden. This type of status normally applies to DNR domain
2574 names.
2575 Registrant Name: IESG
2576 Registrant Contact Information: iesg@ietf.org
2577
2578 Value: proxy
2579 Type: status
2580 Description: The registration of the object instance has been
2581 performed by a third party. This is most commonly applied to
2582 entities.
2583 Registrant Name: IESG
2584 Registrant Contact Information: iesg@ietf.org
2585
2586 Value: private
2587 Type: status
2588 Description: The information of the object instance is not
2589 designated for public consumption. This is most commonly applied
2590 to entities.
2591 Registrant Name: IESG
2592 Registrant Contact Information: iesg@ietf.org
2593
2594 Value: removed
2595 Type: status
2596 Description: Some of the information of the object instance has not
2597 been made available and has been removed. This is most commonly
2598 applied to entities.
2599 Registrant Name: IESG
2600 Registrant Contact Information: iesg@ietf.org
2601
2602 Value: obscured
2603 Type: status
2604 Description: Some of the information of the object instance has been
2605 altered for the purposes of not readily revealing the actual
2606 information of the object instance. This is most commonly applied
2607 to entities.
2608 Registrant Name: IESG
2609 Registrant Contact Information: iesg@ietf.org
2610
2611 Value: associated
2612 Type: status
2613 Description: The object instance is associated with other object
2614 instances in the registry. This is most commonly used to signify
2615 that a nameserver is associated with a domain or that an entity is
2616 associated with a network resource or domain.
2617 Registrant Name: IESG
2618 Registrant Contact Information: iesg@ietf.org
2619
2620 Value: active
2621 Type: status
2622 Description: The object instance is in use. For domain names, it
2623 signifies that the domain name is published in DNS. For network
2624 and autnum registrations, it signifies that they are allocated or
2625 assigned for use in operational networks. This maps to the "OK"
2626 status of the Extensible Provisioning Protocol (EPP) [RFC5730].
2627 Registrant Name: IESG
2628 Registrant Contact Information: iesg@ietf.org
2629
2630 Value: inactive
2631 Type: status
2632 Description: The object instance is not in use. See "active".
2633 Registrant Name: IESG
2634 Registrant Contact Information: iesg@ietf.org
2635
2636 Value: locked
2637 Type: status
2638 Description: Changes to the object instance cannot be made,
2639 including the association of other object instances.
2640 Registrant Name: IESG
2641 Registrant Contact Information: iesg@ietf.org
2642
2643 Value: pending create
2644 Type: status
2645 Description: A request has been received for the creation of the
2646 object instance, but this action is not yet complete.
2647 Registrant Name: IESG
2648 Registrant Contact Information: iesg@ietf.org
2649
2650 Value: pending renew
2651 Type: status
2652 Description: A request has been received for the renewal of the
2653 object instance, but this action is not yet complete.
2654 Registrant Name: IESG
2655 Registrant Contact Information: iesg@ietf.org
2656
2657 Value: pending transfer
2658 Type: status
2659 Description: A request has been received for the transfer of the
2660 object instance, but this action is not yet complete.
2661 Registrant Name: IESG
2662 Registrant Contact Information: iesg@ietf.org
2663
2664 Value: pending update
2665 Type: status
2666 Description: A request has been received for the update or
2667 modification of the object instance, but this action is not yet
2668 complete.
2669 Registrant Name: IESG
2670 Registrant Contact Information: iesg@ietf.org
2671
2672 Value: pending delete
2673 Type: status
2674 Description: A request has been received for the deletion or removal
2675 of the object instance, but this action is not yet complete. For
2676 domains, this might mean that the name is no longer published in
2677 DNS but has not yet been purged from the registry database.
2678 Registrant Name: IESG
2679 Registrant Contact Information: iesg@ietf.org
2680
2681 10.2.3. Event Actions
2682
2683 The following values have been registered in the "RDAP JSON Values"
2684 registry:
2685
2686 Value: registration
2687 Type: event action
2688 Description: The object instance was initially registered.
2689 Registrant Name: IESG
2690 Registrant Contact Information: iesg@ietf.org
2691
2692 Value: reregistration
2693 Type: event action
2694 Description: The object instance was registered subsequently to
2695 initial registration.
2696 Registrant Name: IESG
2697 Registrant Contact Information: iesg@ietf.org
2698
2699 Value: last changed
2700 Type: event action
2701 Description: An action noting when the information in the object
2702 instance was last changed.
2703 Registrant Name: IESG
2704 Registrant Contact Information: iesg@ietf.org
2705
2706 Value: expiration
2707 Type: event action
2708 Description: The object instance has been removed or will be removed
2709 at a predetermined date and time from the registry.
2710 Registrant Name: IESG
2711 Registrant Contact Information: iesg@ietf.org
2712
2713 Value: deletion
2714 Type: event action
2715 Description: The object instance was removed from the registry at a
2716 point in time that was not predetermined.
2717 Registrant Name: IESG
2718 Registrant Contact Information: iesg@ietf.org
2719
2720 Value: reinstantiation
2721 Type: event action
2722 Description: The object instance was reregistered after having been
2723 removed from the registry.
2724 Registrant Name: IESG
2725 Registrant Contact Information: iesg@ietf.org
2726
2727 Value: transfer
2728 Type: event action
2729 Description: The object instance was transferred from one registrar
2730 to another.
2731 Registrant Name: IESG
2732 Registrant Contact Information: iesg@ietf.org
2733
2734 Value: locked
2735 Type: event action
2736 Description: The object instance was locked (see the "locked"
2737 status).
2738 Registrant Name: IESG
2739 Registrant Contact Information: iesg@ietf.org
2740
2741 Value: unlocked
2742 Type: event action
2743 Description: The object instance was unlocked (see the "locked"
2744 status).
2745 Registrant Name: IESG
2746 Registrant Contact Information: iesg@ietf.org
2747
2748 10.2.4. Roles
2749
2750 The following values have been registered in the "RDAP JSON Values"
2751 registry:
2752
2753 Value: registrant
2754 Type: role
2755 Description: The entity object instance is the registrant of the
2756 registration. In some registries, this is known as a maintainer.
2757 Registrant Name: IESG
2758 Registrant Contact Information: iesg@ietf.org
2759
2760 Value: technical
2761 Type: role
2762 Description: The entity object instance is a technical contact for
2763 the registration.
2764 Registrant Name: IESG
2765 Registrant Contact Information: iesg@ietf.org
2766
2767 Value: administrative
2768 Type: role
2769 Description: The entity object instance is an administrative contact
2770 for the registration.
2771 Registrant Name: IESG
2772 Registrant Contact Information: iesg@ietf.org
2773
2774 Value: abuse
2775 Type: role
2776 Description: The entity object instance handles network abuse issues
2777 on behalf of the registrant of the registration.
2778 Registrant Name: IESG
2779 Registrant Contact Information: iesg@ietf.org
2780
2781 Value: billing
2782 Type: role
2783 Description: The entity object instance handles payment and billing
2784 issues on behalf of the registrant of the registration.
2785 Registrant Name: IESG
2786 Registrant Contact Information: iesg@ietf.org
2787
2788 Value: registrar
2789 Type: role
2790 Description: The entity object instance represents the authority
2791 responsible for the registration in the registry.
2792 Registrant Name: IESG
2793 Registrant Contact Information: iesg@ietf.org
2794
2795 Value: reseller
2796 Type: role
2797 Description: The entity object instance represents a third party
2798 through which the registration was conducted (i.e., not the
2799 registry or registrar).
2800 Registrant Name: IESG
2801 Registrant Contact Information: iesg@ietf.org
2802
2803 Value: sponsor
2804 Type: role
2805 Description: The entity object instance represents a domain policy
2806 sponsor, such as an ICANN-approved sponsor.
2807 Registrant Name: IESG
2808 Registrant Contact Information: iesg@ietf.org
2809
2810 Value: proxy
2811 Type: role
2812 Description: The entity object instance represents a proxy for
2813 another entity object, such as a registrant.
2814 Registrant Name: IESG
2815 Registrant Contact Information: iesg@ietf.org
2816
2817 Value: notifications
2818 Type: role
2819 Description: An entity object instance designated to receive
2820 notifications about association object instances.
2821 Registrant Name: IESG
2822 Registrant Contact Information: iesg@ietf.org
2823
2824 Value: noc
2825 Type: role
2826 Description: The entity object instance handles communications
2827 related to a network operations center (NOC).
2828 Registrant Name: IESG
2829 Registrant Contact Information: iesg@ietf.org
2830
2831 10.2.5. Variant Relations
2832
2833 The following values have been registered in the "RDAP JSON Values"
2834 registry:
2835
2836 Value: registered
2837 Type: domain variant relation
2838 Description: The variant names are registered in the registry.
2839 Registrant Name: IESG
2840 Registrant Contact Information: iesg@ietf.org
2841
2842 Value: unregistered
2843 Type: domain variant relation
2844 Description: The variant names are not found in the registry.
2845 Registrant Name: IESG
2846 Registrant Contact Information: iesg@ietf.org
2847
2848 Value: registration restricted
2849 Type: domain variant relation
2850 Description: Registration of the variant names is restricted to
2851 certain parties or within certain rules.
2852 Registrant Name: IESG
2853 Registrant Contact Information: iesg@ietf.org
2854
2855 Value: open registration
2856 Type: domain variant relation
2857 Description: Registration of the variant names is available to
2858 generally qualified registrants.
2859 Registrant Name: IESG
2860 Registrant Contact Information: iesg@ietf.org
2861
2862 Value: conjoined
2863 Type: domain variant relation
2864 Description: Registration of the variant names occurs automatically
2865 with the registration of the containing domain registration.
2866 Registrant Name: IESG
2867 Registrant Contact Information: iesg@ietf.org
2868
2869 11. Security Considerations
2870
2871 This specification models information serialized in JSON format. As
2872 JSON is a subset of JavaScript, implementations are advised to follow
2873 the security considerations outlined in Section 12 of [RFC8259] to
2874 prevent code injection.
2875
2876 Though not specific to JSON, RDAP implementers should be aware of the
2877 security considerations specified in [RFC7480] and the security
2878 requirements and considerations in [RFC7481].
2879
2880 RDAP responses allow for retrieval of DNSSEC (key) related
2881 information, but the RRSIG DS from the parent zone is not conveyed
2882 alongside it. This means that the DNSSEC keys retrieved by RDAP are
2883 disconnected from their containing PKI, and as such are not generally
2884 expected to be trusted without additional information. In
2885 particular, the HTTPS channel protecting the RDAP connection is not
2886 expected to be authorized to certify the validity of the DNSSEC keys.
2887
2888 Clients caching data, especially clients using RDAP-specific caches
2889 (instead of HTTP-layer caches), should have safeguards to prevent
2890 cache poisoning. See Section 5 for advice on using the self links
2891 for caching.
2892
2893 Finally, service operators should be aware of the privacy mechanisms
2894 noted in Section 13.
2895
2896 12. Internationalization Considerations
2897
2898 12.1. Character Encoding
2899
2900 The default text encoding for JSON responses in RDAP is UTF-8
2901 [RFC3629], and all servers and clients MUST support UTF-8.
2902
2903 12.2. URIs and IRIs
2904
2905 [RFC7480] defines the use of URIs and IRIs in RDAP.
2906
2907 12.3. Language Tags
2908
2909 Section 4.4 defines the use of language tags in the JSON responses
2910 defined in this document.
2911
2912 12.4. Internationalized Domain Names
2913
2914 IDNs are denoted in this specification by the separation of DNS names
2915 in LDH form and Unicode form (see Section 3). Representation of IDNs
2916 in registries is described by the "variants" object in Section 5.3
2917 and the suggested values listed in Section 10.2.5.
2918
2919 13. Privacy Considerations
2920
2921 This specification suggests status values to denote contact and
2922 registrant information that has been marked as private and/or has
2923 been removed or obscured. See Section 10.2.2 for the complete list
2924 of status values. A few of the status values indicate that there are
2925 privacy concerns associated with the object instance. The following
2926 status codes SHOULD be used to describe data elements of a response
2927 when appropriate:
2928
2929 * private -- The object is not be shared in query responses, unless
2930 the user is authorized to view this information.
2931
2932 * removed -- Data elements within the object have been collected but
2933 have been omitted from the response. This option can be used to
2934 prevent unauthorized access to associated object instances without
2935 the need to mark them as private.
2936
2937 * obscured -- Data elements within the object have been collected,
2938 but the response value has been altered so that values are not
2939 easily discernible. A value changed from "1212" to "XXXX" is an
2940 example of obscured data. This option may reveal privacy
2941 sensitive information and should only be used when data
2942 sensitivity does not require a more protective option like
2943 "private" or "removed".
2944
2945 See Appendix A.1 for an example of applying those values to contacts
2946 and registrants.
2947
2948 14. References
2949
2950 14.1. Normative References
2951
2952 [ISO.3166.2020]
2953 International Organization for Standardization, "Codes for
2954 the representation of names of countries and their
2955 subdivisions", Fourth edition, ISO Standard 3166, August
2956 2020.
2957
2958 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2959 Requirement Levels", BCP 14, RFC 2119,
2960 DOI 10.17487/RFC2119, March 1997,
2961 <https://www.rfc-editor.org/info/rfc2119>.
2962
2963 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
2964 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
2965 <https://www.rfc-editor.org/info/rfc3339>.
2966
2967 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
2968 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2969 2003, <https://www.rfc-editor.org/info/rfc3629>.
2970
2971 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
2972 Resource Identifier (URI): Generic Syntax", STD 66,
2973 RFC 3986, DOI 10.17487/RFC3986, January 2005,
2974 <https://www.rfc-editor.org/info/rfc3986>.
2975
2976 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S.
2977 Rose, "Resource Records for the DNS Security Extensions",
2978 RFC 4034, DOI 10.17487/RFC4034, March 2005,
2979 <https://www.rfc-editor.org/info/rfc4034>.
2980
2981 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of
2982 Autonomous System (AS) Numbers", RFC 5396,
2983 DOI 10.17487/RFC5396, December 2008,
2984 <https://www.rfc-editor.org/info/rfc5396>.
2985
2986 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
2987 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
2988 September 2009, <https://www.rfc-editor.org/info/rfc5646>.
2989
2990 [RFC5890] Klensin, J., "Internationalized Domain Names for
2991 Applications (IDNA): Definitions and Document Framework",
2992 RFC 5890, DOI 10.17487/RFC5890, August 2010,
2993 <https://www.rfc-editor.org/info/rfc5890>.
2994
2995 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
2996 Address Text Representation", RFC 5952,
2997 DOI 10.17487/RFC5952, August 2010,
2998 <https://www.rfc-editor.org/info/rfc5952>.
2999
3000 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095,
3001 DOI 10.17487/RFC7095, January 2014,
3002 <https://www.rfc-editor.org/info/rfc7095>.
3003
3004 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the
3005 Registration Data Access Protocol (RDAP)", STD 95,
3006 RFC 7480, DOI 10.17487/RFC7480, March 2015,
3007 <https://www.rfc-editor.org/info/rfc7480>.
3008
3009 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the
3010 Registration Data Access Protocol (RDAP)", STD 95,
3011 RFC 7481, DOI 10.17487/RFC7481, March 2015,
3012 <https://www.rfc-editor.org/info/rfc7481>.
3013
3014 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
3015 Writing an IANA Considerations Section in RFCs", BCP 26,
3016 RFC 8126, DOI 10.17487/RFC8126, June 2017,
3017 <https://www.rfc-editor.org/info/rfc8126>.
3018
3019 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
3020 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
3021 May 2017, <https://www.rfc-editor.org/info/rfc8174>.
3022
3023 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
3024 Interchange Format", STD 90, RFC 8259,
3025 DOI 10.17487/RFC8259, December 2017,
3026 <https://www.rfc-editor.org/info/rfc8259>.
3027
3028 [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
3029 DOI 10.17487/RFC8288, October 2017,
3030 <https://www.rfc-editor.org/info/rfc8288>.
3031
3032 [RFC9082] Hollenbeck, S. and A. Newton, "Registration Data Access
3033 Protocol (RDAP) Query Format", STD 95, RFC 9082,
3034 DOI 10.17487/RFC9082, June 2021,
3035 <https://www.rfc-editor.org/info/rfc9082>.
3036
3037 14.2. Informative References
3038
3039 [IANA_IDNTABLES]
3040 IANA, "Repository of IDN Practices",
3041 <https://www.iana.org/domains/idn-tables>.
3042
3043 [JSON_ascendancy]
3044 MacVittie, L., "The Stealthy Ascendancy of JSON", April
3045 2011, <https://devcentral.f5.com/s/articles/the-stealthy-
3046 ascendancy-of-json>.
3047
3048 [JSON_performance_study]
3049 Nurseitov, N., Paulson, M., Reynolds, R., and C. Izurieta,
3050 "Comparison of JSON and XML Data Interchange Formats: A
3051 Case Study", 2009,
3052 <https://www.cs.montana.edu/izurieta/pubs/caine2009.pdf>.
3053
3054 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
3055 DOI 10.17487/RFC3912, September 2004,
3056 <https://www.rfc-editor.org/info/rfc3912>.
3057
3058 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
3059 STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009,
3060 <https://www.rfc-editor.org/info/rfc5730>.
3061
3062 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS)
3063 Security Extensions Mapping for the Extensible
3064 Provisioning Protocol (EPP)", RFC 5910,
3065 DOI 10.17487/RFC5910, May 2010,
3066 <https://www.rfc-editor.org/info/rfc5910>.
3067
3068 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
3069 DOI 10.17487/RFC6350, August 2011,
3070 <https://www.rfc-editor.org/info/rfc6350>.
3071
3072 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type
3073 Structured Syntax Suffixes", RFC 6839,
3074 DOI 10.17487/RFC6839, January 2013,
3075 <https://www.rfc-editor.org/info/rfc6839>.
3076
3077 Appendix A. Suggested Data Modeling with the Entity Object Class
3078
3079 A.1. Registrants and Contacts
3080
3081 This document does not provide specific object classes for
3082 registrants and contacts. Instead, the entity object class may be
3083 used to represent a registrant or contact. When the entity object is
3084 embedded inside a containing object such as a domain name or IP
3085 network, the "roles" string array can be used to signify the
3086 relationship. It is recommended that the values from Section 10.2.4
3087 be used.
3088
3089 The following is an example of an elided containing object with an
3090 embedded entity that is both a registrant and administrative contact:
3091
3092 {
3093 ...
3094 "entities" :
3095 [
3096 {
3097 "objectClassName" : "entity",
3098 "handle" : "XXXX",
3099 "vcardArray":[
3100 "vcard",
3101 [
3102 ["version", {}, "text", "4.0"],
3103 ["fn", {}, "text", "Joe User"],
3104 ["kind", {}, "text", "individual"],
3105 ["lang", {
3106 "pref":"1"
3107 }, "language-tag", "fr"],
3108 ["lang", {
3109 "pref":"2"
3110 }, "language-tag", "en"],
3111 ["org", {
3112 "type":"work"
3113 }, "text", "Example"],
3114 ["title", {}, "text", "Research Scientist"],
3115 ["role", {}, "text", "Project Lead"],
3116 ["adr",
3117 { "type":"work" },
3118 "text",
3119 [
3120 "",
3121 "Suite 1234",
3122 "4321 Rue Somewhere",
3123 "Quebec",
3124 "QC",
3125 "G1V 2M2",
3126 "Canada"
3127 ]
3128 ],
3129 ["tel",
3130 { "type":["work", "voice"], "pref":"1" },
3131 "uri", "tel:+1-555-555-1234;ext=102"
3132 ],
3133 ["email",
3134 { "type":"work" },
3135 "text", "joe.user@example.com"
3136 ]
3137 ]
3138 ],
3139 "roles" : [ "registrant", "administrative" ],
3140 "remarks" :
3141 [
3142 {
3143 "description" :
3144 [
3145 "She sells sea shells down by the sea shore.",
3146 "Originally written by Terry Sullivan."
3147 ]
3148 }
3149 ],
3150 "events" :
3151 [
3152 {
3153 "eventAction" : "registration",
3154 "eventDate" : "1990-12-31T23:59:59Z"
3155 },
3156 {
3157 "eventAction" : "last changed",
3158 "eventDate" : "1991-12-31T23:59:59Z"
3159 }
3160 ]
3161 }
3162 ]
3163 }
3164
3165 Figure 34
3166
3167 In many use cases, it is necessary to hide or obscure the information
3168 of a registrant or contact due to policy or other operational
3169 matters. Registries can denote these situations with "status" values
3170 (see Section 10.2.2).
3171
3172 The following is an elided example of a registrant with information
3173 changed to reflect that of a third party.
3174
3175 {
3176 ...
3177 "entities" :
3178 [
3179 {
3180 "objectClassName" : "entity",
3181 "handle" : "XXXX",
3182 ...
3183 "roles" : [ "registrant", "administrative" ],
3184 "status" : [ "proxy", "private", "obscured" ]
3185 }
3186 ]
3187 }
3188
3189 Figure 35
3190
3191 A.2. Registrars
3192
3193 This document does not provide a specific object class for
3194 registrars, but like registrants and contacts (see Appendix A.1), the
3195 "roles" string array maybe used. Additionally, many registrars have
3196 publicly assigned identifiers. The publicIds structure (Section 4.8)
3197 represents that information.
3198
3199 The following is an example of an elided containing object with an
3200 embedded entity that is a registrar:
3201
3202 {
3203 ...
3204 "entities":[
3205 {
3206 "objectClassName" : "entity",
3207 "handle":"XXXX",
3208 "vcardArray":[
3209 "vcard",
3210 [
3211 ["version", {}, "text", "4.0"],
3212 ["fn", {}, "text", "Joe's Fish, Chips, and Domains"],
3213 ["kind", {}, "text", "org"],
3214 ["lang", {
3215 "pref":"1"
3216 }, "language-tag", "fr"],
3217 ["lang", {
3218 "pref":"2"
3219 }, "language-tag", "en"],
3220 ["org", {
3221 "type":"work"
3222 }, "text", "Example"],
3223 ["adr",
3224 { "type":"work" },
3225 "text",
3226 [
3227 "",
3228 "Suite 1234",
3229 "4321 Rue Somewhere",
3230 "Quebec",
3231 "QC",
3232 "G1V 2M2",
3233 "Canada"
3234 ]
3235 ],
3236 ["tel",
3237 {
3238 "type":["work", "voice"],
3239 "pref":"1"
3240 },
3241 "uri", "tel:+1-555-555-1234;ext=102"
3242 ],
3243 ["email",
3244 { "type":"work" },
3245 "text", "joes_fish_chips_and_domains@example.com"
3246 ]
3247 ]
3248 ],
3249 "roles":[ "registrar" ],
3250 "publicIds":[
3251 {
3252 "type":"IANA Registrar ID",
3253 "identifier":"1"
3254 }
3255 ],
3256 "remarks":[
3257 {
3258 "description":[
3259 "She sells sea shells down by the sea shore.",
3260 "Originally written by Terry Sullivan."
3261 ]
3262 }
3263 ],
3264 "links":[
3265 {
3266 "value":"https://example.net/entity/XXXX",
3267 "rel":"alternate",
3268 "type":"text/html",
3269 "href":"https://www.example.com"
3270 }
3271 ]
3272 }
3273 ]
3274 }
3275
3276 Figure 36
3277
3278 Appendix B. Modeling Events
3279
3280 Events represent actions that have taken place against a registered
3281 object at a certain date and time. Events have three properties: the
3282 action, the actor, and the date and time of the event (which is
3283 sometimes in the future). In some cases, the identity of the actor
3284 is not captured.
3285
3286 Events can be modeled in three ways:
3287
3288 1. events with no designated actor
3289
3290 2. events where the actor is only designated by an identifier
3291
3292 3. events where the actor can be modeled as an entity
3293
3294 For the first use case, the events data structure (Section 4.5) is
3295 used without the "eventActor" object member.
3296
3297 This is an example of an "events" array without the "eventActor".
3298
3299 "events" :
3300 [
3301 {
3302 "eventAction" : "registration",
3303 "eventDate" : "1990-12-31T23:59:59Z"
3304 }
3305 ]
3306
3307 Figure 37
3308
3309 For the second use case, the events data structure (Section 4.5) is
3310 used with the "eventActor" object member.
3311
3312 This is an example of an "events" array with the "eventActor".
3313
3314 "events" :
3315 [
3316 {
3317 "eventAction" : "registration",
3318 "eventActor" : "XYZ-NIC",
3319 "eventDate" : "1990-12-31T23:59:59Z"
3320 }
3321 ]
3322
3323 Figure 38
3324
3325 For the third use case, the "asEventActor" array is used when an
3326 entity (Section 5.1) is embedded into another object class. The
3327 "asEventActor" array follows the same structure as the "events" array
3328 but does not have "eventActor" attributes.
3329
3330 The following is an elided example of a domain object with an entity
3331 as an event actor.
3332
3333 {
3334 "objectClassName" : "domain",
3335 "handle" : "XXXX",
3336 "ldhName" : "foo.example",
3337 "status" : [ "locked", "transfer prohibited" ],
3338 ...
3339 "entities" :
3340 [
3341 {
3342 "handle" : "XXXX",
3343 ...
3344 "asEventActor" :
3345 [
3346 {
3347 "eventAction" : "last changed",
3348 "eventDate" : "1990-12-31T23:59:59Z"
3349 }
3350 ]
3351 }
3352 ]
3353 }
3354
3355 Figure 39
3356
3357 Appendix C. Structured vs. Unstructured Addresses
3358
3359 The entity (Section 5.1) object class uses jCard [RFC7095] to
3360 represent contact information, including postal addresses. jCard has
3361 the ability to represent multiple language preferences, multiple
3362 email address and phone numbers, and multiple postal addresses in
3363 both a structured and unstructured format. This section describes
3364 the use of jCard for representing structured and unstructured
3365 addresses.
3366
3367 The following is an example of a jCard.
3368
3369 {
3370 "vcardArray":[
3371 "vcard",
3372 [
3373 ["version", {}, "text", "4.0"],
3374 ["fn", {}, "text", "Joe User"],
3375 ["n", {}, "text",
3376 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]]
3377 ],
3378 ["kind", {}, "text", "individual"],
3379 ["lang", {
3380 "pref":"1"
3381 }, "language-tag", "fr"],
3382 ["lang", {
3383 "pref":"2"
3384 }, "language-tag", "en"],
3385 ["org", {
3386 "type":"work"
3387 }, "text", "Example"],
3388 ["title", {}, "text", "Research Scientist"],
3389 ["role", {}, "text", "Project Lead"],
3390 ["adr",
3391 { "type":"work" },
3392 "text",
3393 [
3394 "",
3395 "Suite 1234",
3396 "4321 Rue Somewhere",
3397 "Quebec",
3398 "QC",
3399 "G1V 2M2",
3400 "Canada"
3401 ]
3402 ],
3403 ["adr",
3404 {
3405
3406 "type":"home",
3407 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n"
3408 },
3409 "text",
3410 [
3411 "", "", "", "", "", "", ""
3412 ]
3413 ],
3414 ["tel",
3415 { "type":["work", "voice"], "pref":"1" },
3416 "uri", "tel:+1-555-555-1234;ext=102"
3417 ],
3418 ["tel",
3419 {
3420 "type":["work", "cell", "voice", "video", "text"]
3421 },
3422 "uri",
3423 "tel:+1-555-555-1234"
3424 ],
3425 ["email",
3426 { "type":"work" },
3427 "text", "joe.user@example.com"
3428 ],
3429 ["geo", {
3430 "type":"work"
3431 }, "uri", "geo:46.772673,-71.282945"],
3432 ["key",
3433 { "type":"work" },
3434 "uri", "https://www.example.com/joe.user/joe.asc"
3435 ],
3436 ["tz", {},
3437 "utc-offset", "-05:00"],
3438 ["url", { "type":"home" },
3439 "uri", "https://example.org"]
3440 ]
3441 ]
3442 }
3443
3444 Figure 40
3445
3446 The arrays in Figure 40 with the first member of "adr" represent
3447 postal addresses. In the first example, the postal address is given
3448 as an array of strings and constitutes a structured address. For
3449 components of the structured address that are not applicable, an
3450 empty string is given. Each member of that array aligns with the
3451 positions of a vCard as given in [RFC6350]. In this example, the
3452 following data corresponds to the following positional meanings:
3453
3454 1. post office box -- not applicable; empty string
3455
3456 2. extended address (e.g., apartment or suite number) -- Suite 1234
3457
3458 3. street address -- 4321 Rue Somewhere
3459
3460 4. locality (e.g., city) -- Quebec
3461
3462 5. region (e.g., state or province) -- QC
3463
3464 6. postal code -- G1V 2M2
3465
3466 7. country name (full name) -- Canada
3467
3468 The second example is an unstructured address. It uses the "label"
3469 attribute, which is a string containing a newline (\n) character to
3470 separate address components in an unordered, unspecified manner.
3471 Note that in this example, the structured address array is still
3472 given but that each string is an empty string.
3473
3474 Appendix D. Secure DNS
3475
3476 Section 5.3 defines the "secureDNS" member to represent secure DNS
3477 information about domain names.
3478
3479 DNSSEC provides data integrity for DNS through the digital signing of
3480 resource records. To enable DNSSEC, the zone is signed by one or
3481 more private keys and the signatures are stored as RRSIG records. To
3482 complete the chain of trust in the DNS zone hierarchy, a digest of
3483 each DNSKEY record (which contains the public key) must be loaded
3484 into the parent zone, stored as DS records, and signed by the
3485 parent's private key (RRSIG DS record), as indicated in "Resource
3486 Records for the DNS Security Extensions" [RFC4034]. Creating the DS
3487 records in the parent zone can be done by the registration authority
3488 "Domain Name System (DNS) Security Extensions Mapping for the
3489 Extensible Provisioning Protocol (EPP)" [RFC5910].
3490
3491 Only DS-related information is provided by RDAP, since other
3492 information is not generally stored in the registration database.
3493 Other DNSSEC-related information can be retrieved with other DNS
3494 tools such as dig.
3495
3496 The domain object class (Section 5.3) can represent this information
3497 using either the "dsData" or "keyData" object arrays. Client
3498 implementers should be aware that some registries do not collect or
3499 do not publish all of the secure DNS meta-information.
3500
3501 Appendix E. Motivations for Using JSON
3502
3503 This section addresses a common question regarding the use of JSON
3504 over other data formats, most notably XML.
3505
3506 It is often pointed out that many DNRs and one RIR support the EPP
3507 [RFC5730] standard, which is an XML serialized protocol. The logic
3508 is that since EPP is a common protocol in the industry, it follows
3509 that XML would be a more natural choice. While EPP does influence
3510 this specification quite a bit, EPP serves a different purpose, which
3511 is the provisioning of Internet resources between registries and
3512 accredited registrars and serving a much narrower audience than that
3513 envisioned for RDAP.
3514
3515 By contrast, RDAP has a broader audience and is designed for public
3516 consumption of data. Experience from RIRs with first generation
3517 RESTful web services for WHOIS indicate that a large percentage of
3518 clients operate within browsers and other platforms where full-blown
3519 XML stacks are not readily available and where JSON is a better fit.
3520
3521 Additionally, while EPP is used in much of the DNR community it is
3522 not a universal constant in that industry. And finally, EPP's use of
3523 XML predates the specification of JSON. If EPP had been defined
3524 today, it may very well have used JSON instead of XML.
3525
3526 Beyond the specific DNR and RIR communities, the trend in the broader
3527 Internet industry is also switching to JSON over XML, especially in
3528 the area of RESTful web services (see [JSON_ascendancy]). Studies
3529 have also found that JSON is generally less bulky and consequently
3530 faster to parse (see [JSON_performance_study]).
3531
The following is an elided example of an entity truncated 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" : "https://example.net/help",
"rel" : "alternate",
"type" : "text/html",
"href" : "https://www.example.com/data_policy.html"
}
]
}
]
}
The following is an elided example of an entity truncated data.
{
"rdapConformance" :
[
"rdap_level_0"
],
"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" : "https://example.net/help",
"rel" : "alternate",
"type" : "text/html",
"href" : "https://www.example.com/data_policy.html"
}
]
}
]
}
RFC 9083 4.1 states that the rdapConformance data structure MUST appear in the topmost JSON object of RDAP responses. The example error response provided in Figure 33 should include the rdapConformance property but does not.
3532 Appendix F. Changes from RFC 7483
3533
3534 * Addressed known errata.
3535
3536 * Updated references to 7482 to RFC 9082. Adjusted case of "xxxx"
3537 used in examples where "XXXX" was previously used, and removed an
3538 "X" from "XXXXX". Changed IPv6 address example using "C00" to
3539 "c00". Added "a string representing" to the definitions of
3540 startAddress and endAddress. Removed "entity" from "Autonomous
3541 System Number Entity Object Class". Added "an unsigned 32-bit
3542 integer" to the definition of startAutnum and endAutnum. Added "a
3543 string representing" to the definition of name in the IP network
3544 and ASN object classes. Clarified rdapConformance identifier
3545 registration expectations in Section 4.1. Changed
3546 "lunarNic_level_0" to "lunarNIC_level_0".
3547
3548 * Clarified that the "value", "rel" and "href" JSON values MUST be
3549 specified in the "links" array.
3550
3551 * Clarified that the "description" array is required in the Notices
3552 and Remarks data structures and other values are OPTIONAL.
3553
3554 * Noted that all members of the "events" and "Public IDs" arrays are
3555 REQUIRED.
3556
3557 * Fix "self" link values in examples. Changed "http" to "https"
3558 link values in examples. Noted that Figure 18 is an example of a
3559 nameserver object with all "appropriate" values given. In
3560 Appendix C, quoted the word "label" in "label attribute". Added
3561 reference to "status" definition in the descriptions for IP
3562 networks and autnums. Fixed a 404 for the informative reference
3563 to "The Stealthy Ascendancy of JSON". Added "boolean" to the
3564 definition of zoneSigned.
3565
3566 * Clarified REQUIRED and OPTIONAL members of the "events" array.
3567
3568 * Changed "SHOULD not" to "SHOULD NOT" in Section 5.
3569
3570 * Updated normative references (RFC 5226 to RFC 8126, RFC 5988 to
3571 RFC 8288, RFC 7159 to RFC 8259). Changed examples using "ns1.xn--
3572 fo-5ja.example" to split URLs to avoid long lines.
3573
3574 * Added acknowledgments.
3575
3576 * Changed "The "lang" attribute may appear anywhere in an object
3577 class or data structure except for in jCard objects" to "The
3578 "lang" attribute as defined in this section MAY appear anywhere in
3579 an object class or data structure, except for in jCard objects.
3580 jCard supports similar functionality by way of the LANGUAGE
3581 property parameter (see Section 5.1 of RFC 6350 [RFC6350]".
3582
3583 * Changed "simple data types conveyed in JSON strings" to "simple
3584 data types conveyed in JSON primitive types (strings, numbers,
3585 booleans, and null)". Changed "In other words, servers are free
3586 to not include JSON members containing registration data based on
3587 their own policies" to "In other words, servers are free to omit
3588 unrequired/optional JSON members containing registration data
3589 based on their own policies".
3590
3591 * Changed "This data structure appears only in the topmost JSON
3592 object of a response" to "This data structure MUST appear in the
3593 topmost JSON object of a response".
3594
3595 * Changed "Some non-answer responses may return entity bodies with
3596 information that could be more descriptive" to "Some non-answer
3597 responses MAY return entity bodies with information that could be
3598 more descriptive".
3599
3600 * Changed "The basic structure of that response is an object class
3601 containing an error code number (corresponding to the HTTP
3602 response code) followed by a string named "title" and an array of
3603 strings named "description"" to "The basic structure of that
3604 response is an object class containing a REQUIRED error code
3605 number (corresponding to the HTTP response code) followed by an
3606 OPTIONAL string named "title" and an OPTIONAL array of strings
3607 named "description"".
3608
3609 * Changed the "Autonomous System Number Object Class" section title
3610 to "The Autonomous System Number Object Class" for consistency
3611 with other section titles. Removed trailing periods in the
3612 "Terminology and Definitions" section for consistency. Changed
3613 instances of "lunarNic" to "lunarNIC" for consistency. Removed an
3614 extraneous trailing period after the eventDate description.
3615 Changed a "." to ";" in the description of the "network" member of
3616 the domain object class. Changed "The high-level structure of the
3617 autnum object class consists of information about the network
3618 registration" to "The high-level structure of the autnum object
3619 class consists of information about the Autonomous System number
3620 registration". Changed "registry unique" to "registry-unique".
3621
3622 * Changed "registrant" to "registrar" in the description of the
3623 "transfer" event action to address erratum 6158. Added IANA
3624 instructions to correct the description of the value in the
3625 registry.
3626
3627 * Added text to Section 4.2 to note that "self" and "related" "href"
3628 URIs MUST NOT be the same.
3629
3630 * Added text to Section 4.2 to describe return of IDNs in LDH name
3631 format.
3632
3633 * Added text to note that the "fn" member of a contact object MAY be
3634 empty in Section 3.
3635
3636 * Added text to clarify rdapConformance requirements in Section 4.1.
3637
3638 * Added "obsoletes 7483" to the headers, Abstract, and Introduction.
3639 Updated BCP 14 boilerplate. Updated IANA Considerations to note
3640 that this RFC (a product of the REGEXT Working Group) replaces RFC
3641 7483. Changed "simple string" to "simple character string" in
3642 Sections 3 and 4.7. Clarified requirement for the "fn" member in
3643 Section 3. Modified the requirement for rdapConformance placement
3644 in Section 4.1. Changed "jCard" to "vCard" LANGUAGE property
3645 reference in Section 4.4. Changed "no use" to "little or no use"
3646 in Section 5.1. Added example line wrap note in Section 5.2.
3647 Modified the definition of "idnTable" in Section 5.3. Modified
3648 the dsData and keyData examples in Section 5.3. Changed
3649 "2001:c00::/23" to "2001:db8::/32" in Section 5.4. Expanded the
3650 definition of "type" in Sections 5.4 and 5.5. Modified example
3651 autnums in Section 5.5. Added text to the Security Considerations
3652 section to note that DNSSEC information returned in a response
3653 cannot be trusted directly.
3654
3655 Acknowledgments
3656
3657 This document is derived from original work on RIR responses in JSON
3658 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew L.
3659 Newton. Additionally, this document incorporates work on DNR
3660 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean
3661 Shen.
3662
3663 The components of the DNR object classes are derived from a
3664 categorization of WHOIS response formats created by Ning Kong, Linlin
3665 Zhou, Guangqing Deng, Steve Sheng, Francisco Arias, Ray Bellis, and
3666 Frederico Neves.
3667
3668 Tom Harrison, Murray Kucherawy, Ed Lewis, Audric Schiltknecht, Naoki
3669 Kambe, Maarten Bosteels, Mario Loffredo, and Jasdip Singh contributed
3670 significant review comments and provided clarifying text. James
3671 Mitchell provided text regarding the processing of unknown JSON
3672 attributes and identified issues leading to the remodeling of events.
3673 Ernie Dainow and Francisco Obispo provided concrete suggestions that
3674 led to a better variant model for domain names.
3675
3676 Ernie Dainow provided the background information on the secure DNS
3677 attributes and objects for domains, informative text on DNSSEC, and
3678 many other attributes that appear throughout the object classes of
3679 this document.
3680
3681 The switch to and incorporation of jCard was performed by Simon
3682 Perreault.
3683
3684 Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS Working
3685 Group from which this document was originally created. James Galvin
3686 and Antoin Verschuren chaired the REGEXT Working Group that worked on
3687 this document.
3688
3689 Authors' Addresses
3690
3691 Scott Hollenbeck
3692 Verisign Labs
3693 12061 Bluemont Way
3694 Reston, VA 20190
3695 United States of America
3696
3697 Email: shollenbeck@verisign.com
3698 URI: https://www.verisignlabs.com/
3699
3700
3701 Andy Newton
3702 Amazon Web Services, Inc.
3703 13200 Woodland Park Road
3704 Herndon, VA 20171
3705 United States of America
3706
3707 Email: andy@hxr.us
3708
* Noted that all members of the "events" and "Public IDs" arrays are
REQUIRED.
* Noted which members of the "events" and "Public IDs" arrays are
REQUIRED.
According to the "events" array, not all members are REQUIRED.