FSON is a superset of JSON designed for files that people edit by hand — configuration, above all. Every valid JSON document is already a valid FSON document; FSON adds the things you reach for when you maintain a file by hand and JSON gets in the way:

  • Comments — // to end of line, and /* … */ blocks that nest.
  • Bare keys — host: instead of "host": for identifier-like names.
  • Disabled members — a -- prefix switches a member off without deleting it; queries skip it, but it is written back intact.
  • %include directives — pull defaults in from another file.
  • |-block strings — multi-line string values without escaping every newline.

Since v0.9.0.0, FSON is also a pragmatic superset of JSON5: single-quoted strings, trailing commas, hex / Infinity / NaN numbers, a leading or trailing decimal point, extended whitespace, and any value (not just an object) as the document root are all accepted.

// service configuration
{
  service_name: 'billing',
  database: {
    host: "db.internal.example",   // production endpoint
    --user: "root",                /* disabled credential, kept for reference */
    "connection timeout": 2.50,
  },
  retries: [1, 2, 5,],
  max_connections: 0x40,
  timeout: Infinity,
  --debug: false
}

Reading these pages

This section is the prose companion to the normative grammar, which is a set of railroad diagrams (one per production) generated from the .rrd sources in the fson repository's docs/notation/ directory. Each page here covers one topic and shows the diagram(s) for the productions it describes. When prose and diagram seem to disagree, the diagram wins.

In a railroad diagram, follow the line left to right:

  • a rounded box is a literal token — type it exactly;
  • a square box is a reference to another production;
  • a branch is a choice; a loop back is "zero or more" or "one or more".

The Grammar reference page collects every diagram on one page, in file-number order, for quick lookup.

The two deliberate gaps

FSON is almost exactly "JSON5 plus FSON's own additions". Two narrow places differ on purpose:

  1. Nested block comments. JSON5 forbids them; FSON keeps them, because commenting out a region that already contains a block comment must be safe.
  2. Bare-key grammar. FSON's name production is narrower than JSON5's full ECMA-262 IdentifierName — no $foo, no _x, no Unicode identifier characters bare. Quote those keys.

Everything else is JSON5's grammar plus FSON's additions. See FSON and JSON5 for the exact statement.