idnits 2.17.1 draft-ietf-weirds-json-response-03.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: ---------------------------------------------------------------------------- ** The document is more than 15 pages and seems to lack a Table of Contents. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 94: '...nt client/server MUST understand to fu...' RFC 2119 keyword, line 134: '...N attributes but SHOULD NOT treat them...' RFC 2119 keyword, line 135: '... error. Servers MAY insert values sig...' RFC 2119 keyword, line 137: '...o JSON responses SHOULD have names pre...' RFC 2119 keyword, line 140: '...meaningful name, SHOULD adhere to the ...' (15 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 09, 2013) is 4006 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 1644, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 1650, but no explicit reference was found in the text == Unused Reference: 'RFC4343' is defined on line 1665, but no explicit reference was found in the text == Unused Reference: 'RFC5322' is defined on line 1671, 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' -- Obsolete informational reference (is this intentional?): RFC 3730 (Obsoleted by RFC 4930) Summary: 6 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A.L. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track S. Hollenbeck 5 Expires: October 11, 2013 Verisign Labs 6 April 09, 2013 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-weirds-json-response-03 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 October 11, 2013. 36 Copyright Notice 38 Copyright (c) 2013 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 1. Introduction 53 This document describes responses in the JSON [RFC4627] format for 54 the RESTful web queries as defined by the Registration Data Access 55 Protocol Lookup Format [I-D.ietf-weirds-rdap-query]. 57 The data model for JSON responses is specified in four sections: 59 1. simple data types conveyed in JSON strings 61 2. data structures specified as JSON arrays or objects that are used 62 repeatedly when building up larger objects 64 3. object classes representing structured data corresponding to a 65 given query 67 4. the response to an error 69 The object classes represent responses for two major categories of 70 data: responses returned by Regional Internet Registries (RIRs) for 71 registrations data related to IP addresses, reverse DNS names, and 72 Autonomous System numbers; and responses returned by Domain Name 73 Registries (DNRs) for registration data related to forward DNS names. 74 The following object classes are served by both RIRs and DNRs: 76 1. domains 78 2. nameservers 80 3. entities 82 The information served by both RIRs and DNRs for these object classes 83 overlap extensively and are given in this document as a unified model 84 for both classes of service. 86 In addition to the object classes listed above, RIRs also serve the 87 following object classes: 89 1. IP networks 91 2. Autonomous System numbers 93 Object classes defined in this document represent a minimal set of 94 what a compliant client/server MUST understand to function correctly, 95 however some deployments may want to include additional object 96 classes to suit individual needs. Anticipating this need for 97 extension, Section 3.2 of this document defines a mechanism for 98 extending the JSON objects that are described in this document. 100 2. Terminology and Definitions 102 The following list describes terminology and definitions used 103 throughout this document: 105 DNR: "Domain Name Registry". 107 LDH: "Letters, Digits, Hyphen". 109 member: data found with in an object as defined by JSON 110 [RFC4627]. 112 object: a data structure as defined by JSON [RFC4627]. 114 object class: the definition of members that may be found in JSON 115 objects described in this document. 117 object instance: an instantiation or specific instance of an object 118 class. 120 RDAP: "Registration Data Access Protocol". 122 RIR: "Regional Internet Registry". 124 3. Use of JSON 126 3.1. Signaling 128 Media type signaling for the JSON data specified in this document is 129 specified in [I-D.ietf-weirds-using-http]. 131 3.2. Naming 133 Clients processing JSON [RFC4627] responses are under no obligation 134 to process unrecognized JSON attributes but SHOULD NOT treat them as 135 an error. Servers MAY insert values signified by names into the JSON 136 responses which are not specified in this document. Insertion of 137 unspecified values into JSON responses SHOULD have names prefixed 138 with a short identifier followed by an underscore followed by a 139 meaningful name. The full JSON name, the prefix plus the underscore 140 plus the meaningful name, SHOULD adhere to the character and name 141 limitations of the prefix registry described in 142 [I-D.ietf-weirds-using-http]. 144 Consider the following JSON response with JSON names. some of which 145 are not specified in this document. 147 { 148 "handle" : "ABC123", 149 "remarks" : 150 [ 151 { 152 "description" : 153 [ 154 "She sells sea shells down by the sea shore.", 155 "Originally written by Terry Sullivan." 156 ] 157 } 158 ] 159 } 161 Figure 1 163 If The Registry of the Moon desires to express information not found 164 in this specification, it might select "lunarNic" as its identifying 165 prefix and insert, as an example, the name 166 "lunarNic_beforeOneSmallStep" to signify registrations occurring 167 before the first moon landing and the name 168 "lunarNic_harshMistressNotes" containing other descriptive text. 170 Consider the following JSON response with JSON names, some of which 171 should be ignored by clients without knowledge of their meaning. 173 { 174 "handle" : "ABC123", 175 "lunarNic_beforeOneSmallStep" : "TRUE THAT!", 176 "remarks" : 177 [ 178 { 179 "description" : 180 [ 181 "She sells sea shells down by the sea shore.", 182 "Originally written by Terry Sullivan." 183 ] 184 } 185 ], 186 "lunarNic_harshMistressNotes" : 187 [ 188 "In space,", 189 "nobody can hear you scream." 190 ] 191 } 193 Figure 2 195 Insertion of unrecognized names ignored by clients may also be used 196 for future revisions to this specification. 198 Clients processing JSON responses MUST be prepared for values 199 specified in this document to be absent from a response as no JSON 200 value listed is required to appear in a response. In other words, 201 servers MAY remove values as is needed by the policies of the server 202 operator. 204 Finally, all JSON names specified in this document are case 205 sensitive. Both servers and clients MUST transmit and process them 206 using the specified character case. 208 4. Common Data Types 210 JSON [RFC4627] defines the data types of a number, character string, 211 boolean, array, object and null. This section describes the 212 semantics and/or syntax reference for data types used in this 213 document derived from the JSON character string. 215 'handle': DNRs and RIRs have registry-unique identifiers that 216 may be used to specifically reference an object 217 instance. The semantics of this data type as found 218 in this document is to be a registry-unique 219 reference to the closest enclosing object where the 220 value is found. The data type names 'registryId', 221 'roid', 'nic-handle', 'registrationNo', etc. are 222 terms often synonymous with this data type. In 223 this document, the term 'handle' is used. The term 224 exposed to users by clients is a presentation issue 225 beyond the scope of this document. 227 IPv4 addresses: The representation of IPv4 addresses in this 228 document uses the dotted-decimal notation described 229 in [RFC1166]. An example of this textual 230 representation is '192.0.2.0'. 232 IPv6 addresses: The representation of IPv6 addresses in this 233 document follow the forms outlined in [RFC5952]. 234 An example of this textual representation is 235 '2001:db8::1:0:0:1'. 237 country codes: Where the identity of a geopolitical nation or 238 country is needed, these identities are represented 239 with the alpha-2 or 2 character country code 240 designation as defined in [ISO.3166.1988]. The 241 alpha-2 representation is used because it is freely 242 available whereas the alpha-3 and numeric-3 243 standards are not. 245 LDH names: Textual representations of DNS names where the 246 labels of the domain are all "letters, digits, 247 hyphen" labels as described by [RFC5890]. Trailing 248 periods are optional. 250 Unicode names: Textual representations of DNS names were one or 251 more of the labels are u-labels as described by 252 [RFC5890]. Trailing periods are optional. 254 dates and times: The syntax for values denoting dates and times is 255 defined in [RFC3339]. 257 URIs: The syntax for values denoting a Uniform Resource 258 Identifier (URI) is defined by [RFC3986]. 260 Contact information is defined using JSON vCards as described in 261 [I-D.kewisch-vcard-in-json] 263 5. Common Data Structures 265 This section defines common data structures to be used in response. 266 Each of these structures MAY appear within any object class of a 267 response. 269 5.1. RDAP Conformance 271 The first data structure is named "rdapConformance" and is simply an 272 array of strings, each providing a hint as to the specifications used 273 in the construction of the response. This data structure appears 274 only in the top most object of a response. 276 An example rdapConformance data structure: 278 "rdapConformance" : 279 [ 280 "rdap_level_0" 281 ] 283 Figure 3 285 The string literal "rdap_level_0" signifies conformance with this 286 specification. When custom JSON values are inserted into responses, 287 conformance to those custom specifications should use a string 288 prefixed with the appropriate identifier from the IANA prefix 289 identifier registry specified in [I-D.ietf-weirds-using-http]. For 290 example, if the fictional Registry of the Moon wants to signify that 291 their JSON responses are conformant with their registered extensions, 292 the string used might be "lunarNIC_level_0". 294 Example rdapConformance structure with custom extensions noted: 296 "rdapConformance" : 297 [ 298 "rdap_level_0", 299 "lunarNic_level_0" 300 ] 302 Figure 4 304 5.2. Links 306 The "links" array is found in data structures to signify links to 307 other resources on the Internet. The relationship of these links is 308 defined by the IANA registry described by [RFC5988]. 310 The following is an example of the link structure: 312 { 313 "value" : "http://example.com/context_uri", 314 "rel" : "self", 315 "href" : "http://example.com/target_uri", 316 "hreflang" : [ "en", "ch" ], 317 "title" : [ "title1", "title2" ], 318 "media" : "screen", 319 "type" : "application/json" 320 } 322 Figure 5 324 The JSON name/values of "rel", "href", "hreflang", "title", "media", 325 and "type" correspond to values found in Section 5 of [RFC5988]. The 326 "value" JSON value is the context URI as described by [RFC5988]. The 327 "value", "rel", and "href" JSON values MUST be specified. All other 328 JSON values are optional. 330 This is an example of the "links" array as it might be found in an 331 object class: 333 "links" : 334 [ 335 { 336 "value" : "http://example.com/ip/2001:db8::123", 337 "rel" : "self", 338 "href" : "http://example.com/ip/2001:db8::123" 339 }, 340 { 341 "value" : "http://example.com/ip/2001:db8::123", 342 "rel" : "up", 343 "href" : "http://example.com/ip/2001:db8::/48" 344 } 346 ] 348 5.3. Notices And Remarks 350 The "notices" and "remarks" data structures take the same form. The 351 "notices" structure denotes information about the service providing 352 RDAP information, whereas the "remarks" structure denotes information 353 about the object class it is contained within (see Section 6 354 regarding object classes). 356 Both are an array of objects. Each object contains an optional 357 "title" string representing the title of the object, an array of 358 strings named "description" for the purposes of conveying any 359 descriptive text, and an optional "links" array as described in 360 Section 5.2. 362 An example of the notices data structure: 364 "notices" : 365 [ 366 { 367 "title" : "Terms of Use", 368 "description" : 369 [ 370 "Service subject to The Registry of the Moon's TOS.", 371 "Copyright (c) 2020 LunarNIC" 372 ], 373 "links" : 374 [ 375 { 376 "value" : "http://example.net/entity/XXXX", 377 "rel" : "alternate", 378 "type" : "text/html", 379 "href" : "http://www.example.com/terms_of_use.html" 380 } 381 ] 382 } 383 ] 385 Figure 6 387 It is the job of the clients to determine line breaks, spacing and 388 display issues for sentences within the character strings of the 389 "description" array. Servers SHOULD NOT split sentences across 390 multiple strings of this array. Each string is to represent a 391 semantic division in the descriptive text. 393 An example of the remarks data structure: 395 "remarks" : 396 [ 397 { 398 "description" : 399 [ 400 "She sells sea shells down by the sea shore.", 401 "Originally written by Terry Sullivan." 402 ] 403 } 404 ] 406 Figure 7 408 Note that objects in the "remarks" array may also have a "links" 409 array. 411 While the "remarks" array will appear in many object classes in a 412 response, the "notices" array appears only in the top most object of 413 a response. 415 5.4. Language Identifier 417 This data structure is a simple JSON name/value of "lang" with a 418 string containing a language identifier as described by [RFC5646]. 420 "lang" : "mn-Cyrl-MN" 422 Figure 8 424 The 'lang' attribute may appear anywhere in an object class or data 425 structure. 427 5.5. Events 429 This data structure represents events that have occurred on an 430 instance of an object class (see Section 6 regarding object classes). 432 This is an example of an "events" array. 434 "events" : 435 [ 436 { 437 "eventAction" : "registration", 438 "eventActor" : "SOMEID-LUNARNIC", 439 "eventDate" : "1990-12-31T23:59:60Z" 440 }, 441 { 442 "eventAction" : "last changed", 443 "eventActor" : "OTHERID-LUNARNIC", 444 "eventDate" : "1991-12-31T23:59:60Z" 445 } 446 ] 448 Figure 9 450 The "events" array consists of objects, each with the following 451 members: 453 o 'eventAction' -- a string denoting the reason for the event 454 o 'eventActor' -- an optional identifier denoting the actor 455 responsible for the event 457 o 'eventDate' -- a string containing the time and date the event 458 occurred. 460 Events can be future dated. One use case for future dating of events 461 is to denote when an object expires from a registry. 463 See Appendix A.2 for a list of suggested values for the 'eventAction' 464 string. See Appendix C regarding the various ways events can be 465 modeled. 467 5.6. Status 469 This data structure, named 'status', is an array of strings 470 indicating the state of a registered object (see Appendix A.1 for 471 suggested values). 473 5.7. Port 43 Whois Server 475 This data stricture, named 'port43', is a simple string containing 476 the fully-qualified host name of the WHOIS [RFC3912] server where the 477 containing object instance may be found. Note that this is not a 478 URI, as there is not Whois URI scheme. 480 5.8. An Example 482 This is an example response with both rdapConformance and notices 483 embedded: 485 { 486 "rdapConformance" : 487 [ 488 "rdap_level_0" 489 ], 490 "notices" : 491 [ 492 { 493 "title" : "Content Redacted", 494 "description" : 495 [ 496 "Without full authorization, content has been redacted.", 497 "Sorry, dude!" 498 ], 499 "links" : 500 [ 501 { 502 "value" : "http://example.net/ip/192.0.2.0/24", 503 "rel" : "alternate", 504 "type" : "text/html", 505 "href" : "http://www.example.com/redaction_policy.html" 506 } 507 ] 508 } 509 ], 510 "lang" : "en", 511 "startAddress" : "192.0.2.0", 512 "endAddress" : "192.0.2.255", 513 "handle" : "XXXX-RIR", 514 "ipVersion" : "v4", 515 "name": "NET-RTR-1", 516 "description" : [ "A network used for example documentation" ], 517 "parentHandle" : "YYYY-RIR", 518 "remarks" : 519 [ 520 { 521 "description" : 522 [ 523 "She sells sea shells down by the sea shore.", 524 "Originally written by Terry Sullivan." 525 ] 526 } 527 ] 528 } 530 Figure 10 532 6. Object Classes 534 Object classes represent structures appropriate for a response from 535 the queries specified in [I-D.ietf-weirds-rdap-query]. 537 Each object class contains a "links" array as specified in 538 Section 5.2. For every object class in a response, whether the 539 object class is directly representing the response to a query or is 540 embedded in other object classes, servers SHOULD provide a link 541 representing a URI for that object class using the "self" 542 relationship as specified in the IANA registry specified by 543 [RFC5988]. As explained in Section 6.2, this may be not always be 544 possible for name server data. Clients MUST be able to process 545 object instances without a "self" link. When present, clients MAY 546 use the self link for caching data. Servers MAY provide more than 547 one "self" link for any given object instance. 549 This is an example of the "links" array with a self link to an object 550 class: 552 "links" : 553 [ 554 { 555 "value" : "http://example.com/ip/2001:db8::123", 556 "rel" : "self", 557 "href" : "http://example.com/ip/2001:db8::123" 558 } 559 ] 561 6.1. The Entity Object Class 563 The entity object class appears throughout this document and is an 564 appropriate response for the /entity/XXXX query defined in 565 Registration Data Access Protocol Lookup Format 566 [I-D.ietf-weirds-rdap-query]. This object class represents the 567 information of organizations, corporations, governments, non-profits, 568 clubs, individual persons, and informal groups of people. All of 569 these representations are so similar that it is best to represent 570 them in JSON [RFC4627] with one construct, the entity object class, 571 to aid in the re-use of code by implementers. 573 Some of the members of the entity object class are repeated in other 574 object classes described later in this document. 576 The entity object is served by both RIRs and DNRs. The following is 577 an example of an entity that might be served by an RIR: 579 { 580 "handle" : "XXXX", 581 "vCard" : 582 [ 583 [ "version", {}, "text", "4.0" ], 584 [ "fn", {}, "text", "Joe Bob, Inc." ], 585 [ "fn", {}, "text", "Bobby Joe Shopping" ], 586 [ "label", {}, "text", "123 Maple Ave\n", 587 "Suite 90001\n", 588 "Vancouver\n", 589 "BC\n", 590 "1239\n" ], 591 [ "email", {}, "text", "joe at bob.com" ], 592 [ "email", {}, "text", "bob at joe.com" ], 593 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ], 594 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ], 595 [ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ], 596 [ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ], 597 ], 598 "roles" : [ "registrant" ], 599 "remarks" : 600 [ 601 { 602 "description" : 603 [ 604 "She sells sea shells down by the sea shore.", 605 "Originally written by Terry Sullivan." 606 ] 607 } 608 ], 609 "links" : 610 [ 611 { 612 "value" : "http://example.com/entity/XXXX", 613 "rel" : "self", 614 "href" : "http://example.com/entity/XXXX" 615 } 616 ], 617 "events" : 618 [ 619 { 620 "eventAction" : "registration", 621 "eventDate" : "1990-12-31T23:59:60Z" 622 } 623 ], 624 "asEventActor" : 625 [ 626 { 627 "eventAction" : "last changed", 628 "eventDate" : "1991-12-31T23:59:60Z" 629 } 630 ] 631 } 633 This object has the following members: 635 o handle -- a string representing an registry unique identifier of 636 the entity 638 o vCard -- a JSON vCard with the entity's contact information 640 o roles -- an array of strings, each signifying the relationship an 641 object would have with its closest containing object (see 642 Appendix A.3 for suggested values) 644 o remarks -- see Section 5.3 646 o links -- see Section 5.2 648 o events -- see Section 5.5 650 o asEventActor -- this data structure takes the same form as the 651 'events' data structure (see Section 5.5), but each object in the 652 array MUST NOT have an 'eventActor' member. These objects denote 653 that the entity is an event actor for the given events. See 654 Appendix C regarding the various ways events can be modeled. 656 o status -- see Section 5.6 658 o port43 -- see Section 5.7 660 The following is an example of a entity that might be served by a 661 DNR: 663 { 664 "handle" : "XXXX", 665 "vCard" : 666 [ 667 [ "version", {}, "text", "4.0" ], 668 [ "fn", {}, "text", "Joe Bob, Inc." ], 669 [ "fn", {}, "text", "Bobby Joe Shopping" ], 670 [ "label", {}, "text", "123 Maple Ave\n", 671 "Suite 90001\n", 672 "Vancouver\n", 673 "BC\n", 674 "1239\n" ], 675 [ "email", {}, "text", "joe at bob.com" ], 676 [ "email", {}, "text", "bob at joe.com" ], 677 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ], 678 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ], 679 [ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ], 680 [ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ], 681 ], 682 "status" : [ "validated", "locked" ], 683 "remarks" : 684 [ 685 { 686 "description" : 687 [ 688 "She sells sea shells down by the sea shore.", 689 "Originally written by Terry Sullivan." 690 ] 691 } 692 ], 693 "links" : 694 [ 695 { 696 "value" : "http://example.com/entity/XXXX", 697 "rel" : "self", 698 "href" : "http://example.com/entity/XXXX" 699 } 700 ], 701 "port43" : "whois.example.net", 702 "events" : 703 [ 704 { 705 "eventAction" : "registration", 706 "eventDate" : "1990-12-31T23:59:60Z" 707 }, 708 { 709 "eventAction" : "last changed", 710 "eventDate" : "1991-12-31T23:59:60Z", 711 "eventActor" : "joe@bob.com" 712 } 713 ] 714 } 716 6.2. The Nameserver Object Class 717 The nameserver object class represents information regarding DNS name 718 servers used in both forward and reverse DNS. RIRs and some DNRs 719 register or expose nameserver information as an attribute of a domain 720 name, while other DNRs model nameservers as "first class objects". 722 The nameserver object class accommodates both models and degrees of 723 variation in between. 725 The following is an example of a nameserver object. 727 { 728 "handle" : "XXXX", 729 "ldhName" : "ns1.xn--fo-5ja.example", 730 "unicodeName" : "foo.example", 731 "status" : [ "active" ], 732 "ipAddresses" : 733 { 734 "v4": [ "192.0.2.1", "192.0.2.2" ], 735 "v6": [ "2001:db8::123" ] 736 }, 737 "remarks" : 738 [ 739 { 740 "description" : 741 [ 742 "She sells sea shells down by the sea shore.", 743 "Originally written by Terry Sullivan." 744 ] 745 } 746 ], 747 "links" : 748 [ 749 { 750 "value" : "http://example.net/nameserver/xxxx", 751 "rel" : "self", 752 "href" : "http://example.net/nameserver/xxxx" 753 } 754 ], 755 "port43" : "whois.example.net", 756 "events" : 757 [ 758 { 759 "eventAction" : "registration", 760 "eventDate" : "1990-12-31T23:59:60Z" 761 }, 762 { 763 "eventAction" : "last changed", 764 "eventDate" : "1991-12-31T23:59:60Z", 765 "eventActor" : "joe@bob.com" 766 } 767 ] 768 } 770 Figure 11 772 Figure 11 is an example of a nameserver object with all values given. 773 Registries using a first-class nameserver data model would embed this 774 in domain objects as well as allowing references to it with the "/ 775 nameserver" query type (all depending on the registry operators 776 policy). Other registries may pare back the information as needed. 777 Figure 12 is an example of a nameserver object as would be found in 778 RIRs and some DNRs, while Figure 13 is an example of a nameserver 779 object as would be found in other DNRs. 781 The following is an example of the simplest nameserver object: 783 { 784 "ldhName" : "ns1.example.com" 785 } 787 Figure 12 789 The following is an example of a simple nameserver object that might 790 be commonly used by DNRs: 792 { 793 "ldhName" : "ns1.example.com", 794 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 795 } 797 Figure 13 799 The nameserver object class has the following members: 801 o handle -- a string representing an registry unique identifier of 802 the nameserver 804 o ldhName -- a string containing the LDH name of the nameserver (see 805 Section 4) 807 o unicodeName -- a string containing a DNS unicode name of the 808 nameserver (see Section 4) 810 o ipAddresses -- an object containing the following members: 812 * v6 -- an array of strings containing IPv6 addresses of the 813 nameserver 815 * v4 -- an array of strings containing IPv4 addresses of the 816 nameserver 818 o status - see Section 5.6 820 o remarks - see Section 5.3 822 o links - see Section 5.2 824 o port43 - see Section 5.7 826 o events - see Section 5.5 828 6.3. The Domain Object Class 830 The domain object class represents a DNS name and point of 831 delegation. For RIRs these delegation points are in the reverse DNS 832 tree, whereas for DNRs these delegation points are in the forward DNS 833 tree. 835 In both cases, the high level structure of the domain object class 836 consists of information about the domain registration, nameserver 837 information related to the domain name, and entities related to the 838 domain name (e.g. registrant information, contacts, etc.). 840 The following is an elided example of the domain object showing the 841 high level structure: 843 { 844 "handle" : "XXX", 845 "ldhName" : "blah.example.com", 846 ... 847 "nameServers" : 848 [ 849 ... 850 ], 851 ... 852 "entities" : 853 [ 854 ... 855 ] 856 } 858 The following is a description of the members of this object: 860 o handle -- a string representing a registry unique identifier of 861 the domain object instance 863 o ldhName -- a string describing an domain name in LDH form as 864 described in Section 4 866 o unicodeName -- a string containing a domain name with u-labels as 867 described in Section 4 869 o variants -- an array of objects, each containing the following 870 values: 872 * relation -- an array of strings, with each string denoting the 873 relationship between the variants and the containing domain 874 object (see Appendix A.4 for a list of suggested variant 875 relations). 877 * variantNames -- an array of objects, with each object 878 containing an "ldhName" member and a "unicodeName" member (see 879 Section 4). 881 o nameservers -- an array of nameserver objects as defined by 882 Section 6.2 884 o delegationKeys -- an array of objects, each with the following 885 members: 887 * algorithm -- an integer as specified by the algorithm field of 888 a DNS DS record as specified by RFC 4034 [RFC4034] in 889 presentation format 891 * digest -- an string as specified by the digest field of a DNS 892 DS record as specified by RFC 4034 in presentation format 894 * digestType -- an integer as specified by the digest type field 895 of a DNS DS record as specified by RFC 4034 in presentation 896 format 898 * keyTag -- an integer as specified by the key tag field of a DNS 899 DS record as specified by RFC 4034 in presentation format 901 o entities -- an array of entity objects as defined by Section 6.1. 903 o status - see Section 5.6 905 o remarks - see Section 5.3 907 o links - see Section 5.2 909 o port43 - see Section 5.7 910 o events - see Section 5.5 912 The following is an example of a JSON domain object representing a 913 reverse DNS delegation point that might be served by an RIR: 915 { 916 "handle" : "XXXX", 917 "ldhName" : "192.in-addr.arpa", 918 "nameServers" : 919 [ 920 { "ldhName" : "ns1.rir.example" }, 921 { "ldhName" : "ns2.rir.example" } 922 ], 923 "delegationKeys" : 924 [ 925 { 926 "algorithm": 7, 927 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 928 "digestType" : 1, 929 "keyTag" : 53814 930 } 931 ], 932 "remarks" : 933 [ 934 { 935 "description" : 936 [ 937 "She sells sea shells down by the sea shore.", 938 "Originally written by Terry Sullivan." 939 ] 940 } 941 ], 942 "links" : 943 [ 944 { 945 "value": "http://example.net/domain/XXXX", 946 "rel" : "self", 947 "href" : "http://example.net/domain/XXXXX" 948 } 949 ], 950 "events" : 951 [ 952 { 953 "eventAction" : "registration", 954 "eventDate" : "1990-12-31T23:59:60Z" 955 }, 956 { 957 "eventAction" : "last changed", 958 "eventDate" : "1991-12-31T23:59:60Z", 959 "eventActor" : "joe@bob.com" 960 } 961 ], 962 "entities" : 963 [ 964 { 965 "handle" : "XXXX", 966 "vCard" : 967 [ 968 [ "version", {}, "text", "4.0" ], 969 [ "fn", {}, "text", "Joe Bob, Inc." ], 970 [ "fn", {}, "text", "Bobby Joe Shopping" ], 971 [ "label", {}, "text", "123 Maple Ave\n", 972 "Suite 90001\n", 973 "Vancouver\n", 974 "BC\n", 975 "1239\n" ], 976 [ "email", {}, "text", "joe at bob.com" ], 977 [ "email", {}, "text", "bob at joe.com" ], 978 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ], 979 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ], 980 [ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ], 981 [ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ], 982 ], 983 "roles" : [ "registrant" ], 984 "remarks" : 985 [ 986 { 987 "description" : 988 [ 989 "She sells sea shells down by the sea shore.", 990 "Originally written by Terry Sullivan." 991 ] 992 } 993 ], 994 "links" : 995 [ 996 { 997 "value": "http://example.net/entity/xxxx", 998 "rel" : "self", 999 "href" : "http://example.net/entity/xxxx" 1000 } 1001 ], 1002 "events" : 1003 [ 1004 { 1005 "eventAction" : "registration", 1006 "eventDate" : "1990-12-31T23:59:60Z" 1007 }, 1008 { 1009 "eventAction" : "last changed", 1010 "eventDate" : "1991-12-31T23:59:60Z", 1011 "eventActor" : "joe@bob.com" 1012 } 1013 ] 1014 } 1015 ] 1016 } 1018 The following is an example of a JSON domain object representing a 1019 forward DNS delegation point that might be served by a DNR: 1021 { 1022 "handle" : "XXXX", 1023 "ldhName" : "xn--fo-5ja.example", 1024 "unicodeName" : "foo.example", 1025 "variants" : 1026 [ 1027 { 1028 "relation" : [ "registered", "conjoined" ], 1029 "variantNames" : 1030 [ 1031 { 1032 "ldhName" : "xn--fo-cka.example", 1033 "unicodeName" : "foo.example" 1034 }, 1035 { 1036 "ldhName" : "xn--fo-fka.example", 1037 "unicodeName" : "foeo.example" 1038 } 1039 ] 1040 }, 1041 { 1042 "relation" : [ "unregistered", "restricted registration" ], 1043 "variantNames" : 1044 [ 1045 { 1046 "ldhName": "xn--fo-8ja.example", 1047 "unicodeName" : "foo.example" 1048 } 1049 ] 1051 } 1052 ], 1053 "status" : [ "locked", "transferProhibited" ], 1054 "nameServers" : 1055 [ 1056 { 1057 "handle" : "XXXX", 1058 "ldhName" : "ns1.example.com", 1059 "status" : [ "active" ], 1060 "ipAddresses" : 1061 { 1062 "v6": [ "2001:db8::123", "2001:db8::124" ], 1063 "v4": [ "192.0.2.1", "192.0.2.2" ] 1064 }, 1065 "remarks" : 1066 [ 1067 { 1068 "description" : 1069 [ 1070 "She sells sea shells down by the sea shore.", 1071 "Originally written by Terry Sullivan." 1072 ] 1073 } 1074 ], 1075 "links" : 1076 [ 1077 { 1078 "value" : "http://example.net/nameserver/XXXX", 1079 "rel" : "self", 1080 "href" : "http://example.net/nameserver/XXXX" 1081 } 1082 ], 1083 "events" : 1084 [ 1085 { 1086 "eventAction" : "registration", 1087 "eventDate" : "1990-12-31T23:59:60Z" 1088 }, 1089 { 1090 "eventAction" : "last changed", 1091 "eventDate" : "1991-12-31T23:59:60Z" 1092 } 1093 ] 1094 }, 1095 { 1096 "handle" : "XXXX", 1097 "ldhName" : "ns2.example.com", 1098 "status" : [ "active" ], 1099 "ipAddresses" : 1100 { 1101 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1102 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1103 }, 1104 "remarks" : 1105 [ 1106 { 1107 "description" : 1108 [ 1109 "She sells sea shells down by the sea shore.", 1110 "Originally written by Terry Sullivan." 1111 ] 1112 } 1113 ], 1114 "links" : 1115 [ 1116 { 1117 "value" : "http://example.net/nameserver/XXXX", 1118 "rel" : "self", 1119 "href" : "http://example.net/nameserver/XXXX" 1120 } 1121 ], 1122 "events" : 1123 [ 1124 { 1125 "eventAction" : "registration", 1126 "eventDate" : "1990-12-31T23:59:60Z" 1127 }, 1128 { 1129 "eventAction" : "last changed", 1130 "eventDate" : "1991-12-31T23:59:60Z" 1131 } 1132 ] 1133 } 1134 ], 1135 "delegationKeys" : 1136 [ 1137 { 1138 "algorithm": 7, 1139 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 1140 "digestType" : 1, 1141 "keyTag" : 53814 1142 } 1143 ], 1144 "remarks" : 1145 [ 1146 { 1147 "description" : 1148 [ 1149 "She sells sea shells down by the sea shore.", 1150 "Originally written by Terry Sullivan." 1151 ] 1152 } 1153 ], 1154 "links" : 1155 [ 1156 { 1157 "value": "http://example.net/domain/XXXX", 1158 "rel" : "self", 1159 "href" : "http://example.net/domain/XXXX" 1160 } 1161 ], 1162 "port43" : "whois.example.net", 1163 "events" : 1164 [ 1165 { 1166 "eventAction" : "registration", 1167 "eventDate" : "1990-12-31T23:59:60Z" 1168 }, 1169 { 1170 "eventAction" : "last changed", 1171 "eventDate" : "1991-12-31T23:59:60Z", 1172 "eventActor" : "joe@bob.com" 1173 }, 1174 { 1175 "eventAction" : "transfer", 1176 "eventDate" : "1991-12-31T23:59:60Z", 1177 "eventActor" : "joe@bob.com" 1178 }, 1179 { 1180 "eventAction" : "expiration", 1181 "eventDate" : "2016-12-31T23:59:60Z", 1182 "eventActor" : "joe@bob.com" 1183 } 1184 ], 1185 "entities" : 1186 [ 1187 { 1188 "handle" : "XXXX", 1189 "vCard" : 1190 [ 1191 [ "version", {}, "text", "4.0" ], 1192 [ "fn", {}, "text", "Joe Bob, Inc." ], 1193 [ "fn", {}, "text", "Bobby Joe Shopping" ], 1194 [ "label", {}, "text", "123 Maple Ave\n", 1195 "Suite 90001\n", 1196 "Vancouver\n", 1197 "BC\n", 1198 "1239\n" ], 1199 [ "email", {}, "text", "joe at bob.com" ], 1200 [ "email", {}, "text", "bob at joe.com" ], 1201 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ], 1202 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ], 1203 [ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ], 1204 [ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ], 1205 ], 1206 "status" : [ "validated", "locked" ], 1207 "roles" : [ "registrant" ], 1208 "remarks" : 1209 [ 1210 { 1211 "description" : 1212 [ 1213 "She sells sea shells down by the sea shore.", 1214 "Originally written by Terry Sullivan." 1215 ] 1216 } 1217 ], 1218 "links" : 1219 [ 1220 { 1221 "value" : "http://example.net/entity/xxxx", 1222 "rel" : "self", 1223 "href" : "http://example.net/entity/xxxx" 1224 } 1225 ], 1226 "events" : 1227 [ 1228 { 1229 "eventAction" : "registration", 1230 "eventDate" : "1990-12-31T23:59:60Z" 1231 }, 1232 { 1233 "eventAction" : "last changed", 1234 "eventDate" : "1991-12-31T23:59:60Z" 1235 } 1236 ] 1237 } 1238 ] 1239 } 1241 6.4. The IP Network Object Class 1243 The IP Network object class models IP network registrations found in 1244 RIRs and is the expected response for the "/ip" query as defined by 1245 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1246 for DNRs. The high level structure of the IP network object class 1247 consists of information about the network registration and entities 1248 related to the IP network (e.g. registrant information, contacts, 1249 etc...). 1251 The following is an elided example of the IP network object type 1252 showing the high level structure: 1254 { 1255 "handle" : "XXX", 1256 ... 1257 "entities" : 1258 [ 1259 ... 1260 ] 1261 } 1263 The following is an example of the JSON object for the network 1264 registration information 1266 { 1267 "handle" : "XXXX-RIR", 1268 "startAddress" : "2001:db8::0", 1269 "endAddress" : "2001:db8::0:FFFF:FFFF:FFFF:FFFF:FFFF", 1270 "ipVersion" : "v6", 1271 "name": "NET-RTR-1", 1272 "description" : [ "A network used for routing" ], 1273 "type" : "DIRECT ALLOCATION", 1274 "country" : "AU", 1275 "parentHandle" : "YYYY-RIR", 1276 "status" : [ "allocated" ], 1277 "remarks" : 1278 [ 1279 { 1280 "description" : 1281 [ 1282 "She sells sea shells down by the sea shore.", 1283 "Originally written by Terry Sullivan." 1284 ] 1286 } 1287 ], 1288 "links" : 1289 [ 1290 { 1291 "value" : "http://example.ent/ip/2001:db8::/48", 1292 "rel" : "self", 1293 "href" : "http://example.net/ip/2001:db8::/48" 1294 }, 1295 { 1296 "value" : "http://example.net/ip/2001:db8::/48", 1297 "rel" : "up", 1298 "href" : "http://example.net/ip/2001:C00::/23" 1299 } 1300 ], 1301 "events" : 1302 [ 1303 { 1304 "eventAction" : "registration", 1305 "eventDate" : "1990-12-31T23:59:60Z" 1306 }, 1307 { 1308 "eventAction" : "last changed", 1309 "eventDate" : "1991-12-31T23:59:60Z" 1310 } 1311 ], 1312 "entities" : 1313 [ 1314 { 1315 "handle" : "XXXX", 1316 "vCard" : 1317 [ 1318 [ "version", {}, "text", "4.0" ], 1319 [ "fn", {}, "text", "Joe Bob, Inc." ], 1320 [ "fn", {}, "text", "Bobby Joe Shopping" ], 1321 [ "label", {}, "text", "123 Maple Ave\n", 1322 "Suite 90001\n", 1323 "Vancouver\n", 1324 "BC\n", 1325 "1239\n" ], 1326 [ "email", {}, "text", "joe at bob.com" ], 1327 [ "email", {}, "text", "bob at joe.com" ], 1328 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ], 1329 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ], 1330 [ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ], 1331 [ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ], 1332 ], 1333 "roles" : [ "registrant" ], 1334 "remarks" : 1335 [ 1336 { 1337 "description" : 1338 [ 1339 "She sells sea shells down by the sea shore.", 1340 "Originally written by Terry Sullivan." 1341 ] 1342 } 1343 ], 1344 "links" : 1345 [ 1346 { 1347 "value" : "http://example.net/entity/xxxx", 1348 "rel" : "self", 1349 "href" : "http://example.net/entity/xxxx" 1350 } 1351 ], 1352 "events" : 1353 [ 1354 { 1355 "eventAction" : "registration", 1356 "eventDate" : "1990-12-31T23:59:60Z" 1357 }, 1358 { 1359 "eventAction" : "last changed", 1360 "eventDate" : "1991-12-31T23:59:60Z" 1361 } 1362 ] 1363 } 1364 ] 1365 } 1367 The following is a description of the members of this object: 1369 o handle -- a string representing an RIR unique identifier of the 1370 network registration 1372 o startAddress -- the starting IP address of the network, either 1373 IPv4 or IPv6 1375 o endAddress -- the ending IP address of the network, either IPv4 or 1376 IPv6 1378 o ipVersion -- an string signifying the IP protocol version of the 1379 network: "v4" signifying an IPv4 network, "v6" signifying an IPv6 1380 network 1382 o name -- an identifier assigned to the network registration by the 1383 registration holder 1385 o description -- an array of strings containing descriptive text 1386 about the network registration 1388 o type -- a string containing an RIR-specific classification of the 1389 network 1391 o country -- a string containing the name of the 2 character country 1392 code of the network 1394 o parentHandle -- a string containing an RIR-unique identifier of 1395 the parent network of this network registration 1397 o status -- an array of strings indicating the state of the IP 1398 network 1400 o entities -- an array of entity objects as defined by Section 6.1. 1402 o remarks - see Section 5.3 1404 o links - see Section 5.2 1406 o events - see Section 5.5 1408 6.5. Autonomous System Number Entity Object Class 1410 The Autonomous System Number (autnum) object class models Autonomous 1411 System Number registrations found in RIRs and represents the expected 1412 response to an "/autnum" query as defined by 1413 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1414 for DNRs. The high level structure of the autnum object class 1415 consists of information about the network registration and entities 1416 related to the autnum registration (e.g. registrant information, 1417 contacts, etc.), and is similar to the IP Network entity object 1418 class. 1420 The following is an example of a JSON object representing an autnum. 1422 { 1423 "handle" : "XXXX-RIR", 1424 "startAutnum" : "10", 1425 "endAutnum" : "15", 1426 "name": "AS-RTR-1", 1427 "description" : [ "AS for Exchange" ], 1428 "type" : "DIRECT ALLOCATION", 1429 "country": "AU", 1430 "remarks" : 1431 [ 1432 { 1433 "description" : 1434 [ 1435 "She sells sea shells down by the sea shore.", 1436 "Originally written by Terry Sullivan." 1437 ] 1438 } 1439 ], 1440 "links" : 1441 [ 1442 { 1443 "value" : "http://example.net/autnum/xxxx", 1444 "rel" : "self", 1445 "href" : "http://example.net/autnum/xxxx" 1446 } 1447 ], 1448 "events" : 1449 [ 1450 { 1451 "eventAction" : "registration", 1452 "eventDate" : "1990-12-31T23:59:60Z" 1453 }, 1454 { 1455 "eventAction" : "last changed", 1456 "eventDate" : "1991-12-31T23:59:60Z" 1457 } 1458 ], 1459 "entities" : 1460 [ 1461 { 1462 "handle" : "XXXX", 1463 "vCard" : 1464 [ 1465 [ "version", {}, "text", "4.0" ], 1466 [ "fn", {}, "text", "Joe Bob, Inc." ], 1467 [ "fn", {}, "text", "Bobby Joe Shopping" ], 1468 [ "label", {}, "text", "123 Maple Ave\n", 1469 "Suite 90001\n", 1470 "Vancouver\n", 1471 "BC\n", 1472 "1239\n" ], 1474 [ "email", {}, "text", "joe at bob.com" ], 1475 [ "email", {}, "text", "bob at joe.com" ], 1476 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ], 1477 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ], 1478 [ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ], 1479 [ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ], 1480 ], 1481 "roles" : [ "registrant" ], 1482 "remarks" : 1483 [ 1484 { 1485 "description" : 1486 [ 1487 "She sells sea shells down by the sea shore.", 1488 "Originally written by Terry Sullivan." 1489 ] 1490 } 1491 ], 1492 "links" : 1493 [ 1494 { 1495 "value" : "http://example.net/entity/XXXX", 1496 "rel" : "self", 1497 "href" : "http://example.net/entity/XXXX" 1498 } 1499 ], 1500 "events" : 1501 [ 1502 { 1503 "eventAction" : "registration", 1504 "eventDate" : "1990-12-31T23:59:60Z" 1505 }, 1506 { 1507 "eventAction" : "last changed", 1508 "eventDate" : "1991-12-31T23:59:60Z" 1509 } 1510 ] 1511 } 1512 ] 1513 } 1515 The following is a description of the members of this object: 1517 o handle -- a string representing an RIR-unique identifier of the 1518 autnum registration 1520 o startAutnum -- the starting number [RFC5396] in the block of 1521 autonomous system numbers 1523 o endAutnum -- the ending number [RFC5396] in the block of 1524 autonomous system numbers 1526 o name -- an identifier assigned to the autnum registration by the 1527 registration holder 1529 o description -- an array of strings containing descriptive text 1530 about the autnum registration 1532 o type -- a string containing an RIR-specific classification of the 1533 autnum 1535 o country -- a string containing the name of the 2 character country 1536 code of the autnum 1538 o remarks - see Section 5.3 1540 o links - see Section 5.2 1542 o events - see Section 5.5 1544 7. Error Response Body 1546 Some non-answer responses may return entity bodies with information 1547 that could be more descriptive. 1549 The basic structure of that response is an object class containing an 1550 error code number (corresponding to the HTTP response code) followed 1551 by a string named "title" followed by an array of strings named 1552 "description". 1554 This is an example of the JSON version of the common response body: 1556 { 1557 "errorCode": 418, 1558 "title": "Your beverage choice is not available", 1559 "description": 1560 [ 1561 "I know coffee has more ummppphhh.", 1562 "But I cannot provide." 1563 ] 1564 } 1566 Figure 14 1568 A client MAY simply use the HTTP response code as the server is not 1569 required to include error data in the response body. However, if a 1570 client wishes to parse the error data, it SHOULD first check that the 1571 Content-Type header contains the appropriate media type. 1573 8. IANA Considerations 1575 None. 1577 9. Security Considerations 1579 This specification models information serialized in JSON format. As 1580 JSON is a subset of Javascript, implementations are advised to follow 1581 the security considerations outlined in Section 6 of [RFC4627] to 1582 prevent code injection. 1584 10. Internationalization Considerations 1586 10.1. Character Encoding 1588 The default text encoding for JSON and XML responses in RDAP is 1589 UTF-8, and all servers and clients MUST support UTF-8. Servers and 1590 clients MAY optionally support other character encodings. 1592 10.2. URIs and IRIs 1594 [I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in 1595 RDAP. 1597 10.3. Language Tags 1599 Section 5.4 defines the use of language tags in the JSON responses 1600 defined in this document. 1602 10.4. Internationalized Domain Names 1604 Internationalized Domain Names (IDNs) are denoted in this 1605 specification by the separation of DNS names in LDH form and Unicode 1606 form (see Section 4). Representation of IDNs in registries is 1607 described by the "variants" object in Section 6.3 and the suggested 1608 values listed in Appendix A.4. 1610 11. Privacy Considerations 1611 This specification suggests status values to denote contact and 1612 registrant information that has been marked as private and/or has 1613 been redacted or obscured. See Appendix A.1 for the list of status 1614 values. See Appendix B.1 on guidance to apply those values to 1615 contacts and registrants. 1617 12. Contributing Authors and Acknowledgements 1619 This document is derived from original work on RIR responses in JSON 1620 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew 1621 L. Newton. Additionally, this document incorporates word on DNR 1622 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 1623 Shen. 1625 The components of the DNR object classes are derived from a 1626 categorization of WHOIS response formats created by Ning Kong, Linlin 1627 Zhou, and Guangqing Deng, Steve Sheng and Francisco Arias, Ray 1628 Bellis, and Frederico Neves. 1630 Ed Lewis contributed significant review comments and provided 1631 clarifying text. James Mitchel provided text regarding the 1632 processing of unknown JSON attributes and identified issues leading 1633 to the remodeling of events. Ernie Dainow and Francisco Obispo 1634 provided concrete suggestions that led to a better variant model for 1635 domain names. 1637 The switch to and incorporation of JSON vCard was performed by Simon 1638 Perreault. 1640 13. References 1642 13.1. Normative References 1644 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1645 1981. 1647 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 1648 numbers", RFC 1166, July 1990. 1650 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1651 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1652 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1654 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1655 Internet: Timestamps", RFC 3339, July 2002. 1657 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1658 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1659 3986, January 2005. 1661 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 1662 Rose, "Resource Records for the DNS Security Extensions", 1663 RFC 4034, March 2005. 1665 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 1666 Clarification", RFC 4343, January 2006. 1668 [RFC4627] Crockford, D., "The application/json Media Type for 1669 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1671 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1672 October 2008. 1674 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 1675 Autonomous System (AS) Numbers", RFC 5396, December 2008. 1677 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1678 Languages", BCP 47, RFC 5646, September 2009. 1680 [RFC5890] Klensin, J., "Internationalized Domain Names for 1681 Applications (IDNA): Definitions and Document Framework", 1682 RFC 5890, August 2010. 1684 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1685 Address Text Representation", RFC 5952, August 2010. 1687 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1689 [I-D.kewisch-vcard-in-json] 1690 Kewisch, P., "jCard: The JSON format for vCard", draft- 1691 kewisch-vcard-in-json-01 (work in progress), March 2013. 1693 [ISO.3166.1988] 1694 International Organization for Standardization, "Codes for 1695 the representation of names of countries, 3rd edition", 1696 ISO Standard 3166, August 1988. 1698 [I-D.ietf-weirds-rdap-query] 1699 Newton, A. and S. Hollenbeck, "RDAP Query Format", draft- 1700 ietf-weirds-rdap-query-00 (work in progress), September 1701 2011. 1703 [I-D.ietf-weirds-using-http] 1704 Newton, A., Ellacott, B., and N. Kong, "Using HTTP for 1705 RESTful Whois Services by Internet Registries", draft- 1706 ietf-weirds-using-http-01 (work in progress), May 2012. 1708 13.2. Informative References 1710 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 1711 September 2004. 1713 [RFC3730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 1714 RFC 3730, March 2004. 1716 [JSON_acendancy] 1717 MacVittie, , "The Stealthy Ascendancy of JSON", 04 2011. 1719 [JSON_performance_study] 1720 Montana State University - Bozeman, Montana State 1721 University - Bozeman, Montana State University - Bozeman, 1722 Montana State University - Bozeman, "Comparison of JSON 1723 and XML Data Interchange Formats: A Case Study", 2009. 1725 Appendix A. Suggested Values 1727 Due to the wide variation between the hundreds of registry operators 1728 and the on-going policy refinement by registry communities, values of 1729 some data cannot be formally standardized. This section lists 1730 suggested values for such data but is not nor will ever be a complete 1731 list of values and their meanings. 1733 A.1. Status 1735 Many of the object classes have a member named 'status'. This member 1736 is an array of strings, with each string denoting a status associated 1737 with the containing object. The following is a list of suggested 1738 values to use in the 'status' array: 1740 o 'validated' -- Signifies that the data of the object instance has 1741 been found to be accurate. This type of status is usually found 1742 on entity object instances to note the validity of identifying 1743 contact information. 1745 o 'update prohibited' -- Updates to the object instance are 1746 forbidden. 1748 o 'transfer prohibited' -- Transfers of the registration from one 1749 registrar to another are forbidden. This type of status normally 1750 applies to DNR domain names. 1752 o 'delete prohibited' -- Deletion of the registration of the object 1753 instance is forbidden. This type of status normally applies to 1754 DNR domain names. 1756 o 'proxy' -- The registration of the object instance has been 1757 performed by a third party. This is most commonly applied to 1758 entities. 1760 o 'private' -- The information of the object instance is not 1761 designated for public consumption. This is most commonly applied 1762 to entities. 1764 o 'redacted' -- Some of the information of the object instance has 1765 not been made available. This is most commonly applied to 1766 entities. 1768 o 'obscured' -- Some of the information of the object instance has 1769 been altered for the purposes of not readily revealing the actual 1770 information of the object instance. This is most commonly applied 1771 to entities. 1773 A.2. Event Actions 1775 Section 5.5 describes a data structure for denoting events against 1776 object classes. Each event can have an event action, which is a 1777 string. The following is a list of suggested values to use for event 1778 actions: 1780 o 'registration' -- the object instance was initially registered 1782 o 'reregistration' -- the object instance was registered 1783 subsequently to initial registration 1785 o 'last changed' -- when the information in the object instance was 1786 last changed 1788 o 'expiration' -- the object instance has been removed or will be 1789 removed at a pre-determined date and time from the registry 1791 o 'deletion' -- the object instance was removed from the registry at 1792 a point in time that was not pre-determined 1794 o 'reinstantation' -- the object instance was reregistered after 1795 having been removed from the registry 1797 o 'transfer' -- the object instance was transfered from one 1798 registrant to another 1800 A.3. Roles 1802 Entity object classes have a member named 'roles'. This member is an 1803 array of strings, with each string indicating the role or 1804 relationship the entity object instance has with a containing object, 1805 such as a domain name or IP network. An entity object instance can 1806 have more than one type of relationship with a containing object. 1807 The following is a list of suggested values to use in the 'roles' 1808 array: 1810 o 'registrant' -- The entity object instance is the registrant of 1811 the registration. 1813 o 'tech' -- The entity object instance is a technical contact for 1814 the registration. 1816 o 'admin' -- The entity object instance is an administrative contact 1817 for the registration. 1819 o 'abuse' -- The entity object instance handles network abuse issues 1820 on behalf of the registrant of the registration. 1822 o 'billing' -- The entity object instance handles payment and 1823 billing issues on behalf of the registrant of the registration. 1825 o 'registrar' -- The entity object instance represents the authority 1826 responsible for the registration in the registry. 1828 o 'reseller' -- The entity object instance represents a third party 1829 through which the registration was conducted (i.e. not the 1830 registry or registrar). 1832 o 'sponsor' -- The entity object instance represents a domain policy 1833 sponsor, such as an ICANN approved sponsor 1835 A.4. Variant Relations 1837 Section 6.3 describes a structure for noting variants of domain names 1838 and the relationship those variants have with a registered domain 1839 name. The following is a list of suggested values to use as the 1840 variant relation values: 1842 o 'registered' -- the variant names are registered in the registry. 1844 o 'unregistered' -- the variant names are not found in the registry. 1846 o 'restricted registration' -- registration of the variant names is 1847 restricted to certain parties or within certain rules. 1849 o 'open registration' -- registration of the variant names is 1850 available to generally qualified registrants. 1852 o 'conjoined' -- registration of the variant names is occurs 1853 automatically with the registration of the containing domain 1854 registration. 1856 Appendix B. Suggested Data Modeling with the Entity Object Class 1858 B.1. Registrants and Contacts 1860 This document does not provide specific object classes for 1861 registrants and contacts. Instead the entity object class may be 1862 used to represent a registrant or contact. When the entity object is 1863 embedded inside a containing object such as a domain name or IP 1864 network, the 'roles' string array can be used to signify the 1865 relationship. It is recommended that the values from Appendix A.3 be 1866 used. 1868 The following is an example of an elided containing object with an 1869 embedded entity that is both a registrant and admin contact: 1871 { 1872 ... 1873 "entities" : 1874 [ 1875 { 1876 "handle" : "XXXX", 1877 "vCard" : 1878 [ 1879 [ "version", {}, "text", "4.0" ], 1880 [ "fn", {}, "text", "Joe Bob, Inc." ], 1881 [ "fn", {}, "text", "Bobby Joe Shopping" ], 1882 [ "label", {}, "text", "123 Maple Ave\n", 1883 "Suite 90001\n", 1884 "Vancouver\n", 1885 "BC\n", 1886 "1239\n" ], 1887 [ "email", {}, "text", "joe at bob.com" ], 1888 [ "email", {}, "text", "bob at joe.com" ], 1889 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ], 1890 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ], 1891 [ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ], 1892 [ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ], 1893 ], 1894 "roles" : [ "registrant", "admin" ], 1895 "remarks" : 1897 [ 1898 { 1899 "description" : 1900 [ 1901 "She sells sea shells down by the sea shore.", 1902 "Originally written by Terry Sullivan." 1903 ] 1904 } 1905 ], 1906 "events" : 1907 [ 1908 { 1909 "eventAction" : "registration", 1910 "eventDate" : "1990-12-31T23:59:60Z" 1911 }, 1912 { 1913 "eventAction" : "last changed", 1914 "eventDate" : "1991-12-31T23:59:60Z" 1915 } 1916 ] 1917 } 1918 ] 1919 } 1921 In many use cases, it is necessary to hide or obscure the information 1922 of a registrant or contact due to policy or other operational 1923 matters. Registries can denote these situations with 'status' values 1924 (see Appendix A.1). 1926 The following is an elided example of a registrant with information 1927 changed to reflect that of a third party. 1929 { 1930 ... 1931 "entities" : 1932 [ 1933 { 1934 "handle" : "XXXX", 1935 ... 1936 "roles" : [ "registrant", "admin" ], 1937 "status" : [ "proxy", "private", "obscured" ] 1938 } 1939 ] 1940 } 1942 B.2. Registrars 1944 This document does not provide a specific object class for 1945 registrars, but like registrants and contacts (see Appendix B.1) the 1946 'roles' string array maybe used. 1948 The following is an example of an elided containing object with an 1949 embedded entity that is a registrar: 1951 { 1952 ... 1953 "entities" : 1954 [ 1955 { 1956 "handle" : "XXXX", 1957 "vCard" : 1958 [ 1959 [ "version", {}, "text", "4.0" ], 1960 [ "fn", {}, "text", "RegistrarsRUS" ], 1961 [ "label", {}, "text", "1212 Tulip Ave\n", 1962 "Suite 1\n", 1963 "Marina Del Rey\n", 1964 "CA\n", 1965 "12393-2193" ], 1966 [ "email", {}, "text", "joe at bob.com" ], 1967 [ "email", {}, "text", "bob at joe.com" ], 1968 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4321" ], 1969 [ "tel", { "type": "work" }, "uri", "tel:+1-958-555-4322" ], 1970 [ "tel", { "type": "fax" }, "uri", "tel:+1-958-555-4323" ], 1971 [ "tel", { "type": "cell" }, "uri", "tel:+1-958-555-4324" ], 1972 ], 1973 "roles" : [ "registrar" ], 1974 "remarks" : 1975 [ 1976 { 1977 "description" : 1978 [ 1979 "She sells sea shells down by the sea shore.", 1980 "Originally written by Terry Sullivan." 1981 ] 1982 } 1983 ], 1984 "links" : 1985 [ 1986 { 1987 "value" : "http://example.net/entity/XXXX", 1988 "rel" : "alternate", 1989 "type" : "text/html", 1990 "href" : "http://www.example.com" 1991 } 1992 ] 1993 } 1994 ] 1995 } 1997 Appendix C. Modeling Events 1999 Events represent actions that have taken place against a registered 2000 object at a certain date and time. Events have three properties: the 2001 action, the actor, and the date and time of the event (which is 2002 sometimes in the future). In some cases the identity of the actor is 2003 not captured. 2005 Events can be modeled in three ways: 2007 1. events with no designated actor 2009 2. events where the actor is only designated by an identifier 2011 3. events where the actor can be modeled as an entity 2013 For the first use case, the 'events' data structure (Section 5.5) is 2014 used without the 'eventActor' object member. 2016 This is an example of an "events" array without the 'eventActor'. 2018 "events" : 2019 [ 2020 { 2021 "eventAction" : "registration", 2022 "eventDate" : "1990-12-31T23:59:60Z" 2023 } 2024 ] 2026 Figure 15 2028 For the second use case, the 'events' data structure (Section 5.5) is 2029 used with the 'eventActor' object member. 2031 This is an example of an "events" array with the 'eventActor'. 2033 "events" : 2034 [ 2035 { 2036 "eventAction" : "registration", 2037 "eventActor" : "XYZ-NIC", 2038 "eventDate" : "1990-12-31T23:59:60Z" 2039 } 2040 ] 2042 Figure 16 2044 For the third use case, the 'asEventActor' array is used when an 2045 entity (Section 6.1) is embedded into another object class. The 2046 'asEventActor' array follows the same structure as the 'events' array 2047 but does not have 'eventActor' attributes. 2049 The following is an elided example of a domain object with an entity 2050 as an event actor. 2052 { 2053 "handle" : "XXXX", 2054 "ldhName" : "foo.example", 2055 "status" : [ "locked", "transfer Prohibited" ], 2056 ... 2057 "entities" : 2058 [ 2059 { 2060 "handle" : "XXXX", 2061 ... 2062 "asEventActor" : 2063 [ 2064 { 2065 "eventAction" : "last changed", 2066 "eventDate" : "1990-12-31T23:59:60Z" 2067 } 2068 ] 2069 } 2070 ] 2071 } 2073 Appendix D. Motivations for Using JSON 2075 This section addresses a common question regarding the use of JSON 2076 over other data formats, most notably XML. 2078 It is often pointed out that many DNRs and one RIR support the EPP 2079 [RFC3730] standard, which is an XML serialized protocol. The logic 2080 is that since EPP is a common protocol in the industry it follows 2081 that XML would be a more natural choice. While EPP does influence 2082 this specification quite a bit, EPP serves a different purpose which 2083 is the provisioning of Internet resources between registries and 2084 accredited registrars and serves a much narrower audience than that 2085 envisioned for RDAP. 2087 By contrast, RDAP has a broader audience and is designed for public 2088 consumption of data. Experience from RIRs with first generation 2089 RESTful web services for Whois indicate a large percentage of clients 2090 operate within browsers and other platforms where full-blown XML 2091 stacks are not readily available and where JSON is a better fit. 2093 Additionally, while EPP is used in much of the DNR community it is 2094 not a universal constant in that industry. And finally, EPP's use of 2095 XML predates the specification of JSON. If EPP had been defined 2096 today, it may very well have used JSON instead of XML. 2098 Beyond the specific DNR and RIR communities, the trend in the broader 2099 Internet industry is also switching to JSON over XML, especially in 2100 the area of RESTful web services (see [JSON_acendancy]). Studies 2101 have also found that JSON is generally less bulky and consequently 2102 faster to parse (see [JSON_performance_study]). 2104 Appendix E. Changelog 2106 Initial -00 Adopted as working group document 2012-September-18. 2108 -01 2110 Minor spelling corrections. Changed "Registry Data" to 2111 "Registration Data" for the sake of consistency. 2113 Transitioned to RFC 5988 links and relationship types from our 2114 own custom "uris" structure. 2116 Some examples had 'status' as a string. Those have been 2117 corrected as 'status' is always an array of strings. 2119 Domain variants can now have a multi-valued relationship with 2120 domain registrations. 2122 "names" in the entity object class was changed to 2123 "entityNames". 2125 Some IP address examples change to IPv6. 2127 Change phone number examples and added reference to E.164. 2129 Added section on motivations for using JSON. 2131 Added error response body section. 2133 Added JSON naming section. 2135 Added common data structures section. 2137 Added the IANA Considerations section and the media type 2138 registration. 2140 Added 'lang' name/value. 2142 Added internationalization considerations section. 2144 -02 2146 Removed level from media type registration. 2148 Textual changes as given by Ed Lewis. 2150 Fixed object class linking example noted by Francisco Obispo 2152 Fixed a lot of other examples called out by Alex Sergeyev 2154 Added a note that JSON names are case sensitive 2156 Added 'status' to IP networks as suggested by Alex Sergeyev 2158 -03 2160 Added jCard verbiage and examples and deleted overlapping 2161 contact information and the appendix on postal addresses 2163 Removed the IANA considerations as they have been moved to 2164 another document 2166 Changed the remarks structure to be like notices 2168 Reordering and rewording some of the sections so they flow 2169 better 2171 Added note about object class "self" links 2173 Changed ipAddresses in nameserver object class to separate out 2174 v6 from v4 2176 Changed IP network version identifier from integer to string to 2177 be more consistent with ipAddresses identifier in nameserver 2178 object classes 2180 Changed DNS names to LDH names and Unicode names 2182 Modified the definition of 'conjoined' variant relationship so 2183 it was circular 2184 Added 'proxy', 'private', 'redacted', and 'obscured' status 2185 values (most useful for entities). 2187 Added a privacy considerations section 2189 Added a security considerations section 2191 Added 'reseller' and 'sponsor' to the list of entity roles 2193 Added the 'events' common data structure 2195 Added 'asEventActor' to entities 2197 Added appendix on event modeling 2199 Removed the subclasses/superclassing between RIRs/DNRs for 2200 entity and domain object classes 2202 Change suggested status/relation/etc values to be case/spacing 2203 consistent 2205 Normalized some of the definitions of object class members 2207 Modifying the JSON signaling section to reference the guidance 2208 in draft-ietf-weirds-using-http 2210 Changed the text regarding the process of unknown JSON 2211 attributes 2213 Authors' Addresses 2215 Andrew Lee Newton 2216 American Registry for Internet Numbers 2217 3635 Concorde Parkway 2218 Chantilly, VA 20151 2219 US 2221 Email: andy@arin.net 2222 URI: http://www.arin.net 2223 Scott Hollenbeck 2224 Verisign Labs 2225 12061 Bluemont Way 2226 Reston, VA 20190 2227 US 2229 Email: shollenbeck@verisign.com 2230 URI: http://www.verisignlabs.com/