idnits 2.17.1 draft-ietf-weirds-json-response-11.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 (October 27, 2014) is 3469 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) == Outdated reference: A later version (-15) exists of draft-ietf-weirds-using-http-13 -- 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-15 == Outdated reference: A later version (-12) exists of draft-ietf-weirds-rdap-sec-09 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-rdap-sec' Summary: 3 errors (**), 0 flaws (~~), 5 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: April 30, 2015 Verisign Labs 6 October 27, 2014 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-weirds-json-response-11 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 April 30, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 72 97 15.1. Normative References . . . . . . . . . . . . . . . . . . 72 98 15.2. Informative References . . . . . . . . . . . . . . . . . 74 99 Appendix A. Suggested Data Modeling with the Entity Object Class 74 100 A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 74 101 A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 77 102 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 79 103 Appendix C. Structured vs Unstructured Addresses . . . . . . . . 81 104 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 83 105 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 84 106 Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . 84 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90 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 4.3. Notices And Remarks 431 The "notices" and "remarks" data structures take the same form. The 432 "notices" structure denotes information about the service providing 433 RDAP information and/or information about the entire response, 434 whereas the "remarks" structure denotes information about the object 435 class that contains it (see Section 5 regarding object classes). 437 Both are arrays of objects. Each object contains an optional "title" 438 string representing the title of the object, an optional "type" 439 string denoting a registered type of remark or notice (see 440 Section 10.2.1), an array of strings named "description" for the 441 purposes of conveying any descriptive text, and an optional "links" 442 array as described in Section 4.2. 444 An example of the notices data structure: 446 "notices" : 447 [ 448 { 449 "title" : "Terms of Use", 450 "description" : 451 [ 452 "Service subject to The Registry of the Moon's TOS.", 453 "Copyright (c) 2020 LunarNIC" 454 ], 455 "links" : 456 [ 457 { 458 "value" : "http://example.net/entity/XXXX", 459 "rel" : "alternate", 460 "type" : "text/html", 461 "href" : "http://www.example.com/terms_of_use.html" 462 } 463 ] 464 } 465 ] 467 Figure 6 469 It is the job of the clients to determine line breaks, spacing and 470 display issues for sentences within the character strings of the 471 "description" array. Each string in the "description" array contains 472 a single complete division of human readable text indicating to 473 clients where there are semantic breaks. 475 An example of the remarks data structure: 477 "remarks" : 478 [ 479 { 480 "description" : 481 [ 482 "She sells sea shells down by the sea shore.", 483 "Originally written by Terry Sullivan." 484 ] 485 } 486 ] 488 Figure 7 490 Note that objects in the "remarks" array may also have a "links" 491 array. 493 While the "title" and "description" fields are intended primarily for 494 human consumption, the "type" string contains a well-known value to 495 be registered with IANA (see Section 10.2.1) for programmatic use. 497 An example of the remarks data structure: 499 "remarks" : 500 [ 501 { 502 "type" : "object truncated due to authorization", 503 "description" : 504 [ 505 "Some registration data may not have been given.", 506 "Use proper authorization credentials to see all of it." 507 ] 508 } 509 ] 511 Figure 8 513 While the "remarks" array will appear in many object classes in a 514 response, the "notices" array appears only in the top most object of 515 a response. 517 4.4. Language Identifier 519 This data structure consists solely of a name/value pair, where the 520 name is "lang" and the value is a string containing a language 521 identifier as described in [RFC5646]. 523 "lang" : "mn-Cyrl-MN" 525 Figure 9 527 The 'lang' attribute may appear anywhere in an object class or data 528 structure except for in jCard objects. 530 4.5. Events 532 This data structure represents events that have occurred on an 533 instance of an object class (see Section 5 regarding object classes). 535 This is an example of an "events" array. 537 "events" : 538 [ 539 { 540 "eventAction" : "registration", 541 "eventActor" : "SOMEID-LUNARNIC", 542 "eventDate" : "1990-12-31T23:59:59Z" 543 }, 544 { 545 "eventAction" : "last changed", 546 "eventActor" : "OTHERID-LUNARNIC", 547 "eventDate" : "1991-12-31T23:59:59Z" 548 } 549 ] 551 Figure 10 553 The "events" array consists of objects, each with the following 554 members: 556 o 'eventAction' -- a string denoting the reason for the event 558 o 'eventActor' -- an optional identifier denoting the actor 559 responsible for the event 561 o 'eventDate' -- a string containing the time and date the event 562 occurred. 564 o 'links' -- see Section 4.2. 566 Events can be future dated. One use case for future dating of events 567 is to denote when an object expires from a registry. 569 The 'links' array in this data structure is provided for references 570 to the event actor. In order to reference an RDAP entity, a "rel" of 571 "related" and a "type" of "application/rdap+json" is used in the link 572 reference. 574 See Section 10.2.3 for a list of values for the 'eventAction' string. 575 See Appendix B regarding the various ways events can be modeled. 577 4.6. Status 579 This data structure, named 'status', is an array of strings 580 indicating the state of a registered object (see Section 10.2.2 for a 581 list of values). 583 4.7. Port 43 WHOIS Server 585 This data structure, a member named 'port43', is a simple string 586 containing the fully-qualified host name or IP address of the WHOIS 587 [RFC3912] server where the containing object instance may be found. 588 Note that this is not a URI, as there is no WHOIS URI scheme. 590 4.8. Public IDs 592 This data structure maps a public identifier to an object class. It 593 is named 'publicIds' and is an array of objects, with each object 594 containing the following members: 596 o type - a string denoting the type of public identifier 598 o identifier - a public identifier of the type denoted by 'type' 600 The following is an example of a 'publicIds' structure. 602 "publicIds": 603 [ 604 { 605 "type":"IANA Registrar ID", 606 "identifier":"1" 607 } 608 ] 610 Figure 11 612 4.9. Object Class Name 614 This data structure, a member named "objectClassName", gives the 615 object class name of a particular object as a string. This 616 identifies the type of object being processed. An objectClassName is 617 REQUIRED in all RDAP response objects so that the type of the object 618 can be interpreted. 620 4.10. An Example 622 This is an example response with both rdapConformance and notices 623 embedded: 625 { 626 "rdapConformance" : 627 [ 628 "rdap_level_0" 629 ], 630 "notices" : 631 [ 632 { 633 "title" : "Content Redacted", 634 "description" : 635 [ 636 "Without full authorization, content has been redacted.", 637 "Sorry, dude!" 638 ], 639 "links" : 640 [ 641 { 642 "value" : "http://example.net/ip/192.0.2.0/24", 643 "rel" : "alternate", 644 "type" : "text/html", 645 "href" : "http://www.example.com/redaction_policy.html" 646 } 647 ] 648 } 649 ], 650 "lang" : "en", 651 "objectClassName" : "ip network", 652 "startAddress" : "192.0.2.0", 653 "endAddress" : "192.0.2.255", 654 "handle" : "XXXX-RIR", 655 "ipVersion" : "v4", 656 "name": "NET-RTR-1", 657 "parentHandle" : "YYYY-RIR", 658 "remarks" : 659 [ 660 { 661 "description" : 662 [ 663 "She sells sea shells down by the sea shore.", 664 "Originally written by Terry Sullivan." 665 ] 666 } 667 ] 668 } 670 Figure 12 672 5. Object Classes 674 Object classes represent structures appropriate for a response from 675 the queries specified in [I-D.ietf-weirds-rdap-query]. 677 Each object class contains a "links" array as specified in 678 Section 4.2. For every object class instance in a response, whether 679 the object class instance is directly representing the response to a 680 query or is embedded in other object class instances or is an item in 681 a search result set, servers SHOULD provide a link representing a URI 682 for that object class instance using the "self" relationship as 683 described in the IANA registry specified by [RFC5988]. As explained 684 in Section 5.2, this may be not always be possible for name server 685 data. Clients MUST be able to process object instances without a 686 "self" link. When present, clients can use the self link for caching 687 data. Servers MAY provide more than one "self" link for any given 688 object instance. Failure to provide any "self" link by a server may 689 result in clients being unable to cache object class instances. 691 Clients using "self" links for caching SHOULD not cache any object 692 class instances where the authority of the self link is different 693 than the authority of the server returning the data. Failing to do 694 so might result in cache poisoning. 696 Self links MUST contain a "type" element containing the "application/ 697 rdap+json" media type when referencing RDAP object instances as 698 defined by this document. 700 This is an example of the "links" array with a self link to an object 701 class: 703 "links" : 704 [ 705 { 706 "value" : "http://example.com/ip/2001:db8::123", 707 "rel" : "self", 708 "href" : "http://example.com/ip/2001:db8::123", 709 "type" : "application/rdap+json" 710 } 711 ] 713 5.1. The Entity Object Class 715 The entity object class appears throughout this document and is an 716 appropriate response for the /entity/XXXX query defined in 717 Registration Data Access Protocol Lookup Format 718 [I-D.ietf-weirds-rdap-query]. This object class represents the 719 information of organizations, corporations, governments, non-profits, 720 clubs, individual persons, and informal groups of people. All of 721 these representations are so similar that it is best to represent 722 them in JSON [RFC7159] with one construct, the entity object class, 723 to aid in the re-use of code by implementers. 725 The entity object is served by both RIRs and DNRs. The following is 726 an example of an entity that might be served by an RIR. 728 { 729 "objectClassName" : "entity", 730 "handle":"XXXX", 731 "vcardArray":[ 732 "vcard", 733 [ 734 ["version", {}, "text", "4.0"], 735 ["fn", {}, "text", "Joe User"], 736 ["n", {}, "text", 737 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 738 ], 739 ["bday", {}, "date-and-or-time", "--02-03"], 740 ["anniversary", 741 {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" 742 ], 743 ["gender", {}, "text", "M"], 744 ["kind", {}, "text", "individual"], 745 ["lang", { 746 "pref":"1" 747 }, "language-tag", "fr"], 748 ["lang", { 749 "pref":"2" 750 }, "language-tag", "en"], 751 ["org", { 752 "type":"work" 753 }, "text", "Example"], 754 ["title", {}, "text", "Research Scientist"], 755 ["role", {}, "text", "Project Lead"], 756 ["adr", 757 { "type":"work" }, 758 "text", 759 [ 760 "", 761 "Suite 1234", 762 "4321 Rue Somewhere", 763 "Quebec", 764 "QC", 765 "G1V 2M2", 766 "Canada" 768 ] 769 ], 770 ["adr", 771 { 772 "type":"home", 773 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 774 }, 775 "text", 776 [ 777 "", "", "", "", "", "", "" 778 ] 779 ], 780 ["tel", 781 { 782 "type":["work", "voice"], 783 "pref":"1" 784 }, 785 "uri", 786 "tel:+1-555-555-1234;ext=102" 787 ], 788 ["tel", 789 { "type":["work", "cell", "voice", "video", "text"] }, 790 "uri", 791 "tel:+1-555-555-4321" 792 ], 793 ["email", 794 { "type":"work" }, 795 "text", 796 "joe.user@example.com" 797 ], 798 ["geo", { 799 "type":"work" 800 }, "uri", "geo:46.772673,-71.282945"], 801 ["key", 802 { "type":"work" }, 803 "uri", 804 "http://www.example.com/joe.user/joe.asc" 805 ], 806 ["tz", {}, 807 "utc-offset", "-05:00"], 808 ["url", { "type":"home" }, 809 "uri", "http://example.org"] 810 ] 811 ], 812 "roles":[ "registrar" ], 813 "publicIds":[ 814 { 815 "type":"IANA Registrar ID", 816 "identifier":"1" 817 } 818 ], 819 "remarks":[ 820 { 821 "description":[ 822 "She sells sea shells down by the sea shore.", 823 "Originally written by Terry Sullivan." 824 ] 825 } 826 ], 827 "links":[ 828 { 829 "value":"http://example.com/entity/XXXX", 830 "rel":"self", 831 "href":"http://example.com/entity/XXXX", 832 "type" : "application/rdap+json" 833 } 834 ], 835 "events":[ 836 { 837 "eventAction":"registration", 838 "eventDate":"1990-12-31T23:59:59Z" 839 } 840 ], 841 "asEventActor":[ 842 { 843 "eventAction":"last changed", 844 "eventDate":"1991-12-31T23:59:59Z" 845 } 846 ] 847 } 849 This object has the following members: 851 o objectClassName -- the string "entity" 853 o handle -- a string representing an registry unique identifier of 854 the entity 856 o vcardArray -- a jCard with the entity's contact information 858 o roles -- an array of strings, each signifying the relationship an 859 object would have with its closest containing object (see 860 Section 10.2.4 for a list of values) 862 o publicIds - see Section 4.8 863 o entities - an array of entity objects as defined by this section. 865 o remarks -- see Section 4.3 867 o links -- see Section 4.2 869 o events -- see Section 4.5 871 o asEventActor -- this data structure takes the same form as the 872 'events' data structure (see Section 4.5), but each object in the 873 array MUST NOT have an 'eventActor' member. These objects denote 874 that the entity is an event actor for the given events. See 875 Appendix B regarding the various ways events can be modeled. 877 o status -- see Section 4.6 879 o port43 -- see Section 4.7 881 o networks -- an array of IP network objects as defined in 882 Section 5.4 884 o autnums -- an array of autnum objects as defined in Section 5.5 886 Entities may also have other entities embedded with them in an array. 887 This can be used to model an organization with specific individuals 888 fulfilling designated roles of responsibility. 890 The following is an elided example of an entity with embedded 891 entities. 893 { 894 "objectClassName" : "entity", 895 "handle" : "ANENTITY", 896 "roles" : [ "registrar" ], 897 ... 898 "entities" : 899 [ 900 { 901 "objectClassName" : "entity", 902 "handle": "ANEMBEDDEDENTITY", 903 "roles" : [ "technical" ], 904 ... 905 }, 906 ... 907 ], 908 ... 909 } 911 Figure 13 913 The following is an example of a entity that might be served by a 914 DNR. 916 { 917 "objectClassName" : "entity", 918 "handle":"XXXX", 919 "vcardArray":[ 920 "vcard", 921 [ 922 ["version", {}, "text", "4.0"], 923 ["fn", {}, "text", "Joe User"], 924 ["kind", {}, "text", "individual"], 925 ["lang", { 926 "pref":"1" 927 }, "language-tag", "fr"], 928 ["lang", { 929 "pref":"2" 930 }, "language-tag", "en"], 931 ["org", { 932 "type":"work" 933 }, "text", "Example"], 934 ["title", {}, "text", "Research Scientist"], 936 ["role", {}, "text", "Project Lead"], 937 ["adr", 938 { "type":"work" }, 939 "text", 940 [ 941 "", 942 "Suite 1234", 943 "4321 Rue Somewhere", 944 "Quebec", 945 "QC", 946 "G1V 2M2", 947 "Canada" 948 ] 949 ], 950 ["tel", 951 { "type":["work", "voice"], "pref":"1" }, 952 "uri", "tel:+1-555-555-1234;ext=102" 953 ], 954 ["email", 955 { "type":"work" }, 956 "text", "joe.user@example.com" 957 ] 958 ] 959 ], 960 "status":[ "validated", "locked" ], 961 "remarks":[ 962 { 963 "description":[ 964 "She sells sea shells down by the sea shore.", 965 "Originally written by Terry Sullivan." 966 ] 967 } 968 ], 969 "links":[ 970 { 971 "value":"http://example.com/entity/XXXX", 972 "rel":"self", 973 "href":"http://example.com/entity/XXXX", 974 "type":"application/rdap+json" 975 } 976 ], 977 "port43":"whois.example.net", 978 "events":[ 979 { 980 "eventAction":"registration", 981 "eventDate":"1990-12-31T23:59:59Z" 982 }, 983 { 984 "eventAction":"last changed", 985 "eventDate":"1991-12-31T23:59:59Z", 986 "eventActor":"joe@example.com" 987 } 988 ] 989 } 991 See Appendix A for use of the entity object class to model various 992 types of entities found in both RIRs and DNRs. See Appendix C 993 regarding structured vs. unstructured postal addresses in entities. 995 5.2. The Nameserver Object Class 997 The nameserver object class represents information regarding DNS name 998 servers used in both forward and reverse DNS. RIRs and some DNRs 999 register or expose nameserver information as an attribute of a domain 1000 name, while other DNRs model nameservers as "first class objects". 1002 The nameserver object class accommodates both models and degrees of 1003 variation in between. 1005 The following is an example of a nameserver object. 1007 { 1008 "objectClassName" : "nameserver", 1009 "handle" : "XXXX", 1010 "ldhName" : "ns1.xn--fo-5ja.example", 1011 "unicodeName" : "ns1.foo.example", 1012 "status" : [ "active" ], 1013 "ipAddresses" : 1014 { 1015 "v4": [ "192.0.2.1", "192.0.2.2" ], 1016 "v6": [ "2001:db8::123" ] 1017 }, 1018 "remarks" : 1019 [ 1020 { 1021 "description" : 1022 [ 1023 "She sells sea shells down by the sea shore.", 1024 "Originally written by Terry Sullivan." 1025 ] 1026 } 1027 ], 1028 "links" : 1029 [ 1030 { 1031 "value" : "http://example.net/nameserver/xxxx", 1032 "rel" : "self", 1033 "href" : "http://example.net/nameserver/xxxx", 1034 "type" : "application/rdap+json" 1035 } 1036 ], 1037 "port43" : "whois.example.net", 1038 "events" : 1039 [ 1040 { 1041 "eventAction" : "registration", 1042 "eventDate" : "1990-12-31T23:59:59Z" 1043 }, 1044 { 1045 "eventAction" : "last changed", 1046 "eventDate" : "1991-12-31T23:59:59Z", 1047 "eventActor" : "joe@example.com" 1048 } 1049 ] 1050 } 1052 Figure 14 1054 Figure 14 is an example of a nameserver object with all values given. 1055 Registries using a first-class nameserver data model would embed this 1056 in domain objects as well as allowing references to it with the 1057 "/nameserver" query type (all depending on the registry operators 1058 policy). Other registries may pare back the information as needed. 1059 Figure 15 is an example of a nameserver object as would be found in 1060 RIRs and some DNRs, while Figure 16 is an example of a nameserver 1061 object as would be found in other DNRs. 1063 The following is an example of the simplest nameserver object: 1065 { 1066 "objectClassName" : "nameserver", 1067 "ldhName" : "ns1.example.com" 1068 } 1070 Figure 15 1072 The following is an example of a simple nameserver object that might 1073 be commonly used by DNRs: 1075 { 1076 "objectClassName" : "nameserver", 1077 "ldhName" : "ns1.example.com", 1078 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 1079 } 1081 Figure 16 1083 As nameservers can be modeled by some registries to be first-class 1084 objects, they may also have an array of entities (Section 5.1) 1085 embedded to signify parties responsible for the maintenance, 1086 registrations, etc. of the nameservers. 1088 The following is an elided example of a nameserver with embedded 1089 entities. 1091 { 1092 "objectClassName" : "nameserver", 1093 "handle" : "XXXX", 1094 "ldhName" : "ns1.xn--fo-5ja.example", 1095 ... 1096 "entities" : 1097 [ 1098 ... 1099 ], 1100 ... 1101 } 1103 Figure 17 1105 The nameserver object class has the following members: 1107 o objectClassName - the string "nameserver" 1109 o handle -- a string representing an registry unique identifier of 1110 the nameserver 1112 o ldhName -- a string containing the LDH name of the nameserver (see 1113 Section 3) 1115 o unicodeName -- a string containing a DNS Unicode name of the 1116 nameserver (see Section 3) 1118 o ipAddresses -- an object containing the following members: 1120 * v6 -- an array of strings containing IPv6 addresses of the 1121 nameserver 1123 * v4 -- an array of strings containing IPv4 addresses of the 1124 nameserver 1126 o entities -- an array of entity objects as defined by Section 5.1. 1128 o status - see Section 4.6 1130 o remarks - see Section 4.3 1132 o links - see Section 4.2 1133 o port43 - see Section 4.7 1135 o events - see Section 4.5 1137 5.3. The Domain Object Class 1139 The domain object class represents a DNS name and point of 1140 delegation. For RIRs these delegation points are in the reverse DNS 1141 tree, whereas for DNRs these delegation points are in the forward DNS 1142 tree. 1144 In both cases, the high level structure of the domain object class 1145 consists of information about the domain registration, nameserver 1146 information related to the domain name, and entities related to the 1147 domain name (e.g. registrant information, contacts, etc.). 1149 The following is an elided example of the domain object showing the 1150 high level structure: 1152 { 1153 "objectClassName" : "domain", 1154 "handle" : "XXX", 1155 "ldhName" : "blah.example.com", 1156 ... 1157 "nameservers" : 1158 [ 1159 ... 1160 ], 1161 ... 1162 "entities" : 1163 [ 1164 ... 1165 ] 1166 } 1168 The following is a description of the members of this object: 1170 o objectClassName -- the string "domain" 1172 o handle -- a string representing a registry unique identifier of 1173 the domain object instance 1175 o ldhName -- a string describing a domain name in LDH form as 1176 described in Section 3 1178 o unicodeName -- a string containing a domain name with U-labels as 1179 described in Section 3 1181 o variants -- an array of objects, each containing the following 1182 values: 1184 * relation -- an array of strings, with each string denoting the 1185 relationship between the variants and the containing domain 1186 object (see Section 10.2.5 for a list of suggested variant 1187 relations). 1189 * idnTable -- the name of the IDN table of codepoints, such as 1190 one listed with the IANA (see IDN tables [IANA_IDNTABLES]). 1192 * variantNames -- an array of objects, with each object 1193 containing an "ldhName" member and a "unicodeName" member (see 1194 Section 3). 1196 o nameservers -- an array of nameserver objects as defined by 1197 Section 5.2 1199 o secureDNS -- an object with the following members: 1201 * zoneSigned -- true if the zone has been signed, false 1202 otherwise. 1204 * delegationSigned -- boolean true if there are DS records in the 1205 parent, false otherwise. 1207 * maxSigLife -- an integer representing the signature life time 1208 in seconds to be used when creating the RRSIG DS record in the 1209 parent zone [RFC5910]. 1211 * dsData - an array of objects, each with the following members: 1213 + keyTag -- an integer as specified by the key tag field of a 1214 DNS DS record as specified by RFC 4034 [RFC4034] in 1215 presentation format 1217 + algorithm -- an integer as specified by the algorithm field 1218 of a DNS DS record as described by RFC 4034 in presentation 1219 format 1221 + digest -- a string as specified by the digest field of a DNS 1222 DS record as specified by RFC 4034 in presentation format 1224 + digestType -- an integer as specified by the digest type 1225 field of a DNS DS record as specified by RFC 4034 in 1226 presentation format 1228 + events - see Section 4.5 1230 + links - see Section 4.2 1232 * keyData - an array of objects, each with the following members: 1234 + flags -- an integer representing the flags field value in 1235 the DNSKEY record [RFC4034] in presentation format 1237 + protocol - an integer representation of the protocol field 1238 value of the DNSKEY record [RFC4034] in presentation format 1240 + publicKey - a string representation of the public key in the 1241 DNSKEY record [RFC4034] in presentation format 1243 + algorithm -- an integer as specified by the algorithm field 1244 of a DNSKEY record as specified by RFC 4034 [RFC4034] in 1245 presentation format 1247 + events - see Section 4.5 1249 + links - see Section 4.2 1251 See Appendix D for background information on these objects. 1253 o entities -- an array of entity objects as defined by Section 5.1. 1255 o status - see Section 4.6 1257 o publicIds - see Section 4.8 1259 o remarks - see Section 4.3 1261 o links - see Section 4.2 1263 o port43 - see Section 4.7 1265 o events - see Section 4.5 1267 o network - represents the IP network for which a reverse DNS domain 1268 is referenced. See Section 5.4 1270 The following is an example of a JSON domain object representing a 1271 reverse DNS delegation point that might be served by an RIR. 1273 { 1274 "objectClassName" : "domain", 1275 "handle" : "XXXX", 1276 "ldhName" : "0.2.192.in-addr.arpa", 1277 "nameservers" : 1278 [ 1279 { 1280 "objectClassName" : "nameserver", 1281 "ldhName" : "ns1.rir.example" 1282 }, 1283 { 1284 "objectClassName" : "nameserver", 1285 "ldhName" : "ns2.rir.example" 1286 } 1287 ], 1288 "secureDNS": 1289 { 1290 "delegationSigned": true, 1291 "dsData": 1292 [ 1293 { 1294 "keyTag": 12345, 1295 "algorithm": 3, 1296 "digestType": 1, 1297 "digest": "49FD46E6C4B45C55D4AC" 1298 } 1299 ] 1300 }, 1301 "remarks" : 1302 [ 1303 { 1304 "description" : 1305 [ 1306 "She sells sea shells down by the sea shore.", 1307 "Originally written by Terry Sullivan." 1308 ] 1309 } 1310 ], 1311 "links" : 1312 [ 1313 { 1314 "value": "http://example.net/domain/XXXX", 1315 "rel" : "self", 1316 "href" : "http://example.net/domain/XXXXX", 1317 "type" : "application/rdap+json" 1318 } 1319 ], 1320 "events" : 1322 [ 1323 { 1324 "eventAction" : "registration", 1325 "eventDate" : "1990-12-31T23:59:59Z" 1326 }, 1327 { 1328 "eventAction" : "last changed", 1329 "eventDate" : "1991-12-31T23:59:59Z", 1330 "eventActor" : "joe@example.com" 1331 } 1332 ], 1333 "entities" : 1334 [ 1335 { 1336 "objectClassName" : "entity", 1337 "handle" : "XXXX", 1338 "vcardArray":[ 1339 "vcard", 1340 [ 1341 ["version", {}, "text", "4.0"], 1342 ["fn", {}, "text", "Joe User"], 1343 ["kind", {}, "text", "individual"], 1344 ["lang", { 1345 "pref":"1" 1346 }, "language-tag", "fr"], 1347 ["lang", { 1348 "pref":"2" 1349 }, "language-tag", "en"], 1350 ["org", { 1351 "type":"work" 1352 }, "text", "Example"], 1353 ["title", {}, "text", "Research Scientist"], 1354 ["role", {}, "text", "Project Lead"], 1355 ["adr", 1356 { "type":"work" }, 1357 "text", 1358 [ 1359 "", 1360 "Suite 1234", 1361 "4321 Rue Somewhere", 1362 "Quebec", 1363 "QC", 1364 "G1V 2M2", 1365 "Canada" 1366 ] 1367 ], 1368 ["tel", 1369 { "type":["work", "voice"], "pref":"1" }, 1370 "uri", "tel:+1-555-555-1234;ext=102" 1371 ], 1372 ["email", 1373 { "type":"work" }, 1374 "text", "joe.user@example.com" 1375 ] 1376 ] 1377 ], 1378 "roles" : [ "registrant" ], 1379 "remarks" : 1380 [ 1381 { 1382 "description" : 1383 [ 1384 "She sells sea shells down by the sea shore.", 1385 "Originally written by Terry Sullivan." 1386 ] 1387 } 1388 ], 1389 "links" : 1390 [ 1391 { 1392 "value": "http://example.net/entity/xxxx", 1393 "rel" : "self", 1394 "href" : "http://example.net/entity/xxxx", 1395 "type" : "application/rdap+json" 1396 } 1397 ], 1398 "events" : 1399 [ 1400 { 1401 "eventAction" : "registration", 1402 "eventDate" : "1990-12-31T23:59:59Z" 1403 }, 1404 { 1405 "eventAction" : "last changed", 1406 "eventDate" : "1991-12-31T23:59:59Z", 1407 "eventActor" : "joe@example.com" 1408 } 1409 ] 1410 } 1411 ], 1412 "network" : 1413 { 1414 "objectClassName" : "ip network", 1415 "handle" : "XXXX-RIR", 1416 "startAddress" : "192.0.2.0", 1417 "endAddress" : "192.0.2.255", 1418 "ipVersion" : "v6", 1419 "name": "NET-RTR-1", 1420 "type" : "DIRECT ALLOCATION", 1421 "country" : "AU", 1422 "parentHandle" : "YYYY-RIR", 1423 "status" : [ "active" ] 1424 } 1425 } 1427 The following is an example of a JSON domain object representing a 1428 forward DNS delegation point that might be served by a DNR. 1430 { 1431 "objectClassName" : "domain", 1432 "handle" : "XXXX", 1433 "ldhName" : "xn--fo-5ja.example", 1434 "unicodeName" : "foo.example", 1435 "variants" : 1436 [ 1437 { 1438 "relation" : [ "registered", "conjoined" ], 1439 "variantNames" : 1440 [ 1441 { 1442 "ldhName" : "xn--fo-cka.example", 1443 "unicodeName" : "foo.example" 1444 }, 1445 { 1446 "ldhName" : "xn--fo-fka.example", 1447 "unicodeName" : "foeo.example" 1448 } 1449 ] 1450 }, 1451 { 1452 "relation" : [ "unregistered", "registration restricted" ], 1453 "idnTable": ".EXAMPLE Swedish", 1454 "variantNames" : 1455 [ 1456 { 1457 "ldhName": "xn--fo-8ja.example", 1458 "unicodeName" : "foo.example" 1459 } 1460 ] 1461 } 1462 ], 1463 "status" : [ "locked", "transfer prohibited" ], 1464 "publicIds":[ 1465 { 1466 "type":"ENS_Auth ID", 1467 "identifier":"1234567890" 1468 } 1469 ], 1470 "nameservers" : 1471 [ 1472 { 1473 "objectClassName" : "nameserver", 1474 "handle" : "XXXX", 1475 "ldhName" : "ns1.example.com", 1476 "status" : [ "active" ], 1477 "ipAddresses" : 1478 { 1479 "v6": [ "2001:db8::123", "2001:db8::124" ], 1480 "v4": [ "192.0.2.1", "192.0.2.2" ] 1481 }, 1482 "remarks" : 1483 [ 1484 { 1485 "description" : 1486 [ 1487 "She sells sea shells down by the sea shore.", 1488 "Originally written by Terry Sullivan." 1489 ] 1490 } 1491 ], 1492 "links" : 1493 [ 1494 { 1495 "value" : "http://example.net/nameserver/XXXX", 1496 "rel" : "self", 1497 "href" : "http://example.net/nameserver/XXXX", 1498 "type" : "application/rdap+json" 1499 } 1500 ], 1501 "events" : 1502 [ 1503 { 1504 "eventAction" : "registration", 1505 "eventDate" : "1990-12-31T23:59:59Z" 1506 }, 1507 { 1508 "eventAction" : "last changed", 1509 "eventDate" : "1991-12-31T23:59:59Z" 1510 } 1511 ] 1513 }, 1514 { 1515 "objectClassName" : "nameserver", 1516 "handle" : "XXXX", 1517 "ldhName" : "ns2.example.com", 1518 "status" : [ "active" ], 1519 "ipAddresses" : 1520 { 1521 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1522 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1523 }, 1524 "remarks" : 1525 [ 1526 { 1527 "description" : 1528 [ 1529 "She sells sea shells down by the sea shore.", 1530 "Originally written by Terry Sullivan." 1531 ] 1532 } 1533 ], 1534 "links" : 1535 [ 1536 { 1537 "value" : "http://example.net/nameserver/XXXX", 1538 "rel" : "self", 1539 "href" : "http://example.net/nameserver/XXXX", 1540 "type" : "application/rdap+json" 1541 } 1542 ], 1543 "events" : 1544 [ 1545 { 1546 "eventAction" : "registration", 1547 "eventDate" : "1990-12-31T23:59:59Z" 1548 }, 1549 { 1550 "eventAction" : "last changed", 1551 "eventDate" : "1991-12-31T23:59:59Z" 1552 } 1553 ] 1554 } 1555 ], 1556 "secureDNS": 1557 { 1558 "zoneSigned": true, 1559 "delegationSigned": true, 1560 "maxSigLife": 604800, 1561 "keyData": 1562 [ 1563 { 1564 "flags": 257, 1565 "protocol": 3, 1566 "algorithm": 1, 1567 "publicKey": "AQPJ////4Q==", 1568 "events": 1569 [ 1570 { 1571 "eventAction": "last changed", 1572 "eventDate": "2012-07-23T05:15:47Z" 1573 } 1574 ] 1575 } 1576 ] 1577 }, 1578 "remarks" : 1579 [ 1580 { 1581 "description" : 1582 [ 1583 "She sells sea shells down by the sea shore.", 1584 "Originally written by Terry Sullivan." 1585 ] 1586 } 1587 ], 1588 "links" : 1589 [ 1590 { 1591 "value": "http://example.net/domain/XXXX", 1592 "rel" : "self", 1593 "href" : "http://example.net/domain/XXXX", 1594 "type" : "application/rdap+json" 1595 } 1596 ], 1597 "port43" : "whois.example.net", 1598 "events" : 1599 [ 1600 { 1601 "eventAction" : "registration", 1602 "eventDate" : "1990-12-31T23:59:59Z" 1603 }, 1604 { 1605 "eventAction" : "last changed", 1606 "eventDate" : "1991-12-31T23:59:59Z", 1607 "eventActor" : "joe@example.com" 1608 }, 1609 { 1610 "eventAction" : "transfer", 1611 "eventDate" : "1991-12-31T23:59:59Z", 1612 "eventActor" : "joe@example.com" 1613 }, 1614 { 1615 "eventAction" : "expiration", 1616 "eventDate" : "2016-12-31T23:59:59Z", 1617 "eventActor" : "joe@example.com" 1618 } 1619 ], 1620 "entities" : 1621 [ 1622 { 1623 "objectClassName" : "entity", 1624 "handle" : "XXXX", 1625 "vcardArray":[ 1626 "vcard", 1627 [ 1628 ["version", {}, "text", "4.0"], 1629 ["fn", {}, "text", "Joe User"], 1630 ["kind", {}, "text", "individual"], 1631 ["lang", { 1632 "pref":"1" 1633 }, "language-tag", "fr"], 1634 ["lang", { 1635 "pref":"2" 1636 }, "language-tag", "en"], 1637 ["org", { 1638 "type":"work" 1639 }, "text", "Example"], 1640 ["title", {}, "text", "Research Scientist"], 1641 ["role", {}, "text", "Project Lead"], 1642 ["adr", 1643 { "type":"work" }, 1644 "text", 1645 [ 1646 "", 1647 "Suite 1234", 1648 "4321 Rue Somewhere", 1649 "Quebec", 1650 "QC", 1651 "G1V 2M2", 1652 "Canada" 1653 ] 1654 ], 1655 ["tel", 1656 { "type":["work", "voice"], "pref":"1" }, 1657 "uri", "tel:+1-555-555-1234;ext=102" 1658 ], 1659 ["email", 1660 { "type":"work" }, 1661 "text", "joe.user@example.com" 1662 ] 1663 ] 1664 ], 1665 "status" : [ "validated", "locked" ], 1666 "roles" : [ "registrant" ], 1667 "remarks" : 1668 [ 1669 { 1670 "description" : 1671 [ 1672 "She sells sea shells down by the sea shore.", 1673 "Originally written by Terry Sullivan." 1674 ] 1675 } 1676 ], 1677 "links" : 1678 [ 1679 { 1680 "value" : "http://example.net/entity/xxxx", 1681 "rel" : "self", 1682 "href" : "http://example.net/entity/xxxx", 1683 "type" : "application/rdap+json" 1684 } 1685 ], 1686 "events" : 1687 [ 1688 { 1689 "eventAction" : "registration", 1690 "eventDate" : "1990-12-31T23:59:59Z" 1691 }, 1692 { 1693 "eventAction" : "last changed", 1694 "eventDate" : "1991-12-31T23:59:59Z" 1695 } 1696 ] 1697 } 1698 ] 1699 } 1701 5.4. The IP Network Object Class 1703 The IP Network object class models IP network registrations found in 1704 RIRs and is the expected response for the "/ip" query as defined by 1705 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1706 for DNRs. The high level structure of the IP network object class 1707 consists of information about the network registration and entities 1708 related to the IP network (e.g. registrant information, contacts, 1709 etc...). 1711 The following is an elided example of the IP network object type 1712 showing the high level structure: 1714 { 1715 "objectClassName" : "ip network", 1716 "handle" : "XXX", 1717 ... 1718 "entities" : 1719 [ 1720 ... 1721 ] 1722 } 1724 The following is an example of the JSON object for the network 1725 registration information. 1727 { 1728 "objectClassName" : "ip network", 1729 "handle" : "XXXX-RIR", 1730 "startAddress" : "2001:db8::0", 1731 "endAddress" : "2001:db8:0:FFFF:FFFF:FFFF:FFFF:FFFF", 1732 "ipVersion" : "v6", 1733 "name": "NET-RTR-1", 1734 "type" : "DIRECT ALLOCATION", 1735 "country" : "AU", 1736 "parentHandle" : "YYYY-RIR", 1737 "status" : [ "active" ], 1738 "remarks" : 1739 [ 1740 { 1741 "description" : 1742 [ 1743 "She sells sea shells down by the sea shore.", 1744 "Originally written by Terry Sullivan." 1745 ] 1747 } 1748 ], 1749 "links" : 1750 [ 1751 { 1752 "value" : "http://example.net/ip/2001:db8::/48", 1753 "rel" : "self", 1754 "href" : "http://example.net/ip/2001:db8::/48", 1755 "type" : "application/rdap+json" 1756 }, 1757 { 1758 "value" : "http://example.net/ip/2001:db8::/48", 1759 "rel" : "up", 1760 "href" : "http://example.net/ip/2001:C00::/23", 1761 "type" : "application/rdap+json" 1762 } 1763 ], 1764 "events" : 1765 [ 1766 { 1767 "eventAction" : "registration", 1768 "eventDate" : "1990-12-31T23:59:59Z" 1769 }, 1770 { 1771 "eventAction" : "last changed", 1772 "eventDate" : "1991-12-31T23:59:59Z" 1773 } 1774 ], 1775 "entities" : 1776 [ 1777 { 1778 "objectClassName" : "entity", 1779 "handle" : "XXXX", 1780 "vcardArray":[ 1781 "vcard", 1782 [ 1783 ["version", {}, "text", "4.0"], 1784 ["fn", {}, "text", "Joe User"], 1785 ["kind", {}, "text", "individual"], 1786 ["lang", { 1787 "pref":"1" 1788 }, "language-tag", "fr"], 1789 ["lang", { 1790 "pref":"2" 1791 }, "language-tag", "en"], 1792 ["org", { 1793 "type":"work" 1794 }, "text", "Example"], 1796 ["title", {}, "text", "Research Scientist"], 1797 ["role", {}, "text", "Project Lead"], 1798 ["adr", 1799 { "type":"work" }, 1800 "text", 1801 [ 1802 "", 1803 "Suite 1234", 1804 "4321 Rue Somewhere", 1805 "Quebec", 1806 "QC", 1807 "G1V 2M2", 1808 "Canada" 1809 ] 1810 ], 1811 ["tel", 1812 { "type":["work", "voice"], "pref":"1" }, 1813 "uri", "tel:+1-555-555-1234;ext=102" 1814 ], 1815 ["email", 1816 { "type":"work" }, 1817 "text", "joe.user@example.com" 1818 ] 1819 ] 1820 ], 1821 "roles" : [ "registrant" ], 1822 "remarks" : 1823 [ 1824 { 1825 "description" : 1826 [ 1827 "She sells sea shells down by the sea shore.", 1828 "Originally written by Terry Sullivan." 1829 ] 1830 } 1831 ], 1832 "links" : 1833 [ 1834 { 1835 "value" : "http://example.net/entity/xxxx", 1836 "rel" : "self", 1837 "href" : "http://example.net/entity/xxxx", 1838 "type" : "application/rdap+json" 1839 } 1840 ], 1841 "events" : 1842 [ 1843 { 1844 "eventAction" : "registration", 1845 "eventDate" : "1990-12-31T23:59:59Z" 1846 }, 1847 { 1848 "eventAction" : "last changed", 1849 "eventDate" : "1991-12-31T23:59:59Z" 1850 } 1851 ] 1852 } 1853 ] 1854 } 1856 The following is a description of the members of this object: 1858 o objectClassName -- the string "ip network" 1860 o handle -- a string representing an RIR unique identifier of the 1861 network registration 1863 o startAddress -- the starting IP address of the network, either 1864 IPv4 or IPv6 1866 o endAddress -- the ending IP address of the network, either IPv4 or 1867 IPv6 1869 o ipVersion -- a string signifying the IP protocol version of the 1870 network: "v4" signifying an IPv4 network, "v6" signifying an IPv6 1871 network 1873 o name -- an identifier assigned to the network registration by the 1874 registration holder 1876 o type -- a string containing an RIR-specific classification of the 1877 network 1879 o country -- a string containing the two-character country code of 1880 the network 1882 o parentHandle -- a string containing an RIR-unique identifier of 1883 the parent network of this network registration 1885 o status -- an array of strings indicating the state of the IP 1886 network 1888 o entities -- an array of entity objects as defined by Section 5.1. 1890 o remarks - see Section 4.3 1891 o links - see Section 4.2 1893 o port43 - see Section 4.7 1895 o events - see Section 4.5 1897 5.5. Autonomous System Number Entity Object Class 1899 The Autonomous System Number (autnum) object class models Autonomous 1900 System Number registrations found in RIRs and represents the expected 1901 response to an "/autnum" query as defined by 1902 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1903 for DNRs. The high level structure of the autnum object class 1904 consists of information about the network registration and entities 1905 related to the autnum registration (e.g. registrant information, 1906 contacts, etc.), and is similar to the IP Network entity object 1907 class. 1909 The following is an example of a JSON object representing an autnum. 1911 { 1912 "objectClassName" : "autnum", 1913 "handle" : "XXXX-RIR", 1914 "startAutnum" : 10, 1915 "endAutnum" : 15, 1916 "name": "AS-RTR-1", 1917 "type" : "DIRECT ALLOCATION", 1918 "status" : [ "active" ], 1919 "country": "AU", 1920 "remarks" : 1921 [ 1922 { 1923 "description" : 1924 [ 1925 "She sells sea shells down by the sea shore.", 1926 "Originally written by Terry Sullivan." 1927 ] 1928 } 1929 ], 1930 "links" : 1931 [ 1932 { 1933 "value" : "http://example.net/autnum/xxxx", 1934 "rel" : "self", 1935 "href" : "http://example.net/autnum/xxxx", 1936 "type" : "application/rdap+json" 1937 } 1939 ], 1940 "events" : 1941 [ 1942 { 1943 "eventAction" : "registration", 1944 "eventDate" : "1990-12-31T23:59:59Z" 1945 }, 1946 { 1947 "eventAction" : "last changed", 1948 "eventDate" : "1991-12-31T23:59:59Z" 1949 } 1950 ], 1951 "entities" : 1952 [ 1953 { 1954 "objectClassName" : "entity", 1955 "handle" : "XXXX", 1956 "vcardArray":[ 1957 "vcard", 1958 [ 1959 ["version", {}, "text", "4.0"], 1960 ["fn", {}, "text", "Joe User"], 1961 ["kind", {}, "text", "individual"], 1962 ["lang", { 1963 "pref":"1" 1964 }, "language-tag", "fr"], 1965 ["lang", { 1966 "pref":"2" 1967 }, "language-tag", "en"], 1968 ["org", { 1969 "type":"work" 1970 }, "text", "Example"], 1971 ["title", {}, "text", "Research Scientist"], 1972 ["role", {}, "text", "Project Lead"], 1973 ["adr", 1974 { "type":"work" }, 1975 "text", 1976 [ 1977 "", 1978 "Suite 1234", 1979 "4321 Rue Somewhere", 1980 "Quebec", 1981 "QC", 1982 "G1V 2M2", 1983 "Canada" 1984 ] 1985 ], 1986 ["tel", 1987 { "type":["work", "voice"], "pref":"1" }, 1988 "uri", "tel:+1-555-555-1234;ext=102" 1989 ], 1990 ["email", 1991 { "type":"work" }, 1992 "text", "joe.user@example.com" 1993 ] 1994 ] 1995 ], 1996 "roles" : [ "registrant" ], 1997 "remarks" : 1998 [ 1999 { 2000 "description" : 2001 [ 2002 "She sells sea shells down by the sea shore.", 2003 "Originally written by Terry Sullivan." 2004 ] 2005 } 2006 ], 2007 "links" : 2008 [ 2009 { 2010 "value" : "http://example.net/entity/XXXX", 2011 "rel" : "self", 2012 "href" : "http://example.net/entity/XXXX", 2013 "type" : "application/rdap+json" 2014 } 2015 ], 2016 "events" : 2017 [ 2018 { 2019 "eventAction" : "registration", 2020 "eventDate" : "1990-12-31T23:59:59Z" 2021 }, 2022 { 2023 "eventAction" : "last changed", 2024 "eventDate" : "1991-12-31T23:59:59Z" 2025 } 2026 ] 2027 } 2028 ] 2029 } 2031 The following is a description of the members of this object: 2033 o objectClassName -- the string "autnum" 2034 o handle -- a string representing an RIR-unique identifier of the 2035 autnum registration 2037 o startAutnum -- a number representing the starting number [RFC5396] 2038 in the block of autonomous system numbers 2040 o endAutnum -- a number representing the ending number [RFC5396] in 2041 the block of autonomous system numbers 2043 o name -- an identifier assigned to the autnum registration by the 2044 registration holder 2046 o type -- a string containing an RIR-specific classification of the 2047 autnum 2049 o status -- an array of strings indicating the state of the autnum 2051 o country -- a string containing the name of the 2 character country 2052 code of the autnum 2054 o entities -- an array of entity objects as defined by Section 5.1. 2056 o remarks - see Section 4.3 2058 o links - see Section 4.2 2060 o port43 - see Section 4.7 2062 o events - see Section 4.5 2064 6. Error Response Body 2066 Some non-answer responses may return entity bodies with information 2067 that could be more descriptive. 2069 The basic structure of that response is an object class containing an 2070 error code number (corresponding to the HTTP response code) followed 2071 by a string named "title" and an array of strings named 2072 "description". 2074 This is an example of the common response body. 2076 { 2077 "errorCode": 418, 2078 "title": "Your beverage choice is not available", 2079 "description": 2080 [ 2081 "I know coffee has more ummppphhh.", 2082 "Sorry, dude!" 2083 ] 2084 } 2086 Figure 18 2088 This is an example of the common response body with and 2089 rdapConformance and notices data structures: 2091 { 2092 "rdapConformance" : 2093 [ 2094 "rdap_level_0" 2095 ], 2096 "notices" : 2097 [ 2098 { 2099 "title" : "Beverage policy", 2100 "description" : 2101 [ 2102 "Beverages with caffeine for keeping horses awake." 2103 ], 2104 "links" : 2105 [ 2106 { 2107 "value" : "http://example.net/ip/192.0.2.0/24", 2108 "rel" : "alternate", 2109 "type" : "text/html", 2110 "href" : "http://www.example.com/redaction_policy.html" 2111 } 2112 ] 2113 } 2114 ], 2115 "lang" : "en", 2116 "errorCode": 418, 2117 "title": "Your beverage choice is not available", 2118 "description": 2119 [ 2120 "I know coffee has more ummppphhh.", 2121 "Sorry, dude!" 2122 ] 2123 } 2125 Figure 19 2127 7. Responding to Help Queries 2129 The appropriate response to /help queries as defined by 2130 [I-D.ietf-weirds-rdap-query] is to use the notices structure as 2131 defined in Section 4.3. 2133 This is an example of a response to a /help query including the 2134 rdapConformance data structure. 2136 { 2137 "rdapConformance" : 2138 [ 2139 "rdap_level_0" 2140 ], 2141 "notices" : 2142 [ 2143 { 2144 "title" : "Authentication Policy", 2145 "description" : 2146 [ 2147 "Access to sensitive data for users with proper credentials." 2148 ], 2149 "links" : 2150 [ 2151 { 2152 "value" : "http://example.net/help", 2153 "rel" : "alternate", 2154 "type" : "text/html", 2155 "href" : "http://www.example.com/auth_policy.html" 2156 } 2157 ] 2158 } 2159 ] 2160 } 2162 Figure 20 2164 8. Responding To Searches 2166 [I-D.ietf-weirds-rdap-query] specifies three types of searches: 2167 domains, nameservers, and entities. Responses to these searches take 2168 the form of an array of object instances where each instance is an 2169 appropriate object class for the search (i.e. a search for /domains 2170 yields an array of domain object instances). These arrays are 2171 contained within the response object. 2173 The names of the arrays are as follows: 2175 o for /domains searches, the array is "domainSearchResults" 2177 o for /nameservers searches, the array is "nameserverSearchResults" 2179 o for /entities searches, the array is "entitySearchResults" 2180 The following is an elided example of a response to a /domains 2181 search. 2183 { 2184 "rdapConformance" : 2185 [ 2186 "rdap_level_0" 2187 ], 2188 ... 2189 "domainSearchResults" : 2190 [ 2191 { 2192 "objectClassName" : "domain", 2193 "handle" : "1-XXXX", 2194 "ldhName" : "1.example.com", 2195 ... 2196 }, 2197 { 2198 "objectClassName" : "domain", 2199 "handle" : "2-XXXX", 2200 "ldhName" : "2.example.com", 2201 ... 2202 } 2203 ] 2204 } 2206 search_response_example 2208 9. Indicating Truncated Responses 2210 In cases where the data of a response has been truncated (i.e. not 2211 all of it has been included in the response), a server may indicate 2212 this by including a typed notice in the response object. 2214 The following is an elided example of a search response that has been 2215 truncated. 2217 { 2218 "rdapConformance" : 2219 [ 2220 "rdap_level_0" 2221 ], 2222 "notices" : 2223 [ 2224 { 2225 "title" : "Search Policy", 2226 "type" : "result set truncated due to authorization", 2227 "description" : 2228 [ 2229 "Search results are limited to 25 per day per querying IP." 2230 ], 2231 "links" : 2232 [ 2233 { 2234 "value" : "http://example.net/help", 2235 "rel" : "alternate", 2236 "type" : "text/html", 2237 "href" : "http://www.example.com/search_policy.html" 2238 } 2239 ] 2240 } 2241 ], 2242 "domainSearchResults" : 2243 [ 2244 ... 2245 ] 2246 } 2248 search_response_truncated_example 2250 A similar technique can be used with a typed remark where a single 2251 object has been returned and data in that object has been truncated. 2252 Such an example might be an entity object with only a partial set of 2253 the IP networks associated with it. 2255 The following is an elided example of an entity truncated data. 2257 { 2258 "objectClassName" : "entity", 2259 "handle" : "ANENTITY", 2260 "roles" : [ "registrant" ], 2261 ... 2262 "entities" : 2263 [ 2264 { 2265 "objectClassName" : "entity", 2266 "handle": "ANEMBEDDEDENTITY", 2267 "roles" : [ "technical" ], 2268 ... 2269 }, 2270 ... 2271 ], 2272 "networks" : 2273 [ 2274 ... 2275 ], 2276 ... 2277 "remarks" : 2278 [ 2279 { 2280 "title" : "Data Policy", 2281 "type" : "object truncated due to unexplainable reason", 2282 "description" : 2283 [ 2284 "Some of the data in this object has been removed." 2285 ], 2286 "links" : 2287 [ 2288 { 2289 "value" : "http://example.net/help", 2290 "rel" : "alternate", 2291 "type" : "text/html", 2292 "href" : "http://www.example.com/data_policy.html" 2293 } 2294 ] 2295 } 2296 ] 2297 } 2299 Figure 21 2301 10. IANA Considerations 2303 10.1. RDAP JSON Media Type Registration 2305 This specification registers the "application/rdap+json" media type. 2307 Type name: application 2309 Subtype name: rdap+json 2311 Required parameters: n/a 2313 Encoding considerations: See section 3.1 of [RFC6839]. 2315 Security considerations: The media represented by this identifier 2316 does not have security considerations beyond that found in section 2317 6 of [RFC7159] 2319 Interoperability considerations: There are no known 2320 interoperability problems regarding this media format. 2322 Published specification: [[ this document ]] 2324 Applications that use this media type: Implementations of the 2325 Registration Data Access Protocol (RDAP) 2327 Additional information: This media type is a product of the IETF 2328 WEIRDS working group. The WEIRDS charter, information on the 2329 WEIRDS mailing list, and other documents produced by the WEIRDS 2330 working group can be found at https://datatracker.ietf.org/wg/ 2331 weirds/ 2333 Person & email address to contact for further information: IESG 2334 2336 Intended usage: COMMON 2338 Restrictions on usage: none 2340 Author: Andy Newton 2342 Change controller: IETF 2344 Provisional Registration: No (upon publication of this RFC) 2346 10.2. JSON Values Registry 2348 This section requests that the IANA create a new category in the 2349 protocol registries labeled "Registration Data Access Protocol 2350 (RDAP)" (if it does not already exist), and within that category 2351 establish a URL referenceable, stand-alone registry labeled "RDAP 2352 JSON Values". This new registry is for use in the notices and 2353 remarks (Section 4.3), status (Section 4.6), role (Section 5.1), 2354 event action (Section 4.5), and domain variant relation (Section 5.3) 2355 fields specified in RDAP. 2357 Each entry in the registry should contain the following fields: 2359 1. Value - the string value being registered. 2361 2. Type - the type of value being registered. It should be one of 2362 the following: 2364 * 'notice or remark type' - denotes a type of notice or remark 2366 * 'status' - denotes a value for the 'status' object member as 2367 defined by Section 4.6. 2369 * 'role' - denotes a value for the 'role' array as defined in 2370 Section 5.1. 2372 * 'event action' - denotes a value for an event action as 2373 defined in Section 4.5. 2375 * 'domain variant relation' - denotes a relationship between a 2376 domain and a domain variant as defined in Section 5.3. 2378 3. Description - a one or two sentence description regarding the 2379 meaning of the value, how it might be used, and/or how it should 2380 be interpreted by clients. 2382 4. Registrant Name - the name of the person registering the value. 2384 5. Registrant Contact Information - an email address, postal 2385 address, or some other information to be used to contact the 2386 registrant. 2388 This registry is to be operated under the "Expert Review" policy 2389 defined in [RFC5226]. 2391 Review of registrations into this registry by the designated 2392 expert(s) should be narrowly judged on the following criteria: 2394 1. Values in need of being placed into multiple types must be 2395 assigned a separate registration for each type. 2397 2. Values must be strings. They should be multiple words separated 2398 by single space characters. Every character should be 2399 lowercased. If possible, every word should be given in English 2400 and each character should be US ASCII. 2402 3. Registrations should not duplicate the meaning of any existing 2403 registration. That is, if a request for a registration is 2404 significantly similar in nature to an existing registration, the 2405 request should be denied. For example, the terms 'maintainer' 2406 and 'registrant' are significantly similar in nature as they both 2407 denote a holder of a domain name or Internet number resource. In 2408 cases where it may be reasonably argued that machine 2409 interpretation of two similar values may alter the operation of 2410 client software, designated experts should not judge the values 2411 to be of significant similarity. 2413 4. Registrations should be relevant to the common usages of RDAP. 2414 Designated experts may rely upon the serving of the value by a 2415 DNR or RIR to make this determination. 2417 The following sections provide initial registrations into this 2418 registry. 2420 10.2.1. Notice and Remark Types 2422 This section registers the following values into the RDAP JSON Values 2423 Registry: 2425 1. 2427 * Value: result set truncated due to authorization 2429 * Type: notice and remark type 2431 * Description: The list of results does not contain all results 2432 due to lack of authorization. This may indicate to some 2433 clients that proper authorization will yield a longer result 2434 set. 2436 * Registrant Name: IESG 2438 * Registrant Contact Information: iesg@ietf.org 2440 2. 2442 * Value: result set truncated due to excessive load 2444 * Type: notice and remark type 2446 * Description: The list of results does not contain all results 2447 due to excessively heavy load on the server. This may 2448 indicate to some clients that requerying at a later time will 2449 yield a longer result set. 2451 * Registrant Name: IESG 2453 * Registrant Contact Information: iesg@ietf.org 2455 3. 2457 * Value: result set truncated due to unexplainable reasons 2459 * Type: notice and remark type 2461 * Description: The list of results does not contain all results 2462 for an unexplainable reason. This may indicate to some 2463 clients that requerying for any reason will not yield a longer 2464 result set. 2466 * Registrant Name: IESG 2468 * Registrant Contact Information: iesg@ietf.org 2470 4. 2472 * Value: object truncated due to authorization 2474 * Type: notice and remark type 2476 * Description: The object does not contain all data due to lack 2477 of authorization. 2479 * Registrant Name: IESG 2481 * Registrant Contact Information: iesg@ietf.org 2483 5. 2485 * Value: object truncated due to excessive load 2487 * Type: notice and remark type 2488 * Description: The object does not contain all data due to 2489 excessively heavy load on the server. This may indicate to 2490 some clients that requerying at a later time will yield all 2491 data of the object. 2493 * Registrant Name: IESG 2495 * Registrant Contact Information: iesg@ietf.org 2497 6. 2499 * Value: object truncated due to unexplainable reasons 2501 * Type: notice and remark type 2503 * Description: The object does not contain all data for an 2504 unexplainable reason. 2506 * Registrant Name: IESG 2508 * Registrant Contact Information: iesg@ietf.org 2510 10.2.2. Status 2512 This section registers the following values into the RDAP JSON Values 2513 Registry: 2515 1. 2517 * Value: validated 2519 * Type: status 2521 * Description: Signifies that the data of the object instance 2522 has been found to be accurate. This type of status is 2523 usually found on entity object instances to note the validity 2524 of identifying contact information. 2526 * Registrant Name: IESG 2528 * Registrant Contact Information: iesg@ietf.org 2530 2. 2532 * Value: renew prohibited 2534 * Type: status 2535 * Description: Renewal or reregistration of the object instance 2536 is forbidden. 2538 * Registrant Name: IESG 2540 * Registrant Contact Information: iesg@ietf.org 2542 3. 2544 * Value: update prohibited 2546 * Type: status 2548 * Description: Updates to the object instance are forbidden. 2550 * Registrant Name: IESG 2552 * Registrant Contact Information: iesg@ietf.org 2554 4. 2556 * Value: transfer prohibited 2558 * Type: status 2560 * Description: Transfers of the registration from one registrar 2561 to another are forbidden. This type of status normally 2562 applies to DNR domain names. 2564 * Registrant Name: IESG 2566 * Registrant Contact Information: iesg@ietf.org 2568 5. 2570 * Value: delete prohibited 2572 * Type: status 2574 * Description: Deletion of the registration of the object 2575 instance is forbidden. This type of status normally applies 2576 to DNR domain names. 2578 * Registrant Name: IESG 2580 * Registrant Contact Information: iesg@ietf.org 2582 6. 2584 * Value: proxy 2586 * Type: status 2588 * Description: The registration of the object instance has been 2589 performed by a third party. This is most commonly applied to 2590 entities. 2592 * Registrant Name: IESG 2594 * Registrant Contact Information: iesg@ietf.org 2596 7. 2598 * Value: private 2600 * Type: status 2602 * Description: The information of the object instance is not 2603 designated for public consumption. This is most commonly 2604 applied to entities. 2606 * Registrant Name: IESG 2608 * Registrant Contact Information: iesg@ietf.org 2610 8. 2612 * Value: redacted 2614 * Type: status 2616 * Description: Some of the information of the object instance 2617 has not been made available. This is most commonly applied 2618 to entities. 2620 * Registrant Name: IESG 2622 * Registrant Contact Information: iesg@ietf.org 2624 9. 2626 * Value: obscured 2628 * Type: status 2630 * Description: Some of the information of the object instance 2631 has been altered for the purposes of not readily revealing 2632 the actual information of the object instance. This is most 2633 commonly applied to entities. 2635 * Registrant Name: IESG 2637 * Registrant Contact Information: iesg@ietf.org 2639 10. 2641 * Value: associated 2643 * Type: status 2645 * Description: The object instance is associated with other 2646 object instances in the registry. This is most commonly used 2647 to signify that a nameserver is associated with a domain or 2648 that an entity is associated with a network resource or 2649 domain. 2651 * Registrant Name: IESG 2653 * Registrant Contact Information: iesg@ietf.org 2655 11. 2657 * Value: active 2659 * Type: status 2661 * Description: The object instance is in use. For domain 2662 names, it signifies that the domain name is published in DNS. 2663 For network and autnum registrations it signifies that they 2664 are allocated or assigned for use in operational networks. 2665 This maps to the Extensible Provisioning Protocol (EPP) 2666 [RFC5730] 'OK' status. 2668 * Registrant Name: IESG 2670 * Registrant Contact Information: iesg@ietf.org 2672 12. 2674 * Value: inactive 2676 * Type: status 2678 * Description: The object instance is not in use. See 2679 'active'. 2681 * Registrant Name: IESG 2683 * Registrant Contact Information: iesg@ietf.org 2685 13. 2687 * Value: locked 2689 * Type: status 2691 * Description: Changes to the object instance cannot be made, 2692 including the association of other object instances. 2694 * Registrant Name: IESG 2696 * Registrant Contact Information: iesg@ietf.org 2698 14. 2700 * Value: pending create 2702 * Type: status 2704 * Description: A request has been received for the creation of 2705 the object instance but this action is not yet complete. 2707 * Registrant Name: IESG 2709 * Registrant Contact Information: iesg@ietf.org 2711 15. 2713 * Value: pending renew 2715 * Type: status 2717 * Description: A request has been received for the renewal of 2718 the object instance but this action is not yet complete. 2720 * Registrant Name: IESG 2722 * Registrant Contact Information: iesg@ietf.org 2724 16. 2726 * Value: pending transfer 2728 * Type: status 2729 * Description: A request has been received for the transfer of 2730 the object instance but this action is not yet complete. 2732 * Registrant Name: IESG 2734 * Registrant Contact Information: iesg@ietf.org 2736 17. 2738 * Value: pending update 2740 * Type: status 2742 * Description: A request has been received for the update or 2743 modification of the object instance but this action is not 2744 yet complete. 2746 * Registrant Name: IESG 2748 * Registrant Contact Information: iesg@ietf.org 2750 18. 2752 * Value: pending delete 2754 * Type: status 2756 * Description: A request has been received for the deletion or 2757 removal of the object instance but this action is not yet 2758 complete. For domains, this might mean that the name is no 2759 longer published in DNS but has not yet been purged from the 2760 registry database. 2762 * Registrant Name: IESG 2764 * Registrant Contact Information: iesg@ietf.org 2766 10.2.3. Event Actions 2768 This section registers the following values into the RDAP JSON Values 2769 Registry: 2771 1. 2773 * Value: registration 2775 * Type: event action 2776 * Description: The object instance was initially registered. 2778 * Registrant Name: IESG 2780 * Registrant Contact Information: iesg@ietf.org 2782 2. 2784 * Value: reregistration 2786 * Type: event action 2788 * Description: The object instance was registered subsequently 2789 to initial registration. 2791 * Registrant Name: IESG 2793 * Registrant Contact Information: iesg@ietf.org 2795 3. 2797 * Value: last changed 2799 * Type: event action 2801 * Description: An action noting when the information in the 2802 object instance was last changed. 2804 * Registrant Name: IESG 2806 * Registrant Contact Information: iesg@ietf.org 2808 4. 2810 * Value: expiration 2812 * Type: event action 2814 * Description: The object instance has been removed or will be 2815 removed at a pre-determined date and time from the registry. 2817 * Registrant Name: IESG 2819 * Registrant Contact Information: iesg@ietf.org 2821 5. 2823 * Value: deletion 2824 * Type: event action 2826 * Description: The object instance was removed from the registry 2827 at a point in time that was not pre-determined. 2829 * Registrant Name: IESG 2831 * Registrant Contact Information: iesg@ietf.org 2833 6. 2835 * Value: reinstantiation 2837 * Type: event action 2839 * Description: The object instance was reregistered after having 2840 been removed from the registry. 2842 * Registrant Name: IESG 2844 * Registrant Contact Information: iesg@ietf.org 2846 7. 2848 * Value: transfer 2850 * Type: event action 2852 * Description: The object instance was transferred from one 2853 registrant to another. 2855 * Registrant Name: IESG 2857 * Registrant Contact Information: iesg@ietf.org 2859 8. 2861 * Value: locked 2863 * Type: event action 2865 * Description: The object instance was locked (see the 'locked' 2866 status). 2868 * Registrant Name: IESG 2870 * Registrant Contact Information: iesg@ietf.org 2872 9. 2874 * Value: unlocked 2876 * Type: event action 2878 * Description: The object instance was unlocked (see the 2879 'locked' status). 2881 * Registrant Name: IESG 2883 * Registrant Contact Information: iesg@ietf.org 2885 10.2.4. Roles 2887 This section registers the following values into the RDAP JSON Values 2888 Registry: 2890 1. 2892 * Value: registrant 2894 * Type: role 2896 * Description: The entity object instance is the registrant of 2897 the registration. In some registries, this is known as a 2898 maintainer. 2900 * Registrant Name: IESG 2902 * Registrant Contact Information: iesg@ietf.org 2904 2. 2906 * Value: technical 2908 * Type: role 2910 * Description: The entity object instance is a technical 2911 contact for the registration. 2913 * Registrant Name: IESG 2915 * Registrant Contact Information: iesg@ietf.org 2917 3. 2919 * Value: administrative 2920 * Type: role 2922 * Description: The entity object instance is an administrative 2923 contact for the registration. 2925 * Registrant Name: IESG 2927 * Registrant Contact Information: iesg@ietf.org 2929 4. 2931 * Value: abuse 2933 * Type: role 2935 * Description: The entity object instance handles network abuse 2936 issues on behalf of the registrant of the registration. 2938 * Registrant Name: IESG 2940 * Registrant Contact Information: iesg@ietf.org 2942 5. 2944 * Value: billing 2946 * Type: role 2948 * Description: The entity object instance handles payment and 2949 billing issues on behalf of the registrant of the 2950 registration. 2952 * Registrant Name: IESG 2954 * Registrant Contact Information: iesg@ietf.org 2956 6. 2958 * Value: registrar 2960 * Type: role 2962 * Description: The entity object instance represents the 2963 authority responsible for the registration in the registry. 2965 * Registrant Name: IESG 2967 * Registrant Contact Information: iesg@ietf.org 2969 7. 2971 * Value: reseller 2973 * Type: role 2975 * Description: The entity object instance represents a third 2976 party through which the registration was conducted (i.e. not 2977 the registry or registrar). 2979 * Registrant Name: IESG 2981 * Registrant Contact Information: iesg@ietf.org 2983 8. 2985 * Value: sponsor 2987 * Type: role 2989 * Description: The entity object instance represents a domain 2990 policy sponsor, such as an ICANN approved sponsor. 2992 * Registrant Name: IESG 2994 * Registrant Contact Information: iesg@ietf.org 2996 9. 2998 * Value: proxy 3000 * Type: role 3002 * Description: The entity object instance represents a proxy 3003 for another entity object, such as a registrant. 3005 * Registrant Name: IESG 3007 * Registrant Contact Information: iesg@ietf.org 3009 10. 3011 * Value: notifications 3013 * Type: role 3015 * Description: An entity object instance designated to receive 3016 notifications about association object instances. 3018 * Registrant Name: IESG 3020 * Registrant Contact Information: iesg@ietf.org 3022 11. 3024 * Value: noc 3026 * Type: role 3028 * Description: The entity object instance handles 3029 communications related to a network operations center (NOC). 3031 * Registrant Name: IESG 3033 * Registrant Contact Information: iesg@ietf.org 3035 10.2.5. Variant Relations 3037 This section registers the following values into the RDAP JSON Values 3038 Registry: 3040 1. 3042 * Value: registered 3044 * Type: domain variant relation 3046 * Description: The variant names are registered in the registry. 3048 * Registrant Name: IESG 3050 * Registrant Contact Information: iesg@ietf.org 3052 2. 3054 * Value: unregistered 3056 * Type: domain variant relation 3058 * Description: The variant names are not found in the registry. 3060 * Registrant Name: IESG 3062 * Registrant Contact Information: iesg@ietf.org 3064 3. 3066 * Value: registration restricted 3068 * Type: domain variant relation 3070 * Description: Registration of the variant names is restricted 3071 to certain parties or within certain rules. 3073 * Registrant Name: IESG 3075 * Registrant Contact Information: iesg@ietf.org 3077 4. 3079 * Value: open registration 3081 * Type: domain variant relation 3083 * Description: Registration of the variant names is available to 3084 generally qualified registrants. 3086 * Registrant Name: IESG 3088 * Registrant Contact Information: iesg@ietf.org 3090 5. 3092 * Value: conjoined 3094 * Type: domain variant relation 3096 * Description: Registration of the variant names occurs 3097 automatically with the registration of the containing domain 3098 registration. 3100 * Registrant Name: IESG 3102 * Registrant Contact Information: iesg@ietf.org 3104 11. Security Considerations 3106 This specification models information serialized in JSON format. As 3107 JSON is a subset of Javascript, implementations are advised to follow 3108 the security considerations outlined in Section 6 of [RFC7159] to 3109 prevent code injection. 3111 Though not specific to JSON, RDAP implementers should be aware of the 3112 security considerations specified in [I-D.ietf-weirds-using-http] and 3113 the security requirements and considerations in 3114 [I-D.ietf-weirds-rdap-sec]. 3116 Clients caching data, especially clients using RDAP specific caches 3117 (instead of HTTP layer caches), should have safeguards to prevent 3118 cache poisoning. See Section 5 for advice on using the "self" links 3119 for caching. 3121 Finally, service operators should be aware of the privacy mechanisms 3122 noted in Section 13. 3124 12. Internationalization Considerations 3126 12.1. Character Encoding 3128 The default text encoding for JSON responses in RDAP is UTF-8 3129 [RFC3629], and all servers and clients MUST support UTF-8. 3131 12.2. URIs and IRIs 3133 [I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in 3134 RDAP. 3136 12.3. Language Tags 3138 Section 4.4 defines the use of language tags in the JSON responses 3139 defined in this document. 3141 12.4. Internationalized Domain Names 3143 Internationalized Domain Names (IDNs) are denoted in this 3144 specification by the separation of DNS names in LDH form and Unicode 3145 form (see Section 3). Representation of IDNs in registries is 3146 described by the "variants" object in Section 5.3 and the suggested 3147 values listed in Section 10.2.5. 3149 13. Privacy Considerations 3151 This specification suggests status values to denote contact and 3152 registrant information that has been marked as private and/or has 3153 been redacted or obscured. See Section 10.2.2 for the list of status 3154 values. See Appendix A.1 on guidance to apply those values to 3155 contacts and registrants. 3157 14. Contributing Authors and Acknowledgements 3159 This document is derived from original work on RIR responses in JSON 3160 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew 3161 L. Newton. Additionally, this document incorporates work on DNR 3162 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 3163 Shen. 3165 The components of the DNR object classes are derived from a 3166 categorization of WHOIS response formats created by Ning Kong, Linlin 3167 Zhou, and Guangqing Deng, Steve Sheng and Francisco Arias, Ray 3168 Bellis, and Frederico Neves. 3170 Tom Harrison, Murray Kucherawy, Ed Lewis, Audric Schiltknecht, Naoki 3171 Kambe, and Maarten Bosteels contributed significant review comments 3172 and provided clarifying text. James Mitchell provided text regarding 3173 the processing of unknown JSON attributes and identified issues 3174 leading to the remodeling of events. Ernie Dainow and Francisco 3175 Obispo provided concrete suggestions that led to a better variant 3176 model for domain names. 3178 Ernie Dainow provided the background information on the secure DNS 3179 attributes and objects for domains, informative text on DNSSEC, and 3180 many other attributes that appear throughout the object classes of 3181 this draft. 3183 The switch to and incorporation of jCard (JSON vCard) was performed 3184 by Simon Perreault. 3186 Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working 3187 group from which this document as been created. 3189 15. References 3191 15.1. Normative References 3193 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3194 Requirement Levels", BCP 14, RFC 2119, March 1997. 3196 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 3197 Internet: Timestamps", RFC 3339, July 2002. 3199 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3200 10646", STD 63, RFC 3629, November 2003. 3202 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3203 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3204 3986, January 2005. 3206 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 3207 Rose, "Resource Records for the DNS Security Extensions", 3208 RFC 4034, March 2005. 3210 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3211 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3212 May 2008. 3214 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 3215 Autonomous System (AS) Numbers", RFC 5396, December 2008. 3217 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 3218 Languages", BCP 47, RFC 5646, September 2009. 3220 [RFC5890] Klensin, J., "Internationalized Domain Names for 3221 Applications (IDNA): Definitions and Document Framework", 3222 RFC 5890, August 2010. 3224 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3225 Address Text Representation", RFC 5952, August 2010. 3227 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3229 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 3230 January 2014. 3232 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3233 Interchange Format", RFC 7159, March 2014. 3235 [I-D.ietf-weirds-using-http] 3236 Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the 3237 Registration Data Access Protocol (RDAP)", draft-ietf- 3238 weirds-using-http-13 (work in progress), October 2014. 3240 [I-D.ietf-weirds-rdap-query] 3241 Newton, A. and S. Hollenbeck, "Registration Data Access 3242 Protocol Query Format", draft-ietf-weirds-rdap-query-15 3243 (work in progress), October 2014. 3245 [I-D.ietf-weirds-rdap-sec] 3246 Hollenbeck, S. and N. Kong, "Security Services for the 3247 Registration Data Access Protocol", draft-ietf-weirds- 3248 rdap-sec-09 (work in progress), September 2014. 3250 [ISO.3166.1988] 3251 International Organization for Standardization, "Codes for 3252 the representation of names of countries, 3rd edition", 3253 ISO Standard 3166, August 1988. 3255 15.2. Informative References 3257 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 3258 September 2004. 3260 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 3261 STD 69, RFC 5730, August 2009. 3263 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 3264 Security Extensions Mapping for the Extensible 3265 Provisioning Protocol (EPP)", RFC 5910, May 2010. 3267 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 3268 August 2011. 3270 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 3271 Structured Syntax Suffixes", RFC 6839, January 2013. 3273 [JSON_acendancy] 3274 MacVittie, , "The Stealthy Ascendancy of JSON", 04 2011. 3276 [IANA_IDNTABLES] 3277 "IANA IDN Tables", 3278 . 3280 [JSON_performance_study] 3281 Montana State University - Bozeman, Montana State 3282 University - Bozeman, Montana State University - Bozeman, 3283 and Montana State University - Bozeman, "Comparison of 3284 JSON and XML Data Interchange Formats: A Case Study", 3285 2009. 3287 Appendix A. Suggested Data Modeling with the Entity Object Class 3289 A.1. Registrants and Contacts 3291 This document does not provide specific object classes for 3292 registrants and contacts. Instead the entity object class may be 3293 used to represent a registrant or contact. When the entity object is 3294 embedded inside a containing object such as a domain name or IP 3295 network, the 'roles' string array can be used to signify the 3296 relationship. It is recommended that the values from Section 10.2.4 3297 be used. 3299 The following is an example of an elided containing object with an 3300 embedded entity that is both a registrant and administrative contact: 3302 { 3303 ... 3304 "entities" : 3305 [ 3306 { 3307 "objectClassName" : "entity", 3308 "handle" : "XXXX", 3309 "vcardArray":[ 3310 "vcard", 3311 [ 3312 ["version", {}, "text", "4.0"], 3313 ["fn", {}, "text", "Joe User"], 3314 ["kind", {}, "text", "individual"], 3315 ["lang", { 3316 "pref":"1" 3317 }, "language-tag", "fr"], 3318 ["lang", { 3319 "pref":"2" 3320 }, "language-tag", "en"], 3321 ["org", { 3322 "type":"work" 3323 }, "text", "Example"], 3324 ["title", {}, "text", "Research Scientist"], 3325 ["role", {}, "text", "Project Lead"], 3326 ["adr", 3327 { "type":"work" }, 3328 "text", 3329 [ 3330 "", 3331 "Suite 1234", 3332 "4321 Rue Somewhere", 3333 "Quebec", 3334 "QC", 3335 "G1V 2M2", 3336 "Canada" 3337 ] 3338 ], 3339 ["tel", 3340 { "type":["work", "voice"], "pref":"1" }, 3341 "uri", "tel:+1-555-555-1234;ext=102" 3342 ], 3343 ["email", 3344 { "type":"work" }, 3345 "text", "joe.user@example.com" 3346 ] 3347 ] 3348 ], 3349 "roles" : [ "registrant", "administrative" ], 3350 "remarks" : 3351 [ 3352 { 3353 "description" : 3354 [ 3355 "She sells sea shells down by the sea shore.", 3356 "Originally written by Terry Sullivan." 3357 ] 3358 } 3359 ], 3360 "events" : 3361 [ 3362 { 3363 "eventAction" : "registration", 3364 "eventDate" : "1990-12-31T23:59:59Z" 3365 }, 3366 { 3367 "eventAction" : "last changed", 3368 "eventDate" : "1991-12-31T23:59:59Z" 3369 } 3370 ] 3371 } 3372 ] 3373 } 3375 In many use cases, it is necessary to hide or obscure the information 3376 of a registrant or contact due to policy or other operational 3377 matters. Registries can denote these situations with 'status' values 3378 (see Section 10.2.2). 3380 The following is an elided example of a registrant with information 3381 changed to reflect that of a third party. 3383 { 3384 ... 3385 "entities" : 3386 [ 3387 { 3388 "objectClassName" : "entity", 3389 "handle" : "XXXX", 3390 ... 3391 "roles" : [ "registrant", "administrative" ], 3392 "status" : [ "proxy", "private", "obscured" ] 3393 } 3394 ] 3395 } 3397 A.2. Registrars 3399 This document does not provide a specific object class for 3400 registrars, but like registrants and contacts (see Appendix A.1) the 3401 'roles' string array maybe used. Additionally, many registrars have 3402 publicly assigned identifiers. The 'publicIds' structure 3403 (Section 4.8) represents that information. 3405 The following is an example of an elided containing object with an 3406 embedded entity that is a registrar: 3408 { 3409 ... 3410 "entities":[ 3411 { 3412 "objectClassName" : "entity", 3413 "handle":"XXXX", 3414 "vcardArray":[ 3415 "vcard", 3416 [ 3417 ["version", {}, "text", "4.0"], 3418 ["fn", {}, "text", "Joe's Fish, Chips and Domains"], 3419 ["kind", {}, "text", "org"], 3420 ["lang", { 3421 "pref":"1" 3422 }, "language-tag", "fr"], 3423 ["lang", { 3424 "pref":"2" 3426 }, "language-tag", "en"], 3427 ["org", { 3428 "type":"work" 3429 }, "text", "Example"], 3430 ["adr", 3431 { "type":"work" }, 3432 "text", 3433 [ 3434 "", 3435 "Suite 1234", 3436 "4321 Rue Somewhere", 3437 "Quebec", 3438 "QC", 3439 "G1V 2M2", 3440 "Canada" 3441 ] 3442 ], 3443 ["tel", 3444 { 3445 "type":["work", "voice"], 3446 "pref":"1" 3447 }, 3448 "uri", "tel:+1-555-555-1234;ext=102" 3449 ], 3450 ["email", 3451 { "type":"work" }, 3452 "text", "joes_fish_chips_and_domains@example.com" 3453 ] 3454 ] 3455 ], 3456 "roles":[ "registrar" ], 3457 "publicIds":[ 3458 { 3459 "type":"IANA Registrar ID", 3460 "identifier":"1" 3461 } 3462 ], 3463 "remarks":[ 3464 { 3465 "description":[ 3466 "She sells sea shells down by the sea shore.", 3467 "Originally written by Terry Sullivan." 3468 ] 3469 } 3470 ], 3471 "links":[ 3472 { 3473 "value":"http://example.net/entity/XXXX", 3474 "rel":"alternate", 3475 "type":"text/html", 3476 "href":"http://www.example.com" 3477 } 3478 ] 3479 } 3480 ] 3481 } 3483 Appendix B. Modeling Events 3485 Events represent actions that have taken place against a registered 3486 object at a certain date and time. Events have three properties: the 3487 action, the actor, and the date and time of the event (which is 3488 sometimes in the future). In some cases the identity of the actor is 3489 not captured. 3491 Events can be modeled in three ways: 3493 1. events with no designated actor 3495 2. events where the actor is only designated by an identifier 3497 3. events where the actor can be modeled as an entity 3499 For the first use case, the 'events' data structure (Section 4.5) is 3500 used without the 'eventActor' object member. 3502 This is an example of an "events" array without the 'eventActor'. 3504 "events" : 3505 [ 3506 { 3507 "eventAction" : "registration", 3508 "eventDate" : "1990-12-31T23:59:59Z" 3509 } 3510 ] 3512 Figure 22 3514 For the second use case, the 'events' data structure (Section 4.5) is 3515 used with the 'eventActor' object member. 3517 This is an example of an "events" array with the 'eventActor'. 3519 "events" : 3520 [ 3521 { 3522 "eventAction" : "registration", 3523 "eventActor" : "XYZ-NIC", 3524 "eventDate" : "1990-12-31T23:59:59Z" 3525 } 3526 ] 3528 Figure 23 3530 For the third use case, the 'asEventActor' array is used when an 3531 entity (Section 5.1) is embedded into another object class. The 3532 'asEventActor' array follows the same structure as the 'events' array 3533 but does not have 'eventActor' attributes. 3535 The following is an elided example of a domain object with an entity 3536 as an event actor. 3538 { 3539 "objectClassName" : "domain", 3540 "handle" : "XXXX", 3541 "ldhName" : "foo.example", 3542 "status" : [ "locked", "transfer Prohibited" ], 3543 ... 3544 "entities" : 3545 [ 3546 { 3547 "handle" : "XXXX", 3548 ... 3549 "asEventActor" : 3550 [ 3551 { 3552 "eventAction" : "last changed", 3553 "eventDate" : "1990-12-31T23:59:59Z" 3554 } 3555 ] 3556 } 3557 ] 3558 } 3560 Appendix C. Structured vs Unstructured Addresses 3562 The entity (Section 5.1) object class uses jCard [RFC7095] to 3563 represent contact information, including postal addresses. jCard has 3564 the ability to represent multiple language preferences, multiple 3565 email address and phone numbers, and multiple postal addresses in 3566 both a structured and unstructured format. This section describes 3567 the use of jCard for representing structured and unstructured 3568 addresses. 3570 The following is an example of a jCard. 3572 { 3573 "vcardArray":[ 3574 "vcard", 3575 [ 3576 ["version", {}, "text", "4.0"], 3577 ["fn", {}, "text", "Joe User"], 3578 ["n", {}, "text", 3579 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 3580 ], 3581 ["bday", {}, "date-and-or-time", "--02-03"], 3582 ["anniversary", 3583 {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" 3584 ], 3585 ["gender", {}, "text", "M"], 3586 ["kind", {}, "text", "individual"], 3587 ["lang", { 3588 "pref":"1" 3589 }, "language-tag", "fr"], 3590 ["lang", { 3591 "pref":"2" 3592 }, "language-tag", "en"], 3593 ["org", { 3594 "type":"work" 3595 }, "text", "Example"], 3596 ["title", {}, "text", "Research Scientist"], 3597 ["role", {}, "text", "Project Lead"], 3598 ["adr", 3599 { "type":"work" }, 3600 "text", 3601 [ 3602 "", 3603 "Suite 1234", 3604 "4321 Rue Somewhere", 3605 "Quebec", 3606 "QC", 3607 "G1V 2M2", 3608 "Canada" 3609 ] 3610 ], 3611 ["adr", 3612 { 3613 "type":"home", 3614 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 3615 }, 3616 "text", 3617 [ 3618 "", "", "", "", "", "", "" 3619 ] 3620 ], 3621 ["tel", 3622 { "type":["work", "voice"], "pref":"1" }, 3623 "uri", "tel:+1-555-555-1234;ext=102" 3624 ], 3625 ["tel", 3626 { 3627 "type":["work", "cell", "voice", "video", "text"] 3628 }, 3629 "uri", 3630 "tel:+1-555-555-1234" 3631 ], 3632 ["email", 3633 { "type":"work" }, 3634 "text", "joe.user@example.com" 3635 ], 3636 ["geo", { 3637 "type":"work" 3638 }, "uri", "geo:46.772673,-71.282945"], 3639 ["key", 3640 { "type":"work" }, 3641 "uri", "http://www.example.com/joe.user/joe.asc" 3642 ], 3643 ["tz", {}, 3644 "utc-offset", "-05:00"], 3645 ["url", { "type":"home" }, 3646 "uri", "http://example.org"] 3647 ] 3648 ] 3649 } 3651 Figure 24 3653 The arrays in Figure 24 with the first member of "adr" represent 3654 postal addresses. In the first example, the postal address is given 3655 as a an array of strings and constitutes a structured address. For 3656 components of the structured address that are not applicable, an 3657 empty string is given. Each member of that array aligns with the 3658 positions of a vCard as given in [RFC6350]. In this example, the 3659 following data corresponds to the following positional meanings: 3661 1. post office box - not applicable, empty string 3663 2. extended address (e.g., apartment or suite number) - Suite 1234 3665 3. street address - 4321 Rue Somewhere 3667 4. locality (e.g., city) - Quebec 3669 5. region (e.g., state or province) - QC 3671 6. postal code - G1V 2M2 3673 7. country name (full name) - Canada 3675 The second example is an unstructured address. It uses the label 3676 attribute, which is a string containing a newline (\n) character to 3677 separate address components in an unordered, unspecified manner. 3678 Note that in this example the structured address array is still given 3679 but that each string is an empty string. 3681 Appendix D. Secure DNS 3683 Section 5.3 defines the "secureDNS" member to represent secure DNS 3684 information about domain names. 3686 DNSSEC provides data integrity for DNS through digital signing of 3687 resource records. To enable DNSSEC, the zone is signed by one or 3688 more private keys and the signatures stored as RRSIG records. To 3689 complete the chain of trust in the DNS zone hierarchy, a digest of 3690 each DNSKEY record (which contains the public key) must be loaded 3691 into the parent zone, stored as Delegation Signer (DS) records and 3692 signed by the parent's private key (RRSIG DS record), "Resource 3693 Records for the DNS Security Extensions" [RFC4034]. Creating the DS 3694 records in the parent zone can be done by the registration authority, 3695 "Domain Name System (DNS) Security Extensions Mapping for the 3696 Extensible Provisioning Protocol (EPP)" [RFC5910]. 3698 Only DS related information is provided by RDAP, since other 3699 information is not generally stored in the registration database. 3701 Other DNSSEC related information can be retrieved with other DNS 3702 tools such as dig. 3704 The domain object class (Section 5.3) can represent this information 3705 using either the 'dsData' or 'keyData' object arrays. Client 3706 implementers should be aware that some registries do not collect or 3707 do not publish all of the secure DNS meta-information. 3709 Appendix E. Motivations for Using JSON 3711 This section addresses a common question regarding the use of JSON 3712 over other data formats, most notably XML. 3714 It is often pointed out that many DNRs and one RIR support the EPP 3715 [RFC5730] standard, which is an XML serialized protocol. The logic 3716 is that since EPP is a common protocol in the industry it follows 3717 that XML would be a more natural choice. While EPP does influence 3718 this specification quite a bit, EPP serves a different purpose which 3719 is the provisioning of Internet resources between registries and 3720 accredited registrars and serves a much narrower audience than that 3721 envisioned for RDAP. 3723 By contrast, RDAP has a broader audience and is designed for public 3724 consumption of data. Experience from RIRs with first generation 3725 RESTful web services for WHOIS indicate a large percentage of clients 3726 operate within browsers and other platforms where full-blown XML 3727 stacks are not readily available and where JSON is a better fit. 3729 Additionally, while EPP is used in much of the DNR community it is 3730 not a universal constant in that industry. And finally, EPP's use of 3731 XML predates the specification of JSON. If EPP had been defined 3732 today, it may very well have used JSON instead of XML. 3734 Beyond the specific DNR and RIR communities, the trend in the broader 3735 Internet industry is also switching to JSON over XML, especially in 3736 the area of RESTful web services (see [JSON_acendancy]). Studies 3737 have also found that JSON is generally less bulky and consequently 3738 faster to parse (see [JSON_performance_study]). 3740 Appendix F. Changelog 3742 [RFC Editor: Please delete this section prior to publication.] 3744 Initial -00 Adopted as working group document 2012-September-18. 3746 -01 3747 Minor spelling corrections. Changed "Registry Data" to 3748 "Registration Data" for the sake of consistency. 3750 Transitioned to RFC 5988 links and relationship types from our 3751 own custom "uris" structure. 3753 Some examples had 'status' as a string. Those have been 3754 corrected as 'status' is always an array of strings. 3756 Domain variants can now have a multi-valued relationship with 3757 domain registrations. 3759 "names" in the entity object class was changed to 3760 "entityNames". 3762 Some IP address examples change to IPv6. 3764 Change phone number examples and added reference to E.164. 3766 Added section on motivations for using JSON. 3768 Added error response body section. 3770 Added JSON naming section. 3772 Added common data structures section. 3774 Added the IANA Considerations section and the media type 3775 registration. 3777 Added 'lang' name/value. 3779 Added internationalization considerations section. 3781 -02 3783 Removed level from media type registration. 3785 Textual changes as given by Ed Lewis. 3787 Fixed object class linking example noted by Francisco Obispo 3789 Fixed a lot of other examples called out by Alex Sergeyev 3791 Added a note that JSON names are case sensitive 3793 Added 'status' to IP networks as suggested by Alex Sergeyev 3795 -03 3797 Added jCard verbiage and examples and deleted overlapping 3798 contact information and the appendix on postal addresses 3800 Removed the IANA considerations as they have been moved to 3801 another document 3803 Changed the remarks structure to be like notices 3805 Reordering and rewording some of the sections so they flow 3806 better 3808 Added note about object class "self" links 3810 Changed ipAddresses in nameserver object class to separate out 3811 v6 from v4 3813 Changed IP network version identifier from integer to string to 3814 be more consistent with ipAddresses identifier in nameserver 3815 object classes 3817 Changed DNS names to LDH names and Unicode names 3819 Modified the definition of 'conjoined' variant relationship so 3820 it was circular 3822 Added 'proxy', 'private', 'redacted', and 'obscured' status 3823 values (most useful for entities). 3825 Added a privacy considerations section 3827 Added a security considerations section 3829 Added 'reseller' and 'sponsor' to the list of entity roles 3831 Added the 'events' common data structure 3833 Added 'asEventActor' to entities 3835 Added appendix on event modeling 3837 Removed the subclasses/superclassing between RIRs/DNRs for 3838 entity and domain object classes 3840 Change suggested status/relation/etc values to be case/spacing 3841 consistent 3842 Normalized some of the definitions of object class members 3844 Modifying the JSON signaling section to reference the guidance 3845 in draft-ietf-weirds-using-http 3847 Changed the text regarding the process of unknown JSON 3848 attributes 3850 -04 3852 'description' removed from IP network and autnum because it is 3853 redundant with the remarks structure. 3855 Added 'entities' array to nameservers. 3857 Added 'status' to autnum. 3859 Added 'publicIds' to entity and domain. 3861 Added embedded entities to the entity object class. 3863 Added 'idnTable' to variants objects in domain object class. 3865 Changed the numbers for startNum and endNum in autnum to 3866 numbers instead of strings. 3868 Added an example for error response with full rdapConformance 3869 and notices. 3871 Added a section discussing help. 3873 Changed entities to use vcardArray and changed the examples to 3874 be current with jCard. 3876 Added a section on structured vs unstructured addresses. 3878 Added associated to the list of status values. 3880 Added a secure DNS section changed the 'delegationKey' object 3881 into the 'secureDNS' object. 3883 Changed the suggested values to an IANA registry. 3885 Added 'proxy' to the list of entity roles. 3887 -05 3889 Added IANA registration for RDAP JSON Media Type 3890 Added 'associated' status type. This was done earlier but got 3891 dropped during a reorganization of the document. 3893 Added the following status types: 3895 active 3897 inactive 3899 locked 3901 pending create 3903 pending renew 3905 pending update 3907 pending transfer 3909 pending delete 3911 renew prohibited 3913 Added the following event actions: 3915 locked 3917 unlocked 3919 Added the following roles: 3921 notifications 3923 noc 3925 Changed the 'tech' role to 'technical' 3927 Many document reference changes. 3929 Many examples have been fixed. 3931 Added links to dsData and keyData. 3933 Changed flags and protocols to integers in keyData. 3935 Added 'entities' to the specified list for autnum. 3937 Added SHOULD/SHOULD NOT language about using "type": 3938 "application/rdap+json" for self links. 3940 Added 'port43' to ip networks and autnum. 3942 -06 3944 Fix search response example. 3946 Change the returned search arrays to 'domainSearchResults', 3947 'entitySearchResults', and 'nameserverSearchResults'. 3949 -07 3951 'nameservers' in domain object class was changed to 3952 'nameServers' as in the example (note the camel case) 3954 fixed some example per email from James Mitchell 3956 fixed an example per email from Simon Perreault 3958 Added "network" to domain object class. 3960 Added networks and autnums to the entity object class. 3962 Created a section for "resultsTruncated". 3964 -08 3966 Added typed remarks and notices, removed "resultTruncated" in 3967 favor of them. 3969 Added "objectClassName". 3971 Changed JSON reference to RFC 7159. 3973 Removed unused references to RFC 0791, RFC 2616, RFC 4343, RFC 3974 5322. 3976 -09 3978 Fixed numerous examples. 3980 Reference to jCard updated. 3982 Text regarding JSON vCards has been changed to jCards. 3984 JSON naming rules do not apply to jCards. 3986 "nameserver" was made consistently all lower case. 3988 Links contained a "title" array, but it is now just a string 3989 per RFC 5988. 3991 Removed the term RESTful from the first section so it wouldn't 3992 have to be expanded. 3994 Added reference to RFC 2119 and noted that the uppercase form 3995 is what this document uses. 3997 Added text explaining why SHOULDs and SHOULD NOTs are to be 3998 followed. 4000 "port43" can now be either an domain name or IP address. 4002 "objectClassName" is now required. 4004 Numerous changes in prose for better readability. 4006 Updated the security considerations section to point to using- 4007 http and rdap-sec. 4009 -10 4011 Addressing many AD comments. 4013 Changed IANA registrations to IESG. 4015 'href' is now the only MUST in the a link. 4017 -11 4019 Changes to address IETF Last Call comments. 4021 Authors' Addresses 4023 Andrew Lee Newton 4024 American Registry for Internet Numbers 4025 3635 Concorde Parkway 4026 Chantilly, VA 20151 4027 US 4029 Email: andy@arin.net 4030 URI: http://www.arin.net 4031 Scott Hollenbeck 4032 Verisign Labs 4033 12061 Bluemont Way 4034 Reston, VA 20190 4035 US 4037 Email: shollenbeck@verisign.com 4038 URI: http://www.verisignlabs.com/