JSON-sequence = ws *(JSON-text ws LF ws)
  LF = <given by RFC5234>
  ws = <given by RFC7159>
  JSON-text = <given by RFC7159>

Figure 1: JSON text sequence ABNF

As long as a JSON text sequence consist of complete JSON texts, the only requirement is that whitespace separate any non-object, array, string top-level values from neighboring texts. The simplest way to ensure this is to require such whitespace, and furthermore it is convenient to use a newline, as we'll see in Section 2.1. Therefore we impose one requirement:

• JSON text sequence encoders MUST emit a newline after any JSON text.

2.1. Ambiguities

Otherwise An input of 'truefalse' is not a valid sequence of two JSON values, true and false! Neither is 'true0' a valid sequence of true and zero. Some existing JSON parsers that might be used to construct sequence parsers might in fact accept such sequences, resulting in erroneous parsing of sequences of two or more numbers. E.g., a sequence of two numbers, 4 and 2, encoded without the required whitespace between them would parse incorrectly as the number 42.

Such ambiguities is resolved by requiring that encoders emit a whitespace separator (specifically: a newline) after each text.

2.1.1. Ambiguities Resulting from Partial Texts

Another kind of ambiguity arises when a JSON text sequence contains partial texts. Such a sequence can result when using “append writes” to write to a file. For example, many systems might commit partial writes to stable storage then fail to complete the remainder of a write as a result of, e.g., power failures; upon recovery the file may then end with a partial JSON text.

[CREF1]Perhaps we should add a note about what POSIX requires w.r.t. O_APPEND, and how POSIX is agnostic as to power failures and so on. The point being that even where a standard imposes strong atomicity requirements as to append writes, there are good reasons why that might be difficult to obtain under exceptional circumstances.

Consider a portion of a JSON text sequence such as:

 { "foo":
 { "bar": 42 }
 }

How can we tell that the first line isn't part of an incomplete JSON text? We can't, especially if the third line were missing.

In the common case JSON text sequence parsers assume every text is complete, and abort processing if any one text fails to parse. However, for logfiles, there is value is being able to recover from such situations. Recovery is described in Section 3.

2.2. Rationale for Choice of LF as the Text Separator

A variety of characters or character sequences (even non-whitespace characters) could have been used as the JSON text separator in JSON text sequences. The rationale for using newline (LF) as the separator is as follows:

• it matches the 'ws' ABNF rule in [RFC7159] (as do CR, HTAB, and SP);
• it is always escaped in encoded JSON strings, therefore it is safe remove LFs (or replace then with other JSON whitespace characters) from any JSON text (this is also true of CR and HTAB, but not SP);
• it is generally understood as the end-of-line marker by line-oriented tools;
• at least one JSON text sequence implementation exists and has existed for some time [XXX add external informative reference to https://stedolan.github.com/jq], and it uses LF as the JSON text separator.

Note that JSON text sequence writers may (and should) use CR LF as the text separator where the end-of-line marker is expected to be CR LF.

3. Use for Logfiles, or How to Resynchronize Following Truncated entries

The JSON Text Sequence format is useful for logfiles, as those are generally (and atomically) appended to on an ongoing basis. I.e., logfiles are of indeterminate length, at least right up until they are closed.

The partial-write ambiguities described in Section 2.1.1 come up in the case of logfiles.

As long as all texts in the logfile sequence are followed by a newline, it is possible to detect a subsequent JSON text written after an entry that fails to parse: either the first or the second subsequent, complete JSON texts. Figure 2 shows an ABNF rule for detecting the boundary between a non-truncated [and some truncated] JSON text and the next JSON text in a sequence. This rule assumes that only valid JSON texts are written to a sequence.

  boundary = endchar *text-sep *ws startchar
  text-sep = *(SP / HTAB / CR) LF ; these are from RFC5234
  endchar = ( "}" / "]" / DQUOTE / "e" / "l" / DIGIT )
  startchar =  ( "{" / "[" / DQUOTE / "t" / "f" / "n" / "-" / DIGIT )
  ws = <given by RFC7159>

 null
 { "foo":"hello world" }
 "a broken writenull
 "a complete write"