idnits 2.17.1 draft-ietf-weirds-json-response-14.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: ---------------------------------------------------------------------------- No issues found here. 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: Clients using "self" links for caching SHOULD not cache any object class instances where the authority of the self link is different than the authority of the server returning the data. Failing to do so might result in cache poisoning. -- The document date (December 31, 2014) is 3403 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) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-using-http' == Outdated reference: A later version (-18) exists of draft-ietf-weirds-rdap-query-16 == Outdated reference: A later version (-12) exists of draft-ietf-weirds-rdap-sec-11 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-rdap-sec' Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track S. Hollenbeck 5 Expires: July 4, 2015 Verisign Labs 6 December 31, 2014 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-weirds-json-response-14 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 http://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 July 4, 2015. 36 Copyright Notice 38 Copyright (c) 2014 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 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Terminology and Definitions . . . . . . . . . . . . . . . 3 55 1.2. Data Model . . . . . . . . . . . . . . . . . . . . . . . 4 56 2. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.1. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 7 59 4. Common Data Structures . . . . . . . . . . . . . . . . . . . 9 60 4.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 9 61 4.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 4.3. Notices And Remarks . . . . . . . . . . . . . . . . . . . 10 63 4.4. Language Identifier . . . . . . . . . . . . . . . . . . . 12 64 4.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 4.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 14 66 4.7. Port 43 WHOIS Server . . . . . . . . . . . . . . . . . . 14 67 4.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 14 68 4.9. Object Class Name . . . . . . . . . . . . . . . . . . . . 14 69 4.10. An Example . . . . . . . . . . . . . . . . . . . . . . . 15 70 5. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 17 71 5.1. The Entity Object Class . . . . . . . . . . . . . . . . . 17 72 5.2. The Nameserver Object Class . . . . . . . . . . . . . . . 24 73 5.3. The Domain Object Class . . . . . . . . . . . . . . . . . 28 74 5.4. The IP Network Object Class . . . . . . . . . . . . . . . 40 75 5.5. Autonomous System Number Entity Object Class . . . . . . 44 76 6. Error Response Body . . . . . . . . . . . . . . . . . . . . . 47 77 7. Responding to Help Queries . . . . . . . . . . . . . . . . . 49 78 8. Responding To Searches . . . . . . . . . . . . . . . . . . . 50 79 9. Indicating Truncated Responses . . . . . . . . . . . . . . . 51 80 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 81 10.1. RDAP JSON Media Type Registration . . . . . . . . . . . 54 82 10.2. JSON Values Registry . . . . . . . . . . . . . . . . . . 55 83 10.2.1. Notice and Remark Types . . . . . . . . . . . . . . 56 84 10.2.2. Status . . . . . . . . . . . . . . . . . . . . . . . 58 85 10.2.3. Event Actions . . . . . . . . . . . . . . . . . . . 63 86 10.2.4. Roles . . . . . . . . . . . . . . . . . . . . . . . 66 87 10.2.5. Variant Relations . . . . . . . . . . . . . . . . . 69 88 11. Security Considerations . . . . . . . . . . . . . . . . . . . 70 89 12. Internationalization Considerations . . . . . . . . . . . . . 71 90 12.1. Character Encoding . . . . . . . . . . . . . . . . . . . 71 91 12.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 71 92 12.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 71 93 12.4. Internationalized Domain Names . . . . . . . . . . . . . 71 94 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 71 95 14. Contributing Authors and Acknowledgements . . . . . . . . . . 72 96 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 97 15.1. Normative References . . . . . . . . . . . . . . . . . . 73 98 15.2. Informative References . . . . . . . . . . . . . . . . . 74 99 Appendix A. Suggested Data Modeling with the Entity Object Class 75 100 A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 75 101 A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 77 102 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 79 103 Appendix C. Structured vs Unstructured Addresses . . . . . . . . 81 104 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 84 105 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 84 106 Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . 85 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 91 109 1. Introduction 111 This document describes responses in the JSON [RFC7159] format for 112 the queries as defined by the Registration Data Access Protocol 113 Lookup Format [I-D.ietf-weirds-rdap-query]. 114 [I-D.ietf-weirds-using-http] describes a communication protocol for 115 exchanging queries and responses. 117 1.1. Terminology and Definitions 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in RFC 2119 [RFC2119] 122 when specified in their uppercase forms. 124 The following list describes terminology and definitions used 125 throughout this document: 127 DNR: Domain Name Registry 129 LDH: Letters, Digits, Hyphen 131 member: data found within an object as defined by JSON 132 [RFC7159]. 134 object: a data structure as defined by JSON [RFC7159]. 136 object class: the definition of members that may be found in JSON 137 objects described in this document. 139 object instance: an instantiation or specific instance of an object 140 class. 142 RDAP: Registration Data Access Protocol 143 RIR: Regional Internet Registry 145 1.2. Data Model 147 The data model for JSON responses is specified in five sections: 149 1. simple data types conveyed in JSON strings 151 2. data structures specified as JSON arrays or objects that are used 152 repeatedly when building up larger objects 154 3. object classes representing structured data corresponding to a 155 lookup of a single object 157 4. arrays of objects representing structured data corresponding to a 158 search for multiple objects 160 5. the response to an error 162 The object classes represent responses for two major categories of 163 data: responses returned by Regional Internet Registries (RIRs) for 164 registrations data related to IP addresses, reverse DNS names, and 165 Autonomous System numbers; and responses returned by Domain Name 166 Registries (DNRs) for registration data related to forward DNS names. 167 The following object classes are returned by both RIRs and DNRs: 169 1. domains 171 2. nameservers 173 3. entities 175 The information served by both RIRs and DNRs for these object classes 176 overlap extensively and are given in this document as a unified model 177 for both classes of service. 179 In addition to the object classes listed above, RIRs also serve the 180 following object classes: 182 1. IP networks 184 2. Autonomous System numbers 186 Object classes defined in this document represent a minimal set of 187 what a compliant client/server needs to understand to function 188 correctly, however some deployments may want to include additional 189 object classes to suit individual needs. Anticipating this need for 190 extension, Section 2.1 of this document defines a mechanism for 191 extending the JSON objects that are described in this document. 193 Positive responses take two forms. A response to a lookup of a 194 single object in the registration system yields a JSON object which 195 is the subject of the lookup. A response to a search for multiple 196 objects yields a JSON object that contains an array of JSON objects 197 that are the subject of the search. In each type of response, other 198 data structures are present within the topmost JSON object. 200 2. Use of JSON 202 2.1. Naming 204 Clients of these JSON responses SHOULD ignore unrecognized JSON 205 members in responses. Servers can insert members into the JSON 206 responses which are not specified in this document, but that does not 207 constitute an error in the response. Servers which insert such 208 unspecified members into JSON responses SHOULD have member names 209 prefixed with a short identifier followed by an underscore followed 210 by a meaningful name. It has been observed that these short 211 identifiers aid software implementers with identifying the 212 specification of the JSON member, and failure to use one could cause 213 an implementer to assume the server is erroneously using a name from 214 this specification. This allowance does not apply to jCard 215 ([RFC7095]) objects. The full JSON name (the prefix plus the 216 underscore plus the meaningful name) SHOULD adhere to the character 217 and name limitations of the prefix registry described in 218 [I-D.ietf-weirds-using-http]. Failure to use these limitations could 219 result in slower adoption as these limitations have been observed to 220 aid some client programming models. 222 Consider the following JSON response with JSON members, all of which 223 are specified in this document. 225 { 226 "handle" : "ABC123", 227 "remarks" : 228 [ 229 { 230 "description" : 231 [ 232 "She sells sea shells down by the sea shore.", 233 "Originally written by Terry Sullivan." 234 ] 235 } 236 ] 237 } 239 Figure 1 241 If The Registry of the Moon desires to express information not found 242 in this specification, it might select "lunarNic" as its identifying 243 prefix and insert, as an example, the member named 244 "lunarNic_beforeOneSmallStep" to signify registrations occurring 245 before the first moon landing and the member named 246 "lunarNic_harshMistressNotes" containing other descriptive text. 248 Consider the following JSON response with JSON names, some of which 249 should be ignored by clients without knowledge of their meaning. 251 { 252 "handle" : "ABC123", 253 "lunarNic_beforeOneSmallStep" : "TRUE THAT!", 254 "remarks" : 255 [ 256 { 257 "description" : 258 [ 259 "She sells sea shells down by the sea shore.", 260 "Originally written by Terry Sullivan." 261 ] 262 } 263 ], 264 "lunarNic_harshMistressNotes" : 265 [ 266 "In space,", 267 "nobody can hear you scream." 268 ] 269 } 271 Figure 2 273 Insertion of unrecognized members ignored by clients may also be used 274 for future revisions to this specification. 276 Clients processing JSON responses need to be prepared for members 277 representing registration data specified in this document to be 278 absent from a response. In other words, servers are free to not 279 include JSON members containing registration data based on their own 280 policies. 282 Finally, all JSON names specified in this document are case 283 sensitive. Both servers and clients MUST transmit and process them 284 using the specified character case. 286 3. Common Data Types 288 JSON [RFC7159] defines the data types of a number, character string, 289 boolean, array, object and null. This section describes the 290 semantics and/or syntax reference for common, JSON character strings 291 used in this document. 293 handle: DNRs and RIRs have registry-unique identifiers that 294 may be used to specifically reference an object 295 instance. The semantics of this data type as found 296 in this document are to be a registry-unique 297 reference to the closest enclosing object where the 298 value is found. The data type names 'registryId', 299 'roid', 'nic-handle', 'registrationNo', etc. are 300 terms often synonymous with this data type. In 301 this document, the term 'handle' is used. The term 302 exposed to users by clients is a presentation issue 303 beyond the scope of this document. 305 IPv4 addresses: The representation of IPv4 addresses in this 306 document uses the dotted-decimal notation. An 307 example of this textual representation is 308 '192.0.2.0'. 310 IPv6 addresses: The representation of IPv6 addresses in this 311 document follow the forms outlined in [RFC5952]. 312 An example of this textual representation is 313 '2001:db8::1:0:0:1'. 315 country codes: Where the identity of a geopolitical nation or 316 country is needed, these identities are represented 317 with the alpha-2 or two-character country code 318 designation as defined in [ISO.3166.1988]. The 319 alpha-2 representation is used because it is freely 320 available whereas the alpha-3 and numeric-3 321 standards are not. 323 LDH names: Textual representations of DNS names where the 324 labels of the domain are all "letters, digits, 325 hyphen" labels as described by [RFC5890]. Trailing 326 periods are optional. 328 Unicode names: Textual representations of DNS names where one or 329 more of the labels are U-labels as described by 330 [RFC5890]. Trailing periods are optional. 332 dates and times: The syntax for values denoting dates and times is 333 defined in [RFC3339]. 335 URIs: The syntax for values denoting a Uniform Resource 336 Identifier (URI) is defined by [RFC3986]. 338 Contact information is defined using jCards (JSON vCards) as 339 described in [RFC7095] 341 4. Common Data Structures 343 This section defines common data structures used in responses and 344 object classes. 346 4.1. RDAP Conformance 348 The data structure named "rdapConformance" is an array of strings, 349 each providing a hint as to the specifications used in the 350 construction of the response. This data structure appears only in 351 the top most JSON object of a response. 353 An example rdapConformance data structure: 355 "rdapConformance" : 356 [ 357 "rdap_level_0" 358 ] 360 Figure 3 362 The string literal "rdap_level_0" signifies conformance with this 363 specification. When custom JSON values are inserted into responses, 364 conformance to those custom specifications MUST use a string prefixed 365 with the appropriate identifier from the IANA RDAP Extensions 366 registry specified in [I-D.ietf-weirds-using-http]. For example, if 367 the fictional Registry of the Moon wants to signify that their JSON 368 responses are conformant with their registered extensions, the string 369 used might be "lunarNIC_level_0". These prefixes aid the 370 identification of specifications for software implementers, and 371 failure to use them could result in slower adoption of extensions. 373 Example rdapConformance structure with custom extensions noted: 375 "rdapConformance" : 376 [ 377 "rdap_level_0", 378 "lunarNic_level_0" 379 ] 381 Figure 4 383 4.2. Links 385 The "links" array is found in data structures to signify links to 386 other resources on the Internet. The relationship of these links is 387 defined by the IANA registry described by [RFC5988]. 389 The following is an example of the link structure: 391 { 392 "value" : "http://example.com/context_uri", 393 "rel" : "self", 394 "href" : "http://example.com/target_uri", 395 "hreflang" : [ "en", "ch" ], 396 "title" : "title", 397 "media" : "screen", 398 "type" : "application/json" 399 } 401 Figure 5 403 The JSON name/values of "rel", "href", "hreflang", "title", "media", 404 and "type" correspond to values found in Section 5 of [RFC5988]. The 405 "value" JSON value is the context URI as described by [RFC5988]. The 406 "href" JSON value MUST be specified. All other JSON values are 407 OPTIONAL. 409 This is an example of the "links" array as it might be found in an 410 object class: 412 "links" : 413 [ 414 { 415 "value" : "http://example.com/ip/2001:db8::123", 416 "rel" : "self", 417 "href" : "http://example.com/ip/2001:db8::123", 418 "type" : "application/rdap+json" 419 }, 420 { 421 "value" : "http://example.com/ip/2001:db8::123", 422 "rel" : "up", 423 "href" : "http://example.com/ip/2001:db8::/48", 424 "type" : "application/rdap+json" 425 } 427 ] 429 Figure 6 431 4.3. Notices And Remarks 433 The "notices" and "remarks" data structures take the same form. The 434 "notices" structure denotes information about the service providing 435 RDAP information and/or information about the entire response, 436 whereas the "remarks" structure denotes information about the object 437 class that contains it (see Section 5 regarding object classes). 439 Both are arrays of objects. Each object contains an optional "title" 440 string representing the title of the object, an optional "type" 441 string denoting a registered type of remark or notice (see 442 Section 10.2.1), an array of strings named "description" for the 443 purposes of conveying any descriptive text, and an optional "links" 444 array as described in Section 4.2. 446 An example of the notices data structure: 448 "notices" : 449 [ 450 { 451 "title" : "Terms of Use", 452 "description" : 453 [ 454 "Service subject to The Registry of the Moon's TOS.", 455 "Copyright (c) 2020 LunarNIC" 456 ], 457 "links" : 458 [ 459 { 460 "value" : "http://example.net/entity/XXXX", 461 "rel" : "alternate", 462 "type" : "text/html", 463 "href" : "http://www.example.com/terms_of_use.html" 464 } 465 ] 466 } 467 ] 469 Figure 7 471 It is the job of the clients to determine line breaks, spacing and 472 display issues for sentences within the character strings of the 473 "description" array. Each string in the "description" array contains 474 a single complete division of human readable text indicating to 475 clients where there are semantic breaks. 477 An example of the remarks data structure: 479 "remarks" : 480 [ 481 { 482 "description" : 483 [ 484 "She sells sea shells down by the sea shore.", 485 "Originally written by Terry Sullivan." 486 ] 487 } 488 ] 490 Figure 8 492 Note that objects in the "remarks" array may also have a "links" 493 array. 495 While the "title" and "description" fields are intended primarily for 496 human consumption, the "type" string contains a well-known value to 497 be registered with IANA (see Section 10.2.1) for programmatic use. 499 An example of the remarks data structure: 501 "remarks" : 502 [ 503 { 504 "type" : "object truncated due to authorization", 505 "description" : 506 [ 507 "Some registration data may not have been given.", 508 "Use proper authorization credentials to see all of it." 509 ] 510 } 511 ] 513 Figure 9 515 While the "remarks" array will appear in many object classes in a 516 response, the "notices" array appears only in the top most object of 517 a response. 519 4.4. Language Identifier 521 This data structure consists solely of a name/value pair, where the 522 name is "lang" and the value is a string containing a language 523 identifier as described in [RFC5646]. 525 "lang" : "mn-Cyrl-MN" 527 Figure 10 529 The 'lang' attribute may appear anywhere in an object class or data 530 structure except for in jCard objects. 532 4.5. Events 534 This data structure represents events that have occurred on an 535 instance of an object class (see Section 5 regarding object classes). 537 This is an example of an "events" array. 539 "events" : 540 [ 541 { 542 "eventAction" : "registration", 543 "eventActor" : "SOMEID-LUNARNIC", 544 "eventDate" : "1990-12-31T23:59:59Z" 545 }, 546 { 547 "eventAction" : "last changed", 548 "eventActor" : "OTHERID-LUNARNIC", 549 "eventDate" : "1991-12-31T23:59:59Z" 550 } 551 ] 553 Figure 11 555 The "events" array consists of objects, each with the following 556 members: 558 o 'eventAction' -- a string denoting the reason for the event 560 o 'eventActor' -- an optional identifier denoting the actor 561 responsible for the event 563 o 'eventDate' -- a string containing the time and date the event 564 occurred. 566 o 'links' -- see Section 4.2. 568 Events can be future dated. One use case for future dating of events 569 is to denote when an object expires from a registry. 571 The 'links' array in this data structure is provided for references 572 to the event actor. In order to reference an RDAP entity, a "rel" of 573 "related" and a "type" of "application/rdap+json" is used in the link 574 reference. 576 See Section 10.2.3 for a list of values for the 'eventAction' string. 577 See Appendix B regarding the various ways events can be modeled. 579 4.6. Status 581 This data structure, named 'status', is an array of strings 582 indicating the state of a registered object (see Section 10.2.2 for a 583 list of values). 585 4.7. Port 43 WHOIS Server 587 This data structure, a member named 'port43', is a simple string 588 containing the fully-qualified host name or IP address of the WHOIS 589 [RFC3912] server where the containing object instance may be found. 590 Note that this is not a URI, as there is no WHOIS URI scheme. 592 4.8. Public IDs 594 This data structure maps a public identifier to an object class. It 595 is named 'publicIds' and is an array of objects, with each object 596 containing the following members: 598 o type - a string denoting the type of public identifier 600 o identifier - a public identifier of the type denoted by 'type' 602 The following is an example of a 'publicIds' structure. 604 "publicIds": 605 [ 606 { 607 "type":"IANA Registrar ID", 608 "identifier":"1" 609 } 610 ] 612 Figure 12 614 4.9. Object Class Name 616 This data structure, a member named "objectClassName", gives the 617 object class name of a particular object as a string. This 618 identifies the type of object being processed. An objectClassName is 619 REQUIRED in all RDAP response objects so that the type of the object 620 can be interpreted. 622 4.10. An Example 624 This is an example response with both rdapConformance and notices 625 embedded: 627 { 628 "rdapConformance" : 629 [ 630 "rdap_level_0" 631 ], 632 "notices" : 633 [ 634 { 635 "title" : "Content Removed", 636 "description" : 637 [ 638 "Without full authorization, content has been removed.", 639 "Sorry, dude!" 640 ], 641 "links" : 642 [ 643 { 644 "value" : "http://example.net/ip/192.0.2.0/24", 645 "rel" : "alternate", 646 "type" : "text/html", 647 "href" : "http://www.example.com/redaction_policy.html" 648 } 649 ] 650 } 651 ], 652 "lang" : "en", 653 "objectClassName" : "ip network", 654 "startAddress" : "192.0.2.0", 655 "endAddress" : "192.0.2.255", 656 "handle" : "XXXX-RIR", 657 "ipVersion" : "v4", 658 "name": "NET-RTR-1", 659 "parentHandle" : "YYYY-RIR", 660 "remarks" : 661 [ 662 { 663 "description" : 664 [ 665 "She sells sea shells down by the sea shore.", 666 "Originally written by Terry Sullivan." 667 ] 668 } 669 ] 670 } 672 Figure 13 674 5. Object Classes 676 Object classes represent structures appropriate for a response from 677 the queries specified in [I-D.ietf-weirds-rdap-query]. 679 Each object class contains a "links" array as specified in 680 Section 4.2. For every object class instance in a response, whether 681 the object class instance is directly representing the response to a 682 query or is embedded in other object class instances or is an item in 683 a search result set, servers SHOULD provide a link representing a URI 684 for that object class instance using the "self" relationship as 685 described in the IANA registry specified by [RFC5988]. As explained 686 in Section 5.2, this may be not always be possible for name server 687 data. Clients MUST be able to process object instances without a 688 "self" link. When present, clients can use the self link for caching 689 data. Servers MAY provide more than one "self" link for any given 690 object instance. Failure to provide any "self" link by a server may 691 result in clients being unable to cache object class instances. 693 Clients using "self" links for caching SHOULD not cache any object 694 class instances where the authority of the self link is different 695 than the authority of the server returning the data. Failing to do 696 so might result in cache poisoning. 698 Self links MUST contain a "type" element containing the "application/ 699 rdap+json" media type when referencing RDAP object instances as 700 defined by this document. 702 This is an example of the "links" array with a self link to an object 703 class: 705 "links" : 706 [ 707 { 708 "value" : "http://example.com/ip/2001:db8::123", 709 "rel" : "self", 710 "href" : "http://example.com/ip/2001:db8::123", 711 "type" : "application/rdap+json" 712 } 713 ] 715 Figure 14 717 5.1. The Entity Object Class 719 The entity object class appears throughout this document and is an 720 appropriate response for the /entity/XXXX query defined in 721 Registration Data Access Protocol Lookup Format 723 [I-D.ietf-weirds-rdap-query]. This object class represents the 724 information of organizations, corporations, governments, non-profits, 725 clubs, individual persons, and informal groups of people. All of 726 these representations are so similar that it is best to represent 727 them in JSON [RFC7159] with one construct, the entity object class, 728 to aid in the re-use of code by implementers. 730 The entity object class uses jCard [RFC7095] to represent contact 731 information, such as postal addresses, email addresses, phone numbers 732 and names of organizations and individuals. Many of the types of 733 information that can be represented with jCard have no use in RDAP, 734 such as birthdays, anniversaries, and gender. 736 The entity object is served by both RIRs and DNRs. The following is 737 an example of an entity that might be served by an RIR. 739 { 740 "objectClassName" : "entity", 741 "handle":"XXXX", 742 "vcardArray":[ 743 "vcard", 744 [ 745 ["version", {}, "text", "4.0"], 746 ["fn", {}, "text", "Joe User"], 747 ["n", {}, "text", 748 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 749 ], 750 ["kind", {}, "text", "individual"], 751 ["lang", { 752 "pref":"1" 753 }, "language-tag", "fr"], 754 ["lang", { 755 "pref":"2" 756 }, "language-tag", "en"], 757 ["org", { 758 "type":"work" 759 }, "text", "Example"], 760 ["title", {}, "text", "Research Scientist"], 761 ["role", {}, "text", "Project Lead"], 762 ["adr", 763 { "type":"work" }, 764 "text", 765 [ 766 "", 767 "Suite 1234", 768 "4321 Rue Somewhere", 769 "Quebec", 770 "QC", 771 "G1V 2M2", 772 "Canada" 773 ] 774 ], 775 ["adr", 776 { 777 "type":"home", 778 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 779 }, 780 "text", 781 [ 782 "", "", "", "", "", "", "" 783 ] 784 ], 785 ["tel", 786 { 787 "type":["work", "voice"], 788 "pref":"1" 789 }, 790 "uri", 791 "tel:+1-555-555-1234;ext=102" 792 ], 793 ["tel", 794 { "type":["work", "cell", "voice", "video", "text"] }, 795 "uri", 796 "tel:+1-555-555-4321" 797 ], 798 ["email", 799 { "type":"work" }, 800 "text", 801 "joe.user@example.com" 802 ], 803 ["geo", { 804 "type":"work" 805 }, "uri", "geo:46.772673,-71.282945"], 806 ["key", 807 { "type":"work" }, 808 "uri", 809 "http://www.example.com/joe.user/joe.asc" 810 ], 811 ["tz", {}, 812 "utc-offset", "-05:00"], 813 ["url", { "type":"home" }, 814 "uri", "http://example.org"] 815 ] 816 ], 817 "roles":[ "registrar" ], 818 "publicIds":[ 819 { 820 "type":"IANA Registrar ID", 821 "identifier":"1" 822 } 823 ], 824 "remarks":[ 825 { 826 "description":[ 827 "She sells sea shells down by the sea shore.", 828 "Originally written by Terry Sullivan." 829 ] 830 } 831 ], 832 "links":[ 833 { 834 "value":"http://example.com/entity/XXXX", 835 "rel":"self", 836 "href":"http://example.com/entity/XXXX", 837 "type" : "application/rdap+json" 838 } 839 ], 840 "events":[ 841 { 842 "eventAction":"registration", 843 "eventDate":"1990-12-31T23:59:59Z" 844 } 845 ], 846 "asEventActor":[ 847 { 848 "eventAction":"last changed", 849 "eventDate":"1991-12-31T23:59:59Z" 850 } 851 ] 852 } 854 Figure 15 856 The entity object class can contain the following members: 858 o objectClassName -- the string "entity" 860 o handle -- a string representing an registry unique identifier of 861 the entity 863 o vcardArray -- a jCard with the entity's contact information 864 o roles -- an array of strings, each signifying the relationship an 865 object would have with its closest containing object (see 866 Section 10.2.4 for a list of values) 868 o publicIds - see Section 4.8 870 o entities - an array of entity objects as defined by this section. 872 o remarks -- see Section 4.3 874 o links -- see Section 4.2 876 o events -- see Section 4.5 878 o asEventActor -- this data structure takes the same form as the 879 'events' data structure (see Section 4.5), but each object in the 880 array MUST NOT have an 'eventActor' member. These objects denote 881 that the entity is an event actor for the given events. See 882 Appendix B regarding the various ways events can be modeled. 884 o status -- see Section 4.6 886 o port43 -- see Section 4.7 888 o networks -- an array of IP network objects as defined in 889 Section 5.4 891 o autnums -- an array of autnum objects as defined in Section 5.5 893 Entities may also have other entities embedded with them in an array. 894 This can be used to model an organization with specific individuals 895 fulfilling designated roles of responsibility. 897 The following is an elided example of an entity with embedded 898 entities. 900 { 901 "objectClassName" : "entity", 902 "handle" : "ANENTITY", 903 "roles" : [ "registrar" ], 904 ... 905 "entities" : 906 [ 907 { 908 "objectClassName" : "entity", 909 "handle": "ANEMBEDDEDENTITY", 910 "roles" : [ "technical" ], 911 ... 912 }, 913 ... 914 ], 915 ... 916 } 918 Figure 16 920 The following is an example of a entity that might be served by a 921 DNR. 923 { 924 "objectClassName" : "entity", 925 "handle":"XXXX", 926 "vcardArray":[ 927 "vcard", 928 [ 929 ["version", {}, "text", "4.0"], 930 ["fn", {}, "text", "Joe User"], 931 ["kind", {}, "text", "individual"], 932 ["lang", { 933 "pref":"1" 934 }, "language-tag", "fr"], 935 ["lang", { 936 "pref":"2" 937 }, "language-tag", "en"], 938 ["org", { 939 "type":"work" 940 }, "text", "Example"], 941 ["title", {}, "text", "Research Scientist"], 943 ["role", {}, "text", "Project Lead"], 944 ["adr", 945 { "type":"work" }, 946 "text", 947 [ 948 "", 949 "Suite 1234", 950 "4321 Rue Somewhere", 951 "Quebec", 952 "QC", 953 "G1V 2M2", 954 "Canada" 955 ] 956 ], 957 ["tel", 958 { "type":["work", "voice"], "pref":"1" }, 959 "uri", "tel:+1-555-555-1234;ext=102" 960 ], 961 ["email", 962 { "type":"work" }, 963 "text", "joe.user@example.com" 964 ] 965 ] 966 ], 967 "status":[ "validated", "locked" ], 968 "remarks":[ 969 { 970 "description":[ 971 "She sells sea shells down by the sea shore.", 972 "Originally written by Terry Sullivan." 973 ] 974 } 975 ], 976 "links":[ 977 { 978 "value":"http://example.com/entity/XXXX", 979 "rel":"self", 980 "href":"http://example.com/entity/XXXX", 981 "type":"application/rdap+json" 982 } 983 ], 984 "port43":"whois.example.net", 985 "events":[ 986 { 987 "eventAction":"registration", 988 "eventDate":"1990-12-31T23:59:59Z" 989 }, 990 { 991 "eventAction":"last changed", 992 "eventDate":"1991-12-31T23:59:59Z", 993 "eventActor":"joe@example.com" 994 } 995 ] 996 } 998 Figure 17 1000 See Appendix A for use of the entity object class to model various 1001 types of entities found in both RIRs and DNRs. See Appendix C 1002 regarding structured vs. unstructured postal addresses in entities. 1004 5.2. The Nameserver Object Class 1006 The nameserver object class represents information regarding DNS name 1007 servers used in both forward and reverse DNS. RIRs and some DNRs 1008 register or expose nameserver information as an attribute of a domain 1009 name, while other DNRs model nameservers as "first class objects". 1011 The nameserver object class accommodates both models and degrees of 1012 variation in between. 1014 The following is an example of a nameserver object. 1016 { 1017 "objectClassName" : "nameserver", 1018 "handle" : "XXXX", 1019 "ldhName" : "ns1.xn--fo-5ja.example", 1020 "unicodeName" : "ns1.foo.example", 1021 "status" : [ "active" ], 1022 "ipAddresses" : 1023 { 1024 "v4": [ "192.0.2.1", "192.0.2.2" ], 1025 "v6": [ "2001:db8::123" ] 1026 }, 1027 "remarks" : 1028 [ 1029 { 1030 "description" : 1031 [ 1032 "She sells sea shells down by the sea shore.", 1033 "Originally written by Terry Sullivan." 1034 ] 1035 } 1036 ], 1037 "links" : 1038 [ 1039 { 1040 "value" : "http://example.net/nameserver/xxxx", 1041 "rel" : "self", 1042 "href" : "http://example.net/nameserver/xxxx", 1043 "type" : "application/rdap+json" 1044 } 1045 ], 1046 "port43" : "whois.example.net", 1047 "events" : 1048 [ 1049 { 1050 "eventAction" : "registration", 1051 "eventDate" : "1990-12-31T23:59:59Z" 1052 }, 1053 { 1054 "eventAction" : "last changed", 1055 "eventDate" : "1991-12-31T23:59:59Z", 1056 "eventActor" : "joe@example.com" 1057 } 1058 ] 1059 } 1061 Figure 18 1063 Figure 18 is an example of a nameserver object with all values given. 1064 Registries using a first-class nameserver data model would embed this 1065 in domain objects as well as allowing references to it with the 1066 "/nameserver" query type (all depending on the registry operators 1067 policy). Other registries may pare back the information as needed. 1068 Figure 19 is an example of a nameserver object as would be found in 1069 RIRs and some DNRs, while Figure 20 is an example of a nameserver 1070 object as would be found in other DNRs. 1072 The following is an example of the simplest nameserver object: 1074 { 1075 "objectClassName" : "nameserver", 1076 "ldhName" : "ns1.example.com" 1077 } 1079 Figure 19 1081 The following is an example of a simple nameserver object that might 1082 be commonly used by DNRs: 1084 { 1085 "objectClassName" : "nameserver", 1086 "ldhName" : "ns1.example.com", 1087 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 1088 } 1090 Figure 20 1092 As nameservers can be modeled by some registries to be first-class 1093 objects, they may also have an array of entities (Section 5.1) 1094 embedded to signify parties responsible for the maintenance, 1095 registrations, etc. of the nameservers. 1097 The following is an elided example of a nameserver with embedded 1098 entities. 1100 { 1101 "objectClassName" : "nameserver", 1102 "handle" : "XXXX", 1103 "ldhName" : "ns1.xn--fo-5ja.example", 1104 ... 1105 "entities" : 1106 [ 1107 ... 1108 ], 1109 ... 1110 } 1112 Figure 21 1114 The nameserver object class can contain the following members: 1116 o objectClassName - the string "nameserver" 1118 o handle -- a string representing an registry unique identifier of 1119 the nameserver 1121 o ldhName -- a string containing the LDH name of the nameserver (see 1122 Section 3) 1124 o unicodeName -- a string containing a DNS Unicode name of the 1125 nameserver (see Section 3) 1127 o ipAddresses -- an object containing the following members: 1129 * v6 -- an array of strings containing IPv6 addresses of the 1130 nameserver 1132 * v4 -- an array of strings containing IPv4 addresses of the 1133 nameserver 1135 o entities -- an array of entity objects as defined by Section 5.1. 1137 o status - see Section 4.6 1139 o remarks - see Section 4.3 1141 o links - see Section 4.2 1142 o port43 - see Section 4.7 1144 o events - see Section 4.5 1146 5.3. The Domain Object Class 1148 The domain object class represents a DNS name and point of 1149 delegation. For RIRs these delegation points are in the reverse DNS 1150 tree, whereas for DNRs these delegation points are in the forward DNS 1151 tree. 1153 In both cases, the high level structure of the domain object class 1154 consists of information about the domain registration, nameserver 1155 information related to the domain name, and entities related to the 1156 domain name (e.g. registrant information, contacts, etc.). 1158 The following is an elided example of the domain object showing the 1159 high level structure: 1161 { 1162 "objectClassName" : "domain", 1163 "handle" : "XXX", 1164 "ldhName" : "blah.example.com", 1165 ... 1166 "nameservers" : 1167 [ 1168 ... 1169 ], 1170 ... 1171 "entities" : 1172 [ 1173 ... 1174 ] 1175 } 1177 Figure 22 1179 The domain object class can contain the following members: 1181 o objectClassName -- the string "domain" 1183 o handle -- a string representing a registry unique identifier of 1184 the domain object instance 1186 o ldhName -- a string describing a domain name in LDH form as 1187 described in Section 3 1189 o unicodeName -- a string containing a domain name with U-labels as 1190 described in Section 3 1192 o variants -- an array of objects, each containing the following 1193 values: 1195 * relation -- an array of strings, with each string denoting the 1196 relationship between the variants and the containing domain 1197 object (see Section 10.2.5 for a list of suggested variant 1198 relations). 1200 * idnTable -- the name of the IDN table of codepoints, such as 1201 one listed with the IANA (see IDN tables [IANA_IDNTABLES]). 1203 * variantNames -- an array of objects, with each object 1204 containing an "ldhName" member and a "unicodeName" member (see 1205 Section 3). 1207 o nameservers -- an array of nameserver objects as defined by 1208 Section 5.2 1210 o secureDNS -- an object with the following members: 1212 * zoneSigned -- true if the zone has been signed, false 1213 otherwise. 1215 * delegationSigned -- boolean true if there are DS records in the 1216 parent, false otherwise. 1218 * maxSigLife -- an integer representing the signature life time 1219 in seconds to be used when creating the RRSIG DS record in the 1220 parent zone [RFC5910]. 1222 * dsData - an array of objects, each with the following members: 1224 + keyTag -- an integer as specified by the key tag field of a 1225 DNS DS record as specified by RFC 4034 [RFC4034] in 1226 presentation format 1228 + algorithm -- an integer as specified by the algorithm field 1229 of a DNS DS record as described by RFC 4034 in presentation 1230 format 1232 + digest -- a string as specified by the digest field of a DNS 1233 DS record as specified by RFC 4034 in presentation format 1235 + digestType -- an integer as specified by the digest type 1236 field of a DNS DS record as specified by RFC 4034 in 1237 presentation format 1239 + events - see Section 4.5 1241 + links - see Section 4.2 1243 * keyData - an array of objects, each with the following members: 1245 + flags -- an integer representing the flags field value in 1246 the DNSKEY record [RFC4034] in presentation format 1248 + protocol - an integer representation of the protocol field 1249 value of the DNSKEY record [RFC4034] in presentation format 1251 + publicKey - a string representation of the public key in the 1252 DNSKEY record [RFC4034] in presentation format 1254 + algorithm -- an integer as specified by the algorithm field 1255 of a DNSKEY record as specified by RFC 4034 [RFC4034] in 1256 presentation format 1258 + events - see Section 4.5 1260 + links - see Section 4.2 1262 See Appendix D for background information on these objects. 1264 o entities -- an array of entity objects as defined by Section 5.1. 1266 o status - see Section 4.6 1268 o publicIds - see Section 4.8 1270 o remarks - see Section 4.3 1272 o links - see Section 4.2 1274 o port43 - see Section 4.7 1276 o events - see Section 4.5 1278 o network - represents the IP network for which a reverse DNS domain 1279 is referenced. See Section 5.4 1281 The following is an example of a JSON domain object representing a 1282 reverse DNS delegation point that might be served by an RIR. 1284 { 1285 "objectClassName" : "domain", 1286 "handle" : "XXXX", 1287 "ldhName" : "0.2.192.in-addr.arpa", 1288 "nameservers" : 1289 [ 1290 { 1291 "objectClassName" : "nameserver", 1292 "ldhName" : "ns1.rir.example" 1293 }, 1294 { 1295 "objectClassName" : "nameserver", 1296 "ldhName" : "ns2.rir.example" 1297 } 1298 ], 1299 "secureDNS": 1300 { 1301 "delegationSigned": true, 1302 "dsData": 1303 [ 1304 { 1305 "keyTag": 12345, 1306 "algorithm": 3, 1307 "digestType": 1, 1308 "digest": "49FD46E6C4B45C55D4AC" 1309 } 1310 ] 1311 }, 1312 "remarks" : 1313 [ 1314 { 1315 "description" : 1316 [ 1317 "She sells sea shells down by the sea shore.", 1318 "Originally written by Terry Sullivan." 1319 ] 1320 } 1321 ], 1322 "links" : 1323 [ 1324 { 1325 "value": "http://example.net/domain/XXXX", 1326 "rel" : "self", 1327 "href" : "http://example.net/domain/XXXXX", 1328 "type" : "application/rdap+json" 1329 } 1330 ], 1331 "events" : 1333 [ 1334 { 1335 "eventAction" : "registration", 1336 "eventDate" : "1990-12-31T23:59:59Z" 1337 }, 1338 { 1339 "eventAction" : "last changed", 1340 "eventDate" : "1991-12-31T23:59:59Z", 1341 "eventActor" : "joe@example.com" 1342 } 1343 ], 1344 "entities" : 1345 [ 1346 { 1347 "objectClassName" : "entity", 1348 "handle" : "XXXX", 1349 "vcardArray":[ 1350 "vcard", 1351 [ 1352 ["version", {}, "text", "4.0"], 1353 ["fn", {}, "text", "Joe User"], 1354 ["kind", {}, "text", "individual"], 1355 ["lang", { 1356 "pref":"1" 1357 }, "language-tag", "fr"], 1358 ["lang", { 1359 "pref":"2" 1360 }, "language-tag", "en"], 1361 ["org", { 1362 "type":"work" 1363 }, "text", "Example"], 1364 ["title", {}, "text", "Research Scientist"], 1365 ["role", {}, "text", "Project Lead"], 1366 ["adr", 1367 { "type":"work" }, 1368 "text", 1369 [ 1370 "", 1371 "Suite 1234", 1372 "4321 Rue Somewhere", 1373 "Quebec", 1374 "QC", 1375 "G1V 2M2", 1376 "Canada" 1377 ] 1378 ], 1379 ["tel", 1380 { "type":["work", "voice"], "pref":"1" }, 1381 "uri", "tel:+1-555-555-1234;ext=102" 1382 ], 1383 ["email", 1384 { "type":"work" }, 1385 "text", "joe.user@example.com" 1386 ] 1387 ] 1388 ], 1389 "roles" : [ "registrant" ], 1390 "remarks" : 1391 [ 1392 { 1393 "description" : 1394 [ 1395 "She sells sea shells down by the sea shore.", 1396 "Originally written by Terry Sullivan." 1397 ] 1398 } 1399 ], 1400 "links" : 1401 [ 1402 { 1403 "value": "http://example.net/entity/xxxx", 1404 "rel" : "self", 1405 "href" : "http://example.net/entity/xxxx", 1406 "type" : "application/rdap+json" 1407 } 1408 ], 1409 "events" : 1410 [ 1411 { 1412 "eventAction" : "registration", 1413 "eventDate" : "1990-12-31T23:59:59Z" 1414 }, 1415 { 1416 "eventAction" : "last changed", 1417 "eventDate" : "1991-12-31T23:59:59Z", 1418 "eventActor" : "joe@example.com" 1419 } 1420 ] 1421 } 1422 ], 1423 "network" : 1424 { 1425 "objectClassName" : "ip network", 1426 "handle" : "XXXX-RIR", 1427 "startAddress" : "192.0.2.0", 1428 "endAddress" : "192.0.2.255", 1429 "ipVersion" : "v6", 1430 "name": "NET-RTR-1", 1431 "type" : "DIRECT ALLOCATION", 1432 "country" : "AU", 1433 "parentHandle" : "YYYY-RIR", 1434 "status" : [ "active" ] 1435 } 1436 } 1438 Figure 23 1440 The following is an example of a JSON domain object representing a 1441 forward DNS delegation point that might be served by a DNR. 1443 { 1444 "objectClassName" : "domain", 1445 "handle" : "XXXX", 1446 "ldhName" : "xn--fo-5ja.example", 1447 "unicodeName" : "foo.example", 1448 "variants" : 1449 [ 1450 { 1451 "relation" : [ "registered", "conjoined" ], 1452 "variantNames" : 1453 [ 1454 { 1455 "ldhName" : "xn--fo-cka.example", 1456 "unicodeName" : "foo.example" 1457 }, 1458 { 1459 "ldhName" : "xn--fo-fka.example", 1460 "unicodeName" : "foeo.example" 1461 } 1462 ] 1463 }, 1464 { 1465 "relation" : [ "unregistered", "registration restricted" ], 1466 "idnTable": ".EXAMPLE Swedish", 1467 "variantNames" : 1468 [ 1469 { 1470 "ldhName": "xn--fo-8ja.example", 1471 "unicodeName" : "foo.example" 1472 } 1473 ] 1474 } 1476 ], 1477 "status" : [ "locked", "transfer prohibited" ], 1478 "publicIds":[ 1479 { 1480 "type":"ENS_Auth ID", 1481 "identifier":"1234567890" 1482 } 1483 ], 1484 "nameservers" : 1485 [ 1486 { 1487 "objectClassName" : "nameserver", 1488 "handle" : "XXXX", 1489 "ldhName" : "ns1.example.com", 1490 "status" : [ "active" ], 1491 "ipAddresses" : 1492 { 1493 "v6": [ "2001:db8::123", "2001:db8::124" ], 1494 "v4": [ "192.0.2.1", "192.0.2.2" ] 1495 }, 1496 "remarks" : 1497 [ 1498 { 1499 "description" : 1500 [ 1501 "She sells sea shells down by the sea shore.", 1502 "Originally written by Terry Sullivan." 1503 ] 1504 } 1505 ], 1506 "links" : 1507 [ 1508 { 1509 "value" : "http://example.net/nameserver/XXXX", 1510 "rel" : "self", 1511 "href" : "http://example.net/nameserver/XXXX", 1512 "type" : "application/rdap+json" 1513 } 1514 ], 1515 "events" : 1516 [ 1517 { 1518 "eventAction" : "registration", 1519 "eventDate" : "1990-12-31T23:59:59Z" 1520 }, 1521 { 1522 "eventAction" : "last changed", 1523 "eventDate" : "1991-12-31T23:59:59Z" 1525 } 1526 ] 1527 }, 1528 { 1529 "objectClassName" : "nameserver", 1530 "handle" : "XXXX", 1531 "ldhName" : "ns2.example.com", 1532 "status" : [ "active" ], 1533 "ipAddresses" : 1534 { 1535 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1536 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1537 }, 1538 "remarks" : 1539 [ 1540 { 1541 "description" : 1542 [ 1543 "She sells sea shells down by the sea shore.", 1544 "Originally written by Terry Sullivan." 1545 ] 1546 } 1547 ], 1548 "links" : 1549 [ 1550 { 1551 "value" : "http://example.net/nameserver/XXXX", 1552 "rel" : "self", 1553 "href" : "http://example.net/nameserver/XXXX", 1554 "type" : "application/rdap+json" 1555 } 1556 ], 1557 "events" : 1558 [ 1559 { 1560 "eventAction" : "registration", 1561 "eventDate" : "1990-12-31T23:59:59Z" 1562 }, 1563 { 1564 "eventAction" : "last changed", 1565 "eventDate" : "1991-12-31T23:59:59Z" 1566 } 1567 ] 1568 } 1569 ], 1570 "secureDNS": 1571 { 1572 "zoneSigned": true, 1573 "delegationSigned": true, 1574 "maxSigLife": 604800, 1575 "keyData": 1576 [ 1577 { 1578 "flags": 257, 1579 "protocol": 3, 1580 "algorithm": 1, 1581 "publicKey": "AQPJ////4Q==", 1582 "events": 1583 [ 1584 { 1585 "eventAction": "last changed", 1586 "eventDate": "2012-07-23T05:15:47Z" 1587 } 1588 ] 1589 } 1590 ] 1591 }, 1592 "remarks" : 1593 [ 1594 { 1595 "description" : 1596 [ 1597 "She sells sea shells down by the sea shore.", 1598 "Originally written by Terry Sullivan." 1599 ] 1600 } 1601 ], 1602 "links" : 1603 [ 1604 { 1605 "value": "http://example.net/domain/XXXX", 1606 "rel" : "self", 1607 "href" : "http://example.net/domain/XXXX", 1608 "type" : "application/rdap+json" 1609 } 1610 ], 1611 "port43" : "whois.example.net", 1612 "events" : 1613 [ 1614 { 1615 "eventAction" : "registration", 1616 "eventDate" : "1990-12-31T23:59:59Z" 1617 }, 1618 { 1619 "eventAction" : "last changed", 1620 "eventDate" : "1991-12-31T23:59:59Z", 1621 "eventActor" : "joe@example.com" 1622 }, 1623 { 1624 "eventAction" : "transfer", 1625 "eventDate" : "1991-12-31T23:59:59Z", 1626 "eventActor" : "joe@example.com" 1627 }, 1628 { 1629 "eventAction" : "expiration", 1630 "eventDate" : "2016-12-31T23:59:59Z", 1631 "eventActor" : "joe@example.com" 1632 } 1633 ], 1634 "entities" : 1635 [ 1636 { 1637 "objectClassName" : "entity", 1638 "handle" : "XXXX", 1639 "vcardArray":[ 1640 "vcard", 1641 [ 1642 ["version", {}, "text", "4.0"], 1643 ["fn", {}, "text", "Joe User"], 1644 ["kind", {}, "text", "individual"], 1645 ["lang", { 1646 "pref":"1" 1647 }, "language-tag", "fr"], 1648 ["lang", { 1649 "pref":"2" 1650 }, "language-tag", "en"], 1651 ["org", { 1652 "type":"work" 1653 }, "text", "Example"], 1654 ["title", {}, "text", "Research Scientist"], 1655 ["role", {}, "text", "Project Lead"], 1656 ["adr", 1657 { "type":"work" }, 1658 "text", 1659 [ 1660 "", 1661 "Suite 1234", 1662 "4321 Rue Somewhere", 1663 "Quebec", 1664 "QC", 1665 "G1V 2M2", 1666 "Canada" 1667 ] 1668 ], 1670 ["tel", 1671 { "type":["work", "voice"], "pref":"1" }, 1672 "uri", "tel:+1-555-555-1234;ext=102" 1673 ], 1674 ["email", 1675 { "type":"work" }, 1676 "text", "joe.user@example.com" 1677 ] 1678 ] 1679 ], 1680 "status" : [ "validated", "locked" ], 1681 "roles" : [ "registrant" ], 1682 "remarks" : 1683 [ 1684 { 1685 "description" : 1686 [ 1687 "She sells sea shells down by the sea shore.", 1688 "Originally written by Terry Sullivan." 1689 ] 1690 } 1691 ], 1692 "links" : 1693 [ 1694 { 1695 "value" : "http://example.net/entity/xxxx", 1696 "rel" : "self", 1697 "href" : "http://example.net/entity/xxxx", 1698 "type" : "application/rdap+json" 1699 } 1700 ], 1701 "events" : 1702 [ 1703 { 1704 "eventAction" : "registration", 1705 "eventDate" : "1990-12-31T23:59:59Z" 1706 }, 1707 { 1708 "eventAction" : "last changed", 1709 "eventDate" : "1991-12-31T23:59:59Z" 1710 } 1711 ] 1712 } 1713 ] 1714 } 1716 Figure 24 1718 5.4. The IP Network Object Class 1720 The IP network object class models IP network registrations found in 1721 RIRs and is the expected response for the "/ip" query as defined by 1722 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1723 for DNRs. The high level structure of the IP network object class 1724 consists of information about the network registration and entities 1725 related to the IP network (e.g. registrant information, contacts, 1726 etc...). 1728 The following is an elided example of the IP network object type 1729 showing the high level structure: 1731 { 1732 "objectClassName" : "ip network", 1733 "handle" : "XXX", 1734 ... 1735 "entities" : 1736 [ 1737 ... 1738 ] 1739 } 1741 Figure 25 1743 The following is an example of the JSON object for the network 1744 registration information. 1746 { 1747 "objectClassName" : "ip network", 1748 "handle" : "XXXX-RIR", 1749 "startAddress" : "2001:db8::0", 1750 "endAddress" : "2001:db8:0:FFFF:FFFF:FFFF:FFFF:FFFF", 1751 "ipVersion" : "v6", 1752 "name": "NET-RTR-1", 1753 "type" : "DIRECT ALLOCATION", 1754 "country" : "AU", 1755 "parentHandle" : "YYYY-RIR", 1756 "status" : [ "active" ], 1757 "remarks" : 1758 [ 1759 { 1760 "description" : 1761 [ 1762 "She sells sea shells down by the sea shore.", 1763 "Originally written by Terry Sullivan." 1764 ] 1765 } 1766 ], 1767 "links" : 1768 [ 1769 { 1770 "value" : "http://example.net/ip/2001:db8::/48", 1771 "rel" : "self", 1772 "href" : "http://example.net/ip/2001:db8::/48", 1773 "type" : "application/rdap+json" 1774 }, 1775 { 1776 "value" : "http://example.net/ip/2001:db8::/48", 1777 "rel" : "up", 1778 "href" : "http://example.net/ip/2001:C00::/23", 1779 "type" : "application/rdap+json" 1780 } 1781 ], 1782 "events" : 1783 [ 1784 { 1785 "eventAction" : "registration", 1786 "eventDate" : "1990-12-31T23:59:59Z" 1787 }, 1788 { 1789 "eventAction" : "last changed", 1790 "eventDate" : "1991-12-31T23:59:59Z" 1791 } 1792 ], 1793 "entities" : 1794 [ 1795 { 1796 "objectClassName" : "entity", 1797 "handle" : "XXXX", 1798 "vcardArray":[ 1799 "vcard", 1800 [ 1801 ["version", {}, "text", "4.0"], 1802 ["fn", {}, "text", "Joe User"], 1803 ["kind", {}, "text", "individual"], 1804 ["lang", { 1805 "pref":"1" 1806 }, "language-tag", "fr"], 1807 ["lang", { 1808 "pref":"2" 1809 }, "language-tag", "en"], 1810 ["org", { 1811 "type":"work" 1812 }, "text", "Example"], 1813 ["title", {}, "text", "Research Scientist"], 1814 ["role", {}, "text", "Project Lead"], 1815 ["adr", 1816 { "type":"work" }, 1817 "text", 1818 [ 1819 "", 1820 "Suite 1234", 1821 "4321 Rue Somewhere", 1822 "Quebec", 1823 "QC", 1824 "G1V 2M2", 1825 "Canada" 1826 ] 1827 ], 1828 ["tel", 1829 { "type":["work", "voice"], "pref":"1" }, 1830 "uri", "tel:+1-555-555-1234;ext=102" 1831 ], 1832 ["email", 1833 { "type":"work" }, 1834 "text", "joe.user@example.com" 1835 ] 1836 ] 1837 ], 1838 "roles" : [ "registrant" ], 1839 "remarks" : 1840 [ 1841 { 1842 "description" : 1843 [ 1844 "She sells sea shells down by the sea shore.", 1845 "Originally written by Terry Sullivan." 1846 ] 1847 } 1848 ], 1849 "links" : 1850 [ 1851 { 1852 "value" : "http://example.net/entity/xxxx", 1853 "rel" : "self", 1854 "href" : "http://example.net/entity/xxxx", 1855 "type" : "application/rdap+json" 1856 } 1857 ], 1858 "events" : 1860 [ 1861 { 1862 "eventAction" : "registration", 1863 "eventDate" : "1990-12-31T23:59:59Z" 1864 }, 1865 { 1866 "eventAction" : "last changed", 1867 "eventDate" : "1991-12-31T23:59:59Z" 1868 } 1869 ] 1870 } 1871 ] 1872 } 1874 Figure 26 1876 The IP network object class can contain the following members: 1878 o objectClassName -- the string "ip network" 1880 o handle -- a string representing an RIR unique identifier of the 1881 network registration 1883 o startAddress -- the starting IP address of the network, either 1884 IPv4 or IPv6 1886 o endAddress -- the ending IP address of the network, either IPv4 or 1887 IPv6 1889 o ipVersion -- a string signifying the IP protocol version of the 1890 network: "v4" signifying an IPv4 network, "v6" signifying an IPv6 1891 network 1893 o name -- an identifier assigned to the network registration by the 1894 registration holder 1896 o type -- a string containing an RIR-specific classification of the 1897 network 1899 o country -- a string containing the two-character country code of 1900 the network 1902 o parentHandle -- a string containing an RIR-unique identifier of 1903 the parent network of this network registration 1905 o status -- an array of strings indicating the state of the IP 1906 network 1908 o entities -- an array of entity objects as defined by Section 5.1. 1910 o remarks - see Section 4.3 1912 o links - see Section 4.2 1914 o port43 - see Section 4.7 1916 o events - see Section 4.5 1918 5.5. Autonomous System Number Entity Object Class 1920 The autonomous system number (autnum) object class models Autonomous 1921 System Number registrations found in RIRs and represents the expected 1922 response to an "/autnum" query as defined by 1923 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1924 for DNRs. The high level structure of the autnum object class 1925 consists of information about the network registration and entities 1926 related to the autnum registration (e.g. registrant information, 1927 contacts, etc.), and is similar to the IP Network entity object 1928 class. 1930 The following is an example of a JSON object representing an autnum. 1932 { 1933 "objectClassName" : "autnum", 1934 "handle" : "XXXX-RIR", 1935 "startAutnum" : 10, 1936 "endAutnum" : 15, 1937 "name": "AS-RTR-1", 1938 "type" : "DIRECT ALLOCATION", 1939 "status" : [ "active" ], 1940 "country": "AU", 1941 "remarks" : 1942 [ 1943 { 1944 "description" : 1945 [ 1946 "She sells sea shells down by the sea shore.", 1947 "Originally written by Terry Sullivan." 1948 ] 1949 } 1950 ], 1951 "links" : 1952 [ 1953 { 1954 "value" : "http://example.net/autnum/xxxx", 1955 "rel" : "self", 1956 "href" : "http://example.net/autnum/xxxx", 1957 "type" : "application/rdap+json" 1958 } 1959 ], 1960 "events" : 1961 [ 1962 { 1963 "eventAction" : "registration", 1964 "eventDate" : "1990-12-31T23:59:59Z" 1965 }, 1966 { 1967 "eventAction" : "last changed", 1968 "eventDate" : "1991-12-31T23:59:59Z" 1969 } 1970 ], 1971 "entities" : 1972 [ 1973 { 1974 "objectClassName" : "entity", 1975 "handle" : "XXXX", 1976 "vcardArray":[ 1977 "vcard", 1978 [ 1979 ["version", {}, "text", "4.0"], 1980 ["fn", {}, "text", "Joe User"], 1981 ["kind", {}, "text", "individual"], 1982 ["lang", { 1983 "pref":"1" 1984 }, "language-tag", "fr"], 1985 ["lang", { 1986 "pref":"2" 1987 }, "language-tag", "en"], 1988 ["org", { 1989 "type":"work" 1990 }, "text", "Example"], 1991 ["title", {}, "text", "Research Scientist"], 1992 ["role", {}, "text", "Project Lead"], 1993 ["adr", 1994 { "type":"work" }, 1995 "text", 1996 [ 1997 "", 1998 "Suite 1234", 1999 "4321 Rue Somewhere", 2000 "Quebec", 2001 "QC", 2002 "G1V 2M2", 2003 "Canada" 2004 ] 2005 ], 2006 ["tel", 2007 { "type":["work", "voice"], "pref":"1" }, 2008 "uri", "tel:+1-555-555-1234;ext=102" 2009 ], 2010 ["email", 2011 { "type":"work" }, 2012 "text", "joe.user@example.com" 2013 ] 2014 ] 2015 ], 2016 "roles" : [ "registrant" ], 2017 "remarks" : 2018 [ 2019 { 2020 "description" : 2021 [ 2022 "She sells sea shells down by the sea shore.", 2023 "Originally written by Terry Sullivan." 2024 ] 2025 } 2026 ], 2027 "links" : 2028 [ 2029 { 2030 "value" : "http://example.net/entity/XXXX", 2031 "rel" : "self", 2032 "href" : "http://example.net/entity/XXXX", 2033 "type" : "application/rdap+json" 2034 } 2035 ], 2036 "events" : 2037 [ 2038 { 2039 "eventAction" : "registration", 2040 "eventDate" : "1990-12-31T23:59:59Z" 2041 }, 2042 { 2043 "eventAction" : "last changed", 2044 "eventDate" : "1991-12-31T23:59:59Z" 2045 } 2046 ] 2047 } 2048 ] 2049 } 2050 Figure 27 2052 The autonomous system number object class can contain the following 2053 members: 2055 o objectClassName -- the string "autnum" 2057 o handle -- a string representing an RIR-unique identifier of the 2058 autnum registration 2060 o startAutnum -- a number representing the starting number [RFC5396] 2061 in the block of autonomous system numbers 2063 o endAutnum -- a number representing the ending number [RFC5396] in 2064 the block of autonomous system numbers 2066 o name -- an identifier assigned to the autnum registration by the 2067 registration holder 2069 o type -- a string containing an RIR-specific classification of the 2070 autnum 2072 o status -- an array of strings indicating the state of the autnum 2074 o country -- a string containing the name of the 2 character country 2075 code of the autnum 2077 o entities -- an array of entity objects as defined by Section 5.1. 2079 o remarks - see Section 4.3 2081 o links - see Section 4.2 2083 o port43 - see Section 4.7 2085 o events - see Section 4.5 2087 6. Error Response Body 2089 Some non-answer responses may return entity bodies with information 2090 that could be more descriptive. 2092 The basic structure of that response is an object class containing an 2093 error code number (corresponding to the HTTP response code) followed 2094 by a string named "title" and an array of strings named 2095 "description". 2097 This is an example of the common response body. 2099 { 2100 "errorCode": 418, 2101 "title": "Your beverage choice is not available", 2102 "description": 2103 [ 2104 "I know coffee has more ummppphhh.", 2105 "Sorry, dude!" 2106 ] 2107 } 2109 Figure 28 2111 This is an example of the common response body with and 2112 rdapConformance and notices data structures: 2114 { 2115 "rdapConformance" : 2116 [ 2117 "rdap_level_0" 2118 ], 2119 "notices" : 2120 [ 2121 { 2122 "title" : "Beverage policy", 2123 "description" : 2124 [ 2125 "Beverages with caffeine for keeping horses awake." 2126 ], 2127 "links" : 2128 [ 2129 { 2130 "value" : "http://example.net/ip/192.0.2.0/24", 2131 "rel" : "alternate", 2132 "type" : "text/html", 2133 "href" : "http://www.example.com/redaction_policy.html" 2134 } 2135 ] 2136 } 2137 ], 2138 "lang" : "en", 2139 "errorCode": 418, 2140 "title": "Your beverage choice is not available", 2141 "description": 2142 [ 2143 "I know coffee has more ummppphhh.", 2144 "Sorry, dude!" 2145 ] 2146 } 2148 Figure 29 2150 7. Responding to Help Queries 2152 The appropriate response to /help queries as defined by 2153 [I-D.ietf-weirds-rdap-query] is to use the notices structure as 2154 defined in Section 4.3. 2156 This is an example of a response to a /help query including the 2157 rdapConformance data structure. 2159 { 2160 "rdapConformance" : 2161 [ 2162 "rdap_level_0" 2163 ], 2164 "notices" : 2165 [ 2166 { 2167 "title" : "Authentication Policy", 2168 "description" : 2169 [ 2170 "Access to sensitive data for users with proper credentials." 2171 ], 2172 "links" : 2173 [ 2174 { 2175 "value" : "http://example.net/help", 2176 "rel" : "alternate", 2177 "type" : "text/html", 2178 "href" : "http://www.example.com/auth_policy.html" 2179 } 2180 ] 2181 } 2182 ] 2183 } 2185 Figure 30 2187 8. Responding To Searches 2189 [I-D.ietf-weirds-rdap-query] specifies three types of searches: 2190 domains, nameservers, and entities. Responses to these searches take 2191 the form of an array of object instances where each instance is an 2192 appropriate object class for the search (i.e. a search for /domains 2193 yields an array of domain object instances). These arrays are 2194 contained within the response object. 2196 The names of the arrays are as follows: 2198 o for /domains searches, the array is "domainSearchResults" 2200 o for /nameservers searches, the array is "nameserverSearchResults" 2202 o for /entities searches, the array is "entitySearchResults" 2203 The following is an elided example of a response to a /domains 2204 search. 2206 { 2207 "rdapConformance" : 2208 [ 2209 "rdap_level_0" 2210 ], 2211 ... 2212 "domainSearchResults" : 2213 [ 2214 { 2215 "objectClassName" : "domain", 2216 "handle" : "1-XXXX", 2217 "ldhName" : "1.example.com", 2218 ... 2219 }, 2220 { 2221 "objectClassName" : "domain", 2222 "handle" : "2-XXXX", 2223 "ldhName" : "2.example.com", 2224 ... 2225 } 2226 ] 2227 } 2229 search_response_example 2231 9. Indicating Truncated Responses 2233 In cases where the data of a response needs to be limited or parts of 2234 the data need to be omitted, the response is considered "truncated". 2235 A truncated response is still valid JSON, but some of the results in 2236 a search set or some of the data in an object are not provided by the 2237 server. A server may indicate this by including a typed notice in 2238 the response object. 2240 The following is an elided example of a search response that has been 2241 truncated. 2243 { 2244 "rdapConformance" : 2245 [ 2246 "rdap_level_0" 2247 ], 2248 "notices" : 2249 [ 2250 { 2251 "title" : "Search Policy", 2252 "type" : "result set truncated due to authorization", 2253 "description" : 2254 [ 2255 "Search results are limited to 25 per day per querying IP." 2256 ], 2257 "links" : 2258 [ 2259 { 2260 "value" : "http://example.net/help", 2261 "rel" : "alternate", 2262 "type" : "text/html", 2263 "href" : "http://www.example.com/search_policy.html" 2264 } 2265 ] 2266 } 2267 ], 2268 "domainSearchResults" : 2269 [ 2270 ... 2271 ] 2272 } 2274 search_response_truncated_example 2276 A similar technique can be used with a typed remark where a single 2277 object has been returned and data in that object has been truncated. 2278 Such an example might be an entity object with only a partial set of 2279 the IP networks associated with it. 2281 The following is an elided example of an entity truncated data. 2283 { 2284 "objectClassName" : "entity", 2285 "handle" : "ANENTITY", 2286 "roles" : [ "registrant" ], 2287 ... 2288 "entities" : 2289 [ 2290 { 2291 "objectClassName" : "entity", 2292 "handle": "ANEMBEDDEDENTITY", 2293 "roles" : [ "technical" ], 2294 ... 2295 }, 2296 ... 2297 ], 2298 "networks" : 2299 [ 2300 ... 2301 ], 2302 ... 2303 "remarks" : 2304 [ 2305 { 2306 "title" : "Data Policy", 2307 "type" : "object truncated due to unexplainable reason", 2308 "description" : 2309 [ 2310 "Some of the data in this object has been removed." 2311 ], 2312 "links" : 2313 [ 2314 { 2315 "value" : "http://example.net/help", 2316 "rel" : "alternate", 2317 "type" : "text/html", 2318 "href" : "http://www.example.com/data_policy.html" 2319 } 2320 ] 2321 } 2322 ] 2323 } 2325 Figure 31 2327 10. IANA Considerations 2329 10.1. RDAP JSON Media Type Registration 2331 This specification registers the "application/rdap+json" media type. 2333 Type name: application 2335 Subtype name: rdap+json 2337 Required parameters: n/a 2339 Encoding considerations: See section 3.1 of [RFC6839]. 2341 Security considerations: The media represented by this identifier 2342 does not have security considerations beyond that found in section 2343 6 of [RFC7159] 2345 Interoperability considerations: There are no known 2346 interoperability problems regarding this media format. 2348 Published specification: [[ this document ]] 2350 Applications that use this media type: Implementations of the 2351 Registration Data Access Protocol (RDAP) 2353 Additional information: This media type is a product of the IETF 2354 WEIRDS working group. The WEIRDS charter, information on the 2355 WEIRDS mailing list, and other documents produced by the WEIRDS 2356 working group can be found at https://datatracker.ietf.org/wg/ 2357 weirds/ 2359 Person & email address to contact for further information: IESG 2360 2362 Intended usage: COMMON 2364 Restrictions on usage: none 2366 Author: Andy Newton 2368 Change controller: IETF 2370 Provisional Registration: No (upon publication of this RFC) 2372 10.2. JSON Values Registry 2374 This section requests that the IANA create a new category in the 2375 protocol registries labeled "Registration Data Access Protocol 2376 (RDAP)" (if it does not already exist), and within that category 2377 establish a URL referenceable, stand-alone registry labeled "RDAP 2378 JSON Values". This new registry is for use in the notices and 2379 remarks (Section 4.3), status (Section 4.6), role (Section 5.1), 2380 event action (Section 4.5), and domain variant relation (Section 5.3) 2381 fields specified in RDAP. 2383 Each entry in the registry should contain the following fields: 2385 1. Value - the string value being registered. 2387 2. Type - the type of value being registered. It should be one of 2388 the following: 2390 * 'notice or remark type' - denotes a type of notice or remark 2392 * 'status' - denotes a value for the 'status' object member as 2393 defined by Section 4.6. 2395 * 'role' - denotes a value for the 'role' array as defined in 2396 Section 5.1. 2398 * 'event action' - denotes a value for an event action as 2399 defined in Section 4.5. 2401 * 'domain variant relation' - denotes a relationship between a 2402 domain and a domain variant as defined in Section 5.3. 2404 3. Description - a one or two sentence description regarding the 2405 meaning of the value, how it might be used, and/or how it should 2406 be interpreted by clients. 2408 4. Registrant Name - the name of the person registering the value. 2410 5. Registrant Contact Information - an email address, postal 2411 address, or some other information to be used to contact the 2412 registrant. 2414 This registry is to be operated under the "Expert Review" policy 2415 defined in [RFC5226]. 2417 Review of registrations into this registry by the designated 2418 expert(s) should be narrowly judged on the following criteria: 2420 1. Values in need of being placed into multiple types must be 2421 assigned a separate registration for each type. 2423 2. Values must be strings. They should be multiple words separated 2424 by single space characters. Every character should be 2425 lowercased. If possible, every word should be given in English 2426 and each character should be US ASCII. 2428 3. Registrations should not duplicate the meaning of any existing 2429 registration. That is, if a request for a registration is 2430 significantly similar in nature to an existing registration, the 2431 request should be denied. For example, the terms 'maintainer' 2432 and 'registrant' are significantly similar in nature as they both 2433 denote a holder of a domain name or Internet number resource. In 2434 cases where it may be reasonably argued that machine 2435 interpretation of two similar values may alter the operation of 2436 client software, designated experts should not judge the values 2437 to be of significant similarity. 2439 4. Registrations should be relevant to the common usages of RDAP. 2440 Designated experts may rely upon the serving of the value by a 2441 DNR or RIR to make this determination. 2443 The following sections provide initial registrations into this 2444 registry. 2446 10.2.1. Notice and Remark Types 2448 This section registers the following values into the RDAP JSON Values 2449 Registry: 2451 1. 2453 * Value: result set truncated due to authorization 2455 * Type: notice and remark type 2457 * Description: The list of results does not contain all results 2458 due to lack of authorization. This may indicate to some 2459 clients that proper authorization will yield a longer result 2460 set. 2462 * Registrant Name: IESG 2464 * Registrant Contact Information: iesg@ietf.org 2466 2. 2468 * Value: result set truncated due to excessive load 2470 * Type: notice and remark type 2472 * Description: The list of results does not contain all results 2473 due to excessively heavy load on the server. This may 2474 indicate to some clients that requerying at a later time will 2475 yield a longer result set. 2477 * Registrant Name: IESG 2479 * Registrant Contact Information: iesg@ietf.org 2481 3. 2483 * Value: result set truncated due to unexplainable reasons 2485 * Type: notice and remark type 2487 * Description: The list of results does not contain all results 2488 for an unexplainable reason. This may indicate to some 2489 clients that requerying for any reason will not yield a longer 2490 result set. 2492 * Registrant Name: IESG 2494 * Registrant Contact Information: iesg@ietf.org 2496 4. 2498 * Value: object truncated due to authorization 2500 * Type: notice and remark type 2502 * Description: The object does not contain all data due to lack 2503 of authorization. 2505 * Registrant Name: IESG 2507 * Registrant Contact Information: iesg@ietf.org 2509 5. 2511 * Value: object truncated due to excessive load 2513 * Type: notice and remark type 2514 * Description: The object does not contain all data due to 2515 excessively heavy load on the server. This may indicate to 2516 some clients that requerying at a later time will yield all 2517 data of the object. 2519 * Registrant Name: IESG 2521 * Registrant Contact Information: iesg@ietf.org 2523 6. 2525 * Value: object truncated due to unexplainable reasons 2527 * Type: notice and remark type 2529 * Description: The object does not contain all data for an 2530 unexplainable reason. 2532 * Registrant Name: IESG 2534 * Registrant Contact Information: iesg@ietf.org 2536 10.2.2. Status 2538 This section registers the following values into the RDAP JSON Values 2539 Registry: 2541 1. 2543 * Value: validated 2545 * Type: status 2547 * Description: Signifies that the data of the object instance 2548 has been found to be accurate. This type of status is 2549 usually found on entity object instances to note the validity 2550 of identifying contact information. 2552 * Registrant Name: IESG 2554 * Registrant Contact Information: iesg@ietf.org 2556 2. 2558 * Value: renew prohibited 2560 * Type: status 2561 * Description: Renewal or reregistration of the object instance 2562 is forbidden. 2564 * Registrant Name: IESG 2566 * Registrant Contact Information: iesg@ietf.org 2568 3. 2570 * Value: update prohibited 2572 * Type: status 2574 * Description: Updates to the object instance are forbidden. 2576 * Registrant Name: IESG 2578 * Registrant Contact Information: iesg@ietf.org 2580 4. 2582 * Value: transfer prohibited 2584 * Type: status 2586 * Description: Transfers of the registration from one registrar 2587 to another are forbidden. This type of status normally 2588 applies to DNR domain names. 2590 * Registrant Name: IESG 2592 * Registrant Contact Information: iesg@ietf.org 2594 5. 2596 * Value: delete prohibited 2598 * Type: status 2600 * Description: Deletion of the registration of the object 2601 instance is forbidden. This type of status normally applies 2602 to DNR domain names. 2604 * Registrant Name: IESG 2606 * Registrant Contact Information: iesg@ietf.org 2608 6. 2610 * Value: proxy 2612 * Type: status 2614 * Description: The registration of the object instance has been 2615 performed by a third party. This is most commonly applied to 2616 entities. 2618 * Registrant Name: IESG 2620 * Registrant Contact Information: iesg@ietf.org 2622 7. 2624 * Value: private 2626 * Type: status 2628 * Description: The information of the object instance is not 2629 designated for public consumption. This is most commonly 2630 applied to entities. 2632 * Registrant Name: IESG 2634 * Registrant Contact Information: iesg@ietf.org 2636 8. 2638 * Value: removed 2640 * Type: status 2642 * Description: Some of the information of the object instance 2643 has not been made available and has been removed. This is 2644 most commonly applied to entities. 2646 * Registrant Name: IESG 2648 * Registrant Contact Information: iesg@ietf.org 2650 9. 2652 * Value: obscured 2654 * Type: status 2656 * Description: Some of the information of the object instance 2657 has been altered for the purposes of not readily revealing 2658 the actual information of the object instance. This is most 2659 commonly applied to entities. 2661 * Registrant Name: IESG 2663 * Registrant Contact Information: iesg@ietf.org 2665 10. 2667 * Value: associated 2669 * Type: status 2671 * Description: The object instance is associated with other 2672 object instances in the registry. This is most commonly used 2673 to signify that a nameserver is associated with a domain or 2674 that an entity is associated with a network resource or 2675 domain. 2677 * Registrant Name: IESG 2679 * Registrant Contact Information: iesg@ietf.org 2681 11. 2683 * Value: active 2685 * Type: status 2687 * Description: The object instance is in use. For domain 2688 names, it signifies that the domain name is published in DNS. 2689 For network and autnum registrations it signifies that they 2690 are allocated or assigned for use in operational networks. 2691 This maps to the Extensible Provisioning Protocol (EPP) 2692 [RFC5730] 'OK' status. 2694 * Registrant Name: IESG 2696 * Registrant Contact Information: iesg@ietf.org 2698 12. 2700 * Value: inactive 2702 * Type: status 2704 * Description: The object instance is not in use. See 2705 'active'. 2707 * Registrant Name: IESG 2709 * Registrant Contact Information: iesg@ietf.org 2711 13. 2713 * Value: locked 2715 * Type: status 2717 * Description: Changes to the object instance cannot be made, 2718 including the association of other object instances. 2720 * Registrant Name: IESG 2722 * Registrant Contact Information: iesg@ietf.org 2724 14. 2726 * Value: pending create 2728 * Type: status 2730 * Description: A request has been received for the creation of 2731 the object instance but this action is not yet complete. 2733 * Registrant Name: IESG 2735 * Registrant Contact Information: iesg@ietf.org 2737 15. 2739 * Value: pending renew 2741 * Type: status 2743 * Description: A request has been received for the renewal of 2744 the object instance but this action is not yet complete. 2746 * Registrant Name: IESG 2748 * Registrant Contact Information: iesg@ietf.org 2750 16. 2752 * Value: pending transfer 2754 * Type: status 2755 * Description: A request has been received for the transfer of 2756 the object instance but this action is not yet complete. 2758 * Registrant Name: IESG 2760 * Registrant Contact Information: iesg@ietf.org 2762 17. 2764 * Value: pending update 2766 * Type: status 2768 * Description: A request has been received for the update or 2769 modification of the object instance but this action is not 2770 yet complete. 2772 * Registrant Name: IESG 2774 * Registrant Contact Information: iesg@ietf.org 2776 18. 2778 * Value: pending delete 2780 * Type: status 2782 * Description: A request has been received for the deletion or 2783 removal of the object instance but this action is not yet 2784 complete. For domains, this might mean that the name is no 2785 longer published in DNS but has not yet been purged from the 2786 registry database. 2788 * Registrant Name: IESG 2790 * Registrant Contact Information: iesg@ietf.org 2792 10.2.3. Event Actions 2794 This section registers the following values into the RDAP JSON Values 2795 Registry: 2797 1. 2799 * Value: registration 2801 * Type: event action 2802 * Description: The object instance was initially registered. 2804 * Registrant Name: IESG 2806 * Registrant Contact Information: iesg@ietf.org 2808 2. 2810 * Value: reregistration 2812 * Type: event action 2814 * Description: The object instance was registered subsequently 2815 to initial registration. 2817 * Registrant Name: IESG 2819 * Registrant Contact Information: iesg@ietf.org 2821 3. 2823 * Value: last changed 2825 * Type: event action 2827 * Description: An action noting when the information in the 2828 object instance was last changed. 2830 * Registrant Name: IESG 2832 * Registrant Contact Information: iesg@ietf.org 2834 4. 2836 * Value: expiration 2838 * Type: event action 2840 * Description: The object instance has been removed or will be 2841 removed at a pre-determined date and time from the registry. 2843 * Registrant Name: IESG 2845 * Registrant Contact Information: iesg@ietf.org 2847 5. 2849 * Value: deletion 2850 * Type: event action 2852 * Description: The object instance was removed from the registry 2853 at a point in time that was not pre-determined. 2855 * Registrant Name: IESG 2857 * Registrant Contact Information: iesg@ietf.org 2859 6. 2861 * Value: reinstantiation 2863 * Type: event action 2865 * Description: The object instance was reregistered after having 2866 been removed from the registry. 2868 * Registrant Name: IESG 2870 * Registrant Contact Information: iesg@ietf.org 2872 7. 2874 * Value: transfer 2876 * Type: event action 2878 * Description: The object instance was transferred from one 2879 registrant to another. 2881 * Registrant Name: IESG 2883 * Registrant Contact Information: iesg@ietf.org 2885 8. 2887 * Value: locked 2889 * Type: event action 2891 * Description: The object instance was locked (see the 'locked' 2892 status). 2894 * Registrant Name: IESG 2896 * Registrant Contact Information: iesg@ietf.org 2898 9. 2900 * Value: unlocked 2902 * Type: event action 2904 * Description: The object instance was unlocked (see the 2905 'locked' status). 2907 * Registrant Name: IESG 2909 * Registrant Contact Information: iesg@ietf.org 2911 10.2.4. Roles 2913 This section registers the following values into the RDAP JSON Values 2914 Registry: 2916 1. 2918 * Value: registrant 2920 * Type: role 2922 * Description: The entity object instance is the registrant of 2923 the registration. In some registries, this is known as a 2924 maintainer. 2926 * Registrant Name: IESG 2928 * Registrant Contact Information: iesg@ietf.org 2930 2. 2932 * Value: technical 2934 * Type: role 2936 * Description: The entity object instance is a technical 2937 contact for the registration. 2939 * Registrant Name: IESG 2941 * Registrant Contact Information: iesg@ietf.org 2943 3. 2945 * Value: administrative 2946 * Type: role 2948 * Description: The entity object instance is an administrative 2949 contact for the registration. 2951 * Registrant Name: IESG 2953 * Registrant Contact Information: iesg@ietf.org 2955 4. 2957 * Value: abuse 2959 * Type: role 2961 * Description: The entity object instance handles network abuse 2962 issues on behalf of the registrant of the registration. 2964 * Registrant Name: IESG 2966 * Registrant Contact Information: iesg@ietf.org 2968 5. 2970 * Value: billing 2972 * Type: role 2974 * Description: The entity object instance handles payment and 2975 billing issues on behalf of the registrant of the 2976 registration. 2978 * Registrant Name: IESG 2980 * Registrant Contact Information: iesg@ietf.org 2982 6. 2984 * Value: registrar 2986 * Type: role 2988 * Description: The entity object instance represents the 2989 authority responsible for the registration in the registry. 2991 * Registrant Name: IESG 2993 * Registrant Contact Information: iesg@ietf.org 2995 7. 2997 * Value: reseller 2999 * Type: role 3001 * Description: The entity object instance represents a third 3002 party through which the registration was conducted (i.e. not 3003 the registry or registrar). 3005 * Registrant Name: IESG 3007 * Registrant Contact Information: iesg@ietf.org 3009 8. 3011 * Value: sponsor 3013 * Type: role 3015 * Description: The entity object instance represents a domain 3016 policy sponsor, such as an ICANN approved sponsor. 3018 * Registrant Name: IESG 3020 * Registrant Contact Information: iesg@ietf.org 3022 9. 3024 * Value: proxy 3026 * Type: role 3028 * Description: The entity object instance represents a proxy 3029 for another entity object, such as a registrant. 3031 * Registrant Name: IESG 3033 * Registrant Contact Information: iesg@ietf.org 3035 10. 3037 * Value: notifications 3039 * Type: role 3041 * Description: An entity object instance designated to receive 3042 notifications about association object instances. 3044 * Registrant Name: IESG 3046 * Registrant Contact Information: iesg@ietf.org 3048 11. 3050 * Value: noc 3052 * Type: role 3054 * Description: The entity object instance handles 3055 communications related to a network operations center (NOC). 3057 * Registrant Name: IESG 3059 * Registrant Contact Information: iesg@ietf.org 3061 10.2.5. Variant Relations 3063 This section registers the following values into the RDAP JSON Values 3064 Registry: 3066 1. 3068 * Value: registered 3070 * Type: domain variant relation 3072 * Description: The variant names are registered in the registry. 3074 * Registrant Name: IESG 3076 * Registrant Contact Information: iesg@ietf.org 3078 2. 3080 * Value: unregistered 3082 * Type: domain variant relation 3084 * Description: The variant names are not found in the registry. 3086 * Registrant Name: IESG 3088 * Registrant Contact Information: iesg@ietf.org 3090 3. 3092 * Value: registration restricted 3094 * Type: domain variant relation 3096 * Description: Registration of the variant names is restricted 3097 to certain parties or within certain rules. 3099 * Registrant Name: IESG 3101 * Registrant Contact Information: iesg@ietf.org 3103 4. 3105 * Value: open registration 3107 * Type: domain variant relation 3109 * Description: Registration of the variant names is available to 3110 generally qualified registrants. 3112 * Registrant Name: IESG 3114 * Registrant Contact Information: iesg@ietf.org 3116 5. 3118 * Value: conjoined 3120 * Type: domain variant relation 3122 * Description: Registration of the variant names occurs 3123 automatically with the registration of the containing domain 3124 registration. 3126 * Registrant Name: IESG 3128 * Registrant Contact Information: iesg@ietf.org 3130 11. Security Considerations 3132 This specification models information serialized in JSON format. As 3133 JSON is a subset of Javascript, implementations are advised to follow 3134 the security considerations outlined in Section 6 of [RFC7159] to 3135 prevent code injection. 3137 Though not specific to JSON, RDAP implementers should be aware of the 3138 security considerations specified in [I-D.ietf-weirds-using-http] and 3139 the security requirements and considerations in 3140 [I-D.ietf-weirds-rdap-sec]. 3142 Clients caching data, especially clients using RDAP specific caches 3143 (instead of HTTP layer caches), should have safeguards to prevent 3144 cache poisoning. See Section 5 for advice on using the "self" links 3145 for caching. 3147 Finally, service operators should be aware of the privacy mechanisms 3148 noted in Section 13. 3150 12. Internationalization Considerations 3152 12.1. Character Encoding 3154 The default text encoding for JSON responses in RDAP is UTF-8 3155 [RFC3629], and all servers and clients MUST support UTF-8. 3157 12.2. URIs and IRIs 3159 [I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in 3160 RDAP. 3162 12.3. Language Tags 3164 Section 4.4 defines the use of language tags in the JSON responses 3165 defined in this document. 3167 12.4. Internationalized Domain Names 3169 Internationalized Domain Names (IDNs) are denoted in this 3170 specification by the separation of DNS names in LDH form and Unicode 3171 form (see Section 3). Representation of IDNs in registries is 3172 described by the "variants" object in Section 5.3 and the suggested 3173 values listed in Section 10.2.5. 3175 13. Privacy Considerations 3177 This specification suggests status values to denote contact and 3178 registrant information that has been marked as private and/or has 3179 been removed or obscured. See Section 10.2.2 for the complete list 3180 of status values. A few of the status values indicate that there are 3181 privacy concerns associated with the object instance. The following 3182 status codes SHOULD be used to describe data elements of a response 3183 when appropriate: 3185 private - The object is not be shared in query responses, unless 3186 the user is authorized to view this information. 3188 removed - Data elements within the object have been collected, but 3189 have been omitted from the response. This option can be used to 3190 prevent unauthorized access to associated object instances without 3191 the need to mark them as private. 3193 obscured - Data elements within the object have been collected, 3194 but the response value has been altered so that values are not 3195 easily discernible. A value changed from "1212" to "XXXX" is an 3196 example of obscured data. This option may reveal privacy 3197 sensitive information and should only be used when data 3198 sensitivity does not require a more protective option like 3199 "private" or "removed". 3201 See Appendix A.1 for an example applying those values to contacts and 3202 registrants. 3204 14. Contributing Authors and Acknowledgements 3206 This document is derived from original work on RIR responses in JSON 3207 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew 3208 L. Newton. Additionally, this document incorporates work on DNR 3209 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 3210 Shen. 3212 The components of the DNR object classes are derived from a 3213 categorization of WHOIS response formats created by Ning Kong, Linlin 3214 Zhou, and Guangqing Deng, Steve Sheng and Francisco Arias, Ray 3215 Bellis, and Frederico Neves. 3217 Tom Harrison, Murray Kucherawy, Ed Lewis, Audric Schiltknecht, Naoki 3218 Kambe, and Maarten Bosteels contributed significant review comments 3219 and provided clarifying text. James Mitchell provided text regarding 3220 the processing of unknown JSON attributes and identified issues 3221 leading to the remodeling of events. Ernie Dainow and Francisco 3222 Obispo provided concrete suggestions that led to a better variant 3223 model for domain names. 3225 Ernie Dainow provided the background information on the secure DNS 3226 attributes and objects for domains, informative text on DNSSEC, and 3227 many other attributes that appear throughout the object classes of 3228 this draft. 3230 The switch to and incorporation of jCard (JSON vCard) was performed 3231 by Simon Perreault. 3233 Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working 3234 group from which this document as been created. 3236 15. References 3238 15.1. Normative References 3240 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3241 Requirement Levels", BCP 14, RFC 2119, March 1997. 3243 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 3244 Internet: Timestamps", RFC 3339, July 2002. 3246 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3247 10646", STD 63, RFC 3629, November 2003. 3249 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3250 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3251 3986, January 2005. 3253 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 3254 Rose, "Resource Records for the DNS Security Extensions", 3255 RFC 4034, March 2005. 3257 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3258 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3259 May 2008. 3261 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 3262 Autonomous System (AS) Numbers", RFC 5396, December 2008. 3264 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 3265 Languages", BCP 47, RFC 5646, September 2009. 3267 [RFC5890] Klensin, J., "Internationalized Domain Names for 3268 Applications (IDNA): Definitions and Document Framework", 3269 RFC 5890, August 2010. 3271 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3272 Address Text Representation", RFC 5952, August 2010. 3274 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3276 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 3277 January 2014. 3279 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3280 Interchange Format", RFC 7159, March 2014. 3282 [I-D.ietf-weirds-using-http] 3283 Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the 3284 Registration Data Access Protocol (RDAP)", draft-ietf- 3285 weirds-using-http-15 (work in progress), November 2014. 3287 [I-D.ietf-weirds-rdap-query] 3288 Newton, A. and S. Hollenbeck, "Registration Data Access 3289 Protocol Query Format", draft-ietf-weirds-rdap-query-16 3290 (work in progress), October 2014. 3292 [I-D.ietf-weirds-rdap-sec] 3293 Hollenbeck, S. and N. Kong, "Security Services for the 3294 Registration Data Access Protocol", draft-ietf-weirds- 3295 rdap-sec-11 (work in progress), November 2014. 3297 [ISO.3166.1988] 3298 International Organization for Standardization, "Codes for 3299 the representation of names of countries, 3rd edition", 3300 ISO Standard 3166, August 1988. 3302 15.2. Informative References 3304 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 3305 September 2004. 3307 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 3308 STD 69, RFC 5730, August 2009. 3310 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 3311 Security Extensions Mapping for the Extensible 3312 Provisioning Protocol (EPP)", RFC 5910, May 2010. 3314 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 3315 August 2011. 3317 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 3318 Structured Syntax Suffixes", RFC 6839, January 2013. 3320 [JSON_acendancy] 3321 MacVittie, , "The Stealthy Ascendancy of JSON", 04 2011. 3323 [IANA_IDNTABLES] 3324 "IANA IDN Tables", 3325 . 3327 [JSON_performance_study] 3328 Montana State University - Bozeman, Montana State 3329 University - Bozeman, Montana State University - Bozeman, 3330 and Montana State University - Bozeman, "Comparison of 3331 JSON and XML Data Interchange Formats: A Case Study", 3332 2009. 3334 Appendix A. Suggested Data Modeling with the Entity Object Class 3336 A.1. Registrants and Contacts 3338 This document does not provide specific object classes for 3339 registrants and contacts. Instead the entity object class may be 3340 used to represent a registrant or contact. When the entity object is 3341 embedded inside a containing object such as a domain name or IP 3342 network, the 'roles' string array can be used to signify the 3343 relationship. It is recommended that the values from Section 10.2.4 3344 be used. 3346 The following is an example of an elided containing object with an 3347 embedded entity that is both a registrant and administrative contact: 3349 { 3350 ... 3351 "entities" : 3352 [ 3353 { 3354 "objectClassName" : "entity", 3355 "handle" : "XXXX", 3356 "vcardArray":[ 3357 "vcard", 3358 [ 3359 ["version", {}, "text", "4.0"], 3360 ["fn", {}, "text", "Joe User"], 3361 ["kind", {}, "text", "individual"], 3362 ["lang", { 3363 "pref":"1" 3364 }, "language-tag", "fr"], 3365 ["lang", { 3366 "pref":"2" 3367 }, "language-tag", "en"], 3368 ["org", { 3369 "type":"work" 3370 }, "text", "Example"], 3371 ["title", {}, "text", "Research Scientist"], 3372 ["role", {}, "text", "Project Lead"], 3373 ["adr", 3374 { "type":"work" }, 3375 "text", 3376 [ 3377 "", 3378 "Suite 1234", 3379 "4321 Rue Somewhere", 3380 "Quebec", 3381 "QC", 3382 "G1V 2M2", 3383 "Canada" 3384 ] 3385 ], 3386 ["tel", 3387 { "type":["work", "voice"], "pref":"1" }, 3388 "uri", "tel:+1-555-555-1234;ext=102" 3389 ], 3390 ["email", 3391 { "type":"work" }, 3392 "text", "joe.user@example.com" 3393 ] 3394 ] 3395 ], 3396 "roles" : [ "registrant", "administrative" ], 3397 "remarks" : 3398 [ 3399 { 3400 "description" : 3401 [ 3402 "She sells sea shells down by the sea shore.", 3403 "Originally written by Terry Sullivan." 3404 ] 3405 } 3406 ], 3407 "events" : 3408 [ 3409 { 3410 "eventAction" : "registration", 3411 "eventDate" : "1990-12-31T23:59:59Z" 3412 }, 3413 { 3414 "eventAction" : "last changed", 3415 "eventDate" : "1991-12-31T23:59:59Z" 3416 } 3417 ] 3418 } 3419 ] 3420 } 3421 Figure 32 3423 In many use cases, it is necessary to hide or obscure the information 3424 of a registrant or contact due to policy or other operational 3425 matters. Registries can denote these situations with 'status' values 3426 (see Section 10.2.2). 3428 The following is an elided example of a registrant with information 3429 changed to reflect that of a third party. 3431 { 3432 ... 3433 "entities" : 3434 [ 3435 { 3436 "objectClassName" : "entity", 3437 "handle" : "XXXX", 3438 ... 3439 "roles" : [ "registrant", "administrative" ], 3440 "status" : [ "proxy", "private", "obscured" ] 3441 } 3442 ] 3443 } 3445 Figure 33 3447 A.2. Registrars 3449 This document does not provide a specific object class for 3450 registrars, but like registrants and contacts (see Appendix A.1) the 3451 'roles' string array maybe used. Additionally, many registrars have 3452 publicly assigned identifiers. The 'publicIds' structure 3453 (Section 4.8) represents that information. 3455 The following is an example of an elided containing object with an 3456 embedded entity that is a registrar: 3458 { 3459 ... 3460 "entities":[ 3461 { 3462 "objectClassName" : "entity", 3463 "handle":"XXXX", 3464 "vcardArray":[ 3465 "vcard", 3467 [ 3468 ["version", {}, "text", "4.0"], 3469 ["fn", {}, "text", "Joe's Fish, Chips and Domains"], 3470 ["kind", {}, "text", "org"], 3471 ["lang", { 3472 "pref":"1" 3473 }, "language-tag", "fr"], 3474 ["lang", { 3475 "pref":"2" 3476 }, "language-tag", "en"], 3477 ["org", { 3478 "type":"work" 3479 }, "text", "Example"], 3480 ["adr", 3481 { "type":"work" }, 3482 "text", 3483 [ 3484 "", 3485 "Suite 1234", 3486 "4321 Rue Somewhere", 3487 "Quebec", 3488 "QC", 3489 "G1V 2M2", 3490 "Canada" 3491 ] 3492 ], 3493 ["tel", 3494 { 3495 "type":["work", "voice"], 3496 "pref":"1" 3497 }, 3498 "uri", "tel:+1-555-555-1234;ext=102" 3499 ], 3500 ["email", 3501 { "type":"work" }, 3502 "text", "joes_fish_chips_and_domains@example.com" 3503 ] 3504 ] 3505 ], 3506 "roles":[ "registrar" ], 3507 "publicIds":[ 3508 { 3509 "type":"IANA Registrar ID", 3510 "identifier":"1" 3511 } 3512 ], 3513 "remarks":[ 3514 { 3515 "description":[ 3516 "She sells sea shells down by the sea shore.", 3517 "Originally written by Terry Sullivan." 3518 ] 3519 } 3520 ], 3521 "links":[ 3522 { 3523 "value":"http://example.net/entity/XXXX", 3524 "rel":"alternate", 3525 "type":"text/html", 3526 "href":"http://www.example.com" 3527 } 3528 ] 3529 } 3530 ] 3531 } 3533 Figure 34 3535 Appendix B. Modeling Events 3537 Events represent actions that have taken place against a registered 3538 object at a certain date and time. Events have three properties: the 3539 action, the actor, and the date and time of the event (which is 3540 sometimes in the future). In some cases the identity of the actor is 3541 not captured. 3543 Events can be modeled in three ways: 3545 1. events with no designated actor 3547 2. events where the actor is only designated by an identifier 3549 3. events where the actor can be modeled as an entity 3551 For the first use case, the 'events' data structure (Section 4.5) is 3552 used without the 'eventActor' object member. 3554 This is an example of an "events" array without the 'eventActor'. 3556 "events" : 3557 [ 3558 { 3559 "eventAction" : "registration", 3560 "eventDate" : "1990-12-31T23:59:59Z" 3561 } 3562 ] 3564 Figure 35 3566 For the second use case, the 'events' data structure (Section 4.5) is 3567 used with the 'eventActor' object member. 3569 This is an example of an "events" array with the 'eventActor'. 3571 "events" : 3572 [ 3573 { 3574 "eventAction" : "registration", 3575 "eventActor" : "XYZ-NIC", 3576 "eventDate" : "1990-12-31T23:59:59Z" 3577 } 3578 ] 3580 Figure 36 3582 For the third use case, the 'asEventActor' array is used when an 3583 entity (Section 5.1) is embedded into another object class. The 3584 'asEventActor' array follows the same structure as the 'events' array 3585 but does not have 'eventActor' attributes. 3587 The following is an elided example of a domain object with an entity 3588 as an event actor. 3590 { 3591 "objectClassName" : "domain", 3592 "handle" : "XXXX", 3593 "ldhName" : "foo.example", 3594 "status" : [ "locked", "transfer Prohibited" ], 3595 ... 3596 "entities" : 3597 [ 3598 { 3599 "handle" : "XXXX", 3600 ... 3601 "asEventActor" : 3602 [ 3603 { 3604 "eventAction" : "last changed", 3605 "eventDate" : "1990-12-31T23:59:59Z" 3606 } 3607 ] 3608 } 3609 ] 3610 } 3612 Figure 37 3614 Appendix C. Structured vs Unstructured Addresses 3616 The entity (Section 5.1) object class uses jCard [RFC7095] to 3617 represent contact information, including postal addresses. jCard has 3618 the ability to represent multiple language preferences, multiple 3619 email address and phone numbers, and multiple postal addresses in 3620 both a structured and unstructured format. This section describes 3621 the use of jCard for representing structured and unstructured 3622 addresses. 3624 The following is an example of a jCard. 3626 { 3627 "vcardArray":[ 3628 "vcard", 3629 [ 3630 ["version", {}, "text", "4.0"], 3631 ["fn", {}, "text", "Joe User"], 3633 ["n", {}, "text", 3634 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 3635 ], 3636 ["kind", {}, "text", "individual"], 3637 ["lang", { 3638 "pref":"1" 3639 }, "language-tag", "fr"], 3640 ["lang", { 3641 "pref":"2" 3642 }, "language-tag", "en"], 3643 ["org", { 3644 "type":"work" 3645 }, "text", "Example"], 3646 ["title", {}, "text", "Research Scientist"], 3647 ["role", {}, "text", "Project Lead"], 3648 ["adr", 3649 { "type":"work" }, 3650 "text", 3651 [ 3652 "", 3653 "Suite 1234", 3654 "4321 Rue Somewhere", 3655 "Quebec", 3656 "QC", 3657 "G1V 2M2", 3658 "Canada" 3659 ] 3660 ], 3661 ["adr", 3662 { 3663 "type":"home", 3664 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 3665 }, 3666 "text", 3667 [ 3668 "", "", "", "", "", "", "" 3669 ] 3670 ], 3671 ["tel", 3672 { "type":["work", "voice"], "pref":"1" }, 3673 "uri", "tel:+1-555-555-1234;ext=102" 3674 ], 3675 ["tel", 3676 { 3677 "type":["work", "cell", "voice", "video", "text"] 3678 }, 3679 "uri", 3680 "tel:+1-555-555-1234" 3682 ], 3683 ["email", 3684 { "type":"work" }, 3685 "text", "joe.user@example.com" 3686 ], 3687 ["geo", { 3688 "type":"work" 3689 }, "uri", "geo:46.772673,-71.282945"], 3690 ["key", 3691 { "type":"work" }, 3692 "uri", "http://www.example.com/joe.user/joe.asc" 3693 ], 3694 ["tz", {}, 3695 "utc-offset", "-05:00"], 3696 ["url", { "type":"home" }, 3697 "uri", "http://example.org"] 3698 ] 3699 ] 3700 } 3702 Figure 38 3704 The arrays in Figure 38 with the first member of "adr" represent 3705 postal addresses. In the first example, the postal address is given 3706 as a an array of strings and constitutes a structured address. For 3707 components of the structured address that are not applicable, an 3708 empty string is given. Each member of that array aligns with the 3709 positions of a vCard as given in [RFC6350]. In this example, the 3710 following data corresponds to the following positional meanings: 3712 1. post office box - not applicable, empty string 3714 2. extended address (e.g., apartment or suite number) - Suite 1234 3716 3. street address - 4321 Rue Somewhere 3718 4. locality (e.g., city) - Quebec 3720 5. region (e.g., state or province) - QC 3722 6. postal code - G1V 2M2 3724 7. country name (full name) - Canada 3726 The second example is an unstructured address. It uses the label 3727 attribute, which is a string containing a newline (\n) character to 3728 separate address components in an unordered, unspecified manner. 3730 Note that in this example the structured address array is still given 3731 but that each string is an empty string. 3733 Appendix D. Secure DNS 3735 Section 5.3 defines the "secureDNS" member to represent secure DNS 3736 information about domain names. 3738 DNSSEC provides data integrity for DNS through digital signing of 3739 resource records. To enable DNSSEC, the zone is signed by one or 3740 more private keys and the signatures stored as RRSIG records. To 3741 complete the chain of trust in the DNS zone hierarchy, a digest of 3742 each DNSKEY record (which contains the public key) must be loaded 3743 into the parent zone, stored as Delegation Signer (DS) records and 3744 signed by the parent's private key (RRSIG DS record), "Resource 3745 Records for the DNS Security Extensions" [RFC4034]. Creating the DS 3746 records in the parent zone can be done by the registration authority, 3747 "Domain Name System (DNS) Security Extensions Mapping for the 3748 Extensible Provisioning Protocol (EPP)" [RFC5910]. 3750 Only DS related information is provided by RDAP, since other 3751 information is not generally stored in the registration database. 3752 Other DNSSEC related information can be retrieved with other DNS 3753 tools such as dig. 3755 The domain object class (Section 5.3) can represent this information 3756 using either the 'dsData' or 'keyData' object arrays. Client 3757 implementers should be aware that some registries do not collect or 3758 do not publish all of the secure DNS meta-information. 3760 Appendix E. Motivations for Using JSON 3762 This section addresses a common question regarding the use of JSON 3763 over other data formats, most notably XML. 3765 It is often pointed out that many DNRs and one RIR support the EPP 3766 [RFC5730] standard, which is an XML serialized protocol. The logic 3767 is that since EPP is a common protocol in the industry it follows 3768 that XML would be a more natural choice. While EPP does influence 3769 this specification quite a bit, EPP serves a different purpose which 3770 is the provisioning of Internet resources between registries and 3771 accredited registrars and serves a much narrower audience than that 3772 envisioned for RDAP. 3774 By contrast, RDAP has a broader audience and is designed for public 3775 consumption of data. Experience from RIRs with first generation 3776 RESTful web services for WHOIS indicate a large percentage of clients 3777 operate within browsers and other platforms where full-blown XML 3778 stacks are not readily available and where JSON is a better fit. 3780 Additionally, while EPP is used in much of the DNR community it is 3781 not a universal constant in that industry. And finally, EPP's use of 3782 XML predates the specification of JSON. If EPP had been defined 3783 today, it may very well have used JSON instead of XML. 3785 Beyond the specific DNR and RIR communities, the trend in the broader 3786 Internet industry is also switching to JSON over XML, especially in 3787 the area of RESTful web services (see [JSON_acendancy]). Studies 3788 have also found that JSON is generally less bulky and consequently 3789 faster to parse (see [JSON_performance_study]). 3791 Appendix F. Changelog 3793 [RFC Editor: Please delete this section prior to publication.] 3795 Initial -00 Adopted as working group document 2012-September-18. 3797 -01 3799 Minor spelling corrections. Changed "Registry Data" to 3800 "Registration Data" for the sake of consistency. 3802 Transitioned to RFC 5988 links and relationship types from our 3803 own custom "uris" structure. 3805 Some examples had 'status' as a string. Those have been 3806 corrected as 'status' is always an array of strings. 3808 Domain variants can now have a multi-valued relationship with 3809 domain registrations. 3811 "names" in the entity object class was changed to 3812 "entityNames". 3814 Some IP address examples change to IPv6. 3816 Change phone number examples and added reference to E.164. 3818 Added section on motivations for using JSON. 3820 Added error response body section. 3822 Added JSON naming section. 3824 Added common data structures section. 3826 Added the IANA Considerations section and the media type 3827 registration. 3829 Added 'lang' name/value. 3831 Added internationalization considerations section. 3833 -02 3835 Removed level from media type registration. 3837 Textual changes as given by Ed Lewis. 3839 Fixed object class linking example noted by Francisco Obispo 3841 Fixed a lot of other examples called out by Alex Sergeyev 3843 Added a note that JSON names are case sensitive 3845 Added 'status' to IP networks as suggested by Alex Sergeyev 3847 -03 3849 Added jCard verbiage and examples and deleted overlapping 3850 contact information and the appendix on postal addresses 3852 Removed the IANA considerations as they have been moved to 3853 another document 3855 Changed the remarks structure to be like notices 3857 Reordering and rewording some of the sections so they flow 3858 better 3860 Added note about object class "self" links 3862 Changed ipAddresses in nameserver object class to separate out 3863 v6 from v4 3865 Changed IP network version identifier from integer to string to 3866 be more consistent with ipAddresses identifier in nameserver 3867 object classes 3869 Changed DNS names to LDH names and Unicode names 3871 Modified the definition of 'conjoined' variant relationship so 3872 it was circular 3873 Added 'proxy', 'private', 'redacted', and 'obscured' status 3874 values (most useful for entities). 3876 Added a privacy considerations section 3878 Added a security considerations section 3880 Added 'reseller' and 'sponsor' to the list of entity roles 3882 Added the 'events' common data structure 3884 Added 'asEventActor' to entities 3886 Added appendix on event modeling 3888 Removed the subclasses/superclassing between RIRs/DNRs for 3889 entity and domain object classes 3891 Change suggested status/relation/etc values to be case/spacing 3892 consistent 3894 Normalized some of the definitions of object class members 3896 Modifying the JSON signaling section to reference the guidance 3897 in draft-ietf-weirds-using-http 3899 Changed the text regarding the process of unknown JSON 3900 attributes 3902 -04 3904 'description' removed from IP network and autnum because it is 3905 redundant with the remarks structure. 3907 Added 'entities' array to nameservers. 3909 Added 'status' to autnum. 3911 Added 'publicIds' to entity and domain. 3913 Added embedded entities to the entity object class. 3915 Added 'idnTable' to variants objects in domain object class. 3917 Changed the numbers for startNum and endNum in autnum to 3918 numbers instead of strings. 3920 Added an example for error response with full rdapConformance 3921 and notices. 3923 Added a section discussing help. 3925 Changed entities to use vcardArray and changed the examples to 3926 be current with jCard. 3928 Added a section on structured vs unstructured addresses. 3930 Added associated to the list of status values. 3932 Added a secure DNS section changed the 'delegationKey' object 3933 into the 'secureDNS' object. 3935 Changed the suggested values to an IANA registry. 3937 Added 'proxy' to the list of entity roles. 3939 -05 3941 Added IANA registration for RDAP JSON Media Type 3943 Added 'associated' status type. This was done earlier but got 3944 dropped during a reorganization of the document. 3946 Added the following status types: 3948 active 3950 inactive 3952 locked 3954 pending create 3956 pending renew 3958 pending update 3960 pending transfer 3962 pending delete 3964 renew prohibited 3966 Added the following event actions: 3968 locked 3970 unlocked 3972 Added the following roles: 3974 notifications 3976 noc 3978 Changed the 'tech' role to 'technical' 3980 Many document reference changes. 3982 Many examples have been fixed. 3984 Added links to dsData and keyData. 3986 Changed flags and protocols to integers in keyData. 3988 Added 'entities' to the specified list for autnum. 3990 Added SHOULD/SHOULD NOT language about using "type": 3991 "application/rdap+json" for self links. 3993 Added 'port43' to ip networks and autnum. 3995 -06 3997 Fix search response example. 3999 Change the returned search arrays to 'domainSearchResults', 4000 'entitySearchResults', and 'nameserverSearchResults'. 4002 -07 4004 'nameservers' in domain object class was changed to 4005 'nameServers' as in the example (note the camel case) 4007 fixed some example per email from James Mitchell 4009 fixed an example per email from Simon Perreault 4011 Added "network" to domain object class. 4013 Added networks and autnums to the entity object class. 4015 Created a section for "resultsTruncated". 4017 -08 4019 Added typed remarks and notices, removed "resultTruncated" in 4020 favor of them. 4022 Added "objectClassName". 4024 Changed JSON reference to RFC 7159. 4026 Removed unused references to RFC 0791, RFC 2616, RFC 4343, RFC 4027 5322. 4029 -09 4031 Fixed numerous examples. 4033 Reference to jCard updated. 4035 Text regarding JSON vCards has been changed to jCards. 4037 JSON naming rules do not apply to jCards. 4039 "nameserver" was made consistently all lower case. 4041 Links contained a "title" array, but it is now just a string 4042 per RFC 5988. 4044 Removed the term RESTful from the first section so it wouldn't 4045 have to be expanded. 4047 Added reference to RFC 2119 and noted that the uppercase form 4048 is what this document uses. 4050 Added text explaining why SHOULDs and SHOULD NOTs are to be 4051 followed. 4053 "port43" can now be either an domain name or IP address. 4055 "objectClassName" is now required. 4057 Numerous changes in prose for better readability. 4059 Updated the security considerations section to point to using- 4060 http and rdap-sec. 4062 -10 4064 Addressing many AD comments. 4066 Changed IANA registrations to IESG. 4068 'href' is now the only MUST in the a link. 4070 -11 4072 Changes to address IETF Last Call comments. 4074 -12 4076 Changes to address IESG comments. 4078 -13 4080 Changes to address Alyssa's DISCUSS. 4082 'redacted' status changed to 'removed' 4084 -14 4086 Text changes regarding can contain vs has members of for object 4087 classes. 4089 Authors' Addresses 4091 Andrew Lee Newton 4092 American Registry for Internet Numbers 4093 3635 Concorde Parkway 4094 Chantilly, VA 20151 4095 US 4097 Email: andy@arin.net 4098 URI: http://www.arin.net 4100 Scott Hollenbeck 4101 Verisign Labs 4102 12061 Bluemont Way 4103 Reston, VA 20190 4104 US 4106 Email: shollenbeck@verisign.com 4107 URI: http://www.verisignlabs.com/