A dependency-free JSON reader and writer for Common Lisp, with string and
character-stream APIs, explicit object/array mappings, opaque values for JSON
null and false, bounded resource use, and structured diagnostics.
📖 Documentation: https://nerima-lisp.github.io/cl-json-kit/
nix build github:nerima-lisp/cl-json-kitor put the repository where ASDF can find it:
(asdf:load-system "cl-json-kit")The library itself has no external dependencies; only the test system uses
cl-weave. SBCL is the supported implementation — see
Getting Started.
(defparameter *document*
(json-kit:parse
"{\"name\":\"Ada\",\"active\":false,\"note\":null,\"tags\":[\"a\",\"b\"]}"))
(gethash "name" *document*) ; => "Ada", T
(json-kit:json-false-p (gethash "active" *document*)) ; => T
(json-kit:json-null-p (gethash "note" *document*)) ; => T
(json-kit:parse "[1,2,3]" :array-type :list) ; => (1 2 3)
(json-kit:parse "\"\\ud83d\\ude00\"") ; => "😀"
(let ((table (make-hash-table :test #'equal)))
(setf (gethash "name" table) "Ada")
(json-kit:stringify table)) ; => "{\"name\":\"Ada\"}"+json-null+ and +json-false+ are opaque sentinels — test them with
json-null-p and json-false-p rather than depending on their printed form.
parse-prefix returns one value plus its end index, for scanning concatenated
values; read-json reads exactly one value from a character stream without
over-consuming. parse accepts a range with an inclusive :start and an
exclusive :end:
(json-kit:parse "prefix [1,2] suffix" :start 7 :end 12) ; => #(1 2)read-json-line consumes one LF- or CRLF-terminated line and returns the parsed
value and t. Before reading any characters, EOF returns nil, nil. A complete
final value without a newline is accepted; empty lines, incomplete JSON, and
multiple values on one line signal json-parse-error.
See Reading
and Writing for the
option reference.
JSON shape is not inferred from Lisp contents. A JSON object is a hash
table or an alist, chosen with :object-type; a JSON array is a vector or a
list, chosen with :array-type. When writing, hash tables are objects and
vectors and lists are arrays — an alist becomes an object only after an explicit
alist->json-object. An array of pairs can therefore never be silently written
as an object.
| JSON | Default reader result | Writer input |
|---|---|---|
| object | hash table with string keys | hash table with string keys |
| array | vector | vector or proper list |
| string | string | string |
| integer | integer | integer |
| non-integer number | double float | finite float, or a ratio with an exact finite decimal expansion |
true |
t |
t |
false |
+json-false+ |
+json-false+ |
null |
+json-null+ |
+json-null+ |
The value nil is the empty list and is written as [], never as null or
false. Rules for ratios and rejected values are in the
Data Model.
validate-schema accepts a decoded value and schema, using the default parse
representation: hash tables using the equal test with string keys, vectors
for arrays, strings, numbers, t, +json-false+, and +json-null+. Alists,
list arrays, custom sentinel mappings, and hash tables using other tests are
outside this API's contract.
Any hash table in the schema, including within enum values, must use equal;
another hash-table test signals json-schema-error.
(multiple-value-bind (valid-p failures)
(json-kit:validate-schema
(json-kit:parse "{\"count\":\"two\"}")
(json-kit:parse
"{\"type\":\"object\",\"required\":[\"count\"],\"properties\":{\"count\":{\"type\":\"integer\"}}}"))
(values valid-p (mapcar (lambda (failure) (getf failure :path)) failures)))
;; => NIL, ("/count")The result is two values: a boolean and a list of failures. Each failure is a
plist with :path, a JSON Pointer into the value, and :reason, an explanation.
The root pointer is the empty string; object keys escape ~ as ~0 and / as
~1.
Only type, required, properties, enum, items, additionalProperties,
and oneOf are supported. type accepts one type name or an array of names;
integer includes mathematical integers such as 1.0. items applies one
schema to every array element. additionalProperties defaults to true and
accepts true, false, or a schema. oneOf requires exactly one matching schema.
Boolean schemas (true and false) are also accepted.
The entire schema is checked before validating the value. An unsupported
keyword, including annotations such as $schema, $id, and title, or a
malformed schema signals json-schema-error, a subtype of json-kit-error.
No keyword is silently ignored. json-schema-error-path identifies the
location in the schema, and json-schema-error-message explains the error.
See API Reference.
- RFC 8259 conformance tests. The parsing corpus from JSONTestSuite is vendored into the test suite: 95/95 must-accept cases are accepted, 188/188 must-reject cases are rejected, and implementation-defined answers are covered by tests. (details)
- API stability. From 1.0.0 on, the exported surface and its documented behavior follow Semantic Versioning. The test suite checks the export list. (what is and is not covered)
- Default bounds. Reading and writing entry points enforce finite input, output, depth, and element limits, plus an optional wall-clock timeout on SBCL. (limits)
- Diagnostics. Parse and serialization failures signal typed conditions carrying position, line, column, path, and a bounded, sanitized snippet. (error handling)
- Unicode handling.
\uXXXXescapes decode UTF-16 surrogate pairs into a single non-BMP character; lone surrogates are rejected in both directions.
sbcl --script run-tests.lisp # or: nix flake checknix flake check also runs the formatting gate and builds the documentation.
Benchmark harnesses live in benchmark/, and
Development covers
the source layout and conventions.
MIT. See LICENSE.