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