idnits 2.17.1 draft-ietf-weirds-json-response-09.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 -- The document date (September 23, 2014) is 3474 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) ** Downref: Normative reference to an Informational RFC: RFC 1166 ** 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-11 -- 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-13 == Outdated reference: A later version (-12) exists of draft-ietf-weirds-rdap-sec-08 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-rdap-sec' Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track S. Hollenbeck 5 Expires: March 27, 2015 Verisign Labs 6 September 23, 2014 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-weirds-json-response-09 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 March 27, 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 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 4 55 3. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 3.1. Signaling . . . . . . . . . . . . . . . . . . . . . . . . 5 57 3.2. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 4. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 7 59 5. Common Data Structures . . . . . . . . . . . . . . . . . . . 9 60 5.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 9 61 5.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 5.3. Notices And Remarks . . . . . . . . . . . . . . . . . . . 10 63 5.4. Language Identifier . . . . . . . . . . . . . . . . . . . 12 64 5.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 5.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 14 66 5.7. Port 43 WHOIS Server . . . . . . . . . . . . . . . . . . 14 67 5.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 14 68 5.9. Object Class Name . . . . . . . . . . . . . . . . . . . . 14 69 5.10. An Example . . . . . . . . . . . . . . . . . . . . . . . 15 70 6. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 17 71 6.1. The Entity Object Class . . . . . . . . . . . . . . . . . 17 72 6.2. The Nameserver Object Class . . . . . . . . . . . . . . . 24 73 6.3. The Domain Object Class . . . . . . . . . . . . . . . . . 28 74 6.4. The IP Network Object Class . . . . . . . . . . . . . . . 40 75 6.5. Autonomous System Number Entity Object Class . . . . . . 44 76 7. Error Response Body . . . . . . . . . . . . . . . . . . . . . 47 77 8. Responding to Help Queries . . . . . . . . . . . . . . . . . 49 78 9. Responding To Searches . . . . . . . . . . . . . . . . . . . 50 79 10. Indicating Truncated Responses . . . . . . . . . . . . . . . 51 80 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 81 11.1. RDAP JSON Media Type Registration . . . . . . . . . . . 54 82 11.2. JSON Values Registry . . . . . . . . . . . . . . . . . . 55 83 11.2.1. Notice and Remark Types . . . . . . . . . . . . . . 56 84 11.2.2. Status . . . . . . . . . . . . . . . . . . . . . . . 58 85 11.2.3. Event Actions . . . . . . . . . . . . . . . . . . . 63 86 11.2.4. Roles . . . . . . . . . . . . . . . . . . . . . . . 66 87 11.2.5. Variant Relations . . . . . . . . . . . . . . . . . 69 88 12. Security Considerations . . . . . . . . . . . . . . . . . . . 70 89 13. Internationalization Considerations . . . . . . . . . . . . . 71 90 13.1. Character Encoding . . . . . . . . . . . . . . . . . . . 71 91 13.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 71 92 13.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 71 93 13.4. Internationalized Domain Names . . . . . . . . . . . . . 71 94 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 71 95 15. Contributing Authors and Acknowledgements . . . . . . . . . . 71 96 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 72 97 16.1. Normative References . . . . . . . . . . . . . . . . . . 72 98 16.2. Informative References . . . . . . . . . . . . . . . . . 73 99 Appendix A. Suggested Data Modeling with the Entity Object Class 74 100 A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 74 101 A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 76 102 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 78 103 Appendix C. Structured vs Unstructured Addresses . . . . . . . . 80 104 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 83 105 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 83 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]. 115 The data model for JSON responses is specified in four sections: 117 1. simple data types conveyed in JSON strings 119 2. data structures specified as JSON arrays or objects that are used 120 repeatedly when building up larger objects 122 3. object classes representing structured data corresponding to a 123 lookup of a single object 125 4. arrays of objects representing structured data corresponding to a 126 search for multiple objects 128 5. the response to an error 130 The object classes represent responses for two major categories of 131 data: responses returned by Regional Internet Registries (RIRs) for 132 registrations data related to IP addresses, reverse DNS names, and 133 Autonomous System numbers; and responses returned by Domain Name 134 Registries (DNRs) for registration data related to forward DNS names. 135 The following object classes are served by both RIRs and DNRs: 137 1. domains 139 2. nameservers 141 3. entities 142 The information served by both RIRs and DNRs for these object classes 143 overlap extensively and are given in this document as a unified model 144 for both classes of service. 146 In addition to the object classes listed above, RIRs also serve the 147 following object classes: 149 1. IP networks 151 2. Autonomous System numbers 153 Object classes defined in this document represent a minimal set of 154 what a compliant client/server MUST understand to function correctly, 155 however some deployments may want to include additional object 156 classes to suit individual needs. Anticipating this need for 157 extension, Section 3.2 of this document defines a mechanism for 158 extending the JSON objects that are described in this document. 160 Positive responses take two forms. A response to a lookup of a 161 single object in the registration system yields a JSON object which 162 is the subject of the lookup. A response to a search for multiple 163 objects yields a JSON object that contains an array of JSON objects 164 that are the subject of the search. In each type of response, other 165 data structures are present within the topmost JSON object. 167 2. Terminology and Definitions 169 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 170 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 171 document are to be interpreted as described in RFC 2119 [RFC2119] 172 when specified in their uppercase forms. 174 The following list describes terminology and definitions used 175 throughout this document: 177 DNR: Domain Name Registry 179 LDH: Letters, Digits, Hyphen 181 member: data found within an object as defined by JSON 182 [RFC7159]. 184 object: a data structure as defined by JSON [RFC7159]. 186 object class: the definition of members that may be found in JSON 187 objects described in this document. 189 object instance: an instantiation or specific instance of an object 190 class. 192 RDAP: Registration Data Access Protocol 194 RIR: Regional Internet Registry 196 3. Use of JSON 198 3.1. Signaling 200 Media type signaling for the JSON data described in this document is 201 specified in [I-D.ietf-weirds-using-http]. 203 3.2. Naming 205 Clients processing JSON [RFC7159] responses are under no obligation 206 to process unrecognized JSON attributes but SHOULD NOT treat them as 207 an error, because servers MAY insert values signified by names into 208 the JSON responses which are not specified in this document. 209 Insertion of unspecified values into JSON responses SHOULD have names 210 prefixed with a short identifier followed by an underscore followed 211 by a meaningful name. These short identifiers aid software 212 implementers with identifying the specification of the JSON name, and 213 failure to use one could cause an implementer to assume the server is 214 erroneously serving a name from this specification. This allowance 215 does not apply to jCard ([RFC7095]) objects. The full JSON name (the 216 prefix plus the underscore plus the meaningful name) SHOULD adhere to 217 the character and name limitations of the prefix registry described 218 in [I-D.ietf-weirds-using-http]. Failure to use these limitations 219 could result in slower adoption as these limitations have been given 220 to aid some client programming models. 222 Consider the following JSON response with JSON names, 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 name 244 "lunarNic_beforeOneSmallStep" to signify registrations occurring 245 before the first moon landing and the name 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 names ignored by clients may also be used 274 for future revisions to this specification. 276 Clients processing JSON responses MUST be prepared for values 277 specified in this document to be absent from a response as no JSON 278 value listed is required to appear in a response. In other words, 279 servers MAY remove values as is needed by the policies of the server 280 operator. 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 4. 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 data types used in this 291 document derived from the JSON character string. 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 described 307 in [RFC1166]. An example of this textual 308 representation is '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 5. Common Data Structures 343 This section defines common data structures used in responses and 344 object classes. 346 5.1. RDAP Conformance 348 The first data structure is named "rdapConformance" and is simply an 349 array of strings, each providing a hint as to the specifications used 350 in the construction of the response. This data structure appears 351 only in the top most 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 SHOULD use a string 365 prefixed with the appropriate identifier from the IANA RDAP 366 Extensions registry specified in [I-D.ietf-weirds-using-http]. For 367 example, if the fictional Registry of the Moon wants to signify that 368 their JSON responses are conformant with their registered extensions, 369 the string 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 5.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 "value", "rel", and "href" JSON values MUST be specified. All other 407 JSON values are 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 5.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 6 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 11.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 5.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 11.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 5.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 5.5. Events 532 This data structure represents events that have occurred on an 533 instance of an object class (see Section 6 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 5.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. If the event actor being referenced is an RDAP 571 entity, the link reference SHOULD be made with "rel" of "related" and 572 "type" of "application/rdap+json". 574 See Section 11.2.3 for a list of values for the 'eventAction' string. 575 See Appendix B regarding the various ways events can be modeled. 577 5.6. Status 579 This data structure, named 'status', is an array of strings 580 indicating the state of a registered object (see Section 11.2.2 for a 581 list of values). 583 5.7. Port 43 WHOIS Server 585 This data structure, named 'port43', is a simple string containing 586 the fully-qualified host name or IP address of the WHOIS [RFC3912] 587 server where the containing object instance may be found. Note that 588 this is not a URI, as there is no WHOIS URI scheme. 590 5.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 5.9. Object Class Name 614 This data structure, named "objectClassName", gives the object class 615 name of a particular object as a string. This aids clients in 616 identifying the type of object being processed. Servers MUST NOT 617 omit this string so that clients can more easily identify the type of 618 object. 620 5.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 6. 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 5.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 6.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 MAY 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 Self links SHOULD contain a "type" element containing the 692 "application/rdap+json" media type when referencing RDAP object 693 instances as defined by this document. Clients SHOULD NOT assume 694 self links without this media type are represented as RDAP objects as 695 defined by this document. 697 This is an example of the "links" array with a self link to an object 698 class: 700 "links" : 701 [ 702 { 703 "value" : "http://example.com/ip/2001:db8::123", 704 "rel" : "self", 705 "href" : "http://example.com/ip/2001:db8::123", 706 "type" : "application/rdap+json" 707 } 708 ] 710 In addition to the "links" array with a self link, servers SHOULD 711 provide an "objectClassName" (see Section 5.9) string in each object. 713 6.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. For 727 illustrative purposes, it does not include rdapConformance or notices 728 data structures. 730 { 731 "objectClassName" : "entity", 732 "handle":"XXXX", 733 "vcardArray":[ 734 "vcard", 735 [ 736 ["version", {}, "text", "4.0"], 737 ["fn", {}, "text", "Joe User"], 738 ["n", {}, "text", 739 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 740 ], 741 ["bday", {}, "date-and-or-time", "--02-03"], 742 ["anniversary", 743 {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" 744 ], 745 ["gender", {}, "text", "M"], 746 ["kind", {}, "text", "individual"], 747 ["lang", { 748 "pref":"1" 749 }, "language-tag", "fr"], 750 ["lang", { 751 "pref":"2" 752 }, "language-tag", "en"], 753 ["org", { 754 "type":"work" 755 }, "text", "Example"], 756 ["title", {}, "text", "Research Scientist"], 757 ["role", {}, "text", "Project Lead"], 758 ["adr", 759 { "type":"work" }, 760 "text", 761 [ 762 "", 763 "Suite 1234", 764 "4321 Rue Somewhere", 765 "Quebec", 766 "QC", 767 "G1V 2M2", 768 "Canada" 769 ] 770 ], 771 ["adr", 772 { 773 "type":"home", 774 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 775 }, 776 "text", 777 [ 778 "", "", "", "", "", "", "" 779 ] 780 ], 781 ["tel", 782 { 783 "type":["work", "voice"], 784 "pref":"1" 785 }, 786 "uri", 787 "tel:+1-555-555-1234;ext=102" 788 ], 789 ["tel", 790 { "type":["work", "cell", "voice", "video", "text"] }, 791 "uri", 792 "tel:+1-555-555-4321" 793 ], 794 ["email", 795 { "type":"work" }, 796 "text", 797 "joe.user@example.com" 798 ], 799 ["geo", { 800 "type":"work" 801 }, "uri", "geo:46.772673,-71.282945"], 802 ["key", 803 { "type":"work" }, 804 "uri", 805 "http://www.example.com/joe.user/joe.asc" 806 ], 807 ["tz", {}, 808 "utc-offset", "-05:00"], 809 ["url", { "type":"home" }, 810 "uri", "http://example.org"] 811 ] 812 ], 813 "roles":[ "registrar" ], 814 "publicIds":[ 815 { 816 "type":"IANA Registrar ID", 817 "identifier":"1" 818 } 819 ], 820 "remarks":[ 821 { 822 "description":[ 823 "She sells sea shells down by the sea shore.", 824 "Originally written by Terry Sullivan." 825 ] 826 } 827 ], 828 "links":[ 829 { 830 "value":"http://example.com/entity/XXXX", 831 "rel":"self", 832 "href":"http://example.com/entity/XXXX", 833 "type" : "application/rdap+json" 834 } 835 ], 836 "events":[ 837 { 838 "eventAction":"registration", 839 "eventDate":"1990-12-31T23:59:59Z" 840 } 841 ], 842 "asEventActor":[ 843 { 844 "eventAction":"last changed", 845 "eventDate":"1991-12-31T23:59:59Z" 846 } 847 ] 848 } 850 Entities may also have other entities embedded with them in an array. 851 This can be used to model an organization with specific individuals 852 fulfilling designated roles of responsibility. 854 The following is an elided example of an entity with embedded 855 entities. 857 { 858 "objectClassName" : "entity", 859 "handle" : "ANENTITY", 860 "roles" : [ "registrar" ], 861 ... 862 "entities" : 863 [ 864 { 865 "objectClassName" : "entity", 866 "handle": "ANEMBEDDEDENTITY", 867 "roles" : [ "technical" ], 868 ... 869 }, 870 ... 871 ], 872 ... 873 } 875 Figure 13 877 This object has the following members: 879 o objectClassName -- the string "entity" 881 o handle -- a string representing an registry unique identifier of 882 the entity 884 o vcardArray -- a JSON vCard with the entity's contact information 886 o roles -- an array of strings, each signifying the relationship an 887 object would have with its closest containing object (see 888 Section 11.2.4 for a list of values) 890 o publicIds - see Section 5.8 892 o entities - an array of entity objects as defined by this section. 894 o remarks -- see Section 5.3 896 o links -- see Section 5.2 898 o events -- see Section 5.5 899 o asEventActor -- this data structure takes the same form as the 900 'events' data structure (see Section 5.5), but each object in the 901 array MUST NOT have an 'eventActor' member. These objects denote 902 that the entity is an event actor for the given events. See 903 Appendix B regarding the various ways events can be modeled. 905 o status -- see Section 5.6 907 o port43 -- see Section 5.7 909 o networks -- an array of IP network objects as defined in 910 Section 6.4 912 o autnums -- an array of autnum objects as defined in Section 6.5 914 The following is an example of a entity that might be served by a 915 DNR. For illustrative purposes, it does not include rdapConformance 916 or notices data structures. 918 { 919 "objectClassName" : "entity", 920 "handle":"XXXX", 921 "vcardArray":[ 922 "vcard", 923 [ 924 ["version", {}, "text", "4.0"], 925 ["fn", {}, "text", "Joe User"], 926 ["kind", {}, "text", "individual"], 927 ["lang", { 928 "pref":"1" 929 }, "language-tag", "fr"], 930 ["lang", { 931 "pref":"2" 932 }, "language-tag", "en"], 933 ["org", { 934 "type":"work" 935 }, "text", "Example"], 936 ["title", {}, "text", "Research Scientist"], 937 ["role", {}, "text", "Project Lead"], 938 ["adr", 939 { "type":"work" }, 940 "text", 941 [ 942 "", 943 "Suite 1234", 944 "4321 Rue Somewhere", 945 "Quebec", 946 "QC", 947 "G1V 2M2", 948 "Canada" 949 ] 950 ], 951 ["tel", 952 { "type":["work", "voice"], "pref":"1" }, 953 "uri", "tel:+1-555-555-1234;ext=102" 954 ], 955 ["email", 956 { "type":"work" }, 957 "text", "joe.user@example.com" 958 ], 959 ] 960 ], 961 "status":[ "validated", "locked" ], 962 "remarks":[ 963 { 964 "description":[ 965 "She sells sea shells down by the sea shore.", 966 "Originally written by Terry Sullivan." 967 ] 968 } 969 ], 970 "links":[ 971 { 972 "value":"http://example.com/entity/XXXX", 973 "rel":"self", 974 "href":"http://example.com/entity/XXXX", 975 "type":"application/rdap+json" 976 } 977 ], 978 "port43":"whois.example.net", 979 "events":[ 980 { 981 "eventAction":"registration", 982 "eventDate":"1990-12-31T23:59:59Z" 983 }, 984 { 985 "eventAction":"last changed", 986 "eventDate":"1991-12-31T23:59:59Z", 987 "eventActor":"joe@example.com" 988 } 989 ] 990 } 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 6.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. For illustrative 1006 purposes, it does not include rdapConformance or notices data 1007 structures. 1009 { 1010 "objectClassName" : "nameserver", 1011 "handle" : "XXXX", 1012 "ldhName" : "ns1.xn--fo-5ja.example", 1013 "unicodeName" : "ns1.foo.example", 1014 "status" : [ "active" ], 1015 "ipAddresses" : 1016 { 1017 "v4": [ "192.0.2.1", "192.0.2.2" ], 1018 "v6": [ "2001:db8::123" ] 1019 }, 1020 "remarks" : 1021 [ 1022 { 1023 "description" : 1024 [ 1025 "She sells sea shells down by the sea shore.", 1026 "Originally written by Terry Sullivan." 1027 ] 1028 } 1029 ], 1030 "links" : 1031 [ 1032 { 1033 "value" : "http://example.net/nameserver/xxxx", 1034 "rel" : "self", 1035 "href" : "http://example.net/nameserver/xxxx", 1036 "type" : "application/rdap+json" 1037 } 1038 ], 1039 "port43" : "whois.example.net", 1040 "events" : 1041 [ 1042 { 1043 "eventAction" : "registration", 1044 "eventDate" : "1990-12-31T23:59:59Z" 1045 }, 1046 { 1047 "eventAction" : "last changed", 1048 "eventDate" : "1991-12-31T23:59:59Z", 1049 "eventActor" : "joe@example.com" 1050 } 1051 ] 1052 } 1054 Figure 14 1056 Figure 14 is an example of a nameserver object with all values given. 1057 Registries using a first-class nameserver data model would embed this 1058 in domain objects as well as allowing references to it with the 1059 "/nameserver" query type (all depending on the registry operators 1060 policy). Other registries may pare back the information as needed. 1061 Figure 15 is an example of a nameserver object as would be found in 1062 RIRs and some DNRs, while Figure 16 is an example of a nameserver 1063 object as would be found in other DNRs. 1065 The following is an example of the simplest nameserver object: 1067 { 1068 "objectClassName" : "nameserver", 1069 "ldhName" : "ns1.example.com" 1070 } 1072 Figure 15 1074 The following is an example of a simple nameserver object that might 1075 be commonly used by DNRs: 1077 { 1078 "objectClassName" : "nameserver", 1079 "ldhName" : "ns1.example.com", 1080 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 1081 } 1083 Figure 16 1085 As nameservers can be modeled by some registries to be first-class 1086 objects, they may also have an array of entities (Section 6.1) 1087 embedded to signify parties responsible for the maintenance, 1088 registrations, etc. of the nameservers. 1090 The following is an elided example of a nameserver with embedded 1091 entities. 1093 { 1094 "objectClassName", "nameserver", 1095 "handle" : "XXXX", 1096 "ldhName" : "ns1.xn--fo-5ja.example", 1097 ... 1098 "entities" : 1099 [ 1100 ... 1101 ], 1102 ... 1103 } 1105 Figure 17 1107 The nameserver object class has the following members: 1109 o objectClassName - the string "nameserver" 1111 o handle -- a string representing an registry unique identifier of 1112 the nameserver 1114 o ldhName -- a string containing the LDH name of the nameserver (see 1115 Section 4) 1117 o unicodeName -- a string containing a DNS Unicode name of the 1118 nameserver (see Section 4) 1120 o ipAddresses -- an object containing the following members: 1122 * v6 -- an array of strings containing IPv6 addresses of the 1123 nameserver 1125 * v4 -- an array of strings containing IPv4 addresses of the 1126 nameserver 1128 o entities -- an array of entity objects as defined by Section 6.1. 1130 o status - see Section 5.6 1132 o remarks - see Section 5.3 1134 o links - see Section 5.2 1135 o port43 - see Section 5.7 1137 o events - see Section 5.5 1139 6.3. The Domain Object Class 1141 The domain object class represents a DNS name and point of 1142 delegation. For RIRs these delegation points are in the reverse DNS 1143 tree, whereas for DNRs these delegation points are in the forward DNS 1144 tree. 1146 In both cases, the high level structure of the domain object class 1147 consists of information about the domain registration, nameserver 1148 information related to the domain name, and entities related to the 1149 domain name (e.g. registrant information, contacts, etc.). 1151 The following is an elided example of the domain object showing the 1152 high level structure: 1154 { 1155 "objectClassName" : "domain", 1156 "handle" : "XXX", 1157 "ldhName" : "blah.example.com", 1158 ... 1159 "nameservers" : 1160 [ 1161 ... 1162 ], 1163 ... 1164 "entities" : 1165 [ 1166 ... 1167 ] 1168 } 1170 The following is a description of the members of this object: 1172 o objectClassName -- the string "domain" 1174 o handle -- a string representing a registry unique identifier of 1175 the domain object instance 1177 o ldhName -- a string describing a domain name in LDH form as 1178 described in Section 4 1180 o unicodeName -- a string containing a domain name with U-labels as 1181 described in Section 4 1183 o variants -- an array of objects, each containing the following 1184 values: 1186 * relation -- an array of strings, with each string denoting the 1187 relationship between the variants and the containing domain 1188 object (see Section 11.2.5 for a list of suggested variant 1189 relations). 1191 * idnTable -- the name of the IDN table of codepoints, such as 1192 one listed with the IANA (see IDN tables [IANA_IDNTABLES]). 1194 * variantNames -- an array of objects, with each object 1195 containing an "ldhName" member and a "unicodeName" member (see 1196 Section 4). 1198 o nameservers -- an array of nameserver objects as defined by 1199 Section 6.2 1201 o secureDNS -- an object with the following members: 1203 * zoneSigned -- true if the zone has been signed, false 1204 otherwise. 1206 * delegationSigned -- boolean true if there are DS records in the 1207 parent, false otherwise. 1209 * maxSigLife -- an integer representing the signature life time 1210 in seconds to be used when creating the RRSIG DS record in the 1211 parent zone [RFC5910]. 1213 * dsData - an array of objects, each with the following members: 1215 + keyTag -- an integer as specified by the key tag field of a 1216 DNS DS record as specified by RFC 4034 [RFC4034] in 1217 presentation format 1219 + algorithm -- an integer as specified by the algorithm field 1220 of a DNS DS record as described by RFC 4034 in presentation 1221 format 1223 + digest -- a string as specified by the digest field of a DNS 1224 DS record as specified by RFC 4034 in presentation format 1226 + digestType -- an integer as specified by the digest type 1227 field of a DNS DS record as specified by RFC 4034 in 1228 presentation format 1230 + events - see Section 5.5 1232 + links - see Section 5.2 1234 * keyData - an array of objects, each with the following members: 1236 + flags -- an integer representing the flags field value in 1237 the DNSKEY record [RFC4034] in presentation format 1239 + protocol - an integer representation of the protocol field 1240 value of the DNSKEY record [RFC4034] in presentation format 1242 + publicKey - a string representation of the public key in the 1243 DNSKEY record [RFC4034] in presentation format 1245 + algorithm -- an integer as specified by the algorithm field 1246 of a DNSKEY record as specified by RFC 4034 [RFC4034] in 1247 presentation format 1249 + events - see Section 5.5 1251 + links - see Section 5.2 1253 See Appendix D for background information on these objects. 1255 o entities -- an array of entity objects as defined by Section 6.1. 1257 o status - see Section 5.6 1259 o publicIds - see Section 5.8 1261 o remarks - see Section 5.3 1263 o links - see Section 5.2 1265 o port43 - see Section 5.7 1267 o events - see Section 5.5 1269 o network - represents the IP network for which a reverse DNS domain 1270 is referenced. See Section 6.4 1272 The following is an example of a JSON domain object representing a 1273 reverse DNS delegation point that might be served by an RIR. For 1274 illustrative purposes, it does not include rdapConformance or notices 1275 data structures. 1277 { 1278 "objectClassName" : "domain", 1279 "handle" : "XXXX", 1280 "ldhName" : "0.2.192.in-addr.arpa", 1281 "nameservers" : 1282 [ 1283 { 1284 "objectClassName" : "nameserver", 1285 "ldhName" : "ns1.rir.example" 1286 }, 1287 { 1288 "objectClassName" : "nameserver", 1289 "ldhName" : "ns2.rir.example" 1290 } 1291 ], 1292 "secureDNS": 1293 { 1294 "delegationSigned": true, 1295 "dsData": 1296 [ 1297 { 1298 "keyTag": 12345, 1299 "algorithm": 3, 1300 "digestType": 1, 1301 "digest": "49FD46E6C4B45C55D4AC" 1302 } 1303 ] 1304 }, 1305 "remarks" : 1306 [ 1307 { 1308 "description" : 1309 [ 1310 "She sells sea shells down by the sea shore.", 1311 "Originally written by Terry Sullivan." 1312 ] 1313 } 1314 ], 1315 "links" : 1316 [ 1317 { 1318 "value": "http://example.net/domain/XXXX", 1319 "rel" : "self", 1320 "href" : "http://example.net/domain/XXXXX", 1321 "type" : "application/rdap+json" 1322 } 1323 ], 1324 "events" : 1325 [ 1326 { 1327 "eventAction" : "registration", 1328 "eventDate" : "1990-12-31T23:59:59Z" 1329 }, 1330 { 1331 "eventAction" : "last changed", 1332 "eventDate" : "1991-12-31T23:59:59Z", 1333 "eventActor" : "joe@example.com" 1334 } 1335 ], 1336 "entities" : 1337 [ 1338 { 1339 "objectClassName" : "entity", 1340 "handle" : "XXXX", 1341 "vcardArray":[ 1342 "vcard", 1343 [ 1344 ["version", {}, "text", "4.0"], 1345 ["fn", {}, "text", "Joe User"], 1346 ["kind", {}, "text", "individual"], 1347 ["lang", { 1348 "pref":"1" 1349 }, "language-tag", "fr"], 1350 ["lang", { 1351 "pref":"2" 1352 }, "language-tag", "en"], 1353 ["org", { 1354 "type":"work" 1355 }, "text", "Example"], 1356 ["title", {}, "text", "Research Scientist"], 1357 ["role", {}, "text", "Project Lead"], 1358 ["adr", 1359 { "type":"work" }, 1360 "text", 1361 [ 1362 "", 1363 "Suite 1234", 1364 "4321 Rue Somewhere", 1365 "Quebec", 1366 "QC", 1367 "G1V 2M2", 1368 "Canada" 1370 ] 1371 ], 1372 ["tel", 1373 { "type":["work", "voice"], "pref":"1" }, 1374 "uri", "tel:+1-555-555-1234;ext=102" 1375 ], 1376 ["email", 1377 { "type":"work" }, 1378 "text", "joe.user@example.com" 1379 ], 1380 ] 1381 ], 1382 "roles" : [ "registrant" ], 1383 "remarks" : 1384 [ 1385 { 1386 "description" : 1387 [ 1388 "She sells sea shells down by the sea shore.", 1389 "Originally written by Terry Sullivan." 1390 ] 1391 } 1392 ], 1393 "links" : 1394 [ 1395 { 1396 "value": "http://example.net/entity/xxxx", 1397 "rel" : "self", 1398 "href" : "http://example.net/entity/xxxx", 1399 "type" : "application/rdap+json" 1400 } 1401 ], 1402 "events" : 1403 [ 1404 { 1405 "eventAction" : "registration", 1406 "eventDate" : "1990-12-31T23:59:59Z" 1407 }, 1408 { 1409 "eventAction" : "last changed", 1410 "eventDate" : "1991-12-31T23:59:59Z", 1411 "eventActor" : "joe@example.com" 1412 } 1413 ] 1414 } 1415 ], 1416 "network" : 1417 { 1418 "objectClassName" : "ip network", 1419 "handle" : "XXXX-RIR", 1420 "startAddress" : "192.0.2.0", 1421 "endAddress" : "192.0.2.255", 1422 "ipVersion" : "v6", 1423 "name": "NET-RTR-1", 1424 "type" : "DIRECT ALLOCATION", 1425 "country" : "AU", 1426 "parentHandle" : "YYYY-RIR", 1427 "status" : [ "active" ] 1428 } 1429 } 1431 The following is an example of a JSON domain object representing a 1432 forward DNS delegation point that might be served by a DNR. For 1433 illustrative purposes, it does not include rdapConformance or notices 1434 data structures. 1436 { 1437 "objectClassName" : "domain", 1438 "handle" : "XXXX", 1439 "ldhName" : "xn--fo-5ja.example", 1440 "unicodeName" : "foo.example", 1441 "variants" : 1442 [ 1443 { 1444 "relation" : [ "registered", "conjoined" ], 1445 "variantNames" : 1446 [ 1447 { 1448 "ldhName" : "xn--fo-cka.example", 1449 "unicodeName" : "foo.example" 1450 }, 1451 { 1452 "ldhName" : "xn--fo-fka.example", 1453 "unicodeName" : "foeo.example" 1454 } 1455 ] 1456 }, 1457 { 1458 "relation" : [ "unregistered", "registration restricted" ], 1459 "idnTable": ".EXAMPLE Swedish", 1460 "variantNames" : 1461 [ 1462 { 1463 "ldhName": "xn--fo-8ja.example", 1464 "unicodeName" : "foo.example" 1465 } 1466 ] 1467 } 1468 ], 1469 "status" : [ "locked", "transfer prohibited" ], 1470 "publicIds":[ 1471 { 1472 "type":"ENS_Auth ID", 1473 "identifier":"1234567890" 1474 } 1475 ], 1476 "nameservers" : 1477 [ 1478 { 1479 "objectClassName" : "nameserver", 1480 "handle" : "XXXX", 1481 "ldhName" : "ns1.example.com", 1482 "status" : [ "active" ], 1483 "ipAddresses" : 1484 { 1485 "v6": [ "2001:db8::123", "2001:db8::124" ], 1486 "v4": [ "192.0.2.1", "192.0.2.2" ] 1487 }, 1488 "remarks" : 1489 [ 1490 { 1491 "description" : 1492 [ 1493 "She sells sea shells down by the sea shore.", 1494 "Originally written by Terry Sullivan." 1495 ] 1496 } 1497 ], 1498 "links" : 1499 [ 1500 { 1501 "value" : "http://example.net/nameserver/XXXX", 1502 "rel" : "self", 1503 "href" : "http://example.net/nameserver/XXXX", 1504 "type" : "application/rdap+json" 1505 } 1506 ], 1507 "events" : 1508 [ 1509 { 1510 "eventAction" : "registration", 1511 "eventDate" : "1990-12-31T23:59:59Z" 1513 }, 1514 { 1515 "eventAction" : "last changed", 1516 "eventDate" : "1991-12-31T23:59:59Z" 1517 } 1518 ] 1519 }, 1520 { 1521 "objectClassName" : "nameserver", 1522 "handle" : "XXXX", 1523 "ldhName" : "ns2.example.com", 1524 "status" : [ "active" ], 1525 "ipAddresses" : 1526 { 1527 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1528 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1529 }, 1530 "remarks" : 1531 [ 1532 { 1533 "description" : 1534 [ 1535 "She sells sea shells down by the sea shore.", 1536 "Originally written by Terry Sullivan." 1537 ] 1538 } 1539 ], 1540 "links" : 1541 [ 1542 { 1543 "value" : "http://example.net/nameserver/XXXX", 1544 "rel" : "self", 1545 "href" : "http://example.net/nameserver/XXXX", 1546 "type" : "application/rdap+json" 1547 } 1548 ], 1549 "events" : 1550 [ 1551 { 1552 "eventAction" : "registration", 1553 "eventDate" : "1990-12-31T23:59:59Z" 1554 }, 1555 { 1556 "eventAction" : "last changed", 1557 "eventDate" : "1991-12-31T23:59:59Z" 1558 } 1559 ] 1560 } 1562 ], 1563 "secureDNS": 1564 { 1565 "zoneSigned": true, 1566 "delegationSigned": true, 1567 "maxSigLife": 604800, 1568 "keyData": 1569 [ 1570 { 1571 "flags": 257, 1572 "protocol": 3, 1573 "algorithm": 1, 1574 "publicKey": "AQPJ////4Q==", 1575 "events": 1576 [ 1577 { 1578 "eventAction": "last changed", 1579 "eventDate": "2012-07-23T05:15:47Z" 1580 } 1581 ] 1582 } 1583 ] 1584 }, 1585 "remarks" : 1586 [ 1587 { 1588 "description" : 1589 [ 1590 "She sells sea shells down by the sea shore.", 1591 "Originally written by Terry Sullivan." 1592 ] 1593 } 1594 ], 1595 "links" : 1596 [ 1597 { 1598 "value": "http://example.net/domain/XXXX", 1599 "rel" : "self", 1600 "href" : "http://example.net/domain/XXXX", 1601 "type" : "application/rdap+json" 1602 } 1603 ], 1604 "port43" : "whois.example.net", 1605 "events" : 1606 [ 1607 { 1608 "eventAction" : "registration", 1609 "eventDate" : "1990-12-31T23:59:59Z" 1611 }, 1612 { 1613 "eventAction" : "last changed", 1614 "eventDate" : "1991-12-31T23:59:59Z", 1615 "eventActor" : "joe@example.com" 1616 }, 1617 { 1618 "eventAction" : "transfer", 1619 "eventDate" : "1991-12-31T23:59:59Z", 1620 "eventActor" : "joe@example.com" 1621 }, 1622 { 1623 "eventAction" : "expiration", 1624 "eventDate" : "2016-12-31T23:59:59Z", 1625 "eventActor" : "joe@example.com" 1626 } 1627 ], 1628 "entities" : 1629 [ 1630 { 1631 "objectClassName" : "entity", 1632 "handle" : "XXXX", 1633 "vcardArray":[ 1634 "vcard", 1635 [ 1636 ["version", {}, "text", "4.0"], 1637 ["fn", {}, "text", "Joe User"], 1638 ["kind", {}, "text", "individual"], 1639 ["lang", { 1640 "pref":"1" 1641 }, "language-tag", "fr"], 1642 ["lang", { 1643 "pref":"2" 1644 }, "language-tag", "en"], 1645 ["org", { 1646 "type":"work" 1647 }, "text", "Example"], 1648 ["title", {}, "text", "Research Scientist"], 1649 ["role", {}, "text", "Project Lead"], 1650 ["adr", 1651 { "type":"work" }, 1652 "text", 1653 [ 1654 "", 1655 "Suite 1234", 1656 "4321 Rue Somewhere", 1657 "Quebec", 1658 "QC", 1659 "G1V 2M2", 1660 "Canada" 1661 ] 1662 ], 1663 ["tel", 1664 { "type":["work", "voice"], "pref":"1" }, 1665 "uri", "tel:+1-555-555-1234;ext=102" 1666 ], 1667 ["email", 1668 { "type":"work" }, 1669 "text", "joe.user@example.com" 1670 ], 1671 ] 1672 ], 1673 "status" : [ "validated", "locked" ], 1674 "roles" : [ "registrant" ], 1675 "remarks" : 1676 [ 1677 { 1678 "description" : 1679 [ 1680 "She sells sea shells down by the sea shore.", 1681 "Originally written by Terry Sullivan." 1682 ] 1683 } 1684 ], 1685 "links" : 1686 [ 1687 { 1688 "value" : "http://example.net/entity/xxxx", 1689 "rel" : "self", 1690 "href" : "http://example.net/entity/xxxx", 1691 "type" : "application/rdap+json" 1692 } 1693 ], 1694 "events" : 1695 [ 1696 { 1697 "eventAction" : "registration", 1698 "eventDate" : "1990-12-31T23:59:59Z" 1699 }, 1700 { 1701 "eventAction" : "last changed", 1702 "eventDate" : "1991-12-31T23:59:59Z" 1703 } 1704 ] 1705 } 1706 ] 1708 } 1710 6.4. The IP Network Object Class 1712 The IP Network object class models IP network registrations found in 1713 RIRs and is the expected response for the "/ip" query as defined by 1714 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1715 for DNRs. The high level structure of the IP network object class 1716 consists of information about the network registration and entities 1717 related to the IP network (e.g. registrant information, contacts, 1718 etc...). 1720 The following is an elided example of the IP network object type 1721 showing the high level structure: 1723 { 1724 "objectClassName" : "ip network", 1725 "handle" : "XXX", 1726 ... 1727 "entities" : 1728 [ 1729 ... 1730 ] 1731 } 1733 The following is an example of the JSON object for the network 1734 registration information. For illustrative purposes, it does not 1735 include rdapConformance or notices data structures. 1737 { 1738 "objectClassName" : "ip network", 1739 "handle" : "XXXX-RIR", 1740 "startAddress" : "2001:db8::0", 1741 "endAddress" : "2001:db8:0:FFFF:FFFF:FFFF:FFFF:FFFF", 1742 "ipVersion" : "v6", 1743 "name": "NET-RTR-1", 1744 "type" : "DIRECT ALLOCATION", 1745 "country" : "AU", 1746 "parentHandle" : "YYYY-RIR", 1747 "status" : [ "active" ], 1748 "remarks" : 1749 [ 1750 { 1751 "description" : 1753 [ 1754 "She sells sea shells down by the sea shore.", 1755 "Originally written by Terry Sullivan." 1756 ] 1757 } 1758 ], 1759 "links" : 1760 [ 1761 { 1762 "value" : "http://example.net/ip/2001:db8::/48", 1763 "rel" : "self", 1764 "href" : "http://example.net/ip/2001:db8::/48", 1765 "type" : "application/rdap+json" 1766 }, 1767 { 1768 "value" : "http://example.net/ip/2001:db8::/48", 1769 "rel" : "up", 1770 "href" : "http://example.net/ip/2001:C00::/23", 1771 "type" : "application/rdap+json" 1772 } 1773 ], 1774 "events" : 1775 [ 1776 { 1777 "eventAction" : "registration", 1778 "eventDate" : "1990-12-31T23:59:59Z" 1779 }, 1780 { 1781 "eventAction" : "last changed", 1782 "eventDate" : "1991-12-31T23:59:59Z" 1783 } 1784 ], 1785 "entities" : 1786 [ 1787 { 1788 "objectClassName" : "entity", 1789 "handle" : "XXXX", 1790 "vcardArray":[ 1791 "vcard", 1792 [ 1793 ["version", {}, "text", "4.0"], 1794 ["fn", {}, "text", "Joe User"], 1795 ["kind", {}, "text", "individual"], 1796 ["lang", { 1797 "pref":"1" 1798 }, "language-tag", "fr"], 1799 ["lang", { 1800 "pref":"2" 1802 }, "language-tag", "en"], 1803 ["org", { 1804 "type":"work" 1805 }, "text", "Example"], 1806 ["title", {}, "text", "Research Scientist"], 1807 ["role", {}, "text", "Project Lead"], 1808 ["adr", 1809 { "type":"work" }, 1810 "text", 1811 [ 1812 "", 1813 "Suite 1234", 1814 "4321 Rue Somewhere", 1815 "Quebec", 1816 "QC", 1817 "G1V 2M2", 1818 "Canada" 1819 ] 1820 ], 1821 ["tel", 1822 { "type":["work", "voice"], "pref":"1" }, 1823 "uri", "tel:+1-555-555-1234;ext=102" 1824 ], 1825 ["email", 1826 { "type":"work" }, 1827 "text", "joe.user@example.com" 1828 ], 1829 ] 1830 ], 1831 "roles" : [ "registrant" ], 1832 "remarks" : 1833 [ 1834 { 1835 "description" : 1836 [ 1837 "She sells sea shells down by the sea shore.", 1838 "Originally written by Terry Sullivan." 1839 ] 1840 } 1841 ], 1842 "links" : 1843 [ 1844 { 1845 "value" : "http://example.net/entity/xxxx", 1846 "rel" : "self", 1847 "href" : "http://example.net/entity/xxxx", 1848 "type" : "application/rdap+json" 1849 } 1851 ], 1852 "events" : 1853 [ 1854 { 1855 "eventAction" : "registration", 1856 "eventDate" : "1990-12-31T23:59:59Z" 1857 }, 1858 { 1859 "eventAction" : "last changed", 1860 "eventDate" : "1991-12-31T23:59:59Z" 1861 } 1862 ] 1863 } 1864 ] 1865 } 1867 The following is a description of the members of this object: 1869 o objectClassName -- the string "ip network" 1871 o handle -- a string representing an RIR unique identifier of the 1872 network registration 1874 o startAddress -- the starting IP address of the network, either 1875 IPv4 or IPv6 1877 o endAddress -- the ending IP address of the network, either IPv4 or 1878 IPv6 1880 o ipVersion -- a string signifying the IP protocol version of the 1881 network: "v4" signifying an IPv4 network, "v6" signifying an IPv6 1882 network 1884 o name -- an identifier assigned to the network registration by the 1885 registration holder 1887 o type -- a string containing an RIR-specific classification of the 1888 network 1890 o country -- a string containing the name of the two-character 1891 country code of the network 1893 o parentHandle -- a string containing an RIR-unique identifier of 1894 the parent network of this network registration 1896 o status -- an array of strings indicating the state of the IP 1897 network 1899 o entities -- an array of entity objects as defined by Section 6.1. 1901 o remarks - see Section 5.3 1903 o links - see Section 5.2 1905 o port43 - see Section 5.7 1907 o events - see Section 5.5 1909 6.5. Autonomous System Number Entity Object Class 1911 The Autonomous System Number (autnum) object class models Autonomous 1912 System Number registrations found in RIRs and represents the expected 1913 response to an "/autnum" query as defined by 1914 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1915 for DNRs. The high level structure of the autnum object class 1916 consists of information about the network registration and entities 1917 related to the autnum registration (e.g. registrant information, 1918 contacts, etc.), and is similar to the IP Network entity object 1919 class. 1921 The following is an example of a JSON object representing an autnum. 1922 For illustrative purposes, it does not include rdapConformance or 1923 notices data structures. 1925 { 1926 "objectClassName" : "autnum", 1927 "handle" : "XXXX-RIR", 1928 "startAutnum" : 10, 1929 "endAutnum" : 15, 1930 "name": "AS-RTR-1", 1931 "type" : "DIRECT ALLOCATION", 1932 "status" : [ "active" ], 1933 "country": "AU", 1934 "remarks" : 1935 [ 1936 { 1937 "description" : 1938 [ 1939 "She sells sea shells down by the sea shore.", 1940 "Originally written by Terry Sullivan." 1941 ] 1942 } 1943 ], 1944 "links" : 1945 [ 1946 { 1947 "value" : "http://example.net/autnum/xxxx", 1948 "rel" : "self", 1949 "href" : "http://example.net/autnum/xxxx", 1950 "type" : "application/rdap+json" 1951 } 1952 ], 1953 "events" : 1954 [ 1955 { 1956 "eventAction" : "registration", 1957 "eventDate" : "1990-12-31T23:59:59Z" 1958 }, 1959 { 1960 "eventAction" : "last changed", 1961 "eventDate" : "1991-12-31T23:59:59Z" 1962 } 1963 ], 1964 "entities" : 1965 [ 1966 { 1967 "objectClassName" : "entity", 1968 "handle" : "XXXX", 1969 "vcardArray":[ 1970 "vcard", 1971 [ 1972 ["version", {}, "text", "4.0"], 1973 ["fn", {}, "text", "Joe User"], 1974 ["kind", {}, "text", "individual"], 1975 ["lang", { 1976 "pref":"1" 1977 }, "language-tag", "fr"], 1978 ["lang", { 1979 "pref":"2" 1980 }, "language-tag", "en"], 1981 ["org", { 1982 "type":"work" 1983 }, "text", "Example"], 1984 ["title", {}, "text", "Research Scientist"], 1985 ["role", {}, "text", "Project Lead"], 1986 ["adr", 1987 { "type":"work" }, 1988 "text", 1989 [ 1990 "", 1991 "Suite 1234", 1992 "4321 Rue Somewhere", 1993 "Quebec", 1994 "QC", 1995 "G1V 2M2", 1996 "Canada" 1997 ] 1998 ], 1999 ["tel", 2000 { "type":["work", "voice"], "pref":"1" }, 2001 "uri", "tel:+1-555-555-1234;ext=102" 2002 ], 2003 ["email", 2004 { "type":"work" }, 2005 "text", "joe.user@example.com" 2006 ], 2007 ] 2008 ], 2009 "roles" : [ "registrant" ], 2010 "remarks" : 2011 [ 2012 { 2013 "description" : 2014 [ 2015 "She sells sea shells down by the sea shore.", 2016 "Originally written by Terry Sullivan." 2017 ] 2018 } 2019 ], 2020 "links" : 2021 [ 2022 { 2023 "value" : "http://example.net/entity/XXXX", 2024 "rel" : "self", 2025 "href" : "http://example.net/entity/XXXX", 2026 "type" : "application/rdap+json" 2027 } 2028 ], 2029 "events" : 2030 [ 2031 { 2032 "eventAction" : "registration", 2033 "eventDate" : "1990-12-31T23:59:59Z" 2034 }, 2035 { 2036 "eventAction" : "last changed", 2037 "eventDate" : "1991-12-31T23:59:59Z" 2038 } 2039 ] 2040 } 2041 ] 2043 } 2045 The following is a description of the members of this object: 2047 o objectClassName -- the string "autnum" 2049 o handle -- a string representing an RIR-unique identifier of the 2050 autnum registration 2052 o startAutnum -- a number representing the starting number [RFC5396] 2053 in the block of autonomous system numbers 2055 o endAutnum -- a number representing the ending number [RFC5396] in 2056 the block of autonomous system numbers 2058 o name -- an identifier assigned to the autnum registration by the 2059 registration holder 2061 o type -- a string containing an RIR-specific classification of the 2062 autnum 2064 o status -- an array of strings indicating the state of the autnum 2066 o country -- a string containing the name of the 2 character country 2067 code of the autnum 2069 o entities -- an array of entity objects as defined by Section 6.1. 2071 o remarks - see Section 5.3 2073 o links - see Section 5.2 2075 o port43 - see Section 5.7 2077 o events - see Section 5.5 2079 7. Error Response Body 2081 Some non-answer responses may return entity bodies with information 2082 that could be more descriptive. 2084 The basic structure of that response is an object class containing an 2085 error code number (corresponding to the HTTP response code) followed 2086 by a string named "title" and an array of strings named 2087 "description". 2089 This is an example of the common response body. For illustrative 2090 purposes, it does not include rdapConformance or notices data 2091 structures. 2093 { 2094 "errorCode": 418, 2095 "title": "Your beverage choice is not available", 2096 "description": 2097 [ 2098 "I know coffee has more ummppphhh.", 2099 "Sorry, dude!" 2100 ] 2101 } 2103 Figure 18 2105 A client MAY simply use the HTTP response code as the server is not 2106 required to include error data in the response body. However, if a 2107 client wishes to parse the error data, it SHOULD first check that the 2108 Content-Type header contains the appropriate media type. 2110 This is an example of the common response body with and 2111 rdapConformance and notices data structures: 2113 { 2114 "rdapConformance" : 2115 [ 2116 "rdap_level_0" 2117 ], 2118 "notices" : 2119 [ 2120 { 2121 "title" : "Beverage policy", 2122 "description" : 2123 [ 2124 "Beverages with caffeine for keeping horses awake." 2125 ], 2126 "links" : 2127 [ 2128 { 2129 "value" : "http://example.net/ip/192.0.2.0/24", 2130 "rel" : "alternate", 2131 "type" : "text/html", 2132 "href" : "http://www.example.com/redaction_policy.html" 2133 } 2134 ] 2135 } 2136 ], 2137 "lang" : "en", 2138 "errorCode": 418, 2139 "title": "Your beverage choice is not available", 2140 "description": 2141 [ 2142 "I know coffee has more ummppphhh.", 2143 "Sorry, dude!" 2144 ] 2145 } 2147 Figure 19 2149 8. Responding to Help Queries 2151 The appropriate response to /help queries as defined by 2152 [I-D.ietf-weirds-rdap-query] is to use the notices structure as 2153 defined in Section 5.3. 2155 This is an example of a response to a /help query including the 2156 rdapConformance data structure. 2158 { 2159 "rdapConformance" : 2160 [ 2161 "rdap_level_0" 2162 ], 2163 "notices" : 2164 [ 2165 { 2166 "title" : "Authentication Policy", 2167 "description" : 2168 [ 2169 "Access to sensitive data for users with proper credentials." 2170 ], 2171 "links" : 2172 [ 2173 { 2174 "value" : "http://example.net/help", 2175 "rel" : "alternate", 2176 "type" : "text/html", 2177 "href" : "http://www.example.com/auth_policy.html" 2178 } 2179 ] 2180 } 2181 ] 2182 } 2184 Figure 20 2186 9. Responding To Searches 2188 [I-D.ietf-weirds-rdap-query] specifies three types of searches: 2189 domains, nameservers, and entities. Responses to these searches take 2190 the form of an array of object instances where each instance is an 2191 appropriate object class for the search (i.e. a search for /domains 2192 yields an array of domain object instances). These arrays are 2193 contained within the response object. 2195 The names of the arrays are as follows: 2197 o for /domains searches, the array is "domainSearchResults" 2199 o for /nameservers searches, the array is "nameserverSearchResults" 2201 o for /entities searches, the array is "entitySearchResults" 2202 The following is an elided example of a response to a /domains 2203 search. 2205 { 2206 "rdapConformance" : 2207 [ 2208 "rdap_level_0" 2209 ], 2210 ... 2211 "domainSearchResults" : 2212 [ 2213 { 2214 "handle" : "1-XXXX", 2215 "ldhName" : "1.example.com", 2216 ... 2217 }, 2218 { 2219 "handle" : "2-XXXX", 2220 "ldhName" : "2.example.com", 2221 ... 2222 } 2223 ] 2224 } 2226 search_response_example 2228 10. Indicating Truncated Responses 2230 In cases where the data of a response has been truncated (i.e. not 2231 all of it has been included in the response), a server may indicate 2232 this by including a typed notice in the response object. 2234 The following is an elided example of a search response that has been 2235 truncated. 2237 { 2238 "rdapConformance" : 2239 [ 2240 "rdap_level_0" 2241 ], 2242 "notices" : 2243 [ 2244 { 2245 "title" : "Search Policy", 2246 "type" : "result set truncated due to authorization", 2247 "description" : 2248 [ 2249 "Search results are limited to 25 per day per querying IP." 2250 ], 2251 "links" : 2252 [ 2253 { 2254 "value" : "http://example.net/help", 2255 "rel" : "alternate", 2256 "type" : "text/html", 2257 "href" : "http://www.example.com/search_policy.html" 2258 } 2259 ] 2260 } 2261 ], 2262 "domainSearchResults" : 2263 [ 2264 ... 2265 ] 2266 } 2268 search_response_truncated_example 2270 A similar technique can be used with a typed remark where a single 2271 object has been returned and data in that object has been truncated. 2272 Such an example might be an entity object with only a partial set of 2273 the IP networks associated with it. 2275 The following is an elided example of an entity truncated data. 2277 { 2278 "objectClassName" : "entity", 2279 "handle" : "ANENTITY", 2280 "roles" : [ "registrant" ], 2281 ... 2282 "entities" : 2283 [ 2284 { 2285 "objectClassName" : "entity", 2286 "handle": "ANEMBEDDEDENTITY", 2287 "roles" : [ "technical" ], 2288 ... 2289 }, 2290 ... 2291 ], 2292 "networks" : 2293 [ 2294 ... 2295 ], 2296 ... 2297 "remarks" : 2298 [ 2299 { 2300 "title" : "Data Policy", 2301 "type" : "object truncated due to unexplainable reason", 2302 "description" : 2303 [ 2304 "Some of the data in this object has been removed." 2305 ], 2306 "links" : 2307 [ 2308 { 2309 "value" : "http://example.net/help", 2310 "rel" : "alternate", 2311 "type" : "text/html", 2312 "href" : "http://www.example.com/data_policy.html" 2313 } 2314 ] 2315 } 2316 ] 2317 } 2319 Figure 21 2321 11. IANA Considerations 2323 11.1. RDAP JSON Media Type Registration 2325 This specification registers the "application/rdap+json" media type. 2327 Type name: application 2329 Subtype name: rdap+json 2331 Required parameters: n/a 2333 Encoding considerations: See section 3.1 of [RFC6839]. 2335 Security considerations: The media represented by this identifier 2336 does not have security considerations beyond that found in section 2337 6 of [RFC7159] 2339 Interoperability considerations: There are no known 2340 interoperability problems regarding this media format. 2342 Published specification: [[ this document ]] 2344 Applications that use this media type: Implementations of the 2345 Registration Data Access Protocol (RDAP) 2347 Additional information: This media type is a product of the IETF 2348 WEIRDS working group. The WEIRDS charter, information on the 2349 WEIRDS mailing list, and other documents produced by the WEIRDS 2350 working group can be found at https://datatracker.ietf.org/wg/ 2351 weirds/ 2353 Person & email address to contact for further information: Andy 2354 Newton 2356 Intended usage: COMMON 2358 Restrictions on usage: none 2360 Author: Andy Newton 2362 Change controller: IETF 2364 Provisional Registration: No (upon publication of this RFC) 2366 11.2. JSON Values Registry 2368 This section requests that the IANA establish an RDAP JSON Values 2369 Registry for use in the notices and remarks (Section 5.3), status 2370 (Section 5.6), role (Section 6.1), event action (Section 5.5), and 2371 domain variant relation (Section 6.3) fields specified in RDAP. 2373 Each entry in the registry should contain the following fields: 2375 1. Value - the string value being registered. 2377 2. Type - the type of value being registered. It should be one of 2378 the following: 2380 * 'notice or remark type' - denotes a type of notice or remark 2382 * 'status' - denotes a value for the 'status' object member as 2383 defined by Section 5.6. 2385 * 'role' - denotes a value for the 'role' array as defined in 2386 Section 6.1. 2388 * 'event action' - denotes a value for an event action as 2389 defined in Section 5.5. 2391 * 'domain variant relation' - denotes a relationship between a 2392 domain and a domain variant as defined in Section 6.3. 2394 3. Description - a one or two sentence description regarding the 2395 meaning of the value, how it might be used, and/or how it should 2396 be interpreted by clients. 2398 4. Registrant Name - the name of the person registering the value. 2400 5. Registrant Contact Information - an email address, postal 2401 address, or some other information to be used to contact the 2402 registrant. 2404 This registry should be governed by a designated expert or multiple 2405 designated experts. Registration of values into this registry should 2406 be accomplished by providing the information above to the designated 2407 expert(s). 2409 Review of registrations into this registry by the designated 2410 expert(s) should be narrowly judged on the following criteria: 2412 1. Values in need of being placed into multiple types must be 2413 assigned a separate registration for each type. 2415 2. Values must be strings. They should be multiple words separated 2416 by single space characters. Every character should be 2417 lowercased. If possible, every word should be given in English 2418 and each character should be US ASCII. 2420 3. Registrations should not duplicate the meaning of any existing 2421 registration. That is, if a request for a registration is 2422 significantly similar in nature to an existing registration, the 2423 request should be denied. For example, the terms 'maintainer' 2424 and 'registrant' are significantly similar in nature as they both 2425 denote a holder of a domain name or Internet number resource. In 2426 cases where it may be reasonably argued that machine 2427 interpretation of two similar values may alter the operation of 2428 client software, designated experts should not judge the values 2429 to be of significant similarity. 2431 4. Registrations should be relevant to the common usages of RDAP. 2432 Designated experts may rely upon the serving of the value by a 2433 DNR or RIR to make this determination. 2435 11.2.1. Notice and Remark Types 2437 This section registers the following values into the RDAP JSON Values 2438 Registry: 2440 1. 2442 * Value: result set truncated due to authorization 2444 * Type: notice and remark type 2446 * Description: The list of results does not contain all results 2447 due to lack of authorization. This may indicate to some 2448 clients that proper authorization will yield a longer result 2449 set. 2451 * Registrant Name: Andrew Newton 2453 * Registrant Contact Information: andy@hxr.us 2455 2. 2457 * Value: result set truncated due to excessive load 2459 * Type: notice and remark type 2461 * Description: The list of results does not contain all results 2462 due to excessively heavy load on the server. This may 2463 indicate to some clients that requerying at a later time will 2464 yield a longer result set. 2466 * Registrant Name: Andrew Newton 2468 * Registrant Contact Information: andy@hxr.us 2470 3. 2472 * Value: result set truncated due to unexplainable reasons 2474 * Type: notice and remark type 2476 * Description: The list of results does not contain all results 2477 for an unexplainable reason. This may indicate to some 2478 clients that requerying for any reason will not yield a longer 2479 result set. 2481 * Registrant Name: Andrew Newton 2483 * Registrant Contact Information: andy@hxr.us 2485 4. 2487 * Value: object truncated due to authorization 2489 * Type: notice and remark type 2491 * Description: The object does not contain all data due to lack 2492 of authorization. 2494 * Registrant Name: Andrew Newton 2496 * Registrant Contact Information: andy@hxr.us 2498 5. 2500 * Value: object truncated due to excessive load 2502 * Type: notice and remark type 2504 * Description: The object does not contain all data due to 2505 excessively heavy load on the server. This may indicate to 2506 some clients that requerying at a later time will yield all 2507 data of the object. 2509 * Registrant Name: Andrew Newton 2510 * Registrant Contact Information: andy@hxr.us 2512 6. 2514 * Value: object truncated due to unexplainable reasons 2516 * Type: notice and remark type 2518 * Description: The object does not contain all data for an 2519 unexplainable reason. 2521 * Registrant Name: Andrew Newton 2523 * Registrant Contact Information: andy@hxr.us 2525 11.2.2. Status 2527 This section registers the following values into the RDAP JSON Values 2528 Registry: 2530 1. 2532 * Value: validated 2534 * Type: status 2536 * Description: Signifies that the data of the object instance 2537 has been found to be accurate. This type of status is 2538 usually found on entity object instances to note the validity 2539 of identifying contact information. 2541 * Registrant Name: Andrew Newton 2543 * Registrant Contact Information: andy@hxr.us 2545 2. 2547 * Value: renew prohibited 2549 * Type: status 2551 * Description: Renewal or reregistration of the object instance 2552 is forbidden. 2554 * Registrant Name: Andrew Newton 2556 * Registrant Contact Information: andy@hxr.us 2558 3. 2560 * Value: update prohibited 2562 * Type: status 2564 * Description: Updates to the object instance are forbidden. 2566 * Registrant Name: Andrew Newton 2568 * Registrant Contact Information: andy@hxr.us 2570 4. 2572 * Value: transfer prohibited 2574 * Type: status 2576 * Description: Transfers of the registration from one registrar 2577 to another are forbidden. This type of status normally 2578 applies to DNR domain names. 2580 * Registrant Name: Andrew Newton 2582 * Registrant Contact Information: andy@hxr.us 2584 5. 2586 * Value: delete prohibited 2588 * Type: status 2590 * Description: Deletion of the registration of the object 2591 instance is forbidden. This type of status normally applies 2592 to DNR domain names. 2594 * Registrant Name: Andrew Newton 2596 * Registrant Contact Information: andy@hxr.us 2598 6. 2600 * Value: proxy 2602 * Type: status 2603 * Description: The registration of the object instance has been 2604 performed by a third party. This is most commonly applied to 2605 entities. 2607 * Registrant Name: Andrew Newton 2609 * Registrant Contact Information: andy@hxr.us 2611 7. 2613 * Value: private 2615 * Type: status 2617 * Description: The information of the object instance is not 2618 designated for public consumption. This is most commonly 2619 applied to entities. 2621 * Registrant Name: Andrew Newton 2623 * Registrant Contact Information: andy@hxr.us 2625 8. 2627 * Value: redacted 2629 * Type: status 2631 * Description: Some of the information of the object instance 2632 has not been made available. This is most commonly applied 2633 to entities. 2635 * Registrant Name: Andrew Newton 2637 * Registrant Contact Information: andy@hxr.us 2639 9. 2641 * Value: obscured 2643 * Type: status 2645 * Description: Some of the information of the object instance 2646 has been altered for the purposes of not readily revealing 2647 the actual information of the object instance. This is most 2648 commonly applied to entities. 2650 * Registrant Name: Andrew Newton 2651 * Registrant Contact Information: andy@hxr.us 2653 10. 2655 * Value: associated 2657 * Type: status 2659 * Description: The object instance is associated with other 2660 object instances in the registry. This is most commonly used 2661 to signify that a nameserver is associated with a domain or 2662 that an entity is associated with a network resource or 2663 domain. 2665 * Registrant Name: Andrew Newton 2667 * Registrant Contact Information: andy@hxr.us 2669 11. 2671 * Value: active 2673 * Type: status 2675 * Description: The object instance is in use. For domain 2676 names, it signifies that the domain name is published in DNS. 2677 For network and autnum registrations it signifies that they 2678 are allocated or assigned for use in operational networks. 2679 This maps to the Extensible Provisioning Protocol (EPP) 2680 [RFC5730] 'OK' status. 2682 * Registrant Name: Andrew Newton 2684 * Registrant Contact Information: andy@hxr.us 2686 12. 2688 * Value: inactive 2690 * Type: status 2692 * Description: The object instance is not in use. See 2693 'active'. 2695 * Registrant Name: Andrew Newton 2697 * Registrant Contact Information: andy@hxr.us 2699 13. 2701 * Value: locked 2703 * Type: status 2705 * Description: Changes to the object instance cannot be made, 2706 including the association of other object instances. 2708 * Registrant Name: Andrew Newton 2710 * Registrant Contact Information: andy@hxr.us 2712 14. 2714 * Value: pending create 2716 * Type: status 2718 * Description: A request has been received for the creation of 2719 the object instance but this action is not yet complete. 2721 * Registrant Name: Andrew Newton 2723 * Registrant Contact Information: andy@hxr.us 2725 15. 2727 * Value: pending renew 2729 * Type: status 2731 * Description: A request has been received for the renewal of 2732 the object instance but this action is not yet complete. 2734 * Registrant Name: Andrew Newton 2736 * Registrant Contact Information: andy@hxr.us 2738 16. 2740 * Value: pending transfer 2742 * Type: status 2744 * Description: A request has been received for the transfer of 2745 the object instance but this action is not yet complete. 2747 * Registrant Name: Andrew Newton 2749 * Registrant Contact Information: andy@hxr.us 2751 17. 2753 * Value: pending update 2755 * Type: status 2757 * Description: A request has been received for the update or 2758 modification of the object instance but this action is not 2759 yet complete. 2761 * Registrant Name: Andrew Newton 2763 * Registrant Contact Information: andy@hxr.us 2765 18. 2767 * Value: pending delete 2769 * Type: status 2771 * Description: A request has been received for the deletion or 2772 removal of the object instance but this action is not yet 2773 complete. For domains, this might mean that the name is no 2774 longer published in DNS but has not yet been purged from the 2775 registry database. 2777 * Registrant Name: Andrew Newton 2779 * Registrant Contact Information: andy@hxr.us 2781 11.2.3. Event Actions 2783 This section registers the following values into the RDAP JSON Values 2784 Registry: 2786 1. 2788 * Value: registration 2790 * Type: event action 2792 * Description: The object instance was initially registered. 2794 * Registrant Name: Andrew Newton 2795 * Registrant Contact Information: andy@hxr.us 2797 2. 2799 * Value: reregistration 2801 * Type: event action 2803 * Description: The object instance was registered subsequently 2804 to initial registration. 2806 * Registrant Name: Andrew Newton 2808 * Registrant Contact Information: andy@hxr.us 2810 3. 2812 * Value: last changed 2814 * Type: event action 2816 * Description: An action noting when the information in the 2817 object instance was last changed. 2819 * Registrant Name: Andrew Newton 2821 * Registrant Contact Information: andy@hxr.us 2823 4. 2825 * Value: expiration 2827 * Type: event action 2829 * Description: The object instance has been removed or will be 2830 removed at a pre-determined date and time from the registry. 2832 * Registrant Name: Andrew Newton 2834 * Registrant Contact Information: andy@hxr.us 2836 5. 2838 * Value: deletion 2840 * Type: event action 2841 * Description: The object instance was removed from the registry 2842 at a point in time that was not pre-determined. 2844 * Registrant Name: Andrew Newton 2846 * Registrant Contact Information: andy@hxr.us 2848 6. 2850 * Value: reinstantiation 2852 * Type: event action 2854 * Description: The object instance was reregistered after having 2855 been removed from the registry. 2857 * Registrant Name: Andrew Newton 2859 * Registrant Contact Information: andy@hxr.us 2861 7. 2863 * Value: transfer 2865 * Type: event action 2867 * Description: The object instance was transferred from one 2868 registrant to another. 2870 * Registrant Name: Andrew Newton 2872 * Registrant Contact Information: andy@hxr.us 2874 8. 2876 * Value: locked 2878 * Type: event action 2880 * Description: The object instance was locked (see the 'locked' 2881 status). 2883 * Registrant Name: Andrew Newton 2885 * Registrant Contact Information: andy@hxr.us 2887 9. 2889 * Value: unlocked 2891 * Type: event action 2893 * Description: The object instance was unlocked (see the 2894 'locked' status). 2896 * Registrant Name: Andrew Newton 2898 * Registrant Contact Information: andy@hxr.us 2900 11.2.4. Roles 2902 This section registers the following values into the RDAP JSON Values 2903 Registry: 2905 1. 2907 * Value: registrant 2909 * Type: role 2911 * Description: The entity object instance is the registrant of 2912 the registration. In some registries, this is known as a 2913 maintainer. 2915 * Registrant Name: Andrew Newton 2917 * Registrant Contact Information: andy@hxr.us 2919 2. 2921 * Value: technical 2923 * Type: role 2925 * Description: The entity object instance is a technical 2926 contact for the registration. 2928 * Registrant Name: Andrew Newton 2930 * Registrant Contact Information: andy@hxr.us 2932 3. 2934 * Value: administrative 2936 * Type: role 2937 * Description: The entity object instance is an administrative 2938 contact for the registration. 2940 * Registrant Name: Andrew Newton 2942 * Registrant Contact Information: andy@hxr.us 2944 4. 2946 * Value: abuse 2948 * Type: role 2950 * Description: The entity object instance handles network abuse 2951 issues on behalf of the registrant of the registration. 2953 * Registrant Name: Andrew Newton 2955 * Registrant Contact Information: andy@hxr.us 2957 5. 2959 * Value: billing 2961 * Type: role 2963 * Description: The entity object instance handles payment and 2964 billing issues on behalf of the registrant of the 2965 registration. 2967 * Registrant Name: Andrew Newton 2969 * Registrant Contact Information: andy@hxr.us 2971 6. 2973 * Value: registrar 2975 * Type: role 2977 * Description: The entity object instance represents the 2978 authority responsible for the registration in the registry. 2980 * Registrant Name: Andrew Newton 2982 * Registrant Contact Information: andy@hxr.us 2984 7. 2986 * Value: reseller 2988 * Type: role 2990 * Description: The entity object instance represents a third 2991 party through which the registration was conducted (i.e. not 2992 the registry or registrar). 2994 * Registrant Name: Andrew Newton 2996 * Registrant Contact Information: andy@hxr.us 2998 8. 3000 * Value: sponsor 3002 * Type: role 3004 * Description: The entity object instance represents a domain 3005 policy sponsor, such as an ICANN approved sponsor. 3007 * Registrant Name: Andrew Newton 3009 * Registrant Contact Information: andy@hxr.us 3011 9. 3013 * Value: proxy 3015 * Type: role 3017 * Description: The entity object instance represents a proxy 3018 for another entity object, such as a registrant. 3020 * Registrant Name: Andrew Newton 3022 * Registrant Contact Information: andy@hxr.us 3024 10. 3026 * Value: notifications 3028 * Type: role 3030 * Description: An entity object instance designated to receive 3031 notifications about association object instances. 3033 * Registrant Name: Andrew Newton 3034 * Registrant Contact Information: andy@hxr.us 3036 11. 3038 * Value: noc 3040 * Type: role 3042 * Description: The entity object instance handles 3043 communications related to a network operations center (NOC). 3045 * Registrant Name: Andrew Newton 3047 * Registrant Contact Information: andy@hxr.us 3049 11.2.5. Variant Relations 3051 This section registers the following values into the RDAP JSON Values 3052 Registry: 3054 1. 3056 * Value: registered 3058 * Type: domain variant relation 3060 * Description: The variant names are registered in the registry. 3062 * Registrant Name: Andrew Newton 3064 * Registrant Contact Information: andy@hxr.us 3066 2. 3068 * Value: unregistered 3070 * Type: domain variant relation 3072 * Description: The variant names are not found in the registry. 3074 * Registrant Name: Andrew Newton 3076 * Registrant Contact Information: andy@hxr.us 3078 3. 3080 * Value: registration restricted 3081 * Type: domain variant relation 3083 * Description: Registration of the variant names is restricted 3084 to certain parties or within certain rules. 3086 * Registrant Name: Andrew Newton 3088 * Registrant Contact Information: andy@hxr.us 3090 4. 3092 * Value: open registration 3094 * Type: domain variant relation 3096 * Description: Registration of the variant names is available to 3097 generally qualified registrants. 3099 * Registrant Name: Andrew Newton 3101 * Registrant Contact Information: andy@hxr.us 3103 5. 3105 * Value: conjoined 3107 * Type: domain variant relation 3109 * Description: Registration of the variant names occurs 3110 automatically with the registration of the containing domain 3111 registration. 3113 * Registrant Name: Andrew Newton 3115 * Registrant Contact Information: andy@hxr.us 3117 12. Security Considerations 3119 This specification models information serialized in JSON format. As 3120 JSON is a subset of Javascript, implementations are advised to follow 3121 the security considerations outlined in Section 6 of [RFC7159] to 3122 prevent code injection. 3124 Though not specific to JSON, RDAP implementers should be aware of the 3125 security considerations specified in [I-D.ietf-weirds-using-http] and 3126 the security requirements and considerations in 3127 [I-D.ietf-weirds-rdap-sec]. 3129 13. Internationalization Considerations 3131 13.1. Character Encoding 3133 The default text encoding for JSON responses in RDAP is UTF-8 3134 [RFC3629], and all servers and clients MUST support UTF-8. Servers 3135 and clients MAY optionally support other character encodings. 3137 13.2. URIs and IRIs 3139 [I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in 3140 RDAP. 3142 13.3. Language Tags 3144 Section 5.4 defines the use of language tags in the JSON responses 3145 defined in this document. 3147 13.4. Internationalized Domain Names 3149 Internationalized Domain Names (IDNs) are denoted in this 3150 specification by the separation of DNS names in LDH form and Unicode 3151 form (see Section 4). Representation of IDNs in registries is 3152 described by the "variants" object in Section 6.3 and the suggested 3153 values listed in Section 11.2.5. 3155 14. Privacy Considerations 3157 This specification suggests status values to denote contact and 3158 registrant information that has been marked as private and/or has 3159 been redacted or obscured. See Section 11.2.2 for the list of status 3160 values. See Appendix A.1 on guidance to apply those values to 3161 contacts and registrants. 3163 15. Contributing Authors and Acknowledgements 3165 This document is derived from original work on RIR responses in JSON 3166 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew 3167 L. Newton. Additionally, this document incorporates work on DNR 3168 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 3169 Shen. 3171 The components of the DNR object classes are derived from a 3172 categorization of WHOIS response formats created by Ning Kong, Linlin 3173 Zhou, and Guangqing Deng, Steve Sheng and Francisco Arias, Ray 3174 Bellis, and Frederico Neves. 3176 Tom Harrison, Murray Kucherawy, Ed Lewis contributed significant 3177 review comments and provided clarifying text. James Mitchell 3178 provided text regarding the processing of unknown JSON attributes and 3179 identified issues leading to the remodeling of events. Ernie Dainow 3180 and Francisco Obispo provided concrete suggestions that led to a 3181 better variant model for domain names. 3183 Ernie Dainow provided the background information on the secure DNSSEC 3184 attributes and objects for domains, informative text on DNSSEC, and 3185 many other attributes that appear throughout the object classes of 3186 this draft. 3188 The switch to and incorporation of JSON vCard was performed by Simon 3189 Perreault. 3191 Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working 3192 group from which this document as been created. 3194 16. References 3196 16.1. Normative References 3198 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 3199 numbers", RFC 1166, July 1990. 3201 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3202 Requirement Levels", BCP 14, RFC 2119, March 1997. 3204 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 3205 Internet: Timestamps", RFC 3339, July 2002. 3207 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3208 10646", STD 63, RFC 3629, November 2003. 3210 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3211 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3212 3986, January 2005. 3214 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 3215 Rose, "Resource Records for the DNS Security Extensions", 3216 RFC 4034, March 2005. 3218 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 3219 Autonomous System (AS) Numbers", RFC 5396, December 2008. 3221 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 3222 Languages", BCP 47, RFC 5646, September 2009. 3224 [RFC5890] Klensin, J., "Internationalized Domain Names for 3225 Applications (IDNA): Definitions and Document Framework", 3226 RFC 5890, August 2010. 3228 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3229 Address Text Representation", RFC 5952, August 2010. 3231 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3233 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 3234 January 2014. 3236 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3237 Interchange Format", RFC 7159, March 2014. 3239 [I-D.ietf-weirds-using-http] 3240 Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the 3241 Registration Data Access Protocol (RDAP)", draft-ietf- 3242 weirds-using-http-11 (work in progress), September 2014. 3244 [I-D.ietf-weirds-rdap-query] 3245 Newton, A. and S. Hollenbeck, "Registration Data Access 3246 Protocol Query Format", draft-ietf-weirds-rdap-query-13 3247 (work in progress), August 2014. 3249 [I-D.ietf-weirds-rdap-sec] 3250 Hollenbeck, S. and N. Kong, "Security Services for the 3251 Registration Data Access Protocol", draft-ietf-weirds- 3252 rdap-sec-08 (work in progress), August 2014. 3254 [ISO.3166.1988] 3255 International Organization for Standardization, "Codes for 3256 the representation of names of countries, 3rd edition", 3257 ISO Standard 3166, August 1988. 3259 16.2. Informative References 3261 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 3262 September 2004. 3264 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 3265 STD 69, RFC 5730, August 2009. 3267 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 3268 Security Extensions Mapping for the Extensible 3269 Provisioning Protocol (EPP)", RFC 5910, May 2010. 3271 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 3272 August 2011. 3274 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 3275 Structured Syntax Suffixes", RFC 6839, January 2013. 3277 [JSON_acendancy] 3278 MacVittie, , "The Stealthy Ascendancy of JSON", 04 2011. 3280 [IANA_IDNTABLES] 3281 "IANA IDN Tables", 3282 . 3284 [JSON_performance_study] 3285 Montana State University - Bozeman, Montana State 3286 University - Bozeman, Montana State University - Bozeman, 3287 and Montana State University - Bozeman, "Comparison of 3288 JSON and XML Data Interchange Formats: A Case Study", 3289 2009. 3291 Appendix A. Suggested Data Modeling with the Entity Object Class 3293 A.1. Registrants and Contacts 3295 This document does not provide specific object classes for 3296 registrants and contacts. Instead the entity object class may be 3297 used to represent a registrant or contact. When the entity object is 3298 embedded inside a containing object such as a domain name or IP 3299 network, the 'roles' string array can be used to signify the 3300 relationship. It is recommended that the values from Section 11.2.4 3301 be used. 3303 The following is an example of an elided containing object with an 3304 embedded entity that is both a registrant and administrative contact: 3306 { 3307 ... 3308 "entities" : 3309 [ 3310 { 3311 "objectClassName" : "entity", 3312 "handle" : "XXXX", 3313 "vcardArray":[ 3314 "vcard", 3315 [ 3316 ["version", {}, "text", "4.0"], 3317 ["fn", {}, "text", "Joe User"], 3319 ["kind", {}, "text", "individual"], 3320 ["lang", { 3321 "pref":"1" 3322 }, "language-tag", "fr"], 3323 ["lang", { 3324 "pref":"2" 3325 }, "language-tag", "en"], 3326 ["org", { 3327 "type":"work" 3328 }, "text", "Example"], 3329 ["title", {}, "text", "Research Scientist"], 3330 ["role", {}, "text", "Project Lead"], 3331 ["adr", 3332 { "type":"work" }, 3333 "text", 3334 [ 3335 "", 3336 "Suite 1234", 3337 "4321 Rue Somewhere", 3338 "Quebec", 3339 "QC", 3340 "G1V 2M2", 3341 "Canada" 3342 ] 3343 ], 3344 ["tel", 3345 { "type":["work", "voice"], "pref":"1" }, 3346 "uri", "tel:+1-555-555-1234;ext=102" 3347 ], 3348 ["email", 3349 { "type":"work" }, 3350 "text", "joe.user@example.com" 3351 ], 3352 ] 3353 ], 3354 "roles" : [ "registrant", "administrative" ], 3355 "remarks" : 3356 [ 3357 { 3358 "description" : 3359 [ 3360 "She sells sea shells down by the sea shore.", 3361 "Originally written by Terry Sullivan." 3362 ] 3363 } 3364 ], 3365 "events" : 3366 [ 3367 { 3368 "eventAction" : "registration", 3369 "eventDate" : "1990-12-31T23:59:59Z" 3370 }, 3371 { 3372 "eventAction" : "last changed", 3373 "eventDate" : "1991-12-31T23:59:59Z" 3374 } 3375 ] 3376 } 3377 ] 3378 } 3380 In many use cases, it is necessary to hide or obscure the information 3381 of a registrant or contact due to policy or other operational 3382 matters. Registries can denote these situations with 'status' values 3383 (see Section 11.2.2). 3385 The following is an elided example of a registrant with information 3386 changed to reflect that of a third party. 3388 { 3389 ... 3390 "entities" : 3391 [ 3392 { 3393 "objectClassName" : "entity", 3394 "handle" : "XXXX", 3395 ... 3396 "roles" : [ "registrant", "administrative" ], 3397 "status" : [ "proxy", "private", "obscured" ] 3398 } 3399 ] 3400 } 3402 A.2. Registrars 3404 This document does not provide a specific object class for 3405 registrars, but like registrants and contacts (see Appendix A.1) the 3406 'roles' string array maybe used. Additionally, many registrars have 3407 publicly assigned identifiers. The 'publicIds' structure 3408 (Section 5.8) represents that information. 3410 The following is an example of an elided containing object with an 3411 embedded entity that is a registrar: 3413 { 3414 ... 3415 "entities":[ 3416 { 3417 "objectClassName" : "entity", 3418 "handle":"XXXX", 3419 "vcardArray":[ 3420 "vcard", 3421 [ 3422 ["version", {}, "text", "4.0"], 3423 ["fn", {}, "text", "Joe's Fish, Chips and Domains"], 3424 ["kind", {}, "text", "org"], 3425 ["lang", { 3426 "pref":"1" 3427 }, "language-tag", "fr"], 3428 ["lang", { 3429 "pref":"2" 3430 }, "language-tag", "en"], 3431 ["org", { 3432 "type":"work" 3433 }, "text", "Example"], 3434 ["adr", 3435 { "type":"work" }, 3436 "text", 3437 [ 3438 "", 3439 "Suite 1234", 3440 "4321 Rue Somewhere", 3441 "Quebec", 3442 "QC", 3443 "G1V 2M2", 3444 "Canada" 3445 ] 3446 ], 3447 ["tel", 3448 { 3449 "type":["work", "voice"], 3450 "pref":"1" 3451 }, 3452 "uri", "tel:+1-555-555-1234;ext=102" 3453 ], 3454 ["email", 3455 { "type":"work" }, 3456 "text", "joes_fish_chips_and_domains@example.com" 3457 ], 3458 ] 3459 ], 3460 "roles":[ "registrar" ], 3461 "publicIds":[ 3462 { 3463 "type":"IANA Registrar ID", 3464 "identifier":"1" 3465 } 3466 ], 3467 "remarks":[ 3468 { 3469 "description":[ 3470 "She sells sea shells down by the sea shore.", 3471 "Originally written by Terry Sullivan." 3472 ] 3473 } 3474 ], 3475 "links":[ 3476 { 3477 "value":"http://example.net/entity/XXXX", 3478 "rel":"alternate", 3479 "type":"text/html", 3480 "href":"http://www.example.com" 3481 } 3482 ] 3483 } 3484 ] 3485 } 3487 Appendix B. Modeling Events 3489 Events represent actions that have taken place against a registered 3490 object at a certain date and time. Events have three properties: the 3491 action, the actor, and the date and time of the event (which is 3492 sometimes in the future). In some cases the identity of the actor is 3493 not captured. 3495 Events can be modeled in three ways: 3497 1. events with no designated actor 3499 2. events where the actor is only designated by an identifier 3501 3. events where the actor can be modeled as an entity 3503 For the first use case, the 'events' data structure (Section 5.5) is 3504 used without the 'eventActor' object member. 3506 This is an example of an "events" array without the 'eventActor'. 3508 "events" : 3509 [ 3510 { 3511 "eventAction" : "registration", 3512 "eventDate" : "1990-12-31T23:59:59Z" 3513 } 3514 ] 3516 Figure 22 3518 For the second use case, the 'events' data structure (Section 5.5) is 3519 used with the 'eventActor' object member. 3521 This is an example of an "events" array with the 'eventActor'. 3523 "events" : 3524 [ 3525 { 3526 "eventAction" : "registration", 3527 "eventActor" : "XYZ-NIC", 3528 "eventDate" : "1990-12-31T23:59:59Z" 3529 } 3530 ] 3532 Figure 23 3534 For the third use case, the 'asEventActor' array is used when an 3535 entity (Section 6.1) is embedded into another object class. The 3536 'asEventActor' array follows the same structure as the 'events' array 3537 but does not have 'eventActor' attributes. 3539 The following is an elided example of a domain object with an entity 3540 as an event actor. 3542 { 3543 "objectClassName" : "domain", 3544 "handle" : "XXXX", 3545 "ldhName" : "foo.example", 3546 "status" : [ "locked", "transfer Prohibited" ], 3547 ... 3548 "entities" : 3549 [ 3550 { 3551 "handle" : "XXXX", 3552 ... 3553 "asEventActor" : 3554 [ 3555 { 3556 "eventAction" : "last changed", 3557 "eventDate" : "1990-12-31T23:59:59Z" 3558 } 3559 ] 3560 } 3561 ] 3562 } 3564 Appendix C. Structured vs Unstructured Addresses 3566 The entity (Section 6.1) object class uses jCard [RFC7095] to 3567 represent contact information, including postal addresses. jCard has 3568 the ability to represent multiple language preferences, multiple 3569 email address and phone numbers, and multiple postal addresses in 3570 both a structured and unstructured format. This section describes 3571 the use of jCard for representing structured and unstructured 3572 addresses. 3574 The following is an example of a jCard. 3576 { 3577 "vcardArray":[ 3578 "vcard", 3579 [ 3580 ["version", {}, "text", "4.0"], 3581 ["fn", {}, "text", "Joe User"], 3582 ["n", {}, "text", 3583 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 3585 ], 3586 ["bday", {}, "date-and-or-time", "--02-03"], 3587 ["anniversary", 3588 {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" 3589 ], 3590 ["gender", {}, "text", "M"], 3591 ["kind", {}, "text", "individual"], 3592 ["lang", { 3593 "pref":"1" 3594 }, "language-tag", "fr"], 3595 ["lang", { 3596 "pref":"2" 3597 }, "language-tag", "en"], 3598 ["org", { 3599 "type":"work" 3600 }, "text", "Example"], 3601 ["title", {}, "text", "Research Scientist"], 3602 ["role", {}, "text", "Project Lead"], 3603 ["adr", 3604 { "type":"work" }, 3605 "text", 3606 [ 3607 "", 3608 "Suite 1234", 3609 "4321 Rue Somewhere", 3610 "Quebec", 3611 "QC", 3612 "G1V 2M2", 3613 "Canada" 3614 ] 3615 ], 3616 ["adr", 3617 { 3618 "type":"home", 3619 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 3620 }, 3621 "text", 3622 [ 3623 "", "", "", "", "", "", "" 3624 ] 3625 ], 3626 ["tel", 3627 { "type":["work", "voice"], "pref":"1" }, 3628 "uri", "tel:+1-555-555-1234;ext=102" 3629 ], 3630 ["tel", 3631 { 3632 "type":["work", "cell", "voice", "video", "text"] 3634 }, 3635 "uri", 3636 "tel:+1-555-555-1234" 3637 ], 3638 ["email", 3639 { "type":"work" }, 3640 "text", "joe.user@example.com" 3641 ], 3642 ["geo", { 3643 "type":"work" 3644 }, "uri", "geo:46.772673,-71.282945"], 3645 ["key", 3646 { "type":"work" }, 3647 "uri", "http://www.example.com/joe.user/joe.asc" 3648 ], 3649 ["tz", {}, 3650 "utc-offset", "-05:00"], 3651 ["url", { "type":"home" }, 3652 "uri", "http://example.org"] 3653 ] 3654 ] 3655 } 3657 Figure 24 3659 The arrays in Figure 24 with the first member of "adr" represent 3660 postal addresses. In the first example, the postal address is given 3661 as a an array of strings and constitutes a structured address. For 3662 components of the structured address that are not applicable, an 3663 empty string is given. Each member of that array aligns with the 3664 positions of a vCard as given in [RFC6350]. In this example, the 3665 following data corresponds to the following positional meanings: 3667 1. post office box - not applicable, empty string 3669 2. extended address (e.g., apartment or suite number) - Suite 1234 3671 3. street address - 4321 Rue Somewhere 3673 4. locality (e.g., city) - Quebec 3675 5. region (e.g., state or province) - QC 3677 6. postal code - G1V 2M2 3679 7. country name (full name) - Canada 3680 The second example is an unstructured address. It uses the label 3681 attribute, which is a string containing a newline (\n) character to 3682 separate address components in an unordered, unspecified manner. 3683 Note that in this example the structured address array is still given 3684 but that each string is an empty string. 3686 Appendix D. Secure DNS 3688 Section 6.3 defines the "secureDNS" member to represent secure DNS 3689 information about domain names. 3691 DNSSEC provides data integrity for DNS through digital signing of 3692 resource records. To enable DNSSEC, the zone is signed by one or 3693 more private keys and the signatures stored as RRSIG records. To 3694 complete the chain of trust in the DNS zone hierarchy, a digest of 3695 each DNSKEY record (which contains the public key) must be loaded 3696 into the parent zone, stored as Delegation Signer (DS) records and 3697 signed by the parent's private key (RRSIG DS record), "Resource 3698 Records for the DNS Security Extensions" [RFC4034]. Creating the DS 3699 records in the parent zone can be done by the registration authority, 3700 "Domain Name System (DNS) Security Extensions Mapping for the 3701 Extensible Provisioning Protocol (EPP)" [RFC5910]. 3703 Only DS related information is provided by RDAP, since other 3704 information is not generally stored in the registration database. 3705 Other DNSSEC related information can be retrieved with other DNS 3706 tools such as dig. 3708 The domain object class (Section 6.3) can represent this information 3709 using either the 'dsData' or 'keyData' object arrays. Client 3710 implementers should be aware that some registries do not collect or 3711 do not publish all of the secure DNS meta-information. 3713 Appendix E. Motivations for Using JSON 3715 This section addresses a common question regarding the use of JSON 3716 over other data formats, most notably XML. 3718 It is often pointed out that many DNRs and one RIR support the EPP 3719 [RFC5730] standard, which is an XML serialized protocol. The logic 3720 is that since EPP is a common protocol in the industry it follows 3721 that XML would be a more natural choice. While EPP does influence 3722 this specification quite a bit, EPP serves a different purpose which 3723 is the provisioning of Internet resources between registries and 3724 accredited registrars and serves a much narrower audience than that 3725 envisioned for RDAP. 3727 By contrast, RDAP has a broader audience and is designed for public 3728 consumption of data. Experience from RIRs with first generation 3729 RESTful web services for WHOIS indicate a large percentage of clients 3730 operate within browsers and other platforms where full-blown XML 3731 stacks are not readily available and where JSON is a better fit. 3733 Additionally, while EPP is used in much of the DNR community it is 3734 not a universal constant in that industry. And finally, EPP's use of 3735 XML predates the specification of JSON. If EPP had been defined 3736 today, it may very well have used JSON instead of XML. 3738 Beyond the specific DNR and RIR communities, the trend in the broader 3739 Internet industry is also switching to JSON over XML, especially in 3740 the area of RESTful web services (see [JSON_acendancy]). Studies 3741 have also found that JSON is generally less bulky and consequently 3742 faster to parse (see [JSON_performance_study]). 3744 Appendix F. Changelog 3746 [RFC Editor: Please delete this section prior to publication.] 3748 Initial -00 Adopted as working group document 2012-September-18. 3750 -01 3752 Minor spelling corrections. Changed "Registry Data" to 3753 "Registration Data" for the sake of consistency. 3755 Transitioned to RFC 5988 links and relationship types from our 3756 own custom "uris" structure. 3758 Some examples had 'status' as a string. Those have been 3759 corrected as 'status' is always an array of strings. 3761 Domain variants can now have a multi-valued relationship with 3762 domain registrations. 3764 "names" in the entity object class was changed to 3765 "entityNames". 3767 Some IP address examples change to IPv6. 3769 Change phone number examples and added reference to E.164. 3771 Added section on motivations for using JSON. 3773 Added error response body section. 3775 Added JSON naming section. 3777 Added common data structures section. 3779 Added the IANA Considerations section and the media type 3780 registration. 3782 Added 'lang' name/value. 3784 Added internationalization considerations section. 3786 -02 3788 Removed level from media type registration. 3790 Textual changes as given by Ed Lewis. 3792 Fixed object class linking example noted by Francisco Obispo 3794 Fixed a lot of other examples called out by Alex Sergeyev 3796 Added a note that JSON names are case sensitive 3798 Added 'status' to IP networks as suggested by Alex Sergeyev 3800 -03 3802 Added jCard verbiage and examples and deleted overlapping 3803 contact information and the appendix on postal addresses 3805 Removed the IANA considerations as they have been moved to 3806 another document 3808 Changed the remarks structure to be like notices 3810 Reordering and rewording some of the sections so they flow 3811 better 3813 Added note about object class "self" links 3815 Changed ipAddresses in nameserver object class to separate out 3816 v6 from v4 3818 Changed IP network version identifier from integer to string to 3819 be more consistent with ipAddresses identifier in nameserver 3820 object classes 3822 Changed DNS names to LDH names and Unicode names 3823 Modified the definition of 'conjoined' variant relationship so 3824 it was circular 3826 Added 'proxy', 'private', 'redacted', and 'obscured' status 3827 values (most useful for entities). 3829 Added a privacy considerations section 3831 Added a security considerations section 3833 Added 'reseller' and 'sponsor' to the list of entity roles 3835 Added the 'events' common data structure 3837 Added 'asEventActor' to entities 3839 Added appendix on event modeling 3841 Removed the subclasses/superclassing between RIRs/DNRs for 3842 entity and domain object classes 3844 Change suggested status/relation/etc values to be case/spacing 3845 consistent 3847 Normalized some of the definitions of object class members 3849 Modifying the JSON signaling section to reference the guidance 3850 in draft-ietf-weirds-using-http 3852 Changed the text regarding the process of unknown JSON 3853 attributes 3855 -04 3857 'description' removed from IP network and autnum because it is 3858 redundant with the remarks structure. 3860 Added 'entities' array to nameservers. 3862 Added 'status' to autnum. 3864 Added 'publicIds' to entity and domain. 3866 Added embedded entities to the entity object class. 3868 Added 'idnTable' to variants objects in domain object class. 3870 Changed the numbers for startNum and endNum in autnum to 3871 numbers instead of strings. 3873 Added an example for error response with full rdapConformance 3874 and notices. 3876 Added a section discussing help. 3878 Changed entities to use vcardArray and changed the examples to 3879 be current with jCard. 3881 Added a section on structured vs unstructured addresses. 3883 Added associated to the list of status values. 3885 Added a secure DNS section changed the 'delegationKey' object 3886 into the 'secureDNS' object. 3888 Changed the suggested values to an IANA registry. 3890 Added 'proxy' to the list of entity roles. 3892 -05 3894 Added IANA registration for RDAP JSON Media Type 3896 Added 'associated' status type. This was done earlier but got 3897 dropped during a reorganization of the document. 3899 Added the following status types: 3901 active 3903 inactive 3905 locked 3907 pending create 3909 pending renew 3911 pending update 3913 pending transfer 3915 pending delete 3917 renew prohibited 3919 Added the following event actions: 3921 locked 3923 unlocked 3925 Added the following roles: 3927 notifications 3929 noc 3931 Changed the 'tech' role to 'technical' 3933 Many document reference changes. 3935 Many examples have been fixed. 3937 Added links to dsData and keyData. 3939 Changed flags and protocols to integers in keyData. 3941 Added 'entities' to the specified list for autnum. 3943 Added SHOULD/SHOULD NOT language about using "type": 3944 "application/rdap+json" for self links. 3946 Added 'port43' to ip networks and autnum. 3948 -06 3950 Fix search response example. 3952 Change the returned search arrays to 'domainSearchResults', 3953 'entitySearchResults', and 'nameserverSearchResults'. 3955 -07 3957 'nameservers' in domain object class was changed to 3958 'nameServers' as in the example (note the camel case) 3960 fixed some example per email from James Mitchell 3962 fixed an example per email from Simon Perreault 3964 Added "network" to domain object class. 3966 Added networks and autnums to the entity object class. 3968 Created a section for "resultsTruncated". 3970 -08 3972 Added typed remarks and notices, removed "resultTruncated" in 3973 favor of them. 3975 Added "objectClassName". 3977 Changed JSON reference to RFC 7159. 3979 Removed unused references to RFC 0791, RFC 2616, RFC 4343, RFC 3980 5322. 3982 -09 3984 Fixed numerous examples. 3986 Reference to jCard updated. 3988 Text regarding JSON vCards has been changed to jCards. 3990 JSON naming rules do not apply to jCards. 3992 "nameserver" was made consistently all lower case. 3994 Links contained a "title" array, but it is now just a string 3995 per RFC 5988. 3997 Removed the term RESTful from the first section so it wouldn't 3998 have to be expanded. 4000 Added reference to RFC 2119 and noted that the uppercase form 4001 is what this document uses. 4003 Added text explaining why SHOULDs and SHOULD NOTs are to be 4004 followed. 4006 "port43" can now be either an domain name or IP address. 4008 "objectClassName" is now required. 4010 Numerous changes in prose for better readability. 4012 Updated the security considerations section to point to using- 4013 http and rdap-sec. 4015 Authors' Addresses 4017 Andrew Lee Newton 4018 American Registry for Internet Numbers 4019 3635 Concorde Parkway 4020 Chantilly, VA 20151 4021 US 4023 Email: andy@arin.net 4024 URI: http://www.arin.net 4026 Scott Hollenbeck 4027 Verisign Labs 4028 12061 Bluemont Way 4029 Reston, VA 20190 4030 US 4032 Email: shollenbeck@verisign.com 4033 URI: http://www.verisignlabs.com/