idnits 2.17.1 draft-oskarsson-jsond-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 9, 2015) is 3336 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force D. Oskarsson 3 Internet-Draft JSOND.org 4 Intended status: Informational March 9, 2015 5 Expires: August 5, 2015 7 JavaScript Object Notation Definition (JSOND) 9 draft-oskarsson-jsond-00 11 Abstract 13 JSOND (JSON Definition) is a simple, yet powerful, definition 14 language for JSON text. 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 August 5, 2015. 33 Copyright Notice 35 Copyright (c) 2015 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 JSOND (JSON Definition) is a simple, yet powerful, definition 51 language for JSON text. 53 The purpose of JSOND is to facilitate development and documentation 54 of JSON text. 56 JSOND is designed to be a minimal superset of JSON. 58 1.1. Conventions Used in This Document 60 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 61 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 62 document are to be interpreted as described in RFC 2119 [RFC2119]. 63 2. JSOND Grammar 65 JSOND text is JSON text that MAY include JSOND grammar. JSOND 66 grammar is a superset of JSON grammar [RFC7159] [RFC4627] 67 [ECMA-404]. The rest of this document describes the JSOND grammar 68 in ABNF [RFC5234] and text. 70 2.1. Values 72 A JSOND value MUST be an object, array or a string. 74 value = object / array / string 76 2.2. Objects 78 A JSOND object MUST define all members in the corresponding JSON 79 object. A JSON object MUST NOT contain a member that has not been 80 defined in the corresponding JSOND object. 82 value = object ; e.g. { "a": "string" } 84 2.3. Arrays 86 A JSOND array defines zero or more values. All values in a JSON 87 array MUST be defined by at least one of the values in the 88 corresponding JSOND array. 90 value = array ; e.g. [ "string" ] 92 2.4. Booleans 94 A JSOND boolean defines that the corresponding JSON value MUST be 95 true or false. 97 value = %x22.62.6f.6f.6c.65.61.6e.22 ; "boolean" 99 2.5. Strings 101 A JSOND string defines that the corresponding JSON value MUST be any 102 string. 104 value = %x22.73.74.72.69.6e.67.22 ; "string" 106 Regular expressions [ECMA-262] MAY be used to define a subset of 107 strings. 109 value = %x22 regular-expression %x22 ; e.g. "[a-z]" 111 2.4. Numbers and Integers 113 A JSOND number defines that the corresponding JSON value MUST be any 114 number. 116 value = %x22.6e.75.6d.62.65.72.22 ; "number" 118 A JSOND integer defines that the corresponding JSON value MUST be 119 any integer. 121 value = %x22.69.6e.74.65.67.65.72.22 ; "integer" 123 2.4.1 Sets and Intervals 125 An arbitrary number of mathematical sets and intervals [ISO-80000-2] 126 MAY be used to define a subset of numbers. 128 A corresponding JSON number MUST match a number in the defined 129 subset. 131 begin-exclusive = %x28 ; ( 133 end-exclusive = %x29 ; ) 135 integer = [ minus ] zero / ( digit1-9 *DIGIT ) 137 number = integer [ frac ] [ exp ] 139 set = begin-object number *( value-separator number ) end-object 141 interval = begin-array / begin-exclusive ( ( number 142 value-separator ) / ( number value-separator number ) / 143 ( value-separator number ) ) end-array / end-exclusive 145 value = %x22 1*( set / interval ) %x22 ; e.g. "[1.0,2.0)" 147 Set elements SHOULD be ordered in increasing order from the least 148 to the greatest element. There must be at least one element. 150 The left or right interval endpoint is OPTIONAL. An undefined left 151 endpoint defines negative infinity. An undefined right endpoint 152 defines positive infinity. If both endpoints are provided the left 153 endpoint MUST be less than the right endpoint. 155 An interval that is declared using integers defines the 156 corresponding subset of integers. An interval MUST be declared using 157 at least one number with an explicit decimal component to define a 158 subset of real numbers. The decimal component MAY be .0. 160 Insignificant whitespace is OPTIONAL in sets and intervals. 162 2.5. References 164 Any JSOND value MAY be persisted as a file. A file SHOULD be 165 referenced using a relative path, an absolute path, or using the 166 http or https scheme [RFC3986]. 168 value = %x22 [ scheme ] path %x22 ; e.g. "file.jsond" 170 JSOND files SHOULD have the filename extension .jsond. Circular 171 references SHOULD be avoided. 173 2.6. Constants 175 A value that is not valid JSOND grammar SHOULD be interpreted as a 176 constant and thus REQUIRED in the corresponding JSON text. 178 The literals, true, false, and null are not valid JSOND grammar. 179 Numbers are not valid JSOND grammar. 181 Most strings are valid regular expressions and thus valid JSOND 182 grammar. String constants SHOULD include boundary matchers. 184 2.7. Optionals 186 A member can be defined as optional by appending a question mark to 187 the end of the name. 189 name = %x22 *char [ %x3f ] %x22 ; e.g. "name?" 191 An optional member MAY have the value null. An optional member MAY 192 be undefined in JSON text. 194 3. IANA Considerations 196 Additional information: 197 Magic number(s): n/a 198 File extension(s): .jsond 199 Macintosh file type code(s): TEXT 201 4. Security Considerations 203 See Security Considerations in [RFC7159] Section 12. 205 5. References 207 5.1. Normative References 209 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 210 Requirement Levels", BCP 14, RFC 2119, March 1997. 212 [RFC3986] Berners-Lee, T., Fielding R., and Masinter, L., "Uniform 213 Resource Identifier (URI): Generic Syntax", RFC 3986, 214 January 2005. 216 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 217 Specifications: ABNF", STD 68, RFC 5234, January 2008. 219 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 220 Interchange Format", RFC 7159, March 2014. 222 5.2. Informative References 224 [ECMA-404] Ecma International, "The JSON Data Interchange Format", 225 Standard ECMA-404, October 2013, . 228 [ECMA-262] Ecma International, "ECMAScript Language Specification", 229 Standard ECMA-262, June 2011, . 232 [ISO-80000-2] International Organization for Standardization, 233 "Quantities and units - Part 2: Mathematical signs and 234 symbols to be used in the natural sciences and 235 technology", Standard ISO 80000-2:2009, December 2009, 236 . 239 [RFC4627] Crockford, D., "The application/json Media Type for 240 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 242 Appendix A. Examples 244 Example 1: 246 [ 247 { 248 "id": "integer", 249 "slug": "string", 250 "url": "string" 251 "category": "integer", 252 "price": "number", 253 "reduced": "boolean", 254 } 255 ] 257 Example 2: 259 [ 260 { 261 "id": "[0,)", 262 "slug": "[a-z0-9]", 263 "url": "url.jsond" 264 "category": "{10,25,50}", 265 "price": "(0.0,)", 266 "reduced?": "boolean", 267 "margin": "(high|medium|low)", 268 "available": true, 269 } 270 ] 272 Author's Address 274 Daniel Oskarsson 275 Satuna Vekabacken 276 SE-541 94 277 SWEDEN 279 Email: daniel@jsond.org