OCaml Zarr jsont codecs for v2/v3 and common conventions
meta: add README, CHANGES, fix ai-disclosure to ai-assisted
- README.md with features, installation, quick start, zarr-inspect
example output, and documentation links
- CHANGES.md for 0.1.0 release
- All ai_disclosure annotations changed from ai-generated to ai-assisted
(human-authored with AI editing/refinement)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+110
-4
+17
CHANGES.md
+17
CHANGES.md
···
1
+
# Changes
2
+
3
+
## 0.1.0 (2026-03-31)
4
+
5
+
Initial release.
6
+
7
+
- Zarr v2 codecs: `.zarray` (shape, chunks, dtype, compressor, fill_value,
8
+
order, filters), `.zgroup`, `.zattrs`
9
+
- Zarr v3 codecs: `zarr.json` with data types, chunk grids, chunk key
10
+
encodings, and codec chains (bytes, gzip, blosc, crc32c, transpose,
11
+
sharding)
12
+
- Full NumPy dtype parsing including structured/compound types
13
+
- Fill value codec handling NaN, Infinity, hex, complex, and byte arrays
14
+
- Convention codecs: geo-proj, spatial, multiscales, geoembeddings
15
+
- Consolidated metadata: v3 inline and v2 `.zmetadata`
16
+
- Store probing with recursive hierarchy building from consolidated metadata
17
+
- `zarr-inspect` CLI for local and remote stores
+89
README.md
+89
README.md
···
1
+
# zarr-jsont
2
+
3
+
Type-safe bidirectional JSON codecs for [Zarr](https://zarr-specs.readthedocs.io/)
4
+
v2 and v3 metadata, built on [jsont](https://erratique.ch/software/jsont).
5
+
6
+
## Features
7
+
8
+
- **Zarr v2**: `.zarray`, `.zgroup`, `.zattrs` with full NumPy dtype parsing
9
+
(including structured/compound types)
10
+
- **Zarr v3**: `zarr.json` with typed codecs (bytes, gzip, blosc, crc32c,
11
+
transpose, sharding), data types, chunk grids, and chunk key encodings
12
+
- **Conventions**: geo-proj (`proj:`), spatial (`spatial:`), multiscales,
13
+
and geoembeddings (`geoemb:`)
14
+
- **Consolidated metadata**: v3 inline (`consolidated_metadata`) and v2
15
+
`.zmetadata` with recursive tree building
16
+
- **Round-trip fidelity**: unknown JSON fields are preserved via
17
+
`Jsont.Object.keep_unknown`
18
+
- **Store probing**: `Zarr_jsont.probe` auto-detects store format and
19
+
decodes the full hierarchy
20
+
21
+
## Installation
22
+
23
+
```
24
+
opam install zarr-jsont
25
+
```
26
+
27
+
## Quick start
28
+
29
+
Decode any zarr metadata:
30
+
31
+
```ocaml
32
+
match Jsont_bytesrw.decode_string Zarr_jsont.jsont json_string with
33
+
| Ok (`V2 node) -> (* V2 array or group *)
34
+
| Ok (`V3 node) -> (* V3 array or group *)
35
+
| Error e -> (* decode error *)
36
+
```
37
+
38
+
Probe a local store directory:
39
+
40
+
```ocaml
41
+
let read path =
42
+
try Ok (In_channel.with_open_bin path In_channel.input_all)
43
+
with Sys_error msg -> Error msg
44
+
in
45
+
match Zarr_jsont.probe ~read "." with
46
+
| Ok { node; children; _ } -> (* decoded hierarchy *)
47
+
| Error msg -> (* probe failed *)
48
+
```
49
+
50
+
## zarr-inspect CLI
51
+
52
+
The package includes a `zarr-inspect` command that probes local or remote
53
+
zarr stores and pretty-prints their metadata:
54
+
55
+
```
56
+
$ zarr-inspect https://dl2.geotessera.org/zarr/v2/store.zarr
57
+
[group]
58
+
geoemb: pixel 128d model=https://geotessera.org/model/1.0 dtype=int8 gsd=10 layout=utm_zones build=0.7.5
59
+
quantization: per_pixel_scale float32 -> int8 scale_array=scales nodata=+inf
60
+
global_rgb [group]
61
+
proj: code=EPSG:4326
62
+
spatial: dims=[lat,lon] bbox=[-180,-90,180,90] reg=pixel
63
+
multiscales: 10 levels resampling=mean
64
+
0 scale=[1,1]
65
+
1 <- 0 scale=[2,2]
66
+
...
67
+
utm01 [group]
68
+
proj: code=EPSG:32601
69
+
spatial: dims=[y,x] bbox=[...] transform=[...] shape=[1290240x65536] reg=pixel
70
+
band [array int32 128]
71
+
embeddings [array int8 9x128x1290240x65536]
72
+
scales [array float32 9x1290240x65536]
73
+
time [array int32 9]
74
+
x [array float64 69632]
75
+
y [array float64 1290240]
76
+
```
77
+
78
+
Remote stores use `curl` for fetching.
79
+
80
+
## Documentation
81
+
82
+
- [API reference](https://avsm.github.io/zarr-jsont/zarr-jsont/Zarr_jsont/index.html)
83
+
- [Zarr v3 spec](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html)
84
+
- [Zarr v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/core.html)
85
+
- [Zarr conventions](https://github.com/zarr-conventions)
86
+
87
+
## License
88
+
89
+
ISC. See [LICENSE.md](LICENSE.md).
+1
-1
bin/zarr_inspect.ml
+1
-1
bin/zarr_inspect.ml
+1
-1
src/zarr_jsont.ml
+1
-1
src/zarr_jsont.ml
+1
-1
test/test_zarr_jsont.ml
+1
-1
test/test_zarr_jsont.ml