idnits 2.17.1 draft-ietf-weirds-json-response-04.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 : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 146: '...nt client/server MUST understand to fu...' RFC 2119 keyword, line 185: '...N attributes but SHOULD NOT treat them...' RFC 2119 keyword, line 186: '... error. Servers MAY insert values sig...' RFC 2119 keyword, line 188: '...o JSON responses SHOULD have names pre...' RFC 2119 keyword, line 191: '...meaningful name) SHOULD adhere to the ...' (14 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 12, 2013) is 3964 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) -- Looks like a reference, but probably isn't: '1' on line 1086 == Unused Reference: 'RFC0791' is defined on line 2559, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 2565, but no explicit reference was found in the text == Unused Reference: 'RFC4343' is defined on line 2583, but no explicit reference was found in the text == Unused Reference: 'RFC5322' is defined on line 2589, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 1166 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-15) exists of draft-ietf-weirds-using-http-05 -- 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-05 -- Obsolete informational reference (is this intentional?): RFC 3730 (Obsoleted by RFC 4930) Summary: 5 errors (**), 0 flaws (~~), 7 warnings (==), 4 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: December 14, 2013 Verisign Labs 6 June 12, 2013 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-weirds-json-response-04 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 December 14, 2013. 36 Copyright Notice 38 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 3.1. Signaling . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3.2. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 4. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 6 59 5. Common Data Structures . . . . . . . . . . . . . . . . . . . 7 60 5.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 8 61 5.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 5.3. Notices And Remarks . . . . . . . . . . . . . . . . . . . 9 63 5.4. Language Identifier . . . . . . . . . . . . . . . . . . . 11 64 5.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 5.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 12 66 5.7. Port 43 Whois Server . . . . . . . . . . . . . . . . . . 12 67 5.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 12 68 5.9. An Example . . . . . . . . . . . . . . . . . . . . . . . 13 69 6. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 14 70 6.1. The Entity Object Class . . . . . . . . . . . . . . . . . 14 71 6.2. The Nameserver Object Class . . . . . . . . . . . . . . . 20 72 6.3. The Domain Object Class . . . . . . . . . . . . . . . . . 23 73 6.4. The IP Network Object Class . . . . . . . . . . . . . . . 35 74 6.5. Autonomous System Number Entity Object Class . . . . . . 39 75 7. Error Response Body . . . . . . . . . . . . . . . . . . . . . 42 76 8. Responding to Help Queries . . . . . . . . . . . . . . . . . 43 77 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 78 9.1. Status . . . . . . . . . . . . . . . . . . . . . . . . . 46 79 9.2. Event Actions . . . . . . . . . . . . . . . . . . . . . . 48 80 9.3. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 50 81 9.4. Variant Relations . . . . . . . . . . . . . . . . . . . . 53 82 10. Security Considerations . . . . . . . . . . . . . . . . . . . 54 83 11. Internationalization Considerations . . . . . . . . . . . . . 54 84 11.1. Character Encoding . . . . . . . . . . . . . . . . . . . 54 85 11.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 54 86 11.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 55 87 11.4. Internationalized Domain Names . . . . . . . . . . . . . 55 88 12. Privacy Considerations . . . . . . . . . . . . . . . . . . . 55 89 13. Contributing Authors and Acknowledgements . . . . . . . . . . 55 90 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 56 91 14.1. Normative References . . . . . . . . . . . . . . . . . . 56 92 14.2. Informative References . . . . . . . . . . . . . . . . . 57 93 Appendix A. Suggested Data Modeling with the Entity Object Class 58 94 A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 58 95 A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 60 96 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 62 97 Appendix C. Structured vs Unstructured Addresses . . . . . . . . 64 98 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 66 99 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 67 100 Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . 67 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 70 103 1. Introduction 105 This document describes responses in the JSON [RFC4627] format for 106 the RESTful web queries as defined by the Registration Data Access 107 Protocol Lookup Format [I-D.ietf-weirds-rdap-query]. 109 The data model for JSON responses is specified in four sections: 111 1. simple data types conveyed in JSON strings 113 2. data structures specified as JSON arrays or objects that are used 114 repeatedly when building up larger objects 116 3. object classes representing structured data corresponding to a 117 given query 119 4. the response to an error 121 The object classes represent responses for two major categories of 122 data: responses returned by Regional Internet Registries (RIRs) for 123 registrations data related to IP addresses, reverse DNS names, and 124 Autonomous System numbers; and responses returned by Domain Name 125 Registries (DNRs) for registration data related to forward DNS names. 126 The following object classes are served by both RIRs and DNRs: 128 1. domains 130 2. nameservers 132 3. entities 134 The information served by both RIRs and DNRs for these object classes 135 overlap extensively and are given in this document as a unified model 136 for both classes of service. 138 In addition to the object classes listed above, RIRs also serve the 139 following object classes: 141 1. IP networks 143 2. Autonomous System numbers 145 Object classes defined in this document represent a minimal set of 146 what a compliant client/server MUST understand to function correctly, 147 however some deployments may want to include additional object 148 classes to suit individual needs. Anticipating this need for 149 extension, Section 3.2 of this document defines a mechanism for 150 extending the JSON objects that are described in this document. 152 2. Terminology and Definitions 154 The following list describes terminology and definitions used 155 throughout this document: 157 DNR: "Domain Name Registry". 159 LDH: "Letters, Digits, Hyphen". 161 member: data found with in an object as defined by JSON 162 [RFC4627]. 164 object: a data structure as defined by JSON [RFC4627]. 166 object class: the definition of members that may be found in JSON 167 objects described in this document. 169 object instance: an instantiation or specific instance of an object 170 class. 172 RDAP: "Registration Data Access Protocol". 174 RIR: "Regional Internet Registry". 176 3. Use of JSON 178 3.1. Signaling 180 Media type signaling for the JSON data specified in this document is 181 specified in [I-D.ietf-weirds-using-http]. 183 3.2. Naming 184 Clients processing JSON [RFC4627] responses are under no obligation 185 to process unrecognized JSON attributes but SHOULD NOT treat them as 186 an error. Servers MAY insert values signified by names into the JSON 187 responses which are not specified in this document. Insertion of 188 unspecified values into JSON responses SHOULD have names prefixed 189 with a short identifier followed by an underscore followed by a 190 meaningful name. The full JSON name (the prefix plus the underscore 191 plus the meaningful name) SHOULD adhere to the character and name 192 limitations of the prefix registry described in 193 [I-D.ietf-weirds-using-http]. 195 Consider the following JSON response with JSON names, all of which 196 are specified in this document. 198 { 199 "handle" : "ABC123", 200 "remarks" : 201 [ 202 { 203 "description" : 204 [ 205 "She sells sea shells down by the sea shore.", 206 "Originally written by Terry Sullivan." 207 ] 208 } 209 ] 210 } 212 Figure 1 214 If The Registry of the Moon desires to express information not found 215 in this specification, it might select "lunarNic" as its identifying 216 prefix and insert, as an example, the name 217 "lunarNic_beforeOneSmallStep" to signify registrations occurring 218 before the first moon landing and the name 219 "lunarNic_harshMistressNotes" containing other descriptive text. 221 Consider the following JSON response with JSON names, some of which 222 should be ignored by clients without knowledge of their meaning. 224 { 225 "handle" : "ABC123", 226 "lunarNic_beforeOneSmallStep" : "TRUE THAT!", 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 "lunarNic_harshMistressNotes" : 238 [ 239 "In space,", 240 "nobody can hear you scream." 241 ] 242 } 244 Figure 2 246 Insertion of unrecognized names ignored by clients may also be used 247 for future revisions to this specification. 249 Clients processing JSON responses MUST be prepared for values 250 specified in this document to be absent from a response as no JSON 251 value listed is required to appear in a response. In other words, 252 servers MAY remove values as is needed by the policies of the server 253 operator. 255 Finally, all JSON names specified in this document are case 256 sensitive. Both servers and clients MUST transmit and process them 257 using the specified character case. 259 4. Common Data Types 261 JSON [RFC4627] defines the data types of a number, character string, 262 boolean, array, object and null. This section describes the 263 semantics and/or syntax reference for data types used in this 264 document derived from the JSON character string. 266 'handle': DNRs and RIRs have registry-unique identifiers that 267 may be used to specifically reference an object 268 instance. The semantics of this data type as found 269 in this document is to be a registry-unique 270 reference to the closest enclosing object where the 271 value is found. The data type names 'registryId', 272 'roid', 'nic-handle', 'registrationNo', etc. are 273 terms often synonymous with this data type. In 274 this document, the term 'handle' is used. The term 275 exposed to users by clients is a presentation issue 276 beyond the scope of this document. 278 IPv4 addresses: The representation of IPv4 addresses in this 279 document uses the dotted-decimal notation described 280 in [RFC1166]. An example of this textual 281 representation is '192.0.2.0'. 283 IPv6 addresses: The representation of IPv6 addresses in this 284 document follow the forms outlined in [RFC5952]. 285 An example of this textual representation is 286 '2001:db8::1:0:0:1'. 288 country codes: Where the identity of a geopolitical nation or 289 country is needed, these identities are represented 290 with the alpha-2 or 2 character country code 291 designation as defined in [ISO.3166.1988]. The 292 alpha-2 representation is used because it is freely 293 available whereas the alpha-3 and numeric-3 294 standards are not. 296 LDH names: Textual representations of DNS names where the 297 labels of the domain are all "letters, digits, 298 hyphen" labels as described by [RFC5890]. Trailing 299 periods are optional. 301 Unicode names: Textual representations of DNS names where one or 302 more of the labels are U-labels as described by 303 [RFC5890]. Trailing periods are optional. 305 dates and times: The syntax for values denoting dates and times is 306 defined in [RFC3339]. 308 URIs: The syntax for values denoting a Uniform Resource 309 Identifier (URI) is defined by [RFC3986]. 311 Contact information is defined using JSON vCards as described in 312 [I-D.kewisch-vcard-in-json] 314 5. Common Data Structures 316 This section defines common data structures used commonly in object 317 classes. 319 5.1. RDAP Conformance 321 The first data structure is named "rdapConformance" and is simply an 322 array of strings, each providing a hint as to the specifications used 323 in the construction of the response. This data structure appears 324 only in the top most object of a response. 326 An example rdapConformance data structure: 328 "rdapConformance" : 329 [ 330 "rdap_level_0" 331 ] 333 Figure 3 335 The string literal "rdap_level_0" signifies conformance with this 336 specification. When custom JSON values are inserted into responses, 337 conformance to those custom specifications should use a string 338 prefixed with the appropriate identifier from the IANA prefix 339 identifier registry specified in [I-D.ietf-weirds-using-http]. For 340 example, if the fictional Registry of the Moon wants to signify that 341 their JSON responses are conformant with their registered extensions, 342 the string used might be "lunarNIC_level_0". 344 Example rdapConformance structure with custom extensions noted: 346 "rdapConformance" : 347 [ 348 "rdap_level_0", 349 "lunarNic_level_0" 350 ] 352 Figure 4 354 5.2. Links 356 The "links" array is found in data structures to signify links to 357 other resources on the Internet. The relationship of these links is 358 defined by the IANA registry described by [RFC5988]. 360 The following is an example of the link structure: 362 { 363 "value" : "http://example.com/context_uri", 364 "rel" : "self", 365 "href" : "http://example.com/target_uri", 366 "hreflang" : [ "en", "ch" ], 367 "title" : [ "title1", "title2" ], 368 "media" : "screen", 369 "type" : "application/json" 370 } 372 Figure 5 374 The JSON name/values of "rel", "href", "hreflang", "title", "media", 375 and "type" correspond to values found in Section 5 of [RFC5988]. The 376 "value" JSON value is the context URI as described by [RFC5988]. The 377 "value", "rel", and "href" JSON values MUST be specified. All other 378 JSON values are optional. 380 This is an example of the "links" array as it might be found in an 381 object class: 383 "links" : 384 [ 385 { 386 "value" : "http://example.com/ip/2001:db8::123", 387 "rel" : "self", 388 "href" : "http://example.com/ip/2001:db8::123" 389 }, 390 { 391 "value" : "http://example.com/ip/2001:db8::123", 392 "rel" : "up", 393 "href" : "http://example.com/ip/2001:db8::/48" 394 } 396 ] 398 5.3. Notices And Remarks 400 The "notices" and "remarks" data structures take the same form. The 401 "notices" structure denotes information about the service providing 402 RDAP information, whereas the "remarks" structure denotes information 403 about the object class it is contained within (see Section 6 404 regarding object classes). 406 Both are an array of objects. Each object contains an optional 407 "title" string representing the title of the object, an array of 408 strings named "description" for the purposes of conveying any 409 descriptive text, and an optional "links" array as described in 410 Section 5.2. 412 An example of the notices data structure: 414 "notices" : 415 [ 416 { 417 "title" : "Terms of Use", 418 "description" : 419 [ 420 "Service subject to The Registry of the Moon's TOS.", 421 "Copyright (c) 2020 LunarNIC" 422 ], 423 "links" : 424 [ 425 { 426 "value" : "http://example.net/entity/XXXX", 427 "rel" : "alternate", 428 "type" : "text/html", 429 "href" : "http://www.example.com/terms_of_use.html" 430 } 431 ] 432 } 433 ] 435 Figure 6 437 It is the job of the clients to determine line breaks, spacing and 438 display issues for sentences within the character strings of the 439 "description" array. Servers SHOULD NOT split sentences across 440 multiple strings of this array. Each string is to represent a 441 semantic division in the descriptive text. 443 An example of the remarks data structure: 445 "remarks" : 446 [ 447 { 448 "description" : 449 [ 450 "She sells sea shells down by the sea shore.", 451 "Originally written by Terry Sullivan." 452 ] 453 } 454 ] 456 Figure 7 458 Note that objects in the "remarks" array may also have a "links" 459 array. 461 While the "remarks" array will appear in many object classes in a 462 response, the "notices" array appears only in the top most object of 463 a response. 465 5.4. Language Identifier 467 This data structure is a simple JSON name/value of "lang" with a 468 string containing a language identifier as described by [RFC5646]. 470 "lang" : "mn-Cyrl-MN" 472 Figure 8 474 The 'lang' attribute may appear anywhere in an object class or data 475 structure. 477 5.5. Events 479 This data structure represents events that have occurred on an 480 instance of an object class (see Section 6 regarding object classes). 482 This is an example of an "events" array. 484 "events" : 485 [ 486 { 487 "eventAction" : "registration", 488 "eventActor" : "SOMEID-LUNARNIC", 489 "eventDate" : "1990-12-31T23:59:60Z" 490 }, 491 { 492 "eventAction" : "last changed", 493 "eventActor" : "OTHERID-LUNARNIC", 494 "eventDate" : "1991-12-31T23:59:60Z" 495 } 496 ] 498 Figure 9 500 The "events" array consists of objects, each with the following 501 members: 503 o 'eventAction' -- a string denoting the reason for the event 504 o 'eventActor' -- an optional identifier denoting the actor 505 responsible for the event 507 o 'eventDate' -- a string containing the time and date the event 508 occurred. 510 Events can be future dated. One use case for future dating of events 511 is to denote when an object expires from a registry. 513 See Section 9.2 for a list of values for the 'eventAction' string. 514 See Appendix B regarding the various ways events can be modeled. 516 5.6. Status 518 This data structure, named 'status', is an array of strings 519 indicating the state of a registered object (see Section 9.1 for a 520 list of values). 522 5.7. Port 43 Whois Server 524 This data structure, named 'port43', is a simple string containing 525 the fully-qualified host name of the WHOIS [RFC3912] server where the 526 containing object instance may be found. Note that this is not a 527 URI, as there is no WHOIS URI scheme. 529 5.8. Public IDs 531 This data structure maps a public identifier to an object class. It 532 is named 'publicIds' and is an array of objects, with each object 533 containing the following members: 535 o type - a string denoting the type of public identifier 537 o identifier - a public identifier of the type denoted by 'type' 539 The following is an example of a 'publicIds' structure. 541 "publicIds": 542 [ 543 { 544 "type":"IANA Registrar ID", 545 "identifier":"1" 546 } 547 ] 549 Figure 10 551 5.9. An Example 553 This is an example response with both rdapConformance and notices 554 embedded: 556 { 557 "rdapConformance" : 558 [ 559 "rdap_level_0" 560 ], 561 "notices" : 562 [ 563 { 564 "title" : "Content Redacted", 565 "description" : 566 [ 567 "Without full authorization, content has been redacted.", 568 "Sorry, dude!" 569 ], 570 "links" : 571 [ 572 { 573 "value" : "http://example.net/ip/192.0.2.0/24", 574 "rel" : "alternate", 575 "type" : "text/html", 576 "href" : "http://www.example.com/redaction_policy.html" 577 } 578 ] 579 } 580 ], 581 "lang" : "en", 582 "startAddress" : "192.0.2.0", 583 "endAddress" : "192.0.2.255", 584 "handle" : "XXXX-RIR", 585 "ipVersion" : "v4", 586 "name": "NET-RTR-1", 587 "parentHandle" : "YYYY-RIR", 588 "remarks" : 589 [ 590 { 591 "description" : 592 [ 593 "She sells sea shells down by the sea shore.", 594 "Originally written by Terry Sullivan." 595 ] 596 } 597 ] 598 } 599 Figure 11 601 6. Object Classes 603 Object classes represent structures appropriate for a response from 604 the queries specified in [I-D.ietf-weirds-rdap-query]. 606 Each object class contains a "links" array as specified in 607 Section 5.2. For every object class in a response, whether the 608 object class is directly representing the response to a query or is 609 embedded in other object classes, servers SHOULD provide a link 610 representing a URI for that object class using the "self" 611 relationship as specified in the IANA registry specified by 612 [RFC5988]. As explained in Section 6.2, this may be not always be 613 possible for name server data. Clients MUST be able to process 614 object instances without a "self" link. When present, clients MAY 615 use the self link for caching data. Servers MAY provide more than 616 one "self" link for any given object instance. 618 This is an example of the "links" array with a self link to an object 619 class: 621 "links" : 622 [ 623 { 624 "value" : "http://example.com/ip/2001:db8::123", 625 "rel" : "self", 626 "href" : "http://example.com/ip/2001:db8::123" 627 } 628 ] 630 6.1. The Entity Object Class 632 The entity object class appears throughout this document and is an 633 appropriate response for the /entity/XXXX query defined in 634 Registration Data Access Protocol Lookup Format 635 [I-D.ietf-weirds-rdap-query]. This object class represents the 636 information of organizations, corporations, governments, non-profits, 637 clubs, individual persons, and informal groups of people. All of 638 these representations are so similar that it is best to represent 639 them in JSON [RFC4627] with one construct, the entity object class, 640 to aid in the re-use of code by implementers. 642 The entity object is served by both RIRs and DNRs. The following is 643 an example of an entity that might be served by an RIR. For 644 illustrative purposes, it does not include rdapConformance or notices 645 data structures. 647 { 648 "handle":"XXXX", 649 "vcardArray":[ 650 "vcard", 651 [ 652 ["version", {}, "text", "4.0"], 653 ["fn", {}, "text", "Joe User"], 654 ["n", {}, "text", 655 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 656 ], 657 ["bday", {}, "date-and-or-time", "--02-03"], 658 ["anniversary", 659 {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" 660 ], 661 ["gender", {}, "text", "M"], 662 ["kind", {}, "text", "individual"], 663 ["lang", { 664 "pref":"1" 665 }, "language-tag", "fr"], 666 ["lang", { 667 "pref":"2" 668 }, "language-tag", "en"], 669 ["org", { 670 "type":"work" 671 }, "text", "Example"], 672 ["title", {}, "text", "Research Scientist"], 673 ["role", {}, "text", "Project Lead"], 674 ["adr", 675 { "type":"work" }, 676 "text", 677 [ 678 "", 679 "Suite 1234", 680 "4321 Rue Somewhere", 681 "Quebec", 682 "QC", 683 "G1V 2M2", 684 "Canada" 685 ] 686 ], 687 ["adr", 688 { 689 "type":"home", 690 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 691 }, 692 "text", 693 [ 694 "", "", "", "", "", "", "" 696 ] 697 ], 698 ["tel", 699 { 700 "type":["work", "voice"], 701 "pref":"1" 702 }, 703 "uri", 704 "tel:+1-555-555-1234;ext=102" 705 ], 706 ["tel", 707 { "type":["work", "cell", "voice", "video", "text"] }, 708 "uri", 709 "tel:+1-555-555-4321" 710 ], 711 ["email", 712 { "type":"work" }, 713 "text", 714 "joe.user@example.com" 715 ], 716 ["geo", { 717 "type":"work" 718 }, "uri", "geo:46.772673,-71.282945"], 719 ["key", 720 { "type":"work" }, 721 "uri", 722 "http://www.example.com/joe.user/joe.asc" 723 ], 724 ["tz", {}, 725 "utc-offset", "-05:00"], 726 ["url", { "type":"home" }, 727 "uri", "http://example.org"] 728 ] 729 ], 730 "roles":[ "registrar" ], 731 "publicIds":[ 732 { 733 "type":"IANA Registrar ID", 734 "identifier":"1" 735 } 736 ], 737 "remarks":[ 738 { 739 "description":[ 740 "She sells sea shells down by the sea shore.", 741 "Originally written by Terry Sullivan." 742 ] 743 } 745 ], 746 "links":[ 747 { 748 "value":"http://example.com/entity/XXXX", 749 "rel":"self", 750 "href":"http://example.com/entity/XXXX" 751 } 752 ], 753 "events":[ 754 { 755 "eventAction":"registration", 756 "eventDate":"1990-12-31T23:59:60Z" 757 } 758 ], 759 "asEventActor":[ 760 { 761 "eventAction":"last changed", 762 "eventDate":"1991-12-31T23:59:60Z" 763 } 764 ] 765 } 767 Entities may also have other entities embedded with them in an array. 768 This can be used to model an organization with specific individuals 769 fulfilling designated roles of responsibility. 771 The following is an elided example of an entity with embedded 772 entities. 774 { 775 "handle" : "ANENTITY", 776 "roles" : [ "registrar" ], 777 ... 778 "entities" : 779 [ 780 { 781 "handle": "ANEMBEDDEDENTITY", 782 "roles" : [ "technical" ], 783 ... 784 }, 785 ... 786 ], 787 ... 788 } 789 Figure 12 791 This object has the following members: 793 o handle -- a string representing an registry unique identifier of 794 the entity 796 o vcardArray -- a JSON vCard with the entity's contact information 798 o roles -- an array of strings, each signifying the relationship an 799 object would have with its closest containing object (see 800 Section 9.3 for a list of values) 802 o publicIds - see Section 5.8 804 o entities - an array of entity objects as defined by this section. 806 o remarks -- see Section 5.3 808 o links -- see Section 5.2 810 o events -- see Section 5.5 812 o asEventActor -- this data structure takes the same form as the 813 'events' data structure (see Section 5.5), but each object in the 814 array MUST NOT have an 'eventActor' member. These objects denote 815 that the entity is an event actor for the given events. See 816 Appendix B regarding the various ways events can be modeled. 818 o status -- see Section 5.6 820 o port43 -- see Section 5.7 822 The following is an example of a entity that might be served by a 823 DNR. For illustrative purposes, it does not include rdapConformance 824 or notices data structures. 826 { 827 "handle":"XXXX", 828 "vcardArray":[ 829 "vcard", 830 [ 831 ["version", {}, "text", "4.0"], 832 ["fn", {}, "text", "Joe User"], 833 ["kind", {}, "text", "individual"], 834 ["lang", { 835 "pref":"1" 837 }, "language-tag", "fr"], 838 ["lang", { 839 "pref":"2" 840 }, "language-tag", "en"], 841 ["org", { 842 "type":"work" 843 }, "text", "Example"], 844 ["title", {}, "text", "Research Scientist"], 845 ["role", {}, "text", "Project Lead"], 846 ["adr", 847 { "type":"work" }, 848 "text", 849 [ 850 "", 851 "Suite 1234", 852 "4321 Rue Somewhere", 853 "Quebec", 854 "QC", 855 "G1V 2M2", 856 "Canada" 857 ] 858 ], 859 ["tel", 860 { "type":["work", "voice"], "pref":"1" }, 861 "uri", "tel:+1-555-555-1234;ext=102" 862 ], 863 ["email", 864 { "type":"work" }, 865 "text", "joe.user@example.com" 866 ], 867 ] 868 ], 869 "status":[ "validated", "locked" ], 870 "remarks":[ 871 { 872 "description":[ 873 "She sells sea shells down by the sea shore.", 874 "Originally written by Terry Sullivan." 875 ] 876 } 877 ], 878 "links":[ 879 { 880 "value":"http://example.com/entity/XXXX", 881 "rel":"self", 882 "href":"http://example.com/entity/XXXX" 883 } 884 ], 885 "port43":"whois.example.net", 886 "events":[ 887 { 888 "eventAction":"registration", 889 "eventDate":"1990-12-31T23:59:60Z" 890 }, 891 { 892 "eventAction":"last changed", 893 "eventDate":"1991-12-31T23:59:60Z", 894 "eventActor":"joe@example.com" 895 } 896 ] 897 } 899 6.2. The Nameserver Object Class 901 The nameserver object class represents information regarding DNS name 902 servers used in both forward and reverse DNS. RIRs and some DNRs 903 register or expose nameserver information as an attribute of a domain 904 name, while other DNRs model nameservers as "first class objects". 906 The nameserver object class accommodates both models and degrees of 907 variation in between. 909 The following is an example of a nameserver object. For illustrative 910 purposes, it does not include rdapConformance or notices data 911 structures. 913 { 914 "handle" : "XXXX", 915 "ldhName" : "ns1.xn--fo-5ja.example", 916 "unicodeName" : "foo.example", 917 "status" : [ "active" ], 918 "ipAddresses" : 919 { 920 "v4": [ "192.0.2.1", "192.0.2.2" ], 921 "v6": [ "2001:db8::123" ] 922 }, 923 "remarks" : 924 [ 925 { 926 "description" : 927 [ 928 "She sells sea shells down by the sea shore.", 929 "Originally written by Terry Sullivan." 930 ] 931 } 932 ], 933 "links" : 934 [ 935 { 936 "value" : "http://example.net/nameserver/xxxx", 937 "rel" : "self", 938 "href" : "http://example.net/nameserver/xxxx" 939 } 940 ], 941 "port43" : "whois.example.net", 942 "events" : 943 [ 944 { 945 "eventAction" : "registration", 946 "eventDate" : "1990-12-31T23:59:60Z" 947 }, 948 { 949 "eventAction" : "last changed", 950 "eventDate" : "1991-12-31T23:59:60Z", 951 "eventActor" : "joe@example.com" 952 } 953 ] 954 } 956 Figure 13 958 Figure 13 is an example of a nameserver object with all values given. 959 Registries using a first-class nameserver data model would embed this 960 in domain objects as well as allowing references to it with the "/ 961 nameserver" query type (all depending on the registry operators 962 policy). Other registries may pare back the information as needed. 963 Figure 14 is an example of a nameserver object as would be found in 964 RIRs and some DNRs, while Figure 15 is an example of a nameserver 965 object as would be found in other DNRs. 967 The following is an example of the simplest nameserver object: 969 { 970 "ldhName" : "ns1.example.com" 971 } 973 Figure 14 975 The following is an example of a simple nameserver object that might 976 be commonly used by DNRs: 978 { 979 "ldhName" : "ns1.example.com", 980 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 981 } 983 Figure 15 985 As nameservers can be modeled by some registries to be first-class 986 objects, they may also have an array of entities (Section 6.1) 987 embedded to signify parties responsible for the maintenance, 988 registrations, etc. of the nameservers. 990 The following is an elided example of a nameserver with embedded 991 entities. 993 { 994 "handle" : "XXXX", 995 "ldhName" : "ns1.xn--fo-5ja.example", 996 ... 997 "entities" : 998 [ 999 ... 1000 ], 1001 ... 1002 } 1004 Figure 16 1006 The nameserver object class has the following members: 1008 o handle -- a string representing an registry unique identifier of 1009 the nameserver 1011 o ldhName -- a string containing the LDH name of the nameserver (see 1012 Section 4) 1014 o unicodeName -- a string containing a DNS Unicode name of the 1015 nameserver (see Section 4) 1017 o ipAddresses -- an object containing the following members: 1019 * v6 -- an array of strings containing IPv6 addresses of the 1020 nameserver 1022 * v4 -- an array of strings containing IPv4 addresses of the 1023 nameserver 1025 o entities -- an array of entity objects as defined by Section 6.1. 1027 o status - see Section 5.6 1029 o remarks - see Section 5.3 1031 o links - see Section 5.2 1033 o port43 - see Section 5.7 1035 o events - see Section 5.5 1037 6.3. The Domain Object Class 1038 The domain object class represents a DNS name and point of 1039 delegation. For RIRs these delegation points are in the reverse DNS 1040 tree, whereas for DNRs these delegation points are in the forward DNS 1041 tree. 1043 In both cases, the high level structure of the domain object class 1044 consists of information about the domain registration, nameserver 1045 information related to the domain name, and entities related to the 1046 domain name (e.g. registrant information, contacts, etc.). 1048 The following is an elided example of the domain object showing the 1049 high level structure: 1051 { 1052 "handle" : "XXX", 1053 "ldhName" : "blah.example.com", 1054 ... 1055 "nameServers" : 1056 [ 1057 ... 1058 ], 1059 ... 1060 "entities" : 1061 [ 1062 ... 1063 ] 1064 } 1066 The following is a description of the members of this object: 1068 o handle -- a string representing a registry unique identifier of 1069 the domain object instance 1071 o ldhName -- a string describing a domain name in LDH form as 1072 described in Section 4 1074 o unicodeName -- a string containing a domain name with U-labels as 1075 described in Section 4 1077 o variants -- an array of objects, each containing the following 1078 values: 1080 * relation -- an array of strings, with each string denoting the 1081 relationship between the variants and the containing domain 1082 object (see Section 9.4 for a list of suggested variant 1083 relations). 1085 * idnTable -- the name of the IDN table of codepoints, such as 1086 one listed with the IANA (see IDN tables [1]). 1088 * variantNames -- an array of objects, with each object 1089 containing an "ldhName" member and a "unicodeName" member (see 1090 Section 4). 1092 o nameservers -- an array of nameserver objects as defined by 1093 Section 6.2 1095 o secureDNS -- an object with the following members: 1097 * zoneSigned -- boolean true if the zone has been signed, false 1098 otherwise. 1100 * delegationSigned -- boolean true if there are DS records in the 1101 parent, false otherwise. 1103 * maxSigLife -- an integer representing the signature life time 1104 in seconds to be used when creating the RRSIG DS record in the 1105 parent zone [RFC5910]. 1107 * dsData - an array of objects, each with the following members: 1109 + keyTag -- an integer as specified by the key tag field of a 1110 DNS DS record as specified by RFC 4034 RFC 4034 [RFC4034] in 1111 presentation format 1113 + algorithm -- an integer as specified by the algorithm field 1114 of a DNS DS record as specified by RFC 4034 in presentation 1115 format 1117 + digest -- a string as specified by the digest field of a DNS 1118 DS record as specified by RFC 4034 in presentation format 1120 + digestType -- an integer as specified by the digest type 1121 field of a DNS DS record as specified by RFC 4034 in 1122 presentation format 1124 + events - see Section 5.5 1126 * keyData - an array of objects, each with the following members: 1128 + flags -- a string representing the flags field value in the 1129 DNSKEY record [RFC4034] in presentation format. 1131 + protocol - a string representation of the protocol field 1132 value of the DNSKEY record [RFC4034] in presentation format. 1134 + publicKey - a string representation of the public key in the 1135 DNSKEY record [RFC4034] in presentation format. 1137 + algorithm -- an integer as specified by the algorithm field 1138 of a DNSKEY record as specified by RFC 4034 [RFC4034] in 1139 presentation format 1141 + events - see Section 5.5 1143 See Appendix D for background information on these objects. 1145 o entities -- an array of entity objects as defined by Section 6.1. 1147 o status - see Section 5.6 1149 o publicIds - see Section 5.8 1151 o remarks - see Section 5.3 1153 o links - see Section 5.2 1155 o port43 - see Section 5.7 1157 o events - see Section 5.5 1159 The following is an example of a JSON domain object representing a 1160 reverse DNS delegation point that might be served by an RIR. For 1161 illustrative purposes, it does not include rdapConformance or notices 1162 data structures. 1164 { 1165 "handle" : "XXXX", 1166 "ldhName" : "192.in-addr.arpa", 1167 "nameServers" : 1168 [ 1169 { "ldhName" : "ns1.rir.example" }, 1170 { "ldhName" : "ns2.rir.example" } 1171 ], 1172 "secureDNS": 1173 { 1174 "delegationSigned": true, 1175 "dsData": 1176 [ 1177 { 1178 "keyTag": 12345, 1179 "algorithm": 3, 1180 "digestType": 1, 1181 "digest": "49FD46E6C4B45C55D4AC", 1182 } 1183 ] 1184 }, 1185 "remarks" : 1186 [ 1187 { 1188 "description" : 1189 [ 1190 "She sells sea shells down by the sea shore.", 1191 "Originally written by Terry Sullivan." 1192 ] 1193 } 1194 ], 1195 "links" : 1196 [ 1197 { 1198 "value": "http://example.net/domain/XXXX", 1199 "rel" : "self", 1200 "href" : "http://example.net/domain/XXXXX" 1201 } 1202 ], 1203 "events" : 1204 [ 1205 { 1206 "eventAction" : "registration", 1207 "eventDate" : "1990-12-31T23:59:60Z" 1208 }, 1209 { 1210 "eventAction" : "last changed", 1211 "eventDate" : "1991-12-31T23:59:60Z", 1212 "eventActor" : "joe@example.com" 1213 } 1214 ], 1215 "entities" : 1216 [ 1217 { 1218 "handle" : "XXXX", 1219 "vcardArray":[ 1220 "vcard", 1221 [ 1222 ["version", {}, "text", "4.0"], 1224 ["fn", {}, "text", "Joe User"], 1225 ["kind", {}, "text", "individual"], 1226 ["lang", { 1227 "pref":"1" 1228 }, "language-tag", "fr"], 1229 ["lang", { 1230 "pref":"2" 1231 }, "language-tag", "en"], 1232 ["org", { 1233 "type":"work" 1234 }, "text", "Example"], 1235 ["title", {}, "text", "Research Scientist"], 1236 ["role", {}, "text", "Project Lead"], 1237 ["adr", 1238 { "type":"work" }, 1239 "text", 1240 [ 1241 "", 1242 "Suite 1234", 1243 "4321 Rue Somewhere", 1244 "Quebec", 1245 "QC", 1246 "G1V 2M2", 1247 "Canada" 1248 ] 1249 ], 1250 ["tel", 1251 { "type":["work", "voice"], "pref":"1" }, 1252 "uri", "tel:+1-555-555-1234;ext=102" 1253 ], 1254 ["email", 1255 { "type":"work" }, 1256 "text", "joe.user@example.com" 1257 ], 1258 ] 1259 ], 1260 "roles" : [ "registrant" ], 1261 "remarks" : 1262 [ 1263 { 1264 "description" : 1265 [ 1266 "She sells sea shells down by the sea shore.", 1267 "Originally written by Terry Sullivan." 1268 ] 1269 } 1270 ], 1271 "links" : 1273 [ 1274 { 1275 "value": "http://example.net/entity/xxxx", 1276 "rel" : "self", 1277 "href" : "http://example.net/entity/xxxx" 1278 } 1279 ], 1280 "events" : 1281 [ 1282 { 1283 "eventAction" : "registration", 1284 "eventDate" : "1990-12-31T23:59:60Z" 1285 }, 1286 { 1287 "eventAction" : "last changed", 1288 "eventDate" : "1991-12-31T23:59:60Z", 1289 "eventActor" : "joe@example.com" 1290 } 1291 ] 1292 } 1293 ] 1294 } 1296 The following is an example of a JSON domain object representing a 1297 forward DNS delegation point that might be served by a DNR. For 1298 illustrative purposes, it does not include rdapConformance or notices 1299 data structures. 1301 { 1302 "handle" : "XXXX", 1303 "ldhName" : "xn--fo-5ja.example", 1304 "unicodeName" : "foo.example", 1305 "variants" : 1306 [ 1307 { 1308 "relation" : [ "registered", "conjoined" ], 1309 "variantNames" : 1310 [ 1311 { 1312 "ldhName" : "xn--fo-cka.example", 1313 "unicodeName" : "foo.example" 1314 }, 1315 { 1316 "ldhName" : "xn--fo-fka.example", 1317 "unicodeName" : "foeo.example" 1319 } 1320 ] 1321 }, 1322 { 1323 "relation" : [ "unregistered", "restricted registration" ], 1324 "idnTable": ".EXAMPLE Swedish", 1325 "variantNames" : 1326 [ 1327 { 1328 "ldhName": "xn--fo-8ja.example", 1329 "unicodeName" : "foo.example" 1330 } 1331 ] 1332 } 1333 ], 1334 "status" : [ "locked", "transferProhibited" ], 1335 "publicIds":[ 1336 { 1337 "type":"ENS_Auth ID", 1338 "identifier":"1234567890" 1339 } 1340 ], 1341 "nameServers" : 1342 [ 1343 { 1344 "handle" : "XXXX", 1345 "ldhName" : "ns1.example.com", 1346 "status" : [ "active" ], 1347 "ipAddresses" : 1348 { 1349 "v6": [ "2001:db8::123", "2001:db8::124" ], 1350 "v4": [ "192.0.2.1", "192.0.2.2" ] 1351 }, 1352 "remarks" : 1353 [ 1354 { 1355 "description" : 1356 [ 1357 "She sells sea shells down by the sea shore.", 1358 "Originally written by Terry Sullivan." 1359 ] 1360 } 1361 ], 1362 "links" : 1363 [ 1364 { 1365 "value" : "http://example.net/nameserver/XXXX", 1366 "rel" : "self", 1367 "href" : "http://example.net/nameserver/XXXX" 1368 } 1369 ], 1370 "events" : 1371 [ 1372 { 1373 "eventAction" : "registration", 1374 "eventDate" : "1990-12-31T23:59:60Z" 1375 }, 1376 { 1377 "eventAction" : "last changed", 1378 "eventDate" : "1991-12-31T23:59:60Z" 1379 } 1380 ] 1381 }, 1382 { 1383 "handle" : "XXXX", 1384 "ldhName" : "ns2.example.com", 1385 "status" : [ "active" ], 1386 "ipAddresses" : 1387 { 1388 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1389 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1390 }, 1391 "remarks" : 1392 [ 1393 { 1394 "description" : 1395 [ 1396 "She sells sea shells down by the sea shore.", 1397 "Originally written by Terry Sullivan." 1398 ] 1399 } 1400 ], 1401 "links" : 1402 [ 1403 { 1404 "value" : "http://example.net/nameserver/XXXX", 1405 "rel" : "self", 1406 "href" : "http://example.net/nameserver/XXXX" 1407 } 1408 ], 1409 "events" : 1410 [ 1411 { 1412 "eventAction" : "registration", 1413 "eventDate" : "1990-12-31T23:59:60Z" 1414 }, 1415 { 1416 "eventAction" : "last changed", 1417 "eventDate" : "1991-12-31T23:59:60Z" 1418 } 1419 ] 1420 } 1421 ], 1422 "secureDNS": 1423 [ 1424 "zoneSigned": true, 1425 "delegationSigned": true, 1426 "maxSigLife": 604800, 1427 "keyData": 1428 [ 1429 { 1430 "flags": 257, 1431 "protocol": 3, 1432 "algorithm": 1, 1433 "publicKey": "AQPJ////4Q==", 1434 "events": 1435 [ 1436 { 1437 "eventAction": "last changed", 1438 "eventDate": "2012-07-23T05:15:47Z" 1439 } 1440 ] 1441 } 1442 ] 1443 ], 1444 "remarks" : 1445 [ 1446 { 1447 "description" : 1448 [ 1449 "She sells sea shells down by the sea shore.", 1450 "Originally written by Terry Sullivan." 1451 ] 1452 } 1453 ], 1454 "links" : 1455 [ 1456 { 1457 "value": "http://example.net/domain/XXXX", 1458 "rel" : "self", 1459 "href" : "http://example.net/domain/XXXX" 1460 } 1461 ], 1462 "port43" : "whois.example.net", 1463 "events" : 1464 [ 1465 { 1466 "eventAction" : "registration", 1467 "eventDate" : "1990-12-31T23:59:60Z" 1468 }, 1469 { 1470 "eventAction" : "last changed", 1471 "eventDate" : "1991-12-31T23:59:60Z", 1472 "eventActor" : "joe@example.com" 1473 }, 1474 { 1475 "eventAction" : "transfer", 1476 "eventDate" : "1991-12-31T23:59:60Z", 1477 "eventActor" : "joe@example.com" 1478 }, 1479 { 1480 "eventAction" : "expiration", 1481 "eventDate" : "2016-12-31T23:59:60Z", 1482 "eventActor" : "joe@example.com" 1483 } 1484 ], 1485 "entities" : 1486 [ 1487 { 1488 "handle" : "XXXX", 1489 "vcardArray":[ 1490 "vcard", 1491 [ 1492 ["version", {}, "text", "4.0"], 1493 ["fn", {}, "text", "Joe User"], 1494 ["kind", {}, "text", "individual"], 1495 ["lang", { 1496 "pref":"1" 1497 }, "language-tag", "fr"], 1498 ["lang", { 1499 "pref":"2" 1500 }, "language-tag", "en"], 1501 ["org", { 1502 "type":"work" 1503 }, "text", "Example"], 1504 ["title", {}, "text", "Research Scientist"], 1505 ["role", {}, "text", "Project Lead"], 1506 ["adr", 1507 { "type":"work" }, 1508 "text", 1509 [ 1510 "", 1511 "Suite 1234", 1512 "4321 Rue Somewhere", 1513 "Quebec", 1514 "QC", 1515 "G1V 2M2", 1516 "Canada" 1517 ] 1518 ], 1519 ["tel", 1520 { "type":["work", "voice"], "pref":"1" }, 1521 "uri", "tel:+1-555-555-1234;ext=102" 1522 ], 1523 ["email", 1524 { "type":"work" }, 1525 "text", "joe.user@example.com" 1526 ], 1527 ] 1528 ], 1529 "status" : [ "validated", "locked" ], 1530 "roles" : [ "registrant" ], 1531 "remarks" : 1532 [ 1533 { 1534 "description" : 1535 [ 1536 "She sells sea shells down by the sea shore.", 1537 "Originally written by Terry Sullivan." 1538 ] 1539 } 1540 ], 1541 "links" : 1542 [ 1543 { 1544 "value" : "http://example.net/entity/xxxx", 1545 "rel" : "self", 1546 "href" : "http://example.net/entity/xxxx" 1547 } 1548 ], 1549 "events" : 1550 [ 1551 { 1552 "eventAction" : "registration", 1553 "eventDate" : "1990-12-31T23:59:60Z" 1554 }, 1555 { 1556 "eventAction" : "last changed", 1557 "eventDate" : "1991-12-31T23:59:60Z" 1558 } 1560 ] 1561 } 1562 ] 1563 } 1565 6.4. The IP Network Object Class 1567 The IP Network object class models IP network registrations found in 1568 RIRs and is the expected response for the "/ip" query as defined by 1569 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1570 for DNRs. The high level structure of the IP network object class 1571 consists of information about the network registration and entities 1572 related to the IP network (e.g. registrant information, contacts, 1573 etc...). 1575 The following is an elided example of the IP network object type 1576 showing the high level structure: 1578 { 1579 "handle" : "XXX", 1580 ... 1581 "entities" : 1582 [ 1583 ... 1584 ] 1585 } 1587 The following is an example of the JSON object for the network 1588 registration information. For illustrative purposes, it does not 1589 include rdapConformance or notices data structures. 1591 { 1592 "handle" : "XXXX-RIR", 1593 "startAddress" : "2001:db8::0", 1594 "endAddress" : "2001:db8::0:FFFF:FFFF:FFFF:FFFF:FFFF", 1595 "ipVersion" : "v6", 1596 "name": "NET-RTR-1", 1597 "type" : "DIRECT ALLOCATION", 1598 "country" : "AU", 1599 "parentHandle" : "YYYY-RIR", 1600 "status" : [ "allocated" ], 1601 "remarks" : 1603 [ 1604 { 1605 "description" : 1606 [ 1607 "She sells sea shells down by the sea shore.", 1608 "Originally written by Terry Sullivan." 1609 ] 1610 } 1611 ], 1612 "links" : 1613 [ 1614 { 1615 "value" : "http://example.ent/ip/2001:db8::/48", 1616 "rel" : "self", 1617 "href" : "http://example.net/ip/2001:db8::/48" 1618 }, 1619 { 1620 "value" : "http://example.net/ip/2001:db8::/48", 1621 "rel" : "up", 1622 "href" : "http://example.net/ip/2001:C00::/23" 1623 } 1624 ], 1625 "events" : 1626 [ 1627 { 1628 "eventAction" : "registration", 1629 "eventDate" : "1990-12-31T23:59:60Z" 1630 }, 1631 { 1632 "eventAction" : "last changed", 1633 "eventDate" : "1991-12-31T23:59:60Z" 1634 } 1635 ], 1636 "entities" : 1637 [ 1638 { 1639 "handle" : "XXXX", 1640 "vcardArray":[ 1641 "vcard", 1642 [ 1643 ["version", {}, "text", "4.0"], 1644 ["fn", {}, "text", "Joe User"], 1645 ["kind", {}, "text", "individual"], 1646 ["lang", { 1647 "pref":"1" 1648 }, "language-tag", "fr"], 1649 ["lang", { 1650 "pref":"2" 1652 }, "language-tag", "en"], 1653 ["org", { 1654 "type":"work" 1655 }, "text", "Example"], 1656 ["title", {}, "text", "Research Scientist"], 1657 ["role", {}, "text", "Project Lead"], 1658 ["adr", 1659 { "type":"work" }, 1660 "text", 1661 [ 1662 "", 1663 "Suite 1234", 1664 "4321 Rue Somewhere", 1665 "Quebec", 1666 "QC", 1667 "G1V 2M2", 1668 "Canada" 1669 ] 1670 ], 1671 ["tel", 1672 { "type":["work", "voice"], "pref":"1" }, 1673 "uri", "tel:+1-555-555-1234;ext=102" 1674 ], 1675 ["email", 1676 { "type":"work" }, 1677 "text", "joe.user@example.com" 1678 ], 1679 ] 1680 ], 1681 "roles" : [ "registrant" ], 1682 "remarks" : 1683 [ 1684 { 1685 "description" : 1686 [ 1687 "She sells sea shells down by the sea shore.", 1688 "Originally written by Terry Sullivan." 1689 ] 1690 } 1691 ], 1692 "links" : 1693 [ 1694 { 1695 "value" : "http://example.net/entity/xxxx", 1696 "rel" : "self", 1697 "href" : "http://example.net/entity/xxxx" 1698 } 1699 ], 1700 "events" : 1701 [ 1702 { 1703 "eventAction" : "registration", 1704 "eventDate" : "1990-12-31T23:59:60Z" 1705 }, 1706 { 1707 "eventAction" : "last changed", 1708 "eventDate" : "1991-12-31T23:59:60Z" 1709 } 1710 ] 1711 } 1712 ] 1713 } 1715 The following is a description of the members of this object: 1717 o handle -- a string representing an RIR unique identifier of the 1718 network registration 1720 o startAddress -- the starting IP address of the network, either 1721 IPv4 or IPv6 1723 o endAddress -- the ending IP address of the network, either IPv4 or 1724 IPv6 1726 o ipVersion -- a string signifying the IP protocol version of the 1727 network: "v4" signifying an IPv4 network, "v6" signifying an IPv6 1728 network 1730 o name -- an identifier assigned to the network registration by the 1731 registration holder 1733 o type -- a string containing an RIR-specific classification of the 1734 network 1736 o country -- a string containing the name of the 2 character country 1737 code of the network 1739 o parentHandle -- a string containing an RIR-unique identifier of 1740 the parent network of this network registration 1742 o status -- an array of strings indicating the state of the IP 1743 network 1745 o entities -- an array of entity objects as defined by Section 6.1. 1747 o remarks - see Section 5.3 1749 o links - see Section 5.2 1751 o events - see Section 5.5 1753 6.5. Autonomous System Number Entity Object Class 1755 The Autonomous System Number (autnum) object class models Autonomous 1756 System Number registrations found in RIRs and represents the expected 1757 response to an "/autnum" query as defined by 1758 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1759 for DNRs. The high level structure of the autnum object class 1760 consists of information about the network registration and entities 1761 related to the autnum registration (e.g. registrant information, 1762 contacts, etc.), and is similar to the IP Network entity object 1763 class. 1765 The following is an example of a JSON object representing an autnum. 1766 For illustrative purposes, it does not include rdapConformance or 1767 notices data structures. 1769 { 1770 "handle" : "XXXX-RIR", 1771 "startAutnum" : 10, 1772 "endAutnum" : 15, 1773 "name": "AS-RTR-1", 1774 "type" : "DIRECT ALLOCATION", 1775 "status" : [ "allocated" ], 1776 "country": "AU", 1777 "remarks" : 1778 [ 1779 { 1780 "description" : 1781 [ 1782 "She sells sea shells down by the sea shore.", 1783 "Originally written by Terry Sullivan." 1784 ] 1785 } 1786 ], 1787 "links" : 1788 [ 1789 { 1790 "value" : "http://example.net/autnum/xxxx", 1791 "rel" : "self", 1792 "href" : "http://example.net/autnum/xxxx" 1793 } 1795 ], 1796 "events" : 1797 [ 1798 { 1799 "eventAction" : "registration", 1800 "eventDate" : "1990-12-31T23:59:60Z" 1801 }, 1802 { 1803 "eventAction" : "last changed", 1804 "eventDate" : "1991-12-31T23:59:60Z" 1805 } 1806 ], 1807 "entities" : 1808 [ 1809 { 1810 "handle" : "XXXX", 1811 "vcardArray":[ 1812 "vcard", 1813 [ 1814 ["version", {}, "text", "4.0"], 1815 ["fn", {}, "text", "Joe User"], 1816 ["kind", {}, "text", "individual"], 1817 ["lang", { 1818 "pref":"1" 1819 }, "language-tag", "fr"], 1820 ["lang", { 1821 "pref":"2" 1822 }, "language-tag", "en"], 1823 ["org", { 1824 "type":"work" 1825 }, "text", "Example"], 1826 ["title", {}, "text", "Research Scientist"], 1827 ["role", {}, "text", "Project Lead"], 1828 ["adr", 1829 { "type":"work" }, 1830 "text", 1831 [ 1832 "", 1833 "Suite 1234", 1834 "4321 Rue Somewhere", 1835 "Quebec", 1836 "QC", 1837 "G1V 2M2", 1838 "Canada" 1839 ] 1840 ], 1841 ["tel", 1842 { "type":["work", "voice"], "pref":"1" }, 1843 "uri", "tel:+1-555-555-1234;ext=102" 1844 ], 1845 ["email", 1846 { "type":"work" }, 1847 "text", "joe.user@example.com" 1848 ], 1849 ] 1850 ], 1851 "roles" : [ "registrant" ], 1852 "remarks" : 1853 [ 1854 { 1855 "description" : 1856 [ 1857 "She sells sea shells down by the sea shore.", 1858 "Originally written by Terry Sullivan." 1859 ] 1860 } 1861 ], 1862 "links" : 1863 [ 1864 { 1865 "value" : "http://example.net/entity/XXXX", 1866 "rel" : "self", 1867 "href" : "http://example.net/entity/XXXX" 1868 } 1869 ], 1870 "events" : 1871 [ 1872 { 1873 "eventAction" : "registration", 1874 "eventDate" : "1990-12-31T23:59:60Z" 1875 }, 1876 { 1877 "eventAction" : "last changed", 1878 "eventDate" : "1991-12-31T23:59:60Z" 1879 } 1880 ] 1881 } 1882 ] 1883 } 1885 The following is a description of the members of this object: 1887 o handle -- a string representing an RIR-unique identifier of the 1888 autnum registration 1890 o startAutnum -- a number representing the starting number [RFC5396] 1891 in the block of autonomous system numbers 1893 o endAutnum -- a number representing the ending number [RFC5396] in 1894 the block of autonomous system numbers 1896 o name -- an identifier assigned to the autnum registration by the 1897 registration holder 1899 o type -- a string containing an RIR-specific classification of the 1900 autnum 1902 o status -- an array of strings indicating the state of the autnum 1904 o country -- a string containing the name of the 2 character country 1905 code of the autnum 1907 o remarks - see Section 5.3 1909 o links - see Section 5.2 1911 o events - see Section 5.5 1913 7. Error Response Body 1915 Some non-answer responses may return entity bodies with information 1916 that could be more descriptive. 1918 The basic structure of that response is an object class containing an 1919 error code number (corresponding to the HTTP response code) followed 1920 by a string named "title" followed by an array of strings named 1921 "description". 1923 This is an example of the common response body. For illustrative 1924 purposes, it does not include rdapConformance or notices data 1925 structures. 1927 { 1928 "errorCode": 418, 1929 "title": "Your beverage choice is not available", 1930 "description": 1931 [ 1932 "I know coffee has more ummppphhh.", 1933 "Sorry, dude!" 1934 ] 1935 } 1937 Figure 17 1939 A client MAY simply use the HTTP response code as the server is not 1940 required to include error data in the response body. However, if a 1941 client wishes to parse the error data, it SHOULD first check that the 1942 Content-Type header contains the appropriate media type. 1944 This is an example of the common response body with and 1945 rdapConformance and notices data structures: 1947 { 1948 "rdapConformance" : 1949 [ 1950 "rdap_level_0" 1951 ], 1952 "notices" : 1953 [ 1954 { 1955 "title" : "Beverage policy", 1956 "description" : 1957 [ 1958 "Beverages with caffeine for keeping horses awake." 1959 ], 1960 "links" : 1961 [ 1962 { 1963 "value" : "http://example.net/ip/192.0.2.0/24", 1964 "rel" : "alternate", 1965 "type" : "text/html", 1966 "href" : "http://www.example.com/redaction_policy.html" 1967 } 1968 ] 1969 } 1970 ], 1971 "lang" : "en", 1972 "errorCode": 418, 1973 "title": "Your beverage choice is not available", 1974 "description": 1975 [ 1976 "I know coffee has more ummppphhh.", 1977 "Sorry, dude!" 1978 ] 1979 } 1981 Figure 18 1983 8. Responding to Help Queries 1984 The appropriate response to /help queries as defined by 1985 [I-D.ietf-weirds-rdap-query] is to use the notices structure as 1986 defined in Section 5.3. 1988 This is an example of a response to a /help query including the 1989 rdapConformance data structure. 1991 { 1992 "rdapConformance" : 1993 [ 1994 "rdap_level_0" 1995 ], 1996 "notices" : 1997 [ 1998 { 1999 "title" : "Authentication Policy", 2000 "description" : 2001 [ 2002 "Access to sensitive data for users with proper credentials." 2003 ], 2004 "links" : 2005 [ 2006 { 2007 "value" : "http://example.net/help", 2008 "rel" : "alternate", 2009 "type" : "text/html", 2010 "href" : "http://www.example.com/auth_policy.html" 2011 } 2012 ] 2013 } 2014 ] 2015 } 2017 Figure 19 2019 9. IANA Considerations 2021 This section requests that the IANA establish an RDAP JSON Values 2022 Registry for use in the status (Section 5.6), role (Section 6.1), 2023 event action (Section 5.5), and domain variant relation (Section 6.3) 2024 fields specified in RDAP. 2026 Each entry in the registry should contain the following fields: 2028 1. Value - the string value being registered. 2030 2. Type - the type of value being registered. It should be one of 2031 the following: 2033 * 'status' - denotes a value for the 'status' object member as 2034 defined by Section 5.6. 2036 * 'role' - denotes a value for the 'role' array as defined in 2037 Section 6.1. 2039 * 'event action' - denotes a value for an event action as 2040 defined in Section 5.5. 2042 * 'domain variant relation' - denotes a relationship between a 2043 domain and a domain variant as defined in Section 6.3. 2045 3. Description - a one or two sentence description regarding the 2046 meaning of the value, how it might be used, and/or how it should 2047 be interpreted by clients. 2049 4. Registrant Name - the name of the person registering the value. 2051 5. Registrant Contact Information - an email address, postal 2052 address, or some other information to be used to contact the 2053 registrant. 2055 This registry should be governed by a designated expert or multiple 2056 designated experts. Registration of values into this registry should 2057 be accomplished by providing the information above to the designated 2058 expert(s). 2060 Review of registrations into this registry by the designated 2061 expert(s) should be narrowly judged on the following criteria: 2063 1. Values in need of being placed into multiple types must be 2064 assigned a separate registration for each type. 2066 2. Values must be strings. They can be multiple words separated by 2067 single space characters. Every character should be lowercased. 2068 If possible, every word should be given in English and each 2069 character should be US ASCII. 2071 3. Registrations should not duplicate the meaning of any existing 2072 registration. That is, if a request for a registration is 2073 significantly similar in nature to an existing registration, the 2074 request should be denied. For example, the terms 'maintainer' 2075 and 'registrant' are significantly similar in nature as they both 2076 denote a holder of a domain name or Internet number resource. In 2077 cases where it may be reasonably argued that machine 2078 interpretation of two similar values may alter the operation of 2079 client software, designated experts should not judge the values 2080 to be of significant similarity. 2082 4. Registrations should be relevant to the common usages of RDAP. 2083 Designated experts may rely upon the serving of the value by a 2084 DNR or RIR to make this determination. 2086 9.1. Status 2088 This section registers the following values into the RDAP JSON Values 2089 Registry: 2091 1. 2093 * Value: validated 2095 * Type: status 2097 * Description: Signifies that the data of the object instance 2098 has been found to be accurate. This type of status is usually 2099 found on entity object instances to note the validity of 2100 identifying contact information. 2102 * Registrant Name: Andrew Newton 2104 * Registrant Contact Information: andy@hxr.us 2106 2. 2108 * Value: update prohibited 2110 * Type: status 2112 * Description: Updates to the object instance are forbidden. 2114 * Registrant Name: Andrew Newton 2116 * Registrant Contact Information: andy@hxr.us 2118 3. 2120 * Value: transfer prohibited 2122 * Type: status 2124 * Description: Transfers of the registration from one registrar 2125 to another are forbidden. This type of status normally 2126 applies to DNR domain names. 2128 * Registrant Name: Andrew Newton 2129 * Registrant Contact Information: andy@hxr.us 2131 4. 2133 * Value: delete prohibited 2135 * Type: status 2137 * Description: Deletion of the registration of the object 2138 instance is forbidden. This type of status normally applies 2139 to DNR domain names. 2141 * Registrant Name: Andrew Newton 2143 * Registrant Contact Information: andy@hxr.us 2145 5. 2147 * Value: proxy 2149 * Type: status 2151 * Description: The registration of the object instance has been 2152 performed by a third party. This is most commonly applied to 2153 entities. 2155 * Registrant Name: Andrew Newton 2157 * Registrant Contact Information: andy@hxr.us 2159 6. 2161 * Value: private 2163 * Type: status 2165 * Description: The information of the object instance is not 2166 designated for public consumption. This is most commonly 2167 applied to entities. 2169 * Registrant Name: Andrew Newton 2171 * Registrant Contact Information: andy@hxr.us 2173 7. 2175 * Value: redacted 2176 * Type: status 2178 * Description: Some of the information of the object instance 2179 has not been made available. This is most commonly applied to 2180 entities. 2182 * Registrant Name: Andrew Newton 2184 * Registrant Contact Information: andy@hxr.us 2186 8. 2188 * Value: obscured 2190 * Type: status 2192 * Description: Some of the information of the object instance 2193 has been altered for the purposes of not readily revealing the 2194 actual information of the object instance. This is most 2195 commonly applied to entities. 2197 * Registrant Name: Andrew Newton 2199 * Registrant Contact Information: andy@hxr.us 2201 9.2. Event Actions 2203 This section registers the following values into the RDAP JSON Values 2204 Registry: 2206 1. 2208 * Value: registration 2210 * Type: event action 2212 * Description: The object instance was initially registered. 2214 * Registrant Name: Andrew Newton 2216 * Registrant Contact Information: andy@hxr.us 2218 2. 2220 * Value: reregistration 2222 * Type: event action 2223 * Description: The object instance was registered subsequently 2224 to initial registration. 2226 * Registrant Name: Andrew Newton 2228 * Registrant Contact Information: andy@hxr.us 2230 3. 2232 * Value: last changed 2234 * Type: event action 2236 * Description: An action noting when the information in the 2237 object instance was last changed. 2239 * Registrant Name: Andrew Newton 2241 * Registrant Contact Information: andy@hxr.us 2243 4. 2245 * Value: expiration 2247 * Type: event action 2249 * Description: The object instance has been removed or will be 2250 removed at a pre-determined date and time from the registry. 2252 * Registrant Name: Andrew Newton 2254 * Registrant Contact Information: andy@hxr.us 2256 5. 2258 * Value: deletion 2260 * Type: event action 2262 * Description: The object instance was removed from the registry 2263 at a point in time that was not pre-determined. 2265 * Registrant Name: Andrew Newton 2267 * Registrant Contact Information: andy@hxr.us 2269 6. 2271 * Value: reinstantiation 2273 * Type: event action 2275 * Description: The object instance was reregistered after having 2276 been removed from the registry. 2278 * Registrant Name: Andrew Newton 2280 * Registrant Contact Information: andy@hxr.us 2282 7. 2284 * Value: transfer 2286 * Type: event action 2288 * Description: The object instance was transferred from one 2289 registrant to another. 2291 * Registrant Name: Andrew Newton 2293 * Registrant Contact Information: andy@hxr.us 2295 9.3. Roles 2297 This section registers the following values into the RDAP JSON Values 2298 Registry: 2300 1. 2302 * Value: registrant 2304 * Type: role 2306 * Description: The entity object instance is the registrant of 2307 the registration. In some registries, this is known as a 2308 maintainer. 2310 * Registrant Name: Andrew Newton 2312 * Registrant Contact Information: andy@hxr.us 2314 2. 2316 * Value: tech 2318 * Type: role 2319 * Description: The entity object instance is a technical contact 2320 for the registration. 2322 * Registrant Name: Andrew Newton 2324 * Registrant Contact Information: andy@hxr.us 2326 3. 2328 * Value: administrative 2330 * Type: role 2332 * Description: The entity object instance is an administrative 2333 contact for the registration. 2335 * Registrant Name: Andrew Newton 2337 * Registrant Contact Information: andy@hxr.us 2339 4. 2341 * Value: abuse 2343 * Type: role 2345 * Description: The entity object instance handles network abuse 2346 issues on behalf of the registrant of the registration. 2348 * Registrant Name: Andrew Newton 2350 * Registrant Contact Information: andy@hxr.us 2352 5. 2354 * Value: billing 2356 * Type: role 2358 * Description: The entity object instance handles payment and 2359 billing issues on behalf of the registrant of the 2360 registration. 2362 * Registrant Name: Andrew Newton 2364 * Registrant Contact Information: andy@hxr.us 2366 6. 2368 * Value: registrar 2370 * Type: role 2372 * Description: The entity object instance represents the 2373 authority responsible for the registration in the registry. 2375 * Registrant Name: Andrew Newton 2377 * Registrant Contact Information: andy@hxr.us 2379 7. 2381 * Value: reseller 2383 * Type: role 2385 * Description: The entity object instance represents a third 2386 party through which the registration was conducted (i.e. not 2387 the registry or registrar). 2389 * Registrant Name: Andrew Newton 2391 * Registrant Contact Information: andy@hxr.us 2393 8. 2395 * Value: sponsor 2397 * Type: role 2399 * Description: The entity object instance represents a domain 2400 policy sponsor, such as an ICANN approved sponsor. 2402 * Registrant Name: Andrew Newton 2404 * Registrant Contact Information: andy@hxr.us 2406 9. 2408 * Value: proxy 2410 * Type: role 2412 * Description: The entity object instance represents a proxy for 2413 another entity object, such as a registrant. 2415 * Registrant Name: Andrew Newton 2416 * Registrant Contact Information: andy@hxr.us 2418 9.4. Variant Relations 2420 This section registers the following values into the RDAP JSON Values 2421 Registry: 2423 1. 2425 * Value: registered 2427 * Type: domain variant relation 2429 * Description: The variant names are registered in the registry. 2431 * Registrant Name: Andrew Newton 2433 * Registrant Contact Information: andy@hxr.us 2435 2. 2437 * Value: unregistered 2439 * Type: domain variant relation 2441 * Description: The variant names are not found in the registry. 2443 * Registrant Name: Andrew Newton 2445 * Registrant Contact Information: andy@hxr.us 2447 3. 2449 * Value: registration restricted 2451 * Type: domain variant relation 2453 * Description: Registration of the variant names is restricted 2454 to certain parties or within certain rules. 2456 * Registrant Name: Andrew Newton 2458 * Registrant Contact Information: andy@hxr.us 2460 4. 2462 * Value: open registration 2463 * Type: domain variant relation 2465 * Description: Registration of the variant names is available to 2466 generally qualified registrants. 2468 * Registrant Name: Andrew Newton 2470 * Registrant Contact Information: andy@hxr.us 2472 5. 2474 * Value: conjoined 2476 * Type: domain variant relation 2478 * Description: Registration of the variant names occurs 2479 automatically with the registration of the containing domain 2480 registration. 2482 * Registrant Name: Andrew Newton 2484 * Registrant Contact Information: andy@hxr.us 2486 10. Security Considerations 2488 This specification models information serialized in JSON format. As 2489 JSON is a subset of Javascript, implementations are advised to follow 2490 the security considerations outlined in Section 6 of [RFC4627] to 2491 prevent code injection. 2493 11. Internationalization Considerations 2495 11.1. Character Encoding 2497 The default text encoding for JSON and XML responses in RDAP is UTF-8 2498 [RFC3629], and all servers and clients MUST support UTF-8. Servers 2499 and clients MAY optionally support other character encodings. 2501 11.2. URIs and IRIs 2503 [I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in 2504 RDAP. 2506 11.3. Language Tags 2508 Section 5.4 defines the use of language tags in the JSON responses 2509 defined in this document. 2511 11.4. Internationalized Domain Names 2513 Internationalized Domain Names (IDNs) are denoted in this 2514 specification by the separation of DNS names in LDH form and Unicode 2515 form (see Section 4). Representation of IDNs in registries is 2516 described by the "variants" object in Section 6.3 and the suggested 2517 values listed in Section 9.4. 2519 12. Privacy Considerations 2521 This specification suggests status values to denote contact and 2522 registrant information that has been marked as private and/or has 2523 been redacted or obscured. See Section 9.1 for the list of status 2524 values. See Appendix A.1 on guidance to apply those values to 2525 contacts and registrants. 2527 13. Contributing Authors and Acknowledgements 2529 This document is derived from original work on RIR responses in JSON 2530 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew L. 2531 Newton. Additionally, this document incorporates word on DNR 2532 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 2533 Shen. 2535 The components of the DNR object classes are derived from a 2536 categorization of WHOIS response formats created by Ning Kong, Linlin 2537 Zhou, and Guangqing Deng, Steve Sheng and Francisco Arias, Ray 2538 Bellis, and Frederico Neves. 2540 Ed Lewis contributed significant review comments and provided 2541 clarifying text. James Mitchell provided text regarding the 2542 processing of unknown JSON attributes and identified issues leading 2543 to the remodeling of events. Ernie Dainow and Francisco Obispo 2544 provided concrete suggestions that led to a better variant model for 2545 domain names. 2547 Ernie Dainow provided the background information on the secure DNSSEC 2548 attributes and objects for domains, informative text on DNSSEC, and 2549 many other attributes that appear throughout the object classes of 2550 this draft. 2552 The switch to and incorporation of JSON vCard was performed by Simon 2553 Perreault. 2555 14. References 2557 14.1. Normative References 2559 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 2560 1981. 2562 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 2563 numbers", RFC 1166, July 1990. 2565 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2566 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2567 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2569 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 2570 Internet: Timestamps", RFC 3339, July 2002. 2572 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2573 10646", STD 63, RFC 3629, November 2003. 2575 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2576 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2577 3986, January 2005. 2579 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 2580 Rose, "Resource Records for the DNS Security Extensions", 2581 RFC 4034, March 2005. 2583 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 2584 Clarification", RFC 4343, January 2006. 2586 [RFC4627] Crockford, D., "The application/json Media Type for 2587 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2589 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 2590 October 2008. 2592 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 2593 Autonomous System (AS) Numbers", RFC 5396, December 2008. 2595 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 2596 Languages", BCP 47, RFC 5646, September 2009. 2598 [RFC5890] Klensin, J., "Internationalized Domain Names for 2599 Applications (IDNA): Definitions and Document Framework", 2600 RFC 5890, August 2010. 2602 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 2603 Address Text Representation", RFC 5952, August 2010. 2605 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 2607 [I-D.kewisch-vcard-in-json] 2608 Kewisch, P., "jCard: The JSON format for vCard", draft- 2609 kewisch-vcard-in-json-01 (work in progress), March 2013. 2611 [I-D.ietf-weirds-using-http] 2612 Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the 2613 Registration Data Access Protocol (RDAP)", draft-ietf- 2614 weirds-using-http-05 (work in progress), May 2013. 2616 [I-D.ietf-weirds-rdap-query] 2617 Newton, A. and S. Hollenbeck, "Registration Data Access 2618 Protocol Lookup Format", draft-ietf-weirds-rdap-query-05 2619 (work in progress), June 2013. 2621 [ISO.3166.1988] 2622 International Organization for Standardization, "Codes for 2623 the representation of names of countries, 3rd edition", 2624 ISO Standard 3166, August 1988. 2626 14.2. Informative References 2628 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 2629 September 2004. 2631 [RFC3730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 2632 RFC 3730, March 2004. 2634 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 2635 Security Extensions Mapping for the Extensible 2636 Provisioning Protocol (EPP)", RFC 5910, May 2010. 2638 [RFC6530] Klensin, J. and Y. Ko, "Overview and Framework for 2639 Internationalized Email", RFC 6530, February 2012. 2641 [JSON_acendancy] 2642 MacVittie, ., "The Stealthy Ascendancy of JSON", 04 2011. 2644 [JSON_performance_study] 2645 Montana State University - Bozeman, Montana State 2646 University - Bozeman, Montana State University - Bozeman, 2647 Montana State University - Bozeman, "Comparison of JSON 2648 and XML Data Interchange Formats: A Case Study", 2009. 2650 Appendix A. Suggested Data Modeling with the Entity Object Class 2652 A.1. Registrants and Contacts 2654 This document does not provide specific object classes for 2655 registrants and contacts. Instead the entity object class may be 2656 used to represent a registrant or contact. When the entity object is 2657 embedded inside a containing object such as a domain name or IP 2658 network, the 'roles' string array can be used to signify the 2659 relationship. It is recommended that the values from Section 9.3 be 2660 used. 2662 The following is an example of an elided containing object with an 2663 embedded entity that is both a registrant and admin contact: 2665 { 2666 ... 2667 "entities" : 2668 [ 2669 { 2670 "handle" : "XXXX", 2671 "vcardArray":[ 2672 "vcard", 2673 [ 2674 ["version", {}, "text", "4.0"], 2675 ["fn", {}, "text", "Joe User"], 2676 ["kind", {}, "text", "individual"], 2677 ["lang", { 2678 "pref":"1" 2679 }, "language-tag", "fr"], 2680 ["lang", { 2681 "pref":"2" 2682 }, "language-tag", "en"], 2683 ["org", { 2684 "type":"work" 2685 }, "text", "Example"], 2686 ["title", {}, "text", "Research Scientist"], 2687 ["role", {}, "text", "Project Lead"], 2688 ["adr", 2689 { "type":"work" }, 2690 "text", 2691 [ 2692 "", 2693 "Suite 1234", 2694 "4321 Rue Somewhere", 2695 "Quebec", 2696 "QC", 2697 "G1V 2M2", 2698 "Canada" 2699 ] 2700 ], 2701 ["tel", 2702 { "type":["work", "voice"], "pref":"1" }, 2703 "uri", "tel:+1-555-555-1234;ext=102" 2704 ], 2705 ["email", 2706 { "type":"work" }, 2707 "text", "joe.user@example.com" 2708 ], 2709 ] 2710 ], 2711 "roles" : [ "registrant", "admin" ], 2712 "remarks" : 2713 [ 2714 { 2715 "description" : 2716 [ 2717 "She sells sea shells down by the sea shore.", 2718 "Originally written by Terry Sullivan." 2719 ] 2720 } 2721 ], 2722 "events" : 2723 [ 2724 { 2725 "eventAction" : "registration", 2726 "eventDate" : "1990-12-31T23:59:60Z" 2727 }, 2728 { 2729 "eventAction" : "last changed", 2730 "eventDate" : "1991-12-31T23:59:60Z" 2731 } 2732 ] 2733 } 2734 ] 2735 } 2737 In many use cases, it is necessary to hide or obscure the information 2738 of a registrant or contact due to policy or other operational 2739 matters. Registries can denote these situations with 'status' values 2740 (see Section 9.1). 2742 The following is an elided example of a registrant with information 2743 changed to reflect that of a third party. 2745 { 2746 ... 2747 "entities" : 2748 [ 2749 { 2750 "handle" : "XXXX", 2751 ... 2752 "roles" : [ "registrant", "admin" ], 2753 "status" : [ "proxy", "private", "obscured" ] 2754 } 2755 ] 2756 } 2758 A.2. Registrars 2760 This document does not provide a specific object class for 2761 registrars, but like registrants and contacts (see Appendix A.1) the 2762 'roles' string array maybe used. Additionally, many registrars have 2763 publicly assigned identifiers. The 'publicIds' structure 2764 (Section 5.8) represents that information. 2766 The following is an example of an elided containing object with an 2767 embedded entity that is a registrar: 2769 { 2770 ... 2771 "entities":[ 2772 { 2773 "handle":"XXXX", 2774 "vcardArray":[ 2775 "vcard", 2776 [ 2777 ["version", {}, "text", "4.0"], 2778 ["fn", {}, "text", "Joe User"], 2779 ["kind", {}, "text", "individual"], 2780 ["lang", { 2781 "pref":"1" 2782 }, "language-tag", "fr"], 2783 ["lang", { 2784 "pref":"2" 2785 }, "language-tag", "en"], 2787 ["org", { 2788 "type":"work" 2789 }, "text", "Example"], 2790 ["title", {}, "text", "Research Scientist"], 2791 ["role", {}, "text", "Project Lead"], 2792 ["adr", 2793 { "type":"work" }, 2794 "text", 2795 [ 2796 "", 2797 "Suite 1234", 2798 "4321 Rue Somewhere", 2799 "Quebec", 2800 "QC", 2801 "G1V 2M2", 2802 "Canada" 2803 ] 2804 ], 2805 ["tel", 2806 { 2807 "type":["work", "voice"], 2808 "pref":"1" 2809 }, 2810 "uri", "tel:+1-555-555-1234;ext=102" 2811 ], 2812 ["email", 2813 { "type":"work" }, 2814 "text", "joe.user@example.com" 2815 ], 2816 ] 2817 ], 2818 "roles":[ "registrar" ], 2819 "publicIds":[ 2820 { 2821 "type":"IANA Registrar ID", 2822 "identifier":"1" 2823 } 2824 ], 2825 "remarks":[ 2826 { 2827 "description":[ 2828 "She sells sea shells down by the sea shore.", 2829 "Originally written by Terry Sullivan." 2830 ] 2831 } 2832 ], 2833 "links":[ 2834 { 2835 "value":"http://example.net/entity/XXXX", 2836 "rel":"alternate", 2837 "type":"text/html", 2838 "href":"http://www.example.com" 2839 } 2840 ] 2841 } 2842 ] 2843 } 2845 Appendix B. Modeling Events 2847 Events represent actions that have taken place against a registered 2848 object at a certain date and time. Events have three properties: the 2849 action, the actor, and the date and time of the event (which is 2850 sometimes in the future). In some cases the identity of the actor is 2851 not captured. 2853 Events can be modeled in three ways: 2855 1. events with no designated actor 2857 2. events where the actor is only designated by an identifier 2859 3. events where the actor can be modeled as an entity 2861 For the first use case, the 'events' data structure (Section 5.5) is 2862 used without the 'eventActor' object member. 2864 This is an example of an "events" array without the 'eventActor'. 2866 "events" : 2867 [ 2868 { 2869 "eventAction" : "registration", 2870 "eventDate" : "1990-12-31T23:59:60Z" 2871 } 2872 ] 2874 Figure 20 2876 For the second use case, the 'events' data structure (Section 5.5) is 2877 used with the 'eventActor' object member. 2879 This is an example of an "events" array with the 'eventActor'. 2881 "events" : 2882 [ 2883 { 2884 "eventAction" : "registration", 2885 "eventActor" : "XYZ-NIC", 2886 "eventDate" : "1990-12-31T23:59:60Z" 2887 } 2888 ] 2890 Figure 21 2892 For the third use case, the 'asEventActor' array is used when an 2893 entity (Section 6.1) is embedded into another object class. The 2894 'asEventActor' array follows the same structure as the 'events' array 2895 but does not have 'eventActor' attributes. 2897 The following is an elided example of a domain object with an entity 2898 as an event actor. 2900 { 2901 "handle" : "XXXX", 2902 "ldhName" : "foo.example", 2903 "status" : [ "locked", "transfer Prohibited" ], 2904 ... 2905 "entities" : 2906 [ 2907 { 2908 "handle" : "XXXX", 2909 ... 2910 "asEventActor" : 2911 [ 2912 { 2913 "eventAction" : "last changed", 2914 "eventDate" : "1990-12-31T23:59:60Z" 2915 } 2916 ] 2917 } 2918 ] 2919 } 2921 Appendix C. Structured vs Unstructured Addresses 2923 The entity (Section 6.1) object class uses jCard 2924 [I-D.kewisch-vcard-in-json] to represent contact information, 2925 including postal addresses. jCard has the ability to represent 2926 multiple language preferences, multiple email address and phone 2927 numbers, and multiple postal addresses in both a structured and 2928 unstructured format. This section describes the use of jCard for 2929 representing structured and unstructured addresses. 2931 The following is an example of a jCard. 2933 { 2934 "vcardArray":[ 2935 "vcard", 2936 [ 2937 ["version", {}, "text", "4.0"], 2938 ["fn", {}, "text", "Joe User"], 2939 ["n", {}, "text", 2940 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 2941 ], 2942 ["bday", {}, "date-and-or-time", "--02-03"], 2943 ["anniversary", 2944 {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" 2945 ], 2946 ["gender", {}, "text", "M"], 2947 ["kind", {}, "text", "individual"], 2948 ["lang", { 2949 "pref":"1" 2950 }, "language-tag", "fr"], 2951 ["lang", { 2952 "pref":"2" 2953 }, "language-tag", "en"], 2954 ["org", { 2955 "type":"work" 2956 }, "text", "Example"], 2957 ["title", {}, "text", "Research Scientist"], 2958 ["role", {}, "text", "Project Lead"], 2959 ["adr", 2960 { "type":"work" }, 2961 "text", 2962 [ 2963 "", 2964 "Suite 1234", 2965 "4321 Rue Somewhere", 2966 "Quebec", 2967 "QC", 2968 "G1V 2M2", 2969 "Canada" 2970 ] 2971 ], 2972 ["adr", 2973 { 2974 "type":"home", 2975 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 2976 }, 2977 "text", 2978 [ 2979 "", "", "", "", "", "", "" 2980 ] 2981 ], 2982 ["tel", 2983 { "type":["work", "voice"], "pref":"1" }, 2984 "uri", "tel:+1-555-555-1234;ext=102" 2985 ], 2986 ["tel", 2987 { 2988 "type":["work", "cell", "voice", "video", "text"] 2989 }, 2990 "uri", 2991 "tel:+1-555-555-1234" 2992 ], 2993 ["email", 2994 { "type":"work" }, 2995 "text", "joe.user@example.com" 2996 ], 2997 ["geo", { 2998 "type":"work" 2999 }, "uri", "geo:46.772673,-71.282945"], 3000 ["key", 3001 { "type":"work" }, 3002 "uri", "http://www.example.com/joe.user/joe.asc" 3003 ], 3004 ["tz", {}, 3005 "utc-offset", "-05:00"], 3006 ["url", { "type":"home" }, 3007 "uri", "http://example.org"] 3008 ] 3009 ] 3010 } 3012 Figure 22 3014 The arrays in Figure 22 with the first member of "adr" represent 3015 postal addresses. In the first example, the postal address is given 3016 as a an array of strings and constitutes a structured address. For 3017 components of the structured address that are not applicable, an 3018 empty string is given. Each member of that array aligns with the 3019 positions of a vCard as given in [RFC6530]. In this example, the 3020 following data corresponds to the following positional meanings: 3022 1. post office box - not applicable, empty string 3024 2. extended address (e.g., apartment or suite number) - Suite 1234 3026 3. street address - 4321 Rue Somewhere 3028 4. locality (e.g., city) - Quebec 3030 5. region (e.g., state or province) - QC 3032 6. postal code - G1V 2M2 3034 7. country name (full name) - Canada 3036 The second example is an unstructured address. It uses the label 3037 attribute, which is a string containing a newline (\n) character to 3038 separate address components in an unordered, unspecified manner. 3039 Note that in this example the structured address array is still given 3040 but that each string is an empty string. 3042 Appendix D. Secure DNS 3044 Section 6.3 defines the "secureDNS" member to represent secure DNS 3045 information about domain names. 3047 DNSSEC provides data integrity for DNS through digital signing of 3048 resource records. To enable DNSSEC, the zone is signed by one or 3049 more private keys and the signatures stored as RRSIG records. To 3050 complete the chain of trust in the DNS zone hierarchy, a digest of 3051 each DNSKEY record (which contains the public key) must be loaded 3052 into the parent zone, stored as Delegation Signer (DS) records and 3053 signed by the parent's private key (RRSIG DS record), "Resource 3054 Records for the DNS Security Extensions" [RFC4034]. Creating the DS 3055 records in the parent zone can be done by the registration authority, 3056 "Domain Name System (DNS) Security Extensions Mapping for the 3057 Extensible Provisioning Protocol (EPP)" [RFC5910]. 3059 Only DS related information is provided by RDAP, since other 3060 information is not generally stored in the registration database. 3061 Other DNSSEC related information can be retrieved with other DNS 3062 tools such as dig. 3064 The domain object class (Section 6.3) can represent this information 3065 using either the 'dsData' or 'keyData' object arrays. Client 3066 implementers should be aware that some registries do not collect or 3067 do not publish all of the secure DNS meta-information. 3069 Appendix E. Motivations for Using JSON 3071 This section addresses a common question regarding the use of JSON 3072 over other data formats, most notably XML. 3074 It is often pointed out that many DNRs and one RIR support the EPP 3075 [RFC3730] standard, which is an XML serialized protocol. The logic 3076 is that since EPP is a common protocol in the industry it follows 3077 that XML would be a more natural choice. While EPP does influence 3078 this specification quite a bit, EPP serves a different purpose which 3079 is the provisioning of Internet resources between registries and 3080 accredited registrars and serves a much narrower audience than that 3081 envisioned for RDAP. 3083 By contrast, RDAP has a broader audience and is designed for public 3084 consumption of data. Experience from RIRs with first generation 3085 RESTful web services for Whois indicate a large percentage of clients 3086 operate within browsers and other platforms where full-blown XML 3087 stacks are not readily available and where JSON is a better fit. 3089 Additionally, while EPP is used in much of the DNR community it is 3090 not a universal constant in that industry. And finally, EPP's use of 3091 XML predates the specification of JSON. If EPP had been defined 3092 today, it may very well have used JSON instead of XML. 3094 Beyond the specific DNR and RIR communities, the trend in the broader 3095 Internet industry is also switching to JSON over XML, especially in 3096 the area of RESTful web services (see [JSON_acendancy]). Studies 3097 have also found that JSON is generally less bulky and consequently 3098 faster to parse (see [JSON_performance_study]). 3100 Appendix F. Changelog 3102 Initial -00 Adopted as working group document 2012-September-18. 3104 -01 3105 Minor spelling corrections. Changed "Registry Data" to 3106 "Registration Data" for the sake of consistency. 3108 Transitioned to RFC 5988 links and relationship types from our 3109 own custom "uris" structure. 3111 Some examples had 'status' as a string. Those have been 3112 corrected as 'status' is always an array of strings. 3114 Domain variants can now have a multi-valued relationship with 3115 domain registrations. 3117 "names" in the entity object class was changed to 3118 "entityNames". 3120 Some IP address examples change to IPv6. 3122 Change phone number examples and added reference to E.164. 3124 Added section on motivations for using JSON. 3126 Added error response body section. 3128 Added JSON naming section. 3130 Added common data structures section. 3132 Added the IANA Considerations section and the media type 3133 registration. 3135 Added 'lang' name/value. 3137 Added internationalization considerations section. 3139 -02 3141 Removed level from media type registration. 3143 Textual changes as given by Ed Lewis. 3145 Fixed object class linking example noted by Francisco Obispo 3147 Fixed a lot of other examples called out by Alex Sergeyev 3149 Added a note that JSON names are case sensitive 3151 Added 'status' to IP networks as suggested by Alex Sergeyev 3153 -03 3155 Added jCard verbiage and examples and deleted overlapping 3156 contact information and the appendix on postal addresses 3158 Removed the IANA considerations as they have been moved to 3159 another document 3161 Changed the remarks structure to be like notices 3163 Reordering and rewording some of the sections so they flow 3164 better 3166 Added note about object class "self" links 3168 Changed ipAddresses in nameserver object class to separate out 3169 v6 from v4 3171 Changed IP network version identifier from integer to string to 3172 be more consistent with ipAddresses identifier in nameserver 3173 object classes 3175 Changed DNS names to LDH names and Unicode names 3177 Modified the definition of 'conjoined' variant relationship so 3178 it was circular 3180 Added 'proxy', 'private', 'redacted', and 'obscured' status 3181 values (most useful for entities). 3183 Added a privacy considerations section 3185 Added a security considerations section 3187 Added 'reseller' and 'sponsor' to the list of entity roles 3189 Added the 'events' common data structure 3191 Added 'asEventActor' to entities 3193 Added appendix on event modeling 3195 Removed the subclasses/superclassing between RIRs/DNRs for 3196 entity and domain object classes 3198 Change suggested status/relation/etc values to be case/spacing 3199 consistent 3200 Normalized some of the definitions of object class members 3202 Modifying the JSON signaling section to reference the guidance 3203 in draft-ietf-weirds-using-http 3205 Changed the text regarding the process of unknown JSON 3206 attributes 3208 -04 3210 'description' removed from IP network and autnum because it is 3211 redundant with the remarks structure. 3213 Added 'entities' array to nameservers. 3215 Added 'status' to autnum. 3217 Added 'publicIds' to entity and domain. 3219 Added embedded entities to the entity object class. 3221 Added 'idnTable' to variants objects in domain object class. 3223 Changed the numbers for startNum and endNum in autnum to 3224 numbers instead of strings. 3226 Added an example for error response with full rdapConformance 3227 and notices. 3229 Added a section discussing help. 3231 Changed entities to use vcardArray and changed the examples to 3232 be current with jCard. 3234 Added a section on structured vs unstructured addresses. 3236 Added associated to the list of status values. 3238 Added a secure DNS section changed the 'delegationKey' object 3239 into the 'secureDNS' object. 3241 Changed the suggested values to an IANA registry. 3243 Added 'proxy' to the list of entity roles. 3245 Authors' Addresses 3246 Andrew Lee Newton 3247 American Registry for Internet Numbers 3248 3635 Concorde Parkway 3249 Chantilly, VA 20151 3250 US 3252 Email: andy@arin.net 3253 URI: http://www.arin.net 3255 Scott Hollenbeck 3256 Verisign Labs 3257 12061 Bluemont Way 3258 Reston, VA 20190 3259 US 3261 Email: shollenbeck@verisign.com 3262 URI: http://www.verisignlabs.com/