fson

FSON is a human-friendly superset of JSON — and, since v0.9.0.0, a pragmatic superset of JSON5 too — and fson is its C++ library: parse, query, modify and rewrite FSON files without losing a single comment.

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

What FSON adds to JSON

• Comments — // line and nestable /* block */ comments, anywhere.
• Bare keys — host: instead of "host": for identifier-like names.
• Disabled members — prefix any member with -- to switch it off: queries treat it as absent, yet it is preserved and written back intact.
• JSON5 features — single-quoted strings, trailing commas, hex/ Infinity/-Infinity/NaN numbers, and extended whitespace are all accepted; the document root may be any value, not just an object.
• Everything else is plain JSON: same values, same strings, same numbers.

Every valid JSON document is already a valid FSON document, and so is almost every JSON5 document — see docs/notation.md, "FSON and JSON5", for the two narrow, deliberate exceptions.

What the library guarantees

• Lossless round-trips. Comments (with their positions), member order, quoted-vs-bare key form, -- markers and the exact spelling of numbers (1.50 stays 1.50) all survive a load–modify–save cycle. Output is consistently pretty-printed.
• Robust parsing. Errors are collected with file/line/column and parsing continues at the next safe point, so one typo does not hide the rest of the file. Nothing throws on bad input.
• A practical API. Dotted-path access with typed getters (doc.getInteger("database.port", 5432), "servers[0].port"), a full document object model underneath, and a one-line façade:

#include "fson/Fson.hh"
using namespace fedem::fson;

auto result = Fson::load( "config.json" );
if( result.ok( ) )
{
  long long port = result.document->getInteger( "database.port", 5432 );
  result.document->setPath( "database.host",
                            std::make_unique< String >( "db1" ) );
  Fson::save( *result.document, "config.json" );
}

fson-check

The bundled CLI tool validates and reformats FSON files:

fson-check config.json                 # report errors, pretty-print to stdout
fson-check -i config.json              # reformat in place (only when error-free)
fson-check --output out.json in.json   # write the result elsewhere
fson-check --json config.json          # convert to plain JSON (for jq, etc.)
fson-check --json5 config.json         # convert to JSON5 (keeps comments and bare keys)
fson-check --bare config.json          # unquote keys where the grammar allows

Building

git clone <repository-url> fson
cd fson
cmake -B build && cmake --build build
ctest --test-dir build      # optional, needs GoogleTest
cmake --install build

Requires CMake ≥ 3.20 and a C++23 compiler (GCC 12+). The installed public API is C++17-compatible. cparse (the parsing core) is a Conan package — resolve it with conan install . first, or make it available to CMake yourself. See docs/integration.md.

Released source archives (.tar.gz / .zip + .sha256) are on <https://fson.fedem.eu/downloads>.

Documentation

Document	Content
docs/notation.md	the FSON file format, with railroad diagrams in docs/notation/
docs/getting_started.md	load → query → modify → save tutorial
docs/reference_manual.md	every class and function
docs/integration.md	adding fson to your build (pkg-config, CMake, packages)
generated API	Doxygen tree — cmake --build build --target docs (needs Doxygen; dot adds the graphs), published at <https://fson.fedem.eu/api>
examples/	annotated sample FSON files

Repository layout

apps/fson-check/        command-line validator / formatter
docs/                   documentation; docs/notation/ holds the grammar
examples/               sample FSON files
libs/internal/sdk/fson/ the fson library
tests/                  GoogleTest suites

The parsing core cparse is a separate Conan package (cparse/[>=1.0 <2]), not a vendored tree.

License

MIT — Copyright © Fehmi Demiralp (FEDEM). See LICENSE. The name FSON and the FEDEM branding are not covered by the code licence — see TRADEMARKS.md.

Homepage: https://fson.fedem.eu