Skip to main content

JavaScript Object Notation (JSON) Text Sequences
draft-ietf-json-text-sequence-06

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 7464.
Author Nicolás Williams
Last updated 2014-08-21
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state WG Document
Document shepherd Paul E. Hoffman
IESG IESG state Became RFC 7464 (Proposed Standard)
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD Pete Resnick
Send notices to json-chairs@tools.ietf.org, draft-ietf-json-text-sequence@tools.ietf.org
draft-ietf-json-text-sequence-06
json                                                         N. Williams
Internet-Draft                                              Cryptonector
Intended status: Standards Track                         August 22, 2014
Expires: February 23, 2015

            JavaScript Object Notation (JSON) Text Sequences
                    draft-ietf-json-text-sequence-06

Abstract

   This document describes the JSON text sequence format and associated
   media type.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on February 23, 2015.

Copyright Notice

   Copyright (c) 2014 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Williams                Expires February 23, 2015               [Page 1]
Internet-Draft             JSON Text Sequences               August 2014

Table of Contents

   1.    Introduction and Motivation . . . . . . . . . . . . . . . . . 3
   1.1.  Conventions used in this document . . . . . . . . . . . . . . 3
   2.    JSON Text Sequence Format . . . . . . . . . . . . . . . . . . 4
   2.1.  Incomplete JSON texts need not be fatal . . . . . . . . . . . 4
   2.2.  Interoperability note . . . . . . . . . . . . . . . . . . . . 4
   3.    Security Considerations . . . . . . . . . . . . . . . . . . . 5
   4.    IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
   5.    Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . 7
   6.    Normative References  . . . . . . . . . . . . . . . . . . . . 8
         Author's Address  . . . . . . . . . . . . . . . . . . . . . . 9

Williams                Expires February 23, 2015               [Page 2]
Internet-Draft             JSON Text Sequences               August 2014

1.  Introduction and Motivation

   The JavaScript Object Notation (JSON) [RFC7159] is a very handy
   serialization format.  However, when serializing a large sequence of
   values as an array, or a possibly indeterminate-length or never-
   ending sequence of values, JSON becomes difficult to work with.

   Consider a sequence of one million values, each possibly 1 kilobyte
   when encoded -- roughly one gigabyte.  It is often desirable to
   process such a dataset in an incremental manner: without having to
   first read all of it before beginning to produce results.
   Traditionally the way to do this with JSON is to use a "streaming"
   parser, but these are neither widely available, widely used, nor easy
   to use.

   This document describes the concept and format of "JSON text
   sequences", which are specifically not JSON texts themselves but are
   composed of JSON texts.  JSON text sequences can be parsed (and
   produced) incrementally without having to have a streaming parser
   (nor encoder).

1.1.  Conventions used in this document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

Williams                Expires February 23, 2015               [Page 3]
Internet-Draft             JSON Text Sequences               August 2014

2.  JSON Text Sequence Format

   The ABNF [RFC5234] for the JSON text sequence format is as given in
   Figure 1.

     JSON-sequence = *(1*RS JSON-text)
     RS = %x1E; See RFC20
     JSON-text = <given by RFC7159>

                     Figure 1: JSON text sequence ABNF

   In prose: any number of JSON texts, each preceded by one or more
   ASCII RS characters.  Since ASCII RS is a control character it may
   only appear in JSON strings in escaped form, and since RS may not
   appear in JSON texts in any other form, RS unambiguously delimits
   every JSON text (except the final text in the sequence).  Two or more
   RS characters in sequence do not denote "empty" nor missing JSON
   texts.  JSON text sequence encoders MAY emit an RS after emitting a
   JSON text.

   [[anchor1: TODO: Add proper reference to ASCII, for RS.]]

2.1.  Incomplete JSON texts need not be fatal

   JSON text sequence parsers SHOULD NOT abort when RS terminates an
   incomplete JSON text.  Such a situation may arise in contexts where
   append-writes to log files are truncated by the filesystem (e.g., due
   to a crash, or administrative process termination).

2.2.  Interoperability note

   There exist applications which use a format not unlike this one, but
   using LF instead of RS as the separator, or even using no whitespace
   unless it is necessary for disambiguating JSON texts (numbers,
   booleans, null).  JSON text sequence parsers MAY permit this, but
   JSON text sequence encoders MUST only use RS as the separator (as
   described above).

   In some contexts it is useful to write an LF (%x1A) after writing a
   JSON text: it makes working with line-oriented text tools easier.

Williams                Expires February 23, 2015               [Page 4]
Internet-Draft             JSON Text Sequences               August 2014

3.  Security Considerations

   All the security considerations of JSON [RFC7159] apply.

   There is no end of sequence indicator.  This means that "end of
   file", "end of transmission", and so on, can be indistinguishable
   from a logical end of sequence.  Applications where this matters
   should denote end of sequence by convention (e.g., Content-Length in
   HTTP).

Williams                Expires February 23, 2015               [Page 5]
Internet-Draft             JSON Text Sequences               August 2014

4.  IANA Considerations

   The MIME media type for JSON text sequences is application/json-seq.

   Type name: application

   Subtype name: json-seq

   Required parameters: n/a

   Optional parameters: n/a

   Encoding considerations: binary

   Security considerations: See <this document, once published>,
   Section 3.

   Interoperability considerations: Described herein.

   Published specification: <this document, once published>.

   Applicat<http://xml2rfc.tools.ietf.org/public/rfc/bibxml/
   reference.RFC.2119.xml>ions that use this media type: JSON text
   sequences have been used in applications written with the jq
   programming language.

Williams                Expires February 23, 2015               [Page 6]
Internet-Draft             JSON Text Sequences               August 2014

5.  Acknowledgements

   Phillip Hallam-Baker proposed the use of JSON text sequences for
   logfiles and pointed out the need for resynchronization.  James
   Manger contributed the ABNF for resynchronization.  Stephen Dolan
   created <jq>, which uses something like JSON text sequences (with LF
   as the separator between texts on output, and requiring only such
   whitespace as needed to disambiguate on input).  Special thanks to
   Carsten Bormann for suggesting the use of ASCII RS.

Williams                Expires February 23, 2015               [Page 7]
Internet-Draft             JSON Text Sequences               August 2014

6.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234, January 2008.

   [RFC7159]  Bray, T., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, March 2014.

Williams                Expires February 23, 2015               [Page 8]
Internet-Draft             JSON Text Sequences               August 2014

Author's Address

   Nicolas Williams
   Cryptonector, LLC

   Email: nico@cryptonector.com

Williams                Expires February 23, 2015               [Page 9]