Skip to content

About

A small, unambiguous JSON reader/writer for Common Lisp

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

51 Commits

Folders and files

Repository files navigation

cl-json-kit

CI Publish documentation License: MIT

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/

Install

nix build github:nerima-lisp/cl-json-kit

or 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.

Use

(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 representation

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.

JSON Schema subset

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.

Tested and bounded behavior

  • 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. \uXXXX escapes decode UTF-16 surrogate pairs into a single non-BMP character; lone surrogates are rejected in both directions.

Develop

sbcl --script run-tests.lisp   # or: nix flake check

nix flake check also runs the formatting gate and builds the documentation. Benchmark harnesses live in benchmark/, and Development covers the source layout and conventions.

License

MIT. See LICENSE.

About

A small, unambiguous JSON reader/writer for Common Lisp

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages