idnits 2.17.1 draft-newton-json-content-rules-04.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.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 2, 2014) is 3433 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '116' on line 996 -- Looks like a reference, but probably isn't: '943' on line 996 -- Looks like a reference, but probably isn't: '234' on line 996 -- Looks like a reference, but probably isn't: '38793' on line 996 == Missing Reference: 'RFC3912' is mentioned on line 1145, but not defined ** Downref: Normative reference to an Informational RFC: RFC 1166 ** Obsolete normative reference: RFC 4234 (Obsoleted by RFC 5234) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 6 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 December 2, 2014 5 Expires: June 5, 2015 7 A Language for Rules Describing JSON Content 8 draft-newton-json-content-rules-04 10 Abstract 12 This document describes a language useful for describing the expected 13 content of JSON structures found in JSON-using protocols. 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 June 5, 2015. 32 Copyright Notice 34 Copyright (c) 2014 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 goal of this document is to provide a way to specify the expected 50 content of data expressed in JSON [RFC4627] format. That is, the 51 primary purpose of this document is to specify a means for one person 52 to communicate with another person the expected nature of a JSON data 53 structure in a method more concise and unambiguous than prose. The 54 programmatic validation of a JSON data structure against content 55 rules is a lesser goal of this document, though such a practice is 56 useful in both the writing of specifications and the communications 57 of programs. 59 Unlike JSON Schema, this language is not JSON though the syntax 60 described here is "JSON-like" (a comparison with JSON Schema can be 61 found in Appendix A and a "real world" example can be found in 62 Appendix B). A specialized syntax is used to reduce the tedium in 63 reading and writing rules as the complexity describing allowable 64 content is often more involved than most of the actual content. 65 Figure 2 is an example of this language describing the JSON of 66 Figure 1. 68 Example JSON lifted from RFC 4627 70 [ 71 { 72 "precision": "zip", 73 "Latitude": 37.7668, 74 "Longitude": -122.3959, 75 "Address": "", 76 "City": "SAN FRANCISCO", 77 "State": "CA", 78 "Zip": "94107", 79 "Country": "US" 80 }, 81 { 82 "precision": "zip", 83 "Latitude": 37.371991, 84 "Longitude": -122.026020, 85 "Address": "", 86 "City": "SUNNYVALE", 87 "State": "CA", 88 "Zip": "94085", 89 "Country": "US" 90 } 91 ] 93 Figure 1 95 Rules describing Figure 1 97 root [ 98 2*2{ 99 "precision" : string, 100 "Latitude" : float, 101 "Longitude" : float, 102 "Address" : string, 103 "City" : string, 104 "State" : string, 105 "Zip" : string, 106 "Country" : string 107 } 108 ] 110 Figure 2 112 The JSON Content Rules are of five types: 114 o value rules 116 o member rules 118 o array rules 120 o object rules 122 o group rules 124 Each rule has two components, a rule name and a rule definition. 125 Anywhere in a rule definition where a rule name is allowed, another 126 rule definition may be used. 128 This is an example of a value rule: 130 v1 : integer 0..3 132 It specifies a rule named "v1" that has a definition of ": integer 133 0..3" (value rule definitions begin with a ':' character). This 134 defines values of type "v1" to be integers in the range 0 to 3 135 (minimum value of 0, maximum value of 3). Value rules can define the 136 limits of JSON values, such as stating that numbers must fall into a 137 certain range or that strings must be formatted according to certain 138 patterns or standards (i.e. URIs, phone numbers, etc...). 140 Member rules specify JSON object members. The following example 141 member rule states that the rule's name is 'm1' with a value defined 142 by the 'v1' value rule: 144 m1 "m1name" v1 146 Since rule names can be substituted by rule definitions, this member 147 rule can also be written as follows (to define a member rule named m1 148 for JSON member "m1name" that has a value that is an integer between 149 0 and 3): 151 m1 "m1name" : integer 0..3 153 Object rules are composed of member rules, since JSON objects are 154 composed of members. Object rules can specify members that are 155 mandatory, optional, and even choices between members. In this 156 example, the rule 'o1' defines an object that must contain a member 157 as defined by member rule 'm1' and optionally a member defined by the 158 rule 'm2': 160 o1 { m1, ?m2 } 162 Array rules are composed of value, object, and other array rules. 163 Like object rules, array rules can specify the cardinality of the 164 contents of an array. The following array rule defines an array that 165 must contain value rule 'v1' and zero or more objects as defined by 166 rule 'o1': 168 a1 [ v1, *o1 ] 170 Finally, group rules designate a collection of rules. 172 Putting it all together, Figure 4 describes the JSON in Figure 3. 174 Example JSON shamelessly lifted from RFC 4627 176 { 177 "Image": { 178 "Width": 800, 179 "Height": 600, 180 "Title": "View from 15th Floor", 181 "Thumbnail": { 182 "Url": "http://www.example.com/image/481989943", 183 "Height": 125, 184 "Width": "100" 185 }, 186 "IDs": [116, 943, 234, 38793] 187 } 188 } 190 Figure 3 192 Rules describing Figure 3 194 width_v : integer 0..1280 195 height_v : integer 0..1024 197 width "Width" width_v 198 height "Height" height_v 200 thumbnail "Thumbnail" { 201 width, height, "Url" : uri 202 } 204 image "Image" { 205 width, height, "Title" : string, 206 thumbnail, "IDs" [ *: integer ] 207 } 209 root { image } 211 Figure 4 213 The rules from Figure 4 can be written more compactly (see Figure 5). 215 Compact rules describing Figure 3 217 width "Width" : integer 0..1280 218 height "Height" : integer 0..1024 220 root { 221 "Image" { 222 width, height, "Title" :string, 223 "Thumbnail" { width, height, "Url" :uri }, 224 "IDs" [ *:integer ] 225 } 226 } 228 Figure 5 230 2. Lines and Comments 232 There is no statement terminator and therefore no need for a line 233 continuation syntax. Rules may be defined across line boundaries. 234 Blank lines are allowed. 236 Comments are very similar to comments in ABNF [RFC4234]. They start 237 with a semi-colon (';') and continue to the end of the line. 239 3. Rules 241 Rules are composed of two parts, a rule name and a rule definition: 243 245 Rule names allow a rule to be referenced easily by a name. A rule 246 definition describes the validity upon which the content is to be 247 judged. With the exception of value rules, rule definitions refer to 248 other rules using the rule names of other rules of appropriate type. 250 A rule definition may embed another rule definition where a rule name 251 is allowed. In other words, some rules are named and some are 252 anonymous. Named rules start with a rule name and have a rule 253 definition. Anonymous rules are rule definitions embedded in the 254 definitions of other rules. 256 The type of rule to use in a rule definition, either directly or by 257 reference of a name, depends on the type of rule being defined and 258 fall along the structure of allowable JSON grammar: 260 o Since a member of a JSON object can contain a "primitive value", 261 an array, or an object, member rules can be composed of value 262 rules, array rules, and object rules. 264 o JSON objects are composed of members, so object rules can only be 265 composed of member rules. 267 o Finally, as JSON arrays may contain other arrays, objects, and 268 values, array rules may be composed of value rules, object rules, 269 and array rules. 271 A fifth rule type, group rules, exist to help reference a collection 272 of rules. Object rules and array rules may contain group rules so 273 long as the groups contain only the appropriate type of rule of the 274 containing rule. 276 Rule names must start with an alphabetic character (a-z,A-Z) and must 277 contain only alphabetic characters, numeric characters, the hyphen 278 character ('-') and the underscore character ('_'). Rule names must 279 not be used more than once and are case sensitive. 281 3.1. Value Rules 283 Value rules define content for JSON values. JSON allows values to be 284 objects, arrays, numbers, booleans, strings, and null. Arrays and 285 objects are handled by the array and object rules, and the value 286 rules define the rest. 288 3.1.1. Numbers, Booleans and Null 290 The rules for booleans and null are the simplest and take the 291 following forms: 293 rule_name : boolean 295 rule_name : null 297 Rules for numbers can specify the number as either an integer or 298 floating point number and may specify a range: 300 rule_name : integer n..m 302 rule_name : float n..m 304 where n is the minimum allowable value of the number and m is the 305 maximum allowable value of the number. The range doesn't have to be 306 given, but if it is given either the minimum, maximum, or both are 307 required. If the minimum is not given then the minimum is considered 308 to be the minimum number value possible to represent in JSON. 309 Likewise, if the maximum is not given then the maximum is considered 310 to be the maximum number value possible to represent in JSON. 312 3.1.2. Strings 314 String values may be specified generically as: 316 rule_name : string 318 However, the content of strings can be narrowed in the following 319 ways: 321 Regular Expression: A rule can state that a string must match a 322 regular expression by giving the regular expression after the 323 string literal: 325 rule_name : string /regex/ 327 URIs and URI templates: A rule can state that a string must be a 328 URI [RFC3986]: 330 rule_name : uri 332 URIs may be further scoped to a specific URI pattern by prepending 333 a URI template [RFC6570]: 335 rule_name : uri http://{stuff} 336 rule_name : uri http://{authority}/{thing1}?q={thing2} 338 When using URI templates, the variable names are ignored for 339 pattern matching, but the should be provided for construction of a 340 valid URI template. Providing the variable names also aids in the 341 description of what is to be matched. 343 IP Addresses: Narrowing the content of strings down to IP addresses 344 can be done with either the 'ip4' (see [RFC1166]) or 'ip6' (see 345 [RFC5952]) literals: 347 rule_name : ip4 349 rule_name : ip6 351 Domain Names: Fully qualified A-label and U-label domain names can 352 be specified with the 'fqdn' and 'idn' literals: 354 rule_name : fqdn 356 rule_name : idn 358 Dates and Times: Dates and times are specified using the ABNF rules 359 from RFC 3339 [RFC3339] as literals: 361 rule_name : date-time 363 rule_name : full-date 365 rule_name : full-time 367 Email Addresses: A string can be scoped to the syntax of email 368 addresses using the literal 'email': 370 rule_name : email 372 Email addresses must conform to the syntax of RFC 5322 [RFC5322]. 374 Phone Numbers: Strings conforming to E.123 phone number format can 375 be specified as follows: 377 rule_name : phone 379 Base 64: Strings containing base 64 data, as described by RFC 4648 380 [RFC4648], can be specified as follows: 382 rule_name : base64 384 3.1.3. Enumerations 386 Enumerations allow a value to be one of the items in an enumerated 387 list of possible values. They take the following form: 389 rule_name : < "item1" "item2" "item3" > 391 Items in the enumerated list may be quoted strings, integer or 392 floating point numbers, or the literals 'true', 'false' or 'null'. 393 The types of the items may be mixed, as the following example 394 demonstrations: 396 truthy : < 1 true "yes" "Y" > 398 3.2. Member Rules 400 Member rules have the simplest syntax of all the rules and define 401 members of JSON objects. Member rules follow the format: 403 rule_name "member_name" target_rule_name 405 where rule_name is the name of the rule being defined, member_name 406 (in quotes) is the name of the JSON object member, and 407 target_rule_name is a reference to a value rule, array rule, or 408 object rule specifying the allowable content of the JSON object 409 member. 411 Since rule names in rule definitions may be replaced by rule 412 definitions, member rules may also be written in this form: 414 rule_name "member_rule" target_rule_definition 416 The following is an example: 418 location_uri "locationURI" : uri 420 3.3. Object Rules 422 Object rules define the allowable members of a JSON object. Their 423 rule definitions are composed of member rules and group rules. They 424 take the following form: 426 rule_name { member_rule_1, member_rule_2 } 428 The following rule example defines an object composed of two member 429 rules: 431 response { location_uri, status_code } 433 Given that where a rule name is found a rule definition of the 434 appropriate type may be used, the above example might also be 435 written: 437 response { "locationUri" : uri, "statusCode" : integer } 439 Rules given in the rule definition of an object rule do not imply 440 order. Given the example object rule above both 442 { "locationUri" : "http://example.com", "statusCode" : 200 } 444 and 446 { "statusCode" : 200, "locationUri" : "http://example.com" } 448 are JSON objects that match the rule. 450 Member rules or member rule definitions may not be repeated in the 451 rule definition of an object rule. However, a member of an object 452 can be marked as optional if the member rule defining it is preceded 453 by the question mark ('?') character. In the following example, the 454 location_uri member is optional while the status_code member is 455 required to be in the defined object: 457 response { ?location_uri, status_code } 459 An object rule can also define the choice between members by placing 460 the forward slash ('/') character between two member rules. In the 461 following example, the object being defined can have either a 462 location_uri member or content_type member and must have a 463 status_code member: 465 response { location_uri / content_type, status_code } 467 3.4. Array Rules 469 Array rules define the allowable content of JSON arrays. Their rule 470 definitions are composed of value rules, object rules, group rules, 471 and other array rules and have the following form: 473 rulename [ target_rule_name_1, target_rule_name_2 ] 475 The following example defines an array where the first element is 476 defined by the width_value rule and the second element is defined by 477 the height_value rule: 479 size [ width_value, height_value ] 481 Unlike object rules, order is implied by the array rule definition. 482 That is, the first rule referenced or defined within an array rule 483 specifies that the first element of the array will match that rule, 484 the second rule given with the array rule specifies that the second 485 element of the array will match that rule, and so on. 487 Take for example the following array rule definition: 489 person [ : string, : integer ] 491 This JSON array matches the above rule: 493 [ "Bob Smurd", 24 ] 495 while this one does not: 497 [ 24, "Bob Smurd" ] 499 As with object rules, the forward slash character ('/') can be used 500 to indicate a choice between two elements. Take for example the 501 following rules: 503 name_value : string 505 age_value : integer 507 birthdate_value : date-time 509 person [ name_value, age_value / birthdate_vale ] 511 which would validate 513 [ "Bob Smurd", 24 ] 515 or 517 [ "Bob Smurd", "1988-04-12T23:20:50.52Z" ] 519 Repetition of array values may also be specified by preceding a rule 520 with an asterisk ('*') character surrounded by the lower bound and 521 upper bound of the repetition (e.g. "0*1"). The following rules 522 define an array that has between one and three strings: 524 child_value : string 526 children [ 1*3 child_value ] 528 Both the lower bound and the upper bound are optional. If lower 529 bound is not given then it is assumed to be zero. If the upper bound 530 is not given then it is assumed to be infinity. The following 531 example defines an array with an infinite number of child_value 532 defined strings: 534 children [ * child_value ] 536 3.5. Group Rules 538 Unlike the other types of rules, group rules have no direct tie with 539 JSON syntax. Group rules simply group together other rules. They 540 take the form: 542 rule_name ( target_rule_1, target_rule_2 ) 544 Group rule definitions and any nesting of group rule definitions, 545 must conform to the allowable set of rules of the rule containing 546 them. A group rule referenced inside of an array rule may not 547 contain a member rule since member rules are not allowed in array 548 rules directly. Likewise, a group rule referenced inside an object 549 rule must only contain member rules, and once group rules used in an 550 object rule are fully dereferenced there must be no duplicate member 551 rules as member rules in object rules are required to be unique. 553 Take for example the following rules: 555 child_1 "first_child" : string 557 child_2 "second_child" : string 559 child_3 "third_child" : string 561 child_4 "fourth_child" : string 563 first_two_children ( child_1, child_2 ) 565 second_two_children ( child_3, child_4 ) 567 the_children { first_two_children, second_two_children } 569 These rules describe a JSON object that might look like this: 571 { "first_child":"greg", "second_child":"marsha", 572 "third_child":"bobby", "fourth_child":"jan" } 574 Groups can also be used with the choice syntax in member rules. Here 575 the object can either have first_two_children or second_two_children: 577 the_children { first_two_children / second_two_children } 579 and here the object can have second_two_children only if 580 first_two_children are given: 582 the_children { first_two_children & second_two_children } 584 Group rules can be used to create object mixins. In the example in 585 Figure 6, both obj1 and obj2 have a members "foo" and "fob" with obj1 586 having the additional member "bar" and obj2 having the additional 587 member "baz". 589 mixin_group ( "foo" : integer, "fob" : uri ) 591 obj1 { mixin_group, "bar" : string } 593 obj2 { mixin_group, "baz" : string } 595 Figure 6 597 Group rules used in the definition of object rules may be preceded by 598 the '?' character, just as member rules in the definitions of object 599 rules, signifying that the group is optional. 601 response { ?( location_uri, referrer_uri ) } 603 The '?' character may also preceed a rule of the group definition to 604 indicate that the rule is optional if the group rule is contained by 605 an object rule. Therefore, group rules can be used to create member 606 dependencies. This object rule defines that referrer_uri can be 607 present if location_uri is present. 609 response { ?( location_uri, ?referrer_uri ) } 611 When group rules are used in the definition of an array rule, they 612 may be preceded by the repetition syntax of elements of an array 613 definition, and may preceed a rule of the group definition to 614 indicate repetition. 616 orders [ *( 1*5 server, cluster_controller ) ] 618 3.6. Any Value and Any Member 620 It is possible to specify that a value can be of any type allowable 621 by JSON using the any value rule. This is done with the 'any' 622 literal in a value rule: 624 rule_name : any 626 However, unlike other value rules which define primitive data types, 627 this rule defines a value of any kind, either primitive (null, 628 boolean, number, string), object, or array. 630 Use of the any value rule in arrays can be used with repetition to 631 define arrays that may contain any value: 633 any_value : any 635 array_of_any [ *any_value ] 637 Specifying any object member name in a member rule with the any 638 member rule is done by pre-pending a carat character ('^') to an 639 empty member name (that is, ^"" signifies any member name). This has 640 the following form: 642 rule_name ^"" target_rule_name 644 As an example, the following defines an object member with any name 645 that has a value that is a string: 647 user_data ^"" : string 649 Usage of the any member rule must still satisfy the criteria that all 650 member names of an object be unique. 652 Constructing an object member of any name with any type would 653 therefore take the form: 655 rule_name ^"" : any 657 Unlike other types of member rules, it is possible to use repetition 658 with the any member rule in an object rule. The repetition syntax 659 and semantics are the same as the repetition syntax and semantics of 660 repetition with array rules. The following example rules define an 661 object that may contain any number of members where each member may 662 have any value. 664 any_member ^"" : any 666 object_of_anything { *any_member } 668 Use of the repetition of any member rules must satisfy the criteria 669 that all member names of an object be unique. 671 3.7. A Root Rule 673 In some contexts it is necessary that there be a rule that defines 674 the outer most JSON object or array, or if thought of as an inverted 675 object tree the structure at the very top. If in a collection of 676 rules there is no rule explicitly specified for this purpose and a 677 rule named "root" is given, it can be assumed to be the outer most 678 JSON structure or the root of an object/array tree. If a rule is 679 explicitly specified other than "root" and there exists a rule named 680 "root", that rule name holds no special meaning. 682 4. Directives 684 Directives change the interpretation of a collection of rules. They 685 begin with a hash character ('#') and are terminated by the end of a 686 line. They take the following form: 688 # directive_name 690 Directives may have other qualifiers after the directive name. They 691 may appear intermixed with rules but cannot appear in a rule 692 definition. 694 4.1. pedantic 696 This directive specifies that objects with undefined members should 697 not be valid. Without this directive, an object with undefined 698 members will be valid and the undefined members will be ignored. 700 4.2. language-compatible-members 702 This directive specifies that every member name of every object, 703 either explicitly defined or specified via an any member rule or the 704 ignore-unknown-members directive must be a name compatible with 705 programming languages. The intent is to specify object member names 706 that may be promoted to first-order object attributes or methods in 707 an API. The following ABNF describes the restrictions upon the 708 member names: 710 ABNF for programming language compatible JSON names 712 name = ALPHA *( ALPHA / DIGIT / "_" ) 714 Figure 7 716 4.3. include 718 This directive specifies that another collection of rules should be 719 evaluated before the rules following this directive. This directive 720 must be qualified with a URL of a file containing the rules 721 collection. 723 # include http://example.com/rfcXXXX 725 In practice this directive should be accompanied by a comment 726 describing the rules to include. 728 # include http://example.com/rfcXXXX ;Section 3 of RFC XXXX 730 5. ABNF Syntax 732 The following ABNF describes the syntax for JSON Content Rules. 734 grammar = 1*(rule / directive) *c-wsp 736 rule = rulename definition 737 definition = *c-wsp ( value-rule / 738 member-rule / 739 array-rule / 740 object-rule / 741 group-rule ) 743 ; rulenames must be unique, and may not be a reserved word 744 ; rulenames are case sensitive 745 rulename = *c-wsp ALPHA *(ALPHA / DIGIT / "-" / "_") 747 ; Adapted from the ABNF for JSON, RFC 4627 s 2.4 748 float = [ "-" ] int [ frac ] [ exp ] 749 integer = [ "-" ] int [ exp ] 750 exp = ( "e" / "E" ) [ "+" / "-" ] 1*DIGIT 751 frac = "." 1*DIGIT 752 int = "0" / ( %x31-39 *DIGIT ) 754 ; The regex-char rule allows for any sequence of characters, 755 ; including whitespace and newlines, with backslash only 756 ; allowed before either a forward or a backslash. 757 regex-char = %x21-2E / %x30-5D / %x5E-7E / WSP / 758 CR / LF / "\/" / "\\" 760 ; The defintion of a JSON string, from RFC 4627 s 2 761 q-string = %x20-21 / %x23-5B / %x5D-10FFFF / "\" ( 762 %x22 / ; " u+0022 763 %x5C / ; \ u+005C 764 %x2F / ; / u+002F 765 %x62 / ; BS u+0008 766 %x66 / ; FF u+000C 767 %x6E / ; LF u+000A 768 %x72 / ; CR u+000D 769 %x74 / ; HT u+0009 770 ( %x75 4HEXDIG ) ) ; uXXXX u+XXXX 772 enum-items = float / integer / 773 "1" / "0" / "true" / "false" / 774 "null" / 775 q-string 777 boolean-type = "boolean" 778 null-type = "null" 779 integer-type = "integer" [ 1*c-wsp integer ".." integer ] 780 float-type = "float" [ 1*c-wsp float ".." float ] 781 string-type = "string" [ *c-wsp "/" *regex-char "/" ] 782 uri-type = "uri" [ URI ] ; URI defined in RFC 3986 783 ip-type = "ip4" / "ip6" 784 dns-type = "fqdn" / "idn" 785 date-type = "date-time" / "full-date" / "full-time" 786 email-type = "email" 787 phone-type = "phone" 788 base64-type = "base64" 789 enum-type = "<" 1*( 1*c-wsp enum-items) 1*c-wsp ">" 790 any-type = "any" 792 value-rule = ":" *c-wsp type-rule 793 type-rule = boolean-type / 794 null-type / 795 integer-type / 796 float-type / 797 string-type / 798 uri-type / 799 ip-type / 800 dns-type / 801 date-type / 802 email-type / 803 phone-type / 804 base64-type / 805 enum-type / 806 any-type 808 inline-rule = *c-wsp ( rulename / definition ) 810 member-rule = ( 811 ( "^" %x22.22 ) / 812 ( %x22 *q-string %x22 ) 813 ) inline-rule 815 and-or = ( "," / "/" ) 816 object-rule = "{" object-member *( 817 *c-wsp 818 and-or 819 object-member 820 ) *c-wsp "}" 822 object-items = ( rulename / member-rule / group-rule ) 823 object-member = *c-wsp ["?"] *c-wsp object-items 825 array-rule = "[" array-member *( 826 *c-wsp 827 and-or 828 array-member 829 ) *c-wsp "]" 831 array-count = *c-wsp [ 832 [int] 833 *c-wsp 834 "*" 835 *c-wsp 836 [int] 837 *c-wsp 838 ] 839 array-member = array-count ( 840 rulename / 841 value-rule / 842 object-rule / 843 group-rule ) 844 [ *c-wsp "/" array-member ] 846 group-rule = "(" group-member *( 847 1*c-wsp 848 and-or 849 group-member 850 ) *c-wsp ")" 852 group-member = *c-wsp [ ("?" / array-count ] inline-rule 854 directive = *c-wsp "#" *( VCHAR / WSP / %x7F-10FFFF ) EOL 856 ; Taken from the ABNF for ABNF (RFC 4627 section 4) and slightly 857 ; adapted newlines in a c-wsp do not need whitespace at the 858 ; start of a newline to form a valid continuation line, and 859 ; EOL might not be a full CRLF 860 c-wsp = WSP / c-nl 861 c-nl = comment / EOL 862 comment = ";" *(WSP / VCHAR) EOL 863 EOL = 1*( CR / LF ) 865 ; core rules 866 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z 867 CR = %x0D 868 DIGIT = %x30-39 869 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 870 LF = %x0A 871 VCHAR = %x21-7E 872 WSP = SP / HTAB 873 SP = %x20 874 HTAB = %x09 876 JSON Content Rules ABNF 878 6. Acknowledgements 880 Byron Ellacott provided the original ABNF, from which the current 881 ABNF is derived. Andrew Biggs and Paul Jones provided feedback and 882 suggestions which led to many changes in the syntax. 884 7. Normative References 886 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 887 numbers", RFC 1166, July 1990. 889 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 890 Internet: Timestamps", RFC 3339, July 2002. 892 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 893 Resource Identifier (URI): Generic Syntax", STD 66, RFC 894 3986, January 2005. 896 [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 897 Specifications: ABNF", RFC 4234, October 2005. 899 [RFC4627] Crockford, D., "The application/json Media Type for 900 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 902 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 903 Encodings", RFC 4648, October 2006. 905 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 906 October 2008. 908 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 909 Address Text Representation", RFC 5952, August 2010. 911 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 912 and D. Orchard, "URI Template", RFC 6570, March 2012. 914 Appendix A. Comparison with JSON Schema 916 This section compares this specification, JSON Content Rules, with 917 JSON Schema using examples. 919 A.1. Example 1 from RFC 4627 921 Example JSON lifted from RFC 4627 923 [ 924 { 925 "precision": "zip", 926 "Latitude": 37.7668, 927 "Longitude": -122.3959, 928 "Address": "", 929 "City": "SAN FRANCISCO", 930 "State": "CA", 931 "Zip": "94107", 932 "Country": "US" 933 }, 934 { 935 "precision": "zip", 936 "Latitude": 37.371991, 937 "Longitude": -122.026020, 938 "Address": "", 939 "City": "SUNNYVALE", 940 "State": "CA", 941 "Zip": "94085", 942 "Country": "US" 943 } 944 ] 945 JSON Content Rules 947 root [ 948 2*2{ 949 "precision" : string, 950 "Latitude" : float, 951 "Longitude" : float, 952 "Address" : string, 953 "City" : string, 954 "State" : string, 955 "Zip" : string, 956 "Country" : string 957 } 958 ] 960 JSON Schema 962 { 963 "type": "array", 964 "items": [ 965 { 966 "type": "object", 967 "properties": { 968 "precision": { "type": "string", "required": "true" }, 969 "Latitude": { "type": "number", "required": "true" }, 970 "Longitude": { "type": "number", "required": "true" }, 971 "Address" : { "type": "string", "required": "true" }, 972 "City" : { "type": "string", "required": "true" }, 973 "State" : { "type" : "string", "required": "true" }, 974 "Zip" : { "type" : "string", "required": "true" }, 975 "Country" : { "type" : "string", "required": "true" } 976 } 977 } 978 ], 979 "minItems" : 2, 980 "maxItems" : 2 981 } 983 A.2. Example 2 from RFC 4627 984 Example JSON shamelessly lifted from RFC 4627 986 { 987 "Image": { 988 "Width": 800, 989 "Height": 600, 990 "Title": "View from 15th Floor", 991 "Thumbnail": { 992 "Url": "http://www.example.com/image/481989943", 993 "Height": 125, 994 "Width": "100" 995 }, 996 "IDs": [116, 943, 234, 38793] 997 } 998 } 1000 JSON Content Rules 1002 width "width" : integer 0..1280 1003 height "height" : integer 0..1024 1005 root { 1006 "Image" { 1007 width, height, "Title" :string, 1008 "thumbnail" { width, height, "Url" :uri }, 1009 "IDs" [ *:integer ] 1010 } 1011 } 1013 JSON Schema 1015 { 1016 "type" : "object", 1017 "properties" : { 1018 "Image": { 1019 "type" : "object", 1020 "properties" : { 1021 "Width" : { 1022 "type" : "integer", 1023 "minimum" : 0, 1024 "maximum" : 1280, 1025 "required" : "true" 1026 } 1027 "Height" : { 1028 "type" : "integer", 1029 "minimum" : 0, 1030 "maximum" : 1024, 1031 "required" : "true" 1033 } 1034 "Title" : { "type": "string" }, 1035 "Thumbnail" : { 1036 "type" : "object", 1037 "properties" : { 1038 "Url" : { 1039 "type" : "string", 1040 "format" : "uri", 1041 "required" : "true" 1042 }, 1043 "Width" : { 1044 "type" : "integer", 1045 "minimum" : 0, 1046 "maximum" : 1280, 1047 "required" : "true" 1048 }, 1049 "Height" : { 1050 "type" : "integer", 1051 "minimum" : 0, 1052 "maximum" : 1280, 1053 "required" : "true" 1054 } 1055 } 1056 }, 1057 "IDs" : { 1058 "type":"array", 1059 "items":[ { "type": "integer" } ], 1060 "required" : "true" 1061 } 1062 } 1063 } 1064 } 1065 } 1067 Appendix B. A "Real World" Exmaple 1069 The following example is taken from draft-ietf-weirds-json-response- 1070 00. It describes the entity object (Section 4), the nameserver 1071 object (Section 5) and many of the other sub-structures used in 1072 objects defined in other sections of that draft. 1074 JSON Content Rules for nameserver and entity from draft-ietf-weirds- 1075 json-response 1077 # language-compatible-members 1079 ; the nameserver object 1080 ; models nameserver host information 1081 ; this often referred to as 'host' object too 1082 nameserver { 1084 ; the host name of the name server 1085 "name" : fqdn, 1087 ; the ip addresses of the nameserver 1088 "ipAddresses" [ *( :ip4 / :ip6 ) ], 1090 common 1091 } 1093 ; the entity object 1094 ; This object object represents the information of organizations, 1095 ; corporations, governments, non-profits, clubs, individual persons, 1096 ; and informal groups of people. 1097 entity { 1099 ; the names by which the entity is commonly known 1100 "names" [ *:string ], 1102 ; the roles this entity has with any containing object 1103 "roles" [ *:string ], 1105 ; the place where the person, org, etc... receives postal mail 1106 ; THIS IS NOT LOCATION 1107 "postalAddress" [ *:string ], 1109 ; electronic mailboxes where the person, org, etc... 1110 ; receives messages 1111 "emails" [ *:email ], 1113 ; phones where the person, org, etc... receives 1114 ; telephonic communication 1115 "phones" { 1116 "office" [ *:phone ], ; office phones 1117 "fax" [ *:phone ], ; facsilime machines 1118 "mobile" [ *:phone ] ; cell phones and the like 1119 }, 1121 common 1122 } 1124 ; The members "handle", "status", "remarks", "uris", "port43", 1125 ; "sponsoredBy", "resoldBy", "registrationBy", "registrationDate", 1126 ; "lastChangedDate", and "lastChangedBy" are used in many objects 1127 common ( 1128 ; a registry-unique identifier 1129 "handle" : string, 1131 ; an array of status values 1132 "status" [ *:string ], 1134 ; an array of strings, each containing comments about the object 1135 "remarks" [ *:string ]. 1137 ; an array of uri objects 1138 ; "type" referrs to the application of the URI 1139 ; "uri" is the uri 1140 "uris" [ 1141 *{ "type" : string, "uri" : uri } 1142 ], 1144 ; a string containing the fully-qualified host name of the 1145 ; WHOIS [RFC3912] server where the object instance may be found 1146 "port43" : fqdn, 1148 ; a string containing an identifier of the party 1149 ; through which the registration was made, such as an IANA approved 1150 ; registrar 1151 "sponsoredBy" : string, 1153 ; a string containing an identifier of the party 1154 ; originating the registration of the object. 1155 "resoldBy" : string, 1157 ; a string containing an identifier of the party 1158 ; responsible for the registration of the object 1159 "registrationBy" : string, 1161 ; the date the object was registered 1162 "registrationDate" : date-time, 1164 ; the date of last change made to the object 1165 "lastChangedDate" : date-time, 1167 ; a string containing an identifier of the party 1168 ; responsible for the last change made to the registration 1169 "lastChangedBy" : string 1170 ) 1172 Appendix C. Design Notes 1174 C.1. Member Uniqueness 1176 JSON does not disallow non-unique object member names ( in other 1177 words, it allows non-unique object member names ) but strongly 1178 advises against the use of non-unique object member names. Many JSON 1179 implementations use hash-indexed maps to represent JSON objects, 1180 where the object's member names are the key of the hash index. Non- 1181 uniqueness would break such implementations or result in the value of 1182 the last member given overwriting the value of all previous members 1183 of the same name. 1185 Therefore, allowing non-unique object member names would be bad 1186 practice. For this reason, this specification does not accommodate 1187 the need for non-unique object member names. 1189 C.2. Member Order 1191 JSON gives awkward guidance regarding ordering of object member 1192 names. However, many JSON implementations use hash-indexed maps to 1193 represent JSON objects, where the object's member names are the key 1194 of the hash index. Though it is possible, usually these maps have no 1195 explicit order as the only index is the hash. 1197 Therefore, this specification does not provide a means to imply order 1198 of object member names. 1200 C.3. Group Syntax for Arrays and Objects 1202 It is possible to create a separate group syntax for array rules vs 1203 object rules, since allowable group rule content is determined by the 1204 containing rule. For instance, while the syntax for groups in 1205 objects could have been "( blah blah )", syntax for groups in arrays 1206 could have been "< blah blah >". That may be more distinctive and 1207 allow the formal syntax parser to handle rule content validity, but 1208 the added extra syntax appeared to hurt readability. There is only 1209 so many enclosure characters a person should reasonably be required 1210 to know, and adding yet another did not seem prudent. 1212 C.4. Inspiration 1214 The original approach to this problem was to find a concise way to 1215 describe JSON data structures; to do for JSON what RelaxNG compact 1216 syntax does for XML. The syntax itself hopefully has a JSON-ness or 1217 a JSON feel to it. And a good bit of inspiration came from ABNF. 1219 C.5. Changelog 1221 From -00 to -01 1223 1. Added ABNF. Thanks Byron Ellacott. 1225 2. Added section about root rules. 1227 3. Other minor edits. 1229 From -01 to -02 1231 1. Other minor edits. 1233 2. Added the Possible Future Changes section. 1235 3. Mostly a keep-alive version. 1237 From -02 to -03 1239 1. Removed formal syntax (ABNF) until such time as the features are 1240 nailed down. It will appear in a future draft. 1242 2. Took out the option for multiple email conformance levels as 1243 everything should be conformant to RFC 5322. 1245 3. URIs conformance can now either be just 'uri' or match a URI 1246 template (suggestion from Andrew Biggs). 1248 4. Added enumerated values based on a suggestion from Paul Jones. 1250 5. Added a directive for including other collections of rules. 1252 6. Added an example of object mixins using groups thanks to a 1253 discussion with Andrew Biggs. 1255 7. Added an alternate syntax mapping. 1257 From -03 to -04 1259 1. Removed the alternate syntax. Nobody liked it. 1261 2. all-members-optional directive was removed. 1263 3. ignore-unknown-members directive was removed. 1265 4. pedantic directive was added. 1267 5. Modified the include directive syntax. 1269 6. Removed the depends operator. 1271 7. Added syntax for optional members of groups in object rules. 1273 8. Added syntax for repetition for elements of groups in array 1274 rules. 1276 9. ABNF added back. 1278 Author's Address 1280 Andrew Lee Newton 1281 American Registry for Internet Numbers 1282 3635 Concorde Parkway 1283 Chantilly, VA 20151 1284 US 1286 Email: andy@arin.net 1287 URI: http://www.arin.net