idnits 2.17.1 draft-ietf-weirds-json-response-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 8, 2014) is 3486 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) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-15) exists of draft-ietf-weirds-using-http-12 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-using-http' == Outdated reference: A later version (-18) exists of draft-ietf-weirds-rdap-query-14 == Outdated reference: A later version (-12) exists of draft-ietf-weirds-rdap-sec-09 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-rdap-sec' Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track S. Hollenbeck 5 Expires: April 11, 2015 Verisign Labs 6 October 8, 2014 8 JSON Responses for the Registration Data Access Protocol (RDAP) 9 draft-ietf-weirds-json-response-10 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 April 11, 2015. 36 Copyright Notice 38 Copyright (c) 2014 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Terminology and Definitions . . . . . . . . . . . . . . . 3 55 1.2. Data Model . . . . . . . . . . . . . . . . . . . . . . . 4 56 2. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.1. Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3. Common Data Types . . . . . . . . . . . . . . . . . . . . . . 7 59 4. Common Data Structures . . . . . . . . . . . . . . . . . . . 9 60 4.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 9 61 4.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 4.3. Notices And Remarks . . . . . . . . . . . . . . . . . . . 10 63 4.4. Language Identifier . . . . . . . . . . . . . . . . . . . 12 64 4.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 4.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 14 66 4.7. Port 43 WHOIS Server . . . . . . . . . . . . . . . . . . 14 67 4.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 14 68 4.9. Object Class Name . . . . . . . . . . . . . . . . . . . . 14 69 4.10. An Example . . . . . . . . . . . . . . . . . . . . . . . 15 70 5. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 17 71 5.1. The Entity Object Class . . . . . . . . . . . . . . . . . 17 72 5.2. The Nameserver Object Class . . . . . . . . . . . . . . . 24 73 5.3. The Domain Object Class . . . . . . . . . . . . . . . . . 28 74 5.4. The IP Network Object Class . . . . . . . . . . . . . . . 40 75 5.5. Autonomous System Number Entity Object Class . . . . . . 44 76 6. Error Response Body . . . . . . . . . . . . . . . . . . . . . 47 77 7. Responding to Help Queries . . . . . . . . . . . . . . . . . 49 78 8. Responding To Searches . . . . . . . . . . . . . . . . . . . 50 79 9. Indicating Truncated Responses . . . . . . . . . . . . . . . 51 80 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 81 10.1. RDAP JSON Media Type Registration . . . . . . . . . . . 54 82 10.2. JSON Values Registry . . . . . . . . . . . . . . . . . . 55 83 10.2.1. Notice and Remark Types . . . . . . . . . . . . . . 56 84 10.2.2. Status . . . . . . . . . . . . . . . . . . . . . . . 58 85 10.2.3. Event Actions . . . . . . . . . . . . . . . . . . . 63 86 10.2.4. Roles . . . . . . . . . . . . . . . . . . . . . . . 66 87 10.2.5. Variant Relations . . . . . . . . . . . . . . . . . 69 88 11. Security Considerations . . . . . . . . . . . . . . . . . . . 70 89 12. Internationalization Considerations . . . . . . . . . . . . . 71 90 12.1. Character Encoding . . . . . . . . . . . . . . . . . . . 71 91 12.2. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 71 92 12.3. Language Tags . . . . . . . . . . . . . . . . . . . . . 71 93 12.4. Internationalized Domain Names . . . . . . . . . . . . . 71 94 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 71 95 14. Contributing Authors and Acknowledgements . . . . . . . . . . 71 96 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 72 97 15.1. Normative References . . . . . . . . . . . . . . . . . . 72 98 15.2. Informative References . . . . . . . . . . . . . . . . . 73 99 Appendix A. Suggested Data Modeling with the Entity Object Class 74 100 A.1. Registrants and Contacts . . . . . . . . . . . . . . . . 74 101 A.2. Registrars . . . . . . . . . . . . . . . . . . . . . . . 76 102 Appendix B. Modeling Events . . . . . . . . . . . . . . . . . . 78 103 Appendix C. Structured vs Unstructured Addresses . . . . . . . . 80 104 Appendix D. Secure DNS . . . . . . . . . . . . . . . . . . . . . 83 105 Appendix E. Motivations for Using JSON . . . . . . . . . . . . . 83 106 Appendix F. Changelog . . . . . . . . . . . . . . . . . . . . . 84 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90 109 1. Introduction 111 This document describes responses in the JSON [RFC7159] format for 112 the queries as defined by the Registration Data Access Protocol 113 Lookup Format [I-D.ietf-weirds-rdap-query]. 114 [I-D.ietf-weirds-using-http] describes a communication protocol for 115 exchanging queries and responses. 117 1.1. Terminology and Definitions 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in RFC 2119 [RFC2119] 122 when specified in their uppercase forms. 124 The following list describes terminology and definitions used 125 throughout this document: 127 DNR: Domain Name Registry 129 LDH: Letters, Digits, Hyphen 131 member: data found within an object as defined by JSON 132 [RFC7159]. 134 object: a data structure as defined by JSON [RFC7159]. 136 object class: the definition of members that may be found in JSON 137 objects described in this document. 139 object instance: an instantiation or specific instance of an object 140 class. 142 RDAP: Registration Data Access Protocol 143 RIR: Regional Internet Registry 145 1.2. Data Model 147 The data model for JSON responses is specified in four sections: 149 1. simple data types conveyed in JSON strings 151 2. data structures specified as JSON arrays or objects that are used 152 repeatedly when building up larger objects 154 3. object classes representing structured data corresponding to a 155 lookup of a single object 157 4. arrays of objects representing structured data corresponding to a 158 search for multiple objects 160 5. the response to an error 162 The object classes represent responses for two major categories of 163 data: responses returned by Regional Internet Registries (RIRs) for 164 registrations data related to IP addresses, reverse DNS names, and 165 Autonomous System numbers; and responses returned by Domain Name 166 Registries (DNRs) for registration data related to forward DNS names. 167 The following object classes are served by both RIRs and DNRs: 169 1. domains 171 2. nameservers 173 3. entities 175 The information served by both RIRs and DNRs for these object classes 176 overlap extensively and are given in this document as a unified model 177 for both classes of service. 179 In addition to the object classes listed above, RIRs also serve the 180 following object classes: 182 1. IP networks 184 2. Autonomous System numbers 186 Object classes defined in this document represent a minimal set of 187 what a compliant client/server needs to understand to function 188 correctly, however some deployments may want to include additional 189 object classes to suit individual needs. Anticipating this need for 190 extension, Section 2.1 of this document defines a mechanism for 191 extending the JSON objects that are described in this document. 193 Positive responses take two forms. A response to a lookup of a 194 single object in the registration system yields a JSON object which 195 is the subject of the lookup. A response to a search for multiple 196 objects yields a JSON object that contains an array of JSON objects 197 that are the subject of the search. In each type of response, other 198 data structures are present within the topmost JSON object. 200 2. Use of JSON 202 2.1. Naming 204 Clients of these JSON responses SHOULD ignore unrecognized JSON 205 attributes in responses. Servers can insert values into the JSON 206 responses which are not specified in this document, but that does not 207 constitute an error in the response. Servers which insert such 208 unspecified values into JSON responses SHOULD have names prefixed 209 with a short identifier followed by an underscore followed by a 210 meaningful name. These short identifiers aid software implementers 211 with identifying the specification of the JSON name, and failure to 212 use one could cause an implementer to assume the server is 213 erroneously using a name from this specification. This allowance 214 does not apply to jCard ([RFC7095]) objects. The full JSON name (the 215 prefix plus the underscore plus the meaningful name) SHOULD adhere to 216 the character and name limitations of the prefix registry described 217 in [I-D.ietf-weirds-using-http]. Failure to use these limitations 218 could result in slower adoption as these limitations have been given 219 to aid some client programming models. 221 Consider the following JSON response with JSON names, all of which 222 are specified in this document. 224 { 225 "handle" : "ABC123", 226 "remarks" : 227 [ 228 { 229 "description" : 230 [ 231 "She sells sea shells down by the sea shore.", 232 "Originally written by Terry Sullivan." 233 ] 234 } 235 ] 236 } 238 Figure 1 240 If The Registry of the Moon desires to express information not found 241 in this specification, it might select "lunarNic" as its identifying 242 prefix and insert, as an example, the name 243 "lunarNic_beforeOneSmallStep" to signify registrations occurring 244 before the first moon landing and the name 245 "lunarNic_harshMistressNotes" containing other descriptive text. 247 Consider the following JSON response with JSON names, some of which 248 should be ignored by clients without knowledge of their meaning. 250 { 251 "handle" : "ABC123", 252 "lunarNic_beforeOneSmallStep" : "TRUE THAT!", 253 "remarks" : 254 [ 255 { 256 "description" : 257 [ 258 "She sells sea shells down by the sea shore.", 259 "Originally written by Terry Sullivan." 260 ] 261 } 262 ], 263 "lunarNic_harshMistressNotes" : 264 [ 265 "In space,", 266 "nobody can hear you scream." 267 ] 268 } 270 Figure 2 272 Insertion of unrecognized names ignored by clients may also be used 273 for future revisions to this specification. 275 Clients processing JSON responses need to be prepared for values 276 specified in this document to be absent from a response, as no JSON 277 value listed is required to appear in a response. In other words, 278 servers are free to not included values based on their own policies. 280 Finally, all JSON names specified in this document are case 281 sensitive. Both servers and clients MUST transmit and process them 282 using the specified character case. 284 3. Common Data Types 286 JSON [RFC7159] defines the data types of a number, character string, 287 boolean, array, object and null. This section describes the 288 semantics and/or syntax reference for data types used in this 289 document derived from the JSON character string. 291 handle: DNRs and RIRs have registry-unique identifiers that 292 may be used to specifically reference an object 293 instance. The semantics of this data type as found 294 in this document are to be a registry-unique 295 reference to the closest enclosing object where the 296 value is found. The data type names 'registryId', 297 'roid', 'nic-handle', 'registrationNo', etc. are 298 terms often synonymous with this data type. In 299 this document, the term 'handle' is used. The term 300 exposed to users by clients is a presentation issue 301 beyond the scope of this document. 303 IPv4 addresses: The representation of IPv4 addresses in this 304 document uses the dotted-decimal notation. An 305 example of this textual representation is 306 '192.0.2.0'. 308 IPv6 addresses: The representation of IPv6 addresses in this 309 document follow the forms outlined in [RFC5952]. 310 An example of this textual representation is 311 '2001:db8::1:0:0:1'. 313 country codes: Where the identity of a geopolitical nation or 314 country is needed, these identities are represented 315 with the alpha-2 or two-character country code 316 designation as defined in [ISO.3166.1988]. The 317 alpha-2 representation is used because it is freely 318 available whereas the alpha-3 and numeric-3 319 standards are not. 321 LDH names: Textual representations of DNS names where the 322 labels of the domain are all "letters, digits, 323 hyphen" labels as described by [RFC5890]. Trailing 324 periods are optional. 326 Unicode names: Textual representations of DNS names where one or 327 more of the labels are U-labels as described by 328 [RFC5890]. Trailing periods are optional. 330 dates and times: The syntax for values denoting dates and times is 331 defined in [RFC3339]. 333 URIs: The syntax for values denoting a Uniform Resource 334 Identifier (URI) is defined by [RFC3986]. 336 Contact information is defined using jCards (JSON vCards) as 337 described in [RFC7095] 339 4. Common Data Structures 341 This section defines common data structures used in responses and 342 object classes. 344 4.1. RDAP Conformance 346 The first data structure is named "rdapConformance" and is simply an 347 array of strings, each providing a hint as to the specifications used 348 in the construction of the response. This data structure appears 349 only in the top most object of a response. 351 An example rdapConformance data structure: 353 "rdapConformance" : 354 [ 355 "rdap_level_0" 356 ] 358 Figure 3 360 The string literal "rdap_level_0" signifies conformance with this 361 specification. When custom JSON values are inserted into responses, 362 conformance to those custom specifications MUST use a string prefixed 363 with the appropriate identifier from the IANA RDAP Extensions 364 registry specified in [I-D.ietf-weirds-using-http]. For example, if 365 the fictional Registry of the Moon wants to signify that their JSON 366 responses are conformant with their registered extensions, the string 367 used might be "lunarNIC_level_0". These prefixes aid the 368 identification of specifications for software implementers, and 369 failure to use them could result in slower adoption of extensions. 371 Example rdapConformance structure with custom extensions noted: 373 "rdapConformance" : 374 [ 375 "rdap_level_0", 376 "lunarNic_level_0" 377 ] 379 Figure 4 381 4.2. Links 383 The "links" array is found in data structures to signify links to 384 other resources on the Internet. The relationship of these links is 385 defined by the IANA registry described by [RFC5988]. 387 The following is an example of the link structure: 389 { 390 "value" : "http://example.com/context_uri", 391 "rel" : "self", 392 "href" : "http://example.com/target_uri", 393 "hreflang" : [ "en", "ch" ], 394 "title" : "title", 395 "media" : "screen", 396 "type" : "application/json" 397 } 399 Figure 5 401 The JSON name/values of "rel", "href", "hreflang", "title", "media", 402 and "type" correspond to values found in Section 5 of [RFC5988]. The 403 "value" JSON value is the context URI as described by [RFC5988]. The 404 "href" JSON value MUST be specified. All other JSON values are 405 OPTIONAL. 407 This is an example of the "links" array as it might be found in an 408 object class: 410 "links" : 411 [ 412 { 413 "value" : "http://example.com/ip/2001:db8::123", 414 "rel" : "self", 415 "href" : "http://example.com/ip/2001:db8::123", 416 "type" : "application/rdap+json" 417 }, 418 { 419 "value" : "http://example.com/ip/2001:db8::123", 420 "rel" : "up", 421 "href" : "http://example.com/ip/2001:db8::/48", 422 "type" : "application/rdap+json" 423 } 425 ] 427 4.3. Notices And Remarks 429 The "notices" and "remarks" data structures take the same form. The 430 "notices" structure denotes information about the service providing 431 RDAP information and/or information about the entire response, 432 whereas the "remarks" structure denotes information about the object 433 class that contains it (see Section 5 regarding object classes). 435 Both are arrays of objects. Each object contains an optional "title" 436 string representing the title of the object, an optional "type" 437 string denoting a registered type of remark or notice (see 438 Section 10.2.1), an array of strings named "description" for the 439 purposes of conveying any descriptive text, and an optional "links" 440 array as described in Section 4.2. 442 An example of the notices data structure: 444 "notices" : 445 [ 446 { 447 "title" : "Terms of Use", 448 "description" : 449 [ 450 "Service subject to The Registry of the Moon's TOS.", 451 "Copyright (c) 2020 LunarNIC" 452 ], 453 "links" : 454 [ 455 { 456 "value" : "http://example.net/entity/XXXX", 457 "rel" : "alternate", 458 "type" : "text/html", 459 "href" : "http://www.example.com/terms_of_use.html" 460 } 461 ] 462 } 463 ] 465 Figure 6 467 It is the job of the clients to determine line breaks, spacing and 468 display issues for sentences within the character strings of the 469 "description" array. Each string in the "description" array contains 470 a single complete division of human readable text indicating to 471 clients where there are semantic breaks. 473 An example of the remarks data structure: 475 "remarks" : 476 [ 477 { 478 "description" : 479 [ 480 "She sells sea shells down by the sea shore.", 481 "Originally written by Terry Sullivan." 482 ] 483 } 484 ] 486 Figure 7 488 Note that objects in the "remarks" array may also have a "links" 489 array. 491 While the "title" and "description" fields are intended primarily for 492 human consumption, the "type" string contains a well-known value to 493 be registered with IANA (see Section 10.2.1) for programmatic use. 495 An example of the remarks data structure: 497 "remarks" : 498 [ 499 { 500 "type" : "object truncated due to authorization", 501 "description" : 502 [ 503 "Some registration data may not have been given.", 504 "Use proper authorization credentials to see all of it." 505 ] 506 } 507 ] 509 Figure 8 511 While the "remarks" array will appear in many object classes in a 512 response, the "notices" array appears only in the top most object of 513 a response. 515 4.4. Language Identifier 517 This data structure consists solely of a name/value pair, where the 518 name is "lang" and the value is a string containing a language 519 identifier as described in [RFC5646]. 521 "lang" : "mn-Cyrl-MN" 523 Figure 9 525 The 'lang' attribute may appear anywhere in an object class or data 526 structure except for in jCard objects. 528 4.5. Events 530 This data structure represents events that have occurred on an 531 instance of an object class (see Section 5 regarding object classes). 533 This is an example of an "events" array. 535 "events" : 536 [ 537 { 538 "eventAction" : "registration", 539 "eventActor" : "SOMEID-LUNARNIC", 540 "eventDate" : "1990-12-31T23:59:59Z" 541 }, 542 { 543 "eventAction" : "last changed", 544 "eventActor" : "OTHERID-LUNARNIC", 545 "eventDate" : "1991-12-31T23:59:59Z" 546 } 547 ] 549 Figure 10 551 The "events" array consists of objects, each with the following 552 members: 554 o 'eventAction' -- a string denoting the reason for the event 556 o 'eventActor' -- an optional identifier denoting the actor 557 responsible for the event 559 o 'eventDate' -- a string containing the time and date the event 560 occurred. 562 o 'links' -- see Section 4.2. 564 Events can be future dated. One use case for future dating of events 565 is to denote when an object expires from a registry. 567 The 'links' array in this data structure is provided for references 568 to the event actor. In order to reference an RDAP entity, a "rel" of 569 "related" and a "type" of "application/rdap+json" is used in the link 570 reference. 572 See Section 10.2.3 for a list of values for the 'eventAction' string. 573 See Appendix B regarding the various ways events can be modeled. 575 4.6. Status 577 This data structure, named 'status', is an array of strings 578 indicating the state of a registered object (see Section 10.2.2 for a 579 list of values). 581 4.7. Port 43 WHOIS Server 583 This data structure, named 'port43', is a simple string containing 584 the fully-qualified host name or IP address of the WHOIS [RFC3912] 585 server where the containing object instance may be found. Note that 586 this is not a URI, as there is no WHOIS URI scheme. 588 4.8. Public IDs 590 This data structure maps a public identifier to an object class. It 591 is named 'publicIds' and is an array of objects, with each object 592 containing the following members: 594 o type - a string denoting the type of public identifier 596 o identifier - a public identifier of the type denoted by 'type' 598 The following is an example of a 'publicIds' structure. 600 "publicIds": 601 [ 602 { 603 "type":"IANA Registrar ID", 604 "identifier":"1" 605 } 606 ] 608 Figure 11 610 4.9. Object Class Name 612 This data structure, named "objectClassName", gives the object class 613 name of a particular object as a string. This identifies the type of 614 object being processed. An objectClassName is REQUIRED in all RDAP 615 response objects so that the type of the object can be interpreted. 617 4.10. An Example 619 This is an example response with both rdapConformance and notices 620 embedded: 622 { 623 "rdapConformance" : 624 [ 625 "rdap_level_0" 626 ], 627 "notices" : 628 [ 629 { 630 "title" : "Content Redacted", 631 "description" : 632 [ 633 "Without full authorization, content has been redacted.", 634 "Sorry, dude!" 635 ], 636 "links" : 637 [ 638 { 639 "value" : "http://example.net/ip/192.0.2.0/24", 640 "rel" : "alternate", 641 "type" : "text/html", 642 "href" : "http://www.example.com/redaction_policy.html" 643 } 644 ] 645 } 646 ], 647 "lang" : "en", 648 "objectClassName" : "ip network", 649 "startAddress" : "192.0.2.0", 650 "endAddress" : "192.0.2.255", 651 "handle" : "XXXX-RIR", 652 "ipVersion" : "v4", 653 "name": "NET-RTR-1", 654 "parentHandle" : "YYYY-RIR", 655 "remarks" : 656 [ 657 { 658 "description" : 659 [ 660 "She sells sea shells down by the sea shore.", 661 "Originally written by Terry Sullivan." 662 ] 663 } 664 ] 665 } 667 Figure 12 669 5. Object Classes 671 Object classes represent structures appropriate for a response from 672 the queries specified in [I-D.ietf-weirds-rdap-query]. 674 Each object class contains a "links" array as specified in 675 Section 4.2. For every object class instance in a response, whether 676 the object class instance is directly representing the response to a 677 query or is embedded in other object class instances or is an item in 678 a search result set, servers SHOULD provide a link representing a URI 679 for that object class instance using the "self" relationship as 680 described in the IANA registry specified by [RFC5988]. As explained 681 in Section 5.2, this may be not always be possible for name server 682 data. Clients MUST be able to process object instances without a 683 "self" link. When present, clients can use the self link for caching 684 data. Servers MAY provide more than one "self" link for any given 685 object instance. Failure to provide any "self" link by a server may 686 result in clients being unable to cache object class instances. 688 Self links MUST contain a "type" element containing the "application/ 689 rdap+json" media type when referencing RDAP object instances as 690 defined by this document. 692 This is an example of the "links" array with a self link to an object 693 class: 695 "links" : 696 [ 697 { 698 "value" : "http://example.com/ip/2001:db8::123", 699 "rel" : "self", 700 "href" : "http://example.com/ip/2001:db8::123", 701 "type" : "application/rdap+json" 702 } 703 ] 705 In addition to the "links" array with a self link, servers SHOULD 706 provide an "objectClassName" (see Section 4.9) string in each object. 708 5.1. The Entity Object Class 710 The entity object class appears throughout this document and is an 711 appropriate response for the /entity/XXXX query defined in 712 Registration Data Access Protocol Lookup Format 713 [I-D.ietf-weirds-rdap-query]. This object class represents the 714 information of organizations, corporations, governments, non-profits, 715 clubs, individual persons, and informal groups of people. All of 716 these representations are so similar that it is best to represent 717 them in JSON [RFC7159] with one construct, the entity object class, 718 to aid in the re-use of code by implementers. 720 The entity object is served by both RIRs and DNRs. The following is 721 an example of an entity that might be served by an RIR. 723 { 724 "objectClassName" : "entity", 725 "handle":"XXXX", 726 "vcardArray":[ 727 "vcard", 728 [ 729 ["version", {}, "text", "4.0"], 730 ["fn", {}, "text", "Joe User"], 731 ["n", {}, "text", 732 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 733 ], 734 ["bday", {}, "date-and-or-time", "--02-03"], 735 ["anniversary", 736 {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" 737 ], 738 ["gender", {}, "text", "M"], 739 ["kind", {}, "text", "individual"], 740 ["lang", { 741 "pref":"1" 742 }, "language-tag", "fr"], 743 ["lang", { 744 "pref":"2" 745 }, "language-tag", "en"], 746 ["org", { 747 "type":"work" 748 }, "text", "Example"], 749 ["title", {}, "text", "Research Scientist"], 750 ["role", {}, "text", "Project Lead"], 751 ["adr", 752 { "type":"work" }, 753 "text", 754 [ 755 "", 756 "Suite 1234", 757 "4321 Rue Somewhere", 758 "Quebec", 759 "QC", 760 "G1V 2M2", 761 "Canada" 762 ] 763 ], 765 ["adr", 766 { 767 "type":"home", 768 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 769 }, 770 "text", 771 [ 772 "", "", "", "", "", "", "" 773 ] 774 ], 775 ["tel", 776 { 777 "type":["work", "voice"], 778 "pref":"1" 779 }, 780 "uri", 781 "tel:+1-555-555-1234;ext=102" 782 ], 783 ["tel", 784 { "type":["work", "cell", "voice", "video", "text"] }, 785 "uri", 786 "tel:+1-555-555-4321" 787 ], 788 ["email", 789 { "type":"work" }, 790 "text", 791 "joe.user@example.com" 792 ], 793 ["geo", { 794 "type":"work" 795 }, "uri", "geo:46.772673,-71.282945"], 796 ["key", 797 { "type":"work" }, 798 "uri", 799 "http://www.example.com/joe.user/joe.asc" 800 ], 801 ["tz", {}, 802 "utc-offset", "-05:00"], 803 ["url", { "type":"home" }, 804 "uri", "http://example.org"] 805 ] 806 ], 807 "roles":[ "registrar" ], 808 "publicIds":[ 809 { 810 "type":"IANA Registrar ID", 811 "identifier":"1" 812 } 814 ], 815 "remarks":[ 816 { 817 "description":[ 818 "She sells sea shells down by the sea shore.", 819 "Originally written by Terry Sullivan." 820 ] 821 } 822 ], 823 "links":[ 824 { 825 "value":"http://example.com/entity/XXXX", 826 "rel":"self", 827 "href":"http://example.com/entity/XXXX", 828 "type" : "application/rdap+json" 829 } 830 ], 831 "events":[ 832 { 833 "eventAction":"registration", 834 "eventDate":"1990-12-31T23:59:59Z" 835 } 836 ], 837 "asEventActor":[ 838 { 839 "eventAction":"last changed", 840 "eventDate":"1991-12-31T23:59:59Z" 841 } 842 ] 843 } 845 This object has the following members: 847 o objectClassName -- the string "entity" 849 o handle -- a string representing an registry unique identifier of 850 the entity 852 o vcardArray -- a jCard with the entity's contact information 854 o roles -- an array of strings, each signifying the relationship an 855 object would have with its closest containing object (see 856 Section 10.2.4 for a list of values) 858 o publicIds - see Section 4.8 860 o entities - an array of entity objects as defined by this section. 862 o remarks -- see Section 4.3 864 o links -- see Section 4.2 866 o events -- see Section 4.5 868 o asEventActor -- this data structure takes the same form as the 869 'events' data structure (see Section 4.5), but each object in the 870 array MUST NOT have an 'eventActor' member. These objects denote 871 that the entity is an event actor for the given events. See 872 Appendix B regarding the various ways events can be modeled. 874 o status -- see Section 4.6 876 o port43 -- see Section 4.7 878 o networks -- an array of IP network objects as defined in 879 Section 5.4 881 o autnums -- an array of autnum objects as defined in Section 5.5 883 Entities may also have other entities embedded with them in an array. 884 This can be used to model an organization with specific individuals 885 fulfilling designated roles of responsibility. 887 The following is an elided example of an entity with embedded 888 entities. 890 { 891 "objectClassName" : "entity", 892 "handle" : "ANENTITY", 893 "roles" : [ "registrar" ], 894 ... 895 "entities" : 896 [ 897 { 898 "objectClassName" : "entity", 899 "handle": "ANEMBEDDEDENTITY", 900 "roles" : [ "technical" ], 901 ... 902 }, 903 ... 904 ], 905 ... 906 } 908 Figure 13 910 The following is an example of a entity that might be served by a 911 DNR. 913 { 914 "objectClassName" : "entity", 915 "handle":"XXXX", 916 "vcardArray":[ 917 "vcard", 918 [ 919 ["version", {}, "text", "4.0"], 920 ["fn", {}, "text", "Joe User"], 921 ["kind", {}, "text", "individual"], 922 ["lang", { 923 "pref":"1" 924 }, "language-tag", "fr"], 925 ["lang", { 926 "pref":"2" 927 }, "language-tag", "en"], 928 ["org", { 929 "type":"work" 930 }, "text", "Example"], 931 ["title", {}, "text", "Research Scientist"], 933 ["role", {}, "text", "Project Lead"], 934 ["adr", 935 { "type":"work" }, 936 "text", 937 [ 938 "", 939 "Suite 1234", 940 "4321 Rue Somewhere", 941 "Quebec", 942 "QC", 943 "G1V 2M2", 944 "Canada" 945 ] 946 ], 947 ["tel", 948 { "type":["work", "voice"], "pref":"1" }, 949 "uri", "tel:+1-555-555-1234;ext=102" 950 ], 951 ["email", 952 { "type":"work" }, 953 "text", "joe.user@example.com" 954 ] 955 ] 956 ], 957 "status":[ "validated", "locked" ], 958 "remarks":[ 959 { 960 "description":[ 961 "She sells sea shells down by the sea shore.", 962 "Originally written by Terry Sullivan." 963 ] 964 } 965 ], 966 "links":[ 967 { 968 "value":"http://example.com/entity/XXXX", 969 "rel":"self", 970 "href":"http://example.com/entity/XXXX", 971 "type":"application/rdap+json" 972 } 973 ], 974 "port43":"whois.example.net", 975 "events":[ 976 { 977 "eventAction":"registration", 978 "eventDate":"1990-12-31T23:59:59Z" 979 }, 980 { 981 "eventAction":"last changed", 982 "eventDate":"1991-12-31T23:59:59Z", 983 "eventActor":"joe@example.com" 984 } 985 ] 986 } 988 See Appendix A for use of the entity object class to model various 989 types of entities found in both RIRs and DNRs. See Appendix C 990 regarding structured vs. unstructured postal addresses in entities. 992 5.2. The Nameserver Object Class 994 The nameserver object class represents information regarding DNS name 995 servers used in both forward and reverse DNS. RIRs and some DNRs 996 register or expose nameserver information as an attribute of a domain 997 name, while other DNRs model nameservers as "first class objects". 999 The nameserver object class accommodates both models and degrees of 1000 variation in between. 1002 The following is an example of a nameserver object. 1004 { 1005 "objectClassName" : "nameserver", 1006 "handle" : "XXXX", 1007 "ldhName" : "ns1.xn--fo-5ja.example", 1008 "unicodeName" : "ns1.foo.example", 1009 "status" : [ "active" ], 1010 "ipAddresses" : 1011 { 1012 "v4": [ "192.0.2.1", "192.0.2.2" ], 1013 "v6": [ "2001:db8::123" ] 1014 }, 1015 "remarks" : 1016 [ 1017 { 1018 "description" : 1019 [ 1020 "She sells sea shells down by the sea shore.", 1021 "Originally written by Terry Sullivan." 1022 ] 1023 } 1024 ], 1025 "links" : 1026 [ 1027 { 1028 "value" : "http://example.net/nameserver/xxxx", 1029 "rel" : "self", 1030 "href" : "http://example.net/nameserver/xxxx", 1031 "type" : "application/rdap+json" 1032 } 1033 ], 1034 "port43" : "whois.example.net", 1035 "events" : 1036 [ 1037 { 1038 "eventAction" : "registration", 1039 "eventDate" : "1990-12-31T23:59:59Z" 1040 }, 1041 { 1042 "eventAction" : "last changed", 1043 "eventDate" : "1991-12-31T23:59:59Z", 1044 "eventActor" : "joe@example.com" 1045 } 1046 ] 1047 } 1049 Figure 14 1051 Figure 14 is an example of a nameserver object with all values given. 1052 Registries using a first-class nameserver data model would embed this 1053 in domain objects as well as allowing references to it with the 1054 "/nameserver" query type (all depending on the registry operators 1055 policy). Other registries may pare back the information as needed. 1056 Figure 15 is an example of a nameserver object as would be found in 1057 RIRs and some DNRs, while Figure 16 is an example of a nameserver 1058 object as would be found in other DNRs. 1060 The following is an example of the simplest nameserver object: 1062 { 1063 "objectClassName" : "nameserver", 1064 "ldhName" : "ns1.example.com" 1065 } 1067 Figure 15 1069 The following is an example of a simple nameserver object that might 1070 be commonly used by DNRs: 1072 { 1073 "objectClassName" : "nameserver", 1074 "ldhName" : "ns1.example.com", 1075 "ipAddresses" : { "v6" : [ "2001:db8::123", "2001:db8::124" ] } 1076 } 1078 Figure 16 1080 As nameservers can be modeled by some registries to be first-class 1081 objects, they may also have an array of entities (Section 5.1) 1082 embedded to signify parties responsible for the maintenance, 1083 registrations, etc. of the nameservers. 1085 The following is an elided example of a nameserver with embedded 1086 entities. 1088 { 1089 "objectClassName", "nameserver", 1090 "handle" : "XXXX", 1091 "ldhName" : "ns1.xn--fo-5ja.example", 1092 ... 1093 "entities" : 1094 [ 1095 ... 1096 ], 1097 ... 1098 } 1100 Figure 17 1102 The nameserver object class has the following members: 1104 o objectClassName - the string "nameserver" 1106 o handle -- a string representing an registry unique identifier of 1107 the nameserver 1109 o ldhName -- a string containing the LDH name of the nameserver (see 1110 Section 3) 1112 o unicodeName -- a string containing a DNS Unicode name of the 1113 nameserver (see Section 3) 1115 o ipAddresses -- an object containing the following members: 1117 * v6 -- an array of strings containing IPv6 addresses of the 1118 nameserver 1120 * v4 -- an array of strings containing IPv4 addresses of the 1121 nameserver 1123 o entities -- an array of entity objects as defined by Section 5.1. 1125 o status - see Section 4.6 1127 o remarks - see Section 4.3 1129 o links - see Section 4.2 1130 o port43 - see Section 4.7 1132 o events - see Section 4.5 1134 5.3. The Domain Object Class 1136 The domain object class represents a DNS name and point of 1137 delegation. For RIRs these delegation points are in the reverse DNS 1138 tree, whereas for DNRs these delegation points are in the forward DNS 1139 tree. 1141 In both cases, the high level structure of the domain object class 1142 consists of information about the domain registration, nameserver 1143 information related to the domain name, and entities related to the 1144 domain name (e.g. registrant information, contacts, etc.). 1146 The following is an elided example of the domain object showing the 1147 high level structure: 1149 { 1150 "objectClassName" : "domain", 1151 "handle" : "XXX", 1152 "ldhName" : "blah.example.com", 1153 ... 1154 "nameservers" : 1155 [ 1156 ... 1157 ], 1158 ... 1159 "entities" : 1160 [ 1161 ... 1162 ] 1163 } 1165 The following is a description of the members of this object: 1167 o objectClassName -- the string "domain" 1169 o handle -- a string representing a registry unique identifier of 1170 the domain object instance 1172 o ldhName -- a string describing a domain name in LDH form as 1173 described in Section 3 1175 o unicodeName -- a string containing a domain name with U-labels as 1176 described in Section 3 1178 o variants -- an array of objects, each containing the following 1179 values: 1181 * relation -- an array of strings, with each string denoting the 1182 relationship between the variants and the containing domain 1183 object (see Section 10.2.5 for a list of suggested variant 1184 relations). 1186 * idnTable -- the name of the IDN table of codepoints, such as 1187 one listed with the IANA (see IDN tables [IANA_IDNTABLES]). 1189 * variantNames -- an array of objects, with each object 1190 containing an "ldhName" member and a "unicodeName" member (see 1191 Section 3). 1193 o nameservers -- an array of nameserver objects as defined by 1194 Section 5.2 1196 o secureDNS -- an object with the following members: 1198 * zoneSigned -- true if the zone has been signed, false 1199 otherwise. 1201 * delegationSigned -- boolean true if there are DS records in the 1202 parent, false otherwise. 1204 * maxSigLife -- an integer representing the signature life time 1205 in seconds to be used when creating the RRSIG DS record in the 1206 parent zone [RFC5910]. 1208 * dsData - an array of objects, each with the following members: 1210 + keyTag -- an integer as specified by the key tag field of a 1211 DNS DS record as specified by RFC 4034 [RFC4034] in 1212 presentation format 1214 + algorithm -- an integer as specified by the algorithm field 1215 of a DNS DS record as described by RFC 4034 in presentation 1216 format 1218 + digest -- a string as specified by the digest field of a DNS 1219 DS record as specified by RFC 4034 in presentation format 1221 + digestType -- an integer as specified by the digest type 1222 field of a DNS DS record as specified by RFC 4034 in 1223 presentation format 1225 + events - see Section 4.5 1227 + links - see Section 4.2 1229 * keyData - an array of objects, each with the following members: 1231 + flags -- an integer representing the flags field value in 1232 the DNSKEY record [RFC4034] in presentation format 1234 + protocol - an integer representation of the protocol field 1235 value of the DNSKEY record [RFC4034] in presentation format 1237 + publicKey - a string representation of the public key in the 1238 DNSKEY record [RFC4034] in presentation format 1240 + algorithm -- an integer as specified by the algorithm field 1241 of a DNSKEY record as specified by RFC 4034 [RFC4034] in 1242 presentation format 1244 + events - see Section 4.5 1246 + links - see Section 4.2 1248 See Appendix D for background information on these objects. 1250 o entities -- an array of entity objects as defined by Section 5.1. 1252 o status - see Section 4.6 1254 o publicIds - see Section 4.8 1256 o remarks - see Section 4.3 1258 o links - see Section 4.2 1260 o port43 - see Section 4.7 1262 o events - see Section 4.5 1264 o network - represents the IP network for which a reverse DNS domain 1265 is referenced. See Section 5.4 1267 The following is an example of a JSON domain object representing a 1268 reverse DNS delegation point that might be served by an RIR. 1270 { 1271 "objectClassName" : "domain", 1272 "handle" : "XXXX", 1273 "ldhName" : "0.2.192.in-addr.arpa", 1274 "nameservers" : 1275 [ 1276 { 1277 "objectClassName" : "nameserver", 1278 "ldhName" : "ns1.rir.example" 1279 }, 1280 { 1281 "objectClassName" : "nameserver", 1282 "ldhName" : "ns2.rir.example" 1283 } 1284 ], 1285 "secureDNS": 1286 { 1287 "delegationSigned": true, 1288 "dsData": 1289 [ 1290 { 1291 "keyTag": 12345, 1292 "algorithm": 3, 1293 "digestType": 1, 1294 "digest": "49FD46E6C4B45C55D4AC" 1295 } 1296 ] 1297 }, 1298 "remarks" : 1299 [ 1300 { 1301 "description" : 1302 [ 1303 "She sells sea shells down by the sea shore.", 1304 "Originally written by Terry Sullivan." 1305 ] 1306 } 1307 ], 1308 "links" : 1309 [ 1310 { 1311 "value": "http://example.net/domain/XXXX", 1312 "rel" : "self", 1313 "href" : "http://example.net/domain/XXXXX", 1314 "type" : "application/rdap+json" 1315 } 1316 ], 1317 "events" : 1319 [ 1320 { 1321 "eventAction" : "registration", 1322 "eventDate" : "1990-12-31T23:59:59Z" 1323 }, 1324 { 1325 "eventAction" : "last changed", 1326 "eventDate" : "1991-12-31T23:59:59Z", 1327 "eventActor" : "joe@example.com" 1328 } 1329 ], 1330 "entities" : 1331 [ 1332 { 1333 "objectClassName" : "entity", 1334 "handle" : "XXXX", 1335 "vcardArray":[ 1336 "vcard", 1337 [ 1338 ["version", {}, "text", "4.0"], 1339 ["fn", {}, "text", "Joe User"], 1340 ["kind", {}, "text", "individual"], 1341 ["lang", { 1342 "pref":"1" 1343 }, "language-tag", "fr"], 1344 ["lang", { 1345 "pref":"2" 1346 }, "language-tag", "en"], 1347 ["org", { 1348 "type":"work" 1349 }, "text", "Example"], 1350 ["title", {}, "text", "Research Scientist"], 1351 ["role", {}, "text", "Project Lead"], 1352 ["adr", 1353 { "type":"work" }, 1354 "text", 1355 [ 1356 "", 1357 "Suite 1234", 1358 "4321 Rue Somewhere", 1359 "Quebec", 1360 "QC", 1361 "G1V 2M2", 1362 "Canada" 1363 ] 1364 ], 1365 ["tel", 1366 { "type":["work", "voice"], "pref":"1" }, 1367 "uri", "tel:+1-555-555-1234;ext=102" 1368 ], 1369 ["email", 1370 { "type":"work" }, 1371 "text", "joe.user@example.com" 1372 ] 1373 ] 1374 ], 1375 "roles" : [ "registrant" ], 1376 "remarks" : 1377 [ 1378 { 1379 "description" : 1380 [ 1381 "She sells sea shells down by the sea shore.", 1382 "Originally written by Terry Sullivan." 1383 ] 1384 } 1385 ], 1386 "links" : 1387 [ 1388 { 1389 "value": "http://example.net/entity/xxxx", 1390 "rel" : "self", 1391 "href" : "http://example.net/entity/xxxx", 1392 "type" : "application/rdap+json" 1393 } 1394 ], 1395 "events" : 1396 [ 1397 { 1398 "eventAction" : "registration", 1399 "eventDate" : "1990-12-31T23:59:59Z" 1400 }, 1401 { 1402 "eventAction" : "last changed", 1403 "eventDate" : "1991-12-31T23:59:59Z", 1404 "eventActor" : "joe@example.com" 1405 } 1406 ] 1407 } 1408 ], 1409 "network" : 1410 { 1411 "objectClassName" : "ip network", 1412 "handle" : "XXXX-RIR", 1413 "startAddress" : "192.0.2.0", 1414 "endAddress" : "192.0.2.255", 1415 "ipVersion" : "v6", 1416 "name": "NET-RTR-1", 1417 "type" : "DIRECT ALLOCATION", 1418 "country" : "AU", 1419 "parentHandle" : "YYYY-RIR", 1420 "status" : [ "active" ] 1421 } 1422 } 1424 The following is an example of a JSON domain object representing a 1425 forward DNS delegation point that might be served by a DNR. 1427 { 1428 "objectClassName" : "domain", 1429 "handle" : "XXXX", 1430 "ldhName" : "xn--fo-5ja.example", 1431 "unicodeName" : "foo.example", 1432 "variants" : 1433 [ 1434 { 1435 "relation" : [ "registered", "conjoined" ], 1436 "variantNames" : 1437 [ 1438 { 1439 "ldhName" : "xn--fo-cka.example", 1440 "unicodeName" : "foo.example" 1441 }, 1442 { 1443 "ldhName" : "xn--fo-fka.example", 1444 "unicodeName" : "foeo.example" 1445 } 1446 ] 1447 }, 1448 { 1449 "relation" : [ "unregistered", "registration restricted" ], 1450 "idnTable": ".EXAMPLE Swedish", 1451 "variantNames" : 1452 [ 1453 { 1454 "ldhName": "xn--fo-8ja.example", 1455 "unicodeName" : "foo.example" 1456 } 1457 ] 1458 } 1459 ], 1460 "status" : [ "locked", "transfer prohibited" ], 1461 "publicIds":[ 1462 { 1463 "type":"ENS_Auth ID", 1464 "identifier":"1234567890" 1465 } 1466 ], 1467 "nameservers" : 1468 [ 1469 { 1470 "objectClassName" : "nameserver", 1471 "handle" : "XXXX", 1472 "ldhName" : "ns1.example.com", 1473 "status" : [ "active" ], 1474 "ipAddresses" : 1475 { 1476 "v6": [ "2001:db8::123", "2001:db8::124" ], 1477 "v4": [ "192.0.2.1", "192.0.2.2" ] 1478 }, 1479 "remarks" : 1480 [ 1481 { 1482 "description" : 1483 [ 1484 "She sells sea shells down by the sea shore.", 1485 "Originally written by Terry Sullivan." 1486 ] 1487 } 1488 ], 1489 "links" : 1490 [ 1491 { 1492 "value" : "http://example.net/nameserver/XXXX", 1493 "rel" : "self", 1494 "href" : "http://example.net/nameserver/XXXX", 1495 "type" : "application/rdap+json" 1496 } 1497 ], 1498 "events" : 1499 [ 1500 { 1501 "eventAction" : "registration", 1502 "eventDate" : "1990-12-31T23:59:59Z" 1503 }, 1504 { 1505 "eventAction" : "last changed", 1506 "eventDate" : "1991-12-31T23:59:59Z" 1507 } 1508 ] 1510 }, 1511 { 1512 "objectClassName" : "nameserver", 1513 "handle" : "XXXX", 1514 "ldhName" : "ns2.example.com", 1515 "status" : [ "active" ], 1516 "ipAddresses" : 1517 { 1518 "v6" : [ "2001:db8::125", "2001:db8::126" ], 1519 "v4" : [ "192.0.2.3", "192.0.2.4" ] 1520 }, 1521 "remarks" : 1522 [ 1523 { 1524 "description" : 1525 [ 1526 "She sells sea shells down by the sea shore.", 1527 "Originally written by Terry Sullivan." 1528 ] 1529 } 1530 ], 1531 "links" : 1532 [ 1533 { 1534 "value" : "http://example.net/nameserver/XXXX", 1535 "rel" : "self", 1536 "href" : "http://example.net/nameserver/XXXX", 1537 "type" : "application/rdap+json" 1538 } 1539 ], 1540 "events" : 1541 [ 1542 { 1543 "eventAction" : "registration", 1544 "eventDate" : "1990-12-31T23:59:59Z" 1545 }, 1546 { 1547 "eventAction" : "last changed", 1548 "eventDate" : "1991-12-31T23:59:59Z" 1549 } 1550 ] 1551 } 1552 ], 1553 "secureDNS": 1554 { 1555 "zoneSigned": true, 1556 "delegationSigned": true, 1557 "maxSigLife": 604800, 1558 "keyData": 1559 [ 1560 { 1561 "flags": 257, 1562 "protocol": 3, 1563 "algorithm": 1, 1564 "publicKey": "AQPJ////4Q==", 1565 "events": 1566 [ 1567 { 1568 "eventAction": "last changed", 1569 "eventDate": "2012-07-23T05:15:47Z" 1570 } 1571 ] 1572 } 1573 ] 1574 }, 1575 "remarks" : 1576 [ 1577 { 1578 "description" : 1579 [ 1580 "She sells sea shells down by the sea shore.", 1581 "Originally written by Terry Sullivan." 1582 ] 1583 } 1584 ], 1585 "links" : 1586 [ 1587 { 1588 "value": "http://example.net/domain/XXXX", 1589 "rel" : "self", 1590 "href" : "http://example.net/domain/XXXX", 1591 "type" : "application/rdap+json" 1592 } 1593 ], 1594 "port43" : "whois.example.net", 1595 "events" : 1596 [ 1597 { 1598 "eventAction" : "registration", 1599 "eventDate" : "1990-12-31T23:59:59Z" 1600 }, 1601 { 1602 "eventAction" : "last changed", 1603 "eventDate" : "1991-12-31T23:59:59Z", 1604 "eventActor" : "joe@example.com" 1605 }, 1606 { 1607 "eventAction" : "transfer", 1608 "eventDate" : "1991-12-31T23:59:59Z", 1609 "eventActor" : "joe@example.com" 1610 }, 1611 { 1612 "eventAction" : "expiration", 1613 "eventDate" : "2016-12-31T23:59:59Z", 1614 "eventActor" : "joe@example.com" 1615 } 1616 ], 1617 "entities" : 1618 [ 1619 { 1620 "objectClassName" : "entity", 1621 "handle" : "XXXX", 1622 "vcardArray":[ 1623 "vcard", 1624 [ 1625 ["version", {}, "text", "4.0"], 1626 ["fn", {}, "text", "Joe User"], 1627 ["kind", {}, "text", "individual"], 1628 ["lang", { 1629 "pref":"1" 1630 }, "language-tag", "fr"], 1631 ["lang", { 1632 "pref":"2" 1633 }, "language-tag", "en"], 1634 ["org", { 1635 "type":"work" 1636 }, "text", "Example"], 1637 ["title", {}, "text", "Research Scientist"], 1638 ["role", {}, "text", "Project Lead"], 1639 ["adr", 1640 { "type":"work" }, 1641 "text", 1642 [ 1643 "", 1644 "Suite 1234", 1645 "4321 Rue Somewhere", 1646 "Quebec", 1647 "QC", 1648 "G1V 2M2", 1649 "Canada" 1650 ] 1651 ], 1652 ["tel", 1653 { "type":["work", "voice"], "pref":"1" }, 1654 "uri", "tel:+1-555-555-1234;ext=102" 1655 ], 1656 ["email", 1657 { "type":"work" }, 1658 "text", "joe.user@example.com" 1659 ] 1660 ] 1661 ], 1662 "status" : [ "validated", "locked" ], 1663 "roles" : [ "registrant" ], 1664 "remarks" : 1665 [ 1666 { 1667 "description" : 1668 [ 1669 "She sells sea shells down by the sea shore.", 1670 "Originally written by Terry Sullivan." 1671 ] 1672 } 1673 ], 1674 "links" : 1675 [ 1676 { 1677 "value" : "http://example.net/entity/xxxx", 1678 "rel" : "self", 1679 "href" : "http://example.net/entity/xxxx", 1680 "type" : "application/rdap+json" 1681 } 1682 ], 1683 "events" : 1684 [ 1685 { 1686 "eventAction" : "registration", 1687 "eventDate" : "1990-12-31T23:59:59Z" 1688 }, 1689 { 1690 "eventAction" : "last changed", 1691 "eventDate" : "1991-12-31T23:59:59Z" 1692 } 1693 ] 1694 } 1695 ] 1696 } 1698 5.4. The IP Network Object Class 1700 The IP Network object class models IP network registrations found in 1701 RIRs and is the expected response for the "/ip" query as defined by 1702 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1703 for DNRs. The high level structure of the IP network object class 1704 consists of information about the network registration and entities 1705 related to the IP network (e.g. registrant information, contacts, 1706 etc...). 1708 The following is an elided example of the IP network object type 1709 showing the high level structure: 1711 { 1712 "objectClassName" : "ip network", 1713 "handle" : "XXX", 1714 ... 1715 "entities" : 1716 [ 1717 ... 1718 ] 1719 } 1721 The following is an example of the JSON object for the network 1722 registration information. 1724 { 1725 "objectClassName" : "ip network", 1726 "handle" : "XXXX-RIR", 1727 "startAddress" : "2001:db8::0", 1728 "endAddress" : "2001:db8:0:FFFF:FFFF:FFFF:FFFF:FFFF", 1729 "ipVersion" : "v6", 1730 "name": "NET-RTR-1", 1731 "type" : "DIRECT ALLOCATION", 1732 "country" : "AU", 1733 "parentHandle" : "YYYY-RIR", 1734 "status" : [ "active" ], 1735 "remarks" : 1736 [ 1737 { 1738 "description" : 1739 [ 1740 "She sells sea shells down by the sea shore.", 1741 "Originally written by Terry Sullivan." 1742 ] 1744 } 1745 ], 1746 "links" : 1747 [ 1748 { 1749 "value" : "http://example.net/ip/2001:db8::/48", 1750 "rel" : "self", 1751 "href" : "http://example.net/ip/2001:db8::/48", 1752 "type" : "application/rdap+json" 1753 }, 1754 { 1755 "value" : "http://example.net/ip/2001:db8::/48", 1756 "rel" : "up", 1757 "href" : "http://example.net/ip/2001:C00::/23", 1758 "type" : "application/rdap+json" 1759 } 1760 ], 1761 "events" : 1762 [ 1763 { 1764 "eventAction" : "registration", 1765 "eventDate" : "1990-12-31T23:59:59Z" 1766 }, 1767 { 1768 "eventAction" : "last changed", 1769 "eventDate" : "1991-12-31T23:59:59Z" 1770 } 1771 ], 1772 "entities" : 1773 [ 1774 { 1775 "objectClassName" : "entity", 1776 "handle" : "XXXX", 1777 "vcardArray":[ 1778 "vcard", 1779 [ 1780 ["version", {}, "text", "4.0"], 1781 ["fn", {}, "text", "Joe User"], 1782 ["kind", {}, "text", "individual"], 1783 ["lang", { 1784 "pref":"1" 1785 }, "language-tag", "fr"], 1786 ["lang", { 1787 "pref":"2" 1788 }, "language-tag", "en"], 1789 ["org", { 1790 "type":"work" 1791 }, "text", "Example"], 1793 ["title", {}, "text", "Research Scientist"], 1794 ["role", {}, "text", "Project Lead"], 1795 ["adr", 1796 { "type":"work" }, 1797 "text", 1798 [ 1799 "", 1800 "Suite 1234", 1801 "4321 Rue Somewhere", 1802 "Quebec", 1803 "QC", 1804 "G1V 2M2", 1805 "Canada" 1806 ] 1807 ], 1808 ["tel", 1809 { "type":["work", "voice"], "pref":"1" }, 1810 "uri", "tel:+1-555-555-1234;ext=102" 1811 ], 1812 ["email", 1813 { "type":"work" }, 1814 "text", "joe.user@example.com" 1815 ] 1816 ] 1817 ], 1818 "roles" : [ "registrant" ], 1819 "remarks" : 1820 [ 1821 { 1822 "description" : 1823 [ 1824 "She sells sea shells down by the sea shore.", 1825 "Originally written by Terry Sullivan." 1826 ] 1827 } 1828 ], 1829 "links" : 1830 [ 1831 { 1832 "value" : "http://example.net/entity/xxxx", 1833 "rel" : "self", 1834 "href" : "http://example.net/entity/xxxx", 1835 "type" : "application/rdap+json" 1836 } 1837 ], 1838 "events" : 1839 [ 1840 { 1841 "eventAction" : "registration", 1842 "eventDate" : "1990-12-31T23:59:59Z" 1843 }, 1844 { 1845 "eventAction" : "last changed", 1846 "eventDate" : "1991-12-31T23:59:59Z" 1847 } 1848 ] 1849 } 1850 ] 1851 } 1853 The following is a description of the members of this object: 1855 o objectClassName -- the string "ip network" 1857 o handle -- a string representing an RIR unique identifier of the 1858 network registration 1860 o startAddress -- the starting IP address of the network, either 1861 IPv4 or IPv6 1863 o endAddress -- the ending IP address of the network, either IPv4 or 1864 IPv6 1866 o ipVersion -- a string signifying the IP protocol version of the 1867 network: "v4" signifying an IPv4 network, "v6" signifying an IPv6 1868 network 1870 o name -- an identifier assigned to the network registration by the 1871 registration holder 1873 o type -- a string containing an RIR-specific classification of the 1874 network 1876 o country -- a string containing the two-character country code of 1877 the network 1879 o parentHandle -- a string containing an RIR-unique identifier of 1880 the parent network of this network registration 1882 o status -- an array of strings indicating the state of the IP 1883 network 1885 o entities -- an array of entity objects as defined by Section 5.1. 1887 o remarks - see Section 4.3 1888 o links - see Section 4.2 1890 o port43 - see Section 4.7 1892 o events - see Section 4.5 1894 5.5. Autonomous System Number Entity Object Class 1896 The Autonomous System Number (autnum) object class models Autonomous 1897 System Number registrations found in RIRs and represents the expected 1898 response to an "/autnum" query as defined by 1899 [I-D.ietf-weirds-rdap-query]. There is no equivalent object class 1900 for DNRs. The high level structure of the autnum object class 1901 consists of information about the network registration and entities 1902 related to the autnum registration (e.g. registrant information, 1903 contacts, etc.), and is similar to the IP Network entity object 1904 class. 1906 The following is an example of a JSON object representing an autnum. 1908 { 1909 "objectClassName" : "autnum", 1910 "handle" : "XXXX-RIR", 1911 "startAutnum" : 10, 1912 "endAutnum" : 15, 1913 "name": "AS-RTR-1", 1914 "type" : "DIRECT ALLOCATION", 1915 "status" : [ "active" ], 1916 "country": "AU", 1917 "remarks" : 1918 [ 1919 { 1920 "description" : 1921 [ 1922 "She sells sea shells down by the sea shore.", 1923 "Originally written by Terry Sullivan." 1924 ] 1925 } 1926 ], 1927 "links" : 1928 [ 1929 { 1930 "value" : "http://example.net/autnum/xxxx", 1931 "rel" : "self", 1932 "href" : "http://example.net/autnum/xxxx", 1933 "type" : "application/rdap+json" 1934 } 1936 ], 1937 "events" : 1938 [ 1939 { 1940 "eventAction" : "registration", 1941 "eventDate" : "1990-12-31T23:59:59Z" 1942 }, 1943 { 1944 "eventAction" : "last changed", 1945 "eventDate" : "1991-12-31T23:59:59Z" 1946 } 1947 ], 1948 "entities" : 1949 [ 1950 { 1951 "objectClassName" : "entity", 1952 "handle" : "XXXX", 1953 "vcardArray":[ 1954 "vcard", 1955 [ 1956 ["version", {}, "text", "4.0"], 1957 ["fn", {}, "text", "Joe User"], 1958 ["kind", {}, "text", "individual"], 1959 ["lang", { 1960 "pref":"1" 1961 }, "language-tag", "fr"], 1962 ["lang", { 1963 "pref":"2" 1964 }, "language-tag", "en"], 1965 ["org", { 1966 "type":"work" 1967 }, "text", "Example"], 1968 ["title", {}, "text", "Research Scientist"], 1969 ["role", {}, "text", "Project Lead"], 1970 ["adr", 1971 { "type":"work" }, 1972 "text", 1973 [ 1974 "", 1975 "Suite 1234", 1976 "4321 Rue Somewhere", 1977 "Quebec", 1978 "QC", 1979 "G1V 2M2", 1980 "Canada" 1981 ] 1982 ], 1983 ["tel", 1984 { "type":["work", "voice"], "pref":"1" }, 1985 "uri", "tel:+1-555-555-1234;ext=102" 1986 ], 1987 ["email", 1988 { "type":"work" }, 1989 "text", "joe.user@example.com" 1990 ] 1991 ] 1992 ], 1993 "roles" : [ "registrant" ], 1994 "remarks" : 1995 [ 1996 { 1997 "description" : 1998 [ 1999 "She sells sea shells down by the sea shore.", 2000 "Originally written by Terry Sullivan." 2001 ] 2002 } 2003 ], 2004 "links" : 2005 [ 2006 { 2007 "value" : "http://example.net/entity/XXXX", 2008 "rel" : "self", 2009 "href" : "http://example.net/entity/XXXX", 2010 "type" : "application/rdap+json" 2011 } 2012 ], 2013 "events" : 2014 [ 2015 { 2016 "eventAction" : "registration", 2017 "eventDate" : "1990-12-31T23:59:59Z" 2018 }, 2019 { 2020 "eventAction" : "last changed", 2021 "eventDate" : "1991-12-31T23:59:59Z" 2022 } 2023 ] 2024 } 2025 ] 2026 } 2028 The following is a description of the members of this object: 2030 o objectClassName -- the string "autnum" 2031 o handle -- a string representing an RIR-unique identifier of the 2032 autnum registration 2034 o startAutnum -- a number representing the starting number [RFC5396] 2035 in the block of autonomous system numbers 2037 o endAutnum -- a number representing the ending number [RFC5396] in 2038 the block of autonomous system numbers 2040 o name -- an identifier assigned to the autnum registration by the 2041 registration holder 2043 o type -- a string containing an RIR-specific classification of the 2044 autnum 2046 o status -- an array of strings indicating the state of the autnum 2048 o country -- a string containing the name of the 2 character country 2049 code of the autnum 2051 o entities -- an array of entity objects as defined by Section 5.1. 2053 o remarks - see Section 4.3 2055 o links - see Section 4.2 2057 o port43 - see Section 4.7 2059 o events - see Section 4.5 2061 6. Error Response Body 2063 Some non-answer responses may return entity bodies with information 2064 that could be more descriptive. 2066 The basic structure of that response is an object class containing an 2067 error code number (corresponding to the HTTP response code) followed 2068 by a string named "title" and an array of strings named 2069 "description". 2071 This is an example of the common response body. 2073 { 2074 "errorCode": 418, 2075 "title": "Your beverage choice is not available", 2076 "description": 2077 [ 2078 "I know coffee has more ummppphhh.", 2079 "Sorry, dude!" 2080 ] 2081 } 2083 Figure 18 2085 This is an example of the common response body with and 2086 rdapConformance and notices data structures: 2088 { 2089 "rdapConformance" : 2090 [ 2091 "rdap_level_0" 2092 ], 2093 "notices" : 2094 [ 2095 { 2096 "title" : "Beverage policy", 2097 "description" : 2098 [ 2099 "Beverages with caffeine for keeping horses awake." 2100 ], 2101 "links" : 2102 [ 2103 { 2104 "value" : "http://example.net/ip/192.0.2.0/24", 2105 "rel" : "alternate", 2106 "type" : "text/html", 2107 "href" : "http://www.example.com/redaction_policy.html" 2108 } 2109 ] 2110 } 2111 ], 2112 "lang" : "en", 2113 "errorCode": 418, 2114 "title": "Your beverage choice is not available", 2115 "description": 2116 [ 2117 "I know coffee has more ummppphhh.", 2118 "Sorry, dude!" 2119 ] 2120 } 2122 Figure 19 2124 7. Responding to Help Queries 2126 The appropriate response to /help queries as defined by 2127 [I-D.ietf-weirds-rdap-query] is to use the notices structure as 2128 defined in Section 4.3. 2130 This is an example of a response to a /help query including the 2131 rdapConformance data structure. 2133 { 2134 "rdapConformance" : 2135 [ 2136 "rdap_level_0" 2137 ], 2138 "notices" : 2139 [ 2140 { 2141 "title" : "Authentication Policy", 2142 "description" : 2143 [ 2144 "Access to sensitive data for users with proper credentials." 2145 ], 2146 "links" : 2147 [ 2148 { 2149 "value" : "http://example.net/help", 2150 "rel" : "alternate", 2151 "type" : "text/html", 2152 "href" : "http://www.example.com/auth_policy.html" 2153 } 2154 ] 2155 } 2156 ] 2157 } 2159 Figure 20 2161 8. Responding To Searches 2163 [I-D.ietf-weirds-rdap-query] specifies three types of searches: 2164 domains, nameservers, and entities. Responses to these searches take 2165 the form of an array of object instances where each instance is an 2166 appropriate object class for the search (i.e. a search for /domains 2167 yields an array of domain object instances). These arrays are 2168 contained within the response object. 2170 The names of the arrays are as follows: 2172 o for /domains searches, the array is "domainSearchResults" 2174 o for /nameservers searches, the array is "nameserverSearchResults" 2176 o for /entities searches, the array is "entitySearchResults" 2177 The following is an elided example of a response to a /domains 2178 search. 2180 { 2181 "rdapConformance" : 2182 [ 2183 "rdap_level_0" 2184 ], 2185 ... 2186 "domainSearchResults" : 2187 [ 2188 { 2189 "handle" : "1-XXXX", 2190 "ldhName" : "1.example.com", 2191 ... 2192 }, 2193 { 2194 "handle" : "2-XXXX", 2195 "ldhName" : "2.example.com", 2196 ... 2197 } 2198 ] 2199 } 2201 search_response_example 2203 9. Indicating Truncated Responses 2205 In cases where the data of a response has been truncated (i.e. not 2206 all of it has been included in the response), a server may indicate 2207 this by including a typed notice in the response object. 2209 The following is an elided example of a search response that has been 2210 truncated. 2212 { 2213 "rdapConformance" : 2214 [ 2215 "rdap_level_0" 2216 ], 2217 "notices" : 2218 [ 2219 { 2220 "title" : "Search Policy", 2221 "type" : "result set truncated due to authorization", 2222 "description" : 2223 [ 2224 "Search results are limited to 25 per day per querying IP." 2225 ], 2226 "links" : 2227 [ 2228 { 2229 "value" : "http://example.net/help", 2230 "rel" : "alternate", 2231 "type" : "text/html", 2232 "href" : "http://www.example.com/search_policy.html" 2233 } 2234 ] 2235 } 2236 ], 2237 "domainSearchResults" : 2238 [ 2239 ... 2240 ] 2241 } 2243 search_response_truncated_example 2245 A similar technique can be used with a typed remark where a single 2246 object has been returned and data in that object has been truncated. 2247 Such an example might be an entity object with only a partial set of 2248 the IP networks associated with it. 2250 The following is an elided example of an entity truncated data. 2252 { 2253 "objectClassName" : "entity", 2254 "handle" : "ANENTITY", 2255 "roles" : [ "registrant" ], 2256 ... 2257 "entities" : 2258 [ 2259 { 2260 "objectClassName" : "entity", 2261 "handle": "ANEMBEDDEDENTITY", 2262 "roles" : [ "technical" ], 2263 ... 2264 }, 2265 ... 2266 ], 2267 "networks" : 2268 [ 2269 ... 2270 ], 2271 ... 2272 "remarks" : 2273 [ 2274 { 2275 "title" : "Data Policy", 2276 "type" : "object truncated due to unexplainable reason", 2277 "description" : 2278 [ 2279 "Some of the data in this object has been removed." 2280 ], 2281 "links" : 2282 [ 2283 { 2284 "value" : "http://example.net/help", 2285 "rel" : "alternate", 2286 "type" : "text/html", 2287 "href" : "http://www.example.com/data_policy.html" 2288 } 2289 ] 2290 } 2291 ] 2292 } 2294 Figure 21 2296 10. IANA Considerations 2298 10.1. RDAP JSON Media Type Registration 2300 This specification registers the "application/rdap+json" media type. 2302 Type name: application 2304 Subtype name: rdap+json 2306 Required parameters: n/a 2308 Encoding considerations: See section 3.1 of [RFC6839]. 2310 Security considerations: The media represented by this identifier 2311 does not have security considerations beyond that found in section 2312 6 of [RFC7159] 2314 Interoperability considerations: There are no known 2315 interoperability problems regarding this media format. 2317 Published specification: [[ this document ]] 2319 Applications that use this media type: Implementations of the 2320 Registration Data Access Protocol (RDAP) 2322 Additional information: This media type is a product of the IETF 2323 WEIRDS working group. The WEIRDS charter, information on the 2324 WEIRDS mailing list, and other documents produced by the WEIRDS 2325 working group can be found at https://datatracker.ietf.org/wg/ 2326 weirds/ 2328 Person & email address to contact for further information: IESG 2329 2331 Intended usage: COMMON 2333 Restrictions on usage: none 2335 Author: Andy Newton 2337 Change controller: IETF 2339 Provisional Registration: No (upon publication of this RFC) 2341 10.2. JSON Values Registry 2343 This section requests that the IANA establish an RDAP JSON Values 2344 Registry for use in the notices and remarks (Section 4.3), status 2345 (Section 4.6), role (Section 5.1), event action (Section 4.5), and 2346 domain variant relation (Section 5.3) fields specified in RDAP. 2348 Each entry in the registry should contain the following fields: 2350 1. Value - the string value being registered. 2352 2. Type - the type of value being registered. It should be one of 2353 the following: 2355 * 'notice or remark type' - denotes a type of notice or remark 2357 * 'status' - denotes a value for the 'status' object member as 2358 defined by Section 4.6. 2360 * 'role' - denotes a value for the 'role' array as defined in 2361 Section 5.1. 2363 * 'event action' - denotes a value for an event action as 2364 defined in Section 4.5. 2366 * 'domain variant relation' - denotes a relationship between a 2367 domain and a domain variant as defined in Section 5.3. 2369 3. Description - a one or two sentence description regarding the 2370 meaning of the value, how it might be used, and/or how it should 2371 be interpreted by clients. 2373 4. Registrant Name - the name of the person registering the value. 2375 5. Registrant Contact Information - an email address, postal 2376 address, or some other information to be used to contact the 2377 registrant. 2379 This registry is to be operated under the "Expert Review" policy 2380 defined in [RFC5226]. 2382 Review of registrations into this registry by the designated 2383 expert(s) should be narrowly judged on the following criteria: 2385 1. Values in need of being placed into multiple types must be 2386 assigned a separate registration for each type. 2388 2. Values must be strings. They should be multiple words separated 2389 by single space characters. Every character should be 2390 lowercased. If possible, every word should be given in English 2391 and each character should be US ASCII. 2393 3. Registrations should not duplicate the meaning of any existing 2394 registration. That is, if a request for a registration is 2395 significantly similar in nature to an existing registration, the 2396 request should be denied. For example, the terms 'maintainer' 2397 and 'registrant' are significantly similar in nature as they both 2398 denote a holder of a domain name or Internet number resource. In 2399 cases where it may be reasonably argued that machine 2400 interpretation of two similar values may alter the operation of 2401 client software, designated experts should not judge the values 2402 to be of significant similarity. 2404 4. Registrations should be relevant to the common usages of RDAP. 2405 Designated experts may rely upon the serving of the value by a 2406 DNR or RIR to make this determination. 2408 The following sections provide initial registrations into this 2409 registry. 2411 10.2.1. Notice and Remark Types 2413 This section registers the following values into the RDAP JSON Values 2414 Registry: 2416 1. 2418 * Value: result set truncated due to authorization 2420 * Type: notice and remark type 2422 * Description: The list of results does not contain all results 2423 due to lack of authorization. This may indicate to some 2424 clients that proper authorization will yield a longer result 2425 set. 2427 * Registrant Name: IESG 2429 * Registrant Contact Information: iesg@ietf.org 2431 2. 2433 * Value: result set truncated due to excessive load 2435 * Type: notice and remark type 2436 * Description: The list of results does not contain all results 2437 due to excessively heavy load on the server. This may 2438 indicate to some clients that requerying at a later time will 2439 yield a longer result set. 2441 * Registrant Name: IESG 2443 * Registrant Contact Information: iesg@ietf.org 2445 3. 2447 * Value: result set truncated due to unexplainable reasons 2449 * Type: notice and remark type 2451 * Description: The list of results does not contain all results 2452 for an unexplainable reason. This may indicate to some 2453 clients that requerying for any reason will not yield a longer 2454 result set. 2456 * Registrant Name: IESG 2458 * Registrant Contact Information: iesg@ietf.org 2460 4. 2462 * Value: object truncated due to authorization 2464 * Type: notice and remark type 2466 * Description: The object does not contain all data due to lack 2467 of authorization. 2469 * Registrant Name: IESG 2471 * Registrant Contact Information: iesg@ietf.org 2473 5. 2475 * Value: object truncated due to excessive load 2477 * Type: notice and remark type 2479 * Description: The object does not contain all data due to 2480 excessively heavy load on the server. This may indicate to 2481 some clients that requerying at a later time will yield all 2482 data of the object. 2484 * Registrant Name: IESG 2486 * Registrant Contact Information: iesg@ietf.org 2488 6. 2490 * Value: object truncated due to unexplainable reasons 2492 * Type: notice and remark type 2494 * Description: The object does not contain all data for an 2495 unexplainable reason. 2497 * Registrant Name: IESG 2499 * Registrant Contact Information: iesg@ietf.org 2501 10.2.2. Status 2503 This section registers the following values into the RDAP JSON Values 2504 Registry: 2506 1. 2508 * Value: validated 2510 * Type: status 2512 * Description: Signifies that the data of the object instance 2513 has been found to be accurate. This type of status is 2514 usually found on entity object instances to note the validity 2515 of identifying contact information. 2517 * Registrant Name: IESG 2519 * Registrant Contact Information: iesg@ietf.org 2521 2. 2523 * Value: renew prohibited 2525 * Type: status 2527 * Description: Renewal or reregistration of the object instance 2528 is forbidden. 2530 * Registrant Name: IESG 2531 * Registrant Contact Information: iesg@ietf.org 2533 3. 2535 * Value: update prohibited 2537 * Type: status 2539 * Description: Updates to the object instance are forbidden. 2541 * Registrant Name: IESG 2543 * Registrant Contact Information: iesg@ietf.org 2545 4. 2547 * Value: transfer prohibited 2549 * Type: status 2551 * Description: Transfers of the registration from one registrar 2552 to another are forbidden. This type of status normally 2553 applies to DNR domain names. 2555 * Registrant Name: IESG 2557 * Registrant Contact Information: iesg@ietf.org 2559 5. 2561 * Value: delete prohibited 2563 * Type: status 2565 * Description: Deletion of the registration of the object 2566 instance is forbidden. This type of status normally applies 2567 to DNR domain names. 2569 * Registrant Name: IESG 2571 * Registrant Contact Information: iesg@ietf.org 2573 6. 2575 * Value: proxy 2577 * Type: status 2578 * Description: The registration of the object instance has been 2579 performed by a third party. This is most commonly applied to 2580 entities. 2582 * Registrant Name: IESG 2584 * Registrant Contact Information: iesg@ietf.org 2586 7. 2588 * Value: private 2590 * Type: status 2592 * Description: The information of the object instance is not 2593 designated for public consumption. This is most commonly 2594 applied to entities. 2596 * Registrant Name: IESG 2598 * Registrant Contact Information: iesg@ietf.org 2600 8. 2602 * Value: redacted 2604 * Type: status 2606 * Description: Some of the information of the object instance 2607 has not been made available. This is most commonly applied 2608 to entities. 2610 * Registrant Name: IESG 2612 * Registrant Contact Information: iesg@ietf.org 2614 9. 2616 * Value: obscured 2618 * Type: status 2620 * Description: Some of the information of the object instance 2621 has been altered for the purposes of not readily revealing 2622 the actual information of the object instance. This is most 2623 commonly applied to entities. 2625 * Registrant Name: IESG 2626 * Registrant Contact Information: iesg@ietf.org 2628 10. 2630 * Value: associated 2632 * Type: status 2634 * Description: The object instance is associated with other 2635 object instances in the registry. This is most commonly used 2636 to signify that a nameserver is associated with a domain or 2637 that an entity is associated with a network resource or 2638 domain. 2640 * Registrant Name: IESG 2642 * Registrant Contact Information: iesg@ietf.org 2644 11. 2646 * Value: active 2648 * Type: status 2650 * Description: The object instance is in use. For domain 2651 names, it signifies that the domain name is published in DNS. 2652 For network and autnum registrations it signifies that they 2653 are allocated or assigned for use in operational networks. 2654 This maps to the Extensible Provisioning Protocol (EPP) 2655 [RFC5730] 'OK' status. 2657 * Registrant Name: IESG 2659 * Registrant Contact Information: iesg@ietf.org 2661 12. 2663 * Value: inactive 2665 * Type: status 2667 * Description: The object instance is not in use. See 2668 'active'. 2670 * Registrant Name: IESG 2672 * Registrant Contact Information: iesg@ietf.org 2674 13. 2676 * Value: locked 2678 * Type: status 2680 * Description: Changes to the object instance cannot be made, 2681 including the association of other object instances. 2683 * Registrant Name: IESG 2685 * Registrant Contact Information: iesg@ietf.org 2687 14. 2689 * Value: pending create 2691 * Type: status 2693 * Description: A request has been received for the creation of 2694 the object instance but this action is not yet complete. 2696 * Registrant Name: IESG 2698 * Registrant Contact Information: iesg@ietf.org 2700 15. 2702 * Value: pending renew 2704 * Type: status 2706 * Description: A request has been received for the renewal of 2707 the object instance but this action is not yet complete. 2709 * Registrant Name: IESG 2711 * Registrant Contact Information: iesg@ietf.org 2713 16. 2715 * Value: pending transfer 2717 * Type: status 2719 * Description: A request has been received for the transfer of 2720 the object instance but this action is not yet complete. 2722 * Registrant Name: IESG 2724 * Registrant Contact Information: iesg@ietf.org 2726 17. 2728 * Value: pending update 2730 * Type: status 2732 * Description: A request has been received for the update or 2733 modification of the object instance but this action is not 2734 yet complete. 2736 * Registrant Name: IESG 2738 * Registrant Contact Information: iesg@ietf.org 2740 18. 2742 * Value: pending delete 2744 * Type: status 2746 * Description: A request has been received for the deletion or 2747 removal of the object instance but this action is not yet 2748 complete. For domains, this might mean that the name is no 2749 longer published in DNS but has not yet been purged from the 2750 registry database. 2752 * Registrant Name: IESG 2754 * Registrant Contact Information: iesg@ietf.org 2756 10.2.3. Event Actions 2758 This section registers the following values into the RDAP JSON Values 2759 Registry: 2761 1. 2763 * Value: registration 2765 * Type: event action 2767 * Description: The object instance was initially registered. 2769 * Registrant Name: IESG 2770 * Registrant Contact Information: iesg@ietf.org 2772 2. 2774 * Value: reregistration 2776 * Type: event action 2778 * Description: The object instance was registered subsequently 2779 to initial registration. 2781 * Registrant Name: IESG 2783 * Registrant Contact Information: iesg@ietf.org 2785 3. 2787 * Value: last changed 2789 * Type: event action 2791 * Description: An action noting when the information in the 2792 object instance was last changed. 2794 * Registrant Name: IESG 2796 * Registrant Contact Information: iesg@ietf.org 2798 4. 2800 * Value: expiration 2802 * Type: event action 2804 * Description: The object instance has been removed or will be 2805 removed at a pre-determined date and time from the registry. 2807 * Registrant Name: IESG 2809 * Registrant Contact Information: iesg@ietf.org 2811 5. 2813 * Value: deletion 2815 * Type: event action 2816 * Description: The object instance was removed from the registry 2817 at a point in time that was not pre-determined. 2819 * Registrant Name: IESG 2821 * Registrant Contact Information: iesg@ietf.org 2823 6. 2825 * Value: reinstantiation 2827 * Type: event action 2829 * Description: The object instance was reregistered after having 2830 been removed from the registry. 2832 * Registrant Name: IESG 2834 * Registrant Contact Information: iesg@ietf.org 2836 7. 2838 * Value: transfer 2840 * Type: event action 2842 * Description: The object instance was transferred from one 2843 registrant to another. 2845 * Registrant Name: IESG 2847 * Registrant Contact Information: iesg@ietf.org 2849 8. 2851 * Value: locked 2853 * Type: event action 2855 * Description: The object instance was locked (see the 'locked' 2856 status). 2858 * Registrant Name: IESG 2860 * Registrant Contact Information: iesg@ietf.org 2862 9. 2864 * Value: unlocked 2866 * Type: event action 2868 * Description: The object instance was unlocked (see the 2869 'locked' status). 2871 * Registrant Name: IESG 2873 * Registrant Contact Information: iesg@ietf.org 2875 10.2.4. Roles 2877 This section registers the following values into the RDAP JSON Values 2878 Registry: 2880 1. 2882 * Value: registrant 2884 * Type: role 2886 * Description: The entity object instance is the registrant of 2887 the registration. In some registries, this is known as a 2888 maintainer. 2890 * Registrant Name: IESG 2892 * Registrant Contact Information: iesg@ietf.org 2894 2. 2896 * Value: technical 2898 * Type: role 2900 * Description: The entity object instance is a technical 2901 contact for the registration. 2903 * Registrant Name: IESG 2905 * Registrant Contact Information: iesg@ietf.org 2907 3. 2909 * Value: administrative 2911 * Type: role 2912 * Description: The entity object instance is an administrative 2913 contact for the registration. 2915 * Registrant Name: IESG 2917 * Registrant Contact Information: iesg@ietf.org 2919 4. 2921 * Value: abuse 2923 * Type: role 2925 * Description: The entity object instance handles network abuse 2926 issues on behalf of the registrant of the registration. 2928 * Registrant Name: IESG 2930 * Registrant Contact Information: iesg@ietf.org 2932 5. 2934 * Value: billing 2936 * Type: role 2938 * Description: The entity object instance handles payment and 2939 billing issues on behalf of the registrant of the 2940 registration. 2942 * Registrant Name: IESG 2944 * Registrant Contact Information: iesg@ietf.org 2946 6. 2948 * Value: registrar 2950 * Type: role 2952 * Description: The entity object instance represents the 2953 authority responsible for the registration in the registry. 2955 * Registrant Name: IESG 2957 * Registrant Contact Information: iesg@ietf.org 2959 7. 2961 * Value: reseller 2963 * Type: role 2965 * Description: The entity object instance represents a third 2966 party through which the registration was conducted (i.e. not 2967 the registry or registrar). 2969 * Registrant Name: IESG 2971 * Registrant Contact Information: iesg@ietf.org 2973 8. 2975 * Value: sponsor 2977 * Type: role 2979 * Description: The entity object instance represents a domain 2980 policy sponsor, such as an ICANN approved sponsor. 2982 * Registrant Name: IESG 2984 * Registrant Contact Information: iesg@ietf.org 2986 9. 2988 * Value: proxy 2990 * Type: role 2992 * Description: The entity object instance represents a proxy 2993 for another entity object, such as a registrant. 2995 * Registrant Name: IESG 2997 * Registrant Contact Information: iesg@ietf.org 2999 10. 3001 * Value: notifications 3003 * Type: role 3005 * Description: An entity object instance designated to receive 3006 notifications about association object instances. 3008 * Registrant Name: IESG 3009 * Registrant Contact Information: iesg@ietf.org 3011 11. 3013 * Value: noc 3015 * Type: role 3017 * Description: The entity object instance handles 3018 communications related to a network operations center (NOC). 3020 * Registrant Name: IESG 3022 * Registrant Contact Information: iesg@ietf.org 3024 10.2.5. Variant Relations 3026 This section registers the following values into the RDAP JSON Values 3027 Registry: 3029 1. 3031 * Value: registered 3033 * Type: domain variant relation 3035 * Description: The variant names are registered in the registry. 3037 * Registrant Name: IESG 3039 * Registrant Contact Information: iesg@ietf.org 3041 2. 3043 * Value: unregistered 3045 * Type: domain variant relation 3047 * Description: The variant names are not found in the registry. 3049 * Registrant Name: IESG 3051 * Registrant Contact Information: iesg@ietf.org 3053 3. 3055 * Value: registration restricted 3056 * Type: domain variant relation 3058 * Description: Registration of the variant names is restricted 3059 to certain parties or within certain rules. 3061 * Registrant Name: IESG 3063 * Registrant Contact Information: iesg@ietf.org 3065 4. 3067 * Value: open registration 3069 * Type: domain variant relation 3071 * Description: Registration of the variant names is available to 3072 generally qualified registrants. 3074 * Registrant Name: IESG 3076 * Registrant Contact Information: iesg@ietf.org 3078 5. 3080 * Value: conjoined 3082 * Type: domain variant relation 3084 * Description: Registration of the variant names occurs 3085 automatically with the registration of the containing domain 3086 registration. 3088 * Registrant Name: IESG 3090 * Registrant Contact Information: iesg@ietf.org 3092 11. Security Considerations 3094 This specification models information serialized in JSON format. As 3095 JSON is a subset of Javascript, implementations are advised to follow 3096 the security considerations outlined in Section 6 of [RFC7159] to 3097 prevent code injection. 3099 Though not specific to JSON, RDAP implementers should be aware of the 3100 security considerations specified in [I-D.ietf-weirds-using-http] and 3101 the security requirements and considerations in 3102 [I-D.ietf-weirds-rdap-sec]. 3104 12. Internationalization Considerations 3106 12.1. Character Encoding 3108 The default text encoding for JSON responses in RDAP is UTF-8 3109 [RFC3629], and all servers and clients MUST support UTF-8. 3111 12.2. URIs and IRIs 3113 [I-D.ietf-weirds-using-http] defines the use of URIs and IRIs in 3114 RDAP. 3116 12.3. Language Tags 3118 Section 4.4 defines the use of language tags in the JSON responses 3119 defined in this document. 3121 12.4. Internationalized Domain Names 3123 Internationalized Domain Names (IDNs) are denoted in this 3124 specification by the separation of DNS names in LDH form and Unicode 3125 form (see Section 3). Representation of IDNs in registries is 3126 described by the "variants" object in Section 5.3 and the suggested 3127 values listed in Section 10.2.5. 3129 13. Privacy Considerations 3131 This specification suggests status values to denote contact and 3132 registrant information that has been marked as private and/or has 3133 been redacted or obscured. See Section 10.2.2 for the list of status 3134 values. See Appendix A.1 on guidance to apply those values to 3135 contacts and registrants. 3137 14. Contributing Authors and Acknowledgements 3139 This document is derived from original work on RIR responses in JSON 3140 by Byron J. Ellacott, Arturo L. Servin, Kaveh Ranjbar, and Andrew 3141 L. Newton. Additionally, this document incorporates work on DNR 3142 responses in JSON by Ning Kong, Linlin Zhou, Jiagui Xie, and Sean 3143 Shen. 3145 The components of the DNR object classes are derived from a 3146 categorization of WHOIS response formats created by Ning Kong, Linlin 3147 Zhou, and Guangqing Deng, Steve Sheng and Francisco Arias, Ray 3148 Bellis, and Frederico Neves. 3150 Tom Harrison, Murray Kucherawy, Ed Lewis contributed significant 3151 review comments and provided clarifying text. James Mitchell 3152 provided text regarding the processing of unknown JSON attributes and 3153 identified issues leading to the remodeling of events. Ernie Dainow 3154 and Francisco Obispo provided concrete suggestions that led to a 3155 better variant model for domain names. 3157 Ernie Dainow provided the background information on the secure DNSSEC 3158 attributes and objects for domains, informative text on DNSSEC, and 3159 many other attributes that appear throughout the object classes of 3160 this draft. 3162 The switch to and incorporation of jCard (JSON vCard) was performed 3163 by Simon Perreault. 3165 Olaf Kolkman and Murray Kucherawy chaired the IETF's WEIRDS working 3166 group from which this document as been created. 3168 15. References 3170 15.1. Normative References 3172 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3173 Requirement Levels", BCP 14, RFC 2119, March 1997. 3175 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 3176 Internet: Timestamps", RFC 3339, July 2002. 3178 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3179 10646", STD 63, RFC 3629, November 2003. 3181 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3182 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3183 3986, January 2005. 3185 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 3186 Rose, "Resource Records for the DNS Security Extensions", 3187 RFC 4034, March 2005. 3189 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3190 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3191 May 2008. 3193 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 3194 Autonomous System (AS) Numbers", RFC 5396, December 2008. 3196 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 3197 Languages", BCP 47, RFC 5646, September 2009. 3199 [RFC5890] Klensin, J., "Internationalized Domain Names for 3200 Applications (IDNA): Definitions and Document Framework", 3201 RFC 5890, August 2010. 3203 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3204 Address Text Representation", RFC 5952, August 2010. 3206 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3208 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 3209 January 2014. 3211 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3212 Interchange Format", RFC 7159, March 2014. 3214 [I-D.ietf-weirds-using-http] 3215 Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the 3216 Registration Data Access Protocol (RDAP)", draft-ietf- 3217 weirds-using-http-12 (work in progress), September 2014. 3219 [I-D.ietf-weirds-rdap-query] 3220 Newton, A. and S. Hollenbeck, "Registration Data Access 3221 Protocol Query Format", draft-ietf-weirds-rdap-query-14 3222 (work in progress), September 2014. 3224 [I-D.ietf-weirds-rdap-sec] 3225 Hollenbeck, S. and N. Kong, "Security Services for the 3226 Registration Data Access Protocol", draft-ietf-weirds- 3227 rdap-sec-09 (work in progress), September 2014. 3229 [ISO.3166.1988] 3230 International Organization for Standardization, "Codes for 3231 the representation of names of countries, 3rd edition", 3232 ISO Standard 3166, August 1988. 3234 15.2. Informative References 3236 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 3237 September 2004. 3239 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 3240 STD 69, RFC 5730, August 2009. 3242 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 3243 Security Extensions Mapping for the Extensible 3244 Provisioning Protocol (EPP)", RFC 5910, May 2010. 3246 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 3247 August 2011. 3249 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 3250 Structured Syntax Suffixes", RFC 6839, January 2013. 3252 [JSON_acendancy] 3253 MacVittie, , "The Stealthy Ascendancy of JSON", 04 2011. 3255 [IANA_IDNTABLES] 3256 "IANA IDN Tables", 3257 . 3259 [JSON_performance_study] 3260 Montana State University - Bozeman, Montana State 3261 University - Bozeman, Montana State University - Bozeman, 3262 and Montana State University - Bozeman, "Comparison of 3263 JSON and XML Data Interchange Formats: A Case Study", 3264 2009. 3266 Appendix A. Suggested Data Modeling with the Entity Object Class 3268 A.1. Registrants and Contacts 3270 This document does not provide specific object classes for 3271 registrants and contacts. Instead the entity object class may be 3272 used to represent a registrant or contact. When the entity object is 3273 embedded inside a containing object such as a domain name or IP 3274 network, the 'roles' string array can be used to signify the 3275 relationship. It is recommended that the values from Section 10.2.4 3276 be used. 3278 The following is an example of an elided containing object with an 3279 embedded entity that is both a registrant and administrative contact: 3281 { 3282 ... 3283 "entities" : 3284 [ 3285 { 3286 "objectClassName" : "entity", 3287 "handle" : "XXXX", 3288 "vcardArray":[ 3289 "vcard", 3290 [ 3291 ["version", {}, "text", "4.0"], 3292 ["fn", {}, "text", "Joe User"], 3294 ["kind", {}, "text", "individual"], 3295 ["lang", { 3296 "pref":"1" 3297 }, "language-tag", "fr"], 3298 ["lang", { 3299 "pref":"2" 3300 }, "language-tag", "en"], 3301 ["org", { 3302 "type":"work" 3303 }, "text", "Example"], 3304 ["title", {}, "text", "Research Scientist"], 3305 ["role", {}, "text", "Project Lead"], 3306 ["adr", 3307 { "type":"work" }, 3308 "text", 3309 [ 3310 "", 3311 "Suite 1234", 3312 "4321 Rue Somewhere", 3313 "Quebec", 3314 "QC", 3315 "G1V 2M2", 3316 "Canada" 3317 ] 3318 ], 3319 ["tel", 3320 { "type":["work", "voice"], "pref":"1" }, 3321 "uri", "tel:+1-555-555-1234;ext=102" 3322 ], 3323 ["email", 3324 { "type":"work" }, 3325 "text", "joe.user@example.com" 3326 ] 3327 ] 3328 ], 3329 "roles" : [ "registrant", "administrative" ], 3330 "remarks" : 3331 [ 3332 { 3333 "description" : 3334 [ 3335 "She sells sea shells down by the sea shore.", 3336 "Originally written by Terry Sullivan." 3337 ] 3338 } 3339 ], 3340 "events" : 3341 [ 3342 { 3343 "eventAction" : "registration", 3344 "eventDate" : "1990-12-31T23:59:59Z" 3345 }, 3346 { 3347 "eventAction" : "last changed", 3348 "eventDate" : "1991-12-31T23:59:59Z" 3349 } 3350 ] 3351 } 3352 ] 3353 } 3355 In many use cases, it is necessary to hide or obscure the information 3356 of a registrant or contact due to policy or other operational 3357 matters. Registries can denote these situations with 'status' values 3358 (see Section 10.2.2). 3360 The following is an elided example of a registrant with information 3361 changed to reflect that of a third party. 3363 { 3364 ... 3365 "entities" : 3366 [ 3367 { 3368 "objectClassName" : "entity", 3369 "handle" : "XXXX", 3370 ... 3371 "roles" : [ "registrant", "administrative" ], 3372 "status" : [ "proxy", "private", "obscured" ] 3373 } 3374 ] 3375 } 3377 A.2. Registrars 3379 This document does not provide a specific object class for 3380 registrars, but like registrants and contacts (see Appendix A.1) the 3381 'roles' string array maybe used. Additionally, many registrars have 3382 publicly assigned identifiers. The 'publicIds' structure 3383 (Section 4.8) represents that information. 3385 The following is an example of an elided containing object with an 3386 embedded entity that is a registrar: 3388 { 3389 ... 3390 "entities":[ 3391 { 3392 "objectClassName" : "entity", 3393 "handle":"XXXX", 3394 "vcardArray":[ 3395 "vcard", 3396 [ 3397 ["version", {}, "text", "4.0"], 3398 ["fn", {}, "text", "Joe's Fish, Chips and Domains"], 3399 ["kind", {}, "text", "org"], 3400 ["lang", { 3401 "pref":"1" 3402 }, "language-tag", "fr"], 3403 ["lang", { 3404 "pref":"2" 3405 }, "language-tag", "en"], 3406 ["org", { 3407 "type":"work" 3408 }, "text", "Example"], 3409 ["adr", 3410 { "type":"work" }, 3411 "text", 3412 [ 3413 "", 3414 "Suite 1234", 3415 "4321 Rue Somewhere", 3416 "Quebec", 3417 "QC", 3418 "G1V 2M2", 3419 "Canada" 3420 ] 3421 ], 3422 ["tel", 3423 { 3424 "type":["work", "voice"], 3425 "pref":"1" 3426 }, 3427 "uri", "tel:+1-555-555-1234;ext=102" 3428 ], 3429 ["email", 3430 { "type":"work" }, 3431 "text", "joes_fish_chips_and_domains@example.com" 3432 ] 3433 ] 3434 ], 3435 "roles":[ "registrar" ], 3436 "publicIds":[ 3437 { 3438 "type":"IANA Registrar ID", 3439 "identifier":"1" 3440 } 3441 ], 3442 "remarks":[ 3443 { 3444 "description":[ 3445 "She sells sea shells down by the sea shore.", 3446 "Originally written by Terry Sullivan." 3447 ] 3448 } 3449 ], 3450 "links":[ 3451 { 3452 "value":"http://example.net/entity/XXXX", 3453 "rel":"alternate", 3454 "type":"text/html", 3455 "href":"http://www.example.com" 3456 } 3457 ] 3458 } 3459 ] 3460 } 3462 Appendix B. Modeling Events 3464 Events represent actions that have taken place against a registered 3465 object at a certain date and time. Events have three properties: the 3466 action, the actor, and the date and time of the event (which is 3467 sometimes in the future). In some cases the identity of the actor is 3468 not captured. 3470 Events can be modeled in three ways: 3472 1. events with no designated actor 3474 2. events where the actor is only designated by an identifier 3476 3. events where the actor can be modeled as an entity 3478 For the first use case, the 'events' data structure (Section 4.5) is 3479 used without the 'eventActor' object member. 3481 This is an example of an "events" array without the 'eventActor'. 3483 "events" : 3484 [ 3485 { 3486 "eventAction" : "registration", 3487 "eventDate" : "1990-12-31T23:59:59Z" 3488 } 3489 ] 3491 Figure 22 3493 For the second use case, the 'events' data structure (Section 4.5) is 3494 used with the 'eventActor' object member. 3496 This is an example of an "events" array with the 'eventActor'. 3498 "events" : 3499 [ 3500 { 3501 "eventAction" : "registration", 3502 "eventActor" : "XYZ-NIC", 3503 "eventDate" : "1990-12-31T23:59:59Z" 3504 } 3505 ] 3507 Figure 23 3509 For the third use case, the 'asEventActor' array is used when an 3510 entity (Section 5.1) is embedded into another object class. The 3511 'asEventActor' array follows the same structure as the 'events' array 3512 but does not have 'eventActor' attributes. 3514 The following is an elided example of a domain object with an entity 3515 as an event actor. 3517 { 3518 "objectClassName" : "domain", 3519 "handle" : "XXXX", 3520 "ldhName" : "foo.example", 3521 "status" : [ "locked", "transfer Prohibited" ], 3522 ... 3523 "entities" : 3524 [ 3525 { 3526 "handle" : "XXXX", 3527 ... 3528 "asEventActor" : 3529 [ 3530 { 3531 "eventAction" : "last changed", 3532 "eventDate" : "1990-12-31T23:59:59Z" 3533 } 3534 ] 3535 } 3536 ] 3537 } 3539 Appendix C. Structured vs Unstructured Addresses 3541 The entity (Section 5.1) object class uses jCard [RFC7095] to 3542 represent contact information, including postal addresses. jCard has 3543 the ability to represent multiple language preferences, multiple 3544 email address and phone numbers, and multiple postal addresses in 3545 both a structured and unstructured format. This section describes 3546 the use of jCard for representing structured and unstructured 3547 addresses. 3549 The following is an example of a jCard. 3551 { 3552 "vcardArray":[ 3553 "vcard", 3554 [ 3555 ["version", {}, "text", "4.0"], 3556 ["fn", {}, "text", "Joe User"], 3557 ["n", {}, "text", 3558 ["User", "Joe", "", "", ["ing. jr", "M.Sc."]] 3560 ], 3561 ["bday", {}, "date-and-or-time", "--02-03"], 3562 ["anniversary", 3563 {}, "date-and-or-time", "2009-08-08T14:30:00-05:00" 3564 ], 3565 ["gender", {}, "text", "M"], 3566 ["kind", {}, "text", "individual"], 3567 ["lang", { 3568 "pref":"1" 3569 }, "language-tag", "fr"], 3570 ["lang", { 3571 "pref":"2" 3572 }, "language-tag", "en"], 3573 ["org", { 3574 "type":"work" 3575 }, "text", "Example"], 3576 ["title", {}, "text", "Research Scientist"], 3577 ["role", {}, "text", "Project Lead"], 3578 ["adr", 3579 { "type":"work" }, 3580 "text", 3581 [ 3582 "", 3583 "Suite 1234", 3584 "4321 Rue Somewhere", 3585 "Quebec", 3586 "QC", 3587 "G1V 2M2", 3588 "Canada" 3589 ] 3590 ], 3591 ["adr", 3592 { 3593 "type":"home", 3594 "label":"123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 3595 }, 3596 "text", 3597 [ 3598 "", "", "", "", "", "", "" 3599 ] 3600 ], 3601 ["tel", 3602 { "type":["work", "voice"], "pref":"1" }, 3603 "uri", "tel:+1-555-555-1234;ext=102" 3604 ], 3605 ["tel", 3606 { 3607 "type":["work", "cell", "voice", "video", "text"] 3609 }, 3610 "uri", 3611 "tel:+1-555-555-1234" 3612 ], 3613 ["email", 3614 { "type":"work" }, 3615 "text", "joe.user@example.com" 3616 ], 3617 ["geo", { 3618 "type":"work" 3619 }, "uri", "geo:46.772673,-71.282945"], 3620 ["key", 3621 { "type":"work" }, 3622 "uri", "http://www.example.com/joe.user/joe.asc" 3623 ], 3624 ["tz", {}, 3625 "utc-offset", "-05:00"], 3626 ["url", { "type":"home" }, 3627 "uri", "http://example.org"] 3628 ] 3629 ] 3630 } 3632 Figure 24 3634 The arrays in Figure 24 with the first member of "adr" represent 3635 postal addresses. In the first example, the postal address is given 3636 as a an array of strings and constitutes a structured address. For 3637 components of the structured address that are not applicable, an 3638 empty string is given. Each member of that array aligns with the 3639 positions of a vCard as given in [RFC6350]. In this example, the 3640 following data corresponds to the following positional meanings: 3642 1. post office box - not applicable, empty string 3644 2. extended address (e.g., apartment or suite number) - Suite 1234 3646 3. street address - 4321 Rue Somewhere 3648 4. locality (e.g., city) - Quebec 3650 5. region (e.g., state or province) - QC 3652 6. postal code - G1V 2M2 3654 7. country name (full name) - Canada 3655 The second example is an unstructured address. It uses the label 3656 attribute, which is a string containing a newline (\n) character to 3657 separate address components in an unordered, unspecified manner. 3658 Note that in this example the structured address array is still given 3659 but that each string is an empty string. 3661 Appendix D. Secure DNS 3663 Section 5.3 defines the "secureDNS" member to represent secure DNS 3664 information about domain names. 3666 DNSSEC provides data integrity for DNS through digital signing of 3667 resource records. To enable DNSSEC, the zone is signed by one or 3668 more private keys and the signatures stored as RRSIG records. To 3669 complete the chain of trust in the DNS zone hierarchy, a digest of 3670 each DNSKEY record (which contains the public key) must be loaded 3671 into the parent zone, stored as Delegation Signer (DS) records and 3672 signed by the parent's private key (RRSIG DS record), "Resource 3673 Records for the DNS Security Extensions" [RFC4034]. Creating the DS 3674 records in the parent zone can be done by the registration authority, 3675 "Domain Name System (DNS) Security Extensions Mapping for the 3676 Extensible Provisioning Protocol (EPP)" [RFC5910]. 3678 Only DS related information is provided by RDAP, since other 3679 information is not generally stored in the registration database. 3680 Other DNSSEC related information can be retrieved with other DNS 3681 tools such as dig. 3683 The domain object class (Section 5.3) can represent this information 3684 using either the 'dsData' or 'keyData' object arrays. Client 3685 implementers should be aware that some registries do not collect or 3686 do not publish all of the secure DNS meta-information. 3688 Appendix E. Motivations for Using JSON 3690 This section addresses a common question regarding the use of JSON 3691 over other data formats, most notably XML. 3693 It is often pointed out that many DNRs and one RIR support the EPP 3694 [RFC5730] standard, which is an XML serialized protocol. The logic 3695 is that since EPP is a common protocol in the industry it follows 3696 that XML would be a more natural choice. While EPP does influence 3697 this specification quite a bit, EPP serves a different purpose which 3698 is the provisioning of Internet resources between registries and 3699 accredited registrars and serves a much narrower audience than that 3700 envisioned for RDAP. 3702 By contrast, RDAP has a broader audience and is designed for public 3703 consumption of data. Experience from RIRs with first generation 3704 RESTful web services for WHOIS indicate a large percentage of clients 3705 operate within browsers and other platforms where full-blown XML 3706 stacks are not readily available and where JSON is a better fit. 3708 Additionally, while EPP is used in much of the DNR community it is 3709 not a universal constant in that industry. And finally, EPP's use of 3710 XML predates the specification of JSON. If EPP had been defined 3711 today, it may very well have used JSON instead of XML. 3713 Beyond the specific DNR and RIR communities, the trend in the broader 3714 Internet industry is also switching to JSON over XML, especially in 3715 the area of RESTful web services (see [JSON_acendancy]). Studies 3716 have also found that JSON is generally less bulky and consequently 3717 faster to parse (see [JSON_performance_study]). 3719 Appendix F. Changelog 3721 [RFC Editor: Please delete this section prior to publication.] 3723 Initial -00 Adopted as working group document 2012-September-18. 3725 -01 3727 Minor spelling corrections. Changed "Registry Data" to 3728 "Registration Data" for the sake of consistency. 3730 Transitioned to RFC 5988 links and relationship types from our 3731 own custom "uris" structure. 3733 Some examples had 'status' as a string. Those have been 3734 corrected as 'status' is always an array of strings. 3736 Domain variants can now have a multi-valued relationship with 3737 domain registrations. 3739 "names" in the entity object class was changed to 3740 "entityNames". 3742 Some IP address examples change to IPv6. 3744 Change phone number examples and added reference to E.164. 3746 Added section on motivations for using JSON. 3748 Added error response body section. 3750 Added JSON naming section. 3752 Added common data structures section. 3754 Added the IANA Considerations section and the media type 3755 registration. 3757 Added 'lang' name/value. 3759 Added internationalization considerations section. 3761 -02 3763 Removed level from media type registration. 3765 Textual changes as given by Ed Lewis. 3767 Fixed object class linking example noted by Francisco Obispo 3769 Fixed a lot of other examples called out by Alex Sergeyev 3771 Added a note that JSON names are case sensitive 3773 Added 'status' to IP networks as suggested by Alex Sergeyev 3775 -03 3777 Added jCard verbiage and examples and deleted overlapping 3778 contact information and the appendix on postal addresses 3780 Removed the IANA considerations as they have been moved to 3781 another document 3783 Changed the remarks structure to be like notices 3785 Reordering and rewording some of the sections so they flow 3786 better 3788 Added note about object class "self" links 3790 Changed ipAddresses in nameserver object class to separate out 3791 v6 from v4 3793 Changed IP network version identifier from integer to string to 3794 be more consistent with ipAddresses identifier in nameserver 3795 object classes 3797 Changed DNS names to LDH names and Unicode names 3798 Modified the definition of 'conjoined' variant relationship so 3799 it was circular 3801 Added 'proxy', 'private', 'redacted', and 'obscured' status 3802 values (most useful for entities). 3804 Added a privacy considerations section 3806 Added a security considerations section 3808 Added 'reseller' and 'sponsor' to the list of entity roles 3810 Added the 'events' common data structure 3812 Added 'asEventActor' to entities 3814 Added appendix on event modeling 3816 Removed the subclasses/superclassing between RIRs/DNRs for 3817 entity and domain object classes 3819 Change suggested status/relation/etc values to be case/spacing 3820 consistent 3822 Normalized some of the definitions of object class members 3824 Modifying the JSON signaling section to reference the guidance 3825 in draft-ietf-weirds-using-http 3827 Changed the text regarding the process of unknown JSON 3828 attributes 3830 -04 3832 'description' removed from IP network and autnum because it is 3833 redundant with the remarks structure. 3835 Added 'entities' array to nameservers. 3837 Added 'status' to autnum. 3839 Added 'publicIds' to entity and domain. 3841 Added embedded entities to the entity object class. 3843 Added 'idnTable' to variants objects in domain object class. 3845 Changed the numbers for startNum and endNum in autnum to 3846 numbers instead of strings. 3848 Added an example for error response with full rdapConformance 3849 and notices. 3851 Added a section discussing help. 3853 Changed entities to use vcardArray and changed the examples to 3854 be current with jCard. 3856 Added a section on structured vs unstructured addresses. 3858 Added associated to the list of status values. 3860 Added a secure DNS section changed the 'delegationKey' object 3861 into the 'secureDNS' object. 3863 Changed the suggested values to an IANA registry. 3865 Added 'proxy' to the list of entity roles. 3867 -05 3869 Added IANA registration for RDAP JSON Media Type 3871 Added 'associated' status type. This was done earlier but got 3872 dropped during a reorganization of the document. 3874 Added the following status types: 3876 active 3878 inactive 3880 locked 3882 pending create 3884 pending renew 3886 pending update 3888 pending transfer 3890 pending delete 3892 renew prohibited 3894 Added the following event actions: 3896 locked 3898 unlocked 3900 Added the following roles: 3902 notifications 3904 noc 3906 Changed the 'tech' role to 'technical' 3908 Many document reference changes. 3910 Many examples have been fixed. 3912 Added links to dsData and keyData. 3914 Changed flags and protocols to integers in keyData. 3916 Added 'entities' to the specified list for autnum. 3918 Added SHOULD/SHOULD NOT language about using "type": 3919 "application/rdap+json" for self links. 3921 Added 'port43' to ip networks and autnum. 3923 -06 3925 Fix search response example. 3927 Change the returned search arrays to 'domainSearchResults', 3928 'entitySearchResults', and 'nameserverSearchResults'. 3930 -07 3932 'nameservers' in domain object class was changed to 3933 'nameServers' as in the example (note the camel case) 3935 fixed some example per email from James Mitchell 3937 fixed an example per email from Simon Perreault 3939 Added "network" to domain object class. 3941 Added networks and autnums to the entity object class. 3943 Created a section for "resultsTruncated". 3945 -08 3947 Added typed remarks and notices, removed "resultTruncated" in 3948 favor of them. 3950 Added "objectClassName". 3952 Changed JSON reference to RFC 7159. 3954 Removed unused references to RFC 0791, RFC 2616, RFC 4343, RFC 3955 5322. 3957 -09 3959 Fixed numerous examples. 3961 Reference to jCard updated. 3963 Text regarding JSON vCards has been changed to jCards. 3965 JSON naming rules do not apply to jCards. 3967 "nameserver" was made consistently all lower case. 3969 Links contained a "title" array, but it is now just a string 3970 per RFC 5988. 3972 Removed the term RESTful from the first section so it wouldn't 3973 have to be expanded. 3975 Added reference to RFC 2119 and noted that the uppercase form 3976 is what this document uses. 3978 Added text explaining why SHOULDs and SHOULD NOTs are to be 3979 followed. 3981 "port43" can now be either an domain name or IP address. 3983 "objectClassName" is now required. 3985 Numerous changes in prose for better readability. 3987 Updated the security considerations section to point to using- 3988 http and rdap-sec. 3990 -10 3991 Addressing many AD comments. 3993 Changed IANA registrations to IESG. 3995 'href' is now the only MUST in the a link. 3997 Authors' Addresses 3999 Andrew Lee Newton 4000 American Registry for Internet Numbers 4001 3635 Concorde Parkway 4002 Chantilly, VA 20151 4003 US 4005 Email: andy@arin.net 4006 URI: http://www.arin.net 4008 Scott Hollenbeck 4009 Verisign Labs 4010 12061 Bluemont Way 4011 Reston, VA 20190 4012 US 4014 Email: shollenbeck@verisign.com 4015 URI: http://www.verisignlabs.com/