Formata.Codec.JSON5 (formata v0.3.5)

Copy Markdown View Source

JSON5 codec (JSON5 1.0.0).

JSON5 is a separate format, not a mode of :json: use Formata.decode(input, :json5) and Formata.encode(data, :json5).

Decoding

The full JSON5 1.0.0 grammar is accepted:

  • // and /* */ comments, and a trailing comma in arrays and objects
  • single- or double-quoted strings, with the ECMAScript 5.1 escapes (\v, \0, \xHH, \uHHHH, \', any other character escaping itself) and line continuations (a backslash before LF, CR, CRLF, U+2028, or U+2029); U+2028 and U+2029 may appear unescaped in strings
  • unquoted object keys that are ECMAScript 5.1 IdentifierNames, including Unicode letters and \uHHHH escapes. Character classes come from the Unicode general-category tables of the runtime's PCRE library (a newer Unicode version than ES5.1 references)
  • the additional JSON5 whitespace (VT, FF, NBSP, BOM, U+2028, U+2029, and other Zs space separators)
  • numbers with a leading +, leading or trailing decimal point (.5, 5.), hexadecimal integers (0x1F, -0xff), Infinity, -Infinity, +Infinity, and NaN (also +NaN / -NaN)

Decoded values use the portable domain (see Formata.Codec):

  • object keys are strings (never atoms); duplicate keys, compared after unescaping ({a: 1, "\u0061": 2}), are :parse / :duplicate_key errors
  • numbers without a fraction or exponent (decimal or hexadecimal) are integers, others are floats. Infinity, -Infinity, and NaN become :infinity, :negative_infinity, and :nan. The sign of NaN is not kept. -0 is the integer 0, while -0.0 stays the float -0.0
  • a finite literal outside the float range (1e400) is a :parse / :syntax error; it never becomes Infinity. Integers are limited to 1024 digits, like :json
  • a \u escape of an unpaired UTF-16 surrogate cannot be represented in a UTF-8 string and is a :syntax error

Errors carry the byte offset and the line/column derived from it (lines are counted by LF). JSON5 decoding takes no options: comments and trailing commas are always allowed, so :comments and :trailing_commas are rejected as :invalid_option.

Encoding

The output is deterministic and minimal: the JSON subset of JSON5, with object keys sorted and quoted, plus Infinity, -Infinity, and NaN for :infinity, :negative_infinity, and :nan. No comments, unquoted keys, or trailing commas are produced. The domain is the JSON domain plus those three values; everything else is rejected with :encode errors.

Options:

  • :pretty - indent with two spaces (default false)

Conversions

Formata.convert(input, :json5, :json) works for data inside the JSON domain. Non-finite numbers are rejected by the JSON encoder with :unrepresentable errors at their path; replace them explicitly (for example transforms: [:special_floats_to_strings]) when that loss is acceptable. JSON Schema validation likewise rejects them as :non_json_value.