idnits 2.17.1 draft-newton-json-content-rules-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 7 instances of too long lines in the document, the longest one being 24 characters 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 (August 28, 2014) is 3527 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 901 -- Looks like a reference, but probably isn't: '943' on line 901 -- Looks like a reference, but probably isn't: '234' on line 901 -- Looks like a reference, but probably isn't: '38793' on line 901 == Missing Reference: 'RFC3912' is mentioned on line 1052, but not defined ** Downref: Normative reference to an Informational RFC: RFC 1166 ** Obsolete normative reference: RFC 2822 (Obsoleted by RFC 5322) ** Obsolete normative reference: RFC 4234 (Obsoleted by RFC 5234) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 8 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 August 28, 2014 5 Expires: March 1, 2015 7 A Language for Rules Describing JSON Content 8 draft-newton-json-content-rules-02 10 Abstract 12 This document describes a language useful for documenting the 13 expected content of JSON structures found in specifications using 14 JSON. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on March 1, 2015. 33 Copyright Notice 35 Copyright (c) 2014 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 1. Introduction 50 The goal of this document is to provide a way to document the 51 expected content of data expressed in JSON [RFC4627] format. That 52 is, the primary purpose of this document is to specify a means for 53 one person to communicate with another person the expected nature of 54 a JSON data structure in a method more concise than prose. The 55 programmatic validation of a JSON data structure against content 56 rules is a lesser goal of this document, though such a practice is 57 useful in both the writing of specifications and the communications 58 of programs. 60 Unlike JSON Schema, this language is not JSON though the syntax 61 described here is "JSON-like" (a comparison with JSON Schema can be 62 found in Appendix A and a "real world" example can be found in 63 Appendix B). A specialized syntax is used to reduce the tedium in 64 reading and writing rules as the complexity describing allowable 65 content is often more involved than most of the actual content. 66 Figure 2 is an example of this language describing the JSON of 67 Figure 1. 69 Example JSON lifted from RFC 4627 71 [ 72 { 73 "precision": "zip", 74 "Latitude": 37.7668, 75 "Longitude": -122.3959, 76 "Address": "", 77 "City": "SAN FRANCISCO", 78 "State": "CA", 79 "Zip": "94107", 80 "Country": "US" 81 }, 82 { 83 "precision": "zip", 84 "Latitude": 37.371991, 85 "Longitude": -122.026020, 86 "Address": "", 87 "City": "SUNNYVALE", 88 "State": "CA", 89 "Zip": "94085", 90 "Country": "US" 91 } 92 ] 94 Figure 1 96 Rules describing Figure 1 98 root [ 99 2*2{ 100 "precision" : string, 101 "Latitude" : float, 102 "Longitude" : float, 103 "Address" : string, 104 "City" : string, 105 "State" : string, 106 "Zip" : string, 107 "Country" : string 108 } 109 ] 111 Figure 2 113 The JSON Content Rules are of five types: 115 o value rules 117 o member rules 119 o array rules 121 o object rules 123 o group rules 125 Each rule has two components, a rule name and a rule definition. 126 Anywhere in a rule definition where a rule name is allowed, another 127 rule definition may be used. 129 This is an example of a value rule: 131 v1 : integer 0..3 133 It specifies a rule named "v1" that has a definition of ": integer 134 0..3" (value rule definitions begin with a ':' character). This 135 defines values of type "v1" to be integers in the range 0 to 3 136 (minimum value of 0, maximum value of 3). Value rules can define the 137 limits of JSON values, such as stating that numbers must fall into a 138 certain range or that strings must be formatted according to certain 139 patterns or standards (i.e. URIs, phone numbers, etc...). 141 Member rules specify JSON object members. The following example 142 member rule states that the rules name is 'm1' with a value defined 143 by the 'v1' value rule: 145 m1 "m1name" v1 147 Since rule names can be substituted by rule definitions, this member 148 rule can also be written as follows: 150 m1 "m1name" : integer 0..3 152 Object rules are composed of member rules, since JSON objects are 153 composed of members. Object rules can specify members that are 154 mandatory, optional, and even choices between members. In this 155 example, the rule 'o1' defines an object that must contain a member 156 as defined by member rule 'm1' and optionally a member defined by the 157 rule 'm2': 159 o1 { m1, ?m2 } 161 Finally, array rules are composed of value and object rules. Like 162 object rules, array rules can specify the cardinality of the contents 163 of an array. The following array rule defines an array that must 164 contain value rule 'v1' and zero or more objects as defined by rule 165 'o1': 167 a1 [ v1, *o1 ] 169 Putting it all together, Figure 4 describes the JSON in Figure 3. 171 Example JSON shamelessly lifted from RFC 4627 173 { 174 "Image": { 175 "Width": 800, 176 "Height": 600, 177 "Title": "View from 15th Floor", 178 "Thumbnail": { 179 "Url": "http://www.example.com/image/481989943", 180 "Height": 125, 181 "Width": "100" 182 }, 183 "IDs": [116, 943, 234, 38793] 184 } 185 } 187 Figure 3 189 Rules describing Figure 3 191 width_v : integer 0..1280 192 height_v : integer 0..1024 194 width "width" width_v 195 height "height" height_v 197 thumbnail "thumbnail" { 198 width, height, "Url" : uri 199 } 201 image "Image" { 202 width, height, "Title" : string, 203 thumbnail, "IDs" [ *: integer ] 204 } 206 root { image } 208 Figure 4 210 The rules from Figure 4 can be written more compactly (see Figure 5). 212 Compact rules describing Figure 3 214 width "width" : integer 0..1280 215 height "height" : integer 0..1024 217 root { 218 "Image" { 219 width, height, "Title" :string, 220 "thumbnail" { width, height, "Url" :uri }, 221 "IDs" [ *:integer ] 222 } 223 } 225 Figure 5 227 2. Lines and Comments 229 There is no statement terminator and therefore no need for a line 230 continuation syntax. Blank lines are allowed. 232 Comments are very similar to comments in ABNF [RFC4234]. They start 233 with a semi-colon (';') and continue to the end of the line. 235 3. Rules 237 Rules are composed of two parts, a rule name and a rule definition. 238 Rule names allow a rule definition to be referenced easily by a name. 239 With the exception of value rules, rule definitions refer to other 240 rules using the rule names of other appropriate types of rules. 241 Because of this, it is also possible to use a rule definition of the 242 appropriate type where a rule name of that type would be appropriate. 244 The type of rule to use in a rule definition, either directly or by 245 reference of a name, depends on the type of rule being defined and 246 fall along the structure of allowable JSON grammar: 248 o Since a member of a JSON object can contain a "primitive value", 249 an array, or an object, member rules can be composed of value 250 rules, array rules, and object rules. 252 o JSON objects are composed of members, so object rules can only be 253 composed of member rules. 255 o Finally, as JSON arrays may contain other arrays, objects, and 256 values, array rules may be composed of value rules, object rules, 257 and array rules. 259 A fifth rule type, group rules, exist to help reference a collection 260 of rules. 262 Rule names must start with an alphabetic character (a-z,A-Z) and must 263 contain only alphabetic characters, numeric characters, the hyphen 264 character ('-') and the underscore character ('_'). Rule names must 265 not be used more than once. 267 3.1. Value Rules 269 Value rules define content for JSON values. JSON allows values to be 270 objects, arrays, numbers, booleans, strings, and null. Arrays and 271 objects are handled by the array and object rules, and the value 272 rules define the rest. 274 3.1.1. Numbers, Booleans and Null 276 The rules for booleans and null are the simplest and take the 277 following forms: 279 rule_name : boolean 281 rule_name : null 283 Rules for numbers can specify the number as either an integer or 284 floating point number and may specify a range: 286 rule_name : integer n..m 288 rule_name : float n..m 290 where n is the minimum allowable value of the number and m is the 291 maximum allowable value of the number. The range doesn't have to be 292 given, but if it is given either the minimum, maximum, or both are 293 required. If the minimum is not given then the minimum is considered 294 to be the minimum number value possible to represent in JSON. 295 Likewise, if the maximum is not given then the maximum is considered 296 to be the maximum number value possible to represent in JSON. 298 3.1.2. Strings 300 String values may be specified generically as: 302 rule_name : string 304 However, the content of strings can be narrowed in the following 305 ways: 307 Regular Expression: A rule can state that a string must match a 308 regular expression by giving the regular expression after the 309 string literal: 311 rule_name : string /regex/ 313 URIs: A rule can state that a string must be a URI [RFC3986]: 315 rule_name : uri 317 URIs can also be scoped further by providing the literals 'full' 318 or 'relative' to indicate that the URI must be either a full URI 319 or a relative URI: 321 rule_name : uri relative 323 And the scheme of the URI can also be specified: 325 rule_name : uri full http 327 Neither the scheme nor the full/relative literals need to be 328 specified, and neither need to be specified together. 330 IP Addresses: Narrowing the content of strings down to IP addresses 331 can be done with either the 'ip4' (see [RFC1166]) or 'ip6' (see 332 [RFC5952]) literals: 334 rule_name : ip4 336 rule_name : ip6 338 Domain Names: Fully qualified A-label and U-label domain names can 339 be specified with the 'fqdn' and 'idn' literals: 341 rule_name : fqdn 343 rule_name : idn 345 Dates and Times: Dates and times are specified using the ABNF rules 346 from RFC 3339 [RFC3339] as literals: 348 rule_name : date-time 350 rule_name : full-date 352 rule_name : full-time 354 Email Addresses: A string can be scoped to the syntax of email 355 addresses using the literal 'email' followed by an optional 356 conformance level: 358 rule_name : email 2822 360 rule_name : email 5322 362 Conformance levels are specified with the literal '2822' 363 signifying RFC 2822 [RFC2822] conformance or '5322' signifying RFC 364 5322 [RFC5322] conformance. 366 Phone Numbers: Strings conforming to E.123 phone number format can 367 be specified as follows: 369 rule_name : phone 371 Base 64: Strings containing base 64 data, as described by RFC 4648 372 [RFC4648], can be specified as follows: 374 rule_name : base64 376 3.2. Member Rules 378 Member rules are the simplest of the rules and define members of JSON 379 objects. Member rules follow the format: 381 rule_name "member_name" target_rule_name 383 where rule_name is the name of the rule being defined, member_name 384 (in quotes) is the name of the JSON object member, and 385 target_rule_name is a reference to a value rule, array rule, or 386 object rule specifying the allowable content of the JSON object 387 member. 389 Since rule names in rule definitions may be substituted for rule 390 definitions, member rules may also be written in this form: 392 rule_name "member_rule" target_rule_definition 394 The following is an example: 396 location_uri "locationURI" : uri 398 3.3. Object Rules 400 Object rules define the allowable members of a JSON object. Their 401 rule definitions are composed of member rules and group rules. They 402 take the following form: 404 rule_name { member_rule_1, member_rule_2 } 406 The following rule example defines an object composed of two member 407 rules: 409 response { location_uri, status_code } 411 Given the general rule that where a rule name is found a rule 412 definition of the appropriate type may be used, the above example 413 might also be written: 415 response { "locationUri" : uri, "statusCode" : integer } 417 Rules given in the rule definition of an object rule do not imply 418 order. Given the example object rule above both 420 { "locationUri" : "http://example.com", "statusCode" : 200 } 422 and 423 { "statusCode" : 200, "locationUri" : "http://example.com" } 425 are JSON objects that match the rule. 427 Member rules or member rule definitions may not be repeated in the 428 rule definition of an object rule. However, a member of an object 429 can be marked as optional if the member rule defining it is preceded 430 by the question mark ('?') character. In the following example, the 431 location_uri member is optional while the status_code member is 432 required to be in the defined object: 434 response { ?location_uri, status_code } 436 An object rule can also define the choice between members by placing 437 the forward slash ('/') character between two member rules. In the 438 following example, the object being defined can have either a 439 location_uri member or content_type member and must have a 440 status_code member: 442 response { location_uri / content_type, status_code } 444 Finally, the specification of a member of an object can be 445 conditioned upon the the specification of another member of that 446 object by placing the ampersand ('&') character between two member 447 rules. Using this syntax, the member defined by the second rule is 448 only allowed in the object if the member defined by the first rule is 449 given. Or in other words, the appearance of the second member 450 depends upon the appearance of the first member. In the following 451 example, the object defined can have a referrer_uri so long as 452 location_uri is also present: 454 response { location_uri & referrer_uri } 456 3.4. Array Rules 458 Array rules define the allowable content of JSON arrays. Their rule 459 definitions are composed of value rules, object rules, group rules, 460 and other array rules and have the following form: 462 rulename [ target_rule_name_1, target_rule_name_2 ] 464 The following example defines an array where element 1 is defined by 465 the width_value rule and element 2 is defined by the height_value 466 rule: 468 size [ width_value, height_value ] 470 Unlike object rules, order is implied by the array rule definition. 471 That is, the first rule referenced or defined within an array rule 472 specifies that the first element of the array will match that rule, 473 the second rule given with the array rule specifies that the second 474 element of the array will match that rule, and so on. 476 Take for example the following array rule definition: 478 person [ : string, : integer ] 480 This JSON array matches the above rule: 482 [ "Bob Smurd", 24 ] 484 while this one does not: 486 [ 24, "Bob Smurd" ] 488 As with object rules, the forward slash character ('/') can be used 489 to indicate a choice between two elements. Take for example the 490 following rules: 492 name_value : string 494 age_value : integer 496 birthdate_value : date-time 498 person [ name_value, age_value / birthdate_vale ] 500 which would validate 502 [ "Bob Smurd", 24 ] 504 or 506 [ "Bob Smurd", "1988-04-12T23:20:50.52Z" ] 508 Repetition of array values may also be specified by preceding a rule 509 with an asterisk ('*') character surrounded by the lower bound and 510 upper bound of the repetition (e.g. "0*1"). The following rules 511 define an array that has between one and three strings: 513 child_value : string 515 children [ 1*3 child_value ] 517 Both the lower bound and the upper bound are optional. If lower 518 bound is not given then it is assumed to be zero. If the upper bound 519 is not given then it is assumed to be infinity. The following 520 example defines an array with an infinite number of child_value 521 defined strings: 523 children [ * child_value ] 525 3.5. Group Rules 527 Unlike the other types of rules, group rules have no direct tie with 528 JSON syntax. Group rules simply group together other rules. They 529 take the form: 531 rule_name ( target_rule_1, target_rule_2 ) 533 Group rule definitions and any nesting of group rule definitions, 534 must conform to the allowable set of rules of the rule containing 535 them. A group rule referenced inside of an array rule may not 536 contain a member rule since member rules are not allowed in array 537 rules directly. Likewise, a group rule referenced inside an object 538 rule must only contain member rules, and once group rules used in an 539 object rule are fully dereferenced there must be no duplicate member 540 rules as member rules in object rules are required to be unique. 542 Take for example the following rules: 544 child_1 "first_child" : string 546 child_2 "second_child" : string 548 child_3 "third_child" : string 550 child_4 "fourth_child" : string 552 first_two_children ( child_1, child_2 ) 554 second_two_children ( child_3, child_4 ) 556 the_children { first_two_children, second_two_children } 558 These rules describe a JSON object that might look like this: 560 { "first_child":"greg", "second_child":"marsha", 561 "third_child":"bobby", "fourth_child":"jan" } 563 Groups can also be used with the choice and dependency syntax in 564 member rules. Here the object can either have first_two_children or 565 second_two_children: 567 the_children { first_two_children / second_two_children } 569 and here the object can have second_two_children only if 570 first_two_children are given: 572 the_children { first_two_children & second_two_children } 574 3.6. Any Value and Any Member 576 It is possible to specify that a value can be of any type allowable 577 by JSON using the any value rule. This is done with the 'any' 578 literal in a value rule: 580 rule_name : any 582 However, unlike other value rules which define primitive data types, 583 this rule defines a value of any kind, either primitive (null, 584 boolean, number, string), object, or array. 586 Use of the any value rule in arrays can be used with repetition to 587 define arrays that may contain any value: 589 any_value : any 591 array_of_any [ *any_value ] 593 Specifying any object member name in a member rule with the any 594 member rule is done by pre-pending a carat character ('^') to an 595 empty member name (that is, ^"" signifies any member name). This has 596 the following form: 598 rule_name ^"" target_rule_name 600 As an example, the following defines an object member with any name 601 that has a value that is a string: 603 user_data ^"" : string 605 Usage of the any member rule must still satisfy the criteria that all 606 member names of an object be unique. 608 Constructing an object member of any name with any type would 609 therefore take the form: 611 rule_name ^"" : any 613 Unlike other types of member rules, it is possible to use repetition 614 with the any member rule in an object rule. The repetition syntax 615 and semantics are the same as the repetition syntax and semantics of 616 repetition with array rules. The following example rules define an 617 object that may contain any number of members where each member may 618 have any value. 620 any_member ^"" : any 622 object_of_anything { *any_member } 624 Use of the repetition of any member rules must satisfy the criteria 625 that all member names of an object be unique. 627 3.7. A Root Rule 629 In some contexts it is necessary that there be a rule that defines 630 the outer most JSON object or array, or if thought of as an inverted 631 object tree the structure at the very top. If in a collection of 632 rules there is no rule explicitly specified for this purpose and a 633 rule named "root" is given, it can be assumed to be the outer most 634 JSON structure or the root of an object/array tree. If a rule is 635 explicitly specified other than "root" and there exists a rule named 636 "root", that rule name holds no special meaning. 638 4. Directives 640 Directives change the interpretation of a collection of rules. They 641 begin with a hash character ('#') and are terminated by the end of a 642 line. They take the following form: 644 # directive_name 646 4.1. ignore-unknown-members 648 This directive specifies that any member of any object which has not 649 been specified should be ignored. Ignored object members may have a 650 value of any type. This directive cannot be used in any collection 651 of rules that has an any member rule. 653 4.2. language-compatible-members 655 This directive specifies that every member name of every object, 656 either explicitly defined or specified via an any member rule or the 657 ignore-unknown-members directive must be a name compatible with 658 programming languages. The intent is to specify object member names 659 that may be promoted to first-order object attributes or methods in 660 an API. The following ABNF describes the restrictions upon the 661 member names: 663 ABNF for programming language compatible JSON names 665 name = ALPHA *( ALPHA / DIGIT / "_" ) 667 Figure 6 669 4.3. all-members-optional 671 This directive specifies that every member of every object is not 672 required. This directive effectively pre-pends a '?' to every member 673 rule in every object rule. 675 5. Formal Syntax 677 The following ABNF describes the syntax for JSON Content Rules. 679 grammar = 1*(rule / directive) *c-wsp 681 rule = rulename definition 682 definition = *c-wsp ( value-rule / member-rule / array-rule / object-rule / group-rule ) 684 ; rulenames must be unique, and may not be a reserved word 685 rulename = *c-wsp ALPHA *(ALPHA / DIGIT / "-" / "_") 687 ; Adapted from the ABNF for JSON, RFC 4627 s 2.4 688 float = [ "-" ] int [ frac ] [ exp ] 689 integer = [ "-" ] int [ exp ] 690 exp = ( "e" / "E" ) [ "+" / "-" ] 1*DIGIT 691 frac = "." 1*DIGIT 692 int = "0" / ( %x31-39 *DIGIT ) 694 ; The regex-char rule allows for any sequence of characters, including 695 ; whitespace and newlines, with backslash only allowed before either 696 ; a forward or a backslash. 697 regex-char = %x21-2E / %x30-5D / %x5E-7E / WSP / 698 CR / LF / "\/" / "\\" 700 ; uri-scheme from RFC 3986 701 uri-scope = *c-wsp ( "relative" / "full" ) 702 uri-scheme = *c-wsp ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) 704 boolean-type = "boolean" 705 null-type = "null" 706 integer-type = "integer" [ 1*c-wsp integer ".." integer ] 707 float-type = "float" [ 1*c-wsp float ".." float ] 708 string-type = "string" [ *c-wsp "/" *regex-char "/" ] 709 uri-type = "uri" [ uri-scope ] [ uri-scheme ] 710 ip-type = "ip4" / "ip6" 711 dns-type = "fqdn" / "idn" 712 date-type = "date-time" / "full-date" / "full-time" 713 email-type = "email" [ *c-wsp ( "2822" / "5322" ) ] 714 phone-type = "phone" 715 base64-type = "base64" 716 any-type = "any" 718 value-rule = ":" *c-wsp type-rule 719 type-rule = boolean-type / 720 null-type / 721 integer-type / 722 float-type / 723 string-type / 724 uri-type / 725 ip-type / 726 dns-type / 727 date-type / 728 email-type / 729 phone-type / 730 base64-type / 731 any-type 733 inline-rule = *c-wsp ( rulename / definition ) 735 ; The defintion of a JSON string, from RFC 4627 s 2 736 json-name = %x20-21 / %x23-5B / %x5D-10FFFF / "\" ( 737 %x22 / ; " u+0022 738 %x5C / ; \ u+005C 739 %x2F / ; / u+002F 740 %x62 / ; BS u+0008 741 %x66 / ; FF u+000C 742 %x6E / ; LF u+000A 743 %x72 / ; CR u+000D 744 %x74 / ; HT u+0009 745 ( %x75 4HEXDIG ) ) ; uXXXX u+XXXX 747 member-rule = ( ( "^" %x22.22 ) / ( %x22 *json-name %x22 ) ) inline-rule 749 object-rule = "{" [ object-member *( *c-wsp ( "," / "/" / "&" ) object-member ) ] *c-wsp "}" 751 object-member = *c-wsp ["?"] ( rulename / member-rule / group-rule ) 752 array-rule = "[" [ array-member *( *c-wsp "," array-member ) ] *c-wsp "]" 754 array-count = *c-wsp [ [int] "*" [int] *c-wsp ] 755 array-member = array-count ( rulename / value-rule / object-rule / group-rule ) 756 [ *c-wsp "/" array-member ] 758 group-rule = "(" [ group-member *( *c-wsp "," group-member) ] *c-wsp ")" 760 group-member = ["?"] inline-rule [ *c-wsp ( "/" / "&" ) group-member ] 762 directive = *c-wsp "#" *( VCHAR / WSP / %x7F-10FFFF ) EOL 764 ; Taken from the ABNF for ABNF (RFC 4627 section 4) and slightly adapted 765 ; newlines in a c-wsp do not need whitespace at the start of a newline 766 ; to form a valid continuation line, and EOL might not be a full CRLF 767 c-wsp = WSP / c-nl 768 c-nl = comment / EOL 769 comment = ";" *(WSP / VCHAR) EOL 770 EOL = 1*( CR / LF ) 772 ; core rules 773 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z 774 CR = %x0D 775 DIGIT = %x30-39 776 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 777 LF = %x0A 778 VCHAR = %x21-7E 779 WSP = SP / HTAB 780 SP = %x20 781 HTAB = %x09 783 JSON Content Rules ABNF 785 6. Acknowledgements 787 Many thanks to Byron Ellacott for providing the ABNF in Section 5. 789 7. Normative References 791 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 792 numbers", RFC 1166, July 1990. 794 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 795 2001. 797 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 798 Internet: Timestamps", RFC 3339, July 2002. 800 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 801 Resource Identifier (URI): Generic Syntax", STD 66, RFC 802 3986, January 2005. 804 [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 805 Specifications: ABNF", RFC 4234, October 2005. 807 [RFC4627] Crockford, D., "The application/json Media Type for 808 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 810 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 811 Encodings", RFC 4648, October 2006. 813 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 814 October 2008. 816 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 817 Address Text Representation", RFC 5952, August 2010. 819 Appendix A. Comparison with JSON Schema 821 This section compares this specification, JSON Content Rules, with 822 JSON Schema using examples. 824 A.1. Example 1 from RFC 4627 825 Example JSON lifted from RFC 4627 827 [ 828 { 829 "precision": "zip", 830 "Latitude": 37.7668, 831 "Longitude": -122.3959, 832 "Address": "", 833 "City": "SAN FRANCISCO", 834 "State": "CA", 835 "Zip": "94107", 836 "Country": "US" 837 }, 838 { 839 "precision": "zip", 840 "Latitude": 37.371991, 841 "Longitude": -122.026020, 842 "Address": "", 843 "City": "SUNNYVALE", 844 "State": "CA", 845 "Zip": "94085", 846 "Country": "US" 847 } 848 ] 850 JSON Content Rules 852 root [ 853 2*2{ 854 "precision" : string, 855 "Latitude" : float, 856 "Longitude" : float, 857 "Address" : string, 858 "City" : string, 859 "State" : string, 860 "Zip" : string, 861 "Country" : string 862 } 863 ] 864 JSON Schema 866 { 867 "type": "array", 868 "items": [ 869 { 870 "type": "object", 871 "properties": { 872 "precision": { "type": "string", "required": "true" }, 873 "Latitude": { "type": "number", "required": "true" }, 874 "Longitude": { "type": "number", "required": "true" }, 875 "Address" : { "type": "string", "required": "true" }, 876 "City" : { "type": "string", "required": "true" }, 877 "State" : { "type" : "string", "required": "true" }, 878 "Zip" : { "type" : "string", "required": "true" }, 879 "Country" : { "type" : "string", "required": "true" } 880 } 881 } 882 ], 883 "minItems" : 2, 884 "maxItems" : 2 885 } 887 A.2. Example 2 from RFC 4627 889 Example JSON shamelessly lifted from RFC 4627 891 { 892 "Image": { 893 "Width": 800, 894 "Height": 600, 895 "Title": "View from 15th Floor", 896 "Thumbnail": { 897 "Url": "http://www.example.com/image/481989943", 898 "Height": 125, 899 "Width": "100" 900 }, 901 "IDs": [116, 943, 234, 38793] 902 } 903 } 904 JSON Content Rules 906 width "width" : integer 0..1280 907 height "height" : integer 0..1024 909 root { 910 "Image" { 911 width, height, "Title" :string, 912 "thumbnail" { width, height, "Url" :uri }, 913 "IDs" [ *:integer ] 914 } 915 } 917 JSON Schema 919 { 920 "type" : "object", 921 "properties" : { 922 "Image": { 923 "type" : "object", 924 "properties" : { 925 "Width" : { 926 "type" : "integer", 927 "minimum" : 0, 928 "maximum" : 1280, 929 "required" : "true" 930 } 931 "Height" : { 932 "type" : "integer", 933 "minimum" : 0, 934 "maximum" : 1024, 935 "required" : "true" 936 } 937 "Title" : { "type": "string" }, 938 "Thumbnail" : { 939 "type" : "object", 940 "properties" : { 941 "Url" : { 942 "type" : "string", 943 "format" : "uri", 944 "required" : "true" 945 }, 946 "Width" : { 947 "type" : "integer", 948 "minimum" : 0, 949 "maximum" : 1280, 950 "required" : "true" 951 }, 952 "Height" : { 953 "type" : "integer", 954 "minimum" : 0, 955 "maximum" : 1280, 956 "required" : "true" 957 } 958 } 959 }, 960 "IDs" : { 961 "type":"array", 962 "items":[ { "type": "integer" } ], 963 "required" : "true" 964 } 965 } 966 } 967 } 968 } 970 Appendix B. A "Real World" Exmaple 972 The following example is taken from draft-ietf-weirds-json-response- 973 00. It describes the entity object (Section 4), the nameserver 974 object (Section 5) and many of the other sub-structures used in 975 objects defined in other sections of that draft. 977 JSON Content Rules for nameserver and entity from draft-ietf-weirds- 978 json-response 980 # all-members-optional 981 # ignore-unknown-members 982 # language-compatible-members 984 ; the nameserver object 985 ; models nameserver host information 986 ; this often referred to as 'host' object too 987 nameserver { 989 ; the host name of the name server 990 "name" : fqdn, 992 ; the ip addresses of the nameserver 993 "ipAddresses" [ *( :ip4 / :ip6 ) ], 995 common 996 } 998 ; the entity object 999 ; This object object represents the information of organizations, 1000 ; corporations, governments, non-profits, clubs, individual persons, 1001 ; and informal groups of people. 1002 entity { 1004 ; the names by which the entity is commonly known 1005 "names" [ *:string ], 1007 ; the roles this entity has with any containing object 1008 "roles" [ *:string ], 1010 ; the place where the person, org, etc... receives postal mail 1011 ; THIS IS NOT LOCATION 1012 "postalAddress" [ *:string ], 1014 ; electronic mailboxes where the person, org, etc... 1015 ; receives messages 1016 "emails" [ *:email 2822 ], 1018 ; phones where the person, org, etc... receives 1019 ; telephonic communication 1020 "phones" { 1021 "office" [ *:phone ], ; office phones 1022 "fax" [ *:phone ], ; facsilime machines 1023 "mobile" [ *:phone ] ; cell phones and the like 1024 }, 1026 common 1027 } 1029 ; The members "handle", "status", "remarks", "uris", "port43", 1030 ; "sponsoredBy", "resoldBy", "registrationBy", "registrationDate", 1031 ; "lastChangedDate", and "lastChangedBy" are used in many objects 1032 common ( 1034 ; a registry-unique identifier 1035 "handle" : string, 1037 ; an array of status values 1038 "status" [ *:string ], 1040 ; an array of strings, each containing comments about the object 1041 "remarks" [ *:string ]. 1043 ; an array of uri objects 1044 ; "type" referrs to the application of the URI 1045 ; "uri" is the uri 1046 "uris" [ 1047 *{ "type" : string, "uri" : uri } 1049 ], 1051 ; a string containing the fully-qualified host name of the 1052 ; WHOIS [RFC3912] server where the object instance may be found 1053 "port43" : fqdn, 1055 ; a string containing an identifier of the party 1056 ; through which the registration was made, such as an IANA approved 1057 ; registrar 1058 "sponsoredBy" : string, 1060 ; a string containing an identifier of the party 1061 ; originating the registration of the object. 1062 "resoldBy" : string, 1064 ; a string containing an identifier of the party 1065 ; responsible for the registration of the object 1066 "registrationBy" : string, 1068 ; the date the object was registered 1069 "registrationDate" : date-time, 1071 ; the date of last change made to the object 1072 "lastChangedDate" : date-time, 1074 ; a string containing an identifier of the party 1075 ; responsible for the last change made to the registration 1076 "lastChangedBy" : string 1077 ) 1079 Appendix C. Design Notes 1081 C.1. Member Uniqueness 1083 JSON does not disallow non-unique object member names ( in other 1084 words, it allows non-unique object member names ) but strongly 1085 advises against the use of non-unique object member names. Many JSON 1086 implementations use hash-indexed maps to represent JSON objects, 1087 where the object's member names are the key of the hash index. Non- 1088 uniqueness would break such implementations or result in the value of 1089 the last member given overwriting the value of all previous members 1090 of the same name. 1092 Therefore, allowing non-unique object member names would be bad 1093 practice. For this reason, this specification does not accommodate 1094 the need for non-unique object member names. 1096 C.2. Member Order 1098 JSON gives awkward guidance regarding ordering of object member 1099 names. However, many JSON implementations use hash-indexed maps to 1100 represent JSON objects, where the object's member names are the key 1101 of the hash index. Though it is possible, usually these maps have no 1102 explicit order as the only index is the hash. 1104 Therefore, this specification does not provide a means to imply order 1105 of object member names. 1107 C.3. Group Syntax for Arrays and Objects 1109 It is possible to create a separate group syntax for array rules vs 1110 object rules, since allowable group rule content is determined by the 1111 containing rule. For instance, while the syntax for groups in 1112 objects could have been "( blah blah )", syntax for groups in arrays 1113 could have been "< blah blah >". That may be more distinctive and 1114 allow the formal syntax parser to handle rule content validity, but 1115 the added extra syntax appeared to hurt readability. There is only 1116 so many enclosure characters a person should reasonably be required 1117 to know, and adding yet another did not seem prudent. 1119 C.4. Inspiration 1121 The original approach to this problem was to find a concise way to 1122 describe JSON data structures; to do for JSON what RelaxNG compact 1123 syntax does for XML. The syntax itself hopefully has a JSON-ness or 1124 a JSON feel to it. And a good bit of inspiration came from ABNF. 1126 C.5. Changelog 1128 From -00 to -01 1130 1. Added ABNF. Thanks Byron Ellacott. 1132 2. Added section about root rules. 1134 3. Other minor edits. 1136 From -01 to -02 1138 1. Other minor edits. 1140 2. Added the Possible Future Changes section. 1142 3. Mostly a keep-alive version. 1144 C.6. Possible Future Changes 1146 The following is a list of possible modifications and additions to 1147 this specification. 1149 1. Reduction of some of the built-in string patterns. Specifically, 1150 only one email pattern and getting rid of the URI full vs 1151 relative. 1153 2. A way to specify a string can come from an enumerated list of 1154 strings other than with a regex. 1156 3. A method for referencing other collections of rules. 1158 4. A rule or modification to an existing rule that allows a value to 1159 be either a primitive JSON value or an array of those primitive 1160 JSON values. 1162 Author's Address 1164 Andrew Lee Newton 1165 American Registry for Internet Numbers 1166 3635 Concorde Parkway 1167 Chantilly, VA 20151 1168 US 1170 Email: andy@arin.net 1171 URI: http://www.arin.net