idnits 2.17.1 draft-ietf-regext-rfc7483bis-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 5 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: 01: Updated references to 7482 to 7482bis Internet-Draft. Updated "Change Log" to "Changes from RFC 7483". Added APNIC implementation status. Adjusted case of "xxxx" used in examples where "XXXX" was previously used, and removed an "X" from "XXXXX". Changed IPv6 address example using "C00" to "c00". Added "a string representing" to the definitions of startAddress and endAddress. Removed "entity" from "Autonomous System Number Entity Object Class". Added "an unsigned 32-bit integer" to the definition of startAutnum and endAutnum. Added "a string representing" to the definition of name in the IP network and ASN object classes. Clarified rdapConformance identifier registration expectations in Section 4.1. Changed "lunarNic_level_0" to "lunarNIC_level_0". Clarified that the "value", "rel" and "href" JSON values MUST be specified in the "links" array. Clarified that the "description" array is required in the Notices and Remarks data structures and other values are OPTIONAL. Noted that all members of the "events" and "Public IDs" arrays are REQUIRED. Fix "self" link values in examples. Changed "http" to "https" link values in examples. Noted that Figure 18 is an example of a nameserver object with all "appropriate" values given. In appendix C, quoted the word "label" in "label attribute". Added reference to "status" definition in the descriptions for IP networks and autnums. Fixed a 404 for the informative reference to "The Stealthy Ascendancy of JSON". Added "boolean" to the definition of zoneSigned. Clarified REQUIRED and OPTIONAL members of the "events" array. Changed "SHOULD not" to "SHOULD NOT" in Section 5. Updated normative references (5226-8126, 5988-8288, 7159-8259). Changed examples using "ns1.xn--fo-5ja.example" to split URLs to avoid long lines. -- The document date (12 October 2020) is 1285 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-03) exists of draft-ietf-regext-rfc7482bis-02 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-regext-rfc7482bis' Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 REGEXT Working Group S. Hollenbeck 3 Internet-Draft Verisign Labs 4 Intended status: Standards Track A. Newton 5 Expires: 15 April 2021 AWS 6 12 October 2020 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-regext-rfc7483bis-03 11 Abstract 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. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 15 April 2021. 36 Copyright Notice 38 Copyright (c) 2020 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Terminology and Definitions . . . . . . . . . . . . . . . 3 54 1.2. Data Model . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2.1. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 3. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 7 58 4. Common Data Structures . . . . . . . . . . . . . . . . . . . 8 59 4.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 8 60 4.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 9 61 4.3. Notices and Remarks . . . . . . . . . . . . . . . . . . . 10 62 4.4. Language Identifier . . . . . . . . . . . . . . . . . . . 12 63 4.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 12 64 4.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 4.7. Port 43 WHOIS Server . . . . . . . . . . . . . . . . . . 14 66 4.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 14 67 4.9. Object Class Name . . . . . . . . . . . . . . . . . . . . 14 68 4.10. An Example . . . . . . . . . . . . . . . . . . . . . . . 14 69 5. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 16 70 5.1. The Entity Object Class . . . . . . . . . . . . . . . . . 17 71 5.2. The Nameserver Object Class . . . . . . . . . . . . . . . 23 72 5.3. The Domain Object Class . . . . . . . . . . . . . . . . . 26 73 5.4. The IP Network Object Class . . . . . . . . . . . . . . . 38 74 5.5. The Autonomous System Number Object Class . . . . . . . . 43 75 6. Error Response Body . . . . . . . . . . . . . . . . . . . . . 46 76 7. Responding to Help Queries . . . . . . . . . . . . . . . . . 48 77 8. Responding To Searches . . . . . . . . . . . . . . . . . . . 48 78 9. Indicating Truncated Responses . . . . . . . . . . . . . . . 49 79 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 80 10.1. RDAP JSON Media Type Registration . . . . . . . . . . . 52 81 10.2. JSON Values Registry . . . . . . . . . . . . . . . . . . 53 82 10.2.1. Notice and Remark Types . . . . . . . . . . . . . . 54 83 10.2.2. Status . . . . . . . . . . . . . . . . . . . . . . . 56 84 10.2.3. Event Actions . . . . . . . . . . . . . . . . . . . 60 85 10.2.4. Roles . . . . . . . . . . . . . . . . . . . . . . . 62 86 10.2.5. Variant Relations . . . . . . . . . . . . . . . . . 65 87 11. Implementation Status . . . . . . . . . . . . . . . . . . . . 66 88 11.1. RedDog . . . . . . . . . . . . . . . . . . . . . . . . . 67 89 11.2. Verisign . . . . . . . . . . . . . . . . . . . . . . . . 67 90 11.3. Verisign Labs . . . . . . . . . . . . . . . . . . . . . 68 91 11.4. Asia-Pacific Network Information Centre (APNIC) . . . . 68 92 12. Security Considerations . . . . . . . . . . . . . . . . . . . 68 93 13. Internationalization Considerations . . . . . . . . . . . . . 69 94 13.1. Character Encoding . . . . . . . . . . . . . . . . . . . 69 95 13.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 69 96 13.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 69 97 13.4. Internationalized Domain Names . . . . . . . . . . . . . 69 99 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 69 100 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 70 101 15.1. Normative References . . . . . . . . . . . . . . . . . . 70 102 15.2. Informative References . . . . . . . . . . . . . . . . . 72 103 Appendix A. Suggested Data Modeling with the Entity Object 104 Class . . . . . . . . . . . . . . . . . . . . . . . . . . 73 105 A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 73 106 A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 75 107 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 77 108 Appendix C. Structured vs. Unstructured Addresses . . . . . . . 79 109 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 81 110 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 82 111 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 82 112 Changes from RFC 7483 . . . . . . . . . . . . . . . . . . . . . . 83 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 85 115 1. Introduction 117 This document describes responses in the JSON [RFC8259] format for 118 the queries as defined by the Registration Data Access Protocol Query 119 Format [I-D.ietf-regext-rfc7482bis]. A communication protocol for 120 exchanging queries and responses is described in [RFC7480]. 122 1.1. Terminology and Definitions 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in [RFC2119] when 127 specified in their uppercase forms. 129 The following list describes terminology and definitions used 130 throughout this document: 132 DNR: Domain Name Registry or Domain Name Registrar 134 LDH: letters, digits, hyphen 136 member: data found within an object as defined by JSON [RFC8259] 138 object: a data structure as defined by JSON [RFC8259] 140 object class: the definition of members that may be found in JSON 141 objects described in this document 143 object instance: an instantiation or specific instance of an object 144 class 146 RDAP: Registration Data Access Protocol 148 RIR: Regional Internet Registry 150 1.2. Data Model 152 The data model for JSON responses is specified in five sections: 154 1. simple data types conveyed in JSON primitive types (strings, 155 numbers, booleans, and null) 157 2. data structures specified as JSON arrays or objects that are used 158 repeatedly when building up larger objects 160 3. object classes representing structured data corresponding to a 161 lookup of a single object 163 4. arrays of objects representing structured data corresponding to a 164 search for multiple objects 166 5. the response to an error 168 The object classes represent responses for two major categories of 169 data: responses returned by RIRs for registration data related to IP 170 addresses, reverse DNS names, and Autonomous System numbers and 171 responses returned by DNRs for registration data related to forward 172 DNS names. The following object classes are returned by both RIRs 173 and DNRs: 175 1. domains 177 2. nameservers 179 3. entities 181 The information served by both RIRs and DNRs for these object classes 182 overlap extensively and are given in this document as a unified model 183 for both classes of service. 185 In addition to the object classes listed above, RIRs also serve the 186 following object classes: 188 1. IP networks 189 2. Autonomous System numbers 191 Object classes defined in this document represent a minimal set of 192 what a compliant client/server needs to understand to function 193 correctly; however, some deployments may want to include additional 194 object classes to suit individual needs. Anticipating this need for 195 extension, Section 2.1 of this document defines a mechanism for 196 extending the JSON objects that are described in this document. 198 Positive responses take two forms. A response to a lookup of a 199 single object in the registration system yields a JSON object, which 200 is the subject of the lookup. A response to a search for multiple 201 objects yields a JSON object that contains an array of JSON objects 202 that are the subject of the search. In each type of response, other 203 data structures are present within the topmost JSON object. 205 2. Use of JSON 207 2.1. Naming 209 Clients of these JSON responses SHOULD ignore unrecognized JSON 210 members in responses. Servers can insert members into the JSON 211 responses, which are not specified in this document, but that does 212 not constitute an error in the response. Servers that insert such 213 unspecified members into JSON responses SHOULD have member names 214 prefixed with a short identifier followed by an underscore followed 215 by a meaningful name. It has been observed that these short 216 identifiers aid software implementers with identifying the 217 specification of the JSON member, and failure to use one could cause 218 an implementer to assume the server is erroneously using a name from 219 this specification. This allowance does not apply to jCard [RFC7095] 220 objects. The full JSON name (the prefix plus the underscore plus the 221 meaningful name) SHOULD adhere to the character and name limitations 222 of the prefix registry described in [RFC7480]. Failure to use these 223 limitations could result in slower adoption as these limitations have 224 been observed to aid some client programming models. 226 Consider the following JSON response with JSON members, all of which 227 are specified in this document. 229 { 230 "handle" : "ABC123", 231 "remarks" : 232 [ 233 { 234 "description" : 235 [ 236 "She sells sea shells down by the sea shore.", 237 "Originally written by Terry Sullivan." 238 ] 239 } 240 ] 241 } 243 Figure 1 245 If The Registry of the Moon desires to express information not found 246 in this specification, it might select "lunarNIC" as its identifying 247 prefix and insert, as an example, the member named 248 "lunarNIC_beforeOneSmallStep" to signify registrations occurring 249 before the first moon landing and the member named 250 "lunarNIC_harshMistressNotes" that contains other descriptive text. 252 Consider the following JSON response with JSON names, some of which 253 should be ignored by clients without knowledge of their meaning. 255 { 256 "handle" : "ABC123", 257 "lunarNIC_beforeOneSmallStep" : "TRUE THAT!", 258 "remarks" : 259 [ 260 { 261 "description" : 262 [ 263 "She sells sea shells down by the sea shore.", 264 "Originally written by Terry Sullivan." 265 ] 266 } 267 ], 268 "lunarNIC_harshMistressNotes" : 269 [ 270 "In space,", 271 "nobody can hear you scream." 272 ] 273 } 275 Figure 2 277 Insertion of unrecognized members ignored by clients may also be used 278 for future revisions to this specification. 280 Clients processing JSON responses need to be prepared for members 281 representing registration data specified in this document to be 282 absent from a response. In other words, servers are free to omit 283 unrequired/optional JSON members containing registration data based 284 on their own policies. 286 Finally, all JSON names specified in this document are case 287 sensitive. Both servers and clients MUST transmit and process them 288 using the specified character case. 290 3. Common Data Types 292 JSON [RFC8259] defines the data types of a number, character string, 293 boolean, array, object, and null. This section describes the 294 semantics and/or syntax reference for common, JSON character strings 295 used in this document. 297 handle: DNRs and RIRs have registry-unique identifiers that 298 may be used to specifically reference an object 299 instance. The semantics of this data type as found 300 in this document are to be a registry-unique 301 reference to the closest enclosing object where the 302 value is found. The data type names "registryId", 303 "roid", "nic-handle", "registrationNo", etc., are 304 terms often synonymous with this data type. In 305 this document, the term "handle" is used. The term 306 exposed to users by clients is a presentation issue 307 beyond the scope of this document. This value is a 308 simple string. 310 IPv4 addresses: The representation of IPv4 addresses in this 311 document uses the dotted-decimal notation. An 312 example of this textual representation is 313 "192.0.2.0". 315 IPv6 addresses: The representation of IPv6 addresses in this 316 document follow the forms outlined in [RFC5952]. 317 An example of this textual representation is 318 "2001:db8::1:0:0:1". 320 country codes: Where the identity of a geopolitical nation or 321 country is needed, these identities are represented 322 with the alpha-2 or two-character country code 323 designation as defined in [ISO.3166.1988]. The 324 alpha-2 representation is used because it is freely 325 available, whereas the alpha-3 and numeric-3 326 standards are not. 328 LDH names: Textual representations of DNS names where the 329 labels of the domain are all "letters, digits, 330 hyphen" labels as described by [RFC5890]. Trailing 331 periods are optional. 333 Unicode names: Textual representations of DNS names where one or 334 more of the labels are U-labels as described by 335 [RFC5890]. Trailing periods are optional. 337 dates and times: The syntax for values denoting dates and times is 338 defined in [RFC3339]. 340 URIs: The syntax for values denoting a Uniform Resource 341 Identifier (URI) is defined by [RFC3986]. 343 Contact information is defined using jCards as described in 344 [RFC7095]. The "fn" member is required and MUST NOT be null 345 according to [RFC6350], where an empty "fn" member MAY be used when 346 the contact name does not exist or is redacted. 348 4. Common Data Structures 350 This section defines common data structures used in responses and 351 object classes. 353 4.1. RDAP Conformance 355 The data structure named "rdapConformance" is an array of strings, 356 each providing a hint as to the specifications used in the 357 construction of the response. This data structure MUST appear in the 358 topmost JSON object of a response. 360 An example rdapConformance data structure: 362 "rdapConformance" : 363 [ 364 "rdap_level_0" 365 ] 367 Figure 3 369 The string literal "rdap_level_0" signifies conformance with this 370 specification. When custom JSON values are inserted into responses, 371 conformance to those custom specifications MUST be indicated by 372 including a unique string literal value registered in the IANA RDAP 373 Extensions registry specified in [RFC7480]. For example, if the 374 fictional Registry of the Moon wants to signify that their JSON 375 responses are conformant with their registered extensions, the string 376 used might be "lunarNIC_level_0". These registered values aid the 377 identification of specifications for software implementers, and 378 failure to use them could result in slower adoption of extensions. 380 Example rdapConformance structure with custom extensions noted: 382 "rdapConformance" : 383 [ 384 "rdap_level_0", 385 "lunarNIC_level_0" 386 ] 388 Figure 4 390 4.2. Links 392 The "links" array is found in data structures to signify links to 393 other resources on the Internet. The relationship of these links is 394 defined by the IANA registry described by [RFC8288]. 396 The following is an example of the link structure: 398 { 399 "value" : "https://example.com/context_uri", 400 "rel" : "self", 401 "href" : "https://example.com/target_uri", 402 "hreflang" : [ "en", "ch" ], 403 "title" : "title", 404 "media" : "screen", 405 "type" : "application/json" 406 } 408 Figure 5 410 The JSON name/values of "rel", "href", "hreflang", "title", "media", 411 and "type" correspond to values found in Section 3 of [RFC8288]. The 412 "value" JSON value is the context URI as described by [RFC8288]. The 413 "value", "rel" and "href" JSON values MUST be specified. All other 414 JSON values are OPTIONAL. A "related" link relation MUST NOT include 415 an "href" URI that is the same as the "self" link relation "href" URI 416 to reduce the risk of infinite client processing loops. 418 Internationalized Domain Names (IDNs) returned in URIs SHOULD be 419 consistently returned in LDH name format to allow clients to process 420 these IDNs according to their capabilities. 422 This is an example of the "links" array as it might be found in an 423 object class: 425 "links" : 426 [ 427 { 428 "value" : "https://example.com/ip/2001:db8::123", 429 "rel" : "self", 430 "href" : "https://example.com/ip/2001:db8::123", 431 "type" : "application/rdap+json" 432 }, 433 { 434 "value" : "https://example.com/ip/2001:db8::123", 435 "rel" : "up", 436 "href" : "https://example.com/ip/2001:db8::/48", 437 "type" : "application/rdap+json" 438 } 440 ] 442 Figure 6 444 4.3. Notices and Remarks 446 The "notices" and "remarks" data structures take the same form. The 447 notices structure denotes information about the service providing 448 RDAP information and/or information about the entire response, 449 whereas the remarks structure denotes information about the object 450 class that contains it (see Section 5 regarding object classes). 452 Both are arrays of objects. Each object contains a "title" string 453 representing the title of the object, a "type" string denoting a 454 registered type of remark or notice (see Section 10.2.1), an array of 455 strings named "description" for the purposes of conveying any 456 descriptive text, and a "links" array as described in Section 4.2. 457 The "description" array MUST be included. All other JSON values are 458 OPTIONAL. 460 An example of the notices data structure: 462 "notices" : 463 [ 464 { 465 "title" : "Terms of Use", 466 "description" : 467 [ 468 "Service subject to The Registry of the Moon's TOS.", 469 "Copyright (c) 2020 LunarNIC" 470 ], 471 "links" : 472 [ 473 { 474 "value" : "https://example.net/entity/XXXX", 475 "rel" : "alternate", 476 "type" : "text/html", 477 "href" : "https://www.example.com/terms_of_use.html" 478 } 479 ] 480 } 481 ] 483 Figure 7 485 It is the job of the clients to determine line breaks, spacing, and 486 display issues for sentences within the character strings of the 487 "description" array. Each string in the "description" array contains 488 a single complete division of human-readable text indicating to 489 clients where there are semantic breaks. 491 An example of the remarks data structure: 493 "remarks" : 494 [ 495 { 496 "description" : 497 [ 498 "She sells sea shells down by the sea shore.", 499 "Originally written by Terry Sullivan." 500 ] 501 } 502 ] 504 Figure 8 506 Note that objects in the "remarks" array may also have a "links" 507 array. 509 While the "title" and "description" fields are intended primarily for 510 human consumption, the "type" string contains a well-known value to 511 be registered with IANA (see Section 10.2.1) for programmatic use. 513 An example of the remarks data structure: 515 "remarks" : 516 [ 517 { 518 "type" : "object truncated due to authorization", 519 "description" : 520 [ 521 "Some registration data may not have been given.", 522 "Use proper authorization credentials to see all of it." 523 ] 524 } 525 ] 527 Figure 9 529 While the "remarks" array will appear in many object classes in a 530 response, the "notices" array appears only in the topmost object of a 531 response. 533 4.4. Language Identifier 535 This data structure consists solely of a name/value pair, where the 536 name is "lang" and the value is a string containing a language 537 identifier as described in [RFC5646]. 539 "lang" : "mn-Cyrl-MN" 541 Figure 10 543 The "lang" attribute as defined in this section MAY appear anywhere 544 in an object class or data structure, except for in jCard objects. 545 jCard supports similar functionality by way of the LANGUAGE property 546 parameter (see Section 5.1 of RFC 6350 [RFC6350]). 548 4.5. Events 550 This data structure represents events that have occurred on an 551 instance of an object class (see Section 5 regarding object classes). 553 This is an example of an "events" array. 555 "events" : 556 [ 557 { 558 "eventAction" : "registration", 559 "eventActor" : "SOMEID-LUNARNIC", 560 "eventDate" : "1990-12-31T23:59:59Z" 561 }, 562 { 563 "eventAction" : "last changed", 564 "eventActor" : "OTHERID-LUNARNIC", 565 "eventDate" : "1991-12-31T23:59:59Z" 566 } 567 ] 569 Figure 11 571 The "events" array consists of objects, each with the following 572 members: 574 * "eventAction" -- a REQUIRED string denoting the reason for the 575 event 577 * "eventActor" -- an OPTIONAL identifier denoting the actor 578 responsible for the event 580 * "eventDate" -- a REQUIRED string containing the time and date the 581 event occurred 583 * "links" -- OPTIONAL; see Section 4.2 585 Events can be future dated. One use case for future dating of events 586 is to denote when an object expires from a registry. 588 The "links" array in this data structure is provided for references 589 to the event actor. In order to reference an RDAP entity, a "rel" of 590 "related" and a "type" of "application/rdap+json" is used in the link 591 reference. 593 See Section 10.2.3 for a list of values for the "eventAction" string. 594 See Appendix B regarding the various ways events can be modeled. 596 4.6. Status 598 This data structure, named "status", is an array of strings 599 indicating the state of a registered object (see Section 10.2.2 for a 600 list of values). 602 4.7. Port 43 WHOIS Server 604 This data structure, a member named "port43", is a simple string 605 containing the fully qualified host name or IP address of the WHOIS 606 [RFC3912] server where the containing object instance may be found. 607 Note that this is not a URI, as there is no WHOIS URI scheme. 609 4.8. Public IDs 611 This data structure maps a public identifier to an object class. It 612 is named "publicIds" and is an array of objects, with each object 613 containing the following REQUIRED members: 615 * type -- a string denoting the type of public identifier 617 * identifier -- a string denoting a public identifier of the type 618 related to "type" 620 The following is an example of a publicIds structure. 622 "publicIds": 623 [ 624 { 625 "type":"IANA Registrar ID", 626 "identifier":"1" 627 } 628 ] 630 Figure 12 632 4.9. Object Class Name 634 This data structure, a member named "objectClassName", gives the 635 object class name of a particular object as a string. This 636 identifies the type of object being processed. An objectClassName is 637 REQUIRED in all RDAP response objects so that the type of the object 638 can be interpreted. 640 4.10. An Example 642 This is an example response with both rdapConformance and notices 643 embedded: 645 { 646 "rdapConformance" : 647 [ 648 "rdap_level_0" 649 ], 650 "notices" : 651 [ 652 { 653 "title" : "Content Removed", 654 "description" : 655 [ 656 "Without full authorization, content has been removed.", 657 "Sorry, dude!" 658 ], 659 "links" : 660 [ 661 { 662 "value" : "https://example.net/ip/192.0.2.0/24", 663 "rel" : "alternate", 664 "type" : "text/html", 665 "href" : "https://www.example.com/redaction_policy.html" 666 } 667 ] 668 } 669 ], 670 "lang" : "en", 671 "objectClassName" : "ip network", 672 "startAddress" : "192.0.2.0", 673 "endAddress" : "192.0.2.255", 674 "handle" : "XXXX-RIR", 675 "ipVersion" : "v4", 676 "name": "NET-RTR-1", 677 "parentHandle" : "YYYY-RIR", 678 "remarks" : 679 [ 681 { 682 "description" : 683 [ 684 "She sells sea shells down by the sea shore.", 685 "Originally written by Terry Sullivan." 686 ] 687 } 688 ] 689 } 691 Figure 13 693 5. Object Classes 695 Object classes represent structures appropriate for a response from 696 the queries specified in [I-D.ietf-regext-rfc7482bis]. 698 Each object class contains a "links" array as specified in 699 Section 4.2. For every object class instance in a response, whether 700 the object class instance is directly representing the response to a 701 query or is embedded in other object class instances or is an item in 702 a search result set, servers SHOULD provide a link representing a URI 703 for that object class instance using the "self" relationship as 704 described in the IANA registry specified by [RFC8288]. As explained 705 in Section 5.2, this may be not always be possible for nameserver 706 data. Clients MUST be able to process object instances without a 707 self link. When present, clients can use the self link for caching 708 data. Servers MAY provide more than one self link for any given 709 object instance. Failure to provide any self link by a server may 710 result in clients being unable to cache object class instances. 712 Clients using self links for caching SHOULD NOT cache any object 713 class instances where the authority of the self link is different 714 than the authority of the server returning the data. Failing to do 715 so might result in cache poisoning. 717 Self links MUST contain a "type" element containing the "application/ 718 rdap+json" media type when referencing RDAP object instances as 719 defined by this document. 721 This is an example of the "links" array with a self link to an object 722 class: 724 "links" : 725 [ 726 { 727 "value" : "https://example.com/ip/2001:db8::123", 728 "rel" : "self", 729 "href" : "https://example.com/ip/2001:db8::123", 730 "type" : "application/rdap+json" 731 } 732 ] 734 Figure 14 736 5.1. The Entity Object Class 738 The entity object class appears throughout this document and is an 739 appropriate response for the /entity/XXXX query defined in 740 "Registration Data Access Protocol (RDAP) Query Format" 741 [I-D.ietf-regext-rfc7482bis]. This object class represents the 742 information of organizations, corporations, governments, non-profits, 743 clubs, individual persons, and informal groups of people. All of 744 these representations are so similar that it is best to represent 745 them in JSON [RFC8259] with one construct, the entity object class, 746 to aid in the reuse of code by implementers. 748 The entity object class uses jCard [RFC7095] to represent contact 749 information, such as postal addresses, email addresses, phone numbers 750 and names of organizations and individuals. Many of the types of 751 information that can be represented with jCard have no use in RDAP, 752 such as birthdays, anniversaries, and gender. 754 The entity object is served by both RIRs and DNRs. The following is 755 an example of an entity that might be served by an RIR. 757 { 758 "objectClassName" : "entity", 759 "handle":"XXXX", 760 "vcardArray":[ 761 "vcard", 762 [ 763 ["version", {}, "text", "4.0"], 764 ["fn", {}, "text", "Joe User"], 765 ["n", {}, "text", 766 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 767 ], 768 ["kind", {}, "text", "individual"], 769 ["lang", { 770 "pref":"1" 771 }, "language-tag", "fr"], 772 ["lang", { 773 "pref":"2" 774 }, "language-tag", "en"], 775 ["org", { 776 "type":"work" 777 }, "text", "Example"], 778 ["title", {}, "text", "Research Scientist"], 779 ["role", {}, "text", "Project Lead"], 780 ["adr", 781 { "type":"work" }, 782 "text", 783 [ 784 "", 785 "Suite 1234", 786 "4321 Rue Somewhere", 787 "Quebec", 788 "QC", 789 "G1V 2M2", 790 "Canada" 791 ] 792 ], 793 ["adr", 794 { 795 "type":"home", 796 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 797 }, 798 "text", 799 [ 800 "", "", "", "", "", "", "" 801 ] 802 ], 803 ["tel", 804 { 805 "type":["work", "voice"], 806 "pref":"1" 807 }, 808 "uri", 809 "tel:+1-555-555-1234;ext=102" 810 ], 811 ["tel", 812 { "type":["work", "cell", "voice", "video", "text"] }, 813 "uri", 814 "tel:+1-555-555-4321" 815 ], 816 ["email", 817 { "type":"work" }, 818 "text", 819 "joe.user@example.com" 820 ], 821 ["geo", { 822 "type":"work" 823 }, "uri", "geo:46.772673,-71.282945"], 824 ["key", 825 { "type":"work" }, 826 "uri", 827 "https://www.example.com/joe.user/joe.asc" 828 ], 829 ["tz", {}, 830 "utc-offset", "-05:00"], 831 ["url", { "type":"home" }, 832 "uri", "https://example.org"] 833 ] 834 ], 835 "roles":[ "registrar" ], 836 "publicIds":[ 837 { 838 "type":"IANA Registrar ID", 839 "identifier":"1" 840 } 841 ], 842 "remarks":[ 843 { 844 "description":[ 845 "She sells sea shells down by the sea shore.", 846 "Originally written by Terry Sullivan." 847 ] 848 } 849 ], 850 "links":[ 851 { 852 "value":"https://example.com/entity/XXXX", 853 "rel":"self", 854 "href":"https://example.com/entity/XXXX", 855 "type" : "application/rdap+json" 856 } 857 ], 858 "events":[ 859 { 860 "eventAction":"registration", 861 "eventDate":"1990-12-31T23:59:59Z" 862 } 863 ], 864 "asEventActor":[ 866 { 867 "eventAction":"last changed", 868 "eventDate":"1991-12-31T23:59:59Z" 869 } 870 ] 871 } 873 Figure 15 875 The entity object class can contain the following members: 877 * objectClassName -- the string "entity" 878 * handle -- a string representing a registry-unique identifier of 879 the entity 881 * vcardArray -- a jCard with the entity's contact information 883 * roles -- an array of strings, each signifying the relationship an 884 object would have with its closest containing object (see 885 Section 10.2.4 for a list of values) 887 * publicIds -- see Section 4.8 889 * entities -- an array of entity objects as defined by this section 891 * remarks -- see Section 4.3 893 * links -- see Section 4.2 895 * events -- see Section 4.5 897 * asEventActor -- this data structure takes the same form as the 898 events data structure (see Section 4.5), but each object in the 899 array MUST NOT have an "eventActor" member. These objects denote 900 that the entity is an event actor for the given events. See 901 Appendix B regarding the various ways events can be modeled. 903 * status -- see Section 4.6 905 * port43 -- see Section 4.7 907 * networks -- an array of IP network objects as defined in 908 Section 5.4 910 * autnums -- an array of autnum objects as defined in Section 5.5 912 Entities may also have other entities embedded with them in an array. 913 This can be used to model an organization with specific individuals 914 fulfilling designated roles of responsibility. 916 The following is an elided example of an entity with embedded 917 entities. 919 { 920 "objectClassName" : "entity", 921 "handle" : "ANENTITY", 922 "roles" : [ "registrar" ], 923 ... 924 "entities" : 925 [ 926 { 927 "objectClassName" : "entity", 928 "handle": "ANEMBEDDEDENTITY", 929 "roles" : [ "technical" ], 930 ... 931 }, 932 ... 933 ], 934 ... 935 } 937 Figure 16 939 The following is an example of an entity that might be served by a 940 DNR. 942 { 943 "objectClassName" : "entity", 944 "handle":"XXXX", 945 "vcardArray":[ 946 "vcard", 947 [ 948 ["version", {}, "text", "4.0"], 949 ["fn", {}, "text", "Joe User"], 950 ["kind", {}, "text", "individual"], 951 ["lang", { 952 "pref":"1" 953 }, "language-tag", "fr"], 954 ["lang", { 955 "pref":"2" 956 }, "language-tag", "en"], 957 ["org", { 958 "type":"work" 959 }, "text", "Example"], 960 ["title", {}, "text", "Research Scientist"], 961 ["role", {}, "text", "Project Lead"], 962 ["adr", 963 { "type":"work" }, 964 "text", 965 [ 966 "", 967 "Suite 1234", 968 "4321 Rue Somewhere", 969 "Quebec", 970 "QC", 971 "G1V 2M2", 972 "Canada" 973 ] 974 ], 975 ["tel", 976 { "type":["work", "voice"], "pref":"1" }, 977 "uri", "tel:+1-555-555-1234;ext=102" 978 ], 979 ["email", 980 { "type":"work" }, 981 "text", "joe.user@example.com" 982 ] 983 ] 984 ], 985 "status":[ "validated", "locked" ], 986 "remarks":[ 987 { 988 "description":[ 989 "She sells sea shells down by the sea shore.", 990 "Originally written by Terry Sullivan." 991 ] 992 } 993 ], 994 "links":[ 995 { 996 "value":"https://example.com/entity/XXXX", 997 "rel":"self", 998 "href":"https://example.com/entity/XXXX", 999 "type":"application/rdap+json" 1000 } 1001 ], 1002 "port43":"whois.example.net", 1003 "events":[ 1004 { 1005 "eventAction":"registration", 1006 "eventDate":"1990-12-31T23:59:59Z" 1007 }, 1008 { 1009 "eventAction":"last changed", 1010 "eventDate":"1991-12-31T23:59:59Z", 1011 "eventActor":"joe@example.com" 1012 } 1013 ] 1014 } 1015 Figure 17 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. 1021 5.2. The Nameserver Object Class 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". 1028 The nameserver object class accommodates both models and degrees of 1029 variation in between. 1031 The following is an example of a nameserver object. 1033 { 1034 "objectClassName" : "nameserver", 1035 "handle" : "XXXX", 1036 "ldhName" : "ns1.xn--fo-5ja.example", 1037 "unicodeName" : "ns.fóo.example", 1038 "status" : [ "active" ], 1039 "ipAddresses" : 1040 { 1041 "v4": [ "192.0.2.1", "192.0.2.2" ], 1042 "v6": [ "2001:db8::123" ] 1043 }, 1044 "remarks" : 1045 [ 1046 { 1047 "description" : 1048 [ 1049 "She sells sea shells down by the sea shore.", 1050 "Originally written by Terry Sullivan." 1051 ] 1052 } 1053 ], 1054 "links" : 1055 [ 1056 { 1057 "value" : "https://example.net/nameserver/ 1058 ns1.xn--fo-5ja.example", 1059 "rel" : "self", 1060 "href" : "https://example.net/nameserver/ 1061 ns1.xn--fo-5ja.example", 1062 "type" : "application/rdap+json" 1063 } 1064 ], 1065 "port43" : "whois.example.net", 1066 "events" : 1067 [ 1068 { 1069 "eventAction" : "registration", 1070 "eventDate" : "1990-12-31T23:59:59Z" 1071 }, 1072 { 1073 "eventAction" : "last changed", 1074 "eventDate" : "1991-12-31T23:59:59Z", 1075 "eventActor" : "joe@example.com" 1076 } 1077 ] 1078 } 1080 Figure 18 1082 Figure 18 is an example of a nameserver object with all appropriate 1083 values given. Registries using a first-class nameserver data model 1084 would embed this in domain objects as well as allowing references to 1085 it with the "/nameserver" query type (all depending on the registry 1086 operators policy). Other registries may pare back the information as 1087 needed. Figure 19 is an example of a nameserver object as would be 1088 found in RIRs and some DNRs, while Figure 20 is an example of a 1089 nameserver object as would be found in other DNRs. 1091 The following is an example of the simplest nameserver object: 1093 { 1094 "objectClassName" : "nameserver", 1095 "ldhName" : "ns1.example.com" 1096 } 1098 Figure 19 1100 The following is an example of a simple nameserver object that might 1101 be commonly used by DNRs: 1103 { 1104 "objectClassName" : "nameserver", 1105 "ldhName" : "ns1.example.com", 1106 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 1107 } 1109 Figure 20 1111 As nameservers can be modeled by some registries to be first-class 1112 objects, they may also have an array of entities (Section 5.1) 1113 embedded to signify parties responsible for the maintenance, 1114 registrations, etc., of the nameservers. 1116 The following is an elided example of a nameserver with embedded 1117 entities. 1119 { 1120 "objectClassName" : "nameserver", 1121 "handle" : "XXXX", 1122 "ldhName" : "ns.xn--fo-5ja.example", 1123 ... 1124 "entities" : 1125 [ 1126 ... 1127 ], 1128 ... 1129 } 1130 Figure 21 1132 The nameserver object class can contain the following members: 1134 * objectClassName -- the string "nameserver" 1136 * handle -- a string representing a registry-unique identifier of 1137 the nameserver 1139 * ldhName -- a string containing the LDH name of the nameserver (see 1140 Section 3) 1142 * unicodeName -- a string containing a DNS Unicode name of the 1143 nameserver (see Section 3) 1145 * ipAddresses -- an object containing the following members: 1147 - v6 -- an array of strings containing IPv6 addresses of the 1148 nameserver 1150 - v4 -- an array of strings containing IPv4 addresses of the 1151 nameserver 1153 * entities -- an array of entity objects as defined by Section 5.1 1155 * status -- see Section 4.6 1157 * remarks -- see Section 4.3 1159 * links -- see Section 4.2 1161 * port43 -- see Section 4.7 1163 * events -- see Section 4.5 1165 5.3. The Domain Object Class 1167 The domain object class represents a DNS name and point of 1168 delegation. For RIRs, these delegation points are in the reverse DNS 1169 tree, whereas for DNRs, these delegation points are in the forward 1170 DNS tree. 1172 In both cases, the high-level structure of the domain object class 1173 consists of information about the domain registration, nameserver 1174 information related to the domain name, and entities related to the 1175 domain name (e.g., registrant information, contacts, etc.). 1177 The following is an elided example of the domain object showing the 1178 high-level structure: 1180 { 1181 "objectClassName" : "domain", 1182 "handle" : "XXX", 1183 "ldhName" : "blah.example.com", 1184 ... 1185 "nameservers" : 1186 [ 1187 ... 1188 ], 1189 ... 1190 "entities" : 1191 [ 1192 ... 1193 ] 1194 } 1196 Figure 22 1198 The domain object class can contain the following members: 1200 * objectClassName -- the string "domain" 1202 * handle -- a string representing a registry-unique identifier of 1203 the domain object instance 1205 * ldhName -- a string describing a domain name in LDH form as 1206 described in Section 3 1208 * unicodeName -- a string containing a domain name with U-labels as 1209 described in Section 3 1211 * variants -- an array of objects, each containing the following 1212 values: 1214 - relation -- an array of strings, with each string denoting the 1215 relationship between the variants and the containing domain 1216 object (see Section 10.2.5 for a list of suggested variant 1217 relations). 1219 - idnTable -- the name of the Internationalized Domain Name (IDN) 1220 table of codepoints, such as one listed with the IANA (see IDN 1221 tables [IANA_IDNTABLES]). 1223 - variantNames -- an array of objects, with each object 1224 containing an "ldhName" member and a "unicodeName" member (see 1225 Section 3). 1227 * nameservers -- an array of nameserver objects as defined by 1228 Section 5.2 1230 * secureDNS -- an object with the following members: 1232 - zoneSigned -- boolean true if the zone has been signed, false 1233 otherwise. 1235 - delegationSigned -- boolean true if there are DS records in the 1236 parent, false otherwise. 1238 - maxSigLife -- an integer representing the signature lifetime in 1239 seconds to be used when creating the RRSIG DS record in the 1240 parent zone [RFC5910]. 1242 - dsData -- an array of objects, each with the following members: 1244 o keyTag -- an integer as specified by the key tag field of a 1245 DNS DS record as specified by [RFC4034] in presentation 1246 format 1248 o algorithm -- an integer as specified by the algorithm field 1249 of a DNS DS record as described by RFC 4034 in presentation 1250 format 1252 o digest -- a string as specified by the digest field of a DNS 1253 DS record as specified by RFC 4034 in presentation format 1255 o digestType -- an integer as specified by the digest type 1256 field of a DNS DS record as specified by RFC 4034 in 1257 presentation format 1259 o events -- see Section 4.5 1261 o links -- see Section 4.2 1263 - keyData -- an array of objects, each with the following 1264 members: 1266 o flags -- an integer representing the flags field value in 1267 the DNSKEY record [RFC4034] in presentation format 1269 o protocol -- an integer representation of the protocol field 1270 value of the DNSKEY record [RFC4034] in presentation format 1272 o publicKey -- a string representation of the public key in 1273 the DNSKEY record [RFC4034] in presentation format 1275 o algorithm -- an integer as specified by the algorithm field 1276 of a DNSKEY record as specified by [RFC4034] in presentation 1277 format 1279 o events -- see Section 4.5 1281 o links -- see Section 4.2 1283 See Appendix D for background information on these 1284 objects. 1286 * entities -- an array of entity objects as defined by Section 5.1 1288 * status -- see Section 4.6 1290 * publicIds -- see Section 4.8 1292 * remarks -- see Section 4.3 1294 * links -- see Section 4.2 1296 * port43 -- see Section 4.7 1298 * events -- see Section 4.5 1300 * network -- represents the IP network for which a reverse DNS 1301 domain is referenced; see Section 5.4 1303 The following is an example of a JSON domain object representing a 1304 reverse DNS delegation point that might be served by an RIR. 1306 { 1307 "objectClassName" : "domain", 1308 "handle" : "XXXX", 1309 "ldhName" : "0.2.192.in-addr.arpa", 1310 "nameservers" : 1311 [ 1312 { 1313 "objectClassName" : "nameserver", 1314 "ldhName" : "ns1.rir.example" 1315 }, 1316 { 1317 "objectClassName" : "nameserver", 1318 "ldhName" : "ns2.rir.example" 1319 } 1321 ], 1322 "secureDNS": 1323 { 1324 "delegationSigned": true, 1325 "dsData": 1326 [ 1327 { 1328 "keyTag": 12345, 1329 "algorithm": 3, 1330 "digestType": 1, 1331 "digest": "49FD46E6C4B45C55D4AC" 1332 } 1333 ] 1334 }, 1335 "remarks" : 1336 [ 1337 { 1338 "description" : 1339 [ 1340 "She sells sea shells down by the sea shore.", 1341 "Originally written by Terry Sullivan." 1342 ] 1343 } 1344 ], 1345 "links" : 1346 [ 1347 { 1348 "value": "https://example.net/domain/0.2.192.in-addr.arpa", 1349 "rel" : "self", 1350 "href" : "https://example.net/domain/0.2.192.in-addr.arpa", 1351 "type" : "application/rdap+json" 1353 } 1354 ], 1355 "events" : 1356 [ 1357 { 1358 "eventAction" : "registration", 1359 "eventDate" : "1990-12-31T23:59:59Z" 1360 }, 1361 { 1362 "eventAction" : "last changed", 1363 "eventDate" : "1991-12-31T23:59:59Z", 1364 "eventActor" : "joe@example.com" 1365 } 1366 ], 1367 "entities" : 1368 [ 1369 { 1370 "objectClassName" : "entity", 1371 "handle" : "XXXX", 1372 "vcardArray":[ 1373 "vcard", 1374 [ 1375 ["version", {}, "text", "4.0"], 1376 ["fn", {}, "text", "Joe User"], 1377 ["kind", {}, "text", "individual"], 1378 ["lang", { 1379 "pref":"1" 1380 }, "language-tag", "fr"], 1381 ["lang", { 1382 "pref":"2" 1383 }, "language-tag", "en"], 1384 ["org", { 1385 "type":"work" 1386 }, "text", "Example"], 1387 ["title", {}, "text", "Research Scientist"], 1388 ["role", {}, "text", "Project Lead"], 1389 ["adr", 1390 { "type":"work" }, 1391 "text", 1392 [ 1393 "", 1394 "Suite 1234", 1395 "4321 Rue Somewhere", 1396 "Quebec", 1397 "QC", 1398 "G1V 2M2", 1399 "Canada" 1400 ] 1402 ], 1403 ["tel", 1404 { "type":["work", "voice"], "pref":"1" }, 1405 "uri", "tel:+1-555-555-1234;ext=102" 1406 ], 1407 ["email", 1408 { "type":"work" }, 1409 "text", "joe.user@example.com" 1410 ] 1411 ] 1412 ], 1413 "roles" : [ "registrant" ], 1414 "remarks" : 1415 [ 1416 { 1417 "description" : 1418 [ 1419 "She sells sea shells down by the sea shore.", 1420 "Originally written by Terry Sullivan." 1421 ] 1422 } 1423 ], 1424 "links" : 1425 [ 1426 { 1427 "value": "https://example.net/entity/XXXX", 1428 "rel" : "self", 1429 "href" : "https://example.net/entity/XXXX", 1430 "type" : "application/rdap+json" 1431 } 1432 ], 1433 "events" : 1434 [ 1435 { 1436 "eventAction" : "registration", 1437 "eventDate" : "1990-12-31T23:59:59Z" 1438 }, 1439 { 1440 "eventAction" : "last changed", 1441 "eventDate" : "1991-12-31T23:59:59Z", 1442 "eventActor" : "joe@example.com" 1443 } 1444 ] 1445 } 1446 ], 1447 "network" : 1448 { 1449 "objectClassName" : "ip network", 1450 "handle" : "XXXX-RIR", 1451 "startAddress" : "192.0.2.0", 1452 "endAddress" : "192.0.2.255", 1453 "ipVersion" : "v4", 1454 "name": "NET-RTR-1", 1455 "type" : "DIRECT ALLOCATION", 1456 "country" : "AU", 1457 "parentHandle" : "YYYY-RIR", 1458 "status" : [ "active" ] 1459 } 1460 } 1462 Figure 23 1464 The following is an example of a JSON domain object representing a 1465 forward DNS delegation point that might be served by a DNR. 1467 { 1468 "objectClassName" : "domain", 1469 "handle" : "XXXX", 1470 "ldhName" : "xn--fo-5ja.example", 1471 "unicodeName" : "fóo.example", 1472 "variants" : 1473 [ 1474 { 1475 "relation" : [ "registered", "conjoined" ], 1476 "variantNames" : 1477 [ 1478 { 1479 "ldhName" : "xn--fo-cka.example", 1480 "unicodeName" : "fõo.example" 1481 }, 1482 { 1483 "ldhName" : "xn--fo-fka.example", 1484 "unicodeName" : "föo.example" 1485 } 1486 ] 1487 }, 1488 { 1489 "relation" : [ "unregistered", "registration restricted" ], 1490 "idnTable": ".EXAMPLE Swedish", 1491 "variantNames" : 1492 [ 1493 { 1494 "ldhName": "xn--fo-8ja.example", 1495 "unicodeName" : "fôo.example" 1496 } 1497 ] 1499 } 1500 ], 1501 "status" : [ "locked", "transfer prohibited" ], 1502 "publicIds":[ 1503 { 1504 "type":"ENS_Auth ID", 1505 "identifier":"1234567890" 1506 } 1507 ], 1508 "nameservers" : 1509 [ 1510 { 1511 "objectClassName" : "nameserver", 1512 "handle" : "XXXX", 1513 "ldhName" : "ns1.example.com", 1514 "status" : [ "active" ], 1515 "ipAddresses" : 1516 { 1517 "v6": [ "2001:db8::123", "2001:db8::124" ], 1518 "v4": [ "192.0.2.1", "192.0.2.2" ] 1519 }, 1520 "remarks" : 1521 [ 1522 { 1523 "description" : 1524 [ 1525 "She sells sea shells down by the sea shore.", 1526 "Originally written by Terry Sullivan." 1527 ] 1528 } 1529 ], 1530 "links" : 1531 [ 1532 { 1533 "value" : "https://example.net/nameserver/ns1.example.com", 1534 "rel" : "self", 1535 "href" : "https://example.net/nameserver/ns1.example.com", 1536 "type" : "application/rdap+json" 1537 } 1538 ], 1539 "events" : 1540 [ 1541 { 1542 "eventAction" : "registration", 1543 "eventDate" : "1990-12-31T23:59:59Z" 1544 }, 1545 { 1546 "eventAction" : "last changed", 1547 "eventDate" : "1991-12-31T23:59:59Z" 1548 } 1549 ] 1550 }, 1551 { 1552 "objectClassName" : "nameserver", 1553 "handle" : "XXXX", 1554 "ldhName" : "ns2.example.com", 1555 "status" : [ "active" ], 1556 "ipAddresses" : 1557 { 1558 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1559 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1561 }, 1562 "remarks" : 1563 [ 1564 { 1565 "description" : 1566 [ 1567 "She sells sea shells down by the sea shore.", 1568 "Originally written by Terry Sullivan." 1569 ] 1570 } 1571 ], 1572 "links" : 1573 [ 1574 { 1575 "value" : "https://example.net/nameserver/ns2.example.com", 1576 "rel" : "self", 1577 "href" : "https://example.net/nameserver/ns2.example.com", 1578 "type" : "application/rdap+json" 1579 } 1580 ], 1581 "events" : 1582 [ 1583 { 1584 "eventAction" : "registration", 1585 "eventDate" : "1990-12-31T23:59:59Z" 1586 }, 1587 { 1588 "eventAction" : "last changed", 1589 "eventDate" : "1991-12-31T23:59:59Z" 1590 } 1591 ] 1592 } 1593 ], 1594 "secureDNS": 1595 { 1597 "zoneSigned": true, 1598 "delegationSigned": true, 1599 "maxSigLife": 604800, 1600 "keyData": 1601 [ 1602 { 1603 "flags": 257, 1604 "protocol": 3, 1605 "algorithm": 1, 1606 "publicKey": "AQPJ////4Q==", 1607 "events": 1608 [ 1609 { 1610 "eventAction": "last changed", 1611 "eventDate": "2012-07-23T05:15:47Z" 1612 } 1613 ] 1614 } 1615 ] 1616 }, 1617 "remarks" : 1618 [ 1619 { 1620 "description" : 1621 [ 1622 "She sells sea shells down by the sea shore.", 1623 "Originally written by Terry Sullivan." 1624 ] 1625 } 1626 ], 1627 "links" : 1628 [ 1629 { 1630 "value": "https://example.net/domain/xn--fo-5ja.example", 1631 "rel" : "self", 1632 "href" : "https://example.net/domain/xn--fo-5ja.example", 1633 "type" : "application/rdap+json" 1634 } 1635 ], 1636 "port43" : "whois.example.net", 1637 "events" : 1638 [ 1639 { 1640 "eventAction" : "registration", 1641 "eventDate" : "1990-12-31T23:59:59Z" 1642 }, 1643 { 1644 "eventAction" : "last changed", 1645 "eventDate" : "1991-12-31T23:59:59Z", 1646 "eventActor" : "joe@example.com" 1647 }, 1648 { 1649 "eventAction" : "transfer", 1650 "eventDate" : "1991-12-31T23:59:59Z", 1651 "eventActor" : "joe@example.com" 1652 }, 1653 { 1654 "eventAction" : "expiration", 1655 "eventDate" : "2016-12-31T23:59:59Z", 1656 "eventActor" : "joe@example.com" 1658 } 1659 ], 1660 "entities" : 1661 [ 1662 { 1663 "objectClassName" : "entity", 1664 "handle" : "XXXX", 1665 "vcardArray":[ 1666 "vcard", 1667 [ 1668 ["version", {}, "text", "4.0"], 1669 ["fn", {}, "text", "Joe User"], 1670 ["kind", {}, "text", "individual"], 1671 ["lang", { 1672 "pref":"1" 1673 }, "language-tag", "fr"], 1674 ["lang", { 1675 "pref":"2" 1676 }, "language-tag", "en"], 1677 ["org", { 1678 "type":"work" 1679 }, "text", "Example"], 1680 ["title", {}, "text", "Research Scientist"], 1681 ["role", {}, "text", "Project Lead"], 1682 ["adr", 1683 { "type":"work" }, 1684 "text", 1685 [ 1686 "", 1687 "Suite 1234", 1688 "4321 Rue Somewhere", 1689 "Quebec", 1690 "QC", 1691 "G1V 2M2", 1692 "Canada" 1693 ] 1695 ], 1696 ["tel", 1697 { "type":["work", "voice"], "pref":"1" }, 1698 "uri", "tel:+1-555-555-1234;ext=102" 1699 ], 1700 ["email", 1701 { "type":"work" }, 1702 "text", "joe.user@example.com" 1703 ] 1704 ] 1705 ], 1706 "status" : [ "validated", "locked" ], 1707 "roles" : [ "registrant" ], 1708 "remarks" : 1709 [ 1710 { 1711 "description" : 1712 [ 1713 "She sells sea shells down by the sea shore.", 1714 "Originally written by Terry Sullivan." 1715 ] 1716 } 1717 ], 1718 "links" : 1719 [ 1720 { 1721 "value" : "https://example.net/entity/XXXX", 1722 "rel" : "self", 1723 "href" : "https://example.net/entity/XXXX", 1724 "type" : "application/rdap+json" 1725 } 1726 ], 1727 "events" : 1728 [ 1729 { 1730 "eventAction" : "registration", 1731 "eventDate" : "1990-12-31T23:59:59Z" 1732 }, 1733 { 1734 "eventAction" : "last changed", 1735 "eventDate" : "1991-12-31T23:59:59Z" 1736 } 1737 ] 1738 } 1739 ] 1740 } 1742 Figure 24 1744 5.4. The IP Network Object Class 1746 The IP network object class models IP network registrations found in 1747 RIRs and is the expected response for the "/ip" query as defined by 1748 [I-D.ietf-regext-rfc7482bis]. There is no equivalent object class 1749 for DNRs. The high- level structure of the IP network object class 1750 consists of information about the network registration and entities 1751 related to the IP network (e.g., registrant information, contacts, 1752 etc.). 1754 The following is an elided example of the IP network object type 1755 showing the high-level structure: 1757 { 1758 "objectClassName" : "ip network", 1759 "handle" : "XXX", 1760 ... 1761 "entities" : 1762 [ 1763 ... 1764 ] 1765 } 1767 Figure 25 1769 The following is an example of the JSON object for the network 1770 registration information. 1772 { 1773 "objectClassName" : "ip network", 1774 "handle" : "XXXX-RIR", 1775 "startAddress" : "2001:db8::", 1776 "endAddress" : "2001:db8:0:ffff:ffff:ffff:ffff:ffff", 1777 "ipVersion" : "v6", 1778 "name": "NET-RTR-1", 1779 "type" : "DIRECT ALLOCATION", 1780 "country" : "AU", 1781 "parentHandle" : "YYYY-RIR", 1782 "status" : [ "active" ], 1783 "remarks" : 1784 [ 1785 { 1786 "description" : 1787 [ 1788 "She sells sea shells down by the sea shore.", 1789 "Originally written by Terry Sullivan." 1790 ] 1791 } 1792 ], 1793 "links" : 1794 [ 1795 { 1796 "value" : "https://example.net/ip/2001:db8::/48", 1797 "rel" : "self", 1798 "href" : "https://example.net/ip/2001:db8::/48", 1799 "type" : "application/rdap+json" 1800 }, 1801 { 1802 "value" : "https://example.net/ip/2001:db8::/48", 1803 "rel" : "up", 1804 "href" : "https://example.net/ip/2001:c00::/23", 1805 "type" : "application/rdap+json" 1806 } 1807 ], 1808 "events" : 1809 [ 1810 { 1811 "eventAction" : "registration", 1812 "eventDate" : "1990-12-31T23:59:59Z" 1813 }, 1814 { 1815 "eventAction" : "last changed", 1816 "eventDate" : "1991-12-31T23:59:59Z" 1817 } 1818 ], 1819 "entities" : 1820 [ 1821 { 1822 "objectClassName" : "entity", 1823 "handle" : "XXXX", 1824 "vcardArray":[ 1825 "vcard", 1826 [ 1827 ["version", {}, "text", "4.0"], 1828 ["fn", {}, "text", "Joe User"], 1829 ["kind", {}, "text", "individual"], 1830 ["lang", { 1831 "pref":"1" 1832 }, "language-tag", "fr"], 1833 ["lang", { 1834 "pref":"2" 1835 }, "language-tag", "en"], 1836 ["org", { 1837 "type":"work" 1838 }, "text", "Example"], 1839 ["title", {}, "text", "Research Scientist"], 1840 ["role", {}, "text", "Project Lead"], 1841 ["adr", 1842 { "type":"work" }, 1843 "text", 1844 [ 1845 "", 1846 "Suite 1234", 1847 "4321 Rue Somewhere", 1848 "Quebec", 1849 "QC", 1850 "G1V 2M2", 1851 "Canada" 1852 ] 1853 ], 1854 ["tel", 1855 { "type":["work", "voice"], "pref":"1" }, 1856 "uri", "tel:+1-555-555-1234;ext=102" 1857 ], 1858 ["email", 1859 { "type":"work" }, 1860 "text", "joe.user@example.com" 1861 ] 1862 ] 1863 ], 1864 "roles" : [ "registrant" ], 1865 "remarks" : 1866 [ 1867 { 1868 "description" : 1869 [ 1870 "She sells sea shells down by the sea shore.", 1871 "Originally written by Terry Sullivan." 1872 ] 1873 } 1874 ], 1875 "links" : 1876 [ 1877 { 1878 "value" : "https://example.net/entity/xxxx", 1879 "rel" : "self", 1880 "href" : "https://example.net/entity/xxxx", 1881 "type" : "application/rdap+json" 1882 } 1883 ], 1884 "events" : 1885 [ 1886 { 1887 "eventAction" : "registration", 1888 "eventDate" : "1990-12-31T23:59:59Z" 1890 }, 1891 { 1892 "eventAction" : "last changed", 1893 "eventDate" : "1991-12-31T23:59:59Z" 1894 } 1895 ] 1896 } 1897 ] 1899 } 1901 Figure 26 1903 The IP network object class can contain the following members: 1905 * objectClassName -- the string "ip network" 1907 * handle -- a string representing the RIR-unique identifier of the 1908 network registration 1910 * startAddress -- a string representing the starting IP address of 1911 the network, either IPv4 or IPv6 1913 * endAddress -- a string representing the ending IP address of the 1914 network, either IPv4 or IPv6 1916 * ipVersion -- a string signifying the IP protocol version of the 1917 network: "v4" signifies an IPv4 network, and "v6" signifies an 1918 IPv6 network 1920 * name -- a string representing an identifier assigned to the 1921 network registration by the registration holder 1923 * type -- a string containing an RIR-specific classification of the 1924 network 1926 * country -- a string containing the two-character country code of 1927 the network 1929 * parentHandle -- a string containing an RIR-unique identifier of 1930 the parent network of this network registration 1932 * status -- an array of strings indicating the state of the IP 1933 network as defined by Section 4.6 1935 * entities -- an array of entity objects as defined by Section 5.1 1937 * remarks -- see Section 4.3 1939 * links -- see Section 4.2 1941 * port43 -- see Section 4.7 1943 * events -- see Section 4.5 1945 5.5. The Autonomous System Number Object Class 1947 The Autonomous System number (autnum) object class models Autonomous 1948 System number registrations found in RIRs and represents the expected 1949 response to an "/autnum" query as defined by 1950 [I-D.ietf-regext-rfc7482bis]. There is no equivalent object class 1951 for DNRs. The high-level structure of the autnum object class 1952 consists of information about the autonomous system number 1953 registration and entities related to the autnum registration (e.g., 1954 registrant information, contacts, etc.) and is similar to the IP 1955 network object class. 1957 The following is an example of a JSON object representing an autnum. 1959 { 1960 "objectClassName" : "autnum", 1961 "handle" : "XXXX-RIR", 1962 "startAutnum" : 10, 1963 "endAutnum" : 15, 1964 "name": "AS-RTR-1", 1965 "type" : "DIRECT ALLOCATION", 1966 "status" : [ "active" ], 1967 "country": "AU", 1968 "remarks" : 1969 [ 1970 { 1971 "description" : 1972 [ 1973 "She sells sea shells down by the sea shore.", 1974 "Originally written by Terry Sullivan." 1975 ] 1976 } 1977 ], 1978 "links" : 1979 [ 1980 { 1981 "value" : "https://example.net/autnum/xxxx", 1982 "rel" : "self", 1983 "href" : "https://example.net/autnum/xxxx", 1984 "type" : "application/rdap+json" 1985 } 1986 ], 1987 "events" : 1989 [ 1990 { 1991 "eventAction" : "registration", 1992 "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" 2043 ] 2044 ] 2045 ], 2046 "roles" : [ "registrant" ], 2047 "remarks" : 2048 [ 2049 { 2050 "description" : 2051 [ 2052 "She sells sea shells down by the sea shore.", 2053 "Originally written by Terry Sullivan." 2054 ] 2055 } 2056 ], 2057 "links" : 2058 [ 2059 { 2060 "value" : "https://example.net/entity/XXXX", 2061 "rel" : "self", 2062 "href" : "https://example.net/entity/XXXX", 2063 "type" : "application/rdap+json" 2064 } 2065 ], 2066 "events" : 2067 [ 2068 { 2069 "eventAction" : "registration", 2070 "eventDate" : "1990-12-31T23:59:59Z" 2071 }, 2072 { 2073 "eventAction" : "last changed", 2074 "eventDate" : "1991-12-31T23:59:59Z" 2075 } 2076 ] 2077 } 2078 ] 2079 } 2081 Figure 27 2083 The Autonomous System number object class can contain the following 2084 members: 2086 * objectClassName -- the string "autnum" 2088 * handle -- a string representing the RIR-unique identifier of the 2089 autnum registration 2091 * startAutnum -- an unsigned 32-bit integer representing the 2092 starting number [RFC5396] in the block of Autonomous System 2093 numbers 2095 * endAutnum -- an unsigned 32-bit integer representing the ending 2096 number [RFC5396] in the block of Autonomous System numbers 2098 * name -- a string representing an identifier assigned to the autnum 2099 registration by the registration holder 2101 * type -- a string containing an RIR-specific classification of the 2102 autnum 2104 * status -- an array of strings indicating the state of the autnum 2105 as defined by Section 4.6 2107 * country -- a string containing the two-character country code of 2108 the autnum 2110 * entities -- an array of entity objects as defined by Section 5.1 2112 * remarks -- see Section 4.3 2114 * links -- see Section 4.2 2116 * port43 -- see Section 4.7 2118 * events -- see Section 4.5 2120 6. Error Response Body 2122 Some non-answer responses MAY return entity bodies with information 2123 that could be more descriptive. 2125 The basic structure of that response is an object class containing a 2126 REQUIRED error code number (corresponding to the HTTP response code) 2127 followed by an OPTIONAL string named "title" and an OPTIONAL array of 2128 strings named "description". 2130 This is an example of the common response body. 2132 { 2133 "errorCode": 418, 2134 "title": "Your Beverage Choice is Not Available", 2135 "description": 2136 [ 2137 "I know coffee has more ummppphhh.", 2138 "Sorry, dude!" 2139 ] 2140 } 2142 Figure 28 2144 This is an example of the common response body with an 2145 rdapConformance and notices data structures: 2147 { 2148 "rdapConformance" : 2149 [ 2150 "rdap_level_0" 2151 ], 2152 "notices" : 2153 [ 2154 { 2155 "title" : "Beverage Policy", 2156 "description" : 2157 [ 2158 "Beverages with caffeine for keeping horses awake." 2159 ], 2160 "links" : 2161 [ 2162 { 2163 "value" : "https://example.net/ip/192.0.2.0/24", 2164 "rel" : "alternate", 2165 "type" : "text/html", 2166 "href" : "https://www.example.com/redaction_policy.html" 2167 } 2168 ] 2169 } 2170 ], 2171 "lang" : "en", 2172 "errorCode": 418, 2173 "title": "Your beverage choice is not available", 2174 "description": 2175 [ 2176 "I know coffee has more ummppphhh.", 2177 "Sorry, dude!" 2178 ] 2179 } 2180 Figure 29 2182 7. Responding to Help Queries 2184 The appropriate response to /help queries as defined by 2185 [I-D.ietf-regext-rfc7482bis] is to use the notices structure as 2186 defined in Section 4.3. 2188 This is an example of a response to a /help query including the 2189 rdapConformance data structure. 2191 { 2192 "rdapConformance" : 2193 [ 2194 "rdap_level_0" 2195 ], 2196 "notices" : 2197 [ 2198 { 2199 "title" : "Authentication Policy", 2200 "description" : 2201 [ 2202 "Access to sensitive data for users with proper credentials." 2203 ], 2204 "links" : 2205 [ 2206 { 2207 "value" : "https://example.net/help", 2208 "rel" : "alternate", 2209 "type" : "text/html", 2210 "href" : "https://www.example.com/auth_policy.html" 2211 } 2212 ] 2213 } 2214 ] 2215 } 2217 Figure 30 2219 8. Responding To Searches 2221 [I-D.ietf-regext-rfc7482bis] specifies three types of searches: 2222 domains, nameservers, and entities. Responses to these searches take 2223 the form of an array of object instances where each instance is an 2224 appropriate object class for the search (i.e., a search for /domains 2225 yields an array of domain object instances). These arrays are 2226 contained within the response object. 2228 The names of the arrays are as follows: 2230 * for /domains searches, the array is "domainSearchResults" 2232 * for /nameservers searches, the array is "nameserverSearchResults" 2234 * for /entities searches, the array is "entitySearchResults" 2236 The following is an elided example of a response to a /domains 2237 search. 2239 { 2240 "rdapConformance" : 2241 [ 2242 "rdap_level_0" 2243 ], 2244 ... 2245 "domainSearchResults" : 2246 [ 2247 { 2248 "objectClassName" : "domain", 2249 "handle" : "1-XXXX", 2250 "ldhName" : "1.example.com", 2251 ... 2252 }, 2253 { 2254 "objectClassName" : "domain", 2255 "handle" : "2-XXXX", 2256 "ldhName" : "2.example.com", 2257 ... 2258 } 2259 ] 2260 } 2262 Figure 31 2264 9. Indicating Truncated Responses 2266 In cases where the data of a response needs to be limited or parts of 2267 the data need to be omitted, the response is considered "truncated". 2268 A truncated response is still valid JSON, but some of the results in 2269 a search set or some of the data in an object are not provided by the 2270 server. A server may indicate this by including a typed notice in 2271 the response object. 2273 The following is an elided example of a search response that has been 2274 truncated. 2276 { 2277 "rdapConformance" : 2278 [ 2279 "rdap_level_0" 2280 ], 2281 "notices" : 2282 [ 2283 { 2284 "title" : "Search Policy", 2285 "type" : "result set truncated due to authorization", 2286 "description" : 2287 [ 2288 "Search results are limited to 25 per day per querying IP." 2289 ], 2290 "links" : 2291 [ 2292 { 2293 "value" : "https://example.net/help", 2294 "rel" : "alternate", 2295 "type" : "text/html", 2296 "href" : "https://www.example.com/search_policy.html" 2297 } 2298 ] 2299 } 2300 ], 2301 "domainSearchResults" : 2302 [ 2303 ... 2304 ] 2305 } 2307 Figure 32 2309 A similar technique can be used with a typed remark where a single 2310 object has been returned and data in that object has been truncated. 2311 Such an example might be an entity object with only a partial set of 2312 the IP networks associated with it. 2314 The following is an elided example of an entity truncated data. 2316 { 2317 "objectClassName" : "entity", 2318 "handle" : "ANENTITY", 2319 "roles" : [ "registrant" ], 2320 ... 2321 "entities" : 2322 [ 2323 { 2324 "objectClassName" : "entity", 2325 "handle": "ANEMBEDDEDENTITY", 2326 "roles" : [ "technical" ], 2327 ... 2328 }, 2329 ... 2330 ], 2331 "networks" : 2332 [ 2333 ... 2334 ], 2335 ... 2336 "remarks" : 2337 [ 2338 { 2339 "title" : "Data Policy", 2340 "type" : "object truncated due to unexplainable reason", 2341 "description" : 2342 [ 2343 "Some of the data in this object has been removed." 2344 ], 2345 "links" : 2346 [ 2347 { 2348 "value" : "https://example.net/help", 2349 "rel" : "alternate", 2350 "type" : "text/html", 2351 "href" : "https://www.example.com/data_policy.html" 2352 } 2353 ] 2354 } 2355 ] 2356 } 2358 Figure 33 2360 10. IANA Considerations 2362 IANA is requested to update the description of the "transfer" event 2363 action as described in Section 10.2.3. 2365 10.1. RDAP JSON Media Type Registration 2367 This specification registers the "application/rdap+json" media 2368 type. 2369 Type name: application 2371 Subtype name: rdap+json 2373 Required parameters: n/a 2375 Encoding considerations: See Section 3.1 of [RFC6839]. 2377 Security considerations: The media represented by this identifier 2378 does not have security considerations beyond that found in 2379 Section 12 of [RFC8259]. 2381 Interoperability considerations: There are no known 2382 interoperability problems regarding this media format. 2384 Published specification: RFC 7483 2386 Applications that use this media type: Implementations of the 2387 Registration Data Access Protocol (RDAP). 2389 Additional information: This media type is a product of the IETF 2390 WEIRDS working group. The WEIRDS charter, information on the 2391 WEIRDS mailing list, and other documents produced by the WEIRDS 2392 working group can be found at https://datatracker.ietf.org/wg/ 2393 weirds/. 2395 Person & email address to contact for further information: IESG 2396 2398 Intended usage: COMMON 2400 Restrictions on usage: none 2402 Author: Andy Newton 2404 Change controller: IETF 2406 Provisional Registration: No (upon publication of this RFC) 2408 10.2. JSON Values Registry 2410 IANA has created a category in the protocol registries labeled 2411 "Registration Data Access Protocol (RDAP)", and within that category, 2412 IANA has established a URL-referenceable, stand-alone registry 2413 labeled "RDAP JSON Values". This new registry is for use in the 2414 notices and remarks (Section 4.3), status (Section 4.6), role 2415 (Section 5.1), event action (Section 4.5), and domain variant 2416 relation (Section 5.3) fields specified in RDAP. 2418 Each entry in the registry contains the following fields: 2420 1. Value -- the string value being registered. 2422 2. Type -- the type of value being registered. It should be one of 2423 the following: 2425 * "notice or remark type" -- denotes a type of notice or remark. 2427 * "status" -- denotes a value for the "status" object member as 2428 defined by Section 4.6. 2430 * "role" -- denotes a value for the "role" array as defined in 2431 Section 5.1. 2433 * "event action" -- denotes a value for an event action as 2434 defined in Section 4.5. 2436 * "domain variant relation" -- denotes a relationship between a 2437 domain and a domain variant as defined in Section 5.3. 2439 3. Description -- a one- or two-sentence description regarding the 2440 meaning of the value, how it might be used, and/or how it should 2441 be interpreted by clients. 2443 4. Registrant Name -- the name of the person registering the value. 2445 5. Registrant Contact Information -- an email address, postal 2446 address, or some other information to be used to contact the 2447 registrant. 2449 This registry is operated under the "Expert Review" policy defined in 2450 [RFC8126]. 2452 Review of registrations into this registry by the designated 2453 expert(s) should be narrowly judged on the following criteria: 2455 1. Values in need of being placed into multiple types must be 2456 assigned a separate registration for each type. 2458 2. Values must be strings. They should be multiple words separated 2459 by single space characters. Every character should be 2460 lowercased. If possible, every word should be given in English 2461 and each character should be US-ASCII. 2463 3. Registrations should not duplicate the meaning of any existing 2464 registration. That is, if a request for a registration is 2465 significantly similar in nature to an existing registration, the 2466 request should be denied. For example, the terms "maintainer" 2467 and "registrant" are significantly similar in nature as they both 2468 denote a holder of a domain name or Internet number resource. In 2469 cases where it may be reasonably argued that machine 2470 interpretation of two similar values may alter the operation of 2471 client software, designated experts should not judge the values 2472 to be of significant similarity. 2474 4. Registrations should be relevant to the common usages of RDAP. 2475 Designated experts may rely upon the serving of the value by a 2476 DNR or RIR to make this determination. 2478 The following sections provide initial registrations into this 2479 registry. 2481 10.2.1. Notice and Remark Types 2483 The following values have been registered in the "RDAP JSON Values" 2484 registry: 2486 * Value: result set truncated due to authorization 2488 Type: notice and remark type 2490 Description: The list of results does not contain all results due 2491 to lack of authorization. This may indicate to some clients that 2492 proper authorization will yield a longer result set. 2494 Registrant Name: IESG 2496 Registrant Contact Information: iesg@ietf.org 2498 * Value: result set truncated due to excessive load 2500 Type: notice and remark type 2501 Description: The list of results does not contain all results due 2502 to excessively heavy load on the server. This may indicate to 2503 some clients that requerying at a later time will yield a longer 2504 result set. 2506 Registrant Name: IESG 2508 Registrant Contact Information: iesg@ietf.org 2510 * Value: result set truncated due to unexplainable reasons 2512 Type: notice and remark type 2514 Description: The list of results does not contain all results for 2515 an unexplainable reason. This may indicate to some clients that 2516 requerying for any reason will not yield a longer result set. 2518 Registrant Name: IESG 2520 Registrant Contact Information: iesg@ietf.org 2522 * Value: object truncated due to authorization 2524 Type: notice and remark type 2526 Description: The object does not contain all data due to lack of 2527 authorization. 2529 Registrant Name: IESG 2531 Registrant Contact Information: iesg@ietf.org 2533 * Value: object truncated due to excessive load 2535 Type: notice and remark type 2537 Description: The object does not contain all data due to 2538 excessively heavy load on the server. This may indicate to some 2539 clients that requerying at a later time will yield all data of the 2540 object. 2542 Registrant Name: IESG 2544 Registrant Contact Information: iesg@ietf.org 2546 * Value: object truncated due to unexplainable reasons 2548 Type: notice and remark type 2549 Description: The object does not contain all data for an 2550 unexplainable reason. 2552 Registrant Name: IESG 2554 Registrant Contact Information: iesg@ietf.org 2556 10.2.2. Status 2558 The following values have been registered in the "RDAP JSON Values" 2559 registry: 2561 * Value: validated 2563 Type: status 2565 Description: Signifies that the data of the object instance has 2566 been found to be accurate. This type of status is usually found 2567 on entity object instances to note the validity of identifying 2568 contact information. 2570 Registrant Name: IESG 2572 Registrant Contact Information: iesg@ietf.org 2574 * Value: renew prohibited 2576 Type: status 2578 Description: Renewal or reregistration of the object instance is 2579 forbidden. 2581 Registrant Name: IESG 2583 Registrant Contact Information: iesg@ietf.org 2585 * Value: update prohibited 2587 Type: status 2589 Description: Updates to the object instance are forbidden. 2591 Registrant Name: IESG 2593 Registrant Contact Information: iesg@ietf.org 2595 * Value: transfer prohibited 2596 Type: status 2598 Description: Transfers of the registration from one registrar to 2599 another are forbidden. This type of status normally applies to 2600 DNR domain names. 2602 Registrant Name: IESG 2604 Registrant Contact Information: iesg@ietf.org 2606 * Value: delete prohibited 2608 Type: status 2610 Description: Deletion of the registration of the object instance 2611 is forbidden. This type of status normally applies to DNR domain 2612 names. 2614 Registrant Name: IESG 2616 Registrant Contact Information: iesg@ietf.org 2618 * Value: proxy 2620 Type: status 2622 Description: The registration of the object instance has been 2623 performed by a third party. This is most commonly applied to 2624 entities. 2626 Registrant Name: IESG 2628 Registrant Contact Information: iesg@ietf.org 2630 * Value: private 2632 Type: status 2634 Description: The information of the object instance is not 2635 designated for public consumption. This is most commonly applied 2636 to entities. 2638 Registrant Name: IESG 2640 Registrant Contact Information: iesg@ietf.org 2642 * Value: removed 2643 Type: status 2645 Description: Some of the information of the object instance has 2646 not been made available and has been removed. This is most 2647 commonly applied to entities. 2649 Registrant Name: IESG 2651 Registrant Contact Information: iesg@ietf.org 2653 * Value: obscured 2655 Type: status 2657 Description: Some of the information of the object instance has 2658 been altered for the purposes of not readily revealing the actual 2659 information of the object instance. This is most commonly applied 2660 to entities. 2662 Registrant Name: IESG 2664 Registrant Contact Information: iesg@ietf.org 2666 * Value: associated 2668 Type: status 2670 Description: The object instance is associated with other object 2671 instances in the registry. This is most commonly used to signify 2672 that a nameserver is associated with a domain or that an entity is 2673 associated with a network resource or domain. 2675 Registrant Name: IESG 2677 Registrant Contact Information: iesg@ietf.org 2679 * Value: active 2681 Type: status 2683 Description: The object instance is in use. For domain names, it 2684 signifies that the domain name is published in DNS. For network 2685 and autnum registrations it signifies that they are allocated or 2686 assigned for use in operational networks. This maps to the 2687 Extensible Provisioning Protocol (EPP) [RFC5730] 'OK' status. 2689 Registrant Name: IESG 2690 Registrant Contact Information: iesg@ietf.org 2692 * Value: inactive 2694 Type: status 2696 Description: The object instance is not in use. See 'active'. 2698 Registrant Name: IESG 2700 Registrant Contact Information: iesg@ietf.org 2702 * Value: locked 2704 Type: status 2706 Description: Changes to the object instance cannot be made, 2707 including the association of other object instances. 2709 Registrant Name: IESG 2711 Registrant Contact Information: iesg@ietf.org 2713 * Value: pending create 2715 Type: status 2717 Description: A request has been received for the creation of the 2718 object instance but this action is not yet complete. 2720 Registrant Name: IESG 2722 Registrant Contact Information: iesg@ietf.org 2724 * Value: pending renew 2726 Type: status 2728 Description: A request has been received for the renewal of the 2729 object instance but this action is not yet complete. 2731 Registrant Name: IESG 2733 Registrant Contact Information: iesg@ietf.org 2735 * Value: pending transfer 2737 Type: status 2738 Description: A request has been received for the transfer of the 2739 object instance but this action is not yet complete. 2741 Registrant Name: IESG 2743 Registrant Contact Information: iesg@ietf.org 2745 * Value: pending update 2747 Type: status 2749 Description: A request has been received for the update or 2750 modification of the object instance but this action is not yet 2751 complete. 2753 Registrant Name: IESG 2755 Registrant Contact Information: iesg@ietf.org 2757 * Value: pending delete 2759 Type: status 2761 Description: A request has been received for the deletion or 2762 removal of the object instance but this action is not yet 2763 complete. For domains, this might mean that the name is no longer 2764 published in DNS but has not yet been purged from the registry 2765 database. 2767 Registrant Name: IESG 2769 Registrant Contact Information: iesg@ietf.org 2771 10.2.3. Event Actions 2773 The following values have been registered in the "RDAP JSON Values" 2774 registry: 2776 * Value: registration 2778 Type: event action 2780 Description: The object instance was initially registered. 2782 Registrant Name: IESG 2784 Registrant Contact Information: iesg@ietf.org 2786 * Value: reregistration 2788 Type: event action 2790 Description: The object instance was registered subsequently to 2791 initial registration. 2793 Registrant Name: IESG 2795 Registrant Contact Information: iesg@ietf.org 2797 * Value: last changed 2799 Type: event action 2801 Description: An action noting when the information in the object 2802 instance was last changed. 2804 Registrant Name: IESG 2806 Registrant Contact Information: iesg@ietf.org 2808 * Value: expiration 2810 Type: event action 2812 Description: The object instance has been removed or will be 2813 removed at a pre-determined date and time from the registry. 2815 Registrant Name: IESG 2817 Registrant Contact Information: iesg@ietf.org 2819 * Value: deletion 2821 Type: event action 2823 Description: The object instance was removed from the registry at 2824 a point in time that was not pre-determined. 2826 Registrant Name: IESG 2828 Registrant Contact Information: iesg@ietf.org 2830 * Value: reinstantiation 2832 Type: event action 2833 Description: The object instance was reregistered after having 2834 been removed from the registry. 2836 Registrant Name: IESG 2838 Registrant Contact Information: iesg@ietf.org 2840 * Value: transfer 2842 Type: event action 2844 Description: The object instance was transferred from one 2845 registrar to another. 2847 Registrant Name: IESG 2849 Registrant Contact Information: iesg@ietf.org 2851 * Value: locked 2853 Type: event action 2855 Description: The object instance was locked (see the 'locked' 2856 status). 2858 Registrant Name: IESG 2860 Registrant Contact Information: iesg@ietf.org 2862 * Value: unlocked 2864 Type: event action 2866 Description: The object instance was unlocked (see the 'locked' 2867 status). 2869 Registrant Name: IESG 2871 Registrant Contact Information: iesg@ietf.org 2873 10.2.4. Roles 2875 The following values have been registered in the "RDAP JSON Values" 2876 registry: 2878 * Value: registrant 2880 Type: role 2881 Description: The entity object instance is the registrant of the 2882 registration. In some registries, this is known as a maintainer. 2884 Registrant Name: IESG 2886 Registrant Contact Information: iesg@ietf.org 2888 * Value: technical 2890 Type: role 2892 Description: The entity object instance is a technical contact for 2893 the registration. 2895 Registrant Name: IESG 2897 Registrant Contact Information: iesg@ietf.org 2899 * Value: administrative 2901 Type: role 2903 Description: The entity object instance is an administrative 2904 contact for the registration. 2906 Registrant Name: IESG 2908 Registrant Contact Information: iesg@ietf.org 2910 * Value: abuse 2912 Type: role 2914 Description: The entity object instance handles network abuse 2915 issues on behalf of the registrant of the registration. 2917 Registrant Name: IESG 2919 Registrant Contact Information: iesg@ietf.org 2921 * Value: billing 2923 Type: role 2925 Description: The entity object instance handles payment and 2926 billing issues on behalf of the registrant of the registration. 2928 Registrant Name: IESG 2929 Registrant Contact Information: iesg@ietf.org 2931 * Value: registrar 2933 Type: role 2935 Description: The entity object instance represents the authority 2936 responsible for the registration in the registry. 2938 Registrant Name: IESG 2940 Registrant Contact Information: iesg@ietf.org 2942 * Value: reseller 2944 Type: role 2946 Description: The entity object instance represents a third party 2947 through which the registration was conducted (i.e. not the 2948 registry or registrar). 2950 Registrant Name: IESG 2952 Registrant Contact Information: iesg@ietf.org 2954 * Value: sponsor 2956 Type: role 2958 Description: The entity object instance represents a domain policy 2959 sponsor, such as an ICANN approved sponsor. 2961 Registrant Name: IESG 2963 Registrant Contact Information: iesg@ietf.org 2965 * Value: proxy 2967 Type: role 2969 Description: The entity object instance represents a proxy for 2970 another entity object, such as a registrant. 2972 Registrant Name: IESG 2974 Registrant Contact Information: iesg@ietf.org 2976 * Value: notifications 2977 Type: role 2979 Description: An entity object instance designated to receive 2980 notifications about association object instances. 2982 Registrant Name: IESG 2984 Registrant Contact Information: iesg@ietf.org 2986 * Value: noc 2988 Type: role 2990 Description: The entity object instance handles communications 2991 related to a network operations center (NOC). 2993 Registrant Name: IESG 2995 Registrant Contact Information: iesg@ietf.org 2997 10.2.5. Variant Relations 2999 The following values have been registered in the "RDAP JSON Values" 3000 registry: 3002 * Value: registered 3004 Type: domain variant relation 3006 Description: The variant names are registered in the registry. 3008 Registrant Name: IESG 3010 Registrant Contact Information: iesg@ietf.org 3012 * Value: unregistered 3014 Type: domain variant relation 3016 Description: The variant names are not found in the registry. 3018 Registrant Name: IESG 3020 Registrant Contact Information: iesg@ietf.org 3022 * Value: registration restricted 3024 Type: domain variant relation 3025 Description: Registration of the variant names is restricted to 3026 certain parties or within certain rules. 3028 Registrant Name: IESG 3030 Registrant Contact Information: iesg@ietf.org 3032 * Value: open registration 3034 Type: domain variant relation 3036 Description: Registration of the variant names is available to 3037 generally qualified registrants. 3039 Registrant Name: IESG 3041 Registrant Contact Information: iesg@ietf.org 3043 * Value: conjoined 3045 Type: domain variant relation 3047 Description: Registration of the variant names occurs 3048 automatically with the registration of the containing domain 3049 registration. 3051 Registrant Name: IESG 3053 Registrant Contact Information: iesg@ietf.org 3055 11. Implementation Status 3057 NOTE: Please remove this section and the reference to RFC 7942 prior 3058 to publication as an RFC. 3060 This section records the status of known implementations of the 3061 protocol defined by this specification at the time of posting of this 3062 Internet-Draft, and is based on a proposal described in RFC 7942 3063 [RFC7942]. The description of implementations in this section is 3064 intended to assist the IETF in its decision processes in progressing 3065 drafts to RFCs. Please note that the listing of any individual 3066 implementation here does not imply endorsement by the IETF. 3067 Furthermore, no effort has been spent to verify the information 3068 presented here that was supplied by IETF contributors. This is not 3069 intended as, and must not be construed to be, a catalog of available 3070 implementations or their features. Readers are advised to note that 3071 other implementations may exist. 3073 According to RFC 7942, "this will allow reviewers and working groups 3074 to assign due consideration to documents that have the benefit of 3075 running code, which may serve as evidence of valuable experimentation 3076 and feedback that have made the implemented protocols more mature. 3077 It is up to the individual working groups to use this information as 3078 they see fit". 3080 11.1. RedDog 3082 * Responsible Organization: NIC Mexico 3084 * Location: https://reddog.mx/ 3086 * Description: RedDog implements all the functionality of an RDAP 3087 Server defined in RFCs 7480,7481,7482 and 7483. RedDog is highly 3088 configurable and extensible to fit the needs of the developers and 3089 operators. 3091 * Level of Maturity: Production. 3093 * Coverage: RedDog supports all lookups, searches and responses for 3094 all object classes described in RFC 7482 and RFC 7483. 3096 * Version Compatibility: RFC 7482 and RFC 7483 3098 * Licensing: Apache License 2.0 3100 * Contact Information: reddog-dev@nic.mx 3102 * Information last updated: November 22, 2019 3104 11.2. Verisign 3106 * Responsible Organization: Verisign 3108 * Location: https://rdap.verisign.com/com/v1/, 3109 https://rdap.verisign.com/net/v1/ 3111 * Description: Verisign's production RDAP service for the .com and 3112 .net gTLDs. 3114 * Level of Maturity: Production. 3116 * Coverage: Lookup of domain names, name servers, entities; name 3117 server search by IP address; help. 3119 * Version Compatibility: RFC 7483 3120 * Contact Information: info@verisign-grs.com 3122 11.3. Verisign Labs 3124 * Responsible Organization: Verisign Labs 3126 * Location: https://rdap.verisignlabs.com/rdap/v1/ 3128 * Description: Verisign's experimental RDAP service for the .cc and 3129 .tv ccTLDs. 3131 * Level of Maturity: Experimental. 3133 * Coverage: Lookup of domain names, name servers, entities; name 3134 server search by IP address; basic search; regular expression 3135 search; federated authentication; help. 3137 * Version Compatibility: RFC 7483 3139 * Contact Information: Scott Hollenbeck, shollenbeck@verisign.com 3141 11.4. Asia-Pacific Network Information Centre (APNIC) 3143 * Responsible Organization: Asia-Pacific Network Information Centre 3144 (APNIC) 3146 * Location: https://rdap.apnic.net/, https://github.com/APNIC-net/ 3147 rdapd 3149 * Description: APNIC's production RDAP service for Internet number 3150 resouces. 3152 * Level of Maturity: Production. 3154 * Coverage: Lookup of IP networks, AS numbers, domains, and 3155 entities. Also domain search by name, entity search by handle or 3156 full name, and help responses. 3158 * Version Compatibility: RFC 7483 3160 * Contact Information: helpdesk@apnic.net 3162 12. Security Considerations 3164 This specification models information serialized in JSON format. As 3165 JSON is a subset of JavaScript, implementations are advised to follow 3166 the security considerations outlined in Section 12 of [RFC8259] to 3167 prevent code injection. 3169 Though not specific to JSON, RDAP implementers should be aware of the 3170 security considerations specified in [RFC7480] and the security 3171 requirements and considerations in [RFC7481]. 3173 Clients caching data, especially clients using RDAP-specific caches 3174 (instead of HTTP-layer caches), should have safeguards to prevent 3175 cache poisoning. See Section 5 for advice on using the self links 3176 for caching. 3178 Finally, service operators should be aware of the privacy mechanisms 3179 noted in Section 14. 3181 13. Internationalization Considerations 3183 13.1. Character Encoding 3185 The default text encoding for JSON responses in RDAP is UTF-8 3186 [RFC3629], and all servers and clients MUST support UTF-8. 3188 13.2. URIs and IRIs 3190 [RFC7480] defines the use of URIs and IRIs in RDAP. 3192 13.3. Language Tags 3194 Section 4.4 defines the use of language tags in the JSON responses 3195 defined in this document. 3197 13.4. Internationalized Domain Names 3199 IDNs are denoted in this specification by the separation of DNS names 3200 in LDH form and Unicode form (see Section 3). Representation of IDNs 3201 in registries is described by the "variants" object in Section 5.3 3202 and the suggested values listed in Section 10.2.5. 3204 14. Privacy Considerations 3206 This specification suggests status values to denote contact and 3207 registrant information that has been marked as private and/or has 3208 been removed or obscured. See Section 10.2.2 for the complete list 3209 of status values. A few of the status values indicate that there are 3210 privacy concerns associated with the object instance. The following 3211 status codes SHOULD be used to describe data elements of a response 3212 when appropriate: 3214 private -- The object is not be shared in query responses, unless 3215 the user is authorized to view this information. 3217 removed -- Data elements within the object have been collected but 3218 have been omitted from the response. This option can be used to 3219 prevent unauthorized access to associated object instances without 3220 the need to mark them as private. 3222 obscured -- Data elements within the object have been collected, 3223 but the response value has been altered so that values are not 3224 easily discernible. A value changed from "1212" to "XXXX" is an 3225 example of obscured data. This option may reveal privacy 3226 sensitive information and should only be used when data 3227 sensitivity does not require a more protective option like 3228 "private" or "removed". 3230 See Appendix A.1 for an example of applying those values to contacts 3231 and registrants. 3233 15. References 3235 15.1. Normative References 3237 [I-D.ietf-regext-rfc7482bis] 3238 Hollenbeck, S. and A. Newton, "Registration Data Access 3239 Protocol (RDAP) Query Format", Work in Progress, Internet- 3240 Draft, draft-ietf-regext-rfc7482bis-02, 8 September 2020, 3241 . 3244 [ISO.3166.1988] 3245 International Organization for Standardization, "Codes for 3246 the representation of names of countries, 3rd edition", 3247 ISO Standard 3166, August 1988. 3249 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3250 Requirement Levels", BCP 14, RFC 2119, 3251 DOI 10.17487/RFC2119, March 1997, 3252 . 3254 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3255 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3256 . 3258 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3259 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3260 2003, . 3262 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3263 Resource Identifier (URI): Generic Syntax", STD 66, 3264 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3265 . 3267 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 3268 Rose, "Resource Records for the DNS Security Extensions", 3269 RFC 4034, DOI 10.17487/RFC4034, March 2005, 3270 . 3272 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 3273 Autonomous System (AS) Numbers", RFC 5396, 3274 DOI 10.17487/RFC5396, December 2008, 3275 . 3277 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 3278 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 3279 September 2009, . 3281 [RFC5890] Klensin, J., "Internationalized Domain Names for 3282 Applications (IDNA): Definitions and Document Framework", 3283 RFC 5890, DOI 10.17487/RFC5890, August 2010, 3284 . 3286 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3287 Address Text Representation", RFC 5952, 3288 DOI 10.17487/RFC5952, August 2010, 3289 . 3291 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 3292 DOI 10.17487/RFC7095, January 2014, 3293 . 3295 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 3296 Registration Data Access Protocol (RDAP)", RFC 7480, 3297 DOI 10.17487/RFC7480, March 2015, 3298 . 3300 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 3301 Registration Data Access Protocol (RDAP)", RFC 7481, 3302 DOI 10.17487/RFC7481, March 2015, 3303 . 3305 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3306 Writing an IANA Considerations Section in RFCs", BCP 26, 3307 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3308 . 3310 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3311 Interchange Format", STD 90, RFC 8259, 3312 DOI 10.17487/RFC8259, December 2017, 3313 . 3315 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 3316 DOI 10.17487/RFC8288, October 2017, 3317 . 3319 15.2. Informative References 3321 [IANA_IDNTABLES] 3322 IANA, "Repository of IDN Practices", 3323 . 3325 [JSON_ascendancy] 3326 MacVittie, L., "The Stealthy Ascendancy of JSON", April 3327 2011, . 3330 [JSON_performance_study] 3331 Nurseitov, N., Paulson, M., Reynolds, R., and C. Izurieta, 3332 "Comparison of JSON and XML Data Interchange Formats: A 3333 Case Study", 2009, 3334 . 3336 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 3337 DOI 10.17487/RFC3912, September 2004, 3338 . 3340 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 3341 STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009, 3342 . 3344 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 3345 Security Extensions Mapping for the Extensible 3346 Provisioning Protocol (EPP)", RFC 5910, 3347 DOI 10.17487/RFC5910, May 2010, 3348 . 3350 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 3351 DOI 10.17487/RFC6350, August 2011, 3352 . 3354 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 3355 Structured Syntax Suffixes", RFC 6839, 3356 DOI 10.17487/RFC6839, January 2013, 3357 . 3359 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 3360 Code: The Implementation Status Section", BCP 205, 3361 RFC 7942, DOI 10.17487/RFC7942, July 2016, 3362 . 3364 Appendix A. Suggested Data Modeling with the Entity Object Class 3366 A.1. Registrants and Contacts 3368 This document does not provide specific object classes for 3369 registrants and contacts. Instead, the entity object class may be 3370 used to represent a registrant or contact. When the entity object is 3371 embedded inside a containing object such as a domain name or IP 3372 network, the "roles" string array can be used to signify the 3373 relationship. It is recommended that the values from Section 10.2.4 3374 be used. 3376 The following is an example of an elided containing object with an 3377 embedded entity that is both a registrant and administrative contact: 3379 { 3380 ... 3381 "entities" : 3382 [ 3383 { 3384 "objectClassName" : "entity", 3385 "handle" : "XXXX", 3386 "vcardArray":[ 3387 "vcard", 3388 [ 3389 ["version", {}, "text", "4.0"], 3390 ["fn", {}, "text", "Joe User"], 3391 ["kind", {}, "text", "individual"], 3392 ["lang", { 3393 "pref":"1" 3394 }, "language-tag", "fr"], 3395 ["lang", { 3396 "pref":"2" 3397 }, "language-tag", "en"], 3398 ["org", { 3399 "type":"work" 3400 }, "text", "Example"], 3401 ["title", {}, "text", "Research Scientist"], 3402 ["role", {}, "text", "Project Lead"], 3403 ["adr", 3404 { "type":"work" }, 3405 "text", 3406 [ 3407 "", 3408 "Suite 1234", 3409 "4321 Rue Somewhere", 3410 "Quebec", 3411 "QC", 3412 "G1V 2M2", 3413 "Canada" 3414 ] 3415 ], 3416 ["tel", 3417 { "type":["work", "voice"], "pref":"1" }, 3418 "uri", "tel:+1-555-555-1234;ext=102" 3419 ], 3420 ["email", 3421 { "type":"work" }, 3422 "text", "joe.user@example.com" 3423 ] 3424 ] 3425 ], 3426 "roles" : [ "registrant", "administrative" ], 3427 "remarks" : 3428 [ 3429 { 3430 "description" : 3431 [ 3432 "She sells sea shells down by the sea shore.", 3433 "Originally written by Terry Sullivan." 3434 ] 3435 } 3436 ], 3437 "events" : 3438 [ 3439 { 3440 "eventAction" : "registration", 3441 "eventDate" : "1990-12-31T23:59:59Z" 3442 }, 3443 { 3444 "eventAction" : "last changed", 3445 "eventDate" : "1991-12-31T23:59:59Z" 3446 } 3447 ] 3448 } 3449 ] 3450 } 3452 Figure 34 3454 In many use cases, it is necessary to hide or obscure the information 3455 of a registrant or contact due to policy or other operational 3456 matters. Registries can denote these situations with "status" values 3457 (see Section 10.2.2). 3459 The following is an elided example of a registrant with information 3460 changed to reflect that of a third party. 3462 { 3463 ... 3464 "entities" : 3465 [ 3466 { 3467 "objectClassName" : "entity", 3468 "handle" : "XXXX", 3469 ... 3470 "roles" : [ "registrant", "administrative" ], 3471 "status" : [ "proxy", "private", "obscured" ] 3472 } 3473 ] 3474 } 3476 Figure 35 3478 A.2. Registrars 3480 This document does not provide a specific object class for 3481 registrars, but like registrants and contacts (see Appendix A.1), the 3482 "roles" string array maybe used. Additionally, many registrars have 3483 publicly assigned identifiers. The publicIds structure (Section 4.8) 3484 represents that information. 3486 The following is an example of an elided containing object with an 3487 embedded entity that is a registrar: 3489 { 3490 ... 3491 "entities":[ 3492 { 3493 "objectClassName" : "entity", 3494 "handle":"XXXX", 3495 "vcardArray":[ 3496 "vcard", 3497 [ 3498 ["version", {}, "text", "4.0"], 3499 ["fn", {}, "text", "Joe's Fish, Chips, and Domains"], 3500 ["kind", {}, "text", "org"], 3501 ["lang", { 3502 "pref":"1" 3503 }, "language-tag", "fr"], 3504 ["lang", { 3505 "pref":"2" 3506 }, "language-tag", "en"], 3507 ["org", { 3508 "type":"work" 3509 }, "text", "Example"], 3510 ["adr", 3511 { "type":"work" }, 3512 "text", 3513 [ 3514 "", 3515 "Suite 1234", 3516 "4321 Rue Somewhere", 3517 "Quebec", 3518 "QC", 3519 "G1V 2M2", 3520 "Canada" 3521 ] 3522 ], 3523 ["tel", 3524 { 3525 "type":["work", "voice"], 3526 "pref":"1" 3527 }, 3528 "uri", "tel:+1-555-555-1234;ext=102" 3529 ], 3530 ["email", 3531 { "type":"work" }, 3532 "text", "joes_fish_chips_and_domains@example.com" 3533 ] 3534 ] 3535 ], 3536 "roles":[ "registrar" ], 3537 "publicIds":[ 3538 { 3539 "type":"IANA Registrar ID", 3540 "identifier":"1" 3541 } 3542 ], 3543 "remarks":[ 3544 { 3545 "description":[ 3546 "She sells sea shells down by the sea shore.", 3547 "Originally written by Terry Sullivan." 3548 ] 3549 } 3551 ], 3552 "links":[ 3553 { 3554 "value":"https://example.net/entity/XXXX", 3555 "rel":"alternate", 3556 "type":"text/html", 3557 "href":"https://www.example.com" 3558 } 3559 ] 3560 } 3561 ] 3562 } 3564 Figure 36 3566 Appendix B. Modeling Events 3568 Events represent actions that have taken place against a registered 3569 object at a certain date and time. Events have three properties: the 3570 action, the actor, and the date and time of the event (which is 3571 sometimes in the future). In some cases, the identity of the actor 3572 is not captured. 3574 Events can be modeled in three ways: 3576 1. events with no designated actor 3578 2. events where the actor is only designated by an identifier 3580 3. events where the actor can be modeled as an entity 3582 For the first use case, the events data structure (Section 4.5) is 3583 used without the "eventActor" object member. 3585 This is an example of an "events" array without the "eventActor". 3587 "events" : 3588 [ 3589 { 3590 "eventAction" : "registration", 3591 "eventDate" : "1990-12-31T23:59:59Z" 3592 } 3593 ] 3595 Figure 37 3597 For the second use case, the events data structure (Section 4.5) is 3598 used with the "eventActor" object member. 3600 This is an example of an "events" array with the "eventActor". 3602 "events" : 3603 [ 3604 { 3605 "eventAction" : "registration", 3606 "eventActor" : "XYZ-NIC", 3607 "eventDate" : "1990-12-31T23:59:59Z" 3608 } 3609 ] 3611 Figure 38 3613 For the third use case, the "asEventActor" array is used when an 3614 entity (Section 5.1) is embedded into another object class. The 3615 "asEventActor" array follows the same structure as the "events" array 3616 but does not have "eventActor" attributes. 3618 The following is an elided example of a domain object with an entity 3619 as an event actor. 3621 { 3622 "objectClassName" : "domain", 3623 "handle" : "XXXX", 3624 "ldhName" : "foo.example", 3625 "status" : [ "locked", "transfer prohibited" ], 3626 ... 3627 "entities" : 3628 [ 3629 { 3630 "handle" : "XXXX", 3631 ... 3632 "asEventActor" : 3633 [ 3634 { 3635 "eventAction" : "last changed", 3636 "eventDate" : "1990-12-31T23:59:59Z" 3637 } 3638 ] 3639 } 3640 ] 3641 } 3643 Figure 39 3645 Appendix C. Structured vs. Unstructured Addresses 3647 The entity (Section 5.1) object class uses jCard [RFC7095] to 3648 represent contact information, including postal addresses. jCard has 3649 the ability to represent multiple language preferences, multiple 3650 email address and phone numbers, and multiple postal addresses in 3651 both a structured and unstructured format. This section describes 3652 the use of jCard for representing structured and unstructured 3653 addresses. 3655 The following is an example of a jCard. 3657 { 3658 "vcardArray":[ 3659 "vcard", 3660 [ 3661 ["version", {}, "text", "4.0"], 3662 ["fn", {}, "text", "Joe User"], 3663 ["n", {}, "text", 3664 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 3665 ], 3666 ["kind", {}, "text", "individual"], 3667 ["lang", { 3668 "pref":"1" 3669 }, "language-tag", "fr"], 3670 ["lang", { 3671 "pref":"2" 3672 }, "language-tag", "en"], 3673 ["org", { 3674 "type":"work" 3675 }, "text", "Example"], 3676 ["title", {}, "text", "Research Scientist"], 3677 ["role", {}, "text", "Project Lead"], 3678 ["adr", 3679 { "type":"work" }, 3680 "text", 3681 [ 3682 "", 3683 "Suite 1234", 3684 "4321 Rue Somewhere", 3685 "Quebec", 3686 "QC", 3687 "G1V 2M2", 3688 "Canada" 3689 ] 3690 ], 3691 ["adr", 3692 { 3693 "type":"home", 3694 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 3695 }, 3696 "text", 3697 [ 3698 "", "", "", "", "", "", "" 3699 ] 3700 ], 3701 ["tel", 3702 { "type":["work", "voice"], "pref":"1" }, 3703 "uri", "tel:+1-555-555-1234;ext=102" 3704 ], 3705 ["tel", 3706 { 3707 "type":["work", "cell", "voice", "video", "text"] 3708 }, 3709 "uri", 3710 "tel:+1-555-555-1234" 3711 ], 3712 ["email", 3713 { "type":"work" }, 3714 "text", "joe.user@example.com" 3715 ], 3716 ["geo", { 3717 "type":"work" 3718 }, "uri", "geo:46.772673,-71.282945"], 3719 ["key", 3720 { "type":"work" }, 3721 "uri", "https://www.example.com/joe.user/joe.asc" 3722 ], 3723 ["tz", {}, 3724 "utc-offset", "-05:00"], 3725 ["url", { "type":"home" }, 3726 "uri", "https://example.org"] 3727 ] 3728 ] 3729 } 3731 Figure 40 3733 The arrays in Figure 40 with the first member of "adr" represent 3734 postal addresses. In the first example, the postal address is given 3735 as an array of strings and constitutes a structured address. For 3736 components of the structured address that are not applicable, an 3737 empty string is given. Each member of that array aligns with the 3738 positions of a vCard as given in [RFC6350]. In this example, the 3739 following data corresponds to the following positional meanings: 3741 1. post office box -- not applicable; empty string 3743 2. extended address (e.g., apartment or suite number) -- Suite 1234 3745 3. street address -- 4321 Rue Somewhere 3747 4. locality (e.g., city) -- Quebec 3749 5. region (e.g., state or province) -- QC 3751 6. postal code -- G1V 2M2 3753 7. country name (full name) -- Canada 3755 The second example is an unstructured address. It uses the "label" 3756 attribute, which is a string containing a newline (\n) character to 3757 separate address components in an unordered, unspecified manner. 3758 Note that in this example, the structured address array is still 3759 given but that each string is an empty string. 3761 Appendix D. Secure DNS 3763 Section 5.3 defines the "secureDNS" member to represent secure DNS 3764 information about domain names. 3766 DNSSEC provides data integrity for DNS through the digital signing of 3767 resource records. To enable DNSSEC, the zone is signed by one or 3768 more private keys and the signatures are stored as RRSIG records. To 3769 complete the chain of trust in the DNS zone hierarchy, a digest of 3770 each DNSKEY record (which contains the public key) must be loaded 3771 into the parent zone, stored as DS records, and signed by the 3772 parent's private key (RRSIG DS record), as indicated in "Resource 3773 Records for the DNS Security Extensions" [RFC4034]. Creating the DS 3774 records in the parent zone can be done by the registration authority 3775 "Domain Name System (DNS) Security Extensions Mapping for the 3776 Extensible Provisioning Protocol (EPP)" [RFC5910]. 3778 Only DS-related information is provided by RDAP, since other 3779 information is not generally stored in the registration database. 3780 Other DNSSEC-related information can be retrieved with other DNS 3781 tools such as dig. 3783 The domain object class (Section 5.3) can represent this information 3784 using either the "dsData" or "keyData" object arrays. Client 3785 implementers should be aware that some registries do not collect or 3786 do not publish all of the secure DNS meta-information. 3788 Appendix E. Motivations for Using JSON 3790 This section addresses a common question regarding the use of JSON 3791 over other data formats, most notably XML. 3793 It is often pointed out that many DNRs and one RIR support the EPP 3794 [RFC5730] standard, which is an XML serialized protocol. The logic 3795 is that since EPP is a common protocol in the industry, it follows 3796 that XML would be a more natural choice. While EPP does influence 3797 this specification quite a bit, EPP serves a different purpose, which 3798 is the provisioning of Internet resources between registries and 3799 accredited registrars and serving a much narrower audience than that 3800 envisioned for RDAP. 3802 By contrast, RDAP has a broader audience and is designed for public 3803 consumption of data. Experience from RIRs with first generation 3804 RESTful web services for WHOIS indicate that a large percentage of 3805 clients operate within browsers and other platforms where full-blown 3806 XML stacks are not readily available and where JSON is a better fit. 3808 Additionally, while EPP is used in much of the DNR community it is 3809 not a universal constant in that industry. And finally, EPP's use of 3810 XML predates the specification of JSON. If EPP had been defined 3811 today, it may very well have used JSON instead of XML. 3813 Beyond the specific DNR and RIR communities, the trend in the broader 3814 Internet industry is also switching to JSON over XML, especially in 3815 the area of RESTful web services (see [JSON_ascendancy]). Studies 3816 have also found that JSON is generally less bulky and consequently 3817 faster to parse (see [JSON_performance_study]). 3819 Acknowledgments 3821 This document is derived from original work on RIR responses in JSON 3822 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew 3823 L. Newton. Additionally, this document incorporates work on DNR 3824 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 3825 Shen. 3827 The components of the DNR object classes are derived from a 3828 categorization of WHOIS response formats created by Ning Kong, Linlin 3829 Zhou, Guangqing Deng, Steve Sheng, Francisco Arias, Ray Bellis, and 3830 Frederico Neves. 3832 Tom Harrison, Murray Kucherawy, Ed Lewis, Audric Schiltknecht, Naoki 3833 Kambe, Maarten Bosteels, Mario Loffredo, and Jasdip Singh contributed 3834 significant review comments and provided clarifying text. James 3835 Mitchell provided text regarding the processing of unknown JSON 3836 attributes and identified issues leading to the remodeling of events. 3837 Ernie Dainow and Francisco Obispo provided concrete suggestions that 3838 led to a better variant model for domain names. 3840 Ernie Dainow provided the background information on the secure DNS 3841 attributes and objects for domains, informative text on DNSSEC, and 3842 many other attributes that appear throughout the object classes of 3843 this document. 3845 The switch to and incorporation of jCard was performed by Simon 3846 Perreault. 3848 Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working 3849 group from which this document was originally created. James Galvin 3850 and Antoin Verschuren chaired the REGEXT working group that worked on 3851 the -bis version. 3853 Changes from RFC 7483 3855 00: Initial version ported from RFC 7483. Addressed known errata. 3856 Added Implementation Status section. 3858 01: Updated references to 7482 to 7482bis Internet-Draft. Updated 3859 "Change Log" to "Changes from RFC 7483". Added APNIC 3860 implementation status. Adjusted case of "xxxx" used in examples 3861 where "XXXX" was previously used, and removed an "X" from "XXXXX". 3862 Changed IPv6 address example using "C00" to "c00". Added "a 3863 string representing" to the definitions of startAddress and 3864 endAddress. Removed "entity" from "Autonomous System Number 3865 Entity Object Class". Added "an unsigned 32-bit integer" to the 3866 definition of startAutnum and endAutnum. Added "a string 3867 representing" to the definition of name in the IP network and ASN 3868 object classes. Clarified rdapConformance identifier registration 3869 expectations in Section 4.1. Changed "lunarNic_level_0" to 3870 "lunarNIC_level_0". Clarified that the "value", "rel" and "href" 3871 JSON values MUST be specified in the "links" array. Clarified 3872 that the "description" array is required in the Notices and 3873 Remarks data structures and other values are OPTIONAL. Noted that 3874 all members of the "events" and "Public IDs" arrays are REQUIRED. 3875 Fix "self" link values in examples. Changed "http" to "https" 3876 link values in examples. Noted that Figure 18 is an example of a 3877 nameserver object with all "appropriate" values given. In 3878 appendix C, quoted the word "label" in "label attribute". Added 3879 reference to "status" definition in the descriptions for IP 3880 networks and autnums. Fixed a 404 for the informative reference 3881 to "The Stealthy Ascendancy of JSON". Added "boolean" to the 3882 definition of zoneSigned. Clarified REQUIRED and OPTIONAL members 3883 of the "events" array. Changed "SHOULD not" to "SHOULD NOT" in 3884 Section 5. Updated normative references (5226-8126, 5988-8288, 3885 7159-8259). Changed examples using "ns1.xn--fo-5ja.example" to 3886 split URLs to avoid long lines. 3888 00: Initial working group version. Added acknowledgments. 3890 01: Changed "The "lang" attribute may appear anywhere in an object 3891 class or data structure except for in jCard objects" to "The 3892 "lang" attribute as defined in this section MAY appear anywhere in 3893 an object class or data structure, except for in jCard objects. 3894 jCard supports similar functionality by way of the LANGUAGE 3895 property parameter (see Section 5.1 of RFC 6350 [RFC6350]". 3896 Changed "simple data types conveyed in JSON strings" to "simple 3897 data types conveyed in JSON primitive types (strings, numbers, 3898 booleans, and null)". Changed "In other words, servers are free 3899 to not include JSON members containing registration data based on 3900 their own policies" to "In other words, servers are free to omit 3901 unrequired/optional JSON members containing registration data 3902 based on their own policies". Changed "This data structure 3903 appears only in the topmost JSON object of a response" to "This 3904 data structure MUST appear in the topmost JSON object of a 3905 response". Changed "Some non-answer responses may return entity 3906 bodies with information that could be more descriptive" to "Some 3907 non-answer responses MAY return entity bodies with information 3908 that could be more descriptive". Changed "The basic structure of 3909 that response is an object class containing an error code number 3910 (corresponding to the HTTP response code) followed by a string 3911 named "title" and an array of strings named "description"" to "The 3912 basic structure of that response is an object class containing a 3913 REQUIRED error code number (corresponding to the HTTP response 3914 code) followed by an OPTIONAL string named "title" and an OPTIONAL 3915 array of strings named "description"". Changed the "Autonomous 3916 System Number Object Class" section title to "The Autonomous 3917 System Number Object Class" for consistency with other section 3918 titles. Removed trailing periods in the "Terminology and 3919 Definitions" section for consistency. Changed instances of 3920 "lunarNic" to "lunarNIC" for consistency. Removed an extraneous 3921 trailing period after the eventDate description. Changed a "." to 3922 ";" in the description of the "network" member of the domain 3923 object class. Changed "The high-level structure of the autnum 3924 object class consists of information about the network 3925 registration" to "The high-level structure of the autnum object 3926 class consists of information about the autonomous system number 3927 registration". Changed "registry unique" to "registry-unique". 3929 02: Changed "registrant" to "registrar" in the description of the 3930 "transfer" event action to address erratum 6158. Added IANA 3931 instructions to correct the description of the value in the 3932 registry. Added text to Section 4.2 to note that "self" and 3933 "related" "href" URIs MUST NOT be the same. Added text to 3934 Section 4.2 to describe return of IDNs in LDH name format. 3936 03: Added text to note that the "fn" member of a contact object MAY 3937 be empty in Section 3. 3939 Authors' Addresses 3941 Scott Hollenbeck 3942 Verisign Labs 3943 12061 Bluemont Way 3944 Reston, VA 20190 3945 United States 3947 Email: shollenbeck@verisign.com 3948 URI: https://www.verisignlabs.com/ 3950 Andy Newton 3951 Amazon Web Services, Inc. 3952 13200 Woodland Park Road 3953 Herndon, VA 20171 3954 United States of America 3956 Email: andy@hxr.us