Manual

Getting Started 🔗

Judo is an embeddable JSON and JSON5 parser designed with simplicity and robustness in mind. It implements an incremental, non-recursive scanner that returns semantic elements and an optional parser for building an in-memory tree structure.

Judo is robust. It can detect malformed UTF-8 sequences and problematic conditions not fully specified in the JSON specification, such as mismatched UTF-16 surrogate pairs. The implementation is MISRA C:2012 compliant, making it ideal for high-assurance software.

Judo is highly configurable, offering support for three different JSON standards:

  • RFC 4627 - The original JSON standard “discovered” by Douglas Crockford.
  • RFC 8259 - The latest JSON standard.
  • JSON5 - An unofficial JSON extension that incorporates features from ECMAScript 5.1 (ES5).

The most notable difference between RFC 4627 and RFC 8259 is that in RFC 4627, the root value must be an array or an object, whereas RFC 8259 allows any valid JSON value.

Judo supports extensions for comments and trailing commas, which can be enabled for both RFC 4627 and RFC 8259. When both features are enabled, Judo becomes a JSONC parser. Both features are already part of the JSON5 specification.

JSON5 was selected over competing extensions because it extends JSON with features present in ES5, rather than inventing new syntax. Like standard JSON, JSON5 syntax is valid JavaScript syntax.

Building from Source 🔗

To build Judo from source, download the latest release and run:

$ ./configure
$ make
$ make install

Alternatively, you can build it with CMake.

Judo offers several configuration options, which are explored in the subsections below.

Choose a JSON Standard 🔗

Judo allows you to select the JSON standard at configuration time. By default, it builds against the JSON5 standard.

To specify the JSON standard during configuration, run:

$ ./configure --enable-json-standard=<value>

or with CMake:

$ cmake -DJUDO_JSON_STANDARD=<value>

Where <value> must be rfc4627, rfc8259, or json5. For example, to build an RFC 8259 compliant parser, configure the project with:

$ ./configure --enable-json-standard=rfc8259

or with CMake:

$ cmake -DJUDO_JSON_STANDARD=rfc8259

Choose a Floating Point Storage Type 🔗

Judo allows you to specify the floating-point storage type to use or disable floating point support entirely. By default, Judo detects the widest floating-point type your C compiler supports.

To specify the floating-point type during configuration:

$ ./configure --enable-json-float-storage=<value>

or with CMake:

$ cmake -DJUDO_FLOAT_STORAGE=<value>

Where <value> must be auto (for auto-detection), float, double, longdouble, or disabled (to disable floating-point support). For example, to use the double floating point storage type, configure the project with:

$ ./configure --enable-json-float-storage=double

or with CMake:

$ cmake -DJUDO_FLOAT_STORAGE=double

Optionally Enable JSON Extensions 🔗

Judo supports optional extensions for trailing commas and JavaScript-style comments. These extensions are incorporated into the JSON5 standard and are enabled by default when building against it.

The trailing commas extension allows you to place a comma after the last element in an array or object. The comments extension allows both single-line and multi-line JavaScript-style comments.

By default, Judo disables these extensions, but you can enable them during project configuration:

$ ./configure --enable-json-comments --enable-json-trailing-commas

or with CMake:

$ cmake -DJUDO_ENABLE_COMMENTS=ON -DJUDO_ENABLE_TRAILING_COMMAS=ON

Change the Maximum Nesting Depth 🔗

Judo implements a non-recursive scanner and parser. It avoids using the C call stack by relying on a virtual stack with a configurable maximum size. This complies with Rule 17.2 of MISRA C:2012, which requires that functions be non-recursive.

By default, the maximum nesting size is 16, meaning Judo can process arrays and objects with a cumulative nesting depth of up to 16. You can adjust the maximum nesting depth at configuration time. For example, to increase the maximum depth to 32, configure with:

$ ./configure --enable-json-maximum-depth=32

or with CMake:

$ cmake -DMAXIMUM_NESTING_DEPTH=32

You can specify any value between 0 and 256.

Excluding the Parser 🔗

The Judo scanner honors all Mandatory, Required, and Advisory rules defined by MISRA C:2012. However, the Judo parser honors all MISRA rules except Advisory Rules 11.5 and 19.2. If strict conformance is required, the parser interface can be disabled at configuration time with:

$ ./configure --disable-json-parser

or with CMake:

$ cmake -DJUDO_ENABLE_PARSER=OFF

Command-line Interface 🔗

The Judo distribution includes a command-line interface (CLI), named judo, which reads JSON from stdin and echos it back to stdout, optionally pretty printing it depending on the options given. The CLI does not attempt to be MISRA compliant.

You can review all command-line options by running judo with the -h or --help option or by reviewing its man page with man judo.1.