- OCaml 100%
nox-json #
Warning. This is a work-in-progress experimental fork of jsont. Do not use it in production; use jsont instead.
Declarative JSON codecs for OCaml, with located errors and streaming I/O.
nox-json decodes JSON straight into your own OCaml types, and encodes them
back. You write a codec for each type, for instance a record with one line
per member, and that codec drives decoding, encoding, queries and updates. No
generic tree is built in between. A document of the wrong shape is refused
with an error that carries the location of the offending value.
The codecs are in Json.Codec, the object combinators in
Json.Codec.Object. When a generic tree is what you want, it is Json.t,
with constructors and operations in Json.Value; the top-level Json.Object
is only one of its constructors.
Text goes in and out through Json.of_string and Json.to_string, or
Json.of_reader and Json.to_writer for byte streams. Source locations are
tracked by default, layout is kept if you ask, and both directions run under
effect-based concurrency. Json.Number reads and writes signed and unsigned
64-bit integers exactly. The sub-library nox-json.geojson
handles GeoJSON (RFC 7946), and
the separate package nox-json-js converts to and from JavaScript values in
the browser.
The vocabulary follows RFC 8259.
nox-json is a fork of dbuenzli/jsont.
The decoder and the codec model are Daniel Bünzli's; the public API is
arranged differently, and CHANGES.md has the details.
Contents #
Installation #
Install with opam:
$ opam install nox-json
If opam cannot find the package, it may not yet be released in the public
opam-repository. Add the overlay repository, then install it:
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install nox-json
The library is nox-json and its module is Json. It needs OCaml 5.1 or
later, bytesrw, fmt, ascii, nox-loc, nox-hex and nox-jsonptr;
nox-json-js adds brr.
Usage #
A record codec names each member, the codec of its value and how to read it back from the record:
type item = { task : string; done_ : bool }
let item_codec =
Json.Codec.Object.map ~kind:"item" (fun task done_ -> { task; done_ })
|> Json.Codec.Object.member "task" Json.Codec.string ~enc:(fun i -> i.task)
|> Json.Codec.Object.member "done" Json.Codec.bool ~enc:(fun i -> i.done_)
|> Json.Codec.Object.seal
The same value decodes and encodes:
# Json.of_string item_codec {|{ "task": "write the README", "done": false }|};;
- : (item, Json.Error.t) result =
Ok {task = "write the README"; done_ = false}
# Json.to_string item_codec { task = "ship it"; done_ = true };;
- : string = "{\"task\":\"ship it\",\"done\":true}"
A document of the wrong shape is refused with the location of the value at fault and of each value that encloses it:
# match Json.of_string item_codec {|{ "task": "x", "done": "no" }|} with
| Ok _ -> ()
| Error e -> Fmt.pr "%a@." Json.Error.pp e;;
File "-", line 1, characters 23-24:
Expected bool but found string
File "-", line 1, characters 15-21: in member done of
File "-", line 1, characters 0-24: item object
- : unit = ()
When no OCaml type fits, build a generic Json.t with the constructors of
Json.Value:
# let open Json.Value in
to_string (object' [ member (name "ok") (bool true); member (name "n") (int 3) ]);;
- : string = "{\"ok\":true,\"n\":3}"
Read one leaf of a generic value with Json.Value.find and the typed reads
of Json.Value.Find, each following a list of member names:
# let v = Json.Value.of_string_exn {|{"author": {"login": "alice"}}|} in
Json.Value.Find.string [ "author"; "login" ] v;;
- : string option = Some "alice"
Examples #
examples has one codec per file, from the quickstart and a
cookbook up to JSON-RPC and TopoJSON. Each is round-tripped against a
committed document by a test_*.ml runner, so an example that drifts from
the API breaks dune test. The GeoJSON library, nox-json.geojson, is in
lib/geojson.
API #
lib/json.mli is the reference, which dune build @doc
renders with odoc; in a switch where the package and odig are installed,
odig doc nox-json opens it. The main modules are:
Json.Codec, the typed codecs, withJson.Codec.Objectfor records.Json.Value, the genericJson.ttree: constructors, queries and pretty-printers.Json.Error, the located decode errors.Json.Number, exact 64-bit integers.Json.Cursor, a zipper overJson.taddressed by JSON Pointer (RFC 6901), andJson.Tape, a simdjson-compatible tape for random access by word index.
License #
ISC. See LICENSE.md. Three files in examples/ carry a
CC0-1.0 licence header instead.