idnits 2.17.1 draft-ietf-weirds-json-response-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' Security considerations: n/a' ) ** 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 195: '... those telephone numbers in [E164] format, however clients MUST be...' RFC 2119 keyword, line 214: '... Clients processing JSON [RFC4627] responses SHOULD ignore values...' RFC 2119 keyword, line 215: '...ized names. Servers MAY insert values...' RFC 2119 keyword, line 218: '... SHOULD have names prefixed with a s...' RFC 2119 keyword, line 220: '... the meaningful name, SHOULD adhere to...' (8 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 2, 2012) is 4155 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) == Unused Reference: 'RFC0791' is defined on line 1375, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 1381, 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 (-18) exists of draft-ietf-weirds-rdap-query-00 == Outdated reference: A later version (-15) exists of draft-ietf-weirds-using-http-01 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-using-http' -- Possible downref: Non-RFC (?) normative reference: ref. 'E164' -- Obsolete informational reference (is this intentional?): RFC 3730 (Obsoleted by RFC 4930) Summary: 6 errors (**), 0 flaws (~~), 5 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: June 5, 2013 Verisign Labs 6 December 2, 2012 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-weirds-json-response-01 11 Abstract 13 This document describes JSON data structures representing 14 registration information maintained by Regional Internet Registries 15 (RIRs) and Domain Name Registries (DNRs). These data structures are 16 used to form Registration Data Access Protocol (RDAP) query 17 responses. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at 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 June 5, 2013. 36 Copyright Notice 38 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 5 55 3. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 6 56 4. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 8 57 4.1. Signaling . . . . . . . . . . . . . . . . . . . . . . . . 8 58 4.2. Naming . . . . . . . . . . . . . . . . . . . . . . . . . . 8 59 5. Common Data Structures . . . . . . . . . . . . . . . . . . . . 10 60 5.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . . 10 61 5.2. Notices . . . . . . . . . . . . . . . . . . . . . . . . . 10 62 5.3. Language Identifier . . . . . . . . . . . . . . . . . . . 11 63 5.4. An Example . . . . . . . . . . . . . . . . . . . . . . . . 12 64 6. Object Class Links . . . . . . . . . . . . . . . . . . . . . . 13 65 7. The Entity Object Class . . . . . . . . . . . . . . . . . . . 14 66 7.1. The RIR Entity Object Class . . . . . . . . . . . . . . . 15 67 7.2. The DNR Entity Object Class . . . . . . . . . . . . . . . 16 68 8. The Nameserver Object Class . . . . . . . . . . . . . . . . . 19 69 9. The Domain Object Class . . . . . . . . . . . . . . . . . . . 21 70 9.1. The RIR Domain Object Class . . . . . . . . . . . . . . . 21 71 9.2. The DNR Domain Object Class . . . . . . . . . . . . . . . 24 72 10. The IP Network Object Class . . . . . . . . . . . . . . . . . 29 73 11. Autonomous System Number Entity Object Class . . . . . . . . . 32 74 12. Error Response Body . . . . . . . . . . . . . . . . . . . . . 35 75 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 76 14. Internationalization Considerations . . . . . . . . . . . . . 37 77 14.1. Character Encoding . . . . . . . . . . . . . . . . . . . . 37 78 14.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 37 79 14.3. Language Tags . . . . . . . . . . . . . . . . . . . . . . 37 80 14.4. Internationalized Domain Names . . . . . . . . . . . . . . 37 81 15. Contributing Authors and Acknowledgements . . . . . . . . . . 38 82 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 39 83 16.1. Normative References . . . . . . . . . . . . . . . . . . . 39 84 16.2. Informative References . . . . . . . . . . . . . . . . . . 40 85 Appendix A. Suggested Values . . . . . . . . . . . . . . . . . . 41 86 A.1. Status . . . . . . . . . . . . . . . . . . . . . . . . . . 41 87 A.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 41 88 A.3. Variant Relations . . . . . . . . . . . . . . . . . . . . 42 89 Appendix B. Suggested Data Modeling with the Entity Object 90 Class . . . . . . . . . . . . . . . . . . . . . . . . 43 91 B.1. Registrants and Contacts . . . . . . . . . . . . . . . . . 43 92 B.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . . 44 93 Appendix C. IDN Query and Response Model . . . . . . . . . . . . 46 94 Appendix D. Postal Addresses vs Location . . . . . . . . . . . . 47 95 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 48 96 Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . . 49 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 50 99 1. Introduction 101 This document describes responses in the JSON [RFC4627] format for 102 the RESTful web queries as defined by UNIFIED-RDAP-QUERY 103 [I-D.ietf-weirds-rdap-query]. 105 The data model for the responses consists of two major categories: 106 responses returned by Regional Internet Registries (RIRs) for 107 registrations data related to IP addresses, reverse DNS names, and 108 Autonomous System numbers; and responses returned by Domain Name 109 Registries (DNRs) for registration data related to forward DNS names. 110 Where overlap exists between RIR and DNR response object classes, the 111 RIR object classes are a proper subset of the DNR object classes. 112 The current division between RIR and DNR object classes is given to 113 illustrate an expectation of what data may be expected from an RIR vs 114 a DNR. However, implementers should be aware that RIRs are not 115 limited to the data in the RIR object classes (as an example, some 116 RIRs have a notion of "status" for entities as defined in the DNR 117 entity object class and may at some point start publishing that 118 data). 120 Object classes defined in this document do not represent the full 121 range of data that any registry may wish to publish. Section 4.2 122 defines a JSON extension mechanism that maybe used by registries to 123 insert registry specific data values. 125 2. Terminology and Definitions 127 The following list describes terminology and definitions used 128 throughout this document: 130 DNR: "Domain Name Registry". 132 member: data found with in an object as defined by JSON 133 [RFC4627]. 135 object: a data structure as defined by JSON [RFC4627]. 137 object class: the definition of members that may be found in JSON 138 objects described in this document. 140 object instance: an instantiation or specific instance of an object 141 class. 143 RDAP: "Registration Data Access Protocol". 145 RIR: "Regional Internet Registry". 147 3. Common Data Types 149 JSON [RFC4627] defines the data types of a number, character string, 150 boolean, array, object and null. This section describes the 151 semantics and/or syntax reference for data types used in this 152 document derived from the JSON character string. 154 'handle': DNRs and RIRs have registry-unique identifiers that may 155 be used to specifically reference an object instance. The 156 semantics of this data type as found in this document is to be a 157 registry-unique reference to the closest enclosing object where 158 the value is found. The data type names 'registryId', 'roid', 159 'nic-handle', 'registrationNo', etc... are terms often synonymous 160 with this data type. In this document, the term 'handle' is used. 161 The term exposed to users by clients is a presentation issue 162 beyond the scope of this document. 164 IPv4 addresses: The representation of IPv4 addresses in this 165 document uses the dotted-decimal notation described in [RFC1166]. 166 An example of this textual representation is '192.0.2.0'. 168 IPv6 addresses: The representation of IPv6 addresses in this 169 document follow the forms outlined in [RFC5952]. An example of 170 this textual representation is '2001:db8::1:0:0:1'. 172 country codes: Where the identity of a geopolitical nation or 173 country is needed, these identities are represented with the 174 alpha-2 or 2 character country code designation as defined in 175 [ISO.3166.1988]. The alpha-2 representation is used because it is 176 freely available whereas the alpha-3 and numeric-3 standards are 177 not. 179 domain names: Textual representations of DNS names follow the rules 180 set forth in [RFC4343], specifically the case insensitivity and 181 character escaping rules. Trailing periods are optional for both 182 input and output. 184 email addresses: Textual representations of email addresses follow 185 the syntax defined in [RFC5322]. 187 dates and times: The syntax for values denoting dates and times is 188 defined in [RFC3339]. 190 URIs: The syntax for values denoting a Uniform Resource Identifier 191 (URI) is defined by [RFC3986]. 193 Many of the object classes defined in this document contain values 194 representing telephone numbers. Servers are encouraged to provide 195 those telephone numbers in [E164] format, however clients MUST be 196 prepared for telephone numbers that do not adhere to the [E164] 197 standard. 199 Postal addresses also appear in some of the object classes. This 200 document specifies no standard for postal addresses as many 201 registries would have to undergo severe data cleanup efforts to meet 202 such standards. 204 4. Use of JSON 206 4.1. Signaling 208 Clients may signal their desire for JSON using the "application/json" 209 media type or the more specific media type "application/rdap" as 210 specified in Section 13. 212 4.2. Naming 214 Clients processing JSON [RFC4627] responses SHOULD ignore values 215 associated with unrecognized names. Servers MAY insert values 216 signified by names into the JSON responses which are not specified in 217 this document. Insertion of unspecified values into JSON responses 218 SHOULD have names prefixed with a short identifier followed by an 219 underscore followed by a meaningful name. The full JSON name, the 220 prefix plus the underscore plus the meaningful name, SHOULD adhere to 221 the character and name limitations of the prefix registry described 222 in [I-D.ietf-weirds-using-http]. 224 Consider the following JSON response with JSON names. "handle" and 225 "remarks" are JSON names specified in this document. 227 { 228 "handle" : "ABC123", 229 "remarks" : 230 [ 231 "she sells seas shells", 232 "down by the seashore" 233 ] 234 } 236 Figure 1 238 If The Registry of the Moon desires to express information not found 239 in this specification, it might select "lunarNic" as its identifying 240 prefix and insert, as an example, the name 241 "lunarNic_beforeOneSmallStep" to signify registrations occuring 242 before the first moon landing and the name 243 "lunarNic_harshMistressNotes" containing other descriptive text. 245 Consider the following JSON response with JSON names, some of which 246 should be ignored by clients without knowledge of their meaning. 248 { 249 "handle" : "ABC123", 250 "lunarNic_beforeOneSmallStep" : "TRUE THAT!", 251 "remarks" : 252 [ 253 "she sells seas shells", 254 "down by the seashore" 255 ], 256 "lunarNic_harshMistressNotes" : 257 [ 258 "In space,", 259 "nobody can hear you scream." 260 ] 261 } 263 Figure 2 265 Insertion of unrecognized names ignored by clients may also be used 266 for future revisions to this specification. 268 Clients processing JSON responses MUST be prepared for values 269 specified in this document to be absent from a response as no JSON 270 value listed is required to appear in a response. In other words, 271 servers MAY remove values as is needed by the policies of the server 272 operator. 274 5. Common Data Structures 276 This section defines three common data structures to be used in 277 respones. Each of these datatypes MAY appear within any object class 278 of a response, but the intended purpose is that they will be mostly 279 used in the top-most object class of a response. 281 5.1. RDAP Conformance 283 The first data structure is named "rdapConformance" and is simply an 284 array of strings, each providing a hint as to the specifications used 285 in the construction of the response. 287 An example rdapConformance data structure. 289 "rdapConformance" : 290 [ 291 "rdap_level_0" 292 ] 294 Figure 3 296 The string literal "rdap_level_0" signifies conformance with this 297 specification. When custom JSON values are inserted into responses, 298 conformance to those custom specifications should use a string 299 prefixed with the appropriate identifier from the IANA prefix 300 identifier registry specified in [I-D.ietf-weirds-using-http]. For 301 example, if the fictional Registry of the Moon want to signify that 302 their JSON responses are conformant with their registered extensions, 303 the string used might be "lunarNIC_level_0". 305 Example rdapConformance structure with custom extensions noted. 307 "rdapConformance" : 308 [ 309 "rdap_level_0", 310 "lunarNic_level_0" 311 ] 313 Figure 4 315 5.2. Notices 317 The second data structure is named "notices" and is an array of 318 objects. Each object contains a "title" string representing the 319 title of the notice object, an array of strings named "description" 320 for the purposes of conveying any descriptive text about the notice, 321 and an optional "links" object as described in Section 6. 323 An exmaple of the notices data structure. 325 "notices" : 326 [ 327 { 328 "title" : "Terms of Use", 329 "description" : 330 [ 331 "This service is subject to The Registry of the Moons", 332 "terms of service." 333 ], 334 "links" : 335 [ 336 { 337 "value" : "http://example.net/entity/XXXX" 338 "rel" : "alternate", 339 "type" : "text/html", 340 "href" : "http://www.example.com/terms_of_use.html" 341 } 342 ] 343 } 344 ] 346 Figure 5 348 5.3. Language Identifier 350 The third data structure is a simple JSON name/value of "lang" with a 351 string containing a language identifier as described by [RFC5646]. 353 "lang" : "mn-Cyrl-MN" 355 Figure 6 357 5.4. An Example 359 This is an example response with both rdapConformance and notices 360 embedded. 362 { 363 "rdapConformance" : 364 [ 365 "rdap_level_0" 366 ] 367 "notices" : 368 [ 369 { 370 "title" : "Content Redacted", 371 "description" : 372 [ 373 "Without full authorization, content has been redacted.", 374 "Sorry, dude!" 375 ], 376 "links" : 377 [ 378 { 379 "value" : "http://example.net/ip/192.0.2.0/24" 380 "rel" : "alternate", 381 "type" : "text/html", 382 "href" : "http://www.example.com/redaction_policy.html" 383 } 384 ] 385 } 386 ] 387 "lang" : "en" 388 "startAddress" : "192.0.2.0", 389 "endAddress" : "192.0.2.255", 390 "handle" : "XXXX-RIR", 391 "ipVersion" : 4, 392 "name": "NET-RTR-1", 393 "description" : [ "A network used for example documentation" ], 394 "parentHandle" : "YYYY-RIR", 395 "remarks" : 396 [ 397 "she sells seas shells", 398 "down by the seashore" 399 ] 400 } 402 Figure 7 404 6. Object Class Links 406 Each object class defined in this document may have links to other 407 resources on the Internet. The relationship of these links is 408 defined by the IANA registry described by [RFC5988]. 410 The following is an example of the link structure of object classes 412 { 413 "value" : "http://example.com/context_uri", 414 "rel" : "self", 415 "href" : "http://example.com/target_uri", 416 "hreflang" : [ "en, "ch" ], 417 "title" : [ "title1", "title2" ], 418 "media" : "screen", 419 "type" : "application/json" 420 } 422 The JSON name/values of "rel", "href", "hreflang", "title", "media", 423 and "type" correspond to values found in Section 5 of [RFC5988]. The 424 "value" JSON value is the context URI as described by [RFC5988]. The 425 "value", "rel", and "href" JSON values MUST be specified. All other 426 JSON values are optional. 428 Within an object class, these structures are to be in an array named 429 "links". 431 This is an example of the "links" array as it might be found in an 432 object class. 434 "links" : 435 [ 436 { 437 "value" : "http://example.com/ip/2001:db8::123", 438 "rel" : "self", 439 "href" : "http://example.com/ip/2001:db8::123", 440 }, 441 { 442 "value" : "http://example.com/ip/2001:db8::123", 443 "rel" : "up", 444 "href" : "http://example.com/ip/2001:db8::/48", 445 } 447 ] 449 7. The Entity Object Class 451 The entity object class appears throughout this document and is an 452 appropriate response for the /entity/XXXX query defined in UNIFIED- 453 RDAP-QUERY [I-D.ietf-weirds-rdap-query]. This object class 454 represents the information of organizations, corporations, 455 governments, non-profits, clubs, individual persons, and informal 456 groups of people. All of these representations are so similar that 457 it is best to represent them in JSON [RFC4627] with one construct, 458 the entity object class, to aid in the re-use of code by 459 implementers. 461 Many of the members of the entity object class are repeated in other 462 object classes described later in this document. 464 7.1. The RIR Entity Object Class 466 The following is an example of an RIR entity: 468 { 469 "handle" : "XXXX", 470 "entityNames": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 471 "roles" : [ "registrant" ], 472 "postalAddress" : 473 [ 474 "123 Maple Ave", 475 "Suite 90001", 476 "Vancouver", 477 "BC", 478 "12393" 479 ], 480 "emails" : [ "joe@bob.com", "bob@joe.com" ], 481 "phones" : 482 { 483 "office" : [ "1-958-555-4321", "1-958-555-4322" ], 484 "fax" : [ "1-958-555-4323" ], 485 "mobile" : [ "1-958-555-4324" ] 486 }, 487 "remarks" : 488 [ 489 "she sells seas shells", 490 "down by the seashore" 491 ], 492 "links" : 493 [ 494 { 495 "value" : "http://example.com/entity/XXXX", 496 "rel" : "self", 497 "href" : "http://example.com/entity/XXXX" 498 }, 499 ], 500 "registrationDate" : "1990-12-31T23:59:60Z", 501 "lastChangedDate" : "1990-12-31T23:59:60Z", 502 "lastChangedBy" : "joe@bob.com" 503 } 505 This object as the following members. 507 o handle -- a string representing an registry unique identifier of 508 the entity 510 o entityNames -- an array of strings, each signifying the name of 511 the entity 513 o roles -- an array of strings, each signifying the relationship an 514 object would have with its closest containing object. 516 o postalAddress -- an array of string, each representing a line in a 517 postal address. 519 o emails -- an array of strings, each containing an email address 520 for the entity 522 o phones -- an object containing telephone information associated 523 with the entity, with the following members: 525 * office -- an array of strings, each being a telephone number 527 * fax -- an array of strings, each being a telephone number 529 * mobile -- an array of strings, each being a telephone number 531 o remarks -- an array of strings, each containing comments about the 532 entity 534 o links -- see Section 6 536 o registrationDate -- a string containing the date the entity was 537 registered 539 o lastChangedDate -- a string containing the date of last change 540 made to the entity 542 o lastChangedBy -- a string containing an identifier of the party 543 responsible for the last change made to the entity registration 545 7.2. The DNR Entity Object Class 547 The DNR entity object class is a superset of the RIR entity object 548 class (Section 7.1). It has the following additional members: 550 o registrationBy -- a string containing an identifier of the party 551 responsible for the registration of the entity 553 o sponsoredBy -- a string containing an identifier of the party 554 through which the registration was made, such as an IANA approved 555 registrar 557 o resoldBy -- a string containing an identifier of the party 558 originating the registration of the entity. 560 o status -- an array of strings indicating the state of the entity 562 o port43 -- a string containing the fully-qualified host name of the 563 WHOIS [RFC3912] server where the object instance may be found. 565 The following is an example of a DNR entity: 567 { 568 "handle" : "XXXX", 569 "entityNames": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 570 "status" : [ "validated", "locked" ], 571 "postalAddress" : 572 [ 573 "123 Maple Ave", 574 "Suite 90001", 575 "Vancouver", 576 "BC", 577 "12393" 578 ], 579 "emails" : [ "joe@bob.com", "bob@joe.com" ], 580 "phones" : 581 { 582 "office" : [ "1-958-555-4321", "1-958-555-4322" ], 583 "fax" : [ "1-958-555-4323" ], 584 "mobile" : [ "1-958-555-4324" ] 585 }, 586 "remarks" : 587 [ 588 "she sells seas shells", 589 "down by the seashore" 590 ], 591 "links" : 592 [ 593 { 594 "value" : "http://example.com/entity/XXXX", 595 "rel" : "self", 596 "href" : "http://example.com/entity/XXXX" 597 }, 598 ], 599 "port43" : "whois.example.net", 600 "registrationDate" : "1990-12-31T23:59:60Z", 601 "registrationBy" : "ABC123", 602 "lastChangedDate" : "1990-12-31T23:59:60Z", 603 "lastChangedBy" : "ABC123", 604 "sponsoredBy" : "SponsorXYZ", 605 "resoldBy" : "ResellerPDQ" 606 } 608 8. The Nameserver Object Class 610 The nameserver object class is used by both RIRs and DNRs. Unlike 611 other object classes used by both registries where the RIR object 612 class is a subset of the DNR object class, a clear delineation is not 613 made with the nameserver object class because some DNRs have the same 614 or a similar registration model as the RIRs. RIRs and some DNRs 615 register or expose nameserver information as an attribute of a domain 616 name, while other DNRs model nameservers as "first class objects". 618 The nameserver object class accommodates both models and degrees of 619 variation in between. 621 The following is an example of a nameserver object. 623 { 624 "handle" : "XXXX", 625 "name" : "ns1.example.com", 626 "status" : [ "active" ], 627 "ipAddresses" : [ "192.0.2.1", "192.0.2.2" ], 628 "remarks" : 629 [ 630 "she sells seas shells", 631 "down by the seashore" 632 ], 633 "links" : 634 [ 635 { 636 "value" : "http://example.net/nameserver/xxxx", 637 "rel" : "self", 638 "href" : "http://example.net/nameserver/xxxx" 639 } 640 ], 641 "port43" : "whois.example.net", 642 "registrationDate" : "1990-12-31T23:59:60Z", 643 "registrationBy" : "ABC123", 644 "lastChangedDate" : "1990-12-31T23:59:60Z", 645 "lastChangedBy" : "ABC123", 646 "sponsoredBy" : "SponsorXYZ", 647 "resoldBy" : "ResellerPDQ" 648 } 650 Figure 8 652 Figure 8 is an example of a nameserver object with all values given. 653 Registries using a first-class nameserver data model would embed this 654 in domain objects as well as allowing references to it with the 655 /nameserver query type (all depending on the registry operators 656 policy). Other registries may pare back the information as needed. 657 Figure 9 is an example of a nameserver object as would be found in 658 RIRs and some DNRs, while Figure 10 is an example of a nameserver 659 object as would be found in other DNRs. 661 The following is an example of the simplest nameserver object. 663 { 664 "name" : "ns1.example.com" 665 } 667 Figure 9 669 The following is an example of a simple nameserver object that might 670 be commonly used by DNRs. 672 { 673 "name" : "ns1.example.com", 674 "ipAddresses" : [ "2001:db8::123", "2001:db8::124" ] 675 } 677 Figure 10 679 The nameserver object class has the following members: 681 o handle -- a string representing an registry unique identifier of 682 the nameserver 684 o name -- a string containing the DNS name of the nameserver 686 o ipAddresses -- an array of strings containing IPv4 and/or IPv6 687 addresses of the nameserver 689 The members "status", "remarks", "links", "port43", "sponsoredBy", 690 "resoldBy", "registrationBy", "registrationDate", "lastChangedDate", 691 and "lastChangedBy" take the same form of the members of the same 692 name of the entity object (Section 7). 694 9. The Domain Object Class 696 The domain object class represents a DNS name and point of 697 delegation. For RIRs these delegation points are in the reverse DNS 698 tree, whereas for DNRs these delegation points are in the forward DNS 699 tree. The RIR domain object class is a subset of the DNR object 700 class. 702 In both cases, the high level structure of the domain object class 703 consists of information about the domain registration, nameserver 704 information related to the domain name, and entities related to the 705 domain name (e.g. registrant information, contacts, etc...). 707 The following is an elided example of the domain object showing the 708 high level structure. 710 { 711 "handle" : "XXX", 712 "name" : "blah.example.com", 713 ... 714 "nameServers" : 715 [ 716 ... 717 ], 718 ... 719 "entities" : 720 [ 721 ... 722 ] 723 } 725 9.1. The RIR Domain Object Class 727 The following is an example of a JSON object representing a reverse 728 DNS delegation point or the RIR domain object class. 730 { 731 "handle" : "XXXX", 732 "name" : "192.in-addr.arpa", 733 "nameServers" : 734 [ 735 { "name" : "ns1.rir.net" }, 736 { "name" : "ns2.rir.net" } 737 ], 738 "delegationKeys" : 740 [ 741 { 742 "algorithm": 7, 743 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 744 "digestType" : 1, 745 "keyTag" : 53814 746 } 747 ], 748 "remarks" : 749 [ 750 "she sells seas shells", 751 "down by the seashore" 752 ], 753 "links" : 754 [ 755 { 756 "value": "http://example.net/domain/XXXX", 757 "rel" : "self", 758 "href" : "http://example.net/domain/XXXXX" 759 } 760 ], 761 "registrationDate" : "1990-12-31T23:59:60Z", 762 "lastChangedDate" : "1990-12-31T23:59:60Z", 763 "lastChangedBy" : "joe@bob.com", 764 "entities" : 765 [ 766 { 767 "handle" : "XXXX", 768 "entityNames": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 769 "roles" : [ "registrant" ], 770 "postalAddress" : 771 [ 772 "123 Maple Ave", 773 "Suite 90001", 774 "Vancouver", 775 "BC", 776 "12393" 777 ], 778 "emails" : [ "joe@bob.com", "bob@joe.com" ], 779 "phones" : 780 { 781 "office" : [ "1-958-555-4321", "1-958-555-4322" ], 782 "fax" : [ "1-958-555-4323" ], 783 "mobile" : [ "1-958-555-4324" ] 784 }, 785 "remarks" : 786 [ 787 "she sells seas shells", 788 "down by the seashore" 789 ], 790 "links" : 791 [ 792 { 793 "value": "http://example.net/entity/xxxx" 794 "rel" : "self", 795 "href" : "http://example.net/entity/xxxx" 796 } 797 ], 798 "registrationDate" : "1990-12-31T23:59:60Z", 799 "lastChangedDate" : "1990-12-31T23:59:60Z", 800 "lastChangedBy" : "joe@bob.com" 801 } 802 ] 803 } 805 The following is a description of the members of this object: 807 o handle -- a string representing a registry unique identifier of 808 the domain object instance 810 o name -- a string denoting the DNS zone name, which is a domain 811 name 813 o nameservers -- an array of nameserver objects as defined by 814 Section 8 816 o delegationKeys -- an array of objects, each with the following 817 members: 819 * algorithm -- an integer as specified by the algorithm field of 820 a DNS DS record as specified by RFC 4034 [RFC4034] in 821 presentation format 823 * digest -- an string as specified by the digest field of a DNS 824 DS record as specified by RFC 4034 in presentation format 826 * digestType -- an integer as specified by the digest type field 827 of a DNS DS record as specified by RFC 4034 in presentation 828 format 830 * keyTag -- an integer as specified by the key tag field of a DNS 831 DS record as specified by RFC 4034 in presentation format 833 o entities -- an array of entity objects as defined by Section 7.1. 835 The members "remarks", "links", "registrationDate", 836 "lastChangedDate", and "lastChangedBy" take the same form of the 837 members of the same name of the entity object (Section 7). 839 9.2. The DNR Domain Object Class 841 The DNR domain object class is a superset of the RIR domain object 842 class (Section 9.1) and has the following additional members. 844 o variants -- an array of objects, each containing the following 845 values: 847 * relation -- an array of strings, with each string denoting the 848 relationship between the variants and the containing domain 849 object. 851 * variantNames -- an array of strings, each being a variant 852 domain of the containing domain object. 854 o expirationDate -- a string containing the date and time this 855 domain name registration will expire 857 o registrationBy -- a string containing an identifier of the party 858 responsible for the registration of the domain name 860 o sponsoredBy -- a string containing an identifier of the party 861 through which the registration was made, such as an IANA approved 862 registrar 864 o resoldBy -- a string containing an identifier of the party 865 originating the registration of the domain name 867 o status -- an array of strings indicating the state of the domain 868 name 870 o transferDate -- a string containing the date and time this domain 871 name was transferred 873 o port43 -- a string containing the fully-qualified host name of the 874 WHOIS [RFC3912] server where the object instance may be found. 876 The following is an example of a JSON object representing a forward 877 DNS delegation point or the DNR domain object class. 879 { 880 "handle" : "XXXX", 881 "name" : "blah.example.com", 882 "variants" : 883 [ 884 { 885 "relation" : [ "registered", "conjoined" ], 886 "variantNames" : [ "blah2.example.com", "blah3.example.com" ] 887 }, 888 { 889 "relation" : [ "unregistered", "restrictedRegistration" ], 890 "variantNames" : [ "blah3.example.com", "blah4.example.com" ] 891 } 892 ], 893 "status" : [ "locked", "transferProhibited" ], 894 "nameServers" : 895 [ 896 { 897 "handle" : "XXXX", 898 "name" : "ns1.example.com", 899 "status" : [ "active" ], 900 "ipAddresses" : 901 [ 902 "2001:db8::123", "2001:db8::124", 903 "192.0.2.1", "192.0.2.2" 904 ], 905 "remarks" : 906 [ 907 "she sells seas shells", 908 "down by the seashore" 909 ], 910 "links" : 911 [ 912 { 913 "value" : "http://example.net/nameserver/XXXX" 914 "rel" : "self", 915 "href" : "http://example.net/nameserver/XXXX" 916 } 917 ], 918 "registrationDate" : "1990-12-31T23:59:60Z", 919 "registrationBy" : "ABC123", 920 "lastChangedDate" : "1990-12-31T23:59:60Z", 921 "lastChangedBy" : "ABC123", 922 "sponsoredBy" : "SponsorXYZ", 923 "resoldBy" : "ResellerPDQ" 924 }, 925 { 926 "handle" : "XXXX", 927 "name" : "ns2.example.com", 928 "status" : [ "active" ], 929 "ipAddresses" : 930 [ 931 "2001:db8::125", "2001:db8::126", 932 "192.0.2.3", "192.0.2.4" 933 ], 934 "remarks" : 935 [ 936 "she sells seas shells", 937 "down by the seashore" 938 ], 939 "links" : 940 [ 941 { 942 "value" : "http://example.net/nameserver/XXXX", 943 "rel" : "self", 944 "href" : "http://example.net/nameserver/XXXX" 945 } 946 ], 947 "registrationDate" : "1990-12-31T23:59:60Z", 948 "registrationBy" : "ABC123", 949 "lastChangedDate" : "1990-12-31T23:59:60Z", 950 "lastChangedBy" : "ABC123", 951 "sponsoredBy" : "SponsorXYZ", 952 "resoldBy" : "ResellerPDQ" 953 } 954 ] 955 "delegationKeys" : 956 [ 957 { 958 "algorithm": 7, 959 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 960 "digestType" : 1, 961 "keyTag" : 53814 962 } 963 ], 964 "remarks" : 965 [ 966 "she sells seas shells", 967 "down by the seashore" 968 ], 969 "links" : 970 [ 971 { 972 "value": "http://example.net/domain/XXXX", 973 "rel" : "self", 974 "href" : "http://example.net/domain/XXXX" 975 } 977 ], 978 "port43" : "whois.example.net", 979 "registrationDate" : "1990-12-31T23:59:60Z", 980 "registrationBy" : "ABC123", 981 "lastChangedDate" : "1990-12-31T23:59:60Z", 982 "lastChangedBy" : "ABC123", 983 "sponsoredBy" : "SponsorXYZ", 984 "resoldBy" : "ResellerPDQ", 985 "expirationDate" : "2016-12-31T23:59:60Z", 986 "transferDate" : "1990-12-31T23:59:60Z", 987 "entities" : 988 [ 989 { 990 "handle" : "XXXX", 991 "entityNames": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 992 "status" : [ "validated", "locked" ], 993 "postalAddress" : 994 [ 995 "123 Maple Ave", 996 "Suite 90001", 997 "Vancouver", 998 "BC", 999 "12393" 1000 ], 1001 "emails" : [ "joe@bob.com", "bob@joe.com" ], 1002 "phones" : 1003 { 1004 "office" : [ "1-958-555-4321", "1-958-555-4322" ], 1005 "fax" : [ "1-958-555-4323" ], 1006 "mobile" : [ "1-958-555-4324" ] 1007 }, 1008 "remarks" : 1009 [ 1010 "she sells seas shells", 1011 "down by the seashore" 1012 ], 1013 "links" : 1014 [ 1015 { 1016 "value" : "http://example.net/entity/xxxx" 1017 "rel" : "self", 1018 "href" : "http://example.net/entity/xxxx" 1019 } 1020 ], 1021 "registrationDate" : "1990-12-31T23:59:60Z", 1022 "registrationBy" : "ABC123", 1023 "lastChangedDate" : "1990-12-31T23:59:60Z", 1024 "lastChangedBy" : "ABC123", 1025 "sponsoredBy" : "SponsorXYZ", 1026 "resoldBy" : "ResellerPDQ" 1027 } 1028 ] 1029 } 1031 10. The IP Network Object Class 1033 The IP Network object class models IP network registrations found in 1034 RIRs and is the expected response for the /ip query as defined by 1035 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1036 for DNRs. The high level structure of the IP network object class 1037 consists of information about the network registration and entities 1038 related to the IP network (e.g. registrant information, contacts, 1039 etc...). 1041 The following is an elided example of the IP network object type 1042 showing the high level structure. 1044 { 1045 "handle" : "XXX", 1046 ... 1047 "entities" : 1048 [ 1049 ... 1050 ] 1051 } 1053 The following is an example of the JSON object for the network 1054 registration information 1056 { 1057 "handle" : "XXXX-RIR", 1058 "startAddress" : "2001:db8::0", 1059 "endAddress" : "2001:db8::0:FFFF:FFFF:FFFF:FFFF:FFFF", 1060 "ipVersion" : 6, 1061 "name": "NET-RTR-1", 1062 "description" : [ "A network used for routing" ], 1063 "type" : "DIRECT ALLOCATION", 1064 "country" : "AU", 1065 "parentHandle" : "YYYY-RIR", 1066 "remarks" : 1067 [ 1068 "she sells seas shells", 1069 "down by the seashore" 1070 ], 1071 "links" : 1072 [ 1073 { 1074 "value" : "http://example.ent/ip/2001:db8::/48", 1075 "rel" : "self", 1076 "href" : "http://example.net/ip/2001:db8::/48" 1077 }, 1078 { 1079 "value" : "http://example.net/ip/2001:db8::/48", 1080 "rel" : "up", 1081 "href" : "http://example.net/ip/2001:C00::/23" 1082 }, 1083 ], 1084 "registrationDate" : "20110509", 1085 "lastChangedDate" : "20110509", 1086 "lastChangedBy" : "joe@bob.com", 1087 "entities" : 1088 [ 1089 { 1090 "handle" : "XXXX", 1091 "entityNames": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 1092 "roles" : [ "registrant" ], 1093 "postalAddress" : 1094 [ 1095 "123 Maple Ave", 1096 "Suite 90001", 1097 "Vancouver", 1098 "BC", 1099 "12393" 1100 ], 1101 "emails" : [ "joe@bob.com", "bob@joe.com" ], 1102 "phones" : 1103 { 1104 "office" : [ "1-958-555-4321", "1-958-555-4322" ], 1105 "fax" : [ "1-958-555-4323" ], 1106 "mobile" : [ "1-958-555-4324" ] 1107 }, 1108 "remarks" : 1109 [ 1110 "she sells seas shells", 1111 "down by the seashore" 1112 ], 1113 "links" : 1114 [ 1115 { 1116 "value" : "http://example.net/entity/xxxx", 1117 "rel" : "self", 1118 "href" : "http://example.net/entity/xxxx" 1119 } 1120 ], 1121 "registrationDate" : "1990-12-31T23:59:60Z", 1122 "lastChangedDate" : "1990-12-31T23:59:60Z", 1123 "lastChangedBy" : "joe@bob.com" 1125 } 1126 ] 1127 } 1129 The following is a description of the members of this object: 1131 o handle -- a string representing an RIR unique identifier of the 1132 network registration 1134 o startAddress -- the starting IP address of the network, either 1135 IPv4 or IPv6 1137 o endAddress -- the ending IP address of the network, either IPv4 or 1138 IPv6 1140 o ipVersion -- an integer signifying the IP protocol version of the 1141 network: 4 signifying an IPv4 network, 6 signifying an IPv6 1142 network 1144 o name -- an identifier assigned to the network registration by the 1145 registration holder 1147 o description -- an array of strings containing descriptive text 1148 about the network registration 1150 o type -- a string containing an RIR specific classification of the 1151 network 1153 o country -- a string containing the name of the 2 character country 1154 code of the network 1156 o parentHandle -- a string containing an RIR unique identifier of 1157 the parent network of this network registration 1159 o entities -- an array of entity objects as defined by Section 7.1. 1161 The members "remarks", "links", "registrationDate", 1162 "lastChangedDate", and "lastChangedBy" take the same form of the 1163 members of the same name of the entity object (Section 7.1). 1165 11. Autonomous System Number Entity Object Class 1167 The Autonomous System Number (autnum) object class models Autonomous 1168 System Number registrations found in RIRs and represents the expected 1169 response to an /autnum query as defined by 1170 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1171 for DNRs. The high level structure of the autnum object class 1172 consists of information about the network registration and entities 1173 related to the autnum registration (e.g. registrant information, 1174 contacts, etc...), and is similar to the IP Network entity object 1175 class. 1177 The following is an example of a JSON object representing an autnum. 1179 { 1180 "handle" : "XXXX-RIR", 1181 "startAutnum" : "10", 1182 "endAutnum" : "15", 1183 "name": "AS-RTR-1", 1184 "description" : [ "AS for Exchange" ], 1185 "type" : "DIRECT ALLOCATION", 1186 "country": "AU", 1187 "remarks" : 1188 [ 1189 "she sells seas shells", 1190 "down by the seashore" 1191 ], 1192 "links" : 1193 [ 1194 { 1195 "value" : "http://example.net/autnum/xxxx", 1196 "rel" : "self", 1197 "href" : "http://example.net/autnum/xxxx" 1198 } 1199 ], 1200 "registrationDate" : "20110509", 1201 "lastChangedDate" : "20110509", 1202 "lastChangedBy" : "joe@bob.com", 1203 "entities" : 1204 [ 1205 { 1206 "handle" : "XXXX", 1207 "entityNames": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 1208 "roles" : [ "registrant" ], 1209 "postalAddress" : 1210 [ 1211 "123 Maple Ave", 1212 "Suite 90001", 1213 "Vancouver", 1214 "BC", 1215 "12393" 1216 ], 1217 "emails" : [ "joe@bob.com", "bob@joe.com" ], 1218 "phones" : 1219 { 1220 "office" : [ "1-958-555-4321", "1-958-555-4322" ], 1221 "fax" : [ "1-958-555-4323" ], 1222 "mobile" : [ "1-958-555-4324" ] 1223 }, 1224 "remarks" : 1225 [ 1226 "she sells seas shells", 1227 "down by the seashore" 1228 ], 1229 "links" : 1230 [ 1231 { 1232 "value" : "http://example.net/entity/XXXX", 1233 "rel" : "self", 1234 "href" : "http://example.net/entity/XXXX" 1235 } 1236 ], 1237 "registrationDate" : "1990-12-31T23:59:60Z", 1238 "lastChangedDate" : "1990-12-31T23:59:60Z", 1239 "lastChangedBy" : "joe@bob.com" 1240 } 1241 ] 1242 } 1244 The following is a description of the members of this object: 1246 o handle -- a string representing an RIR unique identifier of the 1247 autnum registration 1249 o startAutnum -- the starting number [RFC5396] in the block of 1250 autonomous system numbers 1252 o endAutnum -- the ending number [RFC5396] in the block of 1253 autonomous system numbers 1255 o name -- an identifier assigned to the autnum registration by the 1256 registration holder 1258 o description -- an array of strings containing descriptive text 1259 about the autnum registration 1261 o type -- a string containing an RIR specific classification of the 1262 autnum 1264 o country -- a string containing the name of the 2 character country 1265 code of the autnum 1267 The members "remarks", "links", "registrationDate", 1268 "lastChangedDate", and "lastChangedBy" take the same form of the 1269 members of the same name of the entity object (Section 7.1). 1271 12. Error Response Body 1273 Some non-answer responses may return entity bodies with information 1274 that could be more descriptive. 1276 The basic structure of that response is an object class containing an 1277 error code number (corresponding to the HTTP response code) followed 1278 by a string named "title" followed by an array of strings named 1279 "description". 1281 This is an example of the JSON version of the common response body. 1283 { 1284 "errorCode": 418 1285 "title": "Your beverage choice is not available", 1286 "description": 1287 [ 1288 "I know coffee has more ummppphhh.", 1289 "But I cannot provide." 1290 ] 1291 } 1293 Figure 11 1295 A client MAY simply use the HTTP response code as the server is not 1296 required to include error data in the response body. However, if a 1297 client wishes to parse the error data, it SHOULD first check that the 1298 Content-Type header contains the appropriate media type. 1300 13. IANA Considerations 1302 This specification registers the "application/rdap" media type. 1304 Type name: application 1306 Subtype name: rdap 1308 Required parameters: n/a 1310 Optional parameters: level 1312 Encoding considerations: n/a 1314 Security considerations: n/a 1316 Interoperability considerations: n/a 1318 Published specification: [[ this document ]] 1320 Applications that use this media type: RDAP 1322 Additional information: n/a 1324 Person & email address to contact for further information: Andy 1325 Newton &andy@hxr.us& 1327 Intended usage: COMMON 1329 Restrictions on usage: none 1331 Author: Andy Newton 1333 Change controller: IETF 1335 14. Internationalization Considerations 1337 14.1. Character Encoding 1339 The default text encoding for JSON and XML responses in RDAP is 1340 UTF-8, and all servers and clients MUST support UTF-8. Servers and 1341 clients MAY optionally support other character encodings. 1343 14.2. URIs and IRIs 1345 [I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in 1346 RDAP. 1348 14.3. Language Tags 1350 Section 5.3 defines the use of language tags in the JSON responses 1351 defined in this document. 1353 14.4. Internationalized Domain Names 1355 Appendix C illustrates the model for query and response regarding 1356 internationalized domain names (IDNs). 1358 15. Contributing Authors and Acknowledgements 1360 This document is derived from original work on RIR response in JSON 1361 by Byron J. Ellacott of APNIC, Arturo L. Servin of LACNIC, Kaveh 1362 Ranjbar of the RIPE NCC, and Andrew L. Newton of ARIN. Additionally, 1363 this document incorporates word on DNR responses in JSON by Ning 1364 Kong, Linlin Zhou, Jiagui Xie, and Sean Shen of CNNIC. 1366 The components of the DNR object classes are derived from a 1367 categorization of WHOIS response formats created by Ning Kong, Linlin 1368 Zhou, and Guangqing Deng of CNNIC, Steve Sheng and Francisco Arias of 1369 ICANN, Ray Bellis of Nominet, and Frederico Neves of NIC.BR. 1371 16. References 1373 16.1. Normative References 1375 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 1376 September 1981. 1378 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 1379 numbers", RFC 1166, July 1990. 1381 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1382 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1383 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1385 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1386 Internet: Timestamps", RFC 3339, July 2002. 1388 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1389 Resource Identifier (URI): Generic Syntax", STD 66, 1390 RFC 3986, January 2005. 1392 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 1393 Rose, "Resource Records for the DNS Security Extensions", 1394 RFC 4034, March 2005. 1396 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 1397 Clarification", RFC 4343, January 2006. 1399 [RFC4627] Crockford, D., "The application/json Media Type for 1400 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1402 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1403 October 2008. 1405 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 1406 Autonomous System (AS) Numbers", RFC 5396, December 2008. 1408 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1409 Languages", BCP 47, RFC 5646, September 2009. 1411 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1412 Address Text Representation", RFC 5952, August 2010. 1414 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1416 [ISO.3166.1988] 1417 International Organization for Standardization, "Codes for 1418 the representation of names of countries, 3rd edition", 1419 ISO Standard 3166, August 1988. 1421 [I-D.ietf-weirds-rdap-query] 1422 Newton, A. and S. Hollenbeck, "RDAP Query Format", 1423 draft-ietf-weirds-rdap-query-00 (work in progress), 1424 September 2011. 1426 [I-D.ietf-weirds-using-http] 1427 Newton, A., Ellacott, B., and N. Kong, "Using HTTP for 1428 RESTful Whois Services by Internet Registries", 1429 draft-ietf-weirds-using-http-01 (work in progress), 1430 May 2012. 1432 [E164] ITU-T, "The International Public Telecommunication Number 1433 Plan", Recommendation E.164, May 1997. 1435 16.2. Informative References 1437 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 1438 September 2004. 1440 [RFC3730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 1441 RFC 3730, March 2004. 1443 [JSON_acendancy] 1444 MacVittie, "The Stealthy Ascendancy of JSON", 04 2011. 1446 [JSON_performance_study] 1447 Montana State University - Bozeman, Montana State 1448 University - Bozeman, Montana State University - Bozeman, 1449 and Montana State University - Bozeman, "Comparison of 1450 JSON and XML Data Interchange Formats: A Case Study", 1451 2009. 1453 Appendix A. Suggested Values 1455 Due to the wide variation between the hundreds of registry operators 1456 and the on-going policy refinement by registry communities, values of 1457 some data cannot be formally standardized. This section lists 1458 suggested values for such data but is not nor will ever be a complete 1459 list of values and their meanings. 1461 A.1. Status 1463 Many of the object classes have a member named 'status'. This member 1464 is an array of strings, with each string denoting a status associated 1465 with the containing object. The following is a list of suggested 1466 values to use in the 'status' array: 1468 o 'validated' -- Signifies that the data of the object instance has 1469 been found to be accurate. This type of status is usually found 1470 on entity object instances to note the validity of identifying 1471 contact information. 1473 o 'update prohibited' -- Updates to the object instance are 1474 forbidden. 1476 o 'transfer prohibited' -- Transfers of the registration from one 1477 registrar to another are forbidden. This type of status normally 1478 applies to DNR domain names. 1480 o 'delete prohibited' -- Deletion of the registration of the object 1481 instance is forbidden. This type of status normally applies to 1482 DNR domain names. 1484 A.2. Roles 1486 Entity object classes have a member named 'roles'. This member is an 1487 array of strings, with each string indicating the role or 1488 relationship the entity object instance has with a containing object, 1489 such as a domain name or IP network. An entity object instance can 1490 have more than one type of relationship with a containing object. 1491 The following is a list of suggested values to use in the 'roles' 1492 array: 1494 o 'registrant' -- The entity object instance is the registrant of 1495 the registration. 1497 o 'tech' -- The entity object instance is a technical contact for 1498 the registration. 1500 o 'admin' -- The entity object instance is an administrative contact 1501 for the registration. 1503 o 'abuse' -- The entity object instance handles network abuse issues 1504 on behalf of the registrant of the registration. 1506 o 'billing' -- The entity object instance handles payment and 1507 billing issues on behalf of the registrant of the registration. 1509 o 'registrar' -- The entity object instance represents the authority 1510 responsible for the registration in the registry. 1512 A.3. Variant Relations 1514 Section 9.2 describes a structure for noting variants of domain names 1515 and the relationship those variants have with a registered domain 1516 name. The following is a list of suggested values to use as the 1517 variant relation values: 1519 o 'registered' -- the variant names are registered in the registry. 1521 o 'unregistered' -- the variant names are not found in the registry. 1523 o 'restrictedRegistration' -- registration of the variant names is 1524 restricted to certain parties or within certain rules. 1526 o 'openRegistration' -- registration of the variant names is 1527 available to generally qualified registrants. 1529 o 'conjoined' -- registration of the variant names is conjoined with 1530 the registration of the containing domain registration. 1532 Appendix B. Suggested Data Modeling with the Entity Object Class 1534 B.1. Registrants and Contacts 1536 This document does not provide specific object classes for 1537 registrants and contacts. Instead the entity object class may be 1538 used to represent a registrant or contact. When the entity object is 1539 embedded inside a containing object such as a domain name or IP 1540 network, the 'roles' string array can be used to signify the 1541 relationship. It is recommended that the values from Appendix A.2 be 1542 used. 1544 The following is an example of an elided containing object with an 1545 embedded entity that is both a registrant and admin contact: 1547 { 1548 ... 1549 "entities" : 1550 [ 1551 { 1552 "handle" : "XXXX", 1553 "entityNames": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 1554 "roles" : [ "registrant", "admin" ], 1555 "postalAddress" : 1556 [ 1557 "123 Maple Ave", 1558 "Suite 90001", 1559 "Vancouver", 1560 "BC", 1561 "12393" 1562 ], 1563 "emails" : [ "joe@bob.com", "bob@joe.com" ], 1564 "phones" : 1565 { 1566 "office" : [ "1-958-555-4321", "1-958-555-4322" ], 1567 "fax" : [ "1-958-555-4323" ], 1568 "mobile" : [ "1-958-555-4324" ] 1569 }, 1570 "remarks" : 1571 [ 1572 "she sells seas shells", 1573 "down by the seashore" 1574 ], 1575 "registrationDate" : "1990-12-31T23:59:60Z", 1576 "lastChangedDate" : "1990-12-31T23:59:60Z", 1577 "lastChangedBy" : "joe@bob.com" 1578 } 1580 ] 1581 } 1583 B.2. Registrars 1585 This document does not provide a specific object class for 1586 registrars, but like registrants and contacts (see Appendix B.1) the 1587 'roles' string array maybe used. 1589 The following is an example of an elided containing object with an 1590 embedded entity that is a registrar: 1592 { 1593 ... 1594 "entities" : 1595 [ 1596 { 1597 "handle" : "XXXX", 1598 "names": [ "RegistrarsRUS" ], 1599 "roles" : [ "registrar" ], 1600 "postalAddress" : 1601 [ 1602 "1212 Tulip Ave", 1603 "Suite 1", 1604 "Marina Del Rey", 1605 "CA", 1606 "12393-2193" 1607 ], 1608 "emails" : [ "joe@bob.com", "bob@joe.com" ], 1609 "phones" : 1610 { 1611 "office" : [ "1-958-555-4321", "1-958-555-4322" ], 1612 "fax" : [ "1-958-555-4323" ], 1613 "mobile" : [ "1-958-555-4324" ] 1614 }, 1615 "remarks" : 1616 [ 1617 "we registrar for less!" 1618 ], 1619 "links" : 1620 [ 1621 { 1622 "value" : "http://example.net/entity/XXXX" 1623 "rel" : "alternate", 1624 "type" : "text/html", 1625 "href" : "http://www.example.com" 1626 } 1627 ] 1628 } 1629 ] 1630 } 1632 Appendix C. IDN Query and Response Model 1634 Internationalized Domain Names (IDNs) differ from other types of 1635 domain names because multiple domain names as would be represented by 1636 a name in Master File format (see [RFC4343]) may be registered by a 1637 single IDN. IDNs are based on Unicode, and Unicode can have multiple 1638 means for encoding the same word depending on the character set and 1639 language being used. And the rules for determining which IDN 1640 encoding maps to a "wire-format" domain name vary from DNR to DNR. 1642 When an IDN maps to multiple domain names, the various mappings are 1643 called variants. The DNR Domain object class (Section 9.2) 1644 represents the variants using a string array. 1646 The following is an example of an elided DNR domain object with 1647 variants. 1649 { 1650 "handle" : "XXXX", 1651 "name" : "blah.example.com", 1652 "variants" : [ "blah2.example.com", "blah3.example.com" ], 1653 ... 1654 } 1656 Because IDNs can have multiple targets in a mapping and due to the 1657 variance in DNR mapping rules, it is up to the client to reduce an 1658 IDN to a domain name in Master File format so as to narrow the lookup 1659 of the domain name to the proper subset. A query of a DNR using the 1660 IDN itself might map across multiple registrations depending on the 1661 mapping rules of the DNR. 1663 Appendix D. Postal Addresses vs Location 1665 The postal address data listed in the entity object class (Section 7) 1666 does not necessarily represent location. The intent of this 1667 information is to provide a means to send postal mail to an entity. 1668 While in some cases it may also be the location of the entity, there 1669 is no guarantee that the two are the same. 1671 Additionally, the postal address data represented in this document 1672 does not follow any specific standard for postal addresses because 1673 many registries do not keep postal address data in an 1674 internationalized standard form. Publication of such data in a 1675 format that suggests an internationalized standard form when such 1676 data is not known to be well-formed for that purpose would be 1677 misleading. 1679 Appendix E. Motivations for Using JSON 1681 This section addresses a common question regarding the use of JSON 1682 over other data formats, most notably XML. 1684 It is often pointed out that many DNRs and one RIR support the EPP 1685 [RFC3730] standard, which is an XML serialized protocol. The logic 1686 is that since EPP is a common protocol in the industry it follows 1687 that XML would be a more natural choice. While EPP does enfluence 1688 this specification quite a bit, EPP serves a different purpose which 1689 is the provisioning of Internet resources between registries and 1690 accredited registrars and serves a much narrower audience than that 1691 envisioned for RDAP. 1693 By contrast, RDAP has a broader audience and is designed for public 1694 consumption of data. Experience from RIRs with first generation 1695 RESTful web services for Whois indicate a large percentage of clients 1696 operate within browsers and other platforms where full-blown XML 1697 stacks are not readily available and where JSON is a better fit. 1699 Additionally, while EPP is used in much of the DNR community it is 1700 not a unversial constant in that industry. And finally, EPP's use of 1701 XML predates the specification of JSON. If EPP had been defined 1702 today, it may very well have used JSON instead of XML. 1704 Beyond the specific DNR and RIR communities, the trend in the broader 1705 Internet industry is also switching to JSON over XML, especially in 1706 the area of RESTful web services (see [JSON_acendancy]). Studies 1707 have also found that JSON is generally less bulky and consequently 1708 faster to parse (see [JSON_performance_study]). 1710 Appendix F. Changelog 1712 Initial -00 Adopted as working group document 2012-September-18. 1714 -01 1716 Minor spelling corrections. Changed "Registry Data" to 1717 "Registration Data" for the sake of consistency. 1719 Transitioned to RFC 5988 links and relationshipt types from our 1720 own custom "uris" structure. 1722 Some examples had 'status' as a string. Those have been 1723 corrected as 'status' is always an array of strings. 1725 Domain variants can now have a multi-valued relationship with 1726 domain registrations. 1728 "names" in the entity object class was changed to 1729 "entityNames". 1731 Some IP address examples change to IPv6. 1733 Change phone number examples and added reference to E.164. 1735 Added section on motivations for using JSON. 1737 Added error response body section. 1739 Added JSON naming section. 1741 Added common data structures section. 1743 Added the IANA Considerations section and the media type 1744 registration. 1746 Added 'lang' name/value. 1748 Added internationalization considerations section. 1750 Authors' Addresses 1752 Andrew Lee Newton 1753 American Registry for Internet Numbers 1754 3635 Concorde Parkway 1755 Chantilly, VA 20151 1756 US 1758 Email: andy@arin.net 1759 URI: http://www.arin.net 1761 Scott Hollenbeck 1762 Verisign Labs 1763 12061 Bluemont Way 1764 Reston, VA 20190 1765 US 1767 Email: shollenbeck@verisign.com 1768 URI: http://www.verisignlabs.com/