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