idnits 2.17.1 draft-newton-rdap-jcr-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document is more than 15 pages and seems to lack a Table of Contents. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a 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 21, 2016) is 2774 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) == Outdated reference: A later version (-09) exists of draft-newton-json-content-rules-07 Summary: 7 errors (**), 0 flaws (~~), 2 warnings (==), 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 21, 2016 5 Expires: March 25, 2017 7 A Description of RDAP JSON Messages Using JSON Content Rules 8 draft-newton-rdap-jcr-02 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 http://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 March 25, 2017. 32 Copyright Notice 34 Copyright (c) 2016 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 (http://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 1. Introduction 49 The JSON [RFC7159] responses of the Registration Data Access Protocol 50 [RFC7483] are officially defined with English prose. Those 51 definitions contain imprecise or ambiguous JSON structures and 52 require lengthy, tedious examples in the attempt to offer 53 clarification. The English prose can be difficult for non-native 54 English readers, and the examples create their own confusion. 56 This document describes the JSON found in RDAP with JSON Content 57 Rules [I-D.newton-json-content-rules] (JCR). 59 JCR overcomes some of the obstacles of describing JSON with English 60 prose, reducing the tediousness of the prose and accompanying lengthy 61 examples to understandable data structures. Additionally, JCR has 62 mechanisms which can be used by software developers to create test 63 harnesses and technology compatibility kits. 65 Though this document describes all of the JSON found in [RFC7483], it 66 presents the structures in a different order. The rules defined here 67 use the JCR mixin style of specification, where common structures are 68 defined in group rules instead of separately, distinct objects. 70 2. Response 72 [RFC7483] describes ten distinct JSON response: five entity class 73 response, an error response, a help response, and three search 74 responses. 76 $entity_response = @{root} { $response_mixin, 77 $entity_mixin } 79 $nameserver_response = @{root} { $response_mixin, 80 $nameserver_mixin } 82 $domain_response = @{root} { $response_mixin, 83 $domain_mixin } 85 $network_response = @{root} { $response_mixin, 86 $network_mixin } 88 $autnum_response = @{root} { $response_mixin, 89 $autnum_mixin } 91 $error_response = @{root} { $response_mixin, 92 $error_mixin } 94 $help_response = @{root} { $response_mixin } 96 $domainSearch_response = @{root} { $response_mixin, 97 $domainSearchResult } 99 $nameserverSearch_response = @{root} { $response_mixin, 100 $nameserverSearchResult } 102 $entitySearch_response = @{root} { $response_mixin, 103 $entitySearchResult } 105 All of the responses have a common set of object members described by 106 response_mixin. 108 $response_mixin = ( 109 $rdapConformance ?, 110 "notices" : $notices ?, 111 $lang 112 ) 114 3. Object Classes 116 The primary data structures in RDAP are called object classes. These 117 are first order object instances with identifiers. They are JSON 118 objects which contain other JSON data types. 120 3.1. Entity Object Class 122 The Entity object class represents persons or organizations. It 123 incorporates jCard [RFC7095] (vCard in JSON) for contact information. 124 The rules supplied here only provide for a basic validation of jCard, 125 as the validation of jCard is beyond the scope of this document. 127 $entities = "entities" : [ $entity_oc * ] 129 $entity_oc = { 130 $entity_mixin 131 } 133 $entity_mixin = ( 134 "objectClassName" : "entity", 135 $common_mixin, 136 "vcardArray" : [ "vcard", [ $vcard * ] ] ?, 137 "asEventActor" : [ $event * ] ?, 138 "roles" : [ string * ] ?, 139 $publicIds ?, 140 $entities ?, 141 "networks" : [ $network_oc * ] ?, 142 "autnums" : [ $autnum_oc * ] ? 143 ) 145 $vcard = @{unordered} [ 146 [ "version", {}, "text", "4.0" ], 147 [ "fn", {}, "text", string ], 148 [ string, 149 { /.*/:any * }, 150 "text", 151 ( string | [ string * ] ) 152 ] * 153 ] 155 3.2. Nameserver Object Class 157 The nameserver object class represents DNS nameservers in registries. 159 $nameservers = "nameservers" : [ $nameserver_oc * ] 161 $nameserver_oc = { 162 $nameserver_mixin 163 } 165 $nameserver_mixin = ( 166 "objectClassName" : "nameserver", 167 $common_mixin, 168 "ldhName" : fqdn, 169 "unicodeName" : idn ?, 170 "ipAddresses" : { "v4" : [ ipv4 ? ] ?, "ip6" : [ ipv6 ? ] ? } ?, 171 $entities ? 172 ) 174 3.3. Domain Object Class 176 The Domain object class is the most complex of all the object classes 177 defined in RDAP. It represents both forward and reverse DNS 178 delegations. It's complexity is mostly due to the DNSSEC provisions 179 of the object class. 181 $domain_oc = { 182 $domain_mixin 183 } 185 $domain_mixin = ( 186 "objectClassName" : "domain", 187 $common_mixin, 188 "ldhName" : fqdn, 189 "unicodeName" : idn ?, 190 "variants" : [ $variant * ] ?, 191 $nameservers ?, 192 $secureDNS ? 193 ) 195 $variant = { 196 "relation" : [ string * ] ?, 197 "idnTable" : string ?, 198 "variantNames" : [ { "ldhName" : fqdn, "unicodeName" : idn } * ] 199 } 201 $secureDNS = "secureDNS" : { 202 "zoneSigned" : boolean ?, 203 "delegationSigned" : boolean ?, 204 "maxSigLife" : integer ?, 205 "dsData" : [ $dsData_obj * ] ?, 206 "keyData" : [ $keyData_obj * ] ?, 207 $entities ?, 208 $publicIds ?, 209 "network" : $network_oc ? 210 } 212 $dsData_obj = { 213 "keyTag" : integer, 214 "algorithm" : integer, 215 "digest" : string, 216 "digestType" : integer, 217 $events ?, 218 $links ? 219 } 221 $keyData_obj = { 222 "flags" : integer, 223 "protocol" : integer, 224 "publicKey" : string, 225 "algorithm" : integer, 226 $events ?, 227 $links ? 228 } 230 3.4. IP Network Object Class 232 The IP Network object class represents IP network registrations in 233 RIRs. 235 $network_oc = { 236 $network_mixin 237 } 239 $network_mixin = ( 240 "objectClassName" : "ip network", 241 $common_mixin, 242 "startAddress" : ( ipv4 | ipv6 ) ?, 243 "endAddres" : ( ipv4 | ipv6 ) ?, 244 "ipVersion" : ( "v4" | "v6" ) ?, 245 "name" : string ?, 246 "type" : string ?, 247 "country" : /[A-Z]{2}/ ?, 248 "parentHandle" : string ?, 249 $entities ? 250 ) 252 3.5. Autnum Object Class 254 The Autnum object class represents an autonomous system number or 255 blocks of autonomous system numbers in an RIR. 257 $autnum_oc = { 258 $autnum_mixin 259 } 261 $autnum_mixin = ( 262 "objectClassName" : "autnum", 263 $common_mixin, 264 "startAutnum" : int32 ?, 265 "endAutnum" : int32 ?, 266 "name" : string ?, 267 "type" : string ?, 268 $entities ? 269 ) 271 4. Search Results 273 Search results in RDAP are merely arrays of object classes. 275 $domainSearchResult = "domainSearchResult" : [ $domain_oc * ] 276 $nameserverSearchResult = "nameserverSearchResult" : [ $nameserver_oc * ] 277 $entitySearchResult = "entitySearchResult" : [ $entity_oc * ] 278 5. Common Structures 280 Section 4 of [RFC7483] describes eight common structures used 281 throughout the JSON in RDAP. 283 Most of these common structures are grouped together in a rule called 284 common_mixin. 286 $common_mixin = ( 287 "handle" : string ?, 288 "remarks" : [ $notice * ] ?, 289 $links, 290 $events ?, 291 $status ?, 292 $port43 ?, 293 $lang 294 ) 296 5.1. RDAP Conformance 298 The rdapConformance array is the versioning and capabilities 299 negotiation mechanism of RDAP. 301 $rdapConformance = "rdapConformance" : [ string * ] 303 5.2. Links 305 Structures in RDAP may link to information in other data systems 306 using links. Additionally, RDAP uses "self" links to identify 307 instances of RDAP object classes. The data found in each link is 308 described by [RFC5988]. 310 RDAP links are an array of distinct objects, each representing a 311 separate link. 313 $links = ( "links" : [ $link * ] ? ) 315 $link = { 316 "value" : uri ?, 317 "rel" : string ?, 318 "href" : uri, 319 "hreflang" : [ $lang_value * ] ?, 320 "title" : string ?, 321 "media" : string ?, 322 "type" : /[a-zA-Z][a-zA-Z0-9]*\/[a-zA-Z][a-zA-Z0-9]*/ ? 323 } 325 5.3. Notices And Remarks 327 In RDAP, notices and remarks share the same structure. The 328 difference is that notices are meta-data regarding the entirety of a 329 response whereas remarks are meta-data covering a specific instance 330 of an object class. 332 $notices = [ $notice * ] 334 $notice = { 335 "title" : string ?, 336 "description" : [ string * ], 337 "type" : string ?, 338 $links, 339 $lang 340 } 342 5.4. Language Identifier 344 The "lang" member occurs many RDAP data structures. And the same 345 construct is used in the links structures. 347 $lang_value =: /[a-z]{2}(\-[A-Z][a-zA-Z]*(\-[A-Z]{2})?)?/ 348 $lang = ( "lang" : $lang_value ? ) 350 5.5. Events 352 RDAP events note when a specific action has occured on an object 353 instance, and by whom. The same structure appears in all object 354 classes, as well as being re-used by entities embedded by other 355 objects. 357 $events = "events" : [ $event * ] 359 $event = { 360 "eventAction" : string, 361 "eventActor" : string ?, 362 "eventDate" : datetime, 363 $links, 364 $lang 365 } 367 5.6. Status 369 The status of RDAP object instances is indicated by an array of 370 strings, where the value of the strings are registered in an IANA 371 registry. 373 $status = "status" : [ string * ] 375 5.7. Port 43 377 RDAP object classes reference their corresponding Whois 378 representation using the "port43" object member. This is simply a 379 string holding the hostname of the Whois service. 381 $port43 = "port43" : string 383 5.8. Public IDs 385 Some RDAP services are required to identify entities and domains by 386 public identifiers, such as ICANN Registrar IDs. The publicIds 387 object member is an array of objects to represent these identifiers. 389 $publicIds = "publicIds" : [ $publicId * ] 391 $publicId = { 392 "type" : string, 393 "identifier" : string 394 } 396 6. Complete JCR for RDAP 398 The following is the complete ruleset of JSON Content Rules for RDAP. 400 ; 401 ; The various types of responses 402 ; 404 $entity_response = @{root} { $response_mixin, 405 $entity_mixin } 407 $nameserver_response = @{root} { $response_mixin, 408 $nameserver_mixin } 410 $domain_response = @{root} { $response_mixin, 411 $domain_mixin } 413 $network_response = @{root} { $response_mixin, 414 $network_mixin } 416 $autnum_response = @{root} { $response_mixin, 417 $autnum_mixin } 419 $error_response = @{root} { $response_mixin, 420 $error_mixin } 422 $help_response = @{root} { $response_mixin } 424 $domainSearch_response = @{root} { $response_mixin, 425 $domainSearchResult } 427 $nameserverSearch_response = @{root} { $response_mixin, 428 $nameserverSearchResult } 430 $entitySearch_response = @{root} { $response_mixin, 431 $entitySearchResult } 433 $response_mixin = ( 434 $rdapConformance ?, 435 "notices" : $notices ?, 436 $lang 437 ) 439 ; 440 ; RFC 7483 Section 4.1 - RDAP Conformance 441 ; 443 $rdapConformance = "rdapConformance" : [ string * ] 445 ; 446 ; RFC 7483 Section 4.2 - Links 447 ; 449 $links = ( "links" : [ $link * ] ? ) 451 ; see RFC 5988 452 $link = { 453 "value" : uri ?, 454 "rel" : string ?, 455 "href" : uri, 456 "hreflang" : [ $lang_value * ] ?, 457 "title" : string ?, 458 "media" : string ?, 459 "type" : /[a-zA-Z][a-zA-Z0-9]*\/[a-zA-Z][a-zA-Z0-9]*/ ? 460 } 462 ; 463 ; RFC 7483 Section 4.3 - Notices 464 ; 466 $notices = [ $notice * ] 468 $notice = { 469 "title" : string ?, 470 "description" : [ string * ], 471 "type" : string ?, 472 $links, 473 $lang 474 } 476 ; 477 ; RFC 7483 Section 4.4 - Language Identifier 478 ; 480 $lang_value =: /[a-z]{2}(\-[A-Z][a-zA-Z]*(\-[A-Z]{2})?)?/ 481 $lang = ( "lang" : $lang_value ? ) 483 ; 484 ; RFC 7483 Section 4.5 - Events 485 ; 487 $events = "events" : [ $event * ] 489 $event = { 490 "eventAction" : string, 491 "eventActor" : string ?, 492 "eventDate" : datetime, 493 $links, 494 $lang 495 } 497 ; 498 ; RFC 7483 Section 4.6 - Status 499 ; 501 $status = "status" : [ string * ] 503 ; 504 ; RFC 7483 Section 4.7 - Port43 505 ; 507 $port43 = "port43" : string 509 ; 510 ; RFC 7482 Section 4.8 - Public Ids 511 ; 513 $publicIds = "publicIds" : [ $publicId * ] 515 $publicId = { 516 "type" : string, 517 "identifier" : string 519 } 521 ; 522 ; Common Object Class Structures 523 ; 525 $common_mixin = ( 526 "handle" : string ?, 527 "remarks" : [ $notice * ] ?, 528 $links, 529 $events ?, 530 $status ?, 531 $port43 ?, 532 $lang 533 ) 535 ; 536 ; RFC 7483 Section 5.1 - Entity Object Class 537 ; 539 $entities = "entities" : [ $entity_oc * ] 541 $entity_oc = { 542 $entity_mixin 543 } 545 $entity_mixin = ( 546 "objectClassName" : "entity", 547 $common_mixin, 548 "vcardArray" : [ "vcard", [ $vcard * ] ] ?, 549 "asEventActor" : [ $event * ] ?, 550 "roles" : [ string * ] ?, 551 $publicIds ?, 552 $entities ?, 553 "networks" : [ $network_oc * ] ?, 554 "autnums" : [ $autnum_oc * ] ? 555 ) 557 ; See RFC 7095 558 $vcard = @{unordered} [ 559 [ "version", {}, "text", "4.0" ], 560 [ "fn", {}, "text", string ], 561 [ string, 562 { /.*/:any * }, 563 "text", 564 ( string | [ string * ] ) 565 ] * 566 ] 567 ; 568 ; RFC 7483 Section 5.2 - Nameserver Object Class 569 ; 571 $nameservers = "nameservers" : [ $nameserver_oc * ] 573 $nameserver_oc = { 574 $nameserver_mixin 575 } 577 $nameserver_mixin = ( 578 "objectClassName" : "nameserver", 579 $common_mixin, 580 "ldhName" : fqdn, 581 "unicodeName" : idn ?, 582 "ipAddresses" : { "v4" : [ ipv4 ? ] ?, "ip6" : [ ipv6 ? ] ? } ?, 583 $entities ? 584 ) 586 ; 587 ; RFC 7483 Section 5.3 - Domain Object Class 588 ; 590 $domain_oc = { 591 $domain_mixin 592 } 594 $domain_mixin = ( 595 "objectClassName" : "domain", 596 $common_mixin, 597 "ldhName" : fqdn, 598 "unicodeName" : idn ?, 599 "variants" : [ $variant * ] ?, 600 $nameservers ?, 601 $secureDNS ? 602 ) 604 $variant = { 605 "relation" : [ string * ] ?, 606 "idnTable" : string ?, 607 "variantNames" : [ { "ldhName" : fqdn, "unicodeName" : idn } * ] 608 } 610 $secureDNS = "secureDNS" : { 611 "zoneSigned" : boolean ?, 612 "delegationSigned" : boolean ?, 613 "maxSigLife" : integer ?, 614 "dsData" : [ $dsData_obj * ] ?, 615 "keyData" : [ $keyData_obj * ] ?, 616 $entities ?, 617 $publicIds ?, 618 "network" : $network_oc ? 619 } 621 $dsData_obj = { 622 "keyTag" : integer, 623 "algorithm" : integer, 624 "digest" : string, 625 "digestType" : integer, 626 $events ?, 627 $links ? 628 } 630 $keyData_obj = { 631 "flags" : integer, 632 "protocol" : integer, 633 "publicKey" : string, 634 "algorithm" : integer, 635 $events ?, 636 $links ? 637 } 639 ; 640 ; RFC 7483 Section 5.4 - IP Network Object Class 641 ; 643 $network_oc = { 644 $network_mixin 645 } 647 $network_mixin = ( 648 "objectClassName" : "ip network", 649 $common_mixin, 650 "startAddress" : ( ipv4 | ipv6 ) ?, 651 "endAddres" : ( ipv4 | ipv6 ) ?, 652 "ipVersion" : ( "v4" | "v6" ) ?, 653 "name" : string ?, 654 "type" : string ?, 655 "country" : /[A-Z]{2}/ ?, 656 "parentHandle" : string ?, 657 $entities ? 658 ) 660 ; 661 ; RFC 7483 Section 5.5 - Autnum Object Class 662 ; 663 $autnum_oc = { 664 $autnum_mixin 665 } 667 $autnum_mixin = ( 668 "objectClassName" : "autnum", 669 $common_mixin, 670 "startAutnum" : int32 ?, 671 "endAutnum" : int32 ?, 672 "name" : string ?, 673 "type" : string ?, 674 $entities ? 675 ) 677 ; 678 ; RFC 7483 Section 6 - Error 679 ; 681 $error_mixin = ( 682 "errorCode" : integer, 683 "title" : string ?, 684 "description" : [ string * ] ? 685 ) 687 ; 688 ; RFC 7483 Section 8 - Search Results 689 ; 691 $domainSearchResult = "domainSearchResult" : [ $domain_oc * ] 692 $nameserverSearchResult = "nameserverSearchResult" : [ $nameserver_oc * ] 693 $entitySearchResult = "entitySearchResult" : [ $entity_oc * ] 695 Complete JSON Content Rules for RDAP 697 7. Normative References 699 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 701 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 702 January 2014. 704 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 705 Interchange Format", RFC 7159, March 2014. 707 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 708 Registration Data Access Protocol (RDAP)", RFC 7483, DOI 709 10.17487/RFC7483, March 2015, 710 . 712 [I-D.newton-json-content-rules] 713 Newton, A. and P. Cordell, "A Language for Rules 714 Describing JSON Content", draft-newton-json-content- 715 rules-07 (work in progress), September 2016. 717 Author's Address 719 Andrew Lee Newton 720 American Registry for Internet Numbers 721 3635 Concorde Parkway 722 Chantilly, VA 20151 723 US 725 Email: andy@arin.net 726 URI: http://www.arin.net