JSON Log Format (JSON-L)

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].

A log file consists of a sequence of entries. In a JSON-L log file, each entry is a JSON object [RFC7159].

One of the chief drawbacks to using JSON notation as a log file format is that a log file is by definition a sequence of entries and a JSON document MUST contain exactly one object. Further JSON objects and arrays both require start '{[' and end ']}' markers. Use of the JSON notation as a log file format would thus require a process appending data to a log file to either omit the end markers completely or erase the existing end markers, append the new data the file and write new end markers. Both approaches are highly unsatisfactory, the first violates the JSON encoding rules and the second introduces a risk of a race condition if two processes attempt to update the same log file at the same time. An encoding that permits log entries to be appended to the end of a log file without modifying the existing contents is both safer and more efficient. Since writing data to an append only log file is a common requirement, most platforms already provide efficient and robust primitives to effect append-only updates.

Resynchronization is a mechanism that allows a reader to detect the start of a log file entry. Resynchronization permits a reader to recover in the case that a log entry is corrupted and/or support random access to log file entries. Log files may grow to thousands or millions of entries. When dealling with log files of such size it is frequently desirable to skip forward or backwards to quickly locate an entry added at a specific time. Since JSON objects MAY be of variable lengths and MAY include nested JSON objects, a log file viewer that supports such a random access feature requires a simple means of locating the start of the next entry.

A JSON-L log file consists of a sequence of zero or more JSON objects as specified in [RFC7159] separated by white space that includes at least one newline character.

Since control characters are not permitted inside JSON string values and JSON objects MUST be separated by commas inside a JSON array, the sequence '}' *ws LF *ws '{' can only occur at the end of one log entry and the start of the next:'

JSON-L is limited to an encoding and does not impose semantics on the JSON tags or values. The W3C Extended Log File format [W3C.WD-logfile-960221] defines a set of tags which MAY be used as tags in the JSON object encoding. [W3C.WD-logfile-960221] specifies this example:

The corresponding JSON-L encoding is:

Although the JSON-L encoding is rather less compact than the WD-Logfile format, it is considerably more flexible. It is not necessary for every entry to specify every field being logged. A writer can add the information that is appropriate in the circumstances.

The security considerations for JSON-L are essentially the same as those for the JSON encoding on which it is based. Specifically, since JSON's syntax is borrowed from Javascript it is possible to use the "eval ()" function in that language to parse entries in a JSON-L log. This constitutes an unacceptable security risk as the text could contain executable code along with data declarations. The same risk may exist in other languages that provide similar functions that execute data as code.

The MIME media type for JSON-Log text is application/json-l. Type name: application Subtype name: json-l Required parameters: n/a Optional parameters: n/a Encoding considerations: binary Security considerations: See [this], Section TBS. Interoperability considerations: Described in [this] Published specification: [this] Applications that use this media type: None (so far) Additional information:

Person & email address to contact for further information: Phillip Hallam-Baker <phill@hallambaker.com> Intended usage: COMMON Restrictions on usage: none Author: Phillip Hallam-Baker Change controller: Phillip Hallam-Baker <phill@hallambaker.com> Note: No "charset" parameter is defined for this registration. Adding one really has no effect on compliant recipients.

This is a minor modification of the JSON encoding developed by Douglas Crockford. Nico Williams provided useful advice on the resynchronization scheme.