idnits 2.17.1 draft-hollenbeck-regext-rfc7483bis-01.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 referencce 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 (8 May 2020) is 1448 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 (-06) exists of draft-hollenbeck-regext-rfc7482bis-05 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). 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: 9 November 2020 AWS 6 8 May 2020 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-hollenbeck-regext-rfc7483bis-01 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 9 November 2020. 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. 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 . . . . . . . . . . . 51 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 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 82 112 Changes from RFC 7483 . . . . . . . . . . . . . . . . . . . . . . 83 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84 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.hollenbeck-regext-rfc7482bis]. A communication protocol 120 for 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 147 RIR: Regional Internet Registry 149 1.2. Data Model 151 The data model for JSON responses is specified in five sections: 153 1. simple data types conveyed in JSON strings 155 2. data structures specified as JSON arrays or objects that are used 156 repeatedly when building up larger objects 158 3. object classes representing structured data corresponding to a 159 lookup of a single object 161 4. arrays of objects representing structured data corresponding to a 162 search for multiple objects 164 5. the response to an error 166 The object classes represent responses for two major categories of 167 data: responses returned by RIRs for registration data related to IP 168 addresses, reverse DNS names, and Autonomous System numbers and 169 responses returned by DNRs for registration data related to forward 170 DNS names. The following object classes are returned by both RIRs 171 and DNRs: 173 1. domains 175 2. nameservers 177 3. entities 179 The information served by both RIRs and DNRs for these object classes 180 overlap extensively and are given in this document as a unified model 181 for both classes of service. 183 In addition to the object classes listed above, RIRs also serve the 184 following object classes: 186 1. IP networks 188 2. Autonomous System numbers 189 Object classes defined in this document represent a minimal set of 190 what a compliant client/server needs to understand to function 191 correctly; however, some deployments may want to include additional 192 object classes to suit individual needs. Anticipating this need for 193 extension, Section 2.1 of this document defines a mechanism for 194 extending the JSON objects that are described in this document. 196 Positive responses take two forms. A response to a lookup of a 197 single object in the registration system yields a JSON object, which 198 is the subject of the lookup. A response to a search for multiple 199 objects yields a JSON object that contains an array of JSON objects 200 that are the subject of the search. In each type of response, other 201 data structures are present within the topmost JSON object. 203 2. Use of JSON 205 2.1. Naming 207 Clients of these JSON responses SHOULD ignore unrecognized JSON 208 members in responses. Servers can insert members into the JSON 209 responses, which are not specified in this document, but that does 210 not constitute an error in the response. Servers that insert such 211 unspecified members into JSON responses SHOULD have member names 212 prefixed with a short identifier followed by an underscore followed 213 by a meaningful name. It has been observed that these short 214 identifiers aid software implementers with identifying the 215 specification of the JSON member, and failure to use one could cause 216 an implementer to assume the server is erroneously using a name from 217 this specification. This allowance does not apply to jCard [RFC7095] 218 objects. The full JSON name (the prefix plus the underscore plus the 219 meaningful name) SHOULD adhere to the character and name limitations 220 of the prefix registry described in [RFC7480]. Failure to use these 221 limitations could result in slower adoption as these limitations have 222 been observed to aid some client programming models. 224 Consider the following JSON response with JSON members, all of which 225 are specified in this document. 227 { 228 "handle" : "ABC123", 229 "remarks" : 230 [ 231 { 232 "description" : 233 [ 234 "She sells sea shells down by the sea shore.", 235 "Originally written by Terry Sullivan." 236 ] 237 } 238 ] 239 } 241 Figure 1 243 If The Registry of the Moon desires to express information not found 244 in this specification, it might select "lunarNic" as its identifying 245 prefix and insert, as an example, the member named 246 "lunarNic_beforeOneSmallStep" to signify registrations occurring 247 before the first moon landing and the member named 248 "lunarNic_harshMistressNotes" that contains other descriptive text. 250 Consider the following JSON response with JSON names, some of which 251 should be ignored by clients without knowledge of their meaning. 253 { 254 "handle" : "ABC123", 255 "lunarNic_beforeOneSmallStep" : "TRUE THAT!", 256 "remarks" : 257 [ 258 { 259 "description" : 260 [ 261 "She sells sea shells down by the sea shore.", 262 "Originally written by Terry Sullivan." 263 ] 264 } 265 ], 266 "lunarNic_harshMistressNotes" : 267 [ 268 "In space,", 269 "nobody can hear you scream." 270 ] 271 } 273 Figure 2 275 Insertion of unrecognized members ignored by clients may also be used 276 for future revisions to this specification. 278 Clients processing JSON responses need to be prepared for members 279 representing registration data specified in this document to be 280 absent from a response. In other words, servers are free to not 281 include JSON members containing registration data based on their own 282 policies. 284 Finally, all JSON names specified in this document are case 285 sensitive. Both servers and clients MUST transmit and process them 286 using the specified character case. 288 3. Common Data Types 290 JSON [RFC8259] defines the data types of a number, character string, 291 boolean, array, object, and null. This section describes the 292 semantics and/or syntax reference for common, JSON character strings 293 used in this document. 295 handle: DNRs and RIRs have registry-unique identifiers that 296 may be used to specifically reference an object 297 instance. The semantics of this data type as found 298 in this document are to be a registry-unique 299 reference to the closest enclosing object where the 300 value is found. The data type names "registryId", 301 "roid", "nic-handle", "registrationNo", etc., are 302 terms often synonymous with this data type. In 303 this document, the term "handle" is used. The term 304 exposed to users by clients is a presentation issue 305 beyond the scope of this document. This value is a 306 simple string. 308 IPv4 addresses: The representation of IPv4 addresses in this 310 document uses the dotted-decimal notation. An 311 example of this textual representation is 312 "192.0.2.0". 314 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 322 country is needed, these identities are represented 323 with the alpha-2 or two-character country code 324 designation as defined in [ISO.3166.1988]. The 325 alpha-2 representation is used because it is freely 326 available, whereas the alpha-3 and numeric-3 327 standards are not. 329 LDH names: Textual representations of DNS names where the 331 labels of the domain are all "letters, digits, 332 hyphen" labels as described by [RFC5890]. Trailing 333 periods are optional. 335 Unicode names: Textual representations of DNS names where one or 337 more of the labels are U-labels as described by 338 [RFC5890]. Trailing periods are optional. 340 dates and times: The syntax for values denoting dates and times is 342 defined in [RFC3339]. 344 URIs: The syntax for values denoting a Uniform Resource 346 Identifier (URI) is defined by [RFC3986]. 348 Contact information is defined using jCards as described in 349 [RFC7095]. 351 4. Common Data Structures 353 This section defines common data structures used in responses and 354 object classes. 356 4.1. RDAP Conformance 358 The data structure named "rdapConformance" is an array of strings, 359 each providing a hint as to the specifications used in the 360 construction of the response. This data structure appears only in 361 the topmost JSON object of a response. 363 An example rdapConformance data structure: 365 "rdapConformance" : 366 [ 367 "rdap_level_0" 368 ] 370 Figure 3 372 The string literal "rdap_level_0" signifies conformance with this 373 specification. When custom JSON values are inserted into responses, 374 conformance to those custom specifications MUST be indicated by 375 including a unique string literal value registered in the IANA RDAP 376 Extensions registry specified in [RFC7480]. For example, if the 377 fictional Registry of the Moon wants to signify that their JSON 378 responses are conformant with their registered extensions, the string 379 used might be "lunarNIC_level_0". These registered values aid the 380 identification of specifications for software implementers, and 381 failure to use them could result in slower adoption of extensions. 383 Example rdapConformance structure with custom extensions noted: 385 "rdapConformance" : 386 [ 387 "rdap_level_0", 388 "lunarNIC_level_0" 389 ] 391 Figure 4 393 4.2. Links 395 The "links" array is found in data structures to signify links to 396 other resources on the Internet. The relationship of these links is 397 defined by the IANA registry described by [RFC8288]. 399 The following is an example of the link structure: 401 { 402 "value" : "https://example.com/context_uri", 403 "rel" : "self", 404 "href" : "https://example.com/target_uri", 405 "hreflang" : [ "en", "ch" ], 406 "title" : "title", 407 "media" : "screen", 408 "type" : "application/json" 409 } 411 Figure 5 413 The JSON name/values of "rel", "href", "hreflang", "title", "media", 414 and "type" correspond to values found in Section 3 of [RFC8288]. The 415 "value" JSON value is the context URI as described by [RFC8288]. The 416 "value", "rel" and "href" JSON values MUST be specified. All other 417 JSON values are OPTIONAL. 419 This is an example of the "links" array as it might be found in an 420 object class: 422 "links" : 423 [ 424 { 425 "value" : "https://example.com/ip/2001:db8::123", 426 "rel" : "self", 427 "href" : "https://example.com/ip/2001:db8::123", 428 "type" : "application/rdap+json" 429 }, 430 { 431 "value" : "https://example.com/ip/2001:db8::123", 432 "rel" : "up", 433 "href" : "https://example.com/ip/2001:db8::/48", 434 "type" : "application/rdap+json" 435 } 437 ] 439 Figure 6 441 4.3. Notices and Remarks 443 The "notices" and "remarks" data structures take the same form. The 444 notices structure denotes information about the service providing 445 RDAP information and/or information about the entire response, 446 whereas the remarks structure denotes information about the object 447 class that contains it (see Section 5 regarding object classes). 449 Both are arrays of objects. Each object contains a "title" string 450 representing the title of the object, a "type" string denoting a 451 registered type of remark or notice (see Section 10.2.1), an array of 452 strings named "description" for the purposes of conveying any 453 descriptive text, and a "links" array as described in Section 4.2. 454 The "description" array MUST be included. All other JSON values are 455 OPTIONAL. 457 An example of the notices data structure: 459 "notices" : 460 [ 461 { 462 "title" : "Terms of Use", 463 "description" : 464 [ 465 "Service subject to The Registry of the Moon's TOS.", 466 "Copyright (c) 2020 LunarNIC" 467 ], 468 "links" : 469 [ 470 { 471 "value" : "https://example.net/entity/XXXX", 472 "rel" : "alternate", 473 "type" : "text/html", 474 "href" : "https://www.example.com/terms_of_use.html" 475 } 476 ] 477 } 478 ] 480 Figure 7 482 It is the job of the clients to determine line breaks, spacing, and 483 display issues for sentences within the character strings of the 484 "description" array. Each string in the "description" array contains 485 a single complete division of human-readable text indicating to 486 clients where there are semantic breaks. 488 An example of the remarks data structure: 490 "remarks" : 491 [ 492 { 493 "description" : 494 [ 495 "She sells sea shells down by the sea shore.", 496 "Originally written by Terry Sullivan." 497 ] 498 } 499 ] 501 Figure 8 503 Note that objects in the "remarks" array may also have a "links" 504 array. 506 While the "title" and "description" fields are intended primarily for 507 human consumption, the "type" string contains a well-known value to 508 be registered with IANA (see Section 10.2.1) for programmatic use. 510 An example of the remarks data structure: 512 "remarks" : 513 [ 514 { 515 "type" : "object truncated due to authorization", 516 "description" : 517 [ 518 "Some registration data may not have been given.", 519 "Use proper authorization credentials to see all of it." 520 ] 521 } 522 ] 524 Figure 9 526 While the "remarks" array will appear in many object classes in a 527 response, the "notices" array appears only in the topmost object of a 528 response. 530 4.4. Language Identifier 532 This data structure consists solely of a name/value pair, where the 533 name is "lang" and the value is a string containing a language 534 identifier as described in [RFC5646]. 536 "lang" : "mn-Cyrl-MN" 538 Figure 10 540 The "lang" attribute may appear anywhere in an object class or data 541 structure except for in jCard objects. 543 4.5. Events 545 This data structure represents events that have occurred on an 546 instance of an object class (see Section 5 regarding object classes). 548 This is an example of an "events" array. 550 "events" : 551 [ 552 { 553 "eventAction" : "registration", 554 "eventActor" : "SOMEID-LUNARNIC", 555 "eventDate" : "1990-12-31T23:59:59Z" 556 }, 557 { 558 "eventAction" : "last changed", 559 "eventActor" : "OTHERID-LUNARNIC", 560 "eventDate" : "1991-12-31T23:59:59Z" 561 } 562 ] 564 Figure 11 566 The "events" array consists of objects, each with the following 567 members: 569 * "eventAction" -- a REQUIRED string denoting the reason for the 570 event 572 * "eventActor" -- an OPTIONAL identifier denoting the actor 573 responsible for the event 575 * "eventDate" -- a REQUIRED string containing the time and date the 576 event occurred. 578 * "links" -- OPTIONAL; see Section 4.2 580 Events can be future dated. One use case for future dating of events 581 is to denote when an object expires from a registry. 583 The "links" array in this data structure is provided for references 584 to the event actor. In order to reference an RDAP entity, a "rel" of 585 "related" and a "type" of "application/rdap+json" is used in the link 586 reference. 588 See Section 10.2.3 for a list of values for the "eventAction" string. 589 See Appendix B regarding the various ways events can be modeled. 591 4.6. Status 593 This data structure, named "status", is an array of strings 594 indicating the state of a registered object (see Section 10.2.2 for a 595 list of values). 597 4.7. Port 43 WHOIS Server 599 This data structure, a member named "port43", is a simple string 600 containing the fully qualified host name or IP address of the WHOIS 601 [RFC3912] server where the containing object instance may be found. 602 Note that this is not a URI, as there is no WHOIS URI scheme. 604 4.8. Public IDs 606 This data structure maps a public identifier to an object class. It 607 is named "publicIds" and is an array of objects, with each object 608 containing the following REQUIRED members: 610 * type -- a string denoting the type of public identifier 612 * identifier -- a string denoting a public identifier of the type 613 related to "type" 615 The following is an example of a publicIds structure. 617 "publicIds": 618 [ 619 { 620 "type":"IANA Registrar ID", 621 "identifier":"1" 622 } 623 ] 625 Figure 12 627 4.9. Object Class Name 629 This data structure, a member named "objectClassName", gives the 630 object class name of a particular object as a string. This 631 identifies the type of object being processed. An objectClassName is 632 REQUIRED in all RDAP response objects so that the type of the object 633 can be interpreted. 635 4.10. An Example 637 This is an example response with both rdapConformance and notices 638 embedded: 640 { 641 "rdapConformance" : 642 [ 643 "rdap_level_0" 644 ], 645 "notices" : 646 [ 647 { 648 "title" : "Content Removed", 649 "description" : 650 [ 651 "Without full authorization, content has been removed.", 652 "Sorry, dude!" 653 ], 654 "links" : 655 [ 656 { 657 "value" : "https://example.net/ip/192.0.2.0/24", 658 "rel" : "alternate", 659 "type" : "text/html", 660 "href" : "https://www.example.com/redaction_policy.html" 661 } 662 ] 663 } 664 ], 665 "lang" : "en", 666 "objectClassName" : "ip network", 667 "startAddress" : "192.0.2.0", 668 "endAddress" : "192.0.2.255", 669 "handle" : "XXXX-RIR", 670 "ipVersion" : "v4", 671 "name": "NET-RTR-1", 672 "parentHandle" : "YYYY-RIR", 673 "remarks" : 674 [ 676 { 677 "description" : 678 [ 679 "She sells sea shells down by the sea shore.", 680 "Originally written by Terry Sullivan." 681 ] 682 } 683 ] 684 } 686 Figure 13 688 5. Object Classes 690 Object classes represent structures appropriate for a response from 691 the queries specified in [I-D.hollenbeck-regext-rfc7482bis]. 693 Each object class contains a "links" array as specified in 694 Section 4.2. For every object class instance in a response, whether 695 the object class instance is directly representing the response to a 696 query or is embedded in other object class instances or is an item in 697 a search result set, servers SHOULD provide a link representing a URI 698 for that object class instance using the "self" relationship as 699 described in the IANA registry specified by [RFC8288]. As explained 700 in Section 5.2, this may be not always be possible for nameserver 701 data. Clients MUST be able to process object instances without a 702 self link. When present, clients can use the self link for caching 703 data. Servers MAY provide more than one self link for any given 704 object instance. Failure to provide any self link by a server may 705 result in clients being unable to cache object class instances. 707 Clients using self links for caching SHOULD NOT cache any object 708 class instances where the authority of the self link is different 709 than the authority of the server returning the data. Failing to do 710 so might result in cache poisoning. 712 Self links MUST contain a "type" element containing the "application/ 713 rdap+json" media type when referencing RDAP object instances as 714 defined by this document. 716 This is an example of the "links" array with a self link to an object 717 class: 719 "links" : 720 [ 721 { 722 "value" : "https://example.com/ip/2001:db8::123", 723 "rel" : "self", 724 "href" : "https://example.com/ip/2001:db8::123", 725 "type" : "application/rdap+json" 726 } 727 ] 729 Figure 14 731 5.1. The Entity Object Class 733 The entity object class appears throughout this document and is an 734 appropriate response for the /entity/XXXX query defined in 735 "Registration Data Access Protocol (RDAP) Query Format" 736 [I-D.hollenbeck-regext-rfc7482bis]. This object class represents the 737 information of organizations, corporations, governments, non-profits, 738 clubs, individual persons, and informal groups of people. All of 739 these representations are so similar that it is best to represent 740 them in JSON [RFC8259] with one construct, the entity object class, 741 to aid in the reuse of code by implementers. 743 The entity object class uses jCard [RFC7095] to represent contact 744 information, such as postal addresses, email addresses, phone numbers 745 and names of organizations and individuals. Many of the types of 746 information that can be represented with jCard have no use in RDAP, 747 such as birthdays, anniversaries, and gender. 749 The entity object is served by both RIRs and DNRs. The following is 750 an example of an entity that might be served by an RIR. 752 { 753 "objectClassName" : "entity", 754 "handle":"XXXX", 755 "vcardArray":[ 756 "vcard", 757 [ 758 ["version", {}, "text", "4.0"], 759 ["fn", {}, "text", "Joe User"], 760 ["n", {}, "text", 761 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 762 ], 763 ["kind", {}, "text", "individual"], 764 ["lang", { 765 "pref":"1" 766 }, "language-tag", "fr"], 767 ["lang", { 768 "pref":"2" 769 }, "language-tag", "en"], 770 ["org", { 771 "type":"work" 772 }, "text", "Example"], 773 ["title", {}, "text", "Research Scientist"], 774 ["role", {}, "text", "Project Lead"], 775 ["adr", 776 { "type":"work" }, 777 "text", 778 [ 779 "", 780 "Suite 1234", 781 "4321 Rue Somewhere", 782 "Quebec", 783 "QC", 784 "G1V 2M2", 785 "Canada" 786 ] 787 ], 788 ["adr", 789 { 790 "type":"home", 791 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 792 }, 793 "text", 794 [ 795 "", "", "", "", "", "", "" 796 ] 797 ], 798 ["tel", 799 { 800 "type":["work", "voice"], 801 "pref":"1" 802 }, 803 "uri", 804 "tel:+1-555-555-1234;ext=102" 805 ], 806 ["tel", 807 { "type":["work", "cell", "voice", "video", "text"] }, 808 "uri", 809 "tel:+1-555-555-4321" 810 ], 811 ["email", 812 { "type":"work" }, 813 "text", 814 "joe.user@example.com" 815 ], 816 ["geo", { 817 "type":"work" 818 }, "uri", "geo:46.772673,-71.282945"], 819 ["key", 820 { "type":"work" }, 821 "uri", 822 "https://www.example.com/joe.user/joe.asc" 823 ], 824 ["tz", {}, 825 "utc-offset", "-05:00"], 826 ["url", { "type":"home" }, 827 "uri", "https://example.org"] 828 ] 829 ], 830 "roles":[ "registrar" ], 831 "publicIds":[ 832 { 833 "type":"IANA Registrar ID", 834 "identifier":"1" 835 } 836 ], 837 "remarks":[ 838 { 839 "description":[ 840 "She sells sea shells down by the sea shore.", 841 "Originally written by Terry Sullivan." 842 ] 843 } 844 ], 845 "links":[ 846 { 847 "value":"https://example.com/entity/XXXX", 848 "rel":"self", 849 "href":"https://example.com/entity/XXXX", 850 "type" : "application/rdap+json" 851 } 852 ], 853 "events":[ 854 { 855 "eventAction":"registration", 856 "eventDate":"1990-12-31T23:59:59Z" 857 } 858 ], 859 "asEventActor":[ 861 { 862 "eventAction":"last changed", 863 "eventDate":"1991-12-31T23:59:59Z" 864 } 865 ] 866 } 868 Figure 15 870 The entity object class can contain the following members: 872 * objectClassName -- the string "entity" 873 * handle -- a string representing a registry unique identifier of 874 the entity 876 * vcardArray -- a jCard with the entity's contact information 878 * roles -- an array of strings, each signifying the relationship an 879 object would have with its closest containing object (see 880 Section 10.2.4 for a list of values) 882 * publicIds -- see Section 4.8 884 * entities -- an array of entity objects as defined by this section 886 * remarks -- see Section 4.3 888 * links -- see Section 4.2 890 * events -- see Section 4.5 892 * asEventActor -- this data structure takes the same form as the 893 events data structure (see Section 4.5), but each object in the 894 array MUST NOT have an "eventActor" member. These objects denote 895 that the entity is an event actor for the given events. See 896 Appendix B regarding the various ways events can be modeled. 898 * status -- see Section 4.6 900 * port43 -- see Section 4.7 902 * networks -- an array of IP network objects as defined in 903 Section 5.4 905 * autnums -- an array of autnum objects as defined in Section 5.5 907 Entities may also have other entities embedded with them in an array. 908 This can be used to model an organization with specific individuals 909 fulfilling designated roles of responsibility. 911 The following is an elided example of an entity with embedded 912 entities. 914 { 915 "objectClassName" : "entity", 916 "handle" : "ANENTITY", 917 "roles" : [ "registrar" ], 918 ... 919 "entities" : 920 [ 921 { 922 "objectClassName" : "entity", 923 "handle": "ANEMBEDDEDENTITY", 924 "roles" : [ "technical" ], 925 ... 926 }, 927 ... 928 ], 929 ... 930 } 932 Figure 16 934 The following is an example of an entity that might be served by a 935 DNR. 937 { 938 "objectClassName" : "entity", 939 "handle":"XXXX", 940 "vcardArray":[ 941 "vcard", 942 [ 943 ["version", {}, "text", "4.0"], 944 ["fn", {}, "text", "Joe User"], 945 ["kind", {}, "text", "individual"], 946 ["lang", { 947 "pref":"1" 948 }, "language-tag", "fr"], 949 ["lang", { 950 "pref":"2" 951 }, "language-tag", "en"], 952 ["org", { 953 "type":"work" 954 }, "text", "Example"], 955 ["title", {}, "text", "Research Scientist"], 956 ["role", {}, "text", "Project Lead"], 957 ["adr", 958 { "type":"work" }, 959 "text", 960 [ 961 "", 962 "Suite 1234", 963 "4321 Rue Somewhere", 964 "Quebec", 965 "QC", 966 "G1V 2M2", 967 "Canada" 968 ] 969 ], 970 ["tel", 971 { "type":["work", "voice"], "pref":"1" }, 972 "uri", "tel:+1-555-555-1234;ext=102" 973 ], 974 ["email", 975 { "type":"work" }, 976 "text", "joe.user@example.com" 977 ] 978 ] 979 ], 980 "status":[ "validated", "locked" ], 981 "remarks":[ 982 { 983 "description":[ 984 "She sells sea shells down by the sea shore.", 985 "Originally written by Terry Sullivan." 986 ] 987 } 988 ], 989 "links":[ 990 { 991 "value":"https://example.com/entity/XXXX", 992 "rel":"self", 993 "href":"https://example.com/entity/XXXX", 994 "type":"application/rdap+json" 995 } 996 ], 997 "port43":"whois.example.net", 998 "events":[ 999 { 1000 "eventAction":"registration", 1001 "eventDate":"1990-12-31T23:59:59Z" 1002 }, 1003 { 1004 "eventAction":"last changed", 1005 "eventDate":"1991-12-31T23:59:59Z", 1006 "eventActor":"joe@example.com" 1007 } 1008 ] 1009 } 1010 Figure 17 1012 See Appendix A for use of the entity object class to model various 1013 types of entities found in both RIRs and DNRs. See Appendix C 1014 regarding structured vs. unstructured postal addresses in entities. 1016 5.2. The Nameserver Object Class 1018 The nameserver object class represents information regarding DNS 1019 nameservers used in both forward and reverse DNS. RIRs and some DNRs 1020 register or expose nameserver information as an attribute of a domain 1021 name, while other DNRs model nameservers as "first class objects". 1023 The nameserver object class accommodates both models and degrees of 1024 variation in between. 1026 The following is an example of a nameserver object. 1028 { 1029 "objectClassName" : "nameserver", 1030 "handle" : "XXXX", 1031 "ldhName" : "ns1.xn--fo-5ja.example", 1032 "unicodeName" : "ns.fóo.example", 1033 "status" : [ "active" ], 1034 "ipAddresses" : 1035 { 1036 "v4": [ "192.0.2.1", "192.0.2.2" ], 1037 "v6": [ "2001:db8::123" ] 1038 }, 1039 "remarks" : 1040 [ 1041 { 1042 "description" : 1043 [ 1044 "She sells sea shells down by the sea shore.", 1045 "Originally written by Terry Sullivan." 1046 ] 1047 } 1048 ], 1049 "links" : 1050 [ 1051 { 1052 "value" : "https://example.net/nameserver/ 1053 ns1.xn--fo-5ja.example", 1054 "rel" : "self", 1055 "href" : "https://example.net/nameserver/ 1056 ns1.xn--fo-5ja.example", 1057 "type" : "application/rdap+json" 1058 } 1059 ], 1060 "port43" : "whois.example.net", 1061 "events" : 1062 [ 1063 { 1064 "eventAction" : "registration", 1065 "eventDate" : "1990-12-31T23:59:59Z" 1066 }, 1067 { 1068 "eventAction" : "last changed", 1069 "eventDate" : "1991-12-31T23:59:59Z", 1070 "eventActor" : "joe@example.com" 1071 } 1072 ] 1073 } 1075 Figure 18 1077 Figure 18 is an example of a nameserver object with all appropriate 1078 values given. Registries using a first-class nameserver data model 1079 would embed this in domain objects as well as allowing references to 1080 it with the "/nameserver" query type (all depending on the registry 1081 operators policy). Other registries may pare back the information as 1082 needed. Figure 19 is an example of a nameserver object as would be 1083 found in RIRs and some DNRs, while Figure 20 is an example of a 1084 nameserver object as would be found in other DNRs. 1086 The following is an example of the simplest nameserver object: 1088 { 1089 "objectClassName" : "nameserver", 1090 "ldhName" : "ns1.example.com" 1091 } 1093 Figure 19 1095 The following is an example of a simple nameserver object that might 1096 be commonly used by DNRs: 1098 { 1099 "objectClassName" : "nameserver", 1100 "ldhName" : "ns1.example.com", 1101 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 1102 } 1104 Figure 20 1106 As nameservers can be modeled by some registries to be first-class 1107 objects, they may also have an array of entities (Section 5.1) 1108 embedded to signify parties responsible for the maintenance, 1109 registrations, etc., of the nameservers. 1111 The following is an elided example of a nameserver with embedded 1112 entities. 1114 { 1115 "objectClassName" : "nameserver", 1116 "handle" : "XXXX", 1117 "ldhName" : "ns.xn--fo-5ja.example", 1118 ... 1119 "entities" : 1120 [ 1121 ... 1122 ], 1123 ... 1124 } 1125 Figure 21 1127 The nameserver object class can contain the following members: 1129 * objectClassName -- the string "nameserver" 1131 * handle -- a string representing a registry unique identifier of 1132 the nameserver 1134 * ldhName -- a string containing the LDH name of the nameserver (see 1135 Section 3) 1137 * unicodeName -- a string containing a DNS Unicode name of the 1138 nameserver (see Section 3) 1140 * ipAddresses -- an object containing the following members: 1142 - v6 -- an array of strings containing IPv6 addresses of the 1143 nameserver 1145 - v4 -- an array of strings containing IPv4 addresses of the 1146 nameserver 1148 * entities -- an array of entity objects as defined by Section 5.1 1150 * status -- see Section 4.6 1152 * remarks -- see Section 4.3 1154 * links -- see Section 4.2 1156 * port43 -- see Section 4.7 1158 * events -- see Section 4.5 1160 5.3. The Domain Object Class 1162 The domain object class represents a DNS name and point of 1163 delegation. For RIRs, these delegation points are in the reverse DNS 1164 tree, whereas for DNRs, these delegation points are in the forward 1165 DNS tree. 1167 In both cases, the high-level structure of the domain object class 1168 consists of information about the domain registration, nameserver 1169 information related to the domain name, and entities related to the 1170 domain name (e.g., registrant information, contacts, etc.). 1172 The following is an elided example of the domain object showing the 1173 high-level structure: 1175 { 1176 "objectClassName" : "domain", 1177 "handle" : "XXX", 1178 "ldhName" : "blah.example.com", 1179 ... 1180 "nameservers" : 1181 [ 1182 ... 1183 ], 1184 ... 1185 "entities" : 1186 [ 1187 ... 1188 ] 1189 } 1191 Figure 22 1193 The domain object class can contain the following members: 1195 * objectClassName -- the string "domain" 1197 * handle -- a string representing a registry unique identifier of 1198 the domain object instance 1200 * ldhName -- a string describing a domain name in LDH form as 1201 described in Section 3 1203 * unicodeName -- a string containing a domain name with U-labels as 1204 described in Section 3 1206 * variants -- an array of objects, each containing the following 1207 values: 1209 - relation -- an array of strings, with each string denoting the 1210 relationship between the variants and the containing domain 1211 object (see Section 10.2.5 for a list of suggested variant 1212 relations). 1214 - idnTable -- the name of the Internationalized Domain Name (IDN) 1215 table of codepoints, such as one listed with the IANA (see IDN 1216 tables [IANA_IDNTABLES]). 1218 - variantNames -- an array of objects, with each object 1219 containing an "ldhName" member and a "unicodeName" member (see 1220 Section 3). 1222 * nameservers -- an array of nameserver objects as defined by 1223 Section 5.2 1225 * secureDNS -- an object with the following members: 1227 - zoneSigned -- boolean true if the zone has been signed, false 1228 otherwise. 1230 - delegationSigned -- boolean true if there are DS records in the 1231 parent, false otherwise. 1233 - maxSigLife -- an integer representing the signature lifetime in 1234 seconds to be used when creating the RRSIG DS record in the 1235 parent zone [RFC5910]. 1237 - dsData -- an array of objects, each with the following members: 1239 o keyTag -- an integer as specified by the key tag field of a 1240 DNS DS record as specified by [RFC4034] in presentation 1241 format 1243 o algorithm -- an integer as specified by the algorithm field 1244 of a DNS DS record as described by RFC 4034 in presentation 1245 format 1247 o digest -- a string as specified by the digest field of a DNS 1248 DS record as specified by RFC 4034 in presentation format 1250 o digestType -- an integer as specified by the digest type 1251 field of a DNS DS record as specified by RFC 4034 in 1252 presentation format 1254 o events -- see Section 4.5 1256 o links -- see Section 4.2 1258 - keyData -- an array of objects, each with the following 1259 members: 1261 o flags -- an integer representing the flags field value in 1262 the DNSKEY record [RFC4034] in presentation format 1264 o protocol -- an integer representation of the protocol field 1265 value of the DNSKEY record [RFC4034] in presentation format 1267 o publicKey -- a string representation of the public key in 1268 the DNSKEY record [RFC4034] in presentation format 1270 o algorithm -- an integer as specified by the algorithm field 1271 of a DNSKEY record as specified by [RFC4034] in presentation 1272 format 1274 o events -- see Section 4.5 1276 o links -- see Section 4.2 1278 See Appendix D for background information on these 1279 objects. 1281 * entities -- an array of entity objects as defined by Section 5.1 1283 * status -- see Section 4.6 1285 * publicIds -- see Section 4.8 1287 * remarks -- see Section 4.3 1289 * links -- see Section 4.2 1291 * port43 -- see Section 4.7 1293 * events -- see Section 4.5 1295 * network -- represents the IP network for which a reverse DNS 1296 domain is referenced. See Section 5.4 1298 The following is an example of a JSON domain object representing a 1299 reverse DNS delegation point that might be served by an RIR. 1301 { 1302 "objectClassName" : "domain", 1303 "handle" : "XXXX", 1304 "ldhName" : "0.2.192.in-addr.arpa", 1305 "nameservers" : 1306 [ 1307 { 1308 "objectClassName" : "nameserver", 1309 "ldhName" : "ns1.rir.example" 1310 }, 1311 { 1312 "objectClassName" : "nameserver", 1313 "ldhName" : "ns2.rir.example" 1314 } 1316 ], 1317 "secureDNS": 1318 { 1319 "delegationSigned": true, 1320 "dsData": 1321 [ 1322 { 1323 "keyTag": 12345, 1324 "algorithm": 3, 1325 "digestType": 1, 1326 "digest": "49FD46E6C4B45C55D4AC" 1327 } 1328 ] 1329 }, 1330 "remarks" : 1331 [ 1332 { 1333 "description" : 1334 [ 1335 "She sells sea shells down by the sea shore.", 1336 "Originally written by Terry Sullivan." 1337 ] 1338 } 1339 ], 1340 "links" : 1341 [ 1342 { 1343 "value": "https://example.net/domain/0.2.192.in-addr.arpa", 1344 "rel" : "self", 1345 "href" : "https://example.net/domain/0.2.192.in-addr.arpa", 1346 "type" : "application/rdap+json" 1348 } 1349 ], 1350 "events" : 1351 [ 1352 { 1353 "eventAction" : "registration", 1354 "eventDate" : "1990-12-31T23:59:59Z" 1355 }, 1356 { 1357 "eventAction" : "last changed", 1358 "eventDate" : "1991-12-31T23:59:59Z", 1359 "eventActor" : "joe@example.com" 1360 } 1361 ], 1362 "entities" : 1363 [ 1364 { 1365 "objectClassName" : "entity", 1366 "handle" : "XXXX", 1367 "vcardArray":[ 1368 "vcard", 1369 [ 1370 ["version", {}, "text", "4.0"], 1371 ["fn", {}, "text", "Joe User"], 1372 ["kind", {}, "text", "individual"], 1373 ["lang", { 1374 "pref":"1" 1375 }, "language-tag", "fr"], 1376 ["lang", { 1377 "pref":"2" 1378 }, "language-tag", "en"], 1379 ["org", { 1380 "type":"work" 1381 }, "text", "Example"], 1382 ["title", {}, "text", "Research Scientist"], 1383 ["role", {}, "text", "Project Lead"], 1384 ["adr", 1385 { "type":"work" }, 1386 "text", 1387 [ 1388 "", 1389 "Suite 1234", 1390 "4321 Rue Somewhere", 1391 "Quebec", 1392 "QC", 1393 "G1V 2M2", 1394 "Canada" 1395 ] 1397 ], 1398 ["tel", 1399 { "type":["work", "voice"], "pref":"1" }, 1400 "uri", "tel:+1-555-555-1234;ext=102" 1401 ], 1402 ["email", 1403 { "type":"work" }, 1404 "text", "joe.user@example.com" 1405 ] 1406 ] 1407 ], 1408 "roles" : [ "registrant" ], 1409 "remarks" : 1410 [ 1411 { 1412 "description" : 1413 [ 1414 "She sells sea shells down by the sea shore.", 1415 "Originally written by Terry Sullivan." 1416 ] 1417 } 1418 ], 1419 "links" : 1420 [ 1421 { 1422 "value": "https://example.net/entity/XXXX", 1423 "rel" : "self", 1424 "href" : "https://example.net/entity/XXXX", 1425 "type" : "application/rdap+json" 1426 } 1427 ], 1428 "events" : 1429 [ 1430 { 1431 "eventAction" : "registration", 1432 "eventDate" : "1990-12-31T23:59:59Z" 1433 }, 1434 { 1435 "eventAction" : "last changed", 1436 "eventDate" : "1991-12-31T23:59:59Z", 1437 "eventActor" : "joe@example.com" 1438 } 1439 ] 1440 } 1441 ], 1442 "network" : 1443 { 1444 "objectClassName" : "ip network", 1445 "handle" : "XXXX-RIR", 1446 "startAddress" : "192.0.2.0", 1447 "endAddress" : "192.0.2.255", 1448 "ipVersion" : "v4", 1449 "name": "NET-RTR-1", 1450 "type" : "DIRECT ALLOCATION", 1451 "country" : "AU", 1452 "parentHandle" : "YYYY-RIR", 1453 "status" : [ "active" ] 1454 } 1455 } 1457 Figure 23 1459 The following is an example of a JSON domain object representing a 1460 forward DNS delegation point that might be served by a DNR. 1462 { 1463 "objectClassName" : "domain", 1464 "handle" : "XXXX", 1465 "ldhName" : "xn--fo-5ja.example", 1466 "unicodeName" : "fóo.example", 1467 "variants" : 1468 [ 1469 { 1470 "relation" : [ "registered", "conjoined" ], 1471 "variantNames" : 1472 [ 1473 { 1474 "ldhName" : "xn--fo-cka.example", 1475 "unicodeName" : "fõo.example" 1476 }, 1477 { 1478 "ldhName" : "xn--fo-fka.example", 1479 "unicodeName" : "föo.example" 1480 } 1481 ] 1482 }, 1483 { 1484 "relation" : [ "unregistered", "registration restricted" ], 1485 "idnTable": ".EXAMPLE Swedish", 1486 "variantNames" : 1487 [ 1488 { 1489 "ldhName": "xn--fo-8ja.example", 1490 "unicodeName" : "fôo.example" 1491 } 1492 ] 1494 } 1495 ], 1496 "status" : [ "locked", "transfer prohibited" ], 1497 "publicIds":[ 1498 { 1499 "type":"ENS_Auth ID", 1500 "identifier":"1234567890" 1501 } 1502 ], 1503 "nameservers" : 1504 [ 1505 { 1506 "objectClassName" : "nameserver", 1507 "handle" : "XXXX", 1508 "ldhName" : "ns1.example.com", 1509 "status" : [ "active" ], 1510 "ipAddresses" : 1511 { 1512 "v6": [ "2001:db8::123", "2001:db8::124" ], 1513 "v4": [ "192.0.2.1", "192.0.2.2" ] 1514 }, 1515 "remarks" : 1516 [ 1517 { 1518 "description" : 1519 [ 1520 "She sells sea shells down by the sea shore.", 1521 "Originally written by Terry Sullivan." 1522 ] 1523 } 1524 ], 1525 "links" : 1526 [ 1527 { 1528 "value" : "https://example.net/nameserver/ns1.example.com", 1529 "rel" : "self", 1530 "href" : "https://example.net/nameserver/ns1.example.com", 1531 "type" : "application/rdap+json" 1532 } 1533 ], 1534 "events" : 1535 [ 1536 { 1537 "eventAction" : "registration", 1538 "eventDate" : "1990-12-31T23:59:59Z" 1539 }, 1540 { 1541 "eventAction" : "last changed", 1542 "eventDate" : "1991-12-31T23:59:59Z" 1543 } 1544 ] 1545 }, 1546 { 1547 "objectClassName" : "nameserver", 1548 "handle" : "XXXX", 1549 "ldhName" : "ns2.example.com", 1550 "status" : [ "active" ], 1551 "ipAddresses" : 1552 { 1553 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1554 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1556 }, 1557 "remarks" : 1558 [ 1559 { 1560 "description" : 1561 [ 1562 "She sells sea shells down by the sea shore.", 1563 "Originally written by Terry Sullivan." 1564 ] 1565 } 1566 ], 1567 "links" : 1568 [ 1569 { 1570 "value" : "https://example.net/nameserver/ns2.example.com", 1571 "rel" : "self", 1572 "href" : "https://example.net/nameserver/ns2.example.com", 1573 "type" : "application/rdap+json" 1574 } 1575 ], 1576 "events" : 1577 [ 1578 { 1579 "eventAction" : "registration", 1580 "eventDate" : "1990-12-31T23:59:59Z" 1581 }, 1582 { 1583 "eventAction" : "last changed", 1584 "eventDate" : "1991-12-31T23:59:59Z" 1585 } 1586 ] 1587 } 1588 ], 1589 "secureDNS": 1590 { 1592 "zoneSigned": true, 1593 "delegationSigned": true, 1594 "maxSigLife": 604800, 1595 "keyData": 1596 [ 1597 { 1598 "flags": 257, 1599 "protocol": 3, 1600 "algorithm": 1, 1601 "publicKey": "AQPJ////4Q==", 1602 "events": 1603 [ 1604 { 1605 "eventAction": "last changed", 1606 "eventDate": "2012-07-23T05:15:47Z" 1607 } 1608 ] 1609 } 1610 ] 1611 }, 1612 "remarks" : 1613 [ 1614 { 1615 "description" : 1616 [ 1617 "She sells sea shells down by the sea shore.", 1618 "Originally written by Terry Sullivan." 1619 ] 1620 } 1621 ], 1622 "links" : 1623 [ 1624 { 1625 "value": "https://example.net/domain/xn--fo-5ja.example", 1626 "rel" : "self", 1627 "href" : "https://example.net/domain/xn--fo-5ja.example", 1628 "type" : "application/rdap+json" 1629 } 1630 ], 1631 "port43" : "whois.example.net", 1632 "events" : 1633 [ 1634 { 1635 "eventAction" : "registration", 1636 "eventDate" : "1990-12-31T23:59:59Z" 1637 }, 1638 { 1639 "eventAction" : "last changed", 1640 "eventDate" : "1991-12-31T23:59:59Z", 1641 "eventActor" : "joe@example.com" 1642 }, 1643 { 1644 "eventAction" : "transfer", 1645 "eventDate" : "1991-12-31T23:59:59Z", 1646 "eventActor" : "joe@example.com" 1647 }, 1648 { 1649 "eventAction" : "expiration", 1650 "eventDate" : "2016-12-31T23:59:59Z", 1651 "eventActor" : "joe@example.com" 1653 } 1654 ], 1655 "entities" : 1656 [ 1657 { 1658 "objectClassName" : "entity", 1659 "handle" : "XXXX", 1660 "vcardArray":[ 1661 "vcard", 1662 [ 1663 ["version", {}, "text", "4.0"], 1664 ["fn", {}, "text", "Joe User"], 1665 ["kind", {}, "text", "individual"], 1666 ["lang", { 1667 "pref":"1" 1668 }, "language-tag", "fr"], 1669 ["lang", { 1670 "pref":"2" 1671 }, "language-tag", "en"], 1672 ["org", { 1673 "type":"work" 1674 }, "text", "Example"], 1675 ["title", {}, "text", "Research Scientist"], 1676 ["role", {}, "text", "Project Lead"], 1677 ["adr", 1678 { "type":"work" }, 1679 "text", 1680 [ 1681 "", 1682 "Suite 1234", 1683 "4321 Rue Somewhere", 1684 "Quebec", 1685 "QC", 1686 "G1V 2M2", 1687 "Canada" 1688 ] 1690 ], 1691 ["tel", 1692 { "type":["work", "voice"], "pref":"1" }, 1693 "uri", "tel:+1-555-555-1234;ext=102" 1694 ], 1695 ["email", 1696 { "type":"work" }, 1697 "text", "joe.user@example.com" 1698 ] 1699 ] 1700 ], 1701 "status" : [ "validated", "locked" ], 1702 "roles" : [ "registrant" ], 1703 "remarks" : 1704 [ 1705 { 1706 "description" : 1707 [ 1708 "She sells sea shells down by the sea shore.", 1709 "Originally written by Terry Sullivan." 1710 ] 1711 } 1712 ], 1713 "links" : 1714 [ 1715 { 1716 "value" : "https://example.net/entity/XXXX", 1717 "rel" : "self", 1718 "href" : "https://example.net/entity/XXXX", 1719 "type" : "application/rdap+json" 1720 } 1721 ], 1722 "events" : 1723 [ 1724 { 1725 "eventAction" : "registration", 1726 "eventDate" : "1990-12-31T23:59:59Z" 1727 }, 1728 { 1729 "eventAction" : "last changed", 1730 "eventDate" : "1991-12-31T23:59:59Z" 1731 } 1732 ] 1733 } 1734 ] 1735 } 1737 Figure 24 1739 5.4. The IP Network Object Class 1741 The IP network object class models IP network registrations found in 1742 RIRs and is the expected response for the "/ip" query as defined by 1743 [I-D.hollenbeck-regext-rfc7482bis]. There is no equivalent object 1744 class for DNRs. The high- level structure of the IP network object 1745 class consists of information about the network registration and 1746 entities related to the IP network (e.g., registrant information, 1747 contacts, etc.). 1749 The following is an elided example of the IP network object type 1750 showing the high-level structure: 1752 { 1753 "objectClassName" : "ip network", 1754 "handle" : "XXX", 1755 ... 1756 "entities" : 1757 [ 1758 ... 1759 ] 1760 } 1762 Figure 25 1764 The following is an example of the JSON object for the network 1765 registration information. 1767 { 1768 "objectClassName" : "ip network", 1769 "handle" : "XXXX-RIR", 1770 "startAddress" : "2001:db8::", 1771 "endAddress" : "2001:db8:0:ffff:ffff:ffff:ffff:ffff", 1772 "ipVersion" : "v6", 1773 "name": "NET-RTR-1", 1774 "type" : "DIRECT ALLOCATION", 1775 "country" : "AU", 1776 "parentHandle" : "YYYY-RIR", 1777 "status" : [ "active" ], 1778 "remarks" : 1779 [ 1780 { 1781 "description" : 1782 [ 1783 "She sells sea shells down by the sea shore.", 1784 "Originally written by Terry Sullivan." 1785 ] 1786 } 1787 ], 1788 "links" : 1789 [ 1790 { 1791 "value" : "https://example.net/ip/2001:db8::/48", 1792 "rel" : "self", 1793 "href" : "https://example.net/ip/2001:db8::/48", 1794 "type" : "application/rdap+json" 1795 }, 1796 { 1797 "value" : "https://example.net/ip/2001:db8::/48", 1798 "rel" : "up", 1799 "href" : "https://example.net/ip/2001:c00::/23", 1800 "type" : "application/rdap+json" 1801 } 1802 ], 1803 "events" : 1804 [ 1805 { 1806 "eventAction" : "registration", 1807 "eventDate" : "1990-12-31T23:59:59Z" 1808 }, 1809 { 1810 "eventAction" : "last changed", 1811 "eventDate" : "1991-12-31T23:59:59Z" 1812 } 1813 ], 1814 "entities" : 1815 [ 1816 { 1817 "objectClassName" : "entity", 1818 "handle" : "XXXX", 1819 "vcardArray":[ 1820 "vcard", 1821 [ 1822 ["version", {}, "text", "4.0"], 1823 ["fn", {}, "text", "Joe User"], 1824 ["kind", {}, "text", "individual"], 1825 ["lang", { 1826 "pref":"1" 1827 }, "language-tag", "fr"], 1828 ["lang", { 1829 "pref":"2" 1830 }, "language-tag", "en"], 1831 ["org", { 1832 "type":"work" 1833 }, "text", "Example"], 1834 ["title", {}, "text", "Research Scientist"], 1835 ["role", {}, "text", "Project Lead"], 1836 ["adr", 1837 { "type":"work" }, 1838 "text", 1839 [ 1840 "", 1841 "Suite 1234", 1842 "4321 Rue Somewhere", 1843 "Quebec", 1844 "QC", 1845 "G1V 2M2", 1846 "Canada" 1847 ] 1848 ], 1849 ["tel", 1850 { "type":["work", "voice"], "pref":"1" }, 1851 "uri", "tel:+1-555-555-1234;ext=102" 1852 ], 1853 ["email", 1854 { "type":"work" }, 1855 "text", "joe.user@example.com" 1856 ] 1857 ] 1858 ], 1859 "roles" : [ "registrant" ], 1860 "remarks" : 1861 [ 1862 { 1863 "description" : 1864 [ 1865 "She sells sea shells down by the sea shore.", 1866 "Originally written by Terry Sullivan." 1867 ] 1868 } 1869 ], 1870 "links" : 1871 [ 1872 { 1873 "value" : "https://example.net/entity/xxxx", 1874 "rel" : "self", 1875 "href" : "https://example.net/entity/xxxx", 1876 "type" : "application/rdap+json" 1877 } 1878 ], 1879 "events" : 1880 [ 1881 { 1882 "eventAction" : "registration", 1883 "eventDate" : "1990-12-31T23:59:59Z" 1885 }, 1886 { 1887 "eventAction" : "last changed", 1888 "eventDate" : "1991-12-31T23:59:59Z" 1889 } 1890 ] 1891 } 1892 ] 1894 } 1896 Figure 26 1898 The IP network object class can contain the following members: 1900 * objectClassName -- the string "ip network" 1902 * handle -- a string representing the RIR-unique identifier of the 1903 network registration 1905 * startAddress -- a string representing the starting IP address of 1906 the network, either IPv4 or IPv6 1908 * endAddress -- a string representing the ending IP address of the 1909 network, either IPv4 or IPv6 1911 * ipVersion -- a string signifying the IP protocol version of the 1912 network: "v4" signifies an IPv4 network, and "v6" signifies an 1913 IPv6 network 1915 * name -- a string representing an identifier assigned to the 1916 network registration by the registration holder 1918 * type -- a string containing an RIR-specific classification of the 1919 network 1921 * country -- a string containing the two-character country code of 1922 the network 1924 * parentHandle -- a string containing an RIR-unique identifier of 1925 the parent network of this network registration 1927 * status -- an array of strings indicating the state of the IP 1928 network as defined by Section 4.6 1930 * entities -- an array of entity objects as defined by Section 5.1 1932 * remarks -- see Section 4.3 1934 * links -- see Section 4.2 1936 * port43 -- see Section 4.7 1938 * events -- see Section 4.5 1940 5.5. Autonomous System Number Object Class 1942 The Autonomous System number (autnum) object class models Autonomous 1943 System number registrations found in RIRs and represents the expected 1944 response to an "/autnum" query as defined by 1945 [I-D.hollenbeck-regext-rfc7482bis]. There is no equivalent object 1946 class for DNRs. The high-level structure of the autnum object class 1947 consists of information about the network registration and entities 1948 related to the autnum registration (e.g., registrant information, 1949 contacts, etc.) and is similar to the IP network object class. 1951 The following is an example of a JSON object representing an autnum. 1953 { 1954 "objectClassName" : "autnum", 1955 "handle" : "XXXX-RIR", 1956 "startAutnum" : 10, 1957 "endAutnum" : 15, 1958 "name": "AS-RTR-1", 1959 "type" : "DIRECT ALLOCATION", 1960 "status" : [ "active" ], 1961 "country": "AU", 1962 "remarks" : 1963 [ 1964 { 1965 "description" : 1966 [ 1967 "She sells sea shells down by the sea shore.", 1968 "Originally written by Terry Sullivan." 1969 ] 1970 } 1971 ], 1972 "links" : 1973 [ 1974 { 1975 "value" : "https://example.net/autnum/xxxx", 1976 "rel" : "self", 1977 "href" : "https://example.net/autnum/xxxx", 1978 "type" : "application/rdap+json" 1979 } 1980 ], 1981 "events" : 1983 [ 1984 { 1985 "eventAction" : "registration", 1986 "eventDate" : "1990-12-31T23:59:59Z" 1987 }, 1988 { 1989 "eventAction" : "last changed", 1990 "eventDate" : "1991-12-31T23:59:59Z" 1991 } 1992 ], 1993 "entities" : 1994 [ 1995 { 1996 "objectClassName" : "entity", 1997 "handle" : "XXXX", 1998 "vcardArray":[ 1999 "vcard", 2000 [ 2001 ["version", {}, "text", "4.0"], 2002 ["fn", {}, "text", "Joe User"], 2003 ["kind", {}, "text", "individual"], 2004 ["lang", { 2005 "pref":"1" 2006 }, "language-tag", "fr"], 2007 ["lang", { 2008 "pref":"2" 2009 }, "language-tag", "en"], 2010 ["org", { 2011 "type":"work" 2012 }, "text", "Example"], 2013 ["title", {}, "text", "Research Scientist"], 2014 ["role", {}, "text", "Project Lead"], 2015 ["adr", 2016 { "type":"work" }, 2017 "text", 2018 [ 2019 "", 2020 "Suite 1234", 2021 "4321 Rue Somewhere", 2022 "Quebec", 2023 "QC", 2024 "G1V 2M2", 2025 "Canada" 2026 ] 2027 ], 2028 ["tel", 2029 { "type":["work", "voice"], "pref":"1" }, 2030 "uri", "tel:+1-555-555-1234;ext=102" 2031 ], 2032 ["email", 2033 { "type":"work" }, 2034 "text", "joe.user@example.com" 2035 ] 2037 ] 2038 ], 2039 "roles" : [ "registrant" ], 2040 "remarks" : 2041 [ 2042 { 2043 "description" : 2044 [ 2045 "She sells sea shells down by the sea shore.", 2046 "Originally written by Terry Sullivan." 2047 ] 2048 } 2049 ], 2050 "links" : 2051 [ 2052 { 2053 "value" : "https://example.net/entity/XXXX", 2054 "rel" : "self", 2055 "href" : "https://example.net/entity/XXXX", 2056 "type" : "application/rdap+json" 2057 } 2058 ], 2059 "events" : 2060 [ 2061 { 2062 "eventAction" : "registration", 2063 "eventDate" : "1990-12-31T23:59:59Z" 2064 }, 2065 { 2066 "eventAction" : "last changed", 2067 "eventDate" : "1991-12-31T23:59:59Z" 2068 } 2069 ] 2070 } 2071 ] 2072 } 2074 Figure 27 2076 The Autonomous System number object class can contain the following 2077 members: 2079 * objectClassName -- the string "autnum" 2081 * handle -- a string representing the RIR-unique identifier of the 2082 autnum registration 2084 * startAutnum -- an unsigned 32-bit integer representing the 2085 starting number [RFC5396] in the block of Autonomous System 2086 numbers 2088 * endAutnum -- an unsigned 32-bit integer representing the ending 2089 number [RFC5396] in the block of Autonomous System numbers 2091 * name -- a string representing an identifier assigned to the autnum 2092 registration by the registration holder 2094 * type -- a string containing an RIR-specific classification of the 2095 autnum 2097 * status -- an array of strings indicating the state of the autnum 2098 as defined by Section 4.6 2100 * country -- a string containing the two-character country code of 2101 the autnum 2103 * entities -- an array of entity objects as defined by Section 5.1 2105 * remarks -- see Section 4.3 2107 * links -- see Section 4.2 2109 * port43 -- see Section 4.7 2111 * events -- see Section 4.5 2113 6. Error Response Body 2115 Some non-answer responses may return entity bodies with information 2116 that could be more descriptive. 2118 The basic structure of that response is an object class containing an 2119 error code number (corresponding to the HTTP response code) followed 2120 by a string named "title" and an array of strings named 2121 "description". 2123 This is an example of the common response body. 2125 { 2126 "errorCode": 418, 2127 "title": "Your Beverage Choice is Not Available", 2128 "description": 2129 [ 2130 "I know coffee has more ummppphhh.", 2131 "Sorry, dude!" 2132 ] 2133 } 2135 Figure 28 2137 This is an example of the common response body with an 2138 rdapConformance and notices data structures: 2140 { 2141 "rdapConformance" : 2142 [ 2143 "rdap_level_0" 2144 ], 2145 "notices" : 2146 [ 2147 { 2148 "title" : "Beverage Policy", 2149 "description" : 2150 [ 2151 "Beverages with caffeine for keeping horses awake." 2152 ], 2153 "links" : 2154 [ 2155 { 2156 "value" : "https://example.net/ip/192.0.2.0/24", 2157 "rel" : "alternate", 2158 "type" : "text/html", 2159 "href" : "https://www.example.com/redaction_policy.html" 2160 } 2161 ] 2162 } 2163 ], 2164 "lang" : "en", 2165 "errorCode": 418, 2166 "title": "Your beverage choice is not available", 2167 "description": 2168 [ 2169 "I know coffee has more ummppphhh.", 2170 "Sorry, dude!" 2171 ] 2172 } 2173 Figure 29 2175 7. Responding to Help Queries 2177 The appropriate response to /help queries as defined by 2178 [I-D.hollenbeck-regext-rfc7482bis] is to use the notices structure as 2179 defined in Section 4.3. 2181 This is an example of a response to a /help query including the 2182 rdapConformance data structure. 2184 { 2185 "rdapConformance" : 2186 [ 2187 "rdap_level_0" 2188 ], 2189 "notices" : 2190 [ 2191 { 2192 "title" : "Authentication Policy", 2193 "description" : 2194 [ 2195 "Access to sensitive data for users with proper credentials." 2196 ], 2197 "links" : 2198 [ 2199 { 2200 "value" : "https://example.net/help", 2201 "rel" : "alternate", 2202 "type" : "text/html", 2203 "href" : "https://www.example.com/auth_policy.html" 2204 } 2205 ] 2206 } 2207 ] 2208 } 2210 Figure 30 2212 8. Responding To Searches 2214 [I-D.hollenbeck-regext-rfc7482bis] specifies three types of searches: 2215 domains, nameservers, and entities. Responses to these searches take 2216 the form of an array of object instances where each instance is an 2217 appropriate object class for the search (i.e., a search for /domains 2218 yields an array of domain object instances). These arrays are 2219 contained within the response object. 2221 The names of the arrays are as follows: 2223 * for /domains searches, the array is "domainSearchResults" 2225 * for /nameservers searches, the array is "nameserverSearchResults" 2227 * for /entities searches, the array is "entitySearchResults" 2229 The following is an elided example of a response to a /domains 2230 search. 2232 { 2233 "rdapConformance" : 2234 [ 2235 "rdap_level_0" 2236 ], 2237 ... 2238 "domainSearchResults" : 2239 [ 2240 { 2241 "objectClassName" : "domain", 2242 "handle" : "1-XXXX", 2243 "ldhName" : "1.example.com", 2244 ... 2245 }, 2246 { 2247 "objectClassName" : "domain", 2248 "handle" : "2-XXXX", 2249 "ldhName" : "2.example.com", 2250 ... 2251 } 2252 ] 2253 } 2255 Figure 31 2257 9. Indicating Truncated Responses 2259 In cases where the data of a response needs to be limited or parts of 2260 the data need to be omitted, the response is considered "truncated". 2261 A truncated response is still valid JSON, but some of the results in 2262 a search set or some of the data in an object are not provided by the 2263 server. A server may indicate this by including a typed notice in 2264 the response object. 2266 The following is an elided example of a search response that has been 2267 truncated. 2269 { 2270 "rdapConformance" : 2271 [ 2272 "rdap_level_0" 2273 ], 2274 "notices" : 2275 [ 2276 { 2277 "title" : "Search Policy", 2278 "type" : "result set truncated due to authorization", 2279 "description" : 2280 [ 2281 "Search results are limited to 25 per day per querying IP." 2282 ], 2283 "links" : 2284 [ 2285 { 2286 "value" : "https://example.net/help", 2287 "rel" : "alternate", 2288 "type" : "text/html", 2289 "href" : "https://www.example.com/search_policy.html" 2290 } 2291 ] 2292 } 2293 ], 2294 "domainSearchResults" : 2295 [ 2296 ... 2297 ] 2298 } 2300 Figure 32 2302 A similar technique can be used with a typed remark where a single 2303 object has been returned and data in that object has been truncated. 2304 Such an example might be an entity object with only a partial set of 2305 the IP networks associated with it. 2307 The following is an elided example of an entity truncated data. 2309 { 2310 "objectClassName" : "entity", 2311 "handle" : "ANENTITY", 2312 "roles" : [ "registrant" ], 2313 ... 2314 "entities" : 2315 [ 2316 { 2317 "objectClassName" : "entity", 2318 "handle": "ANEMBEDDEDENTITY", 2319 "roles" : [ "technical" ], 2320 ... 2321 }, 2322 ... 2323 ], 2324 "networks" : 2325 [ 2326 ... 2327 ], 2328 ... 2329 "remarks" : 2330 [ 2331 { 2332 "title" : "Data Policy", 2333 "type" : "object truncated due to unexplainable reason", 2334 "description" : 2335 [ 2336 "Some of the data in this object has been removed." 2337 ], 2338 "links" : 2339 [ 2340 { 2341 "value" : "https://example.net/help", 2342 "rel" : "alternate", 2343 "type" : "text/html", 2344 "href" : "https://www.example.com/data_policy.html" 2345 } 2346 ] 2347 } 2348 ] 2349 } 2351 Figure 33 2353 10. IANA Considerations 2355 10.1. RDAP JSON Media Type Registration 2356 This specification registers the "application/rdap+json" media 2357 type. 2358 Type name: application 2360 Subtype name: rdap+json 2362 Required parameters: n/a 2364 Encoding considerations: See Section 3.1 of [RFC6839]. 2366 Security considerations: The media represented by this identifier 2367 does not have security considerations beyond that found in 2368 Section 12 of [RFC8259]. 2370 Interoperability considerations: There are no known 2371 interoperability problems regarding this media format. 2373 Published specification: RFC 7483 2375 Applications that use this media type: Implementations of the 2376 Registration Data Access Protocol (RDAP). 2378 Additional information: This media type is a product of the IETF 2379 WEIRDS working group. The WEIRDS charter, information on the 2380 WEIRDS mailing list, and other documents produced by the WEIRDS 2381 working group can be found at https://datatracker.ietf.org/wg/ 2382 weirds/. 2384 Person & email address to contact for further information: IESG 2385 2387 Intended usage: COMMON 2389 Restrictions on usage: none 2391 Author: Andy Newton 2393 Change controller: IETF 2395 Provisional Registration: No (upon publication of this RFC) 2397 10.2. JSON Values Registry 2399 IANA has created a category in the protocol registries labeled 2400 "Registration Data Access Protocol (RDAP)", and within that category, 2401 IANA has established a URL-referenceable, stand-alone registry 2402 labeled "RDAP JSON Values". This new registry is for use in the 2403 notices and remarks (Section 4.3), status (Section 4.6), role 2404 (Section 5.1), event action (Section 4.5), and domain variant 2405 relation (Section 5.3) fields specified in RDAP. 2407 Each entry in the registry contains the following fields: 2409 1. Value -- the string value being registered. 2411 2. Type -- the type of value being registered. It should be one of 2412 the following: 2414 * "notice or remark type" -- denotes a type of notice or remark. 2416 * "status" -- denotes a value for the "status" object member as 2417 defined by Section 4.6. 2419 * "role" -- denotes a value for the "role" array as defined in 2420 Section 5.1. 2422 * "event action" -- denotes a value for an event action as 2423 defined in Section 4.5. 2425 * "domain variant relation" -- denotes a relationship between a 2426 domain and a domain variant as defined in Section 5.3. 2428 3. Description -- a one- or two-sentence description regarding the 2429 meaning of the value, how it might be used, and/or how it should 2430 be interpreted by clients. 2432 4. Registrant Name -- the name of the person registering the value. 2434 5. Registrant Contact Information -- an email address, postal 2435 address, or some other information to be used to contact the 2436 registrant. 2438 This registry is operated under the "Expert Review" policy defined in 2439 [RFC8126]. 2441 Review of registrations into this registry by the designated 2442 expert(s) should be narrowly judged on the following criteria: 2444 1. Values in need of being placed into multiple types must be 2445 assigned a separate registration for each type. 2447 2. Values must be strings. They should be multiple words separated 2448 by single space characters. Every character should be 2449 lowercased. If possible, every word should be given in English 2450 and each character should be US-ASCII. 2452 3. Registrations should not duplicate the meaning of any existing 2453 registration. That is, if a request for a registration is 2454 significantly similar in nature to an existing registration, the 2455 request should be denied. For example, the terms "maintainer" 2456 and "registrant" are significantly similar in nature as they both 2457 denote a holder of a domain name or Internet number resource. In 2458 cases where it may be reasonably argued that machine 2459 interpretation of two similar values may alter the operation of 2460 client software, designated experts should not judge the values 2461 to be of significant similarity. 2463 4. Registrations should be relevant to the common usages of RDAP. 2464 Designated experts may rely upon the serving of the value by a 2465 DNR or RIR to make this determination. 2467 The following sections provide initial registrations into this 2468 registry. 2470 10.2.1. Notice and Remark Types 2472 The following values have been registered in the "RDAP JSON Values" 2473 registry: 2475 * Value: result set truncated due to authorization 2477 Type: notice and remark type 2479 Description: The list of results does not contain all results due 2480 to lack of authorization. This may indicate to some clients that 2481 proper authorization will yield a longer result set. 2483 Registrant Name: IESG 2485 Registrant Contact Information: iesg@ietf.org 2487 * Value: result set truncated due to excessive load 2489 Type: notice and remark type 2490 Description: The list of results does not contain all results due 2491 to excessively heavy load on the server. This may indicate to 2492 some clients that requerying at a later time will yield a longer 2493 result set. 2495 Registrant Name: IESG 2497 Registrant Contact Information: iesg@ietf.org 2499 * Value: result set truncated due to unexplainable reasons 2501 Type: notice and remark type 2503 Description: The list of results does not contain all results for 2504 an unexplainable reason. This may indicate to some clients that 2505 requerying for any reason will not yield a longer result set. 2507 Registrant Name: IESG 2509 Registrant Contact Information: iesg@ietf.org 2511 * Value: object truncated due to authorization 2513 Type: notice and remark type 2515 Description: The object does not contain all data due to lack of 2516 authorization. 2518 Registrant Name: IESG 2520 Registrant Contact Information: iesg@ietf.org 2522 * Value: object truncated due to excessive load 2524 Type: notice and remark type 2526 Description: The object does not contain all data due to 2527 excessively heavy load on the server. This may indicate to some 2528 clients that requerying at a later time will yield all data of the 2529 object. 2531 Registrant Name: IESG 2533 Registrant Contact Information: iesg@ietf.org 2535 * Value: object truncated due to unexplainable reasons 2537 Type: notice and remark type 2538 Description: The object does not contain all data for an 2539 unexplainable reason. 2541 Registrant Name: IESG 2543 Registrant Contact Information: iesg@ietf.org 2545 10.2.2. Status 2547 The following values have been registered in the "RDAP JSON Values" 2548 registry: 2550 * Value: validated 2552 Type: status 2554 Description: Signifies that the data of the object instance has 2555 been found to be accurate. This type of status is usually found 2556 on entity object instances to note the validity of identifying 2557 contact information. 2559 Registrant Name: IESG 2561 Registrant Contact Information: iesg@ietf.org 2563 * Value: renew prohibited 2565 Type: status 2567 Description: Renewal or reregistration of the object instance is 2568 forbidden. 2570 Registrant Name: IESG 2572 Registrant Contact Information: iesg@ietf.org 2574 * Value: update prohibited 2576 Type: status 2578 Description: Updates to the object instance are forbidden. 2580 Registrant Name: IESG 2582 Registrant Contact Information: iesg@ietf.org 2584 * Value: transfer prohibited 2585 Type: status 2587 Description: Transfers of the registration from one registrar to 2588 another are forbidden. This type of status normally applies to 2589 DNR domain names. 2591 Registrant Name: IESG 2593 Registrant Contact Information: iesg@ietf.org 2595 * Value: delete prohibited 2597 Type: status 2599 Description: Deletion of the registration of the object instance 2600 is forbidden. This type of status normally applies to DNR domain 2601 names. 2603 Registrant Name: IESG 2605 Registrant Contact Information: iesg@ietf.org 2607 * Value: proxy 2609 Type: status 2611 Description: The registration of the object instance has been 2612 performed by a third party. This is most commonly applied to 2613 entities. 2615 Registrant Name: IESG 2617 Registrant Contact Information: iesg@ietf.org 2619 * Value: private 2621 Type: status 2623 Description: The information of the object instance is not 2624 designated for public consumption. This is most commonly applied 2625 to entities. 2627 Registrant Name: IESG 2629 Registrant Contact Information: iesg@ietf.org 2631 * Value: removed 2632 Type: status 2634 Description: Some of the information of the object instance has 2635 not been made available and has been removed. This is most 2636 commonly applied to entities. 2638 Registrant Name: IESG 2640 Registrant Contact Information: iesg@ietf.org 2642 * Value: obscured 2644 Type: status 2646 Description: Some of the information of the object instance has 2647 been altered for the purposes of not readily revealing the actual 2648 information of the object instance. This is most commonly applied 2649 to entities. 2651 Registrant Name: IESG 2653 Registrant Contact Information: iesg@ietf.org 2655 * Value: associated 2657 Type: status 2659 Description: The object instance is associated with other object 2660 instances in the registry. This is most commonly used to signify 2661 that a nameserver is associated with a domain or that an entity is 2662 associated with a network resource or domain. 2664 Registrant Name: IESG 2666 Registrant Contact Information: iesg@ietf.org 2668 * Value: active 2670 Type: status 2672 Description: The object instance is in use. For domain names, it 2673 signifies that the domain name is published in DNS. For network 2674 and autnum registrations it signifies that they are allocated or 2675 assigned for use in operational networks. This maps to the 2676 Extensible Provisioning Protocol (EPP) [RFC5730] 'OK' status. 2678 Registrant Name: IESG 2679 Registrant Contact Information: iesg@ietf.org 2681 * Value: inactive 2683 Type: status 2685 Description: The object instance is not in use. See 'active'. 2687 Registrant Name: IESG 2689 Registrant Contact Information: iesg@ietf.org 2691 * Value: locked 2693 Type: status 2695 Description: Changes to the object instance cannot be made, 2696 including the association of other object instances. 2698 Registrant Name: IESG 2700 Registrant Contact Information: iesg@ietf.org 2702 * Value: pending create 2704 Type: status 2706 Description: A request has been received for the creation of the 2707 object instance but this action is not yet complete. 2709 Registrant Name: IESG 2711 Registrant Contact Information: iesg@ietf.org 2713 * Value: pending renew 2715 Type: status 2717 Description: A request has been received for the renewal 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 transfer 2726 Type: status 2727 Description: A request has been received for the transfer of the 2728 object instance but this action is not yet complete. 2730 Registrant Name: IESG 2732 Registrant Contact Information: iesg@ietf.org 2734 * Value: pending update 2736 Type: status 2738 Description: A request has been received for the update or 2739 modification of the object instance but this action is not yet 2740 complete. 2742 Registrant Name: IESG 2744 Registrant Contact Information: iesg@ietf.org 2746 * Value: pending delete 2748 Type: status 2750 Description: A request has been received for the deletion or 2751 removal of the object instance but this action is not yet 2752 complete. For domains, this might mean that the name is no longer 2753 published in DNS but has not yet been purged from the registry 2754 database. 2756 Registrant Name: IESG 2758 Registrant Contact Information: iesg@ietf.org 2760 10.2.3. Event Actions 2762 The following values have been registered in the "RDAP JSON Values" 2763 registry: 2765 * Value: registration 2767 Type: event action 2769 Description: The object instance was initially registered. 2771 Registrant Name: IESG 2773 Registrant Contact Information: iesg@ietf.org 2775 * Value: reregistration 2777 Type: event action 2779 Description: The object instance was registered subsequently to 2780 initial registration. 2782 Registrant Name: IESG 2784 Registrant Contact Information: iesg@ietf.org 2786 * Value: last changed 2788 Type: event action 2790 Description: An action noting when the information in the object 2791 instance was last changed. 2793 Registrant Name: IESG 2795 Registrant Contact Information: iesg@ietf.org 2797 * Value: expiration 2799 Type: event action 2801 Description: The object instance has been removed or will be 2802 removed at a pre-determined date and time from the registry. 2804 Registrant Name: IESG 2806 Registrant Contact Information: iesg@ietf.org 2808 * Value: deletion 2810 Type: event action 2812 Description: The object instance was removed from the registry at 2813 a point in time that was not pre-determined. 2815 Registrant Name: IESG 2817 Registrant Contact Information: iesg@ietf.org 2819 * Value: reinstantiation 2821 Type: event action 2822 Description: The object instance was reregistered after having 2823 been removed from the registry. 2825 Registrant Name: IESG 2827 Registrant Contact Information: iesg@ietf.org 2829 * Value: transfer 2831 Type: event action 2833 Description: The object instance was transferred from one 2834 registrant to another. 2836 Registrant Name: IESG 2838 Registrant Contact Information: iesg@ietf.org 2840 * Value: locked 2842 Type: event action 2844 Description: The object instance was locked (see the 'locked' 2845 status). 2847 Registrant Name: IESG 2849 Registrant Contact Information: iesg@ietf.org 2851 * Value: unlocked 2853 Type: event action 2855 Description: The object instance was unlocked (see the 'locked' 2856 status). 2858 Registrant Name: IESG 2860 Registrant Contact Information: iesg@ietf.org 2862 10.2.4. Roles 2864 The following values have been registered in the "RDAP JSON Values" 2865 registry: 2867 * Value: registrant 2869 Type: role 2870 Description: The entity object instance is the registrant of the 2871 registration. In some registries, this is known as a maintainer. 2873 Registrant Name: IESG 2875 Registrant Contact Information: iesg@ietf.org 2877 * Value: technical 2879 Type: role 2881 Description: The entity object instance is a technical contact for 2882 the registration. 2884 Registrant Name: IESG 2886 Registrant Contact Information: iesg@ietf.org 2888 * Value: administrative 2890 Type: role 2892 Description: The entity object instance is an administrative 2893 contact for the registration. 2895 Registrant Name: IESG 2897 Registrant Contact Information: iesg@ietf.org 2899 * Value: abuse 2901 Type: role 2903 Description: The entity object instance handles network abuse 2904 issues on behalf of the registrant of the registration. 2906 Registrant Name: IESG 2908 Registrant Contact Information: iesg@ietf.org 2910 * Value: billing 2912 Type: role 2914 Description: The entity object instance handles payment and 2915 billing issues on behalf of the registrant of the registration. 2917 Registrant Name: IESG 2918 Registrant Contact Information: iesg@ietf.org 2920 * Value: registrar 2922 Type: role 2924 Description: The entity object instance represents the authority 2925 responsible for the registration in the registry. 2927 Registrant Name: IESG 2929 Registrant Contact Information: iesg@ietf.org 2931 * Value: reseller 2933 Type: role 2935 Description: The entity object instance represents a third party 2936 through which the registration was conducted (i.e. not the 2937 registry or registrar). 2939 Registrant Name: IESG 2941 Registrant Contact Information: iesg@ietf.org 2943 * Value: sponsor 2945 Type: role 2947 Description: The entity object instance represents a domain policy 2948 sponsor, such as an ICANN approved sponsor. 2950 Registrant Name: IESG 2952 Registrant Contact Information: iesg@ietf.org 2954 * Value: proxy 2956 Type: role 2958 Description: The entity object instance represents a proxy for 2959 another entity object, such as a registrant. 2961 Registrant Name: IESG 2963 Registrant Contact Information: iesg@ietf.org 2965 * Value: notifications 2966 Type: role 2968 Description: An entity object instance designated to receive 2969 notifications about association object instances. 2971 Registrant Name: IESG 2973 Registrant Contact Information: iesg@ietf.org 2975 * Value: noc 2977 Type: role 2979 Description: The entity object instance handles communications 2980 related to a network operations center (NOC). 2982 Registrant Name: IESG 2984 Registrant Contact Information: iesg@ietf.org 2986 10.2.5. Variant Relations 2988 The following values have been registered in the "RDAP JSON Values" 2989 registry: 2991 * Value: registered 2993 Type: domain variant relation 2995 Description: The variant names are registered in the registry. 2997 Registrant Name: IESG 2999 Registrant Contact Information: iesg@ietf.org 3001 * Value: unregistered 3003 Type: domain variant relation 3005 Description: The variant names are not found in the registry. 3007 Registrant Name: IESG 3009 Registrant Contact Information: iesg@ietf.org 3011 * Value: registration restricted 3013 Type: domain variant relation 3014 Description: Registration of the variant names is restricted to 3015 certain parties or within certain rules. 3017 Registrant Name: IESG 3019 Registrant Contact Information: iesg@ietf.org 3021 * Value: open registration 3023 Type: domain variant relation 3025 Description: Registration of the variant names is available to 3026 generally qualified registrants. 3028 Registrant Name: IESG 3030 Registrant Contact Information: iesg@ietf.org 3032 * Value: conjoined 3034 Type: domain variant relation 3036 Description: Registration of the variant names occurs 3037 automatically with the registration of the containing domain 3038 registration. 3040 Registrant Name: IESG 3042 Registrant Contact Information: iesg@ietf.org 3044 11. Implementation Status 3046 NOTE: Please remove this section and the reference to RFC 7942 prior 3047 to publication as an RFC. 3049 This section records the status of known implementations of the 3050 protocol defined by this specification at the time of posting of this 3051 Internet-Draft, and is based on a proposal described in RFC 7942 3052 [RFC7942]. The description of implementations in this section is 3053 intended to assist the IETF in its decision processes in progressing 3054 drafts to RFCs. Please note that the listing of any individual 3055 implementation here does not imply endorsement by the IETF. 3056 Furthermore, no effort has been spent to verify the information 3057 presented here that was supplied by IETF contributors. This is not 3058 intended as, and must not be construed to be, a catalog of available 3059 implementations or their features. Readers are advised to note that 3060 other implementations may exist. 3062 According to RFC 7942, "this will allow reviewers and working groups 3063 to assign due consideration to documents that have the benefit of 3064 running code, which may serve as evidence of valuable experimentation 3065 and feedback that have made the implemented protocols more mature. 3066 It is up to the individual working groups to use this information as 3067 they see fit". 3069 11.1. RedDog 3071 * Responsible Organization: NIC Mexico 3073 * Location: https://reddog.mx/ 3075 * Description: RedDog implements all the functionality of an RDAP 3076 Server defined in RFCs 7480,7481,7482 and 7483. RedDog is highly 3077 configurable and extensible to fit the needs of the developers and 3078 operators. 3080 * Level of Maturity: Production. 3082 * Coverage: RedDog supports all lookups, searches and responses for 3083 all object classes described in RFC 7482 and RFC 7483. 3085 * Version Compatibility: RFC 7482 and RFC 7483 3087 * Licensing: Apache License 2.0 3089 * Contact Information: reddog-dev@nic.mx 3091 * Information last updated: November 22, 2019 3093 11.2. Verisign 3095 * Responsible Organization: Verisign 3097 * Location: https://rdap.verisign.com/com/v1/, 3098 https://rdap.verisign.com/net/v1/ 3100 * Description: Verisign's production RDAP service for the .com and 3101 .net gTLDs. 3103 * Level of Maturity: Production. 3105 * Coverage: Lookup of domain names, name servers, entities; name 3106 server search by IP address; help. 3108 * Version Compatibility: RFC 7483 3109 * Contact Information: info@verisign-grs.com 3111 11.3. Verisign Labs 3113 * Responsible Organization: Verisign Labs 3115 * Location: https://rdap.verisignlabs.com/rdap/v1/ 3117 * Description: Verisign's experimental RDAP service for the .cc and 3118 .tv ccTLDs. 3120 * Level of Maturity: Experimental. 3122 * Coverage: Lookup of domain names, name servers, entities; name 3123 server search by IP address; basic search; regular expression 3124 search; federated authentication; help. 3126 * Version Compatibility: RFC 7483 3128 * Contact Information: Scott Hollenbeck, shollenbeck@verisign.com 3130 11.4. Asia-Pacific Network Information Centre (APNIC) 3132 * Responsible Organization: Asia-Pacific Network Information Centre 3133 (APNIC) 3135 * Location: https://rdap.apnic.net/, https://github.com/APNIC-net/ 3136 rdapd 3138 * Description: APNIC's production RDAP service for Internet 3139 numberresouces. 3141 * Level of Maturity: Production. 3143 * Coverage: Lookup of IP networks, AS numbers, domains, and 3144 entities. Also domain search by name, entity search by handle or 3145 full name, and help responses. 3147 * Version Compatibility: RFC 7483 3149 * Contact Information: helpdesk@apnic.net 3151 12. Security Considerations 3153 This specification models information serialized in JSON format. As 3154 JSON is a subset of JavaScript, implementations are advised to follow 3155 the security considerations outlined in Section 12 of [RFC8259] to 3156 prevent code injection. 3158 Though not specific to JSON, RDAP implementers should be aware of the 3159 security considerations specified in [RFC7480] and the security 3160 requirements and considerations in [RFC7481]. 3162 Clients caching data, especially clients using RDAP-specific caches 3163 (instead of HTTP-layer caches), should have safeguards to prevent 3164 cache poisoning. See Section 5 for advice on using the self links 3165 for caching. 3167 Finally, service operators should be aware of the privacy mechanisms 3168 noted in Section 14. 3170 13. Internationalization Considerations 3172 13.1. Character Encoding 3174 The default text encoding for JSON responses in RDAP is UTF-8 3175 [RFC3629], and all servers and clients MUST support UTF-8. 3177 13.2. URIs and IRIs 3179 [RFC7480] defines the use of URIs and IRIs in RDAP. 3181 13.3. Language Tags 3183 Section 4.4 defines the use of language tags in the JSON responses 3184 defined in this document. 3186 13.4. Internationalized Domain Names 3188 IDNs are denoted in this specification by the separation of DNS names 3189 in LDH form and Unicode form (see Section 3). Representation of IDNs 3190 in registries is described by the "variants" object in Section 5.3 3191 and the suggested values listed in Section 10.2.5. 3193 14. Privacy Considerations 3195 This specification suggests status values to denote contact and 3196 registrant information that has been marked as private and/or has 3197 been removed or obscured. See Section 10.2.2 for the complete list 3198 of status values. A few of the status values indicate that there are 3199 privacy concerns associated with the object instance. The following 3200 status codes SHOULD be used to describe data elements of a response 3201 when appropriate: 3203 private -- The object is not be shared in query responses, unless 3204 the user is authorized to view this information. 3206 removed -- Data elements within the object have been collected but 3207 have been omitted from the response. This option can be used to 3208 prevent unauthorized access to associated object instances without 3209 the need to mark them as private. 3211 obscured -- Data elements within the object have been collected, 3212 but the response value has been altered so that values are not 3213 easily discernible. A value changed from "1212" to "XXXX" is an 3214 example of obscured data. This option may reveal privacy 3215 sensitive information and should only be used when data 3216 sensitivity does not require a more protective option like 3217 "private" or "removed". 3219 See Appendix A.1 for an example of applying those values to contacts 3220 and registrants. 3222 15. References 3224 15.1. Normative References 3226 [I-D.hollenbeck-regext-rfc7482bis] 3227 Hollenbeck, S. and A. Newton, "Registration Data Access 3228 Protocol (RDAP) Query Format", Work in Progress, Internet- 3229 Draft, draft-hollenbeck-regext-rfc7482bis-05, 6 May 2020, 3230 . 3233 [ISO.3166.1988] 3234 International Organization for Standardization, "Codes for 3235 the representation of names of countries, 3rd edition", 3236 ISO Standard 3166, August 1988. 3238 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3239 Requirement Levels", BCP 14, RFC 2119, 3240 DOI 10.17487/RFC2119, March 1997, 3241 . 3243 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3244 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3245 . 3247 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3248 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3249 2003, . 3251 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3252 Resource Identifier (URI): Generic Syntax", STD 66, 3253 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3254 . 3256 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 3257 Rose, "Resource Records for the DNS Security Extensions", 3258 RFC 4034, DOI 10.17487/RFC4034, March 2005, 3259 . 3261 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 3262 Autonomous System (AS) Numbers", RFC 5396, 3263 DOI 10.17487/RFC5396, December 2008, 3264 . 3266 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 3267 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 3268 September 2009, . 3270 [RFC5890] Klensin, J., "Internationalized Domain Names for 3271 Applications (IDNA): Definitions and Document Framework", 3272 RFC 5890, DOI 10.17487/RFC5890, August 2010, 3273 . 3275 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3276 Address Text Representation", RFC 5952, 3277 DOI 10.17487/RFC5952, August 2010, 3278 . 3280 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 3281 DOI 10.17487/RFC7095, January 2014, 3282 . 3284 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 3285 Registration Data Access Protocol (RDAP)", RFC 7480, 3286 DOI 10.17487/RFC7480, March 2015, 3287 . 3289 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 3290 Registration Data Access Protocol (RDAP)", RFC 7481, 3291 DOI 10.17487/RFC7481, March 2015, 3292 . 3294 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3295 Writing an IANA Considerations Section in RFCs", BCP 26, 3296 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3297 . 3299 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3300 Interchange Format", STD 90, RFC 8259, 3301 DOI 10.17487/RFC8259, December 2017, 3302 . 3304 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 3305 DOI 10.17487/RFC8288, October 2017, 3306 . 3308 15.2. Informative References 3310 [IANA_IDNTABLES] 3311 IANA, "Repository of IDN Practices", 3312 . 3314 [JSON_ascendancy] 3315 MacVittie, L., "The Stealthy Ascendancy of JSON", April 3316 2011, . 3319 [JSON_performance_study] 3320 Nurseitov, N., Paulson, M., Reynolds, R., and C. Izurieta, 3321 "Comparison of JSON and XML Data Interchange Formats: A 3322 Case Study", 2009, 3323 . 3325 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 3326 DOI 10.17487/RFC3912, September 2004, 3327 . 3329 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 3330 STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009, 3331 . 3333 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 3334 Security Extensions Mapping for the Extensible 3335 Provisioning Protocol (EPP)", RFC 5910, 3336 DOI 10.17487/RFC5910, May 2010, 3337 . 3339 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 3340 DOI 10.17487/RFC6350, August 2011, 3341 . 3343 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 3344 Structured Syntax Suffixes", RFC 6839, 3345 DOI 10.17487/RFC6839, January 2013, 3346 . 3348 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 3349 Code: The Implementation Status Section", BCP 205, 3350 RFC 7942, DOI 10.17487/RFC7942, July 2016, 3351 . 3353 Appendix A. Suggested Data Modeling with the Entity Object Class 3355 A.1. Registrants and Contacts 3357 This document does not provide specific object classes for 3358 registrants and contacts. Instead, the entity object class may be 3359 used to represent a registrant or contact. When the entity object is 3360 embedded inside a containing object such as a domain name or IP 3361 network, the "roles" string array can be used to signify the 3362 relationship. It is recommended that the values from Section 10.2.4 3363 be used. 3365 The following is an example of an elided containing object with an 3366 embedded entity that is both a registrant and administrative contact: 3368 { 3369 ... 3370 "entities" : 3371 [ 3372 { 3373 "objectClassName" : "entity", 3374 "handle" : "XXXX", 3375 "vcardArray":[ 3376 "vcard", 3377 [ 3378 ["version", {}, "text", "4.0"], 3379 ["fn", {}, "text", "Joe User"], 3380 ["kind", {}, "text", "individual"], 3381 ["lang", { 3382 "pref":"1" 3383 }, "language-tag", "fr"], 3384 ["lang", { 3385 "pref":"2" 3386 }, "language-tag", "en"], 3387 ["org", { 3388 "type":"work" 3389 }, "text", "Example"], 3390 ["title", {}, "text", "Research Scientist"], 3391 ["role", {}, "text", "Project Lead"], 3392 ["adr", 3393 { "type":"work" }, 3394 "text", 3395 [ 3396 "", 3397 "Suite 1234", 3398 "4321 Rue Somewhere", 3399 "Quebec", 3400 "QC", 3401 "G1V 2M2", 3402 "Canada" 3403 ] 3404 ], 3405 ["tel", 3406 { "type":["work", "voice"], "pref":"1" }, 3407 "uri", "tel:+1-555-555-1234;ext=102" 3408 ], 3409 ["email", 3410 { "type":"work" }, 3411 "text", "joe.user@example.com" 3412 ] 3413 ] 3414 ], 3415 "roles" : [ "registrant", "administrative" ], 3416 "remarks" : 3417 [ 3418 { 3419 "description" : 3420 [ 3421 "She sells sea shells down by the sea shore.", 3422 "Originally written by Terry Sullivan." 3423 ] 3424 } 3425 ], 3426 "events" : 3427 [ 3428 { 3429 "eventAction" : "registration", 3430 "eventDate" : "1990-12-31T23:59:59Z" 3431 }, 3432 { 3433 "eventAction" : "last changed", 3434 "eventDate" : "1991-12-31T23:59:59Z" 3435 } 3436 ] 3437 } 3438 ] 3439 } 3441 Figure 34 3443 In many use cases, it is necessary to hide or obscure the information 3444 of a registrant or contact due to policy or other operational 3445 matters. Registries can denote these situations with "status" values 3446 (see Section 10.2.2). 3448 The following is an elided example of a registrant with information 3449 changed to reflect that of a third party. 3451 { 3452 ... 3453 "entities" : 3454 [ 3455 { 3456 "objectClassName" : "entity", 3457 "handle" : "XXXX", 3458 ... 3459 "roles" : [ "registrant", "administrative" ], 3460 "status" : [ "proxy", "private", "obscured" ] 3461 } 3462 ] 3463 } 3465 Figure 35 3467 A.2. Registrars 3469 This document does not provide a specific object class for 3470 registrars, but like registrants and contacts (see Appendix A.1), the 3471 "roles" string array maybe used. Additionally, many registrars have 3472 publicly assigned identifiers. The publicIds structure (Section 4.8) 3473 represents that information. 3475 The following is an example of an elided containing object with an 3476 embedded entity that is a registrar: 3478 { 3479 ... 3480 "entities":[ 3481 { 3482 "objectClassName" : "entity", 3483 "handle":"XXXX", 3484 "vcardArray":[ 3485 "vcard", 3486 [ 3487 ["version", {}, "text", "4.0"], 3488 ["fn", {}, "text", "Joe's Fish, Chips, and Domains"], 3489 ["kind", {}, "text", "org"], 3490 ["lang", { 3491 "pref":"1" 3492 }, "language-tag", "fr"], 3493 ["lang", { 3494 "pref":"2" 3495 }, "language-tag", "en"], 3496 ["org", { 3497 "type":"work" 3498 }, "text", "Example"], 3499 ["adr", 3500 { "type":"work" }, 3501 "text", 3502 [ 3503 "", 3504 "Suite 1234", 3505 "4321 Rue Somewhere", 3506 "Quebec", 3507 "QC", 3508 "G1V 2M2", 3509 "Canada" 3510 ] 3511 ], 3512 ["tel", 3513 { 3514 "type":["work", "voice"], 3515 "pref":"1" 3516 }, 3517 "uri", "tel:+1-555-555-1234;ext=102" 3518 ], 3519 ["email", 3520 { "type":"work" }, 3521 "text", "joes_fish_chips_and_domains@example.com" 3522 ] 3523 ] 3524 ], 3525 "roles":[ "registrar" ], 3526 "publicIds":[ 3527 { 3528 "type":"IANA Registrar ID", 3529 "identifier":"1" 3530 } 3531 ], 3532 "remarks":[ 3533 { 3534 "description":[ 3535 "She sells sea shells down by the sea shore.", 3536 "Originally written by Terry Sullivan." 3537 ] 3538 } 3540 ], 3541 "links":[ 3542 { 3543 "value":"https://example.net/entity/XXXX", 3544 "rel":"alternate", 3545 "type":"text/html", 3546 "href":"https://www.example.com" 3547 } 3548 ] 3549 } 3550 ] 3551 } 3553 Figure 36 3555 Appendix B. Modeling Events 3557 Events represent actions that have taken place against a registered 3558 object at a certain date and time. Events have three properties: the 3559 action, the actor, and the date and time of the event (which is 3560 sometimes in the future). In some cases, the identity of the actor 3561 is not captured. 3563 Events can be modeled in three ways: 3565 1. events with no designated actor 3567 2. events where the actor is only designated by an identifier 3569 3. events where the actor can be modeled as an entity 3571 For the first use case, the events data structure (Section 4.5) is 3572 used without the "eventActor" object member. 3574 This is an example of an "events" array without the "eventActor". 3576 "events" : 3577 [ 3578 { 3579 "eventAction" : "registration", 3580 "eventDate" : "1990-12-31T23:59:59Z" 3581 } 3582 ] 3584 Figure 37 3586 For the second use case, the events data structure (Section 4.5) is 3587 used with the "eventActor" object member. 3589 This is an example of an "events" array with the "eventActor". 3591 "events" : 3592 [ 3593 { 3594 "eventAction" : "registration", 3595 "eventActor" : "XYZ-NIC", 3596 "eventDate" : "1990-12-31T23:59:59Z" 3597 } 3598 ] 3600 Figure 38 3602 For the third use case, the "asEventActor" array is used when an 3603 entity (Section 5.1) is embedded into another object class. The 3604 "asEventActor" array follows the same structure as the "events" array 3605 but does not have "eventActor" attributes. 3607 The following is an elided example of a domain object with an entity 3608 as an event actor. 3610 { 3611 "objectClassName" : "domain", 3612 "handle" : "XXXX", 3613 "ldhName" : "foo.example", 3614 "status" : [ "locked", "transfer prohibited" ], 3615 ... 3616 "entities" : 3617 [ 3618 { 3619 "handle" : "XXXX", 3620 ... 3621 "asEventActor" : 3622 [ 3623 { 3624 "eventAction" : "last changed", 3625 "eventDate" : "1990-12-31T23:59:59Z" 3626 } 3627 ] 3628 } 3629 ] 3630 } 3632 Figure 39 3634 Appendix C. Structured vs. Unstructured Addresses 3636 The entity (Section 5.1) object class uses jCard [RFC7095] to 3637 represent contact information, including postal addresses. jCard has 3638 the ability to represent multiple language preferences, multiple 3639 email address and phone numbers, and multiple postal addresses in 3640 both a structured and unstructured format. This section describes 3641 the use of jCard for representing structured and unstructured 3642 addresses. 3644 The following is an example of a jCard. 3646 { 3647 "vcardArray":[ 3648 "vcard", 3649 [ 3650 ["version", {}, "text", "4.0"], 3651 ["fn", {}, "text", "Joe User"], 3652 ["n", {}, "text", 3653 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 3654 ], 3655 ["kind", {}, "text", "individual"], 3656 ["lang", { 3657 "pref":"1" 3658 }, "language-tag", "fr"], 3659 ["lang", { 3660 "pref":"2" 3661 }, "language-tag", "en"], 3662 ["org", { 3663 "type":"work" 3664 }, "text", "Example"], 3665 ["title", {}, "text", "Research Scientist"], 3666 ["role", {}, "text", "Project Lead"], 3667 ["adr", 3668 { "type":"work" }, 3669 "text", 3670 [ 3671 "", 3672 "Suite 1234", 3673 "4321 Rue Somewhere", 3674 "Quebec", 3675 "QC", 3676 "G1V 2M2", 3677 "Canada" 3678 ] 3679 ], 3680 ["adr", 3681 { 3682 "type":"home", 3683 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 3684 }, 3685 "text", 3686 [ 3687 "", "", "", "", "", "", "" 3688 ] 3689 ], 3690 ["tel", 3691 { "type":["work", "voice"], "pref":"1" }, 3692 "uri", "tel:+1-555-555-1234;ext=102" 3693 ], 3694 ["tel", 3695 { 3696 "type":["work", "cell", "voice", "video", "text"] 3697 }, 3698 "uri", 3699 "tel:+1-555-555-1234" 3700 ], 3701 ["email", 3702 { "type":"work" }, 3703 "text", "joe.user@example.com" 3704 ], 3705 ["geo", { 3706 "type":"work" 3707 }, "uri", "geo:46.772673,-71.282945"], 3708 ["key", 3709 { "type":"work" }, 3710 "uri", "https://www.example.com/joe.user/joe.asc" 3711 ], 3712 ["tz", {}, 3713 "utc-offset", "-05:00"], 3714 ["url", { "type":"home" }, 3715 "uri", "https://example.org"] 3716 ] 3717 ] 3718 } 3720 Figure 40 3722 The arrays in Figure 40 with the first member of "adr" represent 3723 postal addresses. In the first example, the postal address is given 3724 as an array of strings and constitutes a structured address. For 3725 components of the structured address that are not applicable, an 3726 empty string is given. Each member of that array aligns with the 3727 positions of a vCard as given in [RFC6350]. In this example, the 3728 following data corresponds to the following positional meanings: 3730 1. post office box -- not applicable; empty string 3732 2. extended address (e.g., apartment or suite number) -- Suite 1234 3734 3. street address -- 4321 Rue Somewhere 3736 4. locality (e.g., city) -- Quebec 3738 5. region (e.g., state or province) -- QC 3740 6. postal code -- G1V 2M2 3742 7. country name (full name) -- Canada 3744 The second example is an unstructured address. It uses the "label" 3745 attribute, which is a string containing a newline (\n) character to 3746 separate address components in an unordered, unspecified manner. 3747 Note that in this example, the structured address array is still 3748 given but that each string is an empty string. 3750 Appendix D. Secure DNS 3752 Section 5.3 defines the "secureDNS" member to represent secure DNS 3753 information about domain names. 3755 DNSSEC provides data integrity for DNS through the digital signing of 3756 resource records. To enable DNSSEC, the zone is signed by one or 3757 more private keys and the signatures are stored as RRSIG records. To 3758 complete the chain of trust in the DNS zone hierarchy, a digest of 3759 each DNSKEY record (which contains the public key) must be loaded 3760 into the parent zone, stored as DS records, and signed by the 3761 parent's private key (RRSIG DS record), as indicated in "Resource 3762 Records for the DNS Security Extensions" [RFC4034]. Creating the DS 3763 records in the parent zone can be done by the registration authority 3764 "Domain Name System (DNS) Security Extensions Mapping for the 3765 Extensible Provisioning Protocol (EPP)" [RFC5910]. 3767 Only DS-related information is provided by RDAP, since other 3768 information is not generally stored in the registration database. 3769 Other DNSSEC-related information can be retrieved with other DNS 3770 tools such as dig. 3772 The domain object class (Section 5.3) can represent this information 3773 using either the "dsData" or "keyData" object arrays. Client 3774 implementers should be aware that some registries do not collect or 3775 do not publish all of the secure DNS meta-information. 3777 Appendix E. Motivations for Using JSON 3779 This section addresses a common question regarding the use of JSON 3780 over other data formats, most notably XML. 3782 It is often pointed out that many DNRs and one RIR support the EPP 3783 [RFC5730] standard, which is an XML serialized protocol. The logic 3784 is that since EPP is a common protocol in the industry, it follows 3785 that XML would be a more natural choice. While EPP does influence 3786 this specification quite a bit, EPP serves a different purpose, which 3787 is the provisioning of Internet resources between registries and 3788 accredited registrars and serving a much narrower audience than that 3789 envisioned for RDAP. 3791 By contrast, RDAP has a broader audience and is designed for public 3792 consumption of data. Experience from RIRs with first generation 3793 RESTful web services for WHOIS indicate that a large percentage of 3794 clients operate within browsers and other platforms where full-blown 3795 XML stacks are not readily available and where JSON is a better fit. 3797 Additionally, while EPP is used in much of the DNR community it is 3798 not a universal constant in that industry. And finally, EPP's use of 3799 XML predates the specification of JSON. If EPP had been defined 3800 today, it may very well have used JSON instead of XML. 3802 Beyond the specific DNR and RIR communities, the trend in the broader 3803 Internet industry is also switching to JSON over XML, especially in 3804 the area of RESTful web services (see [JSON_ascendancy]). Studies 3805 have also found that JSON is generally less bulky and consequently 3806 faster to parse (see [JSON_performance_study]). 3808 Acknowledgements 3810 This document is derived from original work on RIR responses in JSON 3811 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew 3812 L. Newton. Additionally, this document incorporates work on DNR 3813 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 3814 Shen. 3816 The components of the DNR object classes are derived from a 3817 categorization of WHOIS response formats created by Ning Kong, Linlin 3818 Zhou, Guangqing Deng, Steve Sheng, Francisco Arias, Ray Bellis, and 3819 Frederico Neves. 3821 Tom Harrison, Murray Kucherawy, Ed Lewis, Audric Schiltknecht, Naoki 3822 Kambe, and Maarten Bosteels contributed significant review comments 3823 and provided clarifying text. James Mitchell provided text regarding 3824 the processing of unknown JSON attributes and identified issues 3825 leading to the remodeling of events. Ernie Dainow and Francisco 3826 Obispo provided concrete suggestions that led to a better variant 3827 model for domain names. 3829 Ernie Dainow provided the background information on the secure DNS 3830 attributes and objects for domains, informative text on DNSSEC, and 3831 many other attributes that appear throughout the object classes of 3832 this document. 3834 The switch to and incorporation of jCard was performed by Simon 3835 Perreault. 3837 Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working 3838 group from which this document has been created. 3840 Changes from RFC 7483 3842 00: Initial version ported from RFC 7483. Addressed known errata. 3843 Added Implementation Status section. 3845 01: Updated references to 7482 to 7482bis Internet-Draft. Updated 3846 "Change Log" to "Changes from RFC 7483". Added APNIC 3847 implementation status. Adjusted case of "xxxx" used in examples 3848 where "XXXX" was previously used, and removed an "X" from "XXXXX". 3849 Changed IPv6 address example using "C00" to "c00". Added "a 3850 string representing" to the definitions of startAddress and 3851 endAddress. Removed "entity" from "Autonomous System Number 3852 Entity Object Class". Added "an unsigned 32-bit integer" to the 3853 definition of startAutnum and endAutnum. Added "a string 3854 representing" to the definition of name in the IP network and ASN 3855 object classes. Clarified rdapConformance identifier registration 3856 expectations in Section 4.1. Changed "lunarNic_level_0" to 3857 "lunarNIC_level_0". Clarified that the "value", "rel" and "href" 3858 JSON values MUST be specified in the "links" array. Clarified 3859 that the "description" array is required in the Notices and 3860 Remarks data structures and other values are OPTIONAL. Noted that 3861 all members of the "events" and "Public IDs" arrays are REQUIRED. 3862 Fix "self" link values in examples. Changed "http" to "https" 3863 link values in examples. Noted that Figure 18 is an example of a 3864 nameserver object with all "appropriate" values given. In 3865 appendix C, quoted the word "label" in "label attribute". Added 3866 referencce to "status" definition in the descriptions for IP 3867 networks and autnums. Fixed a 404 for the informative reference 3868 to "The Stealthy Ascendancy of JSON". Added "boolean" to the 3869 definition of zoneSigned. Clarified REQUIRED and OPTIONAL members 3870 of the "events" array. Changed "SHOULD not" to "SHOULD NOT" in 3871 Section 5. Updated normative references (5226-8126, 5988-8288, 3872 7159-8259). Changed examples using "ns1.xn--fo-5ja.example" to 3873 split URLs to avoid long lines. 3875 Authors' Addresses 3877 Scott Hollenbeck 3878 Verisign Labs 3879 12061 Bluemont Way 3880 Reston, VA 20190 3881 United States 3883 Email: shollenbeck@verisign.com 3884 URI: https://www.verisignlabs.com/ 3886 Andy Newton 3887 Amazon Web Services, Inc. 3888 13200 Woodland Park Road 3889 Herndon, VA 20171 3890 United States of America 3891 Email: andy@hxr.us