Declarative JSON data manipulation
README.md

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, with Json.Codec.Object for records.
  • Json.Value, the generic Json.t tree: constructors, queries and pretty-printers.
  • Json.Error, the located decode errors.
  • Json.Number, exact 64-bit integers.
  • Json.Cursor, a zipper over Json.t addressed by JSON Pointer (RFC 6901), and Json.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.