idnits 2.17.1 draft-newton-weirds-unified-json-response-00.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. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 31, 2012) is 4256 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 917, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 940, but no explicit reference was found in the text == Outdated reference: A later version (-02) exists of draft-newton-et-al-weirds-rir-query-00 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Downref: Normative reference to an Informational RFC: RFC 1166 Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track S. Hollenbeck 5 Expires: March 4, 2013 Verisign Labs 6 K. Ranjbar 7 RIPE NCC 8 A. Servin 9 LACNIC 10 B. Ellacott 11 APNIC 12 August 31, 2012 14 JSON Responses to RESTful URL Queries for RIRs and DNRs 15 draft-newton-weirds-unified-json-response-00 17 Abstract 19 This document describes responses in the JSON format to the RESTful 20 queries described in draft-hollenbeck-weirds-unified-query. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on March 4, 2013. 39 Copyright Notice 41 Copyright (c) 2012 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 4 58 3. The Entity Object Type . . . . . . . . . . . . . . . . . . . . 5 59 3.1. The RIR Entity Object Type . . . . . . . . . . . . . . . . 6 60 3.2. The DNR Entity Object Type . . . . . . . . . . . . . . . . 7 61 4. The Nameserver Object Type . . . . . . . . . . . . . . . . . . 10 62 5. The Domain Object Type . . . . . . . . . . . . . . . . . . . . 12 63 5.1. The RIR Domain Object Type . . . . . . . . . . . . . . . . 12 64 5.2. The DNR Domain Object Type . . . . . . . . . . . . . . . . 15 65 6. The IP Network Object Type . . . . . . . . . . . . . . . . . . 19 66 7. Autonomous System Number Entity Object Type . . . . . . . . . 22 67 8. Normative References . . . . . . . . . . . . . . . . . . . . . 25 68 Appendix A. Suggested Values . . . . . . . . . . . . . . . . . . 27 69 A.1. Status . . . . . . . . . . . . . . . . . . . . . . . . . . 27 70 A.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 27 71 A.3. URI Types . . . . . . . . . . . . . . . . . . . . . . . . 28 72 Appendix B. Suggested Data Modeling with the Entity Object 73 Type . . . . . . . . . . . . . . . . . . . . . . . . 29 74 B.1. Registrants and Contacts . . . . . . . . . . . . . . . . . 29 75 B.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . . 30 76 Appendix C. IDN Query and Response Model . . . . . . . . . . . . 31 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32 79 1. Introduction 81 This document describes responses in the JSON [RFC4627] format for 82 the RESTful web queries as defined by UNIFIED-RDAP-QUERY 83 [I-D.hollenbeck-weirds-unified-query]. The signalling for JSON, JSON 84 naming scheme, JSON namespace and extension mechanism and normalized 85 references to other specifications are documented in RDAP-HTTP 86 [I-D.designteam-weirds-using-http]. 88 The data model for the responses consists of two major categories: 89 responses returned by Regional Internet Registries (RIRs) for 90 registrations data related to IP addresses, reverse DNS names, and 91 Autonomous System numbers; and responses returned by Domain Name 92 Registries (DNRs) for registration data related to forward DNS names. 93 Where overlap exists between RIR and DNR reponse object types, the 94 RIR object types are a proper subset of the DNR object types. 96 The components of the DNR object types are derived from a 97 categorization of WHOIS response formats created by Ning Kong, Linlin 98 Zhou, and Guangqing Deng of CNNIC, Steve Sheng and Francisco Arias of 99 ICANN, Ray Bellis of Nominet, and Frederico Neves of NIC.BR. 101 2. Common Data Types 103 JSON [RFC4627] defines the data types of a number, character string, 104 boolean, array, object and null. This section describes the 105 semantics and/or syntax reference for data types used in this 106 document derived from the JSON character string. 108 'handle': DNRs and RIRs have registry-unique identifiers that may 109 be used to specifically reference an instance of an object type. 110 The semantics of this data type as found in this document is to be 111 a registry-unique reference to the closest enclosing object where 112 the value is found. The data type names 'registryId', 'roid', 113 'nic-handle', 'registrationNo', etc... are terms often synomous 114 with this data type. In this document, the term 'handle' is used. 115 The term exposed to users by clients is a presentation issue 116 beyond the scope of this document. 118 IPv4 addresses: The representation of IPv4 addresses in this 119 document uses the dotted-decimal notation described in [RFC1166]. 120 An example of this textual representation is '192.0.2.0'. 122 IPv6 addresses: The representation of IPv6 addresses in this 123 document follow the forms outlined in [RFC5952]. An example of 124 this textual representation is '2001:db8::1:0:0:1'. 126 country codes: Where the identity of a geopolitical nation or 127 country is needed, these identities are represented with the 128 alpha-2 or 2 charachter country code designation as defined in 129 [ISO.3166.1988]. The alpha-2 representation is used because it is 130 freely available whereas the alpha-3 and numeric-3 standards are 131 not. 133 domain names: Textual representations of DNS names follow the rules 134 set forth in [RFC4343], specifically the case insensitivity and 135 character escaping rules. 137 email addresses: Textual representations of email addresses follow 138 the syntax defined in [RFC5322]. 140 dates and times: The syntax for values denoting dates and times is 141 defined in [RFC3339]. 143 URIs: The syntax for values denoting a Uniform Resource Identifier 144 (URI) is defined by [RFC3986]. 146 3. The Entity Object Type 148 The Entity object type appears throughout this document and is an 149 appropriate response for the /entity/XXXX query defined in UNIFIED- 150 RDAP-QUERY [I-D.hollenbeck-weirds-unified-query]. The object type 151 represents the information of organizations, corporations, 152 governments, non-profits, clubs, individual persons, and informal 153 groups of people. All of these representations are so similar that 154 it is best to represent them in JSON [RFC4627] with one construct, 155 the Entity object type, to aid in the re-use of code by implementers. 157 Many of the members of the Entity object type are repeated in other 158 object types described later in this document. 160 3.1. The RIR Entity Object Type 162 The following is an example of an RIR entity: 164 { 165 "handle" : "XXXX", 166 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 167 "roles" : [ "registrant" ], 168 "postalAddress" : [ 169 "123 Maple Ave", 170 "Suite 90001", 171 "Vancouver", 172 "BC", 173 "12393" 174 ], 175 "emails" : [ "joe@bob.com", "bob@joe.com" ], 176 "phones" : { 177 "office" : [ "999-999-999-99", "111-111-111-11" ], 178 "fax" : [ "222-222-222-22" ], 179 "mobile" : [ "333-333-333-33" ] 180 }, 181 "remarks" : [ 182 "she sells seas shells", 183 "down by the seashore" 184 ], 185 "uris" : [ 186 { 187 "type" : "source", 188 "uri" : "http://whois-rws.net/contact/xxxx" 189 }, 190 { 191 "type" : "held", 192 "uri" : "http://example.net/location/xxxx" 193 } 194 ], 195 "registrationDate" : "1990-12-31T23:59:60Z", 196 "lastChangedDate" : "1990-12-31T23:59:60Z", 197 "lastChangedBy" : "joe@bob.com" 198 } 200 This object as the following members. 202 o handle -- a string representing an registry unique identifier of 203 the entity 205 o names -- an array of strings, each signifying the name of the 206 entity 208 o roles -- an array of strings, each signifying the relationship an 209 object would have with its closest containing object. 211 o postalAddress -- an array of string, each representing a line in a 212 postal address. 214 o emails -- an array of strings, each containing an email address 215 for the entity 217 o phones -- an object containg telephone information associated with 218 the entity, with the following members: 220 * office -- an array of strings, each being a telephone number 222 * fax -- an array of strings, each being a telephone number 224 * mobile -- an array of strings, each being a telephone number 226 o remarks -- an array of strings, each containing comments about the 227 entity 229 o uris -- an array of objects, each object having the following 230 members: 232 * type -- a string denoting the application type of the "uri" 233 value 235 * uri -- a string containing a URI [RFC3986] 237 o registrationDate -- a string containing the date the entity was 238 registered 240 o lastChangedDate -- a string containing the date of last change 241 made to the entity 243 o lastChangedBy -- a string containing an identifier of the party 244 responsible for the last change made to the entity registration 246 3.2. The DNR Entity Object Type 248 The DNR Entity object type is a superset of the RIR Entity object 249 type (Section 3.1). It has the following additional members: 251 o registrationBy -- a string containing an identifier of the party 252 responsible for the registration of the entity 254 o sponsoredBy -- a string containing an identifier of the party 255 through which the registration was made, such as an IANA approved 256 registrar 258 o resoldBy -- a string containing an identifier of the party 259 originating the registration of the entity. 261 o status -- an array of strings indicating the state of the entity 262 The following is an example of a DNR entity: 264 { 265 "handle" : "XXXX", 266 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 267 "status" : [ "validated", "locked" ], 268 "postalAddress" : [ 269 "123 Maple Ave", 270 "Suite 90001", 271 "Vancouver", 272 "BC", 273 "12393" 274 ], 275 "emails" : [ "joe@bob.com", "bob@joe.com" ], 276 "phones" : { 277 "office" : [ "999-999-999-99", "111-111-111-11" ], 278 "fax" : [ "222-222-222-22" ], 279 "mobile" : [ "333-333-333-33" ] 280 }, 281 "remarks" : [ 282 "she sells seas shells", 283 "down by the seashore" 284 ], 285 "uris" : [ 286 { 287 "type" : "source", 288 "uri" : "http://whois-rws.net/entity/xxxx" 289 }, 290 { 291 "type" : "held", 292 "uri" : "http://example.net/location/xxxx" 293 } 294 ], 295 "registrationDate" : "1990-12-31T23:59:60Z", 296 "registrationBy" : "ABC123", 297 "lastChangedDate" : "1990-12-31T23:59:60Z", 298 "lastChangedBy" : "ABC123", 299 "sponsoredBy" : "SponsorXYZ", 300 "resoldBy" : "ResellerPDQ" 301 } 303 4. The Nameserver Object Type 305 The nameserver object type is used by both RIRs and DNRs. Unlike 306 other object types used by both registries where the RIR object type 307 is a subset of the DNR object type, a clear delineation is not made 308 with the nameserver object type because some DNRs have the same or a 309 similar registration model as the RIRs. RIRs and some DNRs register 310 or expose nameserver information as an attribute of a domain name, 311 while other DNRs model nameservers as first class objects. 313 The nameserver object type accomodates both models and degrees of 314 variation in between. 316 The following is an example of a nameserver object type. 318 { 319 "handle" : "XXXX", 320 "name" : "ns1.example.com", 321 "status" : "active", 322 "ipAddresses" : [ "192.0.2.0", "192.0.2.1" ], 323 "remarks" : [ 324 "she sells seas shells", 325 "down by the seashore" 326 ], 327 "uris" : [ 328 { 329 "type" : "source", 330 "uri" : "http://example.net/nameserver/xxxx" 331 } 332 ], 333 "registrationDate" : "1990-12-31T23:59:60Z", 334 "registrationBy" : "ABC123", 335 "lastChangedDate" : "1990-12-31T23:59:60Z", 336 "lastChangedBy" : "ABC123", 337 "sponsoredBy" : "SponsorXYZ", 338 "resoldBy" : "ResellerPDQ" 339 } 341 Figure 1 343 Figure 1 is an example of a nameserver object with all values given. 344 Registries using a first-class nameserver data model would embed this 345 in domain objects as well as allowing references to it with the 346 /nameserver query type (all depending on the registry operators 347 policy). Other registries may pair back the information as needed. 348 Figure 2 is an example of a nameserver object as would be found in 349 RIRs and some DNRs, while Figure 3 is an example of a nameserver 350 object as would be found in other DNRs. 352 The following is an example of the simplest nameserver object type. 354 { 355 "name" : "ns1.example.com" 356 } 358 Figure 2 360 The following is an example of a simple nameserver object type that 361 might be commonly used by DNRs. 363 { 364 "name" : "ns1.example.com", 365 "ipAddresses" : [ "192.0.2.0", "192.0.2.1" ] 366 } 368 Figure 3 370 The nameserver object type has the following members: 372 o handle -- a string representing an registry unique identifier of 373 the nameserver 375 o name -- a string containing the DNS name of the nameserver 377 o ipAddresses -- an array of strings containing IPv4 and/or IPv6 378 addresses of the nameserver 380 The members "status", "remarks", "uris", "sponsoredBy", "resoldBy", 381 "registrationBy", "registrationDate", "lastChangedDate", and 382 "lastChangedBy" take the same form of the members of the same name of 383 the entity object (Section 3). 385 5. The Domain Object Type 387 The domain object type represents a DNS name and point of delegation. 388 For RIRs these delegation points are in the reverse DNS tree, whereas 389 for DNRs these delegation points are in the forward DNS tree. The 390 RIR domain object type is a subset of the DNR object type. 392 In both cases, the high level structure of the domain object type 393 consists of information about the domain registration, nameserver 394 information related to the domain name, and entities related to the 395 domain name (e.g. registrant information, contacts, etc...). 397 The following is an elided example of the domain object type showing 398 the high level structure. 400 { 401 "handle" : "XXX", 402 "name" : "blah.example.com", 403 ... 404 "nameServers" : [ 405 ... 406 ], 407 ... 408 "entities" : [ 409 ... 410 ] 411 } 413 5.1. The RIR Domain Object Type 415 The following is an example of a JSON object representing a reverse 416 DNS delegation point or the RIR domain object type. 418 { 419 "handle" : "XXXX", 420 "name" : "192.in-addr.arpa", 421 "nameServers" : [ 422 { "name" : "ns1.rir.net" }, 423 { "name" : "ns2.rir.net" } 424 ], 425 "delegationKeys" : [ 426 { 427 "algorithm": 7, 428 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 429 "digestType" : 1, 430 "keyTag" : 53814 431 } 432 ], 433 "remarks" : [ 434 "she sells seas shells", 435 "down by the seashore" 436 ], 437 "uris" : [ 438 { 439 "type" : "source", 440 "uri" : "http://whois-rws.net/network/xxxx" 441 }, 442 { 443 "type" : "parent", 444 "uri" : "http://whois-rws.net/network/yyyy" 445 }, 446 { 447 "type" : "held", 448 "uri" : "http://example.net/location/xxxx" 449 } 450 ], 451 "registrationDate" : "1990-12-31T23:59:60Z", 452 "lastChangedDate" : "1990-12-31T23:59:60Z", 453 "lastChangedBy" : "joe@bob.com", 454 "entities" : [ 455 { 456 "handle" : "XXXX", 457 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 458 "roles" : [ "registrant" ], 459 "postalAddress" : [ 460 "123 Maple Ave", 461 "Suite 90001", 462 "Vancouver", 463 "BC", 464 "12393" 465 ], 466 "emails" : [ "joe@bob.com", "bob@joe.com" ], 467 "phones" : { 468 "office" : [ "999-999-999-99", "111-111-111-11" ], 469 "fax" : [ "222-222-222-22" ], 470 "mobile" : [ "333-333-333-33" ] 471 }, 472 "remarks" : [ 473 "she sells seas shells", 474 "down by the seashore" 475 ], 476 "uris" : [ 477 { 478 "type" : "source", 479 "uri" : "http://whois-rws.net/entity/xxxx" 480 }, 481 { 482 "type" : "held", 483 "uri" : "http://example.net/location/xxxx" 484 } 485 ], 486 "registrationDate" : "1990-12-31T23:59:60Z", 487 "lastChangedDate" : "1990-12-31T23:59:60Z", 488 "lastChangedBy" : "joe@bob.com" 489 } 490 ] 491 } 493 The following is a description of the members of this object: 495 o handle -- a string representing a registry unique identifier of 496 the domain object instance 498 o name -- a string denoting the DNS zone name, which is a domain 499 name 501 o nameservers -- an array of strings, each being a fully qualified 502 DNS name of a namesever 504 o delegationKeys -- an array of objects, each with the following 505 members: 507 * algorithm -- an integer as specified by the algorithm field of 508 a DNS DS record as specified by RFC 4034 [RFC4034] in 509 presentation format 511 * digest -- an string as specified by the digest field of a DNS 512 DS record as specified by RFC 4034 in presentation format 514 * digestType -- an integer as specified by the digest type field 515 of a DNS DS record as specified by RFC 4034 in presetnation 516 format 518 * keyTag -- an integer as specified by the key tag field of a DNS 519 DS record as specified by RFC 4034 in presentation format 521 o entities -- an array of entity objects as defined by Section 3.1. 523 The members "remarks", "uris", "registrationDate", "lastChangedDate", 524 and "lastChangedBy" take the same form of the members of the same 525 name of the entity object (Section 3). 527 5.2. The DNR Domain Object Type 529 The DNR domain object type is a superset of the RIR domain object 530 type (Section 5.1) and has the following additional members. 532 o nameServers -- (see note below) 534 o variants -- an array of strings, each containing a domain name 535 that is a variant of this domain name object instance. 537 o expirationDate -- a string containing the date and time this 538 domain name registration will expire 540 o registrationBy -- a string containing an identifier of the party 541 responsible for the registration of the domain name 543 o sponsoredBy -- a string containing an identifier of the party 544 through which the registration was made, such as an IANA approved 545 registrar 547 o resoldBy -- a string containing an identifier of the party 548 originating the registration of the domain name 550 o status -- an array of strings indicating the state of the domain 551 name 553 o transferDate -- a string containing the date and time this domain 554 name was transferred 556 The following is an example of a JSON object representing a forward 557 DNS delegation point or the DNR domain object type. 559 { 560 "handle" : "XXXX", 561 "name" : "blah.example.com", 562 "variants" : [ "blah2.example.com", "blah3.example.com" ], 563 "status" : [ "locked", "transferProhibited" ], 564 "nameServers" : [ 565 { 566 "handle" : "XXXX", 567 "name" : "ns1.example.com", 568 "status" : "active", 569 "ipAddresses" : [ "192.0.2.0", "192.0.2.1" ], 570 "remarks" : [ 571 "she sells seas shells", 572 "down by the seashore" 573 ], 574 "uris" : [ 575 { 576 "type" : "source", 577 "uri" : "http://example.net/nameserver/xxxx" 578 } 579 ], 580 "registrationDate" : "1990-12-31T23:59:60Z", 581 "registrationBy" : "ABC123", 582 "lastChangedDate" : "1990-12-31T23:59:60Z", 583 "lastChangedBy" : "ABC123", 584 "sponsoredBy" : "SponsorXYZ", 585 "resoldBy" : "ResellerPDQ" 586 }, 587 { 588 "handle" : "XXXX", 589 "name" : "ns2.example.com", 590 "status" : "active", 591 "ipAddresses" : [ "192.0.2.2", "192.0.2.3" ], 592 "remarks" : [ 593 "she sells seas shells", 594 "down by the seashore" 595 ], 596 "uris" : [ 597 { 598 "type" : "source", 599 "uri" : "http://example.net/nameserver/xxxx" 600 } 601 ], 602 "registrationDate" : "1990-12-31T23:59:60Z", 603 "registrationBy" : "ABC123", 604 "lastChangedDate" : "1990-12-31T23:59:60Z", 605 "lastChangedBy" : "ABC123", 606 "sponsoredBy" : "SponsorXYZ", 607 "resoldBy" : "ResellerPDQ" 608 } 609 ] 610 "delegationKeys" : [ 611 { 612 "algorithm": 7, 613 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 614 "digestType" : 1, 615 "keyTag" : 53814 616 } 617 ], 618 "remarks" : [ 619 "she sells seas shells", 620 "down by the seashore" 621 ], 622 "uris" : [ 623 { 624 "type" : "source", 625 "uri" : "http://example.net/domain/xxxx" 626 }, 627 { 628 "type" : "held", 629 "uri" : "http://example.net/location/xxxx" 630 } 631 ], 632 "registrationDate" : "1990-12-31T23:59:60Z", 633 "registrationBy" : "ABC123", 634 "lastChangedDate" : "1990-12-31T23:59:60Z", 635 "lastChangedBy" : "ABC123", 636 "sponsoredBy" : "SponsorXYZ", 637 "resoldBy" : "ResellerPDQ", 638 "expirationDate" : "2016-12-31T23:59:60Z", 639 "transferDate" : "1990-12-31T23:59:60Z", 640 "entities" : [ 641 { 642 "handle" : "XXXX", 643 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 644 "status" : [ "validated", "locked" ], 645 "postalAddress" : [ 646 "123 Maple Ave", 647 "Suite 90001", 648 "Vancouver", 649 "BC", 650 "12393" 651 ], 652 "emails" : [ "joe@bob.com", "bob@joe.com" ], 653 "phones" : { 654 "office" : [ "999-999-999-99", "111-111-111-11" ], 655 "fax" : [ "222-222-222-22" ], 656 "mobile" : [ "333-333-333-33" ] 657 }, 658 "remarks" : [ 659 "she sells seas shells", 660 "down by the seashore" 661 ], 662 "uris" : [ 663 { 664 "type" : "source", 665 "uri" : "http://whois-rws.net/entity/xxxx" 666 }, 667 { 668 "type" : "held", 669 "uri" : "http://example.net/location/xxxx" 670 } 671 ], 672 "registrationDate" : "1990-12-31T23:59:60Z", 673 "registrationBy" : "ABC123", 674 "lastChangedDate" : "1990-12-31T23:59:60Z", 675 "lastChangedBy" : "ABC123", 676 "sponsoredBy" : "SponsorXYZ", 677 "resoldBy" : "ResellerPDQ" 678 } 679 ] 680 } 682 6. The IP Network Object Type 684 The IP Network object type models IP network registrations found in 685 RIRs. There is no equivalent object type for DNRs. The high level 686 structure of the IP network object type consists of information about 687 the network registration and entities related to the IP network (e.g. 688 registrant information, contacts, etc...). 690 The following is an elided example of the IP network object type 691 showing the high level structure. 693 { 694 "handle" : "XXX", 695 ... 696 "entities" : [ 697 ... 698 ] 699 } 701 The following is an example of the JSON object for the network 702 registration information 704 { 705 "handle" : "XXXX-RIR", 706 "startAddress" : "10.0.0.0", 707 "endAddress" : "10.0.0.255", 708 "ipVersion" : 4, 709 "name": "NET-RTR-1", 710 "description" : [ "A network used for routing" ], 711 "type" : "DIRECT ALLOCATION", 712 "country" : "AU", 713 "parentHandle" : "YYYY-RIR", 714 "remarks" : [ 715 "she sells seas shells", 716 "down by the seashore" 717 ], 718 "uris" : [ 719 { 720 "type" : "source", 721 "uri" : "http://whois-rws.net/network/xxxx" 722 }, 723 { 724 "type" : "parent", 725 "uri" : "http://whois-rws.net/network/yyyy" 726 }, 728 ], 729 "registrationDate" : "20110509", 730 "lastChangedDate" : "20110509", 731 "lastChangedBy" : "joe@bob.com", 732 "entities" : [ 733 { 734 "handle" : "XXXX", 735 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 736 "roles" : [ "registrant" ], 737 "postalAddress" : [ 738 "123 Maple Ave", 739 "Suite 90001", 740 "Vancouver", 741 "BC", 742 "12393" 743 ], 744 "emails" : [ "joe@bob.com", "bob@joe.com" ], 745 "phones" : { 746 "office" : [ "999-999-999-99", "111-111-111-11" ], 747 "fax" : [ "222-222-222-22" ], 748 "mobile" : [ "333-333-333-33" ] 749 }, 750 "remarks" : [ 751 "she sells seas shells", 752 "down by the seashore" 753 ], 754 "uris" : [ 755 { 756 "type" : "source", 757 "uri" : "http://whois-rws.net/contact/xxxx" 758 }, 759 { 760 "type" : "held", 761 "uri" : "http://example.net/location/xxxx" 762 } 763 ], 764 "registrationDate" : "1990-12-31T23:59:60Z", 765 "lastChangedDate" : "1990-12-31T23:59:60Z", 766 "lastChangedBy" : "joe@bob.com" 767 } 768 ] 769 } 771 The following is a description of the members of this object: 773 o handle -- a string representing an RIR unique identifier of the 774 network registration 776 o startAddress -- the starting IP address of the network, either 777 IPv4 or IPv6 779 o endAddress -- the ending IP address of the network, either IPv4 or 780 IPv6 782 o ipVersion -- an integer signifying the IP protocol version of the 783 network: 4 signifying an IPv4 network, 6 signifing an IPv6 network 785 o name -- an identifier assigned to the network registration by the 786 registration holder 788 o description -- an array of strings containing descriptive text 789 about the network registration 791 o type -- a string containing an RIR specific classification of the 792 network 794 o country -- a string containing the name of the 2 character country 795 code of the network 797 o parentHandle -- a string containing an RIR unique identifier of 798 the parent network of this network registration 800 o entities -- an array of entity objects as defined by Section 3.1. 802 The members "remarks", "uris", "registrationDate", "lastChangedDate", 803 and "lastChangedBy" take the same form of the members of the same 804 name of the entity object (Section 3). 806 7. Autonomous System Number Entity Object Type 808 The Autonomous System Number (autnum) object type models Autonomous 809 System Number registrations found in RIRs. There is no equivalent 810 object type for DNRs. The high level structure of the autnum object 811 type consists of information about the network registration and 812 entities related to the autnum registration (e.g. registrant 813 information, contacts, etc...), and is similar to the IP Network 814 entity object type. 816 The following is an example of a JSON object representing an autnum. 818 { 819 "handle" : "XXXX-RIR", 820 "startAutnum" : "10", 821 "endAutnum" : "15", 822 "name": "AS-RTR-1", 823 "description" : [ "AS for Exchange" ], 824 "type" : "DIRECT ALLOCATION", 825 "country": "AU", 826 "remarks" : [ 827 "she sells seas shells", 828 "down by the seashore" 829 ], 830 "uris" : [ 831 { 832 "type" : "source", 833 "uri" : "http://whois-rws.net/autnum/xxxx" 834 }, 835 { 836 "type" : "parent", 837 "uri" : "http://whois-rws.net/autnum/yyyy" 838 }, 839 { 840 "type" : "held", 841 "uri" : "http://example.net/location/xxxx" 842 } 843 ], 844 "registrationDate" : "20110509", 845 "lastChangedDate" : "20110509", 846 "lastChangedBy" : "joe@bob.com", 847 "entities" : [ 848 { 849 "handle" : "XXXX", 850 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 851 "roles" : [ "registrant" ], 852 "postalAddress" : [ 853 "123 Maple Ave", 854 "Suite 90001", 855 "Vancouver", 856 "BC", 857 "12393" 858 ], 859 "emails" : [ "joe@bob.com", "bob@joe.com" ], 860 "phones" : { 861 "office" : [ "999-999-999-99", "111-111-111-11" ], 862 "fax" : [ "222-222-222-22" ], 863 "mobile" : [ "333-333-333-33" ] 864 }, 865 "remarks" : [ 866 "she sells seas shells", 867 "down by the seashore" 868 ], 869 "uris" : [ 870 { 871 "type" : "source", 872 "uri" : "http://whois-rws.net/autnum/xxxx" 873 } 874 ], 875 "registrationDate" : "1990-12-31T23:59:60Z", 876 "lastChangedDate" : "1990-12-31T23:59:60Z", 877 "lastChangedBy" : "joe@bob.com" 878 } 879 ] 880 } 882 The following is a description of the members of this object: 884 o handle -- a string representing an RIR unique identifier of the 885 autnum registration 887 o startAutnum -- the starting number [RFC5396] in the block of 888 autonomous system numbers 890 o endAutnum -- the ending number [RFC5396] in the block of 891 autonomous system numbers 893 o name -- an identifier assigned to the autnum registration by the 894 registration holder 896 o description -- an array of strings containing descriptive text 897 about the autnum registration 899 o type -- a string containing an RIR specific classification of the 900 autnum 902 o country -- a string containing the name of the 2 character country 903 code of the autnum 905 The members "remarks", "uris", "registrationDate", "lastChangedDate", 906 and "lastChangedBy" take the same form of the members of the same 907 name of the entity object (Section 3). 909 8. Normative References 911 [I-D.hollenbeck-weirds-unified-query] 912 Newton, A., Ranjbar, K., Servin, A., and S. Hollenbeck, 913 "Unified RDAP Query Format", 914 draft-newton-et-al-weirds-rir-query-00 (work in progress), 915 September 2011. 917 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 918 September 1981. 920 [RFC4627] Crockford, D., "The application/json Media Type for 921 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 923 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 924 October 2008. 926 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 927 Address Text Representation", RFC 5952, August 2010. 929 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 930 Rose, "Resource Records for the DNS Security Extensions", 931 RFC 4034, March 2005. 933 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 934 Autonomous System (AS) Numbers", RFC 5396, December 2008. 936 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 937 Resource Identifier (URI): Generic Syntax", STD 66, 938 RFC 3986, January 2005. 940 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 941 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 942 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 944 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 945 Internet: Timestamps", RFC 3339, July 2002. 947 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 948 numbers", RFC 1166, July 1990. 950 [ISO.3166.1988] 951 International Organization for Standardization, "Codes for 952 the representation of names of countries, 3rd edition", 953 ISO Standard 3166, August 1988. 955 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 956 Clarification", RFC 4343, January 2006. 958 [I-D.designteam-weirds-using-http] 959 Newton, A., Ranjbar, K., Servin, A., Ellacott, B., 960 Hollenbeck, S., Sheng, S., Arias, F., Kong, N., and F. 961 Obispo, "Using HTTP for RESTful Whois Services by Internet 962 Registries", draft-designteam-weirds-using-http-01 (work 963 in progress), May 2012. 965 Appendix A. Suggested Values 967 Due to the wide variation between the hundreds of registry operators 968 and the on-going policy refinement by registry communities, values of 969 some data cannot be formally standardized. This section lists 970 suggested values for such data but is not nor will ever be a complete 971 of values and their meanings. 973 A.1. Status 975 Many of the object types have a member named 'status'. This member 976 is an array of strings, with each string denoting a status associated 977 with the object instance. The following is a list of suggested 978 values to use in the 'status' array: 980 o 'validated' -- Signifies that the data of the object instance has 981 been found to be accurate. This type of status is usually found 982 on Entity object instances to note the validity of identifying 983 contact information. 985 o 'update prohibited' -- Updates to the object instance are 986 forbidden. 988 o 'transfer prohibited' -- Transfers of the registration from one 989 registrar to another are forbidden. This type of status normally 990 applies to DNR domain names. 992 o 'delete prohibited' -- Deletion of the registration of the object 993 instance is forbidden. This type of status normally applies to 994 DNR domain names. 996 A.2. Roles 998 Entity object types have a member named 'roles'. This member is an 999 array of strings, with each string indicating the role or 1000 relationship the Entity object instance has with a containing object, 1001 such as a domain name or IP network. An Entity object instance can 1002 have more than one type of relationship with a containing object. 1003 The following is a list of suggested values to use in the 'roles' 1004 array: 1006 o 'registrant' -- The Entity object instance is the registrant of 1007 the registration. 1009 o 'tech' -- The Entity object instance is a technical contact for 1010 the registration. 1012 o 'admin' -- The Entity object instance is an administrative contact 1013 for the registraton. 1015 o 'abuse' -- The Entity object instance handles network abuse issues 1016 on behalf of the registrant of the registration. 1018 o 'billing' -- The Entity object instance handles payment and 1019 billing issues on behalf of the registrant of the registration. 1021 o 'registrar' -- The Entity object instance represents the authority 1022 responsible for the registration in the registry. 1024 A.3. URI Types 1026 Many of the object types have a member named 'uris', which is an 1027 array of objects with each object containing a 'type' string and a 1028 'uri' string. These URIs represent a location to find information 1029 about the containing object. The following is a list of suggested 1030 values to use as a 'type' string for an associated URI. 1032 o 'self' -- Indicates the URI is a direct reference to the object 1033 instance via an RDAP query. 1035 o 'parent' -- Indicates a direct reference to an object instance's 1036 parent via an RDAP query. Such a reference might be used in an IP 1037 network to reference next IP network up the tree of IP address 1038 hierarchies. 1040 o 'source' -- Signifies a direct reference to the registration in 1041 another protocol. As an example, both ARIN and the RIPE NCC have 1042 RESTful web services for Whois data that pre-exists RDAP. This 1043 type of URI would be used to reference the same data in such a 1044 system. 1046 o 'web' -- Signifies the web site of the containing object instance. 1047 The expectation is that a web browser would be needed to use this 1048 URI. 1050 o 'rdap' -- Signifies the RDAP service where RDAP queries can be 1051 issued. 1053 o 'held' -- Signifies a HELD location service for the registered 1054 object. 1056 o 'geo' -- Signifies that the URI is a geo URI related to the 1057 location of the registration. 1059 Appendix B. Suggested Data Modeling with the Entity Object Type 1061 B.1. Registrants and Contacts 1063 This document does not provide specific objects for registrants and 1064 contacts. Instead the Entity object type may be used to represent a 1065 registrant or contact. When the Entity object instance is embedded 1066 inside a containing object such as a domain name or IP network, the 1067 'roles' string array can be used to signify the relationship. It is 1068 recommended that the values from Appendix A.2 be used. 1070 The following is an example of an elided containing object with an 1071 embedded entity that is both a registrant and admin contact: 1073 { 1074 ... 1075 "entities" : 1076 [ 1077 { 1078 "handle" : "XXXX", 1079 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 1080 "roles" : [ "registrant", "admin" ], 1081 "postalAddress" : [ 1082 "123 Maple Ave", 1083 "Suite 90001", 1084 "Vancouver", 1085 "BC", 1086 "12393" 1087 ], 1088 "emails" : [ "joe@bob.com", "bob@joe.com" ], 1089 "phones" : { 1090 "office" : [ "999-999-999-99", "111-111-111-11" ], 1091 "fax" : [ "222-222-222-22" ], 1092 "mobile" : [ "333-333-333-33" ] 1093 }, 1094 "remarks" : [ 1095 "she sells seas shells", 1096 "down by the seashore" 1097 ], 1098 "registrationDate" : "1990-12-31T23:59:60Z", 1099 "lastChangedDate" : "1990-12-31T23:59:60Z", 1100 "lastChangedBy" : "joe@bob.com" 1101 } 1102 ] 1103 } 1105 B.2. Registrars 1107 This document does not provide a specific object type for registrars, 1108 but like registrants and contacts (see Appendix B.1) the 'roles' 1109 string array maybe used. Additionally, a URI type can signify the 1110 registrars point of service (see Appendix A.3). 1112 The following is an example of an elided containing object with an 1113 embedded entity that is a registrar: 1115 { 1116 ... 1117 "entities" : 1118 [ 1119 { 1120 "handle" : "XXXX", 1121 "names": [ "RegistrarsRUS" ], 1122 "roles" : [ "registrar" ], 1123 "postalAddress" : [ 1124 "1212 Tulip Ave", 1125 "Suite 1", 1126 "Marina Del Rey", 1127 "CA", 1128 "12393-2193" 1129 ], 1130 "emails" : [ "joe@bob.com", "bob@joe.com" ], 1131 "phones" : { 1132 "office" : [ "999-999-999-99", "111-111-111-11" ], 1133 "fax" : [ "222-222-222-22" ], 1134 "mobile" : [ "333-333-333-33" ] 1135 }, 1136 "remarks" : [ 1137 "we registrar for less!" 1138 ], 1139 "uris" : [ 1140 { 1141 "type" : "rdap", 1142 "uri" : "http://rdap.exmaple.com" 1143 }, 1144 { 1145 "type" : "web", 1146 "uri" : "http://www.example.com" 1147 } 1148 ] 1149 } 1150 ] 1151 } 1153 Appendix C. IDN Query and Response Model 1155 Internationalized Domain Names (IDNs) differ from other types of 1156 domain names because multiple domain names as would be represented by 1157 a name in Master File format (see [RFC4343]) may be registered by a 1158 single IDN. IDNs are based on Unicode, and Unicode can have multiple 1159 means for encoding the same word depending on the character set and 1160 language being used. And the rules for determining which IDN 1161 encoding maps to a "wire-format" domain name vary from DNR to DNR. 1163 When an IDN maps to multiple domain names, the various mappings are 1164 called variants. The DNR Domain object type (Section 5.2) represents 1165 the variants using a string array. 1167 The following is an example of an elided DNR domain object with 1168 variants. 1170 { 1171 "handle" : "XXXX", 1172 "name" : "blah.example.com", 1173 "variants" : [ "blah2.example.com", "blah3.example.com" ], 1174 ... 1175 } 1177 Because IDNs can have multiple targets in a mapping and due to the 1178 variance in DNR mapping rules, it is up to the client to reduce an 1179 IDN to a domain name in Master File format so as to narrow the lookup 1180 of the domain name to the proper subset. A query of a DNR using the 1181 IDN itself might map across multiple registrations depending on the 1182 mapping rules of the DNR. 1184 Authors' Addresses 1186 Andrew Lee Newton 1187 American Registry for Internet Numbers 1188 3635 Concorde Parkway 1189 Chantilly, VA 20151 1190 US 1192 Email: andy@arin.net 1193 URI: http://www.arin.net 1195 Scott Hollenbeck 1196 Verisign Labs 1197 12061 Bluemont Way 1198 Reston, VA 20190 1199 US 1201 Email: shollenbeck@verisign.com 1202 URI: http://www.verisignlabs.com/ 1204 Kaveh Ranjbar 1205 RIPE Network Coordination Centre 1206 Singel 258 1207 Amsterdam 1016AB 1208 NL 1210 Email: kranjbar@ripe.net 1211 URI: http://www.ripe.net 1213 Arturo L. Servin 1214 Latin American and Caribbean Internet Address Registry 1215 Rambla Republica de Mexico 6125 1216 Montevideo 11300 1217 UY 1219 Email: aservin@lacnic.net 1220 URI: http://www.lacnic.net 1221 Byron J. Ellacott 1222 Asia Pacific Network Information Center 1223 6 Cordelia Street 1224 South Brisbane QLD 4101 1225 Australia 1227 Email: bje@apnic.net 1228 URI: http://www.apnic.net