idnits 2.17.1 draft-ietf-regext-rfc7483bis-05.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 (24 February 2021) is 1156 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 Obsoletes: 7483 (if approved) A. Newton 5 Intended status: Standards Track AWS 6 Expires: 28 August 2021 24 February 2021 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-regext-rfc7483bis-05 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. If approved, this document obsoletes RFC 7483. 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 28 August 2021. 36 Copyright Notice 38 Copyright (c) 2021 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 . . . . . . . . . . . . . . . 39 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 . . . . . . . . . . . . . . . . . . . 70 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 . . . . . . . . . . . . . . . . . . . . . . . 76 107 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 77 108 Appendix C. Structured vs. Unstructured Addresses . . . . . . . 79 109 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 82 110 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 82 111 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 83 112 Changes from RFC 7483 . . . . . . . . . . . . . . . . . . . . . . 83 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 86 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]. If 121 approved, this document obsoletes RFC 7483. 123 1.1. Terminology and Definitions 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 127 "OPTIONAL" in this document are to be interpreted as described in BCP 128 14 [RFC2119] [RFC8174] when, and only when, they appear in all 129 capitals, as shown here. 131 The following list describes terminology and definitions used 132 throughout this document: 134 DNR: Domain Name Registry or Domain Name Registrar 136 LDH: letters, digits, hyphen 138 member: data found within an object as defined by JSON [RFC8259] 140 object: a data structure as defined by JSON [RFC8259] 142 object class: the definition of members that may be found in JSON 143 objects described in this document 145 object instance: an instantiation or specific instance of an object 146 class 148 RDAP: Registration Data Access Protocol 150 RIR: Regional Internet Registry 152 1.2. Data Model 154 The data model for JSON responses is specified in five sections: 156 1. simple data types conveyed in JSON primitive types (strings, 157 numbers, booleans, and null) 159 2. data structures specified as JSON arrays or objects that are used 160 repeatedly when building up larger objects 162 3. object classes representing structured data corresponding to a 163 lookup of a single object 165 4. arrays of objects representing structured data corresponding to a 166 search for multiple objects 168 5. the response to an error 170 The object classes represent responses for two major categories of 171 data: responses returned by RIRs for registration data related to IP 172 addresses, reverse DNS names, and Autonomous System numbers and 173 responses returned by DNRs for registration data related to forward 174 DNS names. The following object classes are returned by both RIRs 175 and DNRs: 177 1. domains 179 2. nameservers 181 3. entities 183 The information served by both RIRs and DNRs for these object classes 184 overlap extensively and are given in this document as a unified model 185 for both classes of service. 187 In addition to the object classes listed above, RIRs also serve the 188 following object classes: 190 1. IP networks 191 2. Autonomous System numbers 193 Object classes defined in this document represent a minimal set of 194 what a compliant client/server needs to understand to function 195 correctly; however, some deployments may want to include additional 196 object classes to suit individual needs. Anticipating this need for 197 extension, Section 2.1 of this document defines a mechanism for 198 extending the JSON objects that are described in this document. 200 Positive responses take two forms. A response to a lookup of a 201 single object in the registration system yields a JSON object, which 202 is the subject of the lookup. A response to a search for multiple 203 objects yields a JSON object that contains an array of JSON objects 204 that are the subject of the search. In each type of response, other 205 data structures are present within the topmost JSON object. 207 2. Use of JSON 209 2.1. Naming 211 Clients of these JSON responses SHOULD ignore unrecognized JSON 212 members in responses. Servers can insert members into the JSON 213 responses, which are not specified in this document, but that does 214 not constitute an error in the response. Servers that insert such 215 unspecified members into JSON responses SHOULD have member names 216 prefixed with a short identifier followed by an underscore followed 217 by a meaningful name. It has been observed that these short 218 identifiers aid software implementers with identifying the 219 specification of the JSON member, and failure to use one could cause 220 an implementer to assume the server is erroneously using a name from 221 this specification. This allowance does not apply to jCard [RFC7095] 222 objects. The full JSON name (the prefix plus the underscore plus the 223 meaningful name) SHOULD adhere to the character and name limitations 224 of the prefix registry described in [RFC7480]. Failure to use these 225 limitations could result in slower adoption as these limitations have 226 been observed to aid some client programming models. 228 Consider the following JSON response with JSON members, all of which 229 are specified in this document. 231 { 232 "handle" : "ABC123", 233 "remarks" : 234 [ 235 { 236 "description" : 237 [ 238 "She sells sea shells down by the sea shore.", 239 "Originally written by Terry Sullivan." 240 ] 241 } 242 ] 243 } 245 Figure 1 247 If The Registry of the Moon desires to express information not found 248 in this specification, it might select "lunarNIC" as its identifying 249 prefix and insert, as an example, the member named 250 "lunarNIC_beforeOneSmallStep" to signify registrations occurring 251 before the first moon landing and the member named 252 "lunarNIC_harshMistressNotes" that contains other descriptive text. 254 Consider the following JSON response with JSON names, some of which 255 should be ignored by clients without knowledge of their meaning. 257 { 258 "handle" : "ABC123", 259 "lunarNIC_beforeOneSmallStep" : "TRUE THAT!", 260 "remarks" : 261 [ 262 { 263 "description" : 264 [ 265 "She sells sea shells down by the sea shore.", 266 "Originally written by Terry Sullivan." 267 ] 268 } 269 ], 270 "lunarNIC_harshMistressNotes" : 271 [ 272 "In space,", 273 "nobody can hear you scream." 274 ] 275 } 277 Figure 2 279 Insertion of unrecognized members ignored by clients may also be used 280 for future revisions to this specification. 282 Clients processing JSON responses need to be prepared for members 283 representing registration data specified in this document to be 284 absent from a response. In other words, servers are free to omit 285 unrequired/optional JSON members containing registration data based 286 on their own policies. 288 Finally, all JSON names specified in this document are case 289 sensitive. Both servers and clients MUST transmit and process them 290 using the specified character case. 292 3. Common Data Types 294 JSON [RFC8259] defines the data types of a number, character string, 295 boolean, array, object, and null. This section describes the 296 semantics and/or syntax reference for common, JSON character strings 297 used in this document. 299 handle: DNRs and RIRs have registry-unique identifiers that 300 may be used to specifically reference an object 301 instance. The semantics of this data type as found 302 in this document are to be a registry-unique 303 reference to the closest enclosing object where the 304 value is found. The data type names "registryId", 305 "roid", "nic-handle", "registrationNo", etc., are 306 terms often synonymous with this data type. In 307 this document, the term "handle" is used. The term 308 exposed to users by clients is a presentation issue 309 beyond the scope of this document. This value is a 310 simple character string. 312 IPv4 addresses: The representation of IPv4 addresses in this 313 document uses the dotted-decimal notation. An 314 example of this textual representation is 315 "192.0.2.0". 317 IPv6 addresses: The representation of IPv6 addresses in this 318 document follow the forms outlined in [RFC5952]. 319 An example of this textual representation is 320 "2001:db8::1:0:0:1". 322 country codes: Where the identity of a geopolitical nation or 323 country is needed, these identities are represented 324 with the alpha-2 or two-character country code 325 designation as defined in [ISO.3166.1988]. The 326 alpha-2 representation is used because it is freely 327 available, whereas the alpha-3 and numeric-3 328 standards are not. 330 LDH names: Textual representations of DNS names where the 331 labels of the domain are all "letters, digits, 332 hyphen" labels as described by [RFC5890]. Trailing 333 periods are optional. 335 Unicode names: Textual representations of DNS names where one or 336 more of the labels are U-labels as described by 337 [RFC5890]. Trailing periods are optional. 339 dates and times: The syntax for values denoting dates and times is 340 defined in [RFC3339]. 342 URIs: The syntax for values denoting a Uniform Resource 343 Identifier (URI) is defined by [RFC3986]. 345 Contact information is defined using jCards as described in 346 [RFC7095]. The "fn" member is required and MUST NOT be null 347 according to [RFC6350]. An empty "fn" member MAY be used when the 348 contact name does not exist or is redacted. 350 4. Common Data Structures 352 This section defines common data structures used in responses and 353 object classes. 355 4.1. RDAP Conformance 357 The data structure named "rdapConformance" is an array of strings, 358 each providing a hint as to the specifications used in the 359 construction of the response. This data structure MUST appear in the 360 topmost JSON object of a response and MUST NOT appear anywhere else. 361 A response to a "help" request will include identifiers for all of 362 the specifications supported by the server. A response to any other 363 request will include only identifiers for the specifications used in 364 the construction of the response. The set of returned identifiers 365 MAY vary depending on the authorization level of the client. 367 An example rdapConformance data structure: 369 "rdapConformance" : 370 [ 371 "rdap_level_0" 372 ] 374 Figure 3 376 The string literal "rdap_level_0" signifies conformance with this 377 specification. When custom JSON values are inserted into responses, 378 conformance to those custom specifications MUST be indicated by 379 including a unique string literal value registered in the IANA RDAP 380 Extensions registry specified in [RFC7480]. For example, if the 381 fictional Registry of the Moon wants to signify that their JSON 382 responses are conformant with their registered extensions, the string 383 used might be "lunarNIC_level_0". These registered values aid the 384 identification of specifications for software implementers, and 385 failure to use them could result in slower adoption of extensions. 387 Example rdapConformance structure with custom extensions noted: 389 "rdapConformance" : 390 [ 391 "rdap_level_0", 392 "lunarNIC_level_0" 393 ] 395 Figure 4 397 4.2. Links 399 The "links" array is found in data structures to signify links to 400 other resources on the Internet. The relationship of these links is 401 defined by the IANA registry described by [RFC8288]. 403 The following is an example of the link structure: 405 { 406 "value" : "https://example.com/context_uri", 407 "rel" : "self", 408 "href" : "https://example.com/target_uri", 409 "hreflang" : [ "en", "ch" ], 410 "title" : "title", 411 "media" : "screen", 412 "type" : "application/json" 413 } 415 Figure 5 417 The JSON name/values of "rel", "href", "hreflang", "title", "media", 418 and "type" correspond to values found in Section 3 of [RFC8288]. The 419 "value" JSON value is the context URI as described by [RFC8288]. The 420 "value", "rel" and "href" JSON values MUST be specified. All other 421 JSON values are OPTIONAL. A "related" link relation MUST NOT include 422 an "href" URI that is the same as the "self" link relation "href" URI 423 to reduce the risk of infinite client processing loops. 424 Internationalized Domain Names (IDNs) returned in URIs SHOULD be 425 consistently returned in LDH name format to allow clients to process 426 these IDNs according to their capabilities. 428 This is an example of the "links" array as it might be found in an 429 object class: 431 "links" : 432 [ 433 { 434 "value" : "https://example.com/ip/2001:db8::123", 435 "rel" : "self", 436 "href" : "https://example.com/ip/2001:db8::123", 437 "type" : "application/rdap+json" 438 }, 439 { 440 "value" : "https://example.com/ip/2001:db8::123", 441 "rel" : "up", 442 "href" : "https://example.com/ip/2001:db8::/48", 443 "type" : "application/rdap+json" 444 } 446 ] 448 Figure 6 450 4.3. Notices and Remarks 452 The "notices" and "remarks" data structures take the same form. The 453 notices structure denotes information about the service providing 454 RDAP information and/or information about the entire response, 455 whereas the remarks structure denotes information about the object 456 class that contains it (see Section 5 regarding object classes). 458 Both are arrays of objects. Each object contains a "title" string 459 representing the title of the object, a "type" string denoting a 460 registered type of remark or notice (see Section 10.2.1), an array of 461 strings named "description" for the purposes of conveying any 462 descriptive text, and a "links" array as described in Section 4.2. 463 The "description" array MUST be included. All other JSON values are 464 OPTIONAL. 466 An example of the notices data structure: 468 "notices" : 469 [ 470 { 471 "title" : "Terms of Use", 472 "description" : 473 [ 474 "Service subject to The Registry of the Moon's TOS.", 475 "Copyright (c) 2020 LunarNIC" 476 ], 477 "links" : 478 [ 479 { 480 "value" : "https://example.net/entity/XXXX", 481 "rel" : "alternate", 482 "type" : "text/html", 483 "href" : "https://www.example.com/terms_of_use.html" 484 } 485 ] 486 } 487 ] 489 Figure 7 491 It is the job of the clients to determine line breaks, spacing, and 492 display issues for sentences within the character strings of the 493 "description" array. Each string in the "description" array contains 494 a single complete division of human-readable text indicating to 495 clients where there are semantic breaks. 497 An example of the remarks data structure: 499 "remarks" : 500 [ 501 { 502 "description" : 503 [ 504 "She sells sea shells down by the sea shore.", 505 "Originally written by Terry Sullivan." 506 ] 507 } 508 ] 510 Figure 8 512 Note that objects in the "remarks" array may also have a "links" 513 array. 515 While the "title" and "description" fields are intended primarily for 516 human consumption, the "type" string contains a well-known value to 517 be registered with IANA (see Section 10.2.1) for programmatic use. 519 An example of the remarks data structure: 521 "remarks" : 522 [ 523 { 524 "type" : "object truncated due to authorization", 525 "description" : 526 [ 527 "Some registration data may not have been given.", 528 "Use proper authorization credentials to see all of it." 529 ] 530 } 531 ] 533 Figure 9 535 While the "remarks" array will appear in many object classes in a 536 response, the "notices" array appears only in the topmost object of a 537 response. 539 4.4. Language Identifier 541 This data structure consists solely of a name/value pair, where the 542 name is "lang" and the value is a string containing a language 543 identifier as described in [RFC5646]. 545 "lang" : "mn-Cyrl-MN" 547 Figure 10 549 The "lang" attribute as defined in this section MAY appear anywhere 550 in an object class or data structure, except for in jCard objects. 551 vCard supports similar functionality by way of the LANGUAGE property 552 parameter (see Section 5.1 of RFC 6350 [RFC6350]). 554 4.5. Events 556 This data structure represents events that have occurred on an 557 instance of an object class (see Section 5 regarding object classes). 559 This is an example of an "events" array. 561 "events" : 562 [ 563 { 564 "eventAction" : "registration", 565 "eventActor" : "SOMEID-LUNARNIC", 566 "eventDate" : "1990-12-31T23:59:59Z" 567 }, 568 { 569 "eventAction" : "last changed", 570 "eventActor" : "OTHERID-LUNARNIC", 571 "eventDate" : "1991-12-31T23:59:59Z" 572 } 573 ] 575 Figure 11 577 The "events" array consists of objects, each with the following 578 members: 580 * "eventAction" -- a REQUIRED string denoting the reason for the 581 event 583 * "eventActor" -- an OPTIONAL identifier denoting the actor 584 responsible for the event 586 * "eventDate" -- a REQUIRED string containing the time and date the 587 event occurred 589 * "links" -- OPTIONAL; see Section 4.2 591 Events can be future dated. One use case for future dating of events 592 is to denote when an object expires from a registry. 594 The "links" array in this data structure is provided for references 595 to the event actor. In order to reference an RDAP entity, a "rel" of 596 "related" and a "type" of "application/rdap+json" is used in the link 597 reference. 599 See Section 10.2.3 for a list of values for the "eventAction" string. 600 See Appendix B regarding the various ways events can be modeled. 602 4.6. Status 604 This data structure, named "status", is an array of strings 605 indicating the state of a registered object (see Section 10.2.2 for a 606 list of values). 608 4.7. Port 43 WHOIS Server 610 This data structure, a member named "port43", is a simple character 611 string containing the fully qualified host name or IP address of the 612 WHOIS [RFC3912] server where the containing object instance may be 613 found. Note that this is not a URI, as there is no WHOIS URI scheme. 615 4.8. Public IDs 617 This data structure maps a public identifier to an object class. It 618 is named "publicIds" and is an array of objects, with each object 619 containing the following REQUIRED members: 621 * type -- a string denoting the type of public identifier 623 * identifier -- a string denoting a public identifier of the type 624 related to "type" 626 The following is an example of a publicIds structure. 628 "publicIds": 629 [ 630 { 631 "type":"IANA Registrar ID", 632 "identifier":"1" 633 } 634 ] 636 Figure 12 638 4.9. Object Class Name 640 This data structure, a member named "objectClassName", gives the 641 object class name of a particular object as a string. This 642 identifies the type of object being processed. An objectClassName is 643 REQUIRED in all RDAP response objects so that the type of the object 644 can be interpreted. 646 4.10. An Example 648 This is an example response with both rdapConformance and notices 649 embedded: 651 { 652 "rdapConformance" : 653 [ 654 "rdap_level_0" 655 ], 656 "notices" : 657 [ 658 { 659 "title" : "Content Removed", 660 "description" : 661 [ 662 "Without full authorization, content has been removed.", 663 "Sorry, dude!" 664 ], 665 "links" : 666 [ 667 { 668 "value" : "https://example.net/ip/192.0.2.0/24", 669 "rel" : "alternate", 670 "type" : "text/html", 671 "href" : "https://www.example.com/redaction_policy.html" 672 } 673 ] 674 } 675 ], 676 "lang" : "en", 677 "objectClassName" : "ip network", 678 "startAddress" : "192.0.2.0", 679 "endAddress" : "192.0.2.255", 680 "handle" : "XXXX-RIR", 681 "ipVersion" : "v4", 682 "name": "NET-RTR-1", 683 "parentHandle" : "YYYY-RIR", 684 "remarks" : 685 [ 687 { 688 "description" : 689 [ 690 "She sells sea shells down by the sea shore.", 691 "Originally written by Terry Sullivan." 692 ] 693 } 694 ] 695 } 697 Figure 13 699 5. Object Classes 701 Object classes represent structures appropriate for a response from 702 the queries specified in [I-D.ietf-regext-rfc7482bis]. 704 Each object class contains a "links" array as specified in 705 Section 4.2. For every object class instance in a response, whether 706 the object class instance is directly representing the response to a 707 query or is embedded in other object class instances or is an item in 708 a search result set, servers SHOULD provide a link representing a URI 709 for that object class instance using the "self" relationship as 710 described in the IANA registry specified by [RFC8288]. As explained 711 in Section 5.2, this may be not always be possible for nameserver 712 data. Clients MUST be able to process object instances without a 713 self link. When present, clients can use the self link for caching 714 data. Servers MAY provide more than one self link for any given 715 object instance. Failure to provide any self link by a server may 716 result in clients being unable to cache object class instances. 718 Clients using self links for caching SHOULD NOT cache any object 719 class instances where the authority of the self link is different 720 than the authority of the server returning the data. Failing to do 721 so might result in cache poisoning. 723 Self links MUST contain a "type" element containing the "application/ 724 rdap+json" media type when referencing RDAP object instances as 725 defined by this document. 727 This is an example of the "links" array with a self link to an object 728 class: 730 "links" : 731 [ 732 { 733 "value" : "https://example.com/ip/2001:db8::123", 734 "rel" : "self", 735 "href" : "https://example.com/ip/2001:db8::123", 736 "type" : "application/rdap+json" 737 } 738 ] 740 Figure 14 742 5.1. The Entity Object Class 744 The entity object class appears throughout this document and is an 745 appropriate response for the /entity/XXXX query defined in 746 "Registration Data Access Protocol (RDAP) Query Format" 747 [I-D.ietf-regext-rfc7482bis]. This object class represents the 748 information of organizations, corporations, governments, non-profits, 749 clubs, individual persons, and informal groups of people. All of 750 these representations are so similar that it is best to represent 751 them in JSON [RFC8259] with one construct, the entity object class, 752 to aid in the reuse of code by implementers. 754 The entity object class uses jCard [RFC7095] to represent contact 755 information, such as postal addresses, email addresses, phone numbers 756 and names of organizations and individuals. Many of the types of 757 information that can be represented with jCard have little or no use 758 in RDAP, such as birthdays, anniversaries, and gender. 760 The entity object is served by both RIRs and DNRs. The following is 761 an example of an entity that might be served by an RIR. 763 { 764 "objectClassName" : "entity", 765 "handle":"XXXX", 766 "vcardArray":[ 767 "vcard", 768 [ 769 ["version", {}, "text", "4.0"], 770 ["fn", {}, "text", "Joe User"], 771 ["n", {}, "text", 772 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 773 ], 774 ["kind", {}, "text", "individual"], 775 ["lang", { 776 "pref":"1" 777 }, "language-tag", "fr"], 778 ["lang", { 779 "pref":"2" 780 }, "language-tag", "en"], 781 ["org", { 782 "type":"work" 783 }, "text", "Example"], 784 ["title", {}, "text", "Research Scientist"], 785 ["role", {}, "text", "Project Lead"], 786 ["adr", 787 { "type":"work" }, 788 "text", 789 [ 790 "", 791 "Suite 1234", 792 "4321 Rue Somewhere", 793 "Quebec", 794 "QC", 795 "G1V 2M2", 796 "Canada" 797 ] 798 ], 799 ["adr", 800 { 801 "type":"home", 802 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 803 }, 804 "text", 805 [ 806 "", "", "", "", "", "", "" 807 ] 808 ], 809 ["tel", 810 { 811 "type":["work", "voice"], 812 "pref":"1" 813 }, 814 "uri", 815 "tel:+1-555-555-1234;ext=102" 816 ], 817 ["tel", 818 { "type":["work", "cell", "voice", "video", "text"] }, 819 "uri", 820 "tel:+1-555-555-4321" 821 ], 822 ["email", 823 { "type":"work" }, 824 "text", 825 "joe.user@example.com" 826 ], 827 ["geo", { 828 "type":"work" 829 }, "uri", "geo:46.772673,-71.282945"], 830 ["key", 831 { "type":"work" }, 832 "uri", 833 "https://www.example.com/joe.user/joe.asc" 834 ], 835 ["tz", {}, 836 "utc-offset", "-05:00"], 837 ["url", { "type":"home" }, 838 "uri", "https://example.org"] 839 ] 840 ], 841 "roles":[ "registrar" ], 842 "publicIds":[ 843 { 844 "type":"IANA Registrar ID", 845 "identifier":"1" 846 } 847 ], 848 "remarks":[ 849 { 850 "description":[ 851 "She sells sea shells down by the sea shore.", 852 "Originally written by Terry Sullivan." 853 ] 854 } 855 ], 856 "links":[ 857 { 858 "value":"https://example.com/entity/XXXX", 859 "rel":"self", 860 "href":"https://example.com/entity/XXXX", 861 "type" : "application/rdap+json" 862 } 863 ], 864 "events":[ 865 { 866 "eventAction":"registration", 867 "eventDate":"1990-12-31T23:59:59Z" 868 } 869 ], 870 "asEventActor":[ 872 { 873 "eventAction":"last changed", 874 "eventDate":"1991-12-31T23:59:59Z" 875 } 876 ] 877 } 879 Figure 15 881 The entity object class can contain the following members: 883 * objectClassName -- the string "entity" 884 * handle -- a string representing a registry-unique identifier of 885 the entity 887 * vcardArray -- a jCard with the entity's contact information 889 * roles -- an array of strings, each signifying the relationship an 890 object would have with its closest containing object (see 891 Section 10.2.4 for a list of values) 893 * publicIds -- see Section 4.8 895 * entities -- an array of entity objects as defined by this section 897 * remarks -- see Section 4.3 899 * links -- see Section 4.2 901 * events -- see Section 4.5 903 * asEventActor -- this data structure takes the same form as the 904 events data structure (see Section 4.5), but each object in the 905 array MUST NOT have an "eventActor" member. These objects denote 906 that the entity is an event actor for the given events. See 907 Appendix B regarding the various ways events can be modeled. 909 * status -- see Section 4.6 911 * port43 -- see Section 4.7 913 * networks -- an array of IP network objects as defined in 914 Section 5.4 916 * autnums -- an array of autnum objects as defined in Section 5.5 918 Entities may also have other entities embedded with them in an array. 919 This can be used to model an organization with specific individuals 920 fulfilling designated roles of responsibility. 922 The following is an elided example of an entity with embedded 923 entities. 925 { 926 "objectClassName" : "entity", 927 "handle" : "ANENTITY", 928 "roles" : [ "registrar" ], 929 ... 930 "entities" : 931 [ 932 { 933 "objectClassName" : "entity", 934 "handle": "ANEMBEDDEDENTITY", 935 "roles" : [ "technical" ], 936 ... 937 }, 938 ... 939 ], 940 ... 941 } 943 Figure 16 945 The following is an example of an entity that might be served by a 946 DNR. 948 { 949 "objectClassName" : "entity", 950 "handle":"XXXX", 951 "vcardArray":[ 952 "vcard", 953 [ 954 ["version", {}, "text", "4.0"], 955 ["fn", {}, "text", "Joe User"], 956 ["kind", {}, "text", "individual"], 957 ["lang", { 958 "pref":"1" 959 }, "language-tag", "fr"], 960 ["lang", { 961 "pref":"2" 962 }, "language-tag", "en"], 963 ["org", { 964 "type":"work" 965 }, "text", "Example"], 966 ["title", {}, "text", "Research Scientist"], 967 ["role", {}, "text", "Project Lead"], 968 ["adr", 969 { "type":"work" }, 970 "text", 971 [ 972 "", 973 "Suite 1234", 974 "4321 Rue Somewhere", 975 "Quebec", 976 "QC", 977 "G1V 2M2", 978 "Canada" 979 ] 980 ], 981 ["tel", 982 { "type":["work", "voice"], "pref":"1" }, 983 "uri", "tel:+1-555-555-1234;ext=102" 984 ], 985 ["email", 986 { "type":"work" }, 987 "text", "joe.user@example.com" 988 ] 989 ] 990 ], 991 "status":[ "validated", "locked" ], 992 "remarks":[ 993 { 994 "description":[ 995 "She sells sea shells down by the sea shore.", 996 "Originally written by Terry Sullivan." 997 ] 998 } 999 ], 1000 "links":[ 1001 { 1002 "value":"https://example.com/entity/XXXX", 1003 "rel":"self", 1004 "href":"https://example.com/entity/XXXX", 1005 "type":"application/rdap+json" 1006 } 1007 ], 1008 "port43":"whois.example.net", 1009 "events":[ 1010 { 1011 "eventAction":"registration", 1012 "eventDate":"1990-12-31T23:59:59Z" 1013 }, 1014 { 1015 "eventAction":"last changed", 1016 "eventDate":"1991-12-31T23:59:59Z", 1017 "eventActor":"joe@example.com" 1018 } 1019 ] 1020 } 1021 Figure 17 1023 See Appendix A for use of the entity object class to model various 1024 types of entities found in both RIRs and DNRs. See Appendix C 1025 regarding structured vs. unstructured postal addresses in entities. 1027 5.2. The Nameserver Object Class 1029 The nameserver object class represents information regarding DNS 1030 nameservers used in both forward and reverse DNS. RIRs and some DNRs 1031 register or expose nameserver information as an attribute of a domain 1032 name, while other DNRs model nameservers as "first class objects". 1033 Please note that some of the examples in this section include lines 1034 that have been wrapped for reading clarity. 1036 The nameserver object class accommodates both models and degrees of 1037 variation in between. 1039 The following is an example of a nameserver object. 1041 { 1042 "objectClassName" : "nameserver", 1043 "handle" : "XXXX", 1044 "ldhName" : "ns1.xn--fo-5ja.example", 1045 "unicodeName" : "ns.fóo.example", 1046 "status" : [ "active" ], 1047 "ipAddresses" : 1048 { 1049 "v4": [ "192.0.2.1", "192.0.2.2" ], 1050 "v6": [ "2001:db8::123" ] 1051 }, 1052 "remarks" : 1053 [ 1054 { 1055 "description" : 1056 [ 1057 "She sells sea shells down by the sea shore.", 1058 "Originally written by Terry Sullivan." 1059 ] 1060 } 1061 ], 1062 "links" : 1063 [ 1064 { 1065 "value" : "https://example.net/nameserver/ 1066 ns1.xn--fo-5ja.example", 1067 "rel" : "self", 1068 "href" : "https://example.net/nameserver/ 1069 ns1.xn--fo-5ja.example", 1070 "type" : "application/rdap+json" 1071 } 1072 ], 1073 "port43" : "whois.example.net", 1074 "events" : 1075 [ 1076 { 1077 "eventAction" : "registration", 1078 "eventDate" : "1990-12-31T23:59:59Z" 1079 }, 1080 { 1081 "eventAction" : "last changed", 1082 "eventDate" : "1991-12-31T23:59:59Z", 1083 "eventActor" : "joe@example.com" 1084 } 1085 ] 1086 } 1088 Figure 18 1090 Figure 18 is an example of a nameserver object with all appropriate 1091 values given. Registries using a first-class nameserver data model 1092 would embed this in domain objects as well as allowing references to 1093 it with the "/nameserver" query type (all depending on the registry 1094 operators policy). Other registries may pare back the information as 1095 needed. Figure 19 is an example of a nameserver object as would be 1096 found in RIRs and some DNRs, while Figure 20 is an example of a 1097 nameserver object as would be found in other DNRs. 1099 The following is an example of the simplest nameserver object: 1101 { 1102 "objectClassName" : "nameserver", 1103 "ldhName" : "ns1.example.com" 1104 } 1106 Figure 19 1108 The following is an example of a simple nameserver object that might 1109 be commonly used by DNRs: 1111 { 1112 "objectClassName" : "nameserver", 1113 "ldhName" : "ns1.example.com", 1114 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 1115 } 1117 Figure 20 1119 As nameservers can be modeled by some registries to be first-class 1120 objects, they may also have an array of entities (Section 5.1) 1121 embedded to signify parties responsible for the maintenance, 1122 registrations, etc., of the nameservers. 1124 The following is an elided example of a nameserver with embedded 1125 entities. 1127 { 1128 "objectClassName" : "nameserver", 1129 "handle" : "XXXX", 1130 "ldhName" : "ns.xn--fo-5ja.example", 1131 ... 1132 "entities" : 1133 [ 1134 ... 1135 ], 1136 ... 1137 } 1138 Figure 21 1140 The nameserver object class can contain the following members: 1142 * objectClassName -- the string "nameserver" 1144 * handle -- a string representing a registry-unique identifier of 1145 the nameserver 1147 * ldhName -- a string containing the LDH name of the nameserver (see 1148 Section 3) 1150 * unicodeName -- a string containing a DNS Unicode name of the 1151 nameserver (see Section 3) 1153 * ipAddresses -- an object containing the following members: 1155 - v6 -- an array of strings containing IPv6 addresses of the 1156 nameserver 1158 - v4 -- an array of strings containing IPv4 addresses of the 1159 nameserver 1161 * entities -- an array of entity objects as defined by Section 5.1 1163 * status -- see Section 4.6 1165 * remarks -- see Section 4.3 1167 * links -- see Section 4.2 1169 * port43 -- see Section 4.7 1171 * events -- see Section 4.5 1173 5.3. The Domain Object Class 1175 The domain object class represents a DNS name and point of 1176 delegation. For RIRs, these delegation points are in the reverse DNS 1177 tree, whereas for DNRs, these delegation points are in the forward 1178 DNS tree. 1180 In both cases, the high-level structure of the domain object class 1181 consists of information about the domain registration, nameserver 1182 information related to the domain name, and entities related to the 1183 domain name (e.g., registrant information, contacts, etc.). 1185 The following is an elided example of the domain object showing the 1186 high-level structure: 1188 { 1189 "objectClassName" : "domain", 1190 "handle" : "XXX", 1191 "ldhName" : "blah.example.com", 1192 ... 1193 "nameservers" : 1194 [ 1195 ... 1196 ], 1197 ... 1198 "entities" : 1199 [ 1200 ... 1201 ] 1202 } 1204 Figure 22 1206 The domain object class can contain the following members: 1208 * objectClassName -- the string "domain" 1210 * handle -- a string representing a registry-unique identifier of 1211 the domain object instance 1213 * ldhName -- a string describing a domain name in LDH form as 1214 described in Section 3 1216 * unicodeName -- a string containing a domain name with U-labels as 1217 described in Section 3 1219 * variants -- an array of objects, each containing the following 1220 values: 1222 - relation -- an array of strings, with each string denoting the 1223 relationship between the variants and the containing domain 1224 object (see Section 10.2.5 for a list of suggested variant 1225 relations). 1227 - idnTable -- the character string literal that represents the 1228 Internationalized Domain Name (IDN) table that has been 1229 registered in the IANA Repository of IDN Practices 1230 [IANA_IDNTABLES]. 1232 - variantNames -- an array of objects, with each object 1233 containing an "ldhName" member and a "unicodeName" member (see 1234 Section 3). 1236 * nameservers -- an array of nameserver objects as defined by 1237 Section 5.2 1239 * secureDNS -- an object with the following members: 1241 - zoneSigned -- boolean true if the zone has been signed, false 1242 otherwise. 1244 - delegationSigned -- boolean true if there are DS records in the 1245 parent, false otherwise. 1247 - maxSigLife -- an integer representing the signature lifetime in 1248 seconds to be used when creating the RRSIG DS record in the 1249 parent zone [RFC5910]. 1251 - dsData -- an array of objects, each with the following members: 1253 o keyTag -- an integer as specified by the key tag field of a 1254 DNS DS record as specified by [RFC4034] in presentation 1255 format 1257 o algorithm -- an integer as specified by the algorithm field 1258 of a DNS DS record as described by RFC 4034 in presentation 1259 format 1261 o digest -- a string as specified by the digest field of a DNS 1262 DS record as specified by RFC 4034 in presentation format 1264 o digestType -- an integer as specified by the digest type 1265 field of a DNS DS record as specified by RFC 4034 in 1266 presentation format 1268 o events -- see Section 4.5 1270 o links -- see Section 4.2 1272 - keyData -- an array of objects, each with the following 1273 members: 1275 o flags -- an integer representing the flags field value in 1276 the DNSKEY record [RFC4034] in presentation format 1278 o protocol -- an integer representation of the protocol field 1279 value of the DNSKEY record [RFC4034] in presentation format 1281 o publicKey -- a string representation of the public key in 1282 the DNSKEY record [RFC4034] in presentation format 1284 o algorithm -- an integer as specified by the algorithm field 1285 of a DNSKEY record as specified by [RFC4034] in presentation 1286 format 1288 o events -- see Section 4.5 1290 o links -- see Section 4.2 1292 See Appendix D for background information on these 1293 objects. 1295 * entities -- an array of entity objects as defined by Section 5.1 1297 * status -- see Section 4.6 1299 * publicIds -- see Section 4.8 1301 * remarks -- see Section 4.3 1303 * links -- see Section 4.2 1305 * port43 -- see Section 4.7 1307 * events -- see Section 4.5 1309 * network -- represents the IP network for which a reverse DNS 1310 domain is referenced; see Section 5.4 1312 The following is an example of a JSON domain object representing a 1313 reverse DNS delegation point that might be served by an RIR (note 1314 that the dsData digest value has been modified to fit on one line). 1316 { 1317 "objectClassName" : "domain", 1318 "handle" : "XXXX", 1319 "ldhName" : "0.2.192.in-addr.arpa", 1320 "nameservers" : 1321 [ 1322 { 1323 "objectClassName" : "nameserver", 1324 "ldhName" : "ns1.rir.example" 1325 }, 1326 { 1327 "objectClassName" : "nameserver", 1328 "ldhName" : "ns2.rir.example" 1330 } 1331 ], 1332 "secureDNS": 1333 { 1334 "delegationSigned": true, 1335 "dsData": 1336 [ 1337 { 1338 "keyTag": 25345, 1339 "algorithm": 8, 1340 "digestType": 2, 1341 "digest": "2788970E18EA14...C890C85B8205B94" 1342 } 1343 ] 1344 }, 1345 "remarks" : 1346 [ 1347 { 1348 "description" : 1349 [ 1350 "She sells sea shells down by the sea shore.", 1351 "Originally written by Terry Sullivan." 1352 ] 1353 } 1354 ], 1355 "links" : 1356 [ 1357 { 1358 "value": "https://example.net/domain/0.2.192.in-addr.arpa", 1359 "rel" : "self", 1360 "href" : "https://example.net/domain/0.2.192.in-addr.arpa", 1361 "type" : "application/rdap+json" 1363 } 1364 ], 1365 "events" : 1366 [ 1367 { 1368 "eventAction" : "registration", 1369 "eventDate" : "1990-12-31T23:59:59Z" 1370 }, 1371 { 1372 "eventAction" : "last changed", 1373 "eventDate" : "1991-12-31T23:59:59Z", 1374 "eventActor" : "joe@example.com" 1375 } 1376 ], 1377 "entities" : 1379 [ 1380 { 1381 "objectClassName" : "entity", 1382 "handle" : "XXXX", 1383 "vcardArray":[ 1384 "vcard", 1385 [ 1386 ["version", {}, "text", "4.0"], 1387 ["fn", {}, "text", "Joe User"], 1388 ["kind", {}, "text", "individual"], 1389 ["lang", { 1390 "pref":"1" 1391 }, "language-tag", "fr"], 1392 ["lang", { 1393 "pref":"2" 1394 }, "language-tag", "en"], 1395 ["org", { 1396 "type":"work" 1397 }, "text", "Example"], 1398 ["title", {}, "text", "Research Scientist"], 1399 ["role", {}, "text", "Project Lead"], 1400 ["adr", 1401 { "type":"work" }, 1402 "text", 1403 [ 1404 "", 1405 "Suite 1234", 1406 "4321 Rue Somewhere", 1407 "Quebec", 1408 "QC", 1409 "G1V 2M2", 1410 "Canada" 1411 ] 1413 ], 1414 ["tel", 1415 { "type":["work", "voice"], "pref":"1" }, 1416 "uri", "tel:+1-555-555-1234;ext=102" 1417 ], 1418 ["email", 1419 { "type":"work" }, 1420 "text", "joe.user@example.com" 1421 ] 1422 ] 1423 ], 1424 "roles" : [ "registrant" ], 1425 "remarks" : 1426 [ 1427 { 1428 "description" : 1429 [ 1430 "She sells sea shells down by the sea shore.", 1431 "Originally written by Terry Sullivan." 1432 ] 1433 } 1434 ], 1435 "links" : 1436 [ 1437 { 1438 "value": "https://example.net/entity/XXXX", 1439 "rel" : "self", 1440 "href" : "https://example.net/entity/XXXX", 1441 "type" : "application/rdap+json" 1442 } 1443 ], 1444 "events" : 1445 [ 1446 { 1447 "eventAction" : "registration", 1448 "eventDate" : "1990-12-31T23:59:59Z" 1449 }, 1450 { 1451 "eventAction" : "last changed", 1452 "eventDate" : "1991-12-31T23:59:59Z", 1453 "eventActor" : "joe@example.com" 1454 } 1455 ] 1456 } 1457 ], 1458 "network" : 1459 { 1460 "objectClassName" : "ip network", 1461 "handle" : "XXXX-RIR", 1462 "startAddress" : "192.0.2.0", 1463 "endAddress" : "192.0.2.255", 1464 "ipVersion" : "v4", 1465 "name": "NET-RTR-1", 1466 "type" : "DIRECT ALLOCATION", 1467 "country" : "AU", 1468 "parentHandle" : "YYYY-RIR", 1469 "status" : [ "active" ] 1470 } 1471 } 1473 Figure 23 1475 The following is an example of a JSON domain object representing a 1476 forward DNS delegation point that might be served by a DNR. Note 1477 that the secureDNS keyData publicKey value has been modified to fit 1478 on a single line. 1480 { 1481 "objectClassName" : "domain", 1482 "handle" : "XXXX", 1483 "ldhName" : "xn--fo-5ja.example", 1484 "unicodeName" : "fóo.example", 1485 "variants" : 1486 [ 1487 { 1488 "relation" : [ "registered", "conjoined" ], 1489 "variantNames" : 1490 [ 1491 { 1492 "ldhName" : "xn--fo-cka.example", 1493 "unicodeName" : "fõo.example" 1494 }, 1495 { 1496 "ldhName" : "xn--fo-fka.example", 1497 "unicodeName" : "föo.example" 1498 } 1499 ] 1500 }, 1501 { 1502 "relation" : [ "unregistered", "registration restricted" ], 1503 "idnTable": ".EXAMPLE Swedish", 1504 "variantNames" : 1505 [ 1506 { 1507 "ldhName": "xn--fo-8ja.example", 1508 "unicodeName" : "fôo.example" 1509 } 1510 ] 1512 } 1513 ], 1514 "status" : [ "locked", "transfer prohibited" ], 1515 "publicIds":[ 1516 { 1517 "type":"ENS_Auth ID", 1518 "identifier":"1234567890" 1519 } 1520 ], 1521 "nameservers" : 1522 [ 1523 { 1524 "objectClassName" : "nameserver", 1525 "handle" : "XXXX", 1526 "ldhName" : "ns1.example.com", 1527 "status" : [ "active" ], 1528 "ipAddresses" : 1529 { 1530 "v6": [ "2001:db8::123", "2001:db8::124" ], 1531 "v4": [ "192.0.2.1", "192.0.2.2" ] 1532 }, 1533 "remarks" : 1534 [ 1535 { 1536 "description" : 1537 [ 1538 "She sells sea shells down by the sea shore.", 1539 "Originally written by Terry Sullivan." 1540 ] 1541 } 1542 ], 1543 "links" : 1544 [ 1545 { 1546 "value" : "https://example.net/nameserver/ns1.example.com", 1547 "rel" : "self", 1548 "href" : "https://example.net/nameserver/ns1.example.com", 1549 "type" : "application/rdap+json" 1550 } 1551 ], 1552 "events" : 1553 [ 1554 { 1555 "eventAction" : "registration", 1556 "eventDate" : "1990-12-31T23:59:59Z" 1557 }, 1558 { 1559 "eventAction" : "last changed", 1560 "eventDate" : "1991-12-31T23:59:59Z" 1561 } 1562 ] 1563 }, 1564 { 1565 "objectClassName" : "nameserver", 1566 "handle" : "XXXX", 1567 "ldhName" : "ns2.example.com", 1568 "status" : [ "active" ], 1569 "ipAddresses" : 1570 { 1571 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1572 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1573 }, 1574 "remarks" : 1575 [ 1576 { 1577 "description" : 1578 [ 1579 "She sells sea shells down by the sea shore.", 1580 "Originally written by Terry Sullivan." 1581 ] 1582 } 1583 ], 1584 "links" : 1585 [ 1586 { 1587 "value" : "https://example.net/nameserver/ns2.example.com", 1588 "rel" : "self", 1589 "href" : "https://example.net/nameserver/ns2.example.com", 1590 "type" : "application/rdap+json" 1591 } 1592 ], 1593 "events" : 1594 [ 1595 { 1596 "eventAction" : "registration", 1597 "eventDate" : "1990-12-31T23:59:59Z" 1598 }, 1599 { 1600 "eventAction" : "last changed", 1601 "eventDate" : "1991-12-31T23:59:59Z" 1602 } 1603 ] 1604 } 1605 ], 1606 "secureDNS": 1607 { 1609 "zoneSigned": true, 1610 "delegationSigned": true, 1611 "maxSigLife": 604800, 1612 "keyData": 1613 [ 1614 { 1615 "flags": 257, 1616 "protocol": 3, 1617 "algorithm": 8, 1618 "publicKey": "AwEAAa6eDzronzjEDbT...Jg1M5N rBSPkuXpdFE=", 1619 "events": 1620 [ 1621 { 1622 "eventAction": "last changed", 1623 "eventDate": "2012-07-23T05:15:47Z" 1624 } 1625 ] 1626 } 1627 ] 1628 }, 1629 "remarks" : 1630 [ 1631 { 1632 "description" : 1633 [ 1634 "She sells sea shells down by the sea shore.", 1635 "Originally written by Terry Sullivan." 1636 ] 1637 } 1638 ], 1639 "links" : 1640 [ 1641 { 1642 "value": "https://example.net/domain/xn--fo-5ja.example", 1643 "rel" : "self", 1644 "href" : "https://example.net/domain/xn--fo-5ja.example", 1645 "type" : "application/rdap+json" 1646 } 1647 ], 1648 "port43" : "whois.example.net", 1649 "events" : 1650 [ 1651 { 1652 "eventAction" : "registration", 1653 "eventDate" : "1990-12-31T23:59:59Z" 1654 }, 1655 { 1656 "eventAction" : "last changed", 1657 "eventDate" : "1991-12-31T23:59:59Z", 1658 "eventActor" : "joe@example.com" 1659 }, 1660 { 1661 "eventAction" : "transfer", 1662 "eventDate" : "1991-12-31T23:59:59Z", 1663 "eventActor" : "joe@example.com" 1664 }, 1665 { 1666 "eventAction" : "expiration", 1667 "eventDate" : "2016-12-31T23:59:59Z", 1668 "eventActor" : "joe@example.com" 1669 } 1670 ], 1671 "entities" : 1672 [ 1673 { 1674 "objectClassName" : "entity", 1675 "handle" : "XXXX", 1676 "vcardArray":[ 1677 "vcard", 1678 [ 1679 ["version", {}, "text", "4.0"], 1680 ["fn", {}, "text", "Joe User"], 1681 ["kind", {}, "text", "individual"], 1682 ["lang", { 1683 "pref":"1" 1684 }, "language-tag", "fr"], 1685 ["lang", { 1686 "pref":"2" 1687 }, "language-tag", "en"], 1688 ["org", { 1689 "type":"work" 1690 }, "text", "Example"], 1691 ["title", {}, "text", "Research Scientist"], 1692 ["role", {}, "text", "Project Lead"], 1693 ["adr", 1694 { "type":"work" }, 1695 "text", 1696 [ 1697 "", 1698 "Suite 1234", 1699 "4321 Rue Somewhere", 1700 "Quebec", 1701 "QC", 1702 "G1V 2M2", 1703 "Canada" 1704 ] 1706 ], 1707 ["tel", 1708 { "type":["work", "voice"], "pref":"1" }, 1709 "uri", "tel:+1-555-555-1234;ext=102" 1710 ], 1711 ["email", 1712 { "type":"work" }, 1713 "text", "joe.user@example.com" 1714 ] 1716 ] 1717 ], 1718 "status" : [ "validated", "locked" ], 1719 "roles" : [ "registrant" ], 1720 "remarks" : 1721 [ 1722 { 1723 "description" : 1724 [ 1725 "She sells sea shells down by the sea shore.", 1726 "Originally written by Terry Sullivan." 1727 ] 1728 } 1729 ], 1730 "links" : 1731 [ 1732 { 1733 "value" : "https://example.net/entity/XXXX", 1734 "rel" : "self", 1735 "href" : "https://example.net/entity/XXXX", 1736 "type" : "application/rdap+json" 1737 } 1738 ], 1739 "events" : 1740 [ 1741 { 1742 "eventAction" : "registration", 1743 "eventDate" : "1990-12-31T23:59:59Z" 1744 }, 1745 { 1746 "eventAction" : "last changed", 1747 "eventDate" : "1991-12-31T23:59:59Z" 1748 } 1749 ] 1750 } 1751 ] 1752 } 1754 Figure 24 1756 5.4. The IP Network Object Class 1758 The IP network object class models IP network registrations found in 1759 RIRs and is the expected response for the "/ip" query as defined by 1760 [I-D.ietf-regext-rfc7482bis]. There is no equivalent object class 1761 for DNRs. The high- level structure of the IP network object class 1762 consists of information about the network registration and entities 1763 related to the IP network (e.g., registrant information, contacts, 1764 etc.). 1766 The following is an elided example of the IP network object type 1767 showing the high-level structure: 1769 { 1770 "objectClassName" : "ip network", 1771 "handle" : "XXX", 1772 ... 1773 "entities" : 1774 [ 1775 ... 1776 ] 1777 } 1779 Figure 25 1781 The following is an example of the JSON object for the network 1782 registration information. 1784 { 1785 "objectClassName" : "ip network", 1786 "handle" : "XXXX-RIR", 1787 "startAddress" : "2001:db8::", 1788 "endAddress" : "2001:db8:0:ffff:ffff:ffff:ffff:ffff", 1789 "ipVersion" : "v6", 1790 "name": "NET-RTR-1", 1791 "type" : "DIRECT ALLOCATION", 1792 "country" : "AU", 1793 "parentHandle" : "YYYY-RIR", 1794 "status" : [ "active" ], 1795 "remarks" : 1796 [ 1797 { 1798 "description" : 1799 [ 1800 "She sells sea shells down by the sea shore.", 1801 "Originally written by Terry Sullivan." 1802 ] 1803 } 1805 ], 1806 "links" : 1807 [ 1808 { 1809 "value" : "https://example.net/ip/2001:db8::/48", 1810 "rel" : "self", 1811 "href" : "https://example.net/ip/2001:db8::/48", 1812 "type" : "application/rdap+json" 1813 }, 1814 { 1815 "value" : "https://example.net/ip/2001:db8::/48", 1816 "rel" : "up", 1817 "href" : "https://example.net/ip/2001:db8::/32", 1818 "type" : "application/rdap+json" 1819 } 1820 ], 1821 "events" : 1822 [ 1823 { 1824 "eventAction" : "registration", 1825 "eventDate" : "1990-12-31T23:59:59Z" 1826 }, 1827 { 1828 "eventAction" : "last changed", 1829 "eventDate" : "1991-12-31T23:59:59Z" 1830 } 1831 ], 1832 "entities" : 1833 [ 1834 { 1835 "objectClassName" : "entity", 1836 "handle" : "XXXX", 1837 "vcardArray":[ 1838 "vcard", 1839 [ 1840 ["version", {}, "text", "4.0"], 1841 ["fn", {}, "text", "Joe User"], 1842 ["kind", {}, "text", "individual"], 1843 ["lang", { 1844 "pref":"1" 1845 }, "language-tag", "fr"], 1846 ["lang", { 1847 "pref":"2" 1848 }, "language-tag", "en"], 1849 ["org", { 1850 "type":"work" 1851 }, "text", "Example"], 1852 ["title", {}, "text", "Research Scientist"], 1854 ["role", {}, "text", "Project Lead"], 1855 ["adr", 1856 { "type":"work" }, 1857 "text", 1858 [ 1859 "", 1860 "Suite 1234", 1861 "4321 Rue Somewhere", 1862 "Quebec", 1863 "QC", 1864 "G1V 2M2", 1865 "Canada" 1866 ] 1867 ], 1868 ["tel", 1869 { "type":["work", "voice"], "pref":"1" }, 1870 "uri", "tel:+1-555-555-1234;ext=102" 1871 ], 1872 ["email", 1873 { "type":"work" }, 1874 "text", "joe.user@example.com" 1875 ] 1876 ] 1877 ], 1878 "roles" : [ "registrant" ], 1879 "remarks" : 1880 [ 1881 { 1882 "description" : 1883 [ 1884 "She sells sea shells down by the sea shore.", 1885 "Originally written by Terry Sullivan." 1886 ] 1887 } 1888 ], 1889 "links" : 1890 [ 1891 { 1892 "value" : "https://example.net/entity/xxxx", 1893 "rel" : "self", 1894 "href" : "https://example.net/entity/xxxx", 1895 "type" : "application/rdap+json" 1896 } 1897 ], 1898 "events" : 1899 [ 1900 { 1901 "eventAction" : "registration", 1902 "eventDate" : "1990-12-31T23:59:59Z" 1904 }, 1905 { 1906 "eventAction" : "last changed", 1907 "eventDate" : "1991-12-31T23:59:59Z" 1908 } 1909 ] 1910 } 1911 ] 1912 } 1914 Figure 26 1916 The IP network object class can contain the following members: 1918 * objectClassName -- the string "ip network" 1920 * handle -- a string representing the RIR-unique identifier of the 1921 network registration 1923 * startAddress -- a string representing the starting IP address of 1924 the network, either IPv4 or IPv6 1926 * endAddress -- a string representing the ending IP address of the 1927 network, either IPv4 or IPv6 1929 * ipVersion -- a string signifying the IP protocol version of the 1930 network: "v4" signifies an IPv4 network, and "v6" signifies an 1931 IPv6 network 1933 * name -- a string representing an identifier assigned to the 1934 network registration by the registration holder 1936 * type -- a string containing an RIR-specific classification of the 1937 network as per that RIR's registration model 1939 * country -- a string containing the two-character country code of 1940 the network 1942 * parentHandle -- a string containing an RIR-unique identifier of 1943 the parent network of this network registration 1945 * status -- an array of strings indicating the state of the IP 1946 network as defined by Section 4.6 1948 * entities -- an array of entity objects as defined by Section 5.1 1949 * remarks -- see Section 4.3 1951 * links -- see Section 4.2 1953 * port43 -- see Section 4.7 1955 * events -- see Section 4.5 1957 5.5. The Autonomous System Number Object Class 1959 The Autonomous System number (autnum) object class models Autonomous 1960 System number registrations found in RIRs and represents the expected 1961 response to an "/autnum" query as defined by 1962 [I-D.ietf-regext-rfc7482bis]. There is no equivalent object class 1963 for DNRs. The high-level structure of the autnum object class 1964 consists of information about the autonomous system number 1965 registration and entities related to the autnum registration (e.g., 1966 registrant information, contacts, etc.) and is similar to the IP 1967 network object class. 1969 The following is an example of a JSON object representing an autnum. 1971 { 1972 "objectClassName" : "autnum", 1973 "handle" : "XXXX-RIR", 1974 "startAutnum" : 65536, 1975 "endAutnum" : 65541, 1976 "name": "AS-RTR-1", 1977 "type" : "DIRECT ALLOCATION", 1978 "status" : [ "active" ], 1979 "country": "AU", 1980 "remarks" : 1981 [ 1982 { 1983 "description" : 1984 [ 1985 "She sells sea shells down by the sea shore.", 1986 "Originally written by Terry Sullivan." 1987 ] 1988 } 1989 ], 1990 "links" : 1991 [ 1992 { 1993 "value" : "https://example.net/autnum/65537", 1994 "rel" : "self", 1995 "href" : "https://example.net/autnum/65537", 1996 "type" : "application/rdap+json" 1998 } 1999 ], 2000 "events" : 2002 [ 2003 { 2004 "eventAction" : "registration", 2005 "eventDate" : "1990-12-31T23:59:59Z" 2006 }, 2007 { 2008 "eventAction" : "last changed", 2009 "eventDate" : "1991-12-31T23:59:59Z" 2010 } 2011 ], 2012 "entities" : 2013 [ 2014 { 2015 "objectClassName" : "entity", 2016 "handle" : "XXXX", 2017 "vcardArray":[ 2018 "vcard", 2019 [ 2020 ["version", {}, "text", "4.0"], 2021 ["fn", {}, "text", "Joe User"], 2022 ["kind", {}, "text", "individual"], 2023 ["lang", { 2024 "pref":"1" 2025 }, "language-tag", "fr"], 2026 ["lang", { 2027 "pref":"2" 2028 }, "language-tag", "en"], 2029 ["org", { 2030 "type":"work" 2031 }, "text", "Example"], 2032 ["title", {}, "text", "Research Scientist"], 2033 ["role", {}, "text", "Project Lead"], 2034 ["adr", 2035 { "type":"work" }, 2036 "text", 2037 [ 2038 "", 2039 "Suite 1234", 2040 "4321 Rue Somewhere", 2041 "Quebec", 2042 "QC", 2043 "G1V 2M2", 2044 "Canada" 2045 ] 2047 ], 2048 ["tel", 2049 { "type":["work", "voice"], "pref":"1" }, 2050 "uri", "tel:+1-555-555-1234;ext=102" 2051 ], 2052 ["email", 2053 { "type":"work" }, 2054 "text", "joe.user@example.com" 2055 ] 2056 ] 2057 ], 2058 "roles" : [ "registrant" ], 2059 "remarks" : 2060 [ 2061 { 2062 "description" : 2063 [ 2064 "She sells sea shells down by the sea shore.", 2065 "Originally written by Terry Sullivan." 2066 ] 2067 } 2068 ], 2069 "links" : 2070 [ 2071 { 2072 "value" : "https://example.net/entity/XXXX", 2073 "rel" : "self", 2074 "href" : "https://example.net/entity/XXXX", 2075 "type" : "application/rdap+json" 2076 } 2077 ], 2078 "events" : 2079 [ 2080 { 2081 "eventAction" : "registration", 2082 "eventDate" : "1990-12-31T23:59:59Z" 2083 }, 2084 { 2085 "eventAction" : "last changed", 2086 "eventDate" : "1991-12-31T23:59:59Z" 2087 } 2088 ] 2089 } 2090 ] 2091 } 2093 Figure 27 2095 The Autonomous System number object class can contain the following 2096 members: 2098 * objectClassName -- the string "autnum" 2100 * handle -- a string representing the RIR-unique identifier of the 2101 autnum registration 2103 * startAutnum -- an unsigned 32-bit integer representing the 2104 starting number [RFC5396] in the block of Autonomous System 2105 numbers 2107 * endAutnum -- an unsigned 32-bit integer representing the ending 2108 number [RFC5396] in the block of Autonomous System numbers 2110 * name -- a string representing an identifier assigned to the autnum 2111 registration by the registration holder 2113 * type -- a string containing an RIR-specific classification of the 2114 autnum as per that RIR's registration model 2116 * status -- an array of strings indicating the state of the autnum 2117 as defined by Section 4.6 2119 * country -- a string containing the two-character country code of 2120 the autnum 2122 * entities -- an array of entity objects as defined by Section 5.1 2124 * remarks -- see Section 4.3 2126 * links -- see Section 4.2 2128 * port43 -- see Section 4.7 2130 * events -- see Section 4.5 2132 6. Error Response Body 2134 Some non-answer responses MAY return entity bodies with information 2135 that could be more descriptive. 2137 The basic structure of that response is an object class containing a 2138 REQUIRED error code number (corresponding to the HTTP response code) 2139 followed by an OPTIONAL string named "title" and an OPTIONAL array of 2140 strings named "description". 2142 This is an example of the common response body. 2144 { 2145 "errorCode": 418, 2146 "title": "Your Beverage Choice is Not Available", 2147 "description": 2148 [ 2149 "I know coffee has more ummppphhh.", 2150 "Sorry, dude!" 2151 ] 2152 } 2154 Figure 28 2156 This is an example of the common response body with an 2157 rdapConformance and notices data structures: 2159 { 2160 "rdapConformance" : 2161 [ 2162 "rdap_level_0" 2163 ], 2164 "notices" : 2165 [ 2166 { 2167 "title" : "Beverage Policy", 2168 "description" : 2169 [ 2170 "Beverages with caffeine for keeping horses awake." 2171 ], 2172 "links" : 2173 [ 2174 { 2175 "value" : "https://example.net/ip/192.0.2.0/24", 2176 "rel" : "alternate", 2177 "type" : "text/html", 2178 "href" : "https://www.example.com/redaction_policy.html" 2179 } 2180 ] 2181 } 2182 ], 2183 "lang" : "en", 2184 "errorCode": 418, 2185 "title": "Your beverage choice is not available", 2186 "description": 2187 [ 2188 "I know coffee has more ummppphhh.", 2189 "Sorry, dude!" 2190 ] 2191 } 2192 Figure 29 2194 7. Responding to Help Queries 2196 The appropriate response to /help queries as defined by 2197 [I-D.ietf-regext-rfc7482bis] is to use the notices structure as 2198 defined in Section 4.3. 2200 This is an example of a response to a /help query including the 2201 rdapConformance data structure. 2203 { 2204 "rdapConformance" : 2205 [ 2206 "rdap_level_0" 2207 ], 2208 "notices" : 2209 [ 2210 { 2211 "title" : "Authentication Policy", 2212 "description" : 2213 [ 2214 "Access to sensitive data for users with proper credentials." 2215 ], 2216 "links" : 2217 [ 2218 { 2219 "value" : "https://example.net/help", 2220 "rel" : "alternate", 2221 "type" : "text/html", 2222 "href" : "https://www.example.com/auth_policy.html" 2223 } 2224 ] 2225 } 2226 ] 2227 } 2229 Figure 30 2231 8. Responding To Searches 2233 [I-D.ietf-regext-rfc7482bis] specifies three types of searches: 2234 domains, nameservers, and entities. Responses to these searches take 2235 the form of an array of object instances where each instance is an 2236 appropriate object class for the search (i.e., a search for /domains 2237 yields an array of domain object instances). These arrays are 2238 contained within the response object. 2240 The names of the arrays are as follows: 2242 * for /domains searches, the array is "domainSearchResults" 2244 * for /nameservers searches, the array is "nameserverSearchResults" 2246 * for /entities searches, the array is "entitySearchResults" 2248 The following is an elided example of a response to a /domains 2249 search. 2251 { 2252 "rdapConformance" : 2253 [ 2254 "rdap_level_0" 2255 ], 2256 ... 2257 "domainSearchResults" : 2258 [ 2259 { 2260 "objectClassName" : "domain", 2261 "handle" : "1-XXXX", 2262 "ldhName" : "1.example.com", 2263 ... 2264 }, 2265 { 2266 "objectClassName" : "domain", 2267 "handle" : "2-XXXX", 2268 "ldhName" : "2.example.com", 2269 ... 2270 } 2271 ] 2272 } 2274 Figure 31 2276 9. Indicating Truncated Responses 2278 In cases where the data of a response needs to be limited or parts of 2279 the data need to be omitted, the response is considered "truncated". 2280 A truncated response is still valid JSON, but some of the results in 2281 a search set or some of the data in an object are not provided by the 2282 server. A server may indicate this by including a typed notice in 2283 the response object. 2285 The following is an elided example of a search response that has been 2286 truncated. 2288 { 2289 "rdapConformance" : 2290 [ 2291 "rdap_level_0" 2292 ], 2293 "notices" : 2294 [ 2295 { 2296 "title" : "Search Policy", 2297 "type" : "result set truncated due to authorization", 2298 "description" : 2299 [ 2300 "Search results are limited to 25 per day per querying IP." 2301 ], 2302 "links" : 2303 [ 2304 { 2305 "value" : "https://example.net/help", 2306 "rel" : "alternate", 2307 "type" : "text/html", 2308 "href" : "https://www.example.com/search_policy.html" 2309 } 2310 ] 2311 } 2312 ], 2313 "domainSearchResults" : 2314 [ 2315 ... 2316 ] 2317 } 2319 Figure 32 2321 A similar technique can be used with a typed remark where a single 2322 object has been returned and data in that object has been truncated. 2323 Such an example might be an entity object with only a partial set of 2324 the IP networks associated with it. 2326 The following is an elided example of an entity truncated data. 2328 { 2329 "objectClassName" : "entity", 2330 "handle" : "ANENTITY", 2331 "roles" : [ "registrant" ], 2332 ... 2333 "entities" : 2334 [ 2335 { 2336 "objectClassName" : "entity", 2337 "handle": "ANEMBEDDEDENTITY", 2338 "roles" : [ "technical" ], 2339 ... 2340 }, 2341 ... 2342 ], 2343 "networks" : 2344 [ 2345 ... 2346 ], 2347 ... 2348 "remarks" : 2349 [ 2350 { 2351 "title" : "Data Policy", 2352 "type" : "object truncated due to unexplainable reason", 2353 "description" : 2354 [ 2355 "Some of the data in this object has been removed." 2356 ], 2357 "links" : 2358 [ 2359 { 2360 "value" : "https://example.net/help", 2361 "rel" : "alternate", 2362 "type" : "text/html", 2363 "href" : "https://www.example.com/data_policy.html" 2364 } 2365 ] 2366 } 2367 ] 2368 } 2370 Figure 33 2372 10. IANA Considerations 2374 IANA is requested to update the description of the "transfer" event 2375 action as described in Section 10.2.3. 2377 10.1. RDAP JSON Media Type Registration 2379 IANA is requested to update the media type registration as described 2380 below. 2382 This specification registers the "application/rdap+json" media 2383 type. 2384 Type name: application 2386 Subtype name: rdap+json 2388 Required parameters: n/a 2390 Encoding considerations: See Section 3.1 of [RFC6839]. 2392 Security considerations: The media represented by this identifier 2393 does not have security considerations beyond that found in 2394 Section 12 of [RFC8259]. 2396 Interoperability considerations: There are no known 2397 interoperability problems regarding this media format. 2399 Published specification: RFC 2401 Applications that use this media type: Implementations of the 2402 Registration Data Access Protocol (RDAP). 2404 Additional information: This media type is a product of the IETF 2405 REGEXT working group. The REGEXT charter, information on the 2406 REGEXT mailing list, and other documents produced by the REGEXT 2407 working group can be found at https://datatracker.ietf.org/wg/ 2408 regext/. 2410 Person & email address to contact for further information: IESG 2411 2413 Intended usage: COMMON 2415 Restrictions on usage: none 2417 Author: Andy Newton 2419 Change controller: IETF 2421 Provisional Registration: No (upon publication of this RFC) 2423 10.2. JSON Values Registry 2425 IANA has created a category in the protocol registries labeled 2426 "Registration Data Access Protocol (RDAP)", and within that category, 2427 IANA has established a URL-referenceable, stand-alone registry 2428 labeled "RDAP JSON Values". This new registry is for use in the 2429 notices and remarks (Section 4.3), status (Section 4.6), role 2430 (Section 5.1), event action (Section 4.5), and domain variant 2431 relation (Section 5.3) fields specified in RDAP. 2433 Each entry in the registry contains the following fields: 2435 1. Value -- the string value being registered. 2437 2. Type -- the type of value being registered. It should be one of 2438 the following: 2440 * "notice or remark type" -- denotes a type of notice or remark. 2442 * "status" -- denotes a value for the "status" object member as 2443 defined by Section 4.6. 2445 * "role" -- denotes a value for the "role" array as defined in 2446 Section 5.1. 2448 * "event action" -- denotes a value for an event action as 2449 defined in Section 4.5. 2451 * "domain variant relation" -- denotes a relationship between a 2452 domain and a domain variant as defined in Section 5.3. 2454 3. Description -- a one- or two-sentence description regarding the 2455 meaning of the value, how it might be used, and/or how it should 2456 be interpreted by clients. 2458 4. Registrant Name -- the name of the person registering the value. 2460 5. Registrant Contact Information -- an email address, postal 2461 address, or some other information to be used to contact the 2462 registrant. 2464 This registry is operated under the "Expert Review" policy defined in 2465 [RFC8126]. 2467 Review of registrations into this registry by the designated 2468 expert(s) should be narrowly judged on the following criteria: 2470 1. Values in need of being placed into multiple types must be 2471 assigned a separate registration for each type. 2473 2. Values must be strings. They should be multiple words separated 2474 by single space characters. Every character should be 2475 lowercased. If possible, every word should be given in English 2476 and each character should be US-ASCII. 2478 3. Registrations should not duplicate the meaning of any existing 2479 registration. That is, if a request for a registration is 2480 significantly similar in nature to an existing registration, the 2481 request should be denied. For example, the terms "maintainer" 2482 and "registrant" are significantly similar in nature as they both 2483 denote a holder of a domain name or Internet number resource. In 2484 cases where it may be reasonably argued that machine 2485 interpretation of two similar values may alter the operation of 2486 client software, designated experts should not judge the values 2487 to be of significant similarity. 2489 4. Registrations should be relevant to the common usages of RDAP. 2490 Designated experts may rely upon the serving of the value by a 2491 DNR or RIR to make this determination. 2493 The following sections provide initial registrations into this 2494 registry. 2496 10.2.1. Notice and Remark Types 2498 The following values have been registered in the "RDAP JSON Values" 2499 registry: 2501 * Value: result set truncated due to authorization 2503 Type: notice and remark type 2505 Description: The list of results does not contain all results due 2506 to lack of authorization. This may indicate to some clients that 2507 proper authorization will yield a longer result set. 2509 Registrant Name: IESG 2511 Registrant Contact Information: iesg@ietf.org 2513 * Value: result set truncated due to excessive load 2515 Type: notice and remark type 2516 Description: The list of results does not contain all results due 2517 to excessively heavy load on the server. This may indicate to 2518 some clients that requerying at a later time will yield a longer 2519 result set. 2521 Registrant Name: IESG 2523 Registrant Contact Information: iesg@ietf.org 2525 * Value: result set truncated due to unexplainable reasons 2527 Type: notice and remark type 2529 Description: The list of results does not contain all results for 2530 an unexplainable reason. This may indicate to some clients that 2531 requerying for any reason will not yield a longer result set. 2533 Registrant Name: IESG 2535 Registrant Contact Information: iesg@ietf.org 2537 * Value: object truncated due to authorization 2539 Type: notice and remark type 2541 Description: The object does not contain all data due to lack of 2542 authorization. 2544 Registrant Name: IESG 2546 Registrant Contact Information: iesg@ietf.org 2548 * Value: object truncated due to excessive load 2550 Type: notice and remark type 2552 Description: The object does not contain all data due to 2553 excessively heavy load on the server. This may indicate to some 2554 clients that requerying at a later time will yield all data of the 2555 object. 2557 Registrant Name: IESG 2559 Registrant Contact Information: iesg@ietf.org 2561 * Value: object truncated due to unexplainable reasons 2563 Type: notice and remark type 2564 Description: The object does not contain all data for an 2565 unexplainable reason. 2567 Registrant Name: IESG 2569 Registrant Contact Information: iesg@ietf.org 2571 10.2.2. Status 2573 The following values have been registered in the "RDAP JSON Values" 2574 registry: 2576 * Value: validated 2578 Type: status 2580 Description: Signifies that the data of the object instance has 2581 been found to be accurate. This type of status is usually found 2582 on entity object instances to note the validity of identifying 2583 contact information. 2585 Registrant Name: IESG 2587 Registrant Contact Information: iesg@ietf.org 2589 * Value: renew prohibited 2591 Type: status 2593 Description: Renewal or reregistration of the object instance is 2594 forbidden. 2596 Registrant Name: IESG 2598 Registrant Contact Information: iesg@ietf.org 2600 * Value: update prohibited 2602 Type: status 2604 Description: Updates to the object instance are forbidden. 2606 Registrant Name: IESG 2608 Registrant Contact Information: iesg@ietf.org 2610 * Value: transfer prohibited 2611 Type: status 2613 Description: Transfers of the registration from one registrar to 2614 another are forbidden. This type of status normally applies to 2615 DNR domain names. 2617 Registrant Name: IESG 2619 Registrant Contact Information: iesg@ietf.org 2621 * Value: delete prohibited 2623 Type: status 2625 Description: Deletion of the registration of the object instance 2626 is forbidden. This type of status normally applies to DNR domain 2627 names. 2629 Registrant Name: IESG 2631 Registrant Contact Information: iesg@ietf.org 2633 * Value: proxy 2635 Type: status 2637 Description: The registration of the object instance has been 2638 performed by a third party. This is most commonly applied to 2639 entities. 2641 Registrant Name: IESG 2643 Registrant Contact Information: iesg@ietf.org 2645 * Value: private 2647 Type: status 2649 Description: The information of the object instance is not 2650 designated for public consumption. This is most commonly applied 2651 to entities. 2653 Registrant Name: IESG 2655 Registrant Contact Information: iesg@ietf.org 2657 * Value: removed 2658 Type: status 2660 Description: Some of the information of the object instance has 2661 not been made available and has been removed. This is most 2662 commonly applied to entities. 2664 Registrant Name: IESG 2666 Registrant Contact Information: iesg@ietf.org 2668 * Value: obscured 2670 Type: status 2672 Description: Some of the information of the object instance has 2673 been altered for the purposes of not readily revealing the actual 2674 information of the object instance. This is most commonly applied 2675 to entities. 2677 Registrant Name: IESG 2679 Registrant Contact Information: iesg@ietf.org 2681 * Value: associated 2683 Type: status 2685 Description: The object instance is associated with other object 2686 instances in the registry. This is most commonly used to signify 2687 that a nameserver is associated with a domain or that an entity is 2688 associated with a network resource or domain. 2690 Registrant Name: IESG 2692 Registrant Contact Information: iesg@ietf.org 2694 * Value: active 2696 Type: status 2698 Description: The object instance is in use. For domain names, it 2699 signifies that the domain name is published in DNS. For network 2700 and autnum registrations it signifies that they are allocated or 2701 assigned for use in operational networks. This maps to the 2702 Extensible Provisioning Protocol (EPP) [RFC5730] 'OK' status. 2704 Registrant Name: IESG 2705 Registrant Contact Information: iesg@ietf.org 2707 * Value: inactive 2709 Type: status 2711 Description: The object instance is not in use. See 'active'. 2713 Registrant Name: IESG 2715 Registrant Contact Information: iesg@ietf.org 2717 * Value: locked 2719 Type: status 2721 Description: Changes to the object instance cannot be made, 2722 including the association of other object instances. 2724 Registrant Name: IESG 2726 Registrant Contact Information: iesg@ietf.org 2728 * Value: pending create 2730 Type: status 2732 Description: A request has been received for the creation 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 renew 2741 Type: status 2743 Description: A request has been received for the renewal of the 2744 object instance but this action is not yet complete. 2746 Registrant Name: IESG 2748 Registrant Contact Information: iesg@ietf.org 2750 * Value: pending transfer 2752 Type: status 2753 Description: A request has been received for the transfer of the 2754 object instance but this action is not yet complete. 2756 Registrant Name: IESG 2758 Registrant Contact Information: iesg@ietf.org 2760 * Value: pending update 2762 Type: status 2764 Description: A request has been received for the update or 2765 modification of the object instance but this action is not yet 2766 complete. 2768 Registrant Name: IESG 2770 Registrant Contact Information: iesg@ietf.org 2772 * Value: pending delete 2774 Type: status 2776 Description: A request has been received for the deletion or 2777 removal of the object instance but this action is not yet 2778 complete. For domains, this might mean that the name is no longer 2779 published in DNS but has not yet been purged from the registry 2780 database. 2782 Registrant Name: IESG 2784 Registrant Contact Information: iesg@ietf.org 2786 10.2.3. Event Actions 2788 The following values have been registered in the "RDAP JSON Values" 2789 registry: 2791 * Value: registration 2793 Type: event action 2795 Description: The object instance was initially registered. 2797 Registrant Name: IESG 2799 Registrant Contact Information: iesg@ietf.org 2801 * Value: reregistration 2803 Type: event action 2805 Description: The object instance was registered subsequently to 2806 initial registration. 2808 Registrant Name: IESG 2810 Registrant Contact Information: iesg@ietf.org 2812 * Value: last changed 2814 Type: event action 2816 Description: An action noting when the information in the object 2817 instance was last changed. 2819 Registrant Name: IESG 2821 Registrant Contact Information: iesg@ietf.org 2823 * Value: expiration 2825 Type: event action 2827 Description: The object instance has been removed or will be 2828 removed at a pre-determined date and time from the registry. 2830 Registrant Name: IESG 2832 Registrant Contact Information: iesg@ietf.org 2834 * Value: deletion 2836 Type: event action 2838 Description: The object instance was removed from the registry at 2839 a point in time that was not pre-determined. 2841 Registrant Name: IESG 2843 Registrant Contact Information: iesg@ietf.org 2845 * Value: reinstantiation 2847 Type: event action 2848 Description: The object instance was reregistered after having 2849 been removed from the registry. 2851 Registrant Name: IESG 2853 Registrant Contact Information: iesg@ietf.org 2855 * Value: transfer 2857 Type: event action 2859 Description: The object instance was transferred from one 2860 registrar to another. 2862 Registrant Name: IESG 2864 Registrant Contact Information: iesg@ietf.org 2866 * Value: locked 2868 Type: event action 2870 Description: The object instance was locked (see the 'locked' 2871 status). 2873 Registrant Name: IESG 2875 Registrant Contact Information: iesg@ietf.org 2877 * Value: unlocked 2879 Type: event action 2881 Description: The object instance was unlocked (see the 'locked' 2882 status). 2884 Registrant Name: IESG 2886 Registrant Contact Information: iesg@ietf.org 2888 10.2.4. Roles 2890 The following values have been registered in the "RDAP JSON Values" 2891 registry: 2893 * Value: registrant 2895 Type: role 2896 Description: The entity object instance is the registrant of the 2897 registration. In some registries, this is known as a maintainer. 2899 Registrant Name: IESG 2901 Registrant Contact Information: iesg@ietf.org 2903 * Value: technical 2905 Type: role 2907 Description: The entity object instance is a technical contact for 2908 the registration. 2910 Registrant Name: IESG 2912 Registrant Contact Information: iesg@ietf.org 2914 * Value: administrative 2916 Type: role 2918 Description: The entity object instance is an administrative 2919 contact for the registration. 2921 Registrant Name: IESG 2923 Registrant Contact Information: iesg@ietf.org 2925 * Value: abuse 2927 Type: role 2929 Description: The entity object instance handles network abuse 2930 issues on behalf of the registrant of the registration. 2932 Registrant Name: IESG 2934 Registrant Contact Information: iesg@ietf.org 2936 * Value: billing 2938 Type: role 2940 Description: The entity object instance handles payment and 2941 billing issues on behalf of the registrant of the registration. 2943 Registrant Name: IESG 2944 Registrant Contact Information: iesg@ietf.org 2946 * Value: registrar 2948 Type: role 2950 Description: The entity object instance represents the authority 2951 responsible for the registration in the registry. 2953 Registrant Name: IESG 2955 Registrant Contact Information: iesg@ietf.org 2957 * Value: reseller 2959 Type: role 2961 Description: The entity object instance represents a third party 2962 through which the registration was conducted (i.e. not the 2963 registry or registrar). 2965 Registrant Name: IESG 2967 Registrant Contact Information: iesg@ietf.org 2969 * Value: sponsor 2971 Type: role 2973 Description: The entity object instance represents a domain policy 2974 sponsor, such as an ICANN approved sponsor. 2976 Registrant Name: IESG 2978 Registrant Contact Information: iesg@ietf.org 2980 * Value: proxy 2982 Type: role 2984 Description: The entity object instance represents a proxy for 2985 another entity object, such as a registrant. 2987 Registrant Name: IESG 2989 Registrant Contact Information: iesg@ietf.org 2991 * Value: notifications 2992 Type: role 2994 Description: An entity object instance designated to receive 2995 notifications about association object instances. 2997 Registrant Name: IESG 2999 Registrant Contact Information: iesg@ietf.org 3001 * Value: noc 3003 Type: role 3005 Description: The entity object instance handles communications 3006 related to a network operations center (NOC). 3008 Registrant Name: IESG 3010 Registrant Contact Information: iesg@ietf.org 3012 10.2.5. Variant Relations 3014 The following values have been registered in the "RDAP JSON Values" 3015 registry: 3017 * Value: registered 3019 Type: domain variant relation 3021 Description: The variant names are registered in the registry. 3023 Registrant Name: IESG 3025 Registrant Contact Information: iesg@ietf.org 3027 * Value: unregistered 3029 Type: domain variant relation 3031 Description: The variant names are not found in the registry. 3033 Registrant Name: IESG 3035 Registrant Contact Information: iesg@ietf.org 3037 * Value: registration restricted 3039 Type: domain variant relation 3040 Description: Registration of the variant names is restricted to 3041 certain parties or within certain rules. 3043 Registrant Name: IESG 3045 Registrant Contact Information: iesg@ietf.org 3047 * Value: open registration 3049 Type: domain variant relation 3051 Description: Registration of the variant names is available to 3052 generally qualified registrants. 3054 Registrant Name: IESG 3056 Registrant Contact Information: iesg@ietf.org 3058 * Value: conjoined 3060 Type: domain variant relation 3062 Description: Registration of the variant names occurs 3063 automatically with the registration of the containing domain 3064 registration. 3066 Registrant Name: IESG 3068 Registrant Contact Information: iesg@ietf.org 3070 11. Implementation Status 3072 NOTE: Please remove this section and the reference to RFC 7942 prior 3073 to publication as an RFC. 3075 This section records the status of known implementations of the 3076 protocol defined by this specification at the time of posting of this 3077 Internet-Draft, and is based on a proposal described in RFC 7942 3078 [RFC7942]. The description of implementations in this section is 3079 intended to assist the IETF in its decision processes in progressing 3080 drafts to RFCs. Please note that the listing of any individual 3081 implementation here does not imply endorsement by the IETF. 3082 Furthermore, no effort has been spent to verify the information 3083 presented here that was supplied by IETF contributors. This is not 3084 intended as, and must not be construed to be, a catalog of available 3085 implementations or their features. Readers are advised to note that 3086 other implementations may exist. 3088 According to RFC 7942, "this will allow reviewers and working groups 3089 to assign due consideration to documents that have the benefit of 3090 running code, which may serve as evidence of valuable experimentation 3091 and feedback that have made the implemented protocols more mature. 3092 It is up to the individual working groups to use this information as 3093 they see fit". 3095 11.1. RedDog 3097 * Responsible Organization: NIC Mexico 3099 * Location: https://reddog.mx/ 3101 * Description: RedDog implements all the functionality of an RDAP 3102 Server defined in RFCs 7480,7481,7482 and 7483. RedDog is highly 3103 configurable and extensible to fit the needs of the developers and 3104 operators. 3106 * Level of Maturity: Production. 3108 * Coverage: RedDog supports all lookups, searches and responses for 3109 all object classes described in RFC 7482 and RFC 7483. 3111 * Version Compatibility: RFC 7482 and RFC 7483 3113 * Licensing: Apache License 2.0 3115 * Contact Information: reddog-dev@nic.mx 3117 * Information last updated: November 22, 2019 3119 11.2. Verisign 3121 * Responsible Organization: Verisign 3123 * Location: https://rdap.verisign.com/com/v1/, 3124 https://rdap.verisign.com/net/v1/ 3126 * Description: Verisign's production RDAP service for the .com and 3127 .net gTLDs. 3129 * Level of Maturity: Production. 3131 * Coverage: Lookup of domain names, name servers, entities; name 3132 server search by IP address; help. 3134 * Version Compatibility: RFC 7483 3135 * Contact Information: info@verisign-grs.com 3137 11.3. Verisign Labs 3139 * Responsible Organization: Verisign Labs 3141 * Location: https://rdap.verisignlabs.com/rdap/v1/ 3143 * Description: Verisign's experimental RDAP service for the .cc and 3144 .tv ccTLDs. 3146 * Level of Maturity: Experimental. 3148 * Coverage: Lookup of domain names, name servers, entities; name 3149 server search by IP address; basic search; regular expression 3150 search; federated authentication; help. 3152 * Version Compatibility: RFC 7483 3154 * Contact Information: Scott Hollenbeck, shollenbeck@verisign.com 3156 11.4. Asia-Pacific Network Information Centre (APNIC) 3158 * Responsible Organization: Asia-Pacific Network Information Centre 3159 (APNIC) 3161 * Location: https://rdap.apnic.net/, https://github.com/APNIC-net/ 3162 rdapd 3164 * Description: APNIC's production RDAP service for Internet number 3165 resouces. 3167 * Level of Maturity: Production. 3169 * Coverage: Lookup of IP networks, AS numbers, domains, and 3170 entities. Also domain search by name, entity search by handle or 3171 full name, and help responses. 3173 * Version Compatibility: RFC 7483 3175 * Contact Information: helpdesk@apnic.net 3177 12. Security Considerations 3179 This specification models information serialized in JSON format. As 3180 JSON is a subset of JavaScript, implementations are advised to follow 3181 the security considerations outlined in Section 12 of [RFC8259] to 3182 prevent code injection. 3184 Though not specific to JSON, RDAP implementers should be aware of the 3185 security considerations specified in [RFC7480] and the security 3186 requirements and considerations in [RFC7481]. 3188 RDAP responses allow for retrieval of DNSSEC (key) related 3189 information, but the RRSIG DS from the parent zone is not conveyed 3190 alongside it. This means that the DNSSEC keys retrieved by RDAP are 3191 disconnected from their containing PKI, and as such are not generally 3192 expected to be trusted without additional information. In 3193 particular, the HTTPS channel protecting the RDAP connection is not 3194 expected to be authorized to certify the validity of the DNSSEC keys. 3196 Clients caching data, especially clients using RDAP-specific caches 3197 (instead of HTTP-layer caches), should have safeguards to prevent 3198 cache poisoning. See Section 5 for advice on using the self links 3199 for caching. 3201 Finally, service operators should be aware of the privacy mechanisms 3202 noted in Section 14. 3204 13. Internationalization Considerations 3206 13.1. Character Encoding 3208 The default text encoding for JSON responses in RDAP is UTF-8 3209 [RFC3629], and all servers and clients MUST support UTF-8. 3211 13.2. URIs and IRIs 3213 [RFC7480] defines the use of URIs and IRIs in RDAP. 3215 13.3. Language Tags 3217 Section 4.4 defines the use of language tags in the JSON responses 3218 defined in this document. 3220 13.4. Internationalized Domain Names 3222 IDNs are denoted in this specification by the separation of DNS names 3223 in LDH form and Unicode form (see Section 3). Representation of IDNs 3224 in registries is described by the "variants" object in Section 5.3 3225 and the suggested values listed in Section 10.2.5. 3227 14. Privacy Considerations 3229 This specification suggests status values to denote contact and 3230 registrant information that has been marked as private and/or has 3231 been removed or obscured. See Section 10.2.2 for the complete list 3232 of status values. A few of the status values indicate that there are 3233 privacy concerns associated with the object instance. The following 3234 status codes SHOULD be used to describe data elements of a response 3235 when appropriate: 3237 private -- The object is not be shared in query responses, unless 3238 the user is authorized to view this information. 3240 removed -- Data elements within the object have been collected but 3241 have been omitted from the response. This option can be used to 3242 prevent unauthorized access to associated object instances without 3243 the need to mark them as private. 3245 obscured -- Data elements within the object have been collected, 3246 but the response value has been altered so that values are not 3247 easily discernible. A value changed from "1212" to "XXXX" is an 3248 example of obscured data. This option may reveal privacy 3249 sensitive information and should only be used when data 3250 sensitivity does not require a more protective option like 3251 "private" or "removed". 3253 See Appendix A.1 for an example of applying those values to contacts 3254 and registrants. 3256 15. References 3258 15.1. Normative References 3260 [I-D.ietf-regext-rfc7482bis] 3261 Hollenbeck, S. and A. Newton, "Registration Data Access 3262 Protocol (RDAP) Query Format", Work in Progress, Internet- 3263 Draft, draft-ietf-regext-rfc7482bis-02, 8 September 2020, 3264 . 3267 [ISO.3166.1988] 3268 International Organization for Standardization, "Codes for 3269 the representation of names of countries, 3rd edition", 3270 ISO Standard 3166, August 1988. 3272 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3273 Requirement Levels", BCP 14, RFC 2119, 3274 DOI 10.17487/RFC2119, March 1997, 3275 . 3277 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3278 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3279 . 3281 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3282 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3283 2003, . 3285 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3286 Resource Identifier (URI): Generic Syntax", STD 66, 3287 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3288 . 3290 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 3291 Rose, "Resource Records for the DNS Security Extensions", 3292 RFC 4034, DOI 10.17487/RFC4034, March 2005, 3293 . 3295 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 3296 Autonomous System (AS) Numbers", RFC 5396, 3297 DOI 10.17487/RFC5396, December 2008, 3298 . 3300 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 3301 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 3302 September 2009, . 3304 [RFC5890] Klensin, J., "Internationalized Domain Names for 3305 Applications (IDNA): Definitions and Document Framework", 3306 RFC 5890, DOI 10.17487/RFC5890, August 2010, 3307 . 3309 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3310 Address Text Representation", RFC 5952, 3311 DOI 10.17487/RFC5952, August 2010, 3312 . 3314 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 3315 DOI 10.17487/RFC7095, January 2014, 3316 . 3318 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 3319 Registration Data Access Protocol (RDAP)", RFC 7480, 3320 DOI 10.17487/RFC7480, March 2015, 3321 . 3323 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 3324 Registration Data Access Protocol (RDAP)", RFC 7481, 3325 DOI 10.17487/RFC7481, March 2015, 3326 . 3328 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3329 Writing an IANA Considerations Section in RFCs", BCP 26, 3330 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3331 . 3333 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3334 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3335 May 2017, . 3337 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3338 Interchange Format", STD 90, RFC 8259, 3339 DOI 10.17487/RFC8259, December 2017, 3340 . 3342 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 3343 DOI 10.17487/RFC8288, October 2017, 3344 . 3346 15.2. Informative References 3348 [IANA_IDNTABLES] 3349 IANA, "Repository of IDN Practices", 3350 . 3352 [JSON_ascendancy] 3353 MacVittie, L., "The Stealthy Ascendancy of JSON", April 3354 2011, . 3357 [JSON_performance_study] 3358 Nurseitov, N., Paulson, M., Reynolds, R., and C. Izurieta, 3359 "Comparison of JSON and XML Data Interchange Formats: A 3360 Case Study", 2009, 3361 . 3363 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 3364 DOI 10.17487/RFC3912, September 2004, 3365 . 3367 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 3368 STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009, 3369 . 3371 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 3372 Security Extensions Mapping for the Extensible 3373 Provisioning Protocol (EPP)", RFC 5910, 3374 DOI 10.17487/RFC5910, May 2010, 3375 . 3377 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 3378 DOI 10.17487/RFC6350, August 2011, 3379 . 3381 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 3382 Structured Syntax Suffixes", RFC 6839, 3383 DOI 10.17487/RFC6839, January 2013, 3384 . 3386 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 3387 Code: The Implementation Status Section", BCP 205, 3388 RFC 7942, DOI 10.17487/RFC7942, July 2016, 3389 . 3391 Appendix A. Suggested Data Modeling with the Entity Object Class 3393 A.1. Registrants and Contacts 3395 This document does not provide specific object classes for 3396 registrants and contacts. Instead, the entity object class may be 3397 used to represent a registrant or contact. When the entity object is 3398 embedded inside a containing object such as a domain name or IP 3399 network, the "roles" string array can be used to signify the 3400 relationship. It is recommended that the values from Section 10.2.4 3401 be used. 3403 The following is an example of an elided containing object with an 3404 embedded entity that is both a registrant and administrative contact: 3406 { 3407 ... 3408 "entities" : 3409 [ 3410 { 3411 "objectClassName" : "entity", 3412 "handle" : "XXXX", 3413 "vcardArray":[ 3414 "vcard", 3416 [ 3417 ["version", {}, "text", "4.0"], 3418 ["fn", {}, "text", "Joe User"], 3419 ["kind", {}, "text", "individual"], 3420 ["lang", { 3421 "pref":"1" 3422 }, "language-tag", "fr"], 3423 ["lang", { 3424 "pref":"2" 3425 }, "language-tag", "en"], 3426 ["org", { 3427 "type":"work" 3428 }, "text", "Example"], 3429 ["title", {}, "text", "Research Scientist"], 3430 ["role", {}, "text", "Project Lead"], 3431 ["adr", 3432 { "type":"work" }, 3433 "text", 3434 [ 3435 "", 3436 "Suite 1234", 3437 "4321 Rue Somewhere", 3438 "Quebec", 3439 "QC", 3440 "G1V 2M2", 3441 "Canada" 3442 ] 3443 ], 3444 ["tel", 3445 { "type":["work", "voice"], "pref":"1" }, 3446 "uri", "tel:+1-555-555-1234;ext=102" 3447 ], 3448 ["email", 3449 { "type":"work" }, 3450 "text", "joe.user@example.com" 3451 ] 3452 ] 3453 ], 3454 "roles" : [ "registrant", "administrative" ], 3455 "remarks" : 3456 [ 3457 { 3458 "description" : 3459 [ 3460 "She sells sea shells down by the sea shore.", 3461 "Originally written by Terry Sullivan." 3462 ] 3463 } 3465 ], 3466 "events" : 3467 [ 3468 { 3469 "eventAction" : "registration", 3470 "eventDate" : "1990-12-31T23:59:59Z" 3471 }, 3472 { 3473 "eventAction" : "last changed", 3474 "eventDate" : "1991-12-31T23:59:59Z" 3475 } 3476 ] 3477 } 3478 ] 3479 } 3481 Figure 34 3483 In many use cases, it is necessary to hide or obscure the information 3484 of a registrant or contact due to policy or other operational 3485 matters. Registries can denote these situations with "status" values 3486 (see Section 10.2.2). 3488 The following is an elided example of a registrant with information 3489 changed to reflect that of a third party. 3491 { 3492 ... 3493 "entities" : 3494 [ 3495 { 3496 "objectClassName" : "entity", 3497 "handle" : "XXXX", 3498 ... 3499 "roles" : [ "registrant", "administrative" ], 3500 "status" : [ "proxy", "private", "obscured" ] 3501 } 3502 ] 3503 } 3505 Figure 35 3507 A.2. Registrars 3509 This document does not provide a specific object class for 3510 registrars, but like registrants and contacts (see Appendix A.1), the 3511 "roles" string array maybe used. Additionally, many registrars have 3512 publicly assigned identifiers. The publicIds structure (Section 4.8) 3513 represents that information. 3515 The following is an example of an elided containing object with an 3516 embedded entity that is a registrar: 3518 { 3519 ... 3520 "entities":[ 3521 { 3522 "objectClassName" : "entity", 3523 "handle":"XXXX", 3524 "vcardArray":[ 3525 "vcard", 3526 [ 3527 ["version", {}, "text", "4.0"], 3528 ["fn", {}, "text", "Joe's Fish, Chips, and Domains"], 3529 ["kind", {}, "text", "org"], 3530 ["lang", { 3531 "pref":"1" 3532 }, "language-tag", "fr"], 3533 ["lang", { 3534 "pref":"2" 3535 }, "language-tag", "en"], 3536 ["org", { 3537 "type":"work" 3538 }, "text", "Example"], 3539 ["adr", 3540 { "type":"work" }, 3541 "text", 3542 [ 3543 "", 3544 "Suite 1234", 3545 "4321 Rue Somewhere", 3546 "Quebec", 3547 "QC", 3548 "G1V 2M2", 3549 "Canada" 3550 ] 3551 ], 3552 ["tel", 3553 { 3554 "type":["work", "voice"], 3555 "pref":"1" 3556 }, 3557 "uri", "tel:+1-555-555-1234;ext=102" 3558 ], 3559 ["email", 3560 { "type":"work" }, 3561 "text", "joes_fish_chips_and_domains@example.com" 3562 ] 3563 ] 3564 ], 3565 "roles":[ "registrar" ], 3566 "publicIds":[ 3567 { 3568 "type":"IANA Registrar ID", 3569 "identifier":"1" 3570 } 3571 ], 3572 "remarks":[ 3573 { 3574 "description":[ 3575 "She sells sea shells down by the sea shore.", 3576 "Originally written by Terry Sullivan." 3577 ] 3578 } 3579 ], 3580 "links":[ 3581 { 3582 "value":"https://example.net/entity/XXXX", 3583 "rel":"alternate", 3584 "type":"text/html", 3585 "href":"https://www.example.com" 3586 } 3587 ] 3588 } 3589 ] 3590 } 3592 Figure 36 3594 Appendix B. Modeling Events 3596 Events represent actions that have taken place against a registered 3597 object at a certain date and time. Events have three properties: the 3598 action, the actor, and the date and time of the event (which is 3599 sometimes in the future). In some cases, the identity of the actor 3600 is not captured. 3602 Events can be modeled in three ways: 3604 1. events with no designated actor 3606 2. events where the actor is only designated by an identifier 3608 3. events where the actor can be modeled as an entity 3610 For the first use case, the events data structure (Section 4.5) is 3611 used without the "eventActor" object member. 3613 This is an example of an "events" array without the "eventActor". 3615 "events" : 3616 [ 3617 { 3618 "eventAction" : "registration", 3619 "eventDate" : "1990-12-31T23:59:59Z" 3620 } 3621 ] 3623 Figure 37 3625 For the second use case, the events data structure (Section 4.5) is 3626 used with the "eventActor" object member. 3628 This is an example of an "events" array with the "eventActor". 3630 "events" : 3631 [ 3632 { 3633 "eventAction" : "registration", 3634 "eventActor" : "XYZ-NIC", 3635 "eventDate" : "1990-12-31T23:59:59Z" 3636 } 3637 ] 3639 Figure 38 3641 For the third use case, the "asEventActor" array is used when an 3642 entity (Section 5.1) is embedded into another object class. The 3643 "asEventActor" array follows the same structure as the "events" array 3644 but does not have "eventActor" attributes. 3646 The following is an elided example of a domain object with an entity 3647 as an event actor. 3649 { 3650 "objectClassName" : "domain", 3651 "handle" : "XXXX", 3652 "ldhName" : "foo.example", 3653 "status" : [ "locked", "transfer prohibited" ], 3654 ... 3655 "entities" : 3656 [ 3657 { 3658 "handle" : "XXXX", 3659 ... 3660 "asEventActor" : 3661 [ 3662 { 3663 "eventAction" : "last changed", 3664 "eventDate" : "1990-12-31T23:59:59Z" 3665 } 3666 ] 3667 } 3668 ] 3669 } 3671 Figure 39 3673 Appendix C. Structured vs. Unstructured Addresses 3675 The entity (Section 5.1) object class uses jCard [RFC7095] to 3676 represent contact information, including postal addresses. jCard has 3677 the ability to represent multiple language preferences, multiple 3678 email address and phone numbers, and multiple postal addresses in 3679 both a structured and unstructured format. This section describes 3680 the use of jCard for representing structured and unstructured 3681 addresses. 3683 The following is an example of a jCard. 3685 { 3686 "vcardArray":[ 3687 "vcard", 3688 [ 3689 ["version", {}, "text", "4.0"], 3690 ["fn", {}, "text", "Joe User"], 3691 ["n", {}, "text", 3692 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 3693 ], 3694 ["kind", {}, "text", "individual"], 3695 ["lang", { 3696 "pref":"1" 3698 }, "language-tag", "fr"], 3699 ["lang", { 3700 "pref":"2" 3701 }, "language-tag", "en"], 3702 ["org", { 3703 "type":"work" 3704 }, "text", "Example"], 3705 ["title", {}, "text", "Research Scientist"], 3706 ["role", {}, "text", "Project Lead"], 3707 ["adr", 3708 { "type":"work" }, 3709 "text", 3710 [ 3711 "", 3712 "Suite 1234", 3713 "4321 Rue Somewhere", 3714 "Quebec", 3715 "QC", 3716 "G1V 2M2", 3717 "Canada" 3718 ] 3719 ], 3720 ["adr", 3721 { 3723 "type":"home", 3724 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 3725 }, 3726 "text", 3727 [ 3728 "", "", "", "", "", "", "" 3729 ] 3730 ], 3731 ["tel", 3732 { "type":["work", "voice"], "pref":"1" }, 3733 "uri", "tel:+1-555-555-1234;ext=102" 3734 ], 3735 ["tel", 3736 { 3737 "type":["work", "cell", "voice", "video", "text"] 3738 }, 3739 "uri", 3740 "tel:+1-555-555-1234" 3741 ], 3742 ["email", 3743 { "type":"work" }, 3744 "text", "joe.user@example.com" 3745 ], 3747 ["geo", { 3748 "type":"work" 3749 }, "uri", "geo:46.772673,-71.282945"], 3750 ["key", 3751 { "type":"work" }, 3752 "uri", "https://www.example.com/joe.user/joe.asc" 3753 ], 3754 ["tz", {}, 3755 "utc-offset", "-05:00"], 3756 ["url", { "type":"home" }, 3757 "uri", "https://example.org"] 3758 ] 3759 ] 3760 } 3762 Figure 40 3764 The arrays in Figure 40 with the first member of "adr" represent 3765 postal addresses. In the first example, the postal address is given 3766 as an array of strings and constitutes a structured address. For 3767 components of the structured address that are not applicable, an 3768 empty string is given. Each member of that array aligns with the 3769 positions of a vCard as given in [RFC6350]. In this example, the 3770 following data corresponds to the following positional meanings: 3772 1. post office box -- not applicable; empty string 3774 2. extended address (e.g., apartment or suite number) -- Suite 1234 3776 3. street address -- 4321 Rue Somewhere 3778 4. locality (e.g., city) -- Quebec 3780 5. region (e.g., state or province) -- QC 3782 6. postal code -- G1V 2M2 3784 7. country name (full name) -- Canada 3786 The second example is an unstructured address. It uses the "label" 3787 attribute, which is a string containing a newline (\n) character to 3788 separate address components in an unordered, unspecified manner. 3789 Note that in this example, the structured address array is still 3790 given but that each string is an empty string. 3792 Appendix D. Secure DNS 3794 Section 5.3 defines the "secureDNS" member to represent secure DNS 3795 information about domain names. 3797 DNSSEC provides data integrity for DNS through the digital signing of 3798 resource records. To enable DNSSEC, the zone is signed by one or 3799 more private keys and the signatures are stored as RRSIG records. To 3800 complete the chain of trust in the DNS zone hierarchy, a digest of 3801 each DNSKEY record (which contains the public key) must be loaded 3802 into the parent zone, stored as DS records, and signed by the 3803 parent's private key (RRSIG DS record), as indicated in "Resource 3804 Records for the DNS Security Extensions" [RFC4034]. Creating the DS 3805 records in the parent zone can be done by the registration authority 3806 "Domain Name System (DNS) Security Extensions Mapping for the 3807 Extensible Provisioning Protocol (EPP)" [RFC5910]. 3809 Only DS-related information is provided by RDAP, since other 3810 information is not generally stored in the registration database. 3811 Other DNSSEC-related information can be retrieved with other DNS 3812 tools such as dig. 3814 The domain object class (Section 5.3) can represent this information 3815 using either the "dsData" or "keyData" object arrays. Client 3816 implementers should be aware that some registries do not collect or 3817 do not publish all of the secure DNS meta-information. 3819 Appendix E. Motivations for Using JSON 3821 This section addresses a common question regarding the use of JSON 3822 over other data formats, most notably XML. 3824 It is often pointed out that many DNRs and one RIR support the EPP 3825 [RFC5730] standard, which is an XML serialized protocol. The logic 3826 is that since EPP is a common protocol in the industry, it follows 3827 that XML would be a more natural choice. While EPP does influence 3828 this specification quite a bit, EPP serves a different purpose, which 3829 is the provisioning of Internet resources between registries and 3830 accredited registrars and serving a much narrower audience than that 3831 envisioned for RDAP. 3833 By contrast, RDAP has a broader audience and is designed for public 3834 consumption of data. Experience from RIRs with first generation 3835 RESTful web services for WHOIS indicate that a large percentage of 3836 clients operate within browsers and other platforms where full-blown 3837 XML stacks are not readily available and where JSON is a better fit. 3839 Additionally, while EPP is used in much of the DNR community it is 3840 not a universal constant in that industry. And finally, EPP's use of 3841 XML predates the specification of JSON. If EPP had been defined 3842 today, it may very well have used JSON instead of XML. 3844 Beyond the specific DNR and RIR communities, the trend in the broader 3845 Internet industry is also switching to JSON over XML, especially in 3846 the area of RESTful web services (see [JSON_ascendancy]). Studies 3847 have also found that JSON is generally less bulky and consequently 3848 faster to parse (see [JSON_performance_study]). 3850 Acknowledgments 3852 This document is derived from original work on RIR responses in JSON 3853 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew 3854 L. Newton. Additionally, this document incorporates work on DNR 3855 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 3856 Shen. 3858 The components of the DNR object classes are derived from a 3859 categorization of WHOIS response formats created by Ning Kong, Linlin 3860 Zhou, Guangqing Deng, Steve Sheng, Francisco Arias, Ray Bellis, and 3861 Frederico Neves. 3863 Tom Harrison, Murray Kucherawy, Ed Lewis, Audric Schiltknecht, Naoki 3864 Kambe, Maarten Bosteels, Mario Loffredo, and Jasdip Singh contributed 3865 significant review comments and provided clarifying text. James 3866 Mitchell provided text regarding the processing of unknown JSON 3867 attributes and identified issues leading to the remodeling of events. 3868 Ernie Dainow and Francisco Obispo provided concrete suggestions that 3869 led to a better variant model for domain names. 3871 Ernie Dainow provided the background information on the secure DNS 3872 attributes and objects for domains, informative text on DNSSEC, and 3873 many other attributes that appear throughout the object classes of 3874 this document. 3876 The switch to and incorporation of jCard was performed by Simon 3877 Perreault. 3879 Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working 3880 group from which this document was originally created. James Galvin 3881 and Antoin Verschuren chaired the REGEXT working group that worked on 3882 the -bis version. 3884 Changes from RFC 7483 3886 00: Initial version ported from RFC 7483. Addressed known errata. 3888 Added Implementation Status section. 3890 01: Updated references to 7482 to 7482bis Internet-Draft. Updated 3891 "Change Log" to "Changes from RFC 7483". Added APNIC 3892 implementation status. Adjusted case of "xxxx" used in examples 3893 where "XXXX" was previously used, and removed an "X" from "XXXXX". 3894 Changed IPv6 address example using "C00" to "c00". Added "a 3895 string representing" to the definitions of startAddress and 3896 endAddress. Removed "entity" from "Autonomous System Number 3897 Entity Object Class". Added "an unsigned 32-bit integer" to the 3898 definition of startAutnum and endAutnum. Added "a string 3899 representing" to the definition of name in the IP network and ASN 3900 object classes. Clarified rdapConformance identifier registration 3901 expectations in Section 4.1. Changed "lunarNic_level_0" to 3902 "lunarNIC_level_0". Clarified that the "value", "rel" and "href" 3903 JSON values MUST be specified in the "links" array. Clarified 3904 that the "description" array is required in the Notices and 3905 Remarks data structures and other values are OPTIONAL. Noted that 3906 all members of the "events" and "Public IDs" arrays are REQUIRED. 3907 Fix "self" link values in examples. Changed "http" to "https" 3908 link values in examples. Noted that Figure 18 is an example of a 3909 nameserver object with all "appropriate" values given. In 3910 appendix C, quoted the word "label" in "label attribute". Added 3911 reference to "status" definition in the descriptions for IP 3912 networks and autnums. Fixed a 404 for the informative reference 3913 to "The Stealthy Ascendancy of JSON". Added "boolean" to the 3914 definition of zoneSigned. Clarified REQUIRED and OPTIONAL members 3915 of the "events" array. Changed "SHOULD not" to "SHOULD NOT" in 3916 Section 5. Updated normative references (5226-8126, 5988-8288, 3917 7159-8259). Changed examples using "ns1.xn--fo-5ja.example" to 3918 split URLs to avoid long lines. 3920 00: Initial working group version. Added acknowledgments. 3922 01: Changed "The "lang" attribute may appear anywhere in an object 3923 class or data structure except for in jCard objects" to "The 3924 "lang" attribute as defined in this section MAY appear anywhere in 3925 an object class or data structure, except for in jCard objects. 3926 jCard supports similar functionality by way of the LANGUAGE 3927 property parameter (see Section 5.1 of RFC 6350 [RFC6350]". 3928 Changed "simple data types conveyed in JSON strings" to "simple 3929 data types conveyed in JSON primitive types (strings, numbers, 3930 booleans, and null)". Changed "In other words, servers are free 3931 to not include JSON members containing registration data based on 3932 their own policies" to "In other words, servers are free to omit 3933 unrequired/optional JSON members containing registration data 3934 based on their own policies". Changed "This data structure 3935 appears only in the topmost JSON object of a response" to "This 3936 data structure MUST appear in the topmost JSON object of a 3937 response". Changed "Some non-answer responses may return entity 3938 bodies with information that could be more descriptive" to "Some 3939 non-answer responses MAY return entity bodies with information 3940 that could be more descriptive". Changed "The basic structure of 3941 that response is an object class containing an error code number 3942 (corresponding to the HTTP response code) followed by a string 3943 named "title" and an array of strings named "description"" to "The 3944 basic structure of that response is an object class containing a 3945 REQUIRED error code number (corresponding to the HTTP response 3946 code) followed by an OPTIONAL string named "title" and an OPTIONAL 3947 array of strings named "description"". Changed the "Autonomous 3948 System Number Object Class" section title to "The Autonomous 3949 System Number Object Class" for consistency with other section 3950 titles. Removed trailing periods in the "Terminology and 3951 Definitions" section for consistency. Changed instances of 3952 "lunarNic" to "lunarNIC" for consistency. Removed an extraneous 3953 trailing period after the eventDate description. Changed a "." to 3954 ";" in the description of the "network" member of the domain 3955 object class. Changed "The high-level structure of the autnum 3956 object class consists of information about the network 3957 registration" to "The high-level structure of the autnum object 3958 class consists of information about the autonomous system number 3959 registration". Changed "registry unique" to "registry-unique". 3961 02: Changed "registrant" to "registrar" in the description of the 3962 "transfer" event action to address erratum 6158. Added IANA 3963 instructions to correct the description of the value in the 3964 registry. Added text to Section 4.2 to note that "self" and 3965 "related" "href" URIs MUST NOT be the same. Added text to 3966 Section 4.2 to describe return of IDNs in LDH name format. 3968 03: Added text to note that the "fn" member of a contact object MAY 3969 be empty in Section 3. 3971 04: Added text to clarify rdapConformance requirements in 3972 Section 4.1. 3974 05: Added "obsoletes 7483" to the headers, Abstract, and 3975 Introduction. Updated BCP14 template. Updated IANA 3976 Considerations to note that this new RFC (a product of the REGEXT 3977 working group) replaces 7483. Changed "simple string" to "simple 3978 character string" in Sections 3 and 4.7. Clarified requirement 3979 for the "fn" member in Section 3. Modified the requirement for 3980 rdapConformance placement in Section 4.1. Changed "jCard" to 3981 "vCard" LANGUAGE property reference in Section 4.4. Changed "no 3982 use" to "little or no use" in Section 5.1. Added example line 3983 wrap note in Section 5.2. Modified the definition of "idnTable" 3984 in Section 5.3. Modified the dsData and keyData examples in 3985 Section 5.3. Changed "2001:c00::/23" to "2001:db8::/32" in 3986 Section 5.4. Expanded the definition of "type" in Sections 5.4 3987 and 5.5. Modified example autnums in Section 5.5. Added text to 3988 the Security Considerations section to note that DNSSEC 3989 information returned in a response can not be trusted directly. 3991 Authors' Addresses 3993 Scott Hollenbeck 3994 Verisign Labs 3995 12061 Bluemont Way 3996 Reston, VA 20190 3997 United States 3999 Email: shollenbeck@verisign.com 4000 URI: https://www.verisignlabs.com/ 4002 Andy Newton 4003 Amazon Web Services, Inc. 4004 13200 Woodland Park Road 4005 Herndon, VA 20171 4006 United States of America 4008 Email: andy@hxr.us