idnits 2.17.1 draft-newton-rdap-jcr-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 2 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 29, 2017) is 2400 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7483 (Obsoleted by RFC 9083) Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 2 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: Informational September 29, 2017 5 Expires: April 2, 2018 7 A Description of RDAP JSON Messages Using JSON Content Rules 8 draft-newton-rdap-jcr-03 10 Abstract 12 This document describes the JSON responses in the Registration Data 13 Access Protocol with the formal notation of JSON Content Rules. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on April 2, 2018. 32 Copyright Notice 34 Copyright (c) 2017 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 2. Response . . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 3. Object Classes . . . . . . . . . . . . . . . . . . . . . . . 4 52 3.1. Entity Object Class . . . . . . . . . . . . . . . . . . . 4 53 3.2. Nameserver Object Class . . . . . . . . . . . . . . . . . 4 54 3.3. Domain Object Class . . . . . . . . . . . . . . . . . . . 5 55 3.4. IP Network Object Class . . . . . . . . . . . . . . . . . 7 56 3.5. Autnum Object Class . . . . . . . . . . . . . . . . . . . 7 57 4. Search Results . . . . . . . . . . . . . . . . . . . . . . . 7 58 5. Common Structures . . . . . . . . . . . . . . . . . . . . . . 8 59 5.1. RDAP Conformance . . . . . . . . . . . . . . . . . . . . 8 60 5.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 5.3. Notices And Remarks . . . . . . . . . . . . . . . . . . . 9 62 5.4. Language Identifier . . . . . . . . . . . . . . . . . . . 9 63 5.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 5.6. Status . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 5.7. Port 43 . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 5.8. Public IDs . . . . . . . . . . . . . . . . . . . . . . . 10 67 6. Complete JCR for RDAP . . . . . . . . . . . . . . . . . . . . 10 68 7. Normative References . . . . . . . . . . . . . . . . . . . . 16 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17 71 1. Introduction 73 The JSON [RFC7159] responses of the Registration Data Access Protocol 74 [RFC7483] are officially defined with English prose. Those 75 definitions contain imprecise or ambiguous JSON structures and 76 require lengthy, tedious examples in the attempt to offer 77 clarification. The English prose can be difficult for non-native 78 English readers, and the examples create their own confusion. 80 This document describes the JSON found in RDAP with JSON Content 81 Rules [I-D.newton-json-content-rules] (JCR). 83 JCR overcomes some of the obstacles of describing JSON with English 84 prose, reducing the tediousness of the prose and accompanying lengthy 85 examples to understandable data structures. Additionally, JCR has 86 mechanisms which can be used by software developers to create test 87 harnesses and technology compatibility kits. 89 Though this document describes all of the JSON found in [RFC7483], it 90 presents the structures in a different order. The rules defined here 91 use the JCR mixin style of specification, where common structures are 92 defined in group rules instead of separately, distinct objects. 94 2. Response 96 [RFC7483] describes ten distinct JSON response: five entity class 97 response, an error response, a help response, and three search 98 responses. 100 $entity_response = @{root} { $response_mixin, 101 $entity_mixin } 103 $nameserver_response = @{root} { $response_mixin, 104 $nameserver_mixin } 106 $domain_response = @{root} { $response_mixin, 107 $domain_mixin } 109 $network_response = @{root} { $response_mixin, 110 $network_mixin } 112 $autnum_response = @{root} { $response_mixin, 113 $autnum_mixin } 115 $error_response = @{root} { $response_mixin, 116 $error_mixin } 118 $help_response = @{root} { $response_mixin } 120 $domainSearch_response = @{root} { $response_mixin, 121 $domainSearchResult } 123 $nameserverSearch_response = @{root} { $response_mixin, 124 $nameserverSearchResult } 126 $entitySearch_response = @{root} { $response_mixin, 127 $entitySearchResult } 129 All of the responses have a common set of object members described by 130 response_mixin. 132 $response_mixin = ( 133 $rdapConformance ?, 134 "notices" : $notices ?, 135 $lang 136 ) 138 3. Object Classes 140 The primary data structures in RDAP are called object classes. These 141 are first order object instances with identifiers. They are JSON 142 objects which contain other JSON data types. 144 3.1. Entity Object Class 146 The Entity object class represents persons or organizations. It 147 incorporates jCard [RFC7095] (vCard in JSON) for contact information. 148 The rules supplied here only provide for a basic validation of jCard, 149 as the validation of jCard is beyond the scope of this document. 151 $entities = "entities" : [ $entity_oc * ] 153 $entity_oc = { 154 $entity_mixin 155 } 157 $entity_mixin = ( 158 "objectClassName" : "entity", 159 $common_mixin, 160 "vcardArray" : [ "vcard", [ $vcard * ] ] ?, 161 "asEventActor" : [ $event * ] ?, 162 "roles" : [ string * ] ?, 163 $publicIds ?, 164 $entities ?, 165 "networks" : [ $network_oc * ] ?, 166 "autnums" : [ $autnum_oc * ] ? 167 ) 169 $vcard = @{unordered} [ 170 [ "version", {}, "text", "4.0" ], 171 [ "fn", {}, "text", string ], 172 [ string, 173 { /.*/:any * }, 174 "text", 175 ( string | [ string * ] ) 176 ] * 177 ] 179 3.2. Nameserver Object Class 181 The nameserver object class represents DNS nameservers in registries. 183 $nameservers = "nameservers" : [ $nameserver_oc * ] 185 $nameserver_oc = { 186 $nameserver_mixin 187 } 189 $nameserver_mixin = ( 190 "objectClassName" : "nameserver", 191 $common_mixin, 192 "ldhName" : fqdn, 193 "unicodeName" : idn ?, 194 "ipAddresses" : { "v4" : [ ipv4 ? ] ?, "ip6" : [ ipv6 ? ] ? } ?, 195 $entities ? 196 ) 198 3.3. Domain Object Class 200 The Domain object class is the most complex of all the object classes 201 defined in RDAP. It represents both forward and reverse DNS 202 delegations. It's complexity is mostly due to the DNSSEC provisions 203 of the object class. 205 $domain_oc = { 206 $domain_mixin 207 } 209 $domain_mixin = ( 210 "objectClassName" : "domain", 211 $common_mixin, 212 "ldhName" : fqdn, 213 "unicodeName" : idn ?, 214 "variants" : [ $variant * ] ?, 215 $nameservers ?, 216 $secureDNS ? 217 ) 219 $variant = { 220 "relation" : [ string * ] ?, 221 "idnTable" : string ?, 222 "variantNames" : [ { "ldhName" : fqdn, "unicodeName" : idn } * ] 223 } 225 $secureDNS = "secureDNS" : { 226 "zoneSigned" : boolean ?, 227 "delegationSigned" : boolean ?, 228 "maxSigLife" : integer ?, 229 "dsData" : [ $dsData_obj * ] ?, 230 "keyData" : [ $keyData_obj * ] ?, 231 $entities ?, 232 $publicIds ?, 233 "network" : $network_oc ? 234 } 236 $dsData_obj = { 237 "keyTag" : integer, 238 "algorithm" : integer, 239 "digest" : string, 240 "digestType" : integer, 241 $events ?, 242 $links ? 243 } 245 $keyData_obj = { 246 "flags" : integer, 247 "protocol" : integer, 248 "publicKey" : string, 249 "algorithm" : integer, 250 $events ?, 251 $links ? 252 } 254 3.4. IP Network Object Class 256 The IP Network object class represents IP network registrations in 257 RIRs. 259 $network_oc = { 260 $network_mixin 261 } 263 $network_mixin = ( 264 "objectClassName" : "ip network", 265 $common_mixin, 266 "startAddress" : ( ipv4 | ipv6 ) ?, 267 "endAddres" : ( ipv4 | ipv6 ) ?, 268 "ipVersion" : ( "v4" | "v6" ) ?, 269 "name" : string ?, 270 "type" : string ?, 271 "country" : /[A-Z]{2}/ ?, 272 "parentHandle" : string ?, 273 $entities ? 274 ) 276 3.5. Autnum Object Class 278 The Autnum object class represents an autonomous system number or 279 blocks of autonomous system numbers in an RIR. 281 $autnum_oc = { 282 $autnum_mixin 283 } 285 $autnum_mixin = ( 286 "objectClassName" : "autnum", 287 $common_mixin, 288 "startAutnum" : int32 ?, 289 "endAutnum" : int32 ?, 290 "name" : string ?, 291 "type" : string ?, 292 $entities ? 293 ) 295 4. Search Results 297 Search results in RDAP are merely arrays of object classes. 299 $domainSearchResult = "domainSearchResult" : [ $domain_oc * ] 300 $nameserverSearchResult = "nameserverSearchResult" : [ $nameserver_oc * ] 301 $entitySearchResult = "entitySearchResult" : [ $entity_oc * ] 302 5. Common Structures 304 Section 4 of [RFC7483] describes eight common structures used 305 throughout the JSON in RDAP. 307 Most of these common structures are grouped together in a rule called 308 common_mixin. 310 $common_mixin = ( 311 "handle" : string ?, 312 "remarks" : [ $notice * ] ?, 313 $links, 314 $events ?, 315 $status ?, 316 $port43 ?, 317 $lang 318 ) 320 5.1. RDAP Conformance 322 The rdapConformance array is the versioning and capabilities 323 negotiation mechanism of RDAP. 325 $rdapConformance = "rdapConformance" : [ string * ] 327 5.2. Links 329 Structures in RDAP may link to information in other data systems 330 using links. Additionally, RDAP uses "self" links to identify 331 instances of RDAP object classes. The data found in each link is 332 described by [RFC5988]. 334 RDAP links are an array of distinct objects, each representing a 335 separate link. 337 $links = ( "links" : [ $link * ] ? ) 339 $link = { 340 "value" : uri ?, 341 "rel" : string ?, 342 "href" : uri, 343 "hreflang" : [ $lang_value * ] ?, 344 "title" : string ?, 345 "media" : string ?, 346 "type" : /[a-zA-Z][a-zA-Z0-9]*\/[a-zA-Z][a-zA-Z0-9]*/ ? 347 } 349 5.3. Notices And Remarks 351 In RDAP, notices and remarks share the same structure. The 352 difference is that notices are meta-data regarding the entirety of a 353 response whereas remarks are meta-data covering a specific instance 354 of an object class. 356 $notices = [ $notice * ] 358 $notice = { 359 "title" : string ?, 360 "description" : [ string * ], 361 "type" : string ?, 362 $links, 363 $lang 364 } 366 5.4. Language Identifier 368 The "lang" member occurs many RDAP data structures. And the same 369 construct is used in the links structures. 371 $lang_value =: /[a-z]{2}(\-[A-Z][a-zA-Z]*(\-[A-Z]{2})?)?/ 372 $lang = ( "lang" : $lang_value ? ) 374 5.5. Events 376 RDAP events note when a specific action has occured on an object 377 instance, and by whom. The same structure appears in all object 378 classes, as well as being re-used by entities embedded by other 379 objects. 381 $events = "events" : [ $event * ] 383 $event = { 384 "eventAction" : string, 385 "eventActor" : string ?, 386 "eventDate" : datetime, 387 $links, 388 $lang 389 } 391 5.6. Status 393 The status of RDAP object instances is indicated by an array of 394 strings, where the value of the strings are registered in an IANA 395 registry. 397 $status = "status" : [ string * ] 399 5.7. Port 43 401 RDAP object classes reference their corresponding Whois 402 representation using the "port43" object member. This is simply a 403 string holding the hostname of the Whois service. 405 $port43 = "port43" : string 407 5.8. Public IDs 409 Some RDAP services are required to identify entities and domains by 410 public identifiers, such as ICANN Registrar IDs. The publicIds 411 object member is an array of objects to represent these identifiers. 413 $publicIds = "publicIds" : [ $publicId * ] 415 $publicId = { 416 "type" : string, 417 "identifier" : string 418 } 420 6. Complete JCR for RDAP 422 The following is the complete ruleset of JSON Content Rules for RDAP. 424 ; 425 ; The various types of responses 426 ; 428 $entity_response = @{root} { $response_mixin, 429 $entity_mixin } 431 $nameserver_response = @{root} { $response_mixin, 432 $nameserver_mixin } 434 $domain_response = @{root} { $response_mixin, 435 $domain_mixin } 437 $network_response = @{root} { $response_mixin, 438 $network_mixin } 440 $autnum_response = @{root} { $response_mixin, 441 $autnum_mixin } 443 $error_response = @{root} { $response_mixin, 444 $error_mixin } 446 $help_response = @{root} { $response_mixin } 448 $domainSearch_response = @{root} { $response_mixin, 449 $domainSearchResult } 451 $nameserverSearch_response = @{root} { $response_mixin, 452 $nameserverSearchResult } 454 $entitySearch_response = @{root} { $response_mixin, 455 $entitySearchResult } 457 $response_mixin = ( 458 $rdapConformance ?, 459 "notices" : $notices ?, 460 $lang 461 ) 463 ; 464 ; RFC 7483 Section 4.1 - RDAP Conformance 465 ; 467 $rdapConformance = "rdapConformance" : [ string * ] 469 ; 470 ; RFC 7483 Section 4.2 - Links 471 ; 473 $links = ( "links" : [ $link * ] ? ) 475 ; see RFC 5988 476 $link = { 477 "value" : uri ?, 478 "rel" : string ?, 479 "href" : uri, 480 "hreflang" : [ $lang_value * ] ?, 481 "title" : string ?, 482 "media" : string ?, 483 "type" : /[a-zA-Z][a-zA-Z0-9]*\/[a-zA-Z][a-zA-Z0-9]*/ ? 484 } 486 ; 487 ; RFC 7483 Section 4.3 - Notices 488 ; 490 $notices = [ $notice * ] 492 $notice = { 493 "title" : string ?, 494 "description" : [ string * ], 495 "type" : string ?, 496 $links, 497 $lang 498 } 500 ; 501 ; RFC 7483 Section 4.4 - Language Identifier 502 ; 504 $lang_value =: /[a-z]{2}(\-[A-Z][a-zA-Z]*(\-[A-Z]{2})?)?/ 505 $lang = ( "lang" : $lang_value ? ) 507 ; 508 ; RFC 7483 Section 4.5 - Events 509 ; 511 $events = "events" : [ $event * ] 513 $event = { 514 "eventAction" : string, 515 "eventActor" : string ?, 516 "eventDate" : datetime, 517 $links, 518 $lang 519 } 521 ; 522 ; RFC 7483 Section 4.6 - Status 523 ; 525 $status = "status" : [ string * ] 527 ; 528 ; RFC 7483 Section 4.7 - Port43 529 ; 531 $port43 = "port43" : string 533 ; 534 ; RFC 7482 Section 4.8 - Public Ids 535 ; 537 $publicIds = "publicIds" : [ $publicId * ] 539 $publicId = { 540 "type" : string, 541 "identifier" : string 543 } 545 ; 546 ; Common Object Class Structures 547 ; 549 $common_mixin = ( 550 "handle" : string ?, 551 "remarks" : [ $notice * ] ?, 552 $links, 553 $events ?, 554 $status ?, 555 $port43 ?, 556 $lang 557 ) 559 ; 560 ; RFC 7483 Section 5.1 - Entity Object Class 561 ; 563 $entities = "entities" : [ $entity_oc * ] 565 $entity_oc = { 566 $entity_mixin 567 } 569 $entity_mixin = ( 570 "objectClassName" : "entity", 571 $common_mixin, 572 "vcardArray" : [ "vcard", [ $vcard * ] ] ?, 573 "asEventActor" : [ $event * ] ?, 574 "roles" : [ string * ] ?, 575 $publicIds ?, 576 $entities ?, 577 "networks" : [ $network_oc * ] ?, 578 "autnums" : [ $autnum_oc * ] ? 579 ) 581 ; See RFC 7095 582 $vcard = @{unordered} [ 583 [ "version", {}, "text", "4.0" ], 584 [ "fn", {}, "text", string ], 585 [ string, 586 { /.*/:any * }, 587 "text", 588 ( string | [ string * ] ) 589 ] * 590 ] 591 ; 592 ; RFC 7483 Section 5.2 - Nameserver Object Class 593 ; 595 $nameservers = "nameservers" : [ $nameserver_oc * ] 597 $nameserver_oc = { 598 $nameserver_mixin 599 } 601 $nameserver_mixin = ( 602 "objectClassName" : "nameserver", 603 $common_mixin, 604 "ldhName" : fqdn, 605 "unicodeName" : idn ?, 606 "ipAddresses" : { "v4" : [ ipv4 ? ] ?, "ip6" : [ ipv6 ? ] ? } ?, 607 $entities ? 608 ) 610 ; 611 ; RFC 7483 Section 5.3 - Domain Object Class 612 ; 614 $domain_oc = { 615 $domain_mixin 616 } 618 $domain_mixin = ( 619 "objectClassName" : "domain", 620 $common_mixin, 621 "ldhName" : fqdn, 622 "unicodeName" : idn ?, 623 "variants" : [ $variant * ] ?, 624 $nameservers ?, 625 $secureDNS ? 626 ) 628 $variant = { 629 "relation" : [ string * ] ?, 630 "idnTable" : string ?, 631 "variantNames" : [ { "ldhName" : fqdn, "unicodeName" : idn } * ] 632 } 634 $secureDNS = "secureDNS" : { 635 "zoneSigned" : boolean ?, 636 "delegationSigned" : boolean ?, 637 "maxSigLife" : integer ?, 638 "dsData" : [ $dsData_obj * ] ?, 639 "keyData" : [ $keyData_obj * ] ?, 640 $entities ?, 641 $publicIds ?, 642 "network" : $network_oc ? 643 } 645 $dsData_obj = { 646 "keyTag" : integer, 647 "algorithm" : integer, 648 "digest" : string, 649 "digestType" : integer, 650 $events ?, 651 $links ? 652 } 654 $keyData_obj = { 655 "flags" : integer, 656 "protocol" : integer, 657 "publicKey" : string, 658 "algorithm" : integer, 659 $events ?, 660 $links ? 661 } 663 ; 664 ; RFC 7483 Section 5.4 - IP Network Object Class 665 ; 667 $network_oc = { 668 $network_mixin 669 } 671 $network_mixin = ( 672 "objectClassName" : "ip network", 673 $common_mixin, 674 "startAddress" : ( ipv4 | ipv6 ) ?, 675 "endAddres" : ( ipv4 | ipv6 ) ?, 676 "ipVersion" : ( "v4" | "v6" ) ?, 677 "name" : string ?, 678 "type" : string ?, 679 "country" : /[A-Z]{2}/ ?, 680 "parentHandle" : string ?, 681 $entities ? 682 ) 684 ; 685 ; RFC 7483 Section 5.5 - Autnum Object Class 686 ; 687 $autnum_oc = { 688 $autnum_mixin 689 } 691 $autnum_mixin = ( 692 "objectClassName" : "autnum", 693 $common_mixin, 694 "startAutnum" : int32 ?, 695 "endAutnum" : int32 ?, 696 "name" : string ?, 697 "type" : string ?, 698 $entities ? 699 ) 701 ; 702 ; RFC 7483 Section 6 - Error 703 ; 705 $error_mixin = ( 706 "errorCode" : integer, 707 "title" : string ?, 708 "description" : [ string * ] ? 709 ) 711 ; 712 ; RFC 7483 Section 8 - Search Results 713 ; 715 $domainSearchResult = "domainSearchResult" : [ $domain_oc * ] 716 $nameserverSearchResult = "nameserverSearchResult" : [ $nameserver_oc * ] 717 $entitySearchResult = "entitySearchResult" : [ $entity_oc * ] 719 Complete JSON Content Rules for RDAP 721 7. Normative References 723 [I-D.newton-json-content-rules] 724 Newton, A. and P. Cordell, "A Language for Rules 725 Describing JSON Content", draft-newton-json-content- 726 rules-09 (work in progress), September 2017. 728 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 729 DOI 10.17487/RFC5988, October 2010, 730 . 732 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 733 DOI 10.17487/RFC7095, January 2014, 734 . 736 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 737 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 738 2014, . 740 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 741 Registration Data Access Protocol (RDAP)", RFC 7483, 742 DOI 10.17487/RFC7483, March 2015, 743 . 745 Author's Address 747 Andrew Lee Newton 748 American Registry for Internet Numbers 749 PO Box 232290 750 Centerville, VA 20120 751 US 753 Email: andy@arin.net 754 URI: http://www.arin.net