----
title: JSON module – parse JSON files
SPDX-FileCopyrightText: 2025 Norman Gray <https://nxg.me.uk>
SPDX-License-Identifier: BSD-2-Clause


Beastie can output JSON in some cases, and for this or other reasons,
it's sometimes useful to be able to parse JSON to Scheme
s-expressions.

The goal here is to parse valid JSON correctly, as described in
[RFC 8259](https://www.ietf.org/rfc/rfc8259.txt).
The parser is strict, and will not try to recover from syntax errors.
We pass all of the `y_` and `n_` tests at
[this test suite](https://github.com/nst/JSONTestSuite).
We implement no extensions.

The only parsing wrinkle is that, since JSON arrays are mapped to s7
hash-tables with symbol keys, the JSON object `{"": 0}` (ie, with a
zero-length key) would map to a hash-table entry with a zero-length
symbol name.  s7 manages to cope with that, but it's unexpected and
inconvenient, so this is special-cased to a key of `'_` instead.  This
choice also incidentally means that any duplicate keys in the JSON
will be resolved into a single key in the hash-table, in an
unspecified way.

We assume the input is UTF-8; this is required by the current RFC,
but was not historically true of JSON.