idnits 2.17.1 draft-ietf-json-text-sequence-09.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 (October 26, 2014) is 3469 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 json N. Williams 3 Internet-Draft Cryptonector 4 Intended status: Standards Track October 26, 2014 5 Expires: April 29, 2015 7 JavaScript Object Notation (JSON) Text Sequences 8 draft-ietf-json-text-sequence-09 10 Abstract 12 This document describes the JSON text sequence format and associated 13 media type, "application/json-seq". A JSON text sequence consists of 14 any number of JSON texts, each prefix by an Record Separator 15 (U+001E), and each ending with a newline character (U+000A). 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on April 29, 2015. 34 Copyright Notice 36 Copyright (c) 2014 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction and Motivation . . . . . . . . . . . . . . . . 3 52 1.1. Conventions used in this document . . . . . . . . . . . . . 3 53 2. JSON Text Sequence Format . . . . . . . . . . . . . . . . . 4 54 2.1. JSON text sequence parsing . . . . . . . . . . . . . . . . . 4 55 2.2. JSON text sequence encoding . . . . . . . . . . . . . . . . 4 56 2.3. Incomplete JSON texts are not fatal . . . . . . . . . . . . 5 57 2.4. Top-level numeric values . . . . . . . . . . . . . . . . . . 5 58 3. Security Considerations . . . . . . . . . . . . . . . . . . 6 59 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . 7 60 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 61 6. Normative References . . . . . . . . . . . . . . . . . . . . 9 62 Author's Address . . . . . . . . . . . . . . . . . . . . . . 10 64 1. Introduction and Motivation 66 The JavaScript Object Notation (JSON) [RFC7159] is a very handy 67 serialization format. However, when serializing a large sequence of 68 values as an array, or a possibly indeterminate-length or never- 69 ending sequence of values, JSON becomes difficult to work with. 71 Consider a sequence of one million values, each possibly 1 kilobyte 72 when encoded -- roughly one gigabyte. It is often desirable to 73 process such a dataset in an incremental manner: without having to 74 first read all of it before beginning to produce results. 75 Traditionally the way to do this with JSON is to use a "streaming" 76 parser, but these are neither widely available, widely used, nor easy 77 to use. 79 This document describes the concept and format of "JSON text 80 sequences", which are specifically not JSON texts themselves but are 81 composed of (possible) JSON texts. JSON text sequences can be parsed 82 (and produced) incrementally without having to have a streaming 83 parser (nor streaming encoder). 85 1.1. Conventions used in this document 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in 90 [RFC2119]. 92 2. JSON Text Sequence Format 94 Two different sets of ABNF rules are provided for the definition of 95 JSON text sequences: one for parsers, and one for encoders. Having 96 two different sets of rules permits recovery by parsers from 97 sequences where some the elements are truncated for whatever reason. 98 The syntax for parsers is specified in terms of octet strings which 99 are then interpreted as JSON texts if possible. The syntax for 100 encoders, on the other hand, assumes that sequence elements are not 101 truncated. 103 2.1. JSON text sequence parsing 105 The ABNF [RFC5234] for the JSON text sequence parser is as given in 106 Figure 1. 108 JSON-sequence = *(1*RS possible-JSON) 109 RS = %x1E; "record separator" (RS), see RFC20 110 possible-JSON = 1*(not-RS); attempt to parse as UTF-8-encoded 111 ; JSON text (see RFC7159) 112 not-RS = %x00-1d / %x1f-ff; any octets other than RS 114 Figure 1: JSON text sequence ABNF 116 In prose: a series of octet strings, each containing any octet other 117 than a record separator (RS) (0x1E) [RFC0020], all octet strings 118 separated from each other by RS octets. Each octet string in the 119 sequence is to be parsed as a JSON text. 121 If parsing of such an octet string as a JSON text fails, the parser 122 SHOULD nonetheless continue parsing the remainder of the sequence. 123 The parser should report such failures to applications (which might 124 choose to terminate parsing of a sequence). Multiple consecutive RS 125 octets do not denote empty sequence elements between them, and can be 126 ignored. 128 There is no end of sequence indicator. 130 2.2. JSON text sequence encoding 132 The ABNF for the JSON text sequence encoder is given in Figure 2. 134 JSON-sequence = *(RS JSON-text LF) 135 RS = %x1E; see RFC20 136 LF = %x0A; "line feed" (LF), see RFC20 137 JSON-text = 139 Figure 2: JSON text sequence ABNF 141 In prose: any number of JSON texts, each preceded by one ASCII RS 142 character and each followed by a line feed (LF). Since RS is an 143 ASCII control character it may only appear in JSON strings in escaped 144 form (see [RFC7159]), and since RS may not appear in JSON texts in 145 any other form, RS unambiguously delimits the start of any element in 146 the sequence. RS is sufficient to unambiguously delimit all top- 147 level JSON value types other than numbers. Following each JSON text 148 in the sequence with an LF allows detection of truncated JSON texts 149 consisting of a number at the top-level. 151 Note that on some systems it's possible to input RS by typing 152 'ctrl-^'. This is helpful when constructing a sequence manually with 153 a text editor. 155 2.3. Incomplete JSON texts are not fatal 157 Per- Section 2.1, JSON text sequence parsers SHOULD NOT abort when an 158 octet string contains a malformed JSON text. Such a situation may 159 arise in contexts where, for example, append-writes to log files are 160 truncated by the filesystem (e.g., due to a crash, or administrative 161 process termination). 163 2.4. Top-level numeric values 165 Parsers MUST check that any JSON texts that are a top-level number 166 include JSON whitespace ("ws" ABNF rule from [RFC7159]) after the 167 number, otherwise the JSON-text may have been truncated. Parsers 168 MUST NOT report JSON-text sequence elements consisting of top-level 169 numbers that may have been truncated in the same way they would a 170 complete JSON-text. Parsers MAY report such texts as errors 171 (including, optionally, the parsed text and/or the original octet 172 string). 174 3. Security Considerations 176 All the security considerations of JSON [RFC7159] apply. This format 177 provides no cryptographic integrity protection of any kind. 179 4. IANA Considerations 181 The MIME media type for JSON text sequences is application/json-seq. 183 Type name: application 185 Subtype name: json-seq 187 Required parameters: n/a 189 Optional parameters: n/a 191 Encoding considerations: binary 193 Security considerations: See , 194 Section 3. 196 Interoperability considerations: Described herein. 198 Published specification: . 200 Applications that use this media type: is likely to support this format>. 203 5. Acknowledgements 205 Phillip Hallam-Baker proposed the use of JSON text sequences for 206 logfiles and pointed out the need for resynchronization. Stephen 207 Dolan created , which uses something 208 like JSON text sequences (with LF as the separator between texts on 209 output, and requiring only such whitespace as needed to disambiguate 210 on input). Carsten Bormann suggested the use of ASCII RS, and Joe 211 Hildebrand suggested the use of LF in addition to RS for 212 disambiguating top-level number values. Paul Hoffman shepherded the 213 Internet-Draft. Many others contributed reviews and comments on the 214 JSON Working Group mailing list. 216 6. Normative References 218 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 219 Requirement Levels", BCP 14, RFC 2119, March 1997. 221 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 222 October 1969. 224 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 225 Specifications: ABNF", STD 68, RFC 5234, January 2008. 227 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 228 Interchange Format", RFC 7159, March 2014. 230 Author's Address 232 Nicolas Williams 233 Cryptonector, LLC 235 Email: nico@cryptonector.com