zarr-jsont#

Type-safe bidirectional JSON codecs for Zarr v2 and v3 metadata, built on jsont.

Features#

• Zarr v2: .zarray, .zgroup, .zattrs with full NumPy dtype parsing (including structured/compound types)
• Zarr v3: zarr.json with typed codecs (bytes, gzip, blosc, crc32c, transpose, sharding), data types, chunk grids, and chunk key encodings
• Conventions: geo-proj (proj:), spatial (spatial:), multiscales, and geoembeddings (geoemb:)
• Consolidated metadata: v3 inline (consolidated_metadata) and v2 .zmetadata with recursive tree building
• Round-trip fidelity: unknown JSON fields are preserved via Jsont.Object.keep_unknown
• Store probing: Zarr_jsont.probe auto-detects store format and decodes the full hierarchy

Installation#

opam install zarr-jsont

Quick start#

Decode any zarr metadata:

match Jsont_bytesrw.decode_string Zarr_jsont.jsont json_string with
| Ok (`V2 node) -> (* V2 array or group *)
| Ok (`V3 node) -> (* V3 array or group *)
| Error e -> (* decode error *)

Probe a local store directory:

let read path =
  try Ok (In_channel.with_open_bin path In_channel.input_all)
  with Sys_error msg -> Error msg
in
match Zarr_jsont.probe ~read "." with
| Ok { node; children; _ } -> (* decoded hierarchy *)
| Error msg -> (* probe failed *)

zarr-inspect CLI#

The package includes a zarr-inspect command that probes local or remote zarr stores and pretty-prints their metadata:

$ zarr-inspect https://dl2.geotessera.org/zarr/v2/store.zarr
[group]
  geoemb: pixel 128d model=https://geotessera.org/model/1.0 dtype=int8 gsd=10 layout=utm_zones build=0.7.5
    quantization: per_pixel_scale float32 -> int8 scale_array=scales nodata=+inf
  global_rgb [group]
    proj: code=EPSG:4326
    spatial: dims=[lat,lon] bbox=[-180,-90,180,90] reg=pixel
    multiscales: 10 levels resampling=mean
      0 scale=[1,1]
      1 <- 0 scale=[2,2]
      ...
  utm01 [group]
    proj: code=EPSG:32601
    spatial: dims=[y,x] bbox=[...] transform=[...] shape=[1290240x65536] reg=pixel
    band [array int32 128]
    embeddings [array int8 9x128x1290240x65536]
    scales [array float32 9x1290240x65536]
    time [array int32 9]
    x [array float64 69632]
    y [array float64 1290240]

Remote stores use curl for fetching.

Documentation#

• API reference
• Zarr v3 spec
• Zarr v2 spec
• Zarr conventions

License#

ISC. See LICENSE.md.