OCaml Zarr jsont codecs for v2/v3 and common conventions
Add zarr-jsont implementation plan
15 tasks covering bottom-up build: shared types, v2/v3 modules,
conventions, attrs composition, dispatch codec, and roundtrip tests.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+3239
+3239
docs/superpowers/plans/2026-03-30-zarr-jsont.md
+3239
docs/superpowers/plans/2026-03-30-zarr-jsont.md
···
1
+
# zarr-jsont Implementation Plan
2
+
3
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+
**Goal:** Build type-safe bidirectional jsont codecs for Zarr v2/v3 JSON metadata with convention support.
6
+
7
+
**Architecture:** Bottom-up build: shared types first (fill_value, dtype, other_codec/ext), then v2/v3 modules, then conventions, then attrs composition, then top-level dispatch. Each module is self-contained with its own codec and tests.
8
+
9
+
**Tech Stack:** OCaml, jsont 0.2.0, jsont.bytesrw, dune 3.0
10
+
11
+
---
12
+
13
+
### Task 1: Project scaffold and build system
14
+
15
+
**Files:**
16
+
- Create: `dune-project`
17
+
- Create: `zarr-jsont.opam`
18
+
- Create: `src/dune`
19
+
- Create: `test/dune`
20
+
- Create: `test/test_zarr_jsont.ml`
21
+
- Create: `src/zarr_jsont.ml`
22
+
- Create: `src/zarr_jsont.mli`
23
+
24
+
- [ ] **Step 1: Create dune-project**
25
+
26
+
```
27
+
(lang dune 3.0)
28
+
(name zarr-jsont)
29
+
(generate_opam_files true)
30
+
31
+
(package
32
+
(name zarr-jsont)
33
+
(synopsis "Jsont codecs for Zarr v2 and v3 metadata")
34
+
(depends
35
+
(ocaml (>= 5.1))
36
+
(jsont (>= 0.2.0))
37
+
(bytesrw (>= 0.1.0))))
38
+
```
39
+
40
+
- [ ] **Step 2: Create src/dune**
41
+
42
+
```
43
+
(library
44
+
(name zarr_jsont)
45
+
(public_name zarr-jsont)
46
+
(libraries jsont jsont.bytesrw))
47
+
```
48
+
49
+
- [ ] **Step 3: Create test/dune**
50
+
51
+
```
52
+
(test
53
+
(name test_zarr_jsont)
54
+
(libraries zarr_jsont jsont.bytesrw))
55
+
```
56
+
57
+
- [ ] **Step 4: Create minimal src/zarr_jsont.mli**
58
+
59
+
```ocaml
60
+
(** Jsont codecs for Zarr v2 and v3 metadata. *)
61
+
```
62
+
63
+
- [ ] **Step 5: Create minimal src/zarr_jsont.ml**
64
+
65
+
```ocaml
66
+
(* Zarr jsont codecs *)
67
+
```
68
+
69
+
- [ ] **Step 6: Create test stub**
70
+
71
+
```ocaml
72
+
let () = print_endline "zarr-jsont tests: ok"
73
+
```
74
+
75
+
- [ ] **Step 7: Verify build**
76
+
77
+
Run: `dune build && dune test`
78
+
Expected: Builds cleanly, test prints "zarr-jsont tests: ok"
79
+
80
+
- [ ] **Step 8: Commit**
81
+
82
+
```bash
83
+
git add dune-project src/dune test/dune src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
84
+
git commit -m "scaffold: project structure with dune build"
85
+
```
86
+
87
+
---
88
+
89
+
### Task 2: Other_codec and Other_ext escape hatches
90
+
91
+
**Files:**
92
+
- Modify: `src/zarr_jsont.ml`
93
+
- Modify: `src/zarr_jsont.mli`
94
+
- Modify: `test/test_zarr_jsont.ml`
95
+
96
+
These are the catch-all types for unrecognized codecs (v2) and extensions (v3). They must be defined first since other modules depend on them.
97
+
98
+
- [ ] **Step 1: Write failing test for Other_codec roundtrip**
99
+
100
+
In `test/test_zarr_jsont.ml`:
101
+
102
+
```ocaml
103
+
let decode c s = match Jsont_bytesrw.decode_string c s with
104
+
| Ok v -> v | Error e -> failwith e
105
+
106
+
let encode c v = match Jsont_bytesrw.encode_string c v with
107
+
| Ok s -> s | Error e -> failwith e
108
+
109
+
let test_other_codec () =
110
+
let json = {|{"id":"custom_codec","param1":42,"param2":"hello"}|} in
111
+
let v = decode Zarr_jsont.Other_codec.jsont json in
112
+
assert (Zarr_jsont.Other_codec.name v = "custom_codec");
113
+
let json' = encode Zarr_jsont.Other_codec.jsont v in
114
+
let v' = decode Zarr_jsont.Other_codec.jsont json' in
115
+
assert (Zarr_jsont.Other_codec.name v' = "custom_codec");
116
+
print_endline "test_other_codec: ok"
117
+
118
+
let () = test_other_codec ()
119
+
```
120
+
121
+
- [ ] **Step 2: Run test to verify it fails**
122
+
123
+
Run: `dune test`
124
+
Expected: FAIL — `Other_codec` not defined
125
+
126
+
- [ ] **Step 3: Implement Other_codec**
127
+
128
+
In `src/zarr_jsont.mli`, add:
129
+
130
+
```ocaml
131
+
module Other_codec : sig
132
+
type t
133
+
val name : t -> string
134
+
val configuration : t -> Jsont.json
135
+
val make : string -> Jsont.json -> t
136
+
val jsont : t Jsont.t
137
+
end
138
+
```
139
+
140
+
In `src/zarr_jsont.ml`, add:
141
+
142
+
```ocaml
143
+
module Other_codec = struct
144
+
type t = { name : string; configuration : Jsont.json }
145
+
let name t = t.name
146
+
let configuration t = t.configuration
147
+
let make name configuration = { name; configuration }
148
+
149
+
let jsont =
150
+
let decode name unknown =
151
+
(* unknown is a JSON object with remaining members *)
152
+
{ name; configuration = unknown }
153
+
in
154
+
Jsont.Object.map ~kind:"Other_codec" decode
155
+
|> Jsont.Object.mem "id" Jsont.string ~enc:(fun t -> t.name)
156
+
|> Jsont.Object.keep_unknown Jsont.json_mems ~enc:(fun t ->
157
+
match t.configuration with
158
+
| Jsont.Object (_, mems) ->
159
+
List.fold_left (fun acc ((_,name), v) ->
160
+
Jsont.Object (Jsont.Meta.none,
161
+
[(Jsont.Meta.none, name), v]
162
+
)
163
+
) (Jsont.Object (Jsont.Meta.none, [])) mems
164
+
| _ -> t.configuration)
165
+
|> Jsont.Object.finish
166
+
end
167
+
```
168
+
169
+
Wait — `keep_unknown` with `json_mems` captures unknown members as `Jsont.json`. The json value will be an `Object` containing just the unknown keys. Let me simplify — the `configuration` field stores the entire unknown-members JSON object:
170
+
171
+
```ocaml
172
+
module Other_codec = struct
173
+
type t = { name : string; unknown : Jsont.json }
174
+
let name t = t.name
175
+
let configuration t = t.unknown
176
+
let make name configuration = { name; unknown = configuration }
177
+
178
+
let jsont =
179
+
Jsont.Object.map ~kind:"Other_codec" (fun name unknown -> { name; unknown })
180
+
|> Jsont.Object.mem "id" Jsont.string ~enc:(fun t -> t.name)
181
+
|> Jsont.Object.keep_unknown Jsont.json_mems ~enc:(fun t -> t.unknown)
182
+
|> Jsont.Object.finish
183
+
end
184
+
```
185
+
186
+
- [ ] **Step 4: Run test to verify it passes**
187
+
188
+
Run: `dune test`
189
+
Expected: PASS — "test_other_codec: ok"
190
+
191
+
- [ ] **Step 5: Write failing test for Other_ext**
192
+
193
+
Append to `test/test_zarr_jsont.ml`:
194
+
195
+
```ocaml
196
+
let test_other_ext () =
197
+
let json = {|{"name":"custom.ext","configuration":{"key":"val"},"must_understand":false}|} in
198
+
let v = decode Zarr_jsont.Other_ext.jsont json in
199
+
assert (Zarr_jsont.Other_ext.name v = "custom.ext");
200
+
assert (Zarr_jsont.Other_ext.must_understand v = false);
201
+
assert (Zarr_jsont.Other_ext.configuration v <> None);
202
+
let json' = encode Zarr_jsont.Other_ext.jsont v in
203
+
let v' = decode Zarr_jsont.Other_ext.jsont json' in
204
+
assert (Zarr_jsont.Other_ext.name v' = "custom.ext");
205
+
print_endline "test_other_ext: ok"
206
+
207
+
let () = test_other_ext ()
208
+
```
209
+
210
+
- [ ] **Step 6: Run test to verify it fails**
211
+
212
+
Run: `dune test`
213
+
Expected: FAIL — `Other_ext` not defined
214
+
215
+
- [ ] **Step 7: Implement Other_ext**
216
+
217
+
In `src/zarr_jsont.mli`, add:
218
+
219
+
```ocaml
220
+
module Other_ext : sig
221
+
type t
222
+
val name : t -> string
223
+
val configuration : t -> Jsont.json option
224
+
val must_understand : t -> bool
225
+
val make : string -> Jsont.json option -> bool -> t
226
+
val jsont : t Jsont.t
227
+
end
228
+
```
229
+
230
+
In `src/zarr_jsont.ml`, add:
231
+
232
+
```ocaml
233
+
module Other_ext = struct
234
+
type t = {
235
+
name : string;
236
+
configuration : Jsont.json option;
237
+
must_understand : bool;
238
+
}
239
+
let name t = t.name
240
+
let configuration t = t.configuration
241
+
let must_understand t = t.must_understand
242
+
let make name configuration must_understand =
243
+
{ name; configuration; must_understand }
244
+
245
+
let jsont =
246
+
Jsont.Object.map ~kind:"Other_ext"
247
+
(fun name configuration must_understand ->
248
+
{ name; configuration; must_understand })
249
+
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun t -> t.name)
250
+
|> Jsont.Object.opt_mem "configuration" Jsont.json
251
+
~enc:(fun t -> t.configuration)
252
+
|> Jsont.Object.mem "must_understand" Jsont.bool
253
+
~dec_absent:true ~enc:(fun t -> t.must_understand)
254
+
~enc_omit:(fun v -> v = true)
255
+
|> Jsont.Object.skip_unknown
256
+
|> Jsont.Object.finish
257
+
end
258
+
```
259
+
260
+
- [ ] **Step 8: Run test to verify it passes**
261
+
262
+
Run: `dune test`
263
+
Expected: PASS — "test_other_ext: ok"
264
+
265
+
- [ ] **Step 9: Commit**
266
+
267
+
```bash
268
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
269
+
git commit -m "feat: Other_codec and Other_ext escape hatch types"
270
+
```
271
+
272
+
---
273
+
274
+
### Task 3: Fill_value codec
275
+
276
+
**Files:**
277
+
- Modify: `src/zarr_jsont.ml`
278
+
- Modify: `src/zarr_jsont.mli`
279
+
- Modify: `test/test_zarr_jsont.ml`
280
+
281
+
- [ ] **Step 1: Write failing tests for fill_value**
282
+
283
+
Append to `test/test_zarr_jsont.ml`:
284
+
285
+
```ocaml
286
+
let test_fill_value () =
287
+
let fv = Zarr_jsont.fill_value_jsont in
288
+
(* null *)
289
+
let v = decode fv "null" in
290
+
assert (v = `Null);
291
+
(* bool *)
292
+
let v = decode fv "true" in
293
+
assert (v = `Bool true);
294
+
(* int *)
295
+
let v = decode fv "42" in
296
+
assert (v = `Int 42L);
297
+
(* float *)
298
+
let v = decode fv "3.14" in
299
+
(match v with `Float f -> assert (f = 3.14) | _ -> assert false);
300
+
(* NaN string *)
301
+
let v = decode fv {|"NaN"|} in
302
+
(match v with `Float f -> assert (Float.is_nan f) | _ -> assert false);
303
+
(* Infinity string *)
304
+
let v = decode fv {|"Infinity"|} in
305
+
(match v with `Float f -> assert (f = infinity) | _ -> assert false);
306
+
(* -Infinity string *)
307
+
let v = decode fv {|"-Infinity"|} in
308
+
(match v with `Float f -> assert (f = neg_infinity) | _ -> assert false);
309
+
(* complex as array *)
310
+
let v = decode fv {|[1.0, 2.0]|} in
311
+
assert (v = `Complex (1.0, 2.0));
312
+
(* bytes as int array *)
313
+
let v = decode fv {|[0, 255, 128]|} in
314
+
(match v with `Bytes s -> assert (String.length s = 3) | _ -> assert false);
315
+
print_endline "test_fill_value: ok"
316
+
317
+
let () = test_fill_value ()
318
+
```
319
+
320
+
- [ ] **Step 2: Run test to verify it fails**
321
+
322
+
Run: `dune test`
323
+
Expected: FAIL — `fill_value_jsont` not defined
324
+
325
+
- [ ] **Step 3: Implement fill_value type and codec**
326
+
327
+
In `src/zarr_jsont.mli`, add:
328
+
329
+
```ocaml
330
+
type fill_value = [
331
+
| `Null
332
+
| `Bool of bool
333
+
| `Int of int64
334
+
| `Float of float
335
+
| `Complex of float * float
336
+
| `Bytes of string
337
+
]
338
+
339
+
val fill_value_jsont : fill_value Jsont.t
340
+
```
341
+
342
+
In `src/zarr_jsont.ml`, add:
343
+
344
+
```ocaml
345
+
type fill_value = [
346
+
| `Null
347
+
| `Bool of bool
348
+
| `Int of int64
349
+
| `Float of float
350
+
| `Complex of float * float
351
+
| `Bytes of string
352
+
]
353
+
354
+
let fill_value_jsont =
355
+
let null = Jsont.map ~kind:"fill_value"
356
+
~dec:(fun () -> `Null)
357
+
~enc:(function `Null -> () | _ -> assert false)
358
+
(Jsont.null ())
359
+
in
360
+
let bool = Jsont.map ~kind:"fill_value"
361
+
~dec:(fun b -> `Bool b)
362
+
~enc:(function `Bool b -> b | _ -> assert false)
363
+
Jsont.bool
364
+
in
365
+
let number = Jsont.map ~kind:"fill_value"
366
+
~dec:(fun f ->
367
+
if Float.is_integer f && Float.is_finite f
368
+
then `Int (Int64.of_float f)
369
+
else `Float f)
370
+
~enc:(function
371
+
| `Int i -> Int64.to_float i
372
+
| `Float f -> f
373
+
| _ -> assert false)
374
+
Jsont.number
375
+
in
376
+
let string = Jsont.map ~kind:"fill_value"
377
+
~dec:(function
378
+
| "NaN" -> `Float Float.nan
379
+
| "Infinity" -> `Float Float.infinity
380
+
| "-Infinity" -> `Float Float.neg_infinity
381
+
| s when String.length s >= 2 && s.[0] = '0' && s.[1] = 'x' ->
382
+
`Float (Int64.to_float (Int64.of_string s))
383
+
| _ -> `Null (* should not happen for well-formed zarr *))
384
+
~enc:(function
385
+
| `Float f when Float.is_nan f -> "NaN"
386
+
| `Float f when f = Float.infinity -> "Infinity"
387
+
| `Float f when f = Float.neg_infinity -> "-Infinity"
388
+
| _ -> assert false)
389
+
Jsont.string
390
+
in
391
+
let array =
392
+
let elt_jsont = Jsont.number in
393
+
Jsont.map ~kind:"fill_value"
394
+
~dec:(fun arr ->
395
+
if List.length arr = 2 then
396
+
`Complex (List.nth arr 0, List.nth arr 1)
397
+
else
398
+
let buf = Buffer.create (List.length arr) in
399
+
List.iter (fun f -> Buffer.add_char buf (Char.chr (Float.to_int f))) arr;
400
+
`Bytes (Buffer.contents buf))
401
+
~enc:(function
402
+
| `Complex (r, i) -> [r; i]
403
+
| `Bytes s ->
404
+
List.init (String.length s) (fun i ->
405
+
Float.of_int (Char.code s.[i]))
406
+
| _ -> assert false)
407
+
(Jsont.list elt_jsont)
408
+
in
409
+
let enc = function
410
+
| `Null -> null
411
+
| `Bool _ -> bool
412
+
| `Int _ -> number
413
+
| `Float f when Float.is_nan f || Float.is_infinite f -> string
414
+
| `Float _ -> number
415
+
| `Complex _ -> array
416
+
| `Bytes _ -> array
417
+
in
418
+
Jsont.any ~kind:"fill_value"
419
+
~dec_null:null ~dec_bool:bool ~dec_number:number
420
+
~dec_string:string ~dec_array:array ~enc ()
421
+
```
422
+
423
+
- [ ] **Step 4: Run test to verify it passes**
424
+
425
+
Run: `dune test`
426
+
Expected: PASS — "test_fill_value: ok"
427
+
428
+
- [ ] **Step 5: Commit**
429
+
430
+
```bash
431
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
432
+
git commit -m "feat: fill_value polymorphic variant codec"
433
+
```
434
+
435
+
---
436
+
437
+
### Task 4: Dtype codec (v2 NumPy typestr parsing)
438
+
439
+
**Files:**
440
+
- Modify: `src/zarr_jsont.ml`
441
+
- Modify: `src/zarr_jsont.mli`
442
+
- Modify: `test/test_zarr_jsont.ml`
443
+
444
+
The dtype codec must handle simple string types like `"<f8"` and structured types like `[["x","<f4"],["y","<f4",[3]]]`. Simple dtypes are JSON strings; structured dtypes are JSON arrays.
445
+
446
+
- [ ] **Step 1: Write failing tests for dtype parsing**
447
+
448
+
Append to `test/test_zarr_jsont.ml`:
449
+
450
+
```ocaml
451
+
let test_dtype () =
452
+
let dt = Zarr_jsont.dtype_jsont in
453
+
(* simple float *)
454
+
let v = decode dt {|"<f8"|} in
455
+
assert (v = `Float (`Little, 8));
456
+
(* big-endian int *)
457
+
let v = decode dt {|">i4"|} in
458
+
assert (v = `Int (`Big, 4));
459
+
(* boolean *)
460
+
let v = decode dt {|"|b1"|} in
461
+
assert (v = `Bool);
462
+
(* unsigned int *)
463
+
let v = decode dt {|"<u2"|} in
464
+
assert (v = `Uint (`Little, 2));
465
+
(* complex *)
466
+
let v = decode dt {|"<c16"|} in
467
+
assert (v = `Complex (`Little, 16));
468
+
(* datetime *)
469
+
let v = decode dt {|"<M8[ns]"|} in
470
+
assert (v = `Datetime (`Little, "ns"));
471
+
(* timedelta *)
472
+
let v = decode dt {|"<m8[s]"|} in
473
+
assert (v = `Timedelta (`Little, "s"));
474
+
(* fixed string *)
475
+
let v = decode dt {|"|S10"|} in
476
+
assert (v = `String 10);
477
+
(* unicode *)
478
+
let v = decode dt {|"<U5"|} in
479
+
assert (v = `Unicode (`Little, 5));
480
+
(* void/raw *)
481
+
let v = decode dt {|"|V16"|} in
482
+
assert (v = `Raw 16);
483
+
(* structured *)
484
+
let v = decode dt {|[["x","<f4"],["y","<f4",[3]]]|} in
485
+
(match v with
486
+
| `Structured fields ->
487
+
assert (List.length fields = 2);
488
+
let (n1, t1, s1) = List.nth fields 0 in
489
+
assert (n1 = "x" && t1 = `Float (`Little, 4) && s1 = None);
490
+
let (n2, t2, s2) = List.nth fields 1 in
491
+
assert (n2 = "y" && t2 = `Float (`Little, 4) && s2 = Some [3])
492
+
| _ -> assert false);
493
+
(* roundtrip simple *)
494
+
let json' = encode dt (`Float (`Little, 8)) in
495
+
assert (decode dt json' = `Float (`Little, 8));
496
+
(* roundtrip structured *)
497
+
let s = `Structured [("x", `Float (`Little, 4), None);
498
+
("y", `Int (`Big, 2), Some [3; 2])] in
499
+
let json' = encode dt s in
500
+
assert (decode dt json' = s);
501
+
print_endline "test_dtype: ok"
502
+
503
+
let () = test_dtype ()
504
+
```
505
+
506
+
- [ ] **Step 2: Run test to verify it fails**
507
+
508
+
Run: `dune test`
509
+
Expected: FAIL — `dtype_jsont` not defined
510
+
511
+
- [ ] **Step 3: Implement dtype type and parser**
512
+
513
+
In `src/zarr_jsont.mli`, add:
514
+
515
+
```ocaml
516
+
type endian = [ `Little | `Big | `Not_applicable ]
517
+
518
+
type dtype = [
519
+
| `Bool
520
+
| `Int of endian * int
521
+
| `Uint of endian * int
522
+
| `Float of endian * int
523
+
| `Complex of endian * int
524
+
| `Timedelta of endian * string
525
+
| `Datetime of endian * string
526
+
| `String of int
527
+
| `Unicode of endian * int
528
+
| `Raw of int
529
+
| `Structured of (string * dtype * int list option) list
530
+
]
531
+
532
+
val dtype_jsont : dtype Jsont.t
533
+
```
534
+
535
+
In `src/zarr_jsont.ml`, add:
536
+
537
+
```ocaml
538
+
type endian = [ `Little | `Big | `Not_applicable ]
539
+
540
+
type dtype = [
541
+
| `Bool
542
+
| `Int of endian * int
543
+
| `Uint of endian * int
544
+
| `Float of endian * int
545
+
| `Complex of endian * int
546
+
| `Timedelta of endian * string
547
+
| `Datetime of endian * string
548
+
| `String of int
549
+
| `Unicode of endian * int
550
+
| `Raw of int
551
+
| `Structured of (string * dtype * int list option) list
552
+
]
553
+
554
+
let parse_endian = function
555
+
| '<' -> `Little
556
+
| '>' -> `Big
557
+
| '|' | '=' -> `Not_applicable
558
+
| c -> failwith (Printf.sprintf "Unknown endian char: %c" c)
559
+
560
+
let parse_simple_dtype s =
561
+
let len = String.length s in
562
+
if len < 3 then failwith ("Invalid dtype: " ^ s);
563
+
let endian = parse_endian s.[0] in
564
+
let kind = s.[1] in
565
+
let rest = String.sub s 2 (len - 2) in
566
+
match kind with
567
+
| 'b' -> `Bool
568
+
| 'i' -> `Int (endian, int_of_string rest)
569
+
| 'u' -> `Uint (endian, int_of_string rest)
570
+
| 'f' -> `Float (endian, int_of_string rest)
571
+
| 'c' -> `Complex (endian, int_of_string rest)
572
+
| 'M' ->
573
+
(* "<M8[ns]" — extract unit from brackets *)
574
+
let i = String.index rest '[' in
575
+
let j = String.index rest ']' in
576
+
let unit = String.sub rest (i + 1) (j - i - 1) in
577
+
`Datetime (endian, unit)
578
+
| 'm' ->
579
+
let i = String.index rest '[' in
580
+
let j = String.index rest ']' in
581
+
let unit = String.sub rest (i + 1) (j - i - 1) in
582
+
`Timedelta (endian, unit)
583
+
| 'S' -> `String (int_of_string rest)
584
+
| 'U' -> `Unicode (endian, int_of_string rest)
585
+
| 'V' -> `Raw (int_of_string rest)
586
+
| c -> failwith (Printf.sprintf "Unknown dtype kind: %c" c)
587
+
588
+
let endian_to_char = function
589
+
| `Little -> '<'
590
+
| `Big -> '>'
591
+
| `Not_applicable -> '|'
592
+
593
+
let rec dtype_to_string = function
594
+
| `Bool -> "|b1"
595
+
| `Int (e, n) -> Printf.sprintf "%ci%d" (endian_to_char e) n
596
+
| `Uint (e, n) -> Printf.sprintf "%cu%d" (endian_to_char e) n
597
+
| `Float (e, n) -> Printf.sprintf "%cf%d" (endian_to_char e) n
598
+
| `Complex (e, n) -> Printf.sprintf "%cc%d" (endian_to_char e) n
599
+
| `Datetime (e, u) -> Printf.sprintf "%cM8[%s]" (endian_to_char e) u
600
+
| `Timedelta (e, u) -> Printf.sprintf "%cm8[%s]" (endian_to_char e) u
601
+
| `String n -> Printf.sprintf "|S%d" n
602
+
| `Unicode (e, n) -> Printf.sprintf "%cU%d" (endian_to_char e) n
603
+
| `Raw n -> Printf.sprintf "|V%d" n
604
+
| `Structured _ -> assert false (* structured uses array encoding *)
605
+
606
+
let dtype_jsont =
607
+
let simple_string = Jsont.map ~kind:"dtype"
608
+
~dec:parse_simple_dtype
609
+
~enc:dtype_to_string
610
+
Jsont.string
611
+
in
612
+
let rec structured_field_jsont = lazy (
613
+
Jsont.map ~kind:"dtype_field"
614
+
~dec:(fun arr ->
615
+
match arr with
616
+
| Jsont.String (_, name) :: dtype_json :: rest ->
617
+
let dt_s = match dtype_json with
618
+
| Jsont.String (_, s) -> parse_simple_dtype s
619
+
| Jsont.Array (_, items) ->
620
+
(* nested structured type *)
621
+
decode_structured items
622
+
| _ -> failwith "Invalid dtype in structured field"
623
+
in
624
+
let shape = match rest with
625
+
| [Jsont.Array (_, ints)] ->
626
+
Some (List.map (fun j ->
627
+
match j with
628
+
| Jsont.Number (_, f) -> Float.to_int f
629
+
| _ -> failwith "Invalid shape element") ints)
630
+
| [] -> None
631
+
| _ -> failwith "Invalid structured field"
632
+
in
633
+
(name, dt_s, shape)
634
+
| _ -> failwith "Invalid structured field")
635
+
~enc:(fun (name, dt, shape) ->
636
+
let name_j = Jsont.Json.string name in
637
+
let dt_j = match dt with
638
+
| `Structured fields -> encode_structured fields
639
+
| d -> Jsont.Json.string (dtype_to_string d)
640
+
in
641
+
match shape with
642
+
| None -> [name_j; dt_j]
643
+
| Some s ->
644
+
let shape_j = Jsont.Json.list
645
+
(List.map (fun i -> Jsont.Json.number (Float.of_int i)) s) in
646
+
[name_j; dt_j; shape_j])
647
+
(Jsont.list Jsont.json)
648
+
)
649
+
and decode_structured items =
650
+
`Structured (List.map (fun item ->
651
+
match item with
652
+
| Jsont.Array (_, field_items) ->
653
+
let field_json = Jsont.Json.list field_items in
654
+
(match Jsont.Json.decode (Lazy.force structured_field_jsont) field_json with
655
+
| Ok v -> v
656
+
| Error e -> failwith e)
657
+
| _ -> failwith "Invalid structured dtype field") items)
658
+
and encode_structured fields =
659
+
Jsont.Json.list (List.map (fun field ->
660
+
match Jsont.Json.encode (Lazy.force structured_field_jsont) field with
661
+
| Ok v -> v
662
+
| Error e -> failwith e) fields)
663
+
in
664
+
let structured = Jsont.map ~kind:"dtype"
665
+
~dec:(fun items -> decode_structured items)
666
+
~enc:(function
667
+
| `Structured fields ->
668
+
(match encode_structured fields with
669
+
| Jsont.Array (_, items) -> items
670
+
| _ -> assert false)
671
+
| _ -> assert false)
672
+
(Jsont.list Jsont.json)
673
+
in
674
+
let enc = function
675
+
| `Structured _ -> structured
676
+
| _ -> simple_string
677
+
in
678
+
Jsont.any ~kind:"dtype" ~dec_string:simple_string ~dec_array:structured ~enc ()
679
+
```
680
+
681
+
Note: The structured dtype implementation uses `Jsont.Json.decode` / `Jsont.Json.encode` for recursive field parsing within the JSON AST. This avoids needing `Jsont.rec'` since the recursion operates at the value level. The exact API for `Jsont.Json.decode`/`encode` takes a codec and a `Jsont.json` value and returns a result. Adjust the error handling if the actual API differs slightly.
682
+
683
+
- [ ] **Step 4: Run test to verify it passes**
684
+
685
+
Run: `dune test`
686
+
Expected: PASS — "test_dtype: ok"
687
+
688
+
- [ ] **Step 5: Commit**
689
+
690
+
```bash
691
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
692
+
git commit -m "feat: dtype codec with full NumPy typestr parsing"
693
+
```
694
+
695
+
---
696
+
697
+
### Task 5: V2 compressor and filter codecs
698
+
699
+
**Files:**
700
+
- Modify: `src/zarr_jsont.ml`
701
+
- Modify: `src/zarr_jsont.mli`
702
+
- Modify: `test/test_zarr_jsont.ml`
703
+
704
+
- [ ] **Step 1: Write failing tests for v2 compressors and filters**
705
+
706
+
Append to `test/test_zarr_jsont.ml`:
707
+
708
+
```ocaml
709
+
let test_v2_compressor () =
710
+
let c = Zarr_jsont.V2.compressor_jsont in
711
+
(* blosc *)
712
+
let json = {|{"id":"blosc","cname":"lz4","clevel":5,"shuffle":1}|} in
713
+
let v = decode c json in
714
+
(match v with
715
+
| `Blosc b ->
716
+
assert (Zarr_jsont.V2.Compressor.Blosc.cname b = "lz4");
717
+
assert (Zarr_jsont.V2.Compressor.Blosc.clevel b = 5);
718
+
assert (Zarr_jsont.V2.Compressor.Blosc.shuffle b = 1)
719
+
| _ -> assert false);
720
+
(* zlib *)
721
+
let json = {|{"id":"zlib","level":1}|} in
722
+
let v = decode c json in
723
+
(match v with
724
+
| `Zlib z -> assert (Zarr_jsont.V2.Compressor.Zlib.level z = 1)
725
+
| _ -> assert false);
726
+
(* unknown compressor *)
727
+
let json = {|{"id":"lzma","preset":6}|} in
728
+
let v = decode c json in
729
+
(match v with
730
+
| `Other o -> assert (Zarr_jsont.Other_codec.name o = "lzma")
731
+
| _ -> assert false);
732
+
print_endline "test_v2_compressor: ok"
733
+
734
+
let test_v2_filter () =
735
+
let f = Zarr_jsont.V2.filter_jsont in
736
+
let json = {|{"id":"delta","dtype":"<f8","astype":"<f4"}|} in
737
+
let v = decode f json in
738
+
(match v with
739
+
| `Delta d ->
740
+
assert (Zarr_jsont.V2.Filter.Delta.dtype d = "<f8");
741
+
assert (Zarr_jsont.V2.Filter.Delta.astype d = Some "<f4")
742
+
| _ -> assert false);
743
+
(* unknown filter *)
744
+
let json = {|{"id":"quantize","digits":10}|} in
745
+
let v = decode f json in
746
+
(match v with
747
+
| `Other o -> assert (Zarr_jsont.Other_codec.name o = "quantize")
748
+
| _ -> assert false);
749
+
print_endline "test_v2_filter: ok"
750
+
751
+
let () = test_v2_compressor ()
752
+
let () = test_v2_filter ()
753
+
```
754
+
755
+
- [ ] **Step 2: Run test to verify it fails**
756
+
757
+
Run: `dune test`
758
+
Expected: FAIL — `V2` not defined
759
+
760
+
- [ ] **Step 3: Implement V2 compressor and filter types**
761
+
762
+
In `src/zarr_jsont.mli`, add:
763
+
764
+
```ocaml
765
+
module V2 : sig
766
+
module Compressor : sig
767
+
module Blosc : sig
768
+
type t
769
+
val cname : t -> string
770
+
val clevel : t -> int
771
+
val shuffle : t -> int
772
+
val blocksize : t -> int option
773
+
val unknown : t -> Jsont.json
774
+
end
775
+
module Zlib : sig
776
+
type t
777
+
val level : t -> int
778
+
val unknown : t -> Jsont.json
779
+
end
780
+
end
781
+
782
+
type compressor = [
783
+
| `Blosc of Compressor.Blosc.t
784
+
| `Zlib of Compressor.Zlib.t
785
+
| `Other of Other_codec.t
786
+
]
787
+
788
+
val compressor_jsont : compressor Jsont.t
789
+
790
+
module Filter : sig
791
+
module Delta : sig
792
+
type t
793
+
val dtype : t -> string
794
+
val astype : t -> string option
795
+
val unknown : t -> Jsont.json
796
+
end
797
+
end
798
+
799
+
type filter = [
800
+
| `Delta of Filter.Delta.t
801
+
| `Other of Other_codec.t
802
+
]
803
+
804
+
val filter_jsont : filter Jsont.t
805
+
end
806
+
```
807
+
808
+
In `src/zarr_jsont.ml`, add:
809
+
810
+
```ocaml
811
+
module V2 = struct
812
+
module Compressor = struct
813
+
module Blosc = struct
814
+
type t = {
815
+
cname : string; clevel : int; shuffle : int;
816
+
blocksize : int option; unknown : Jsont.json;
817
+
}
818
+
let cname t = t.cname
819
+
let clevel t = t.clevel
820
+
let shuffle t = t.shuffle
821
+
let blocksize t = t.blocksize
822
+
let unknown t = t.unknown
823
+
824
+
let jsont =
825
+
Jsont.Object.map ~kind:"Blosc"
826
+
(fun cname clevel shuffle blocksize unknown ->
827
+
{ cname; clevel; shuffle; blocksize; unknown })
828
+
|> Jsont.Object.mem "cname" Jsont.string ~enc:(fun t -> t.cname)
829
+
|> Jsont.Object.mem "clevel" Jsont.int ~enc:(fun t -> t.clevel)
830
+
|> Jsont.Object.mem "shuffle" Jsont.int ~enc:(fun t -> t.shuffle)
831
+
|> Jsont.Object.opt_mem "blocksize" Jsont.int
832
+
~enc:(fun t -> t.blocksize)
833
+
|> Jsont.Object.keep_unknown Jsont.json_mems
834
+
~enc:(fun t -> t.unknown)
835
+
|> Jsont.Object.finish
836
+
end
837
+
838
+
module Zlib = struct
839
+
type t = { level : int; unknown : Jsont.json }
840
+
let level t = t.level
841
+
let unknown t = t.unknown
842
+
843
+
let jsont =
844
+
Jsont.Object.map ~kind:"Zlib"
845
+
(fun level unknown -> { level; unknown })
846
+
|> Jsont.Object.mem "level" Jsont.int ~enc:(fun t -> t.level)
847
+
|> Jsont.Object.keep_unknown Jsont.json_mems
848
+
~enc:(fun t -> t.unknown)
849
+
|> Jsont.Object.finish
850
+
end
851
+
end
852
+
853
+
type compressor = [
854
+
| `Blosc of Compressor.Blosc.t
855
+
| `Zlib of Compressor.Zlib.t
856
+
| `Other of Other_codec.t
857
+
]
858
+
859
+
let compressor_jsont =
860
+
let blosc = Jsont.Object.Case.map ~dec:(fun b -> `Blosc b)
861
+
"blosc" Compressor.Blosc.jsont in
862
+
let zlib = Jsont.Object.Case.map ~dec:(fun z -> `Zlib z)
863
+
"zlib" Compressor.Zlib.jsont in
864
+
let other = Jsont.Object.Case.map ~dec:(fun o -> `Other o)
865
+
"other" Other_codec.jsont in
866
+
let enc_case = function
867
+
| `Blosc b -> Jsont.Object.Case.value blosc b
868
+
| `Zlib z -> Jsont.Object.Case.value zlib z
869
+
| `Other o -> Jsont.Object.Case.value other o
870
+
in
871
+
Jsont.Object.map ~kind:"Compressor" Fun.id
872
+
|> Jsont.Object.case_mem "id" Jsont.string
873
+
~enc:Fun.id ~enc_case
874
+
~tag_to_string:Fun.id ~tag_compare:String.compare
875
+
[ Jsont.Object.Case.make blosc;
876
+
Jsont.Object.Case.make zlib;
877
+
Jsont.Object.Case.make other ]
878
+
|> Jsont.Object.finish
879
+
880
+
module Filter = struct
881
+
module Delta = struct
882
+
type t = { dtype : string; astype : string option; unknown : Jsont.json }
883
+
let dtype t = t.dtype
884
+
let astype t = t.astype
885
+
let unknown t = t.unknown
886
+
887
+
let jsont =
888
+
Jsont.Object.map ~kind:"Delta"
889
+
(fun dtype astype unknown -> { dtype; astype; unknown })
890
+
|> Jsont.Object.mem "dtype" Jsont.string ~enc:(fun t -> t.dtype)
891
+
|> Jsont.Object.opt_mem "astype" Jsont.string
892
+
~enc:(fun t -> t.astype)
893
+
|> Jsont.Object.keep_unknown Jsont.json_mems
894
+
~enc:(fun t -> t.unknown)
895
+
|> Jsont.Object.finish
896
+
end
897
+
end
898
+
899
+
type filter = [
900
+
| `Delta of Filter.Delta.t
901
+
| `Other of Other_codec.t
902
+
]
903
+
904
+
let filter_jsont =
905
+
let delta = Jsont.Object.Case.map ~dec:(fun d -> `Delta d)
906
+
"delta" Filter.Delta.jsont in
907
+
let other = Jsont.Object.Case.map ~dec:(fun o -> `Other o)
908
+
"other" Other_codec.jsont in
909
+
let enc_case = function
910
+
| `Delta d -> Jsont.Object.Case.value delta d
911
+
| `Other o -> Jsont.Object.Case.value other o
912
+
in
913
+
Jsont.Object.map ~kind:"Filter" Fun.id
914
+
|> Jsont.Object.case_mem "id" Jsont.string
915
+
~enc:Fun.id ~enc_case
916
+
~tag_to_string:Fun.id ~tag_compare:String.compare
917
+
[ Jsont.Object.Case.make delta;
918
+
Jsont.Object.Case.make other ]
919
+
|> Jsont.Object.finish
920
+
end
921
+
```
922
+
923
+
Note: The `case_mem` approach for compressors/filters uses `"id"` as the tag field. The `"other"` tag in the case list acts as a fallback — when `case_mem` encounters an unknown tag value, it needs a default case. If jsont's `case_mem` doesn't support default/fallback cases, an alternative approach is to first peek at the `"id"` field then dispatch manually using `Jsont.any` with `dec_object`. The implementer should verify the exact `case_mem` fallback behavior and adjust if needed. An alternative pattern is:
924
+
925
+
```ocaml
926
+
(* Alternative: manual dispatch if case_mem doesn't support fallback *)
927
+
let compressor_jsont =
928
+
let peek_id json =
929
+
match Jsont.Json.find_mem "id" json with
930
+
| Some (_, Jsont.String (_, id)) -> id
931
+
| _ -> failwith "missing id"
932
+
in
933
+
Jsont.map ~kind:"Compressor"
934
+
~dec:(fun json ->
935
+
let id = peek_id json in
936
+
match id with
937
+
| "blosc" -> ...
938
+
| "zlib" -> ...
939
+
| _ -> `Other ...)
940
+
...
941
+
```
942
+
943
+
The implementer should use whichever approach works with the actual jsont API.
944
+
945
+
- [ ] **Step 4: Run test to verify it passes**
946
+
947
+
Run: `dune test`
948
+
Expected: PASS — "test_v2_compressor: ok", "test_v2_filter: ok"
949
+
950
+
- [ ] **Step 5: Commit**
951
+
952
+
```bash
953
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
954
+
git commit -m "feat: V2 compressor and filter codecs with case dispatch"
955
+
```
956
+
957
+
---
958
+
959
+
### Task 6: V2 Array_meta and Node
960
+
961
+
**Files:**
962
+
- Modify: `src/zarr_jsont.ml`
963
+
- Modify: `src/zarr_jsont.mli`
964
+
- Modify: `test/test_zarr_jsont.ml`
965
+
966
+
- [ ] **Step 1: Write failing test for V2 array metadata**
967
+
968
+
Append to `test/test_zarr_jsont.ml`:
969
+
970
+
```ocaml
971
+
let test_v2_array () =
972
+
let json = {|{
973
+
"zarr_format": 2,
974
+
"shape": [10000, 10000],
975
+
"chunks": [1000, 1000],
976
+
"dtype": "<f8",
977
+
"compressor": {"id": "blosc", "cname": "lz4", "clevel": 5, "shuffle": 1},
978
+
"fill_value": "NaN",
979
+
"order": "C",
980
+
"filters": [{"id": "delta", "dtype": "<f8", "astype": "<f4"}]
981
+
}|} in
982
+
let v = decode Zarr_jsont.V2.array_meta_jsont json in
983
+
assert (Zarr_jsont.V2.Array_meta.shape v = [10000; 10000]);
984
+
assert (Zarr_jsont.V2.Array_meta.chunks v = [1000; 1000]);
985
+
assert (Zarr_jsont.V2.Array_meta.dtype v = `Float (`Little, 8));
986
+
assert (Zarr_jsont.V2.Array_meta.order v = `C);
987
+
(match Zarr_jsont.V2.Array_meta.compressor v with
988
+
| Some (`Blosc b) ->
989
+
assert (Zarr_jsont.V2.Compressor.Blosc.cname b = "lz4")
990
+
| _ -> assert false);
991
+
(match Zarr_jsont.V2.Array_meta.filters v with
992
+
| Some [(`Delta _)] -> ()
993
+
| _ -> assert false);
994
+
(match Zarr_jsont.V2.Array_meta.fill_value v with
995
+
| `Float f -> assert (Float.is_nan f)
996
+
| _ -> assert false);
997
+
(* roundtrip *)
998
+
let json' = encode Zarr_jsont.V2.array_meta_jsont v in
999
+
let _ = decode Zarr_jsont.V2.array_meta_jsont json' in
1000
+
print_endline "test_v2_array: ok"
1001
+
1002
+
let () = test_v2_array ()
1003
+
```
1004
+
1005
+
- [ ] **Step 2: Run test to verify it fails**
1006
+
1007
+
Run: `dune test`
1008
+
Expected: FAIL — `V2.Array_meta` / `V2.array_meta_jsont` not defined
1009
+
1010
+
- [ ] **Step 3: Implement V2.Array_meta, V2.Node, and codecs**
1011
+
1012
+
Add to `src/zarr_jsont.mli` inside the `V2` module:
1013
+
1014
+
```ocaml
1015
+
module Array_meta : sig
1016
+
type t
1017
+
val shape : t -> int list
1018
+
val chunks : t -> int list
1019
+
val dtype : t -> dtype
1020
+
val compressor : t -> compressor option
1021
+
val fill_value : t -> fill_value
1022
+
val order : t -> [ `C | `F ]
1023
+
val filters : t -> filter list option
1024
+
val dimension_separator : t -> [ `Dot | `Slash ] option
1025
+
val unknown : t -> Jsont.json
1026
+
end
1027
+
1028
+
val array_meta_jsont : Array_meta.t Jsont.t
1029
+
1030
+
module Node : sig
1031
+
type t
1032
+
val kind : t -> [ `Array of Array_meta.t | `Group ]
1033
+
val attrs : t -> Attrs.t
1034
+
val unknown : t -> Jsont.json
1035
+
end
1036
+
```
1037
+
1038
+
Add to `src/zarr_jsont.ml` inside the `V2` module:
1039
+
1040
+
```ocaml
1041
+
module Array_meta = struct
1042
+
type t = {
1043
+
shape : int list;
1044
+
chunks : int list;
1045
+
dtype : dtype;
1046
+
compressor : compressor option;
1047
+
fill_value : fill_value;
1048
+
order : [ `C | `F ];
1049
+
filters : filter list option;
1050
+
dimension_separator : [ `Dot | `Slash ] option;
1051
+
unknown : Jsont.json;
1052
+
}
1053
+
let shape t = t.shape
1054
+
let chunks t = t.chunks
1055
+
let dtype t = t.dtype
1056
+
let compressor t = t.compressor
1057
+
let fill_value t = t.fill_value
1058
+
let order t = t.order
1059
+
let filters t = t.filters
1060
+
let dimension_separator t = t.dimension_separator
1061
+
let unknown t = t.unknown
1062
+
end
1063
+
1064
+
let order_jsont =
1065
+
Jsont.enum ~kind:"order" ["C", `C; "F", `F]
1066
+
1067
+
let dimension_separator_jsont =
1068
+
Jsont.enum ~kind:"dimension_separator" [".", `Dot; "/", `Slash]
1069
+
1070
+
let nullable_compressor_jsont =
1071
+
Jsont.option compressor_jsont
1072
+
1073
+
let nullable_filters_jsont =
1074
+
Jsont.option (Jsont.list filter_jsont)
1075
+
1076
+
let array_meta_jsont =
1077
+
Jsont.Object.map ~kind:"V2.Array_meta"
1078
+
(fun _zarr_format shape chunks dtype compressor fill_value order
1079
+
filters dimension_separator unknown ->
1080
+
Array_meta.{ shape; chunks; dtype; compressor; fill_value;
1081
+
order; filters; dimension_separator; unknown })
1082
+
|> Jsont.Object.mem "zarr_format" Jsont.int
1083
+
~enc:(fun _ -> 2)
1084
+
|> Jsont.Object.mem "shape" (Jsont.list Jsont.int)
1085
+
~enc:(fun (t : Array_meta.t) -> t.shape)
1086
+
|> Jsont.Object.mem "chunks" (Jsont.list Jsont.int)
1087
+
~enc:(fun (t : Array_meta.t) -> t.chunks)
1088
+
|> Jsont.Object.mem "dtype" dtype_jsont
1089
+
~enc:(fun (t : Array_meta.t) -> t.dtype)
1090
+
|> Jsont.Object.mem "compressor" nullable_compressor_jsont
1091
+
~enc:(fun (t : Array_meta.t) -> t.compressor)
1092
+
|> Jsont.Object.mem "fill_value" fill_value_jsont
1093
+
~enc:(fun (t : Array_meta.t) -> t.fill_value)
1094
+
|> Jsont.Object.mem "order" order_jsont
1095
+
~enc:(fun (t : Array_meta.t) -> t.order)
1096
+
|> Jsont.Object.mem "filters" nullable_filters_jsont
1097
+
~enc:(fun (t : Array_meta.t) -> t.filters)
1098
+
|> Jsont.Object.opt_mem "dimension_separator" dimension_separator_jsont
1099
+
~enc:(fun (t : Array_meta.t) -> t.dimension_separator)
1100
+
|> Jsont.Object.keep_unknown Jsont.json_mems
1101
+
~enc:(fun (t : Array_meta.t) -> t.unknown)
1102
+
|> Jsont.Object.finish
1103
+
1104
+
(* Node will be completed in Task 8 after Attrs is defined *)
1105
+
```
1106
+
1107
+
Note: The `Node` type depends on `Attrs`, which depends on conventions. We define the `Node` module signature now but defer the implementation to Task 8. For now, expose `array_meta_jsont` for testing.
1108
+
1109
+
- [ ] **Step 4: Run test to verify it passes**
1110
+
1111
+
Run: `dune test`
1112
+
Expected: PASS — "test_v2_array: ok"
1113
+
1114
+
- [ ] **Step 5: Write test for v2 group (minimal)**
1115
+
1116
+
```ocaml
1117
+
let test_v2_group () =
1118
+
let json = {|{"zarr_format": 2}|} in
1119
+
(* For now just verify it parses as valid JSON with zarr_format=2 *)
1120
+
let v = decode Jsont.json json in
1121
+
(match v with Jsont.Object _ -> () | _ -> assert false);
1122
+
print_endline "test_v2_group: ok"
1123
+
1124
+
let () = test_v2_group ()
1125
+
```
1126
+
1127
+
- [ ] **Step 6: Run tests**
1128
+
1129
+
Run: `dune test`
1130
+
Expected: PASS
1131
+
1132
+
- [ ] **Step 7: Commit**
1133
+
1134
+
```bash
1135
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
1136
+
git commit -m "feat: V2 Array_meta codec with all fields"
1137
+
```
1138
+
1139
+
---
1140
+
1141
+
### Task 7: V3 codecs (Bytes, Gzip, Blosc, Crc32c, Transpose, Sharding)
1142
+
1143
+
**Files:**
1144
+
- Modify: `src/zarr_jsont.ml`
1145
+
- Modify: `src/zarr_jsont.mli`
1146
+
- Modify: `test/test_zarr_jsont.ml`
1147
+
1148
+
- [ ] **Step 1: Write failing tests for V3 codecs**
1149
+
1150
+
```ocaml
1151
+
let test_v3_codecs () =
1152
+
let c = Zarr_jsont.V3.codec_jsont in
1153
+
(* bytes codec *)
1154
+
let json = {|{"name":"bytes","configuration":{"endian":"little"}}|} in
1155
+
let v = decode c json in
1156
+
(match v with
1157
+
| `Bytes b -> assert (Zarr_jsont.V3.Codec.Bytes.endian b = `Little)
1158
+
| _ -> assert false);
1159
+
(* gzip codec *)
1160
+
let json = {|{"name":"gzip","configuration":{"level":5}}|} in
1161
+
let v = decode c json in
1162
+
(match v with
1163
+
| `Gzip g -> assert (Zarr_jsont.V3.Codec.Gzip.level g = 5)
1164
+
| _ -> assert false);
1165
+
(* blosc codec *)
1166
+
let json = {|{"name":"blosc","configuration":{"cname":"lz4","clevel":5,"shuffle":"shuffle","typesize":4,"blocksize":0}}|} in
1167
+
let v = decode c json in
1168
+
(match v with
1169
+
| `Blosc b ->
1170
+
assert (Zarr_jsont.V3.Codec.Blosc.cname b = "lz4");
1171
+
assert (Zarr_jsont.V3.Codec.Blosc.shuffle b = `Shuffle)
1172
+
| _ -> assert false);
1173
+
(* crc32c *)
1174
+
let json = {|{"name":"crc32c"}|} in
1175
+
let v = decode c json in
1176
+
assert (v = `Crc32c);
1177
+
(* transpose *)
1178
+
let json = {|{"name":"transpose","configuration":{"order":[1,0,2]}}|} in
1179
+
let v = decode c json in
1180
+
(match v with
1181
+
| `Transpose t -> assert (Zarr_jsont.V3.Codec.Transpose.order t = [1;0;2])
1182
+
| _ -> assert false);
1183
+
(* unknown codec *)
1184
+
let json = {|{"name":"zstd","configuration":{"level":3}}|} in
1185
+
let v = decode c json in
1186
+
(match v with
1187
+
| `Other o -> assert (Zarr_jsont.Other_ext.name o = "zstd")
1188
+
| _ -> assert false);
1189
+
print_endline "test_v3_codecs: ok"
1190
+
1191
+
let () = test_v3_codecs ()
1192
+
```
1193
+
1194
+
- [ ] **Step 2: Run test to verify it fails**
1195
+
1196
+
Run: `dune test`
1197
+
Expected: FAIL — `V3` module not defined
1198
+
1199
+
- [ ] **Step 3: Implement V3 codec submodules**
1200
+
1201
+
In `src/zarr_jsont.mli`, add:
1202
+
1203
+
```ocaml
1204
+
module V3 : sig
1205
+
module Codec : sig
1206
+
module Bytes : sig
1207
+
type t
1208
+
val endian : t -> [ `Little | `Big ]
1209
+
end
1210
+
module Gzip : sig
1211
+
type t
1212
+
val level : t -> int
1213
+
end
1214
+
module Blosc : sig
1215
+
type t
1216
+
val cname : t -> string
1217
+
val clevel : t -> int
1218
+
val shuffle : t -> [ `Noshuffle | `Shuffle | `Bitshuffle ]
1219
+
val typesize : t -> int option
1220
+
val blocksize : t -> int
1221
+
end
1222
+
module Transpose : sig
1223
+
type t
1224
+
val order : t -> int list
1225
+
end
1226
+
module Sharding : sig
1227
+
type t
1228
+
val chunk_shape : t -> int list
1229
+
val codecs : t -> codec list
1230
+
val index_codecs : t -> codec list
1231
+
val index_location : t -> [ `Start | `End ]
1232
+
end
1233
+
end
1234
+
1235
+
type codec = [
1236
+
| `Bytes of Codec.Bytes.t
1237
+
| `Gzip of Codec.Gzip.t
1238
+
| `Blosc of Codec.Blosc.t
1239
+
| `Crc32c
1240
+
| `Transpose of Codec.Transpose.t
1241
+
| `Sharding of Codec.Sharding.t
1242
+
| `Other of Other_ext.t
1243
+
]
1244
+
1245
+
val codec_jsont : codec Jsont.t
1246
+
end
1247
+
```
1248
+
1249
+
In `src/zarr_jsont.ml`, add:
1250
+
1251
+
```ocaml
1252
+
module V3 = struct
1253
+
module Codec = struct
1254
+
module Bytes = struct
1255
+
type t = { endian : [ `Little | `Big ] }
1256
+
let endian t = t.endian
1257
+
let endian_jsont = Jsont.enum ~kind:"endian" ["little", `Little; "big", `Big]
1258
+
let jsont =
1259
+
Jsont.Object.map ~kind:"Bytes.config" (fun endian -> { endian })
1260
+
|> Jsont.Object.mem "endian" endian_jsont ~enc:(fun t -> t.endian)
1261
+
|> Jsont.Object.skip_unknown
1262
+
|> Jsont.Object.finish
1263
+
end
1264
+
1265
+
module Gzip = struct
1266
+
type t = { level : int }
1267
+
let level t = t.level
1268
+
let jsont =
1269
+
Jsont.Object.map ~kind:"Gzip.config" (fun level -> { level })
1270
+
|> Jsont.Object.mem "level" Jsont.int ~enc:(fun t -> t.level)
1271
+
|> Jsont.Object.skip_unknown
1272
+
|> Jsont.Object.finish
1273
+
end
1274
+
1275
+
module Blosc = struct
1276
+
type t = {
1277
+
cname : string; clevel : int;
1278
+
shuffle : [ `Noshuffle | `Shuffle | `Bitshuffle ];
1279
+
typesize : int option; blocksize : int;
1280
+
}
1281
+
let cname t = t.cname
1282
+
let clevel t = t.clevel
1283
+
let shuffle t = t.shuffle
1284
+
let typesize t = t.typesize
1285
+
let blocksize t = t.blocksize
1286
+
1287
+
let shuffle_jsont = Jsont.enum ~kind:"blosc_shuffle"
1288
+
["noshuffle", `Noshuffle; "shuffle", `Shuffle; "bitshuffle", `Bitshuffle]
1289
+
1290
+
let jsont =
1291
+
Jsont.Object.map ~kind:"Blosc.config"
1292
+
(fun cname clevel shuffle typesize blocksize ->
1293
+
{ cname; clevel; shuffle; typesize; blocksize })
1294
+
|> Jsont.Object.mem "cname" Jsont.string ~enc:(fun t -> t.cname)
1295
+
|> Jsont.Object.mem "clevel" Jsont.int ~enc:(fun t -> t.clevel)
1296
+
|> Jsont.Object.mem "shuffle" shuffle_jsont ~enc:(fun t -> t.shuffle)
1297
+
|> Jsont.Object.opt_mem "typesize" Jsont.int ~enc:(fun t -> t.typesize)
1298
+
|> Jsont.Object.mem "blocksize" Jsont.int ~enc:(fun t -> t.blocksize)
1299
+
|> Jsont.Object.skip_unknown
1300
+
|> Jsont.Object.finish
1301
+
end
1302
+
1303
+
module Transpose = struct
1304
+
type t = { order : int list }
1305
+
let order t = t.order
1306
+
let jsont =
1307
+
Jsont.Object.map ~kind:"Transpose.config" (fun order -> { order })
1308
+
|> Jsont.Object.mem "order" (Jsont.list Jsont.int) ~enc:(fun t -> t.order)
1309
+
|> Jsont.Object.skip_unknown
1310
+
|> Jsont.Object.finish
1311
+
end
1312
+
1313
+
module Sharding = struct
1314
+
type t = {
1315
+
chunk_shape : int list;
1316
+
codecs : codec list;
1317
+
index_codecs : codec list;
1318
+
index_location : [ `Start | `End ];
1319
+
}
1320
+
and codec = [
1321
+
| `Bytes of Bytes.t
1322
+
| `Gzip of Gzip.t
1323
+
| `Blosc of Blosc.t
1324
+
| `Crc32c
1325
+
| `Transpose of Transpose.t
1326
+
| `Sharding of t
1327
+
| `Other of Other_ext.t
1328
+
]
1329
+
let chunk_shape t = t.chunk_shape
1330
+
let codecs t = t.codecs
1331
+
let index_codecs t = t.index_codecs
1332
+
let index_location t = t.index_location
1333
+
end
1334
+
end
1335
+
1336
+
type codec = [
1337
+
| `Bytes of Codec.Bytes.t
1338
+
| `Gzip of Codec.Gzip.t
1339
+
| `Blosc of Codec.Blosc.t
1340
+
| `Crc32c
1341
+
| `Transpose of Codec.Transpose.t
1342
+
| `Sharding of Codec.Sharding.t
1343
+
| `Other of Other_ext.t
1344
+
]
1345
+
1346
+
(* Codec jsont needs to be recursive for sharding *)
1347
+
let rec codec_jsont_lazy : codec Jsont.t Lazy.t = lazy (
1348
+
let index_location_jsont = Jsont.enum ~kind:"index_location"
1349
+
["start", `Start; "end", `End] in
1350
+
(* Each named codec: decode configuration object into typed value *)
1351
+
let wrap_config name config_jsont ~dec ~enc_config =
1352
+
(* Wraps {"name":"X","configuration":{...}} *)
1353
+
Jsont.Object.map ~kind:name (fun _name config -> dec config)
1354
+
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun _ -> name)
1355
+
|> Jsont.Object.mem "configuration" config_jsont
1356
+
~enc:enc_config
1357
+
|> Jsont.Object.skip_unknown
1358
+
|> Jsont.Object.finish
1359
+
in
1360
+
let bytes_obj = wrap_config "bytes" Codec.Bytes.jsont
1361
+
~dec:(fun b -> `Bytes b)
1362
+
~enc_config:(function `Bytes b -> b | _ -> assert false) in
1363
+
let gzip_obj = wrap_config "gzip" Codec.Gzip.jsont
1364
+
~dec:(fun g -> `Gzip g)
1365
+
~enc_config:(function `Gzip g -> g | _ -> assert false) in
1366
+
let blosc_obj = wrap_config "blosc" Codec.Blosc.jsont
1367
+
~dec:(fun b -> `Blosc b)
1368
+
~enc_config:(function `Blosc b -> b | _ -> assert false) in
1369
+
let transpose_obj = wrap_config "transpose" Codec.Transpose.jsont
1370
+
~dec:(fun t -> `Transpose t)
1371
+
~enc_config:(function `Transpose t -> t | _ -> assert false) in
1372
+
let crc32c_obj =
1373
+
Jsont.Object.map ~kind:"crc32c" (fun _name -> `Crc32c)
1374
+
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun _ -> "crc32c")
1375
+
|> Jsont.Object.skip_unknown
1376
+
|> Jsont.Object.finish
1377
+
in
1378
+
let sharding_config =
1379
+
let codec_list = Jsont.list (Jsont.rec' codec_jsont_lazy) in
1380
+
Jsont.Object.map ~kind:"Sharding.config"
1381
+
(fun chunk_shape codecs index_codecs index_location ->
1382
+
Codec.Sharding.{ chunk_shape; codecs; index_codecs; index_location })
1383
+
|> Jsont.Object.mem "chunk_shape" (Jsont.list Jsont.int)
1384
+
~enc:(fun (t : Codec.Sharding.t) -> t.chunk_shape)
1385
+
|> Jsont.Object.mem "codecs" codec_list
1386
+
~enc:(fun (t : Codec.Sharding.t) -> t.codecs)
1387
+
|> Jsont.Object.mem "index_codecs" codec_list
1388
+
~dec_absent:[] ~enc:(fun (t : Codec.Sharding.t) -> t.index_codecs)
1389
+
~enc_omit:(fun l -> l = [])
1390
+
|> Jsont.Object.mem "index_location" index_location_jsont
1391
+
~dec_absent:`End ~enc:(fun (t : Codec.Sharding.t) -> t.index_location)
1392
+
~enc_omit:(fun v -> v = `End)
1393
+
|> Jsont.Object.skip_unknown
1394
+
|> Jsont.Object.finish
1395
+
in
1396
+
let sharding_obj = wrap_config "sharding_indexed" sharding_config
1397
+
~dec:(fun s -> `Sharding s)
1398
+
~enc_config:(function `Sharding s -> s | _ -> assert false) in
1399
+
let other_obj = Jsont.map ~kind:"Other_codec"
1400
+
~dec:(fun o -> `Other o)
1401
+
~enc:(function `Other o -> o | _ -> assert false)
1402
+
Other_ext.jsont
1403
+
in
1404
+
(* Dispatch: decode JSON object, peek at "name" field *)
1405
+
(* Using Jsont.any with dec_object that tries each known codec *)
1406
+
(* Alternative: decode as JSON, inspect name, then re-decode *)
1407
+
let dec_object =
1408
+
Jsont.map ~kind:"codec"
1409
+
~dec:(fun json ->
1410
+
let try_decode codec =
1411
+
match Jsont.Json.decode codec json with
1412
+
| Ok v -> Some v
1413
+
| Error _ -> None
1414
+
in
1415
+
match try_decode bytes_obj with Some v -> v | None ->
1416
+
match try_decode gzip_obj with Some v -> v | None ->
1417
+
match try_decode blosc_obj with Some v -> v | None ->
1418
+
match try_decode crc32c_obj with Some v -> v | None ->
1419
+
match try_decode transpose_obj with Some v -> v | None ->
1420
+
match try_decode sharding_obj with Some v -> v | None ->
1421
+
match try_decode other_obj with Some v -> v | None ->
1422
+
failwith "Unknown codec")
1423
+
~enc:(fun v ->
1424
+
let codec = match v with
1425
+
| `Bytes _ -> bytes_obj
1426
+
| `Gzip _ -> gzip_obj
1427
+
| `Blosc _ -> blosc_obj
1428
+
| `Crc32c -> crc32c_obj
1429
+
| `Transpose _ -> transpose_obj
1430
+
| `Sharding _ -> sharding_obj
1431
+
| `Other _ -> other_obj
1432
+
in
1433
+
match Jsont.Json.encode codec v with
1434
+
| Ok json -> json
1435
+
| Error e -> failwith e)
1436
+
Jsont.json_object
1437
+
in
1438
+
dec_object
1439
+
)
1440
+
1441
+
let codec_jsont = Lazy.force codec_jsont_lazy
1442
+
end
1443
+
```
1444
+
1445
+
Note: The dispatch approach above decodes the full JSON object then tries each known codec. This works but is not the most efficient. An alternative is to use `case_mem` on the `"name"` field. The implementer should choose whichever approach compiles cleanly with the actual jsont API. The `case_mem` approach would look like:
1446
+
1447
+
```ocaml
1448
+
let case_bytes = Jsont.Object.Case.map "bytes" bytes_inner ~dec:(fun b -> `Bytes b) in
1449
+
(* ... *)
1450
+
Jsont.Object.map Fun.id
1451
+
|> Jsont.Object.case_mem "name" Jsont.string ~enc_case ...
1452
+
|> Jsont.Object.finish
1453
+
```
1454
+
1455
+
But this requires the configuration to be flattened into the same object level as `"name"`, which doesn't match the v3 spec format (`"configuration"` is a nested object). So the decode-and-dispatch approach is likely correct.
1456
+
1457
+
- [ ] **Step 4: Run test to verify it passes**
1458
+
1459
+
Run: `dune test`
1460
+
Expected: PASS — "test_v3_codecs: ok"
1461
+
1462
+
- [ ] **Step 5: Write sharding test**
1463
+
1464
+
```ocaml
1465
+
let test_v3_sharding () =
1466
+
let c = Zarr_jsont.V3.codec_jsont in
1467
+
let json = {|{"name":"sharding_indexed","configuration":{"chunk_shape":[32,32],"codecs":[{"name":"bytes","configuration":{"endian":"little"}}],"index_location":"end"}}|} in
1468
+
let v = decode c json in
1469
+
(match v with
1470
+
| `Sharding s ->
1471
+
assert (Zarr_jsont.V3.Codec.Sharding.chunk_shape s = [32; 32]);
1472
+
assert (List.length (Zarr_jsont.V3.Codec.Sharding.codecs s) = 1);
1473
+
assert (Zarr_jsont.V3.Codec.Sharding.index_location s = `End)
1474
+
| _ -> assert false);
1475
+
print_endline "test_v3_sharding: ok"
1476
+
1477
+
let () = test_v3_sharding ()
1478
+
```
1479
+
1480
+
- [ ] **Step 6: Run test**
1481
+
1482
+
Run: `dune test`
1483
+
Expected: PASS
1484
+
1485
+
- [ ] **Step 7: Commit**
1486
+
1487
+
```bash
1488
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
1489
+
git commit -m "feat: V3 codec types (bytes, gzip, blosc, crc32c, transpose, sharding)"
1490
+
```
1491
+
1492
+
---
1493
+
1494
+
### Task 8: V3 Data_type, Chunk_grid, Chunk_key_encoding, Array_meta
1495
+
1496
+
**Files:**
1497
+
- Modify: `src/zarr_jsont.ml`
1498
+
- Modify: `src/zarr_jsont.mli`
1499
+
- Modify: `test/test_zarr_jsont.ml`
1500
+
1501
+
- [ ] **Step 1: Write failing tests**
1502
+
1503
+
```ocaml
1504
+
let test_v3_data_type () =
1505
+
let dt = Zarr_jsont.V3.data_type_jsont in
1506
+
(* string form *)
1507
+
assert (decode dt {|"float64"|} = `Float64);
1508
+
assert (decode dt {|"bool"|} = `Bool);
1509
+
assert (decode dt {|"int32"|} = `Int32);
1510
+
assert (decode dt {|"r16"|} = `Raw 16);
1511
+
(* extension form *)
1512
+
let v = decode dt {|{"name":"datetime","configuration":{"unit":"ns"}}|} in
1513
+
(match v with
1514
+
| `Other o -> assert (Zarr_jsont.Other_ext.name o = "datetime")
1515
+
| _ -> assert false);
1516
+
print_endline "test_v3_data_type: ok"
1517
+
1518
+
let test_v3_array_meta () =
1519
+
let json = {|{
1520
+
"zarr_format": 3,
1521
+
"node_type": "array",
1522
+
"shape": [10000, 1000],
1523
+
"dimension_names": ["rows", "columns"],
1524
+
"data_type": "float64",
1525
+
"chunk_grid": {"name": "regular", "configuration": {"chunk_shape": [1000, 100]}},
1526
+
"chunk_key_encoding": {"name": "default", "configuration": {"separator": "/"}},
1527
+
"codecs": [{"name": "bytes", "configuration": {"endian": "little"}}],
1528
+
"fill_value": "NaN",
1529
+
"attributes": {"foo": 42}
1530
+
}|} in
1531
+
let v = decode Zarr_jsont.V3.array_meta_jsont json in
1532
+
assert (Zarr_jsont.V3.Array_meta.shape v = [10000; 1000]);
1533
+
assert (Zarr_jsont.V3.Array_meta.data_type v = `Float64);
1534
+
assert (Zarr_jsont.V3.Array_meta.dimension_names v
1535
+
= Some [Some "rows"; Some "columns"]);
1536
+
(match Zarr_jsont.V3.Array_meta.chunk_grid v with
1537
+
| `Regular r ->
1538
+
assert (Zarr_jsont.V3.Chunk_grid.Regular.chunk_shape r = [1000; 100])
1539
+
| _ -> assert false);
1540
+
print_endline "test_v3_array_meta: ok"
1541
+
1542
+
let () = test_v3_data_type ()
1543
+
let () = test_v3_array_meta ()
1544
+
```
1545
+
1546
+
- [ ] **Step 2: Run test to verify it fails**
1547
+
1548
+
Run: `dune test`
1549
+
Expected: FAIL
1550
+
1551
+
- [ ] **Step 3: Implement V3 Data_type, Chunk_grid, Chunk_key_encoding**
1552
+
1553
+
Add to `src/zarr_jsont.mli` inside `V3`:
1554
+
1555
+
```ocaml
1556
+
module Data_type : sig
1557
+
type t = [
1558
+
| `Bool | `Int8 | `Int16 | `Int32 | `Int64
1559
+
| `Uint8 | `Uint16 | `Uint32 | `Uint64
1560
+
| `Float16 | `Float32 | `Float64
1561
+
| `Complex64 | `Complex128
1562
+
| `Raw of int
1563
+
| `Other of Other_ext.t
1564
+
]
1565
+
end
1566
+
val data_type_jsont : Data_type.t Jsont.t
1567
+
1568
+
module Chunk_grid : sig
1569
+
module Regular : sig
1570
+
type t
1571
+
val chunk_shape : t -> int list
1572
+
end
1573
+
type t = [ `Regular of Regular.t | `Other of Other_ext.t ]
1574
+
end
1575
+
val chunk_grid_jsont : Chunk_grid.t Jsont.t
1576
+
1577
+
module Chunk_key_encoding : sig
1578
+
module Default : sig
1579
+
type t
1580
+
val separator : t -> [ `Slash | `Dot ]
1581
+
end
1582
+
type t = [ `Default of Default.t | `Other of Other_ext.t ]
1583
+
end
1584
+
val chunk_key_encoding_jsont : Chunk_key_encoding.t Jsont.t
1585
+
1586
+
module Array_meta : sig
1587
+
type t
1588
+
val shape : t -> int list
1589
+
val data_type : t -> Data_type.t
1590
+
val chunk_grid : t -> Chunk_grid.t
1591
+
val chunk_key_encoding : t -> Chunk_key_encoding.t
1592
+
val codecs : t -> codec list
1593
+
val fill_value : t -> fill_value
1594
+
val dimension_names : t -> string option list option
1595
+
val storage_transformers : t -> Other_ext.t list option
1596
+
val unknown : t -> Jsont.json
1597
+
end
1598
+
val array_meta_jsont : Array_meta.t Jsont.t
1599
+
```
1600
+
1601
+
Add to `src/zarr_jsont.ml` inside `V3`:
1602
+
1603
+
```ocaml
1604
+
module Data_type = struct
1605
+
type t = [
1606
+
| `Bool | `Int8 | `Int16 | `Int32 | `Int64
1607
+
| `Uint8 | `Uint16 | `Uint32 | `Uint64
1608
+
| `Float16 | `Float32 | `Float64
1609
+
| `Complex64 | `Complex128
1610
+
| `Raw of int
1611
+
| `Other of Other_ext.t
1612
+
]
1613
+
end
1614
+
1615
+
let data_type_jsont =
1616
+
let known = [
1617
+
"bool", `Bool; "int8", `Int8; "int16", `Int16; "int32", `Int32;
1618
+
"int64", `Int64; "uint8", `Uint8; "uint16", `Uint16;
1619
+
"uint32", `Uint32; "uint64", `Uint64; "float16", `Float16;
1620
+
"float32", `Float32; "float64", `Float64;
1621
+
"complex64", `Complex64; "complex128", `Complex128;
1622
+
] in
1623
+
let from_string = Jsont.map ~kind:"data_type"
1624
+
~dec:(fun s ->
1625
+
match List.assoc_opt s known with
1626
+
| Some t -> t
1627
+
| None ->
1628
+
(* Check for r* pattern *)
1629
+
if String.length s > 1 && s.[0] = 'r' then
1630
+
let bits = int_of_string (String.sub s 1 (String.length s - 1)) in
1631
+
`Raw bits
1632
+
else
1633
+
failwith ("Unknown data type: " ^ s))
1634
+
~enc:(fun dt ->
1635
+
match List.find_opt (fun (_, v) -> v = dt) known with
1636
+
| Some (s, _) -> s
1637
+
| None -> match dt with
1638
+
| `Raw bits -> "r" ^ string_of_int bits
1639
+
| _ -> assert false)
1640
+
Jsont.string
1641
+
in
1642
+
let from_object = Jsont.map ~kind:"data_type"
1643
+
~dec:(fun o -> `Other o)
1644
+
~enc:(function `Other o -> o | _ -> assert false)
1645
+
Other_ext.jsont
1646
+
in
1647
+
let enc = function
1648
+
| `Other _ -> from_object
1649
+
| _ -> from_string
1650
+
in
1651
+
Jsont.any ~kind:"data_type" ~dec_string:from_string
1652
+
~dec_object:from_object ~enc ()
1653
+
1654
+
module Chunk_grid = struct
1655
+
module Regular = struct
1656
+
type t = { chunk_shape : int list }
1657
+
let chunk_shape t = t.chunk_shape
1658
+
let jsont =
1659
+
Jsont.Object.map ~kind:"Regular" (fun chunk_shape -> { chunk_shape })
1660
+
|> Jsont.Object.mem "chunk_shape" (Jsont.list Jsont.int)
1661
+
~enc:(fun t -> t.chunk_shape)
1662
+
|> Jsont.Object.skip_unknown
1663
+
|> Jsont.Object.finish
1664
+
end
1665
+
type t = [ `Regular of Regular.t | `Other of Other_ext.t ]
1666
+
end
1667
+
1668
+
let chunk_grid_jsont =
1669
+
(* {"name":"regular","configuration":{"chunk_shape":[...]}} *)
1670
+
let decode_named json =
1671
+
match Jsont.Json.decode (Jsont.Object.as_string_map Jsont.json) json with
1672
+
| Error e -> failwith e
1673
+
| Ok map ->
1674
+
let module M = Map.Make(String) in
1675
+
let name = match M.find_opt "name" map with
1676
+
| Some (Jsont.String (_, s)) -> s
1677
+
| _ -> failwith "missing name" in
1678
+
match name with
1679
+
| "regular" ->
1680
+
let config = match M.find_opt "configuration" map with
1681
+
| Some c -> c | None -> failwith "missing configuration" in
1682
+
(match Jsont.Json.decode Chunk_grid.Regular.jsont config with
1683
+
| Ok r -> `Regular r
1684
+
| Error e -> failwith e)
1685
+
| _ ->
1686
+
(match Jsont.Json.decode Other_ext.jsont json with
1687
+
| Ok o -> `Other o
1688
+
| Error e -> failwith e)
1689
+
in
1690
+
Jsont.map ~kind:"chunk_grid"
1691
+
~dec:decode_named
1692
+
~enc:(function
1693
+
| `Regular r ->
1694
+
let config = match Jsont.Json.encode Chunk_grid.Regular.jsont r with
1695
+
| Ok j -> j | Error e -> failwith e in
1696
+
Jsont.Json.object' [
1697
+
(Jsont.Meta.none, "name"), Jsont.Json.string "regular";
1698
+
(Jsont.Meta.none, "configuration"), config;
1699
+
]
1700
+
| `Other o ->
1701
+
(match Jsont.Json.encode Other_ext.jsont o with
1702
+
| Ok j -> j | Error e -> failwith e))
1703
+
Jsont.json
1704
+
1705
+
module Chunk_key_encoding = struct
1706
+
module Default = struct
1707
+
type t = { separator : [ `Slash | `Dot ] }
1708
+
let separator t = t.separator
1709
+
let sep_jsont = Jsont.enum ~kind:"separator" ["/", `Slash; ".", `Dot]
1710
+
let jsont =
1711
+
Jsont.Object.map ~kind:"Default" (fun separator -> { separator })
1712
+
|> Jsont.Object.mem "separator" sep_jsont
1713
+
~dec_absent:`Slash ~enc:(fun t -> t.separator)
1714
+
|> Jsont.Object.skip_unknown
1715
+
|> Jsont.Object.finish
1716
+
end
1717
+
type t = [ `Default of Default.t | `Other of Other_ext.t ]
1718
+
end
1719
+
1720
+
let chunk_key_encoding_jsont =
1721
+
(* Same pattern as chunk_grid *)
1722
+
Jsont.map ~kind:"chunk_key_encoding"
1723
+
~dec:(fun json ->
1724
+
let module M = Map.Make(String) in
1725
+
match Jsont.Json.decode (Jsont.Object.as_string_map Jsont.json) json with
1726
+
| Error e -> failwith e
1727
+
| Ok map ->
1728
+
let name = match M.find_opt "name" map with
1729
+
| Some (Jsont.String (_, s)) -> s
1730
+
| _ -> failwith "missing name" in
1731
+
match name with
1732
+
| "default" ->
1733
+
let config = match M.find_opt "configuration" map with
1734
+
| Some c -> c
1735
+
| None -> Jsont.Json.object' [] in
1736
+
(match Jsont.Json.decode Chunk_key_encoding.Default.jsont config with
1737
+
| Ok d -> `Default d
1738
+
| Error e -> failwith e)
1739
+
| _ ->
1740
+
(match Jsont.Json.decode Other_ext.jsont json with
1741
+
| Ok o -> `Other o
1742
+
| Error e -> failwith e))
1743
+
~enc:(function
1744
+
| `Default d ->
1745
+
let config = match Jsont.Json.encode Chunk_key_encoding.Default.jsont d with
1746
+
| Ok j -> j | Error e -> failwith e in
1747
+
Jsont.Json.object' [
1748
+
(Jsont.Meta.none, "name"), Jsont.Json.string "default";
1749
+
(Jsont.Meta.none, "configuration"), config;
1750
+
]
1751
+
| `Other o ->
1752
+
(match Jsont.Json.encode Other_ext.jsont o with
1753
+
| Ok j -> j | Error e -> failwith e))
1754
+
Jsont.json
1755
+
1756
+
module Array_meta = struct
1757
+
type t = {
1758
+
shape : int list;
1759
+
data_type : Data_type.t;
1760
+
chunk_grid : Chunk_grid.t;
1761
+
chunk_key_encoding : Chunk_key_encoding.t;
1762
+
codecs : codec list;
1763
+
fill_value : fill_value;
1764
+
dimension_names : string option list option;
1765
+
storage_transformers : Other_ext.t list option;
1766
+
unknown : Jsont.json;
1767
+
}
1768
+
let shape t = t.shape
1769
+
let data_type t = t.data_type
1770
+
let chunk_grid t = t.chunk_grid
1771
+
let chunk_key_encoding t = t.chunk_key_encoding
1772
+
let codecs t = t.codecs
1773
+
let fill_value t = t.fill_value
1774
+
let dimension_names t = t.dimension_names
1775
+
let storage_transformers t = t.storage_transformers
1776
+
let unknown t = t.unknown
1777
+
end
1778
+
1779
+
let dim_name_jsont = Jsont.option Jsont.string
1780
+
1781
+
let array_meta_jsont =
1782
+
Jsont.Object.map ~kind:"V3.Array_meta"
1783
+
(fun _zarr_format _node_type shape data_type chunk_grid
1784
+
chunk_key_encoding codecs fill_value dimension_names
1785
+
storage_transformers _attributes unknown ->
1786
+
Array_meta.{ shape; data_type; chunk_grid; chunk_key_encoding;
1787
+
codecs; fill_value; dimension_names;
1788
+
storage_transformers; unknown })
1789
+
|> Jsont.Object.mem "zarr_format" Jsont.int ~enc:(fun _ -> 3)
1790
+
|> Jsont.Object.mem "node_type" Jsont.string ~enc:(fun _ -> "array")
1791
+
|> Jsont.Object.mem "shape" (Jsont.list Jsont.int)
1792
+
~enc:(fun (t : Array_meta.t) -> t.shape)
1793
+
|> Jsont.Object.mem "data_type" data_type_jsont
1794
+
~enc:(fun (t : Array_meta.t) -> t.data_type)
1795
+
|> Jsont.Object.mem "chunk_grid" chunk_grid_jsont
1796
+
~enc:(fun (t : Array_meta.t) -> t.chunk_grid)
1797
+
|> Jsont.Object.mem "chunk_key_encoding" chunk_key_encoding_jsont
1798
+
~enc:(fun (t : Array_meta.t) -> t.chunk_key_encoding)
1799
+
|> Jsont.Object.mem "codecs" (Jsont.list codec_jsont)
1800
+
~enc:(fun (t : Array_meta.t) -> t.codecs)
1801
+
|> Jsont.Object.mem "fill_value" fill_value_jsont
1802
+
~enc:(fun (t : Array_meta.t) -> t.fill_value)
1803
+
|> Jsont.Object.opt_mem "dimension_names" (Jsont.list dim_name_jsont)
1804
+
~enc:(fun (t : Array_meta.t) -> t.dimension_names)
1805
+
|> Jsont.Object.opt_mem "storage_transformers"
1806
+
(Jsont.list Other_ext.jsont)
1807
+
~enc:(fun (t : Array_meta.t) -> t.storage_transformers)
1808
+
|> Jsont.Object.mem "attributes" Jsont.json
1809
+
~dec_absent:(Jsont.Json.object' [])
1810
+
~enc:(fun _ -> Jsont.Json.object' [])
1811
+
~enc_omit:(fun _ -> true)
1812
+
|> Jsont.Object.keep_unknown Jsont.json_mems
1813
+
~enc:(fun (t : Array_meta.t) -> t.unknown)
1814
+
|> Jsont.Object.finish
1815
+
```
1816
+
1817
+
Note: The `attributes` member is consumed here to prevent it from being captured in `unknown`, but the actual attributes decoding happens at the Node level. This is a placeholder — the implementer may need to adjust the approach when integrating with the `Attrs` module in Task 9.
1818
+
1819
+
- [ ] **Step 4: Run tests**
1820
+
1821
+
Run: `dune test`
1822
+
Expected: PASS — "test_v3_data_type: ok", "test_v3_array_meta: ok"
1823
+
1824
+
- [ ] **Step 5: Commit**
1825
+
1826
+
```bash
1827
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
1828
+
git commit -m "feat: V3 data_type, chunk_grid, chunk_key_encoding, array_meta"
1829
+
```
1830
+
1831
+
---
1832
+
1833
+
### Task 9: Conventions (Proj, Spatial, Multiscales)
1834
+
1835
+
**Files:**
1836
+
- Modify: `src/zarr_jsont.ml`
1837
+
- Modify: `src/zarr_jsont.mli`
1838
+
- Modify: `test/test_zarr_jsont.ml`
1839
+
1840
+
- [ ] **Step 1: Write failing tests for conventions**
1841
+
1842
+
```ocaml
1843
+
let test_conv_proj () =
1844
+
(* Test proj decoding from an attributes-like object *)
1845
+
let json = {|{"proj:code":"EPSG:4326","proj:wkt2":null}|} in
1846
+
let v = decode Zarr_jsont.Conv.Proj.jsont json in
1847
+
assert (Zarr_jsont.Conv.Proj.code v = Some "EPSG:4326");
1848
+
assert (Zarr_jsont.Conv.Proj.wkt2 v = None);
1849
+
assert (Zarr_jsont.Conv.Proj.projjson v = None);
1850
+
print_endline "test_conv_proj: ok"
1851
+
1852
+
let test_conv_spatial () =
1853
+
let json = {|{
1854
+
"spatial:dimensions": ["Y", "X"],
1855
+
"spatial:bbox": [-180.0, -90.0, 180.0, 90.0],
1856
+
"spatial:transform": [1.0, 0.0, 0.0, 0.0, -1.0, 90.0],
1857
+
"spatial:registration": "pixel"
1858
+
}|} in
1859
+
let v = decode Zarr_jsont.Conv.Spatial.jsont json in
1860
+
assert (Zarr_jsont.Conv.Spatial.dimensions v = ["Y"; "X"]);
1861
+
assert (Zarr_jsont.Conv.Spatial.registration v = Some `Pixel);
1862
+
assert (Zarr_jsont.Conv.Spatial.bbox v = Some [-180.0; -90.0; 180.0; 90.0]);
1863
+
print_endline "test_conv_spatial: ok"
1864
+
1865
+
let test_conv_multiscales () =
1866
+
let json = {|{
1867
+
"layout": [
1868
+
{"asset": "0", "transform": {"scale": [1.0, 1.0]}},
1869
+
{"asset": "1", "derived_from": "0", "transform": {"scale": [2.0, 2.0]}, "resampling_method": "average"}
1870
+
],
1871
+
"resampling_method": "average"
1872
+
}|} in
1873
+
let v = decode Zarr_jsont.Conv.Multiscales.jsont json in
1874
+
let layout = Zarr_jsont.Conv.Multiscales.layout v in
1875
+
assert (List.length layout = 2);
1876
+
let item0 = List.nth layout 0 in
1877
+
assert (Zarr_jsont.Conv.Multiscales.Layout_item.asset item0 = "0");
1878
+
assert (Zarr_jsont.Conv.Multiscales.Layout_item.derived_from item0 = None);
1879
+
let item1 = List.nth layout 1 in
1880
+
assert (Zarr_jsont.Conv.Multiscales.Layout_item.derived_from item1 = Some "0");
1881
+
assert (Zarr_jsont.Conv.Multiscales.Layout_item.resampling_method item1
1882
+
= Some "average");
1883
+
print_endline "test_conv_multiscales: ok"
1884
+
1885
+
let () = test_conv_proj ()
1886
+
let () = test_conv_spatial ()
1887
+
let () = test_conv_multiscales ()
1888
+
```
1889
+
1890
+
- [ ] **Step 2: Run test to verify it fails**
1891
+
1892
+
Run: `dune test`
1893
+
Expected: FAIL — `Conv` not defined
1894
+
1895
+
- [ ] **Step 3: Implement Conv.Meta**
1896
+
1897
+
In `src/zarr_jsont.mli`:
1898
+
1899
+
```ocaml
1900
+
module Conv : sig
1901
+
module Meta : sig
1902
+
type t
1903
+
val uuid : t -> string
1904
+
val name : t -> string
1905
+
val schema_url : t -> string option
1906
+
val spec_url : t -> string option
1907
+
val description : t -> string option
1908
+
val jsont : t Jsont.t
1909
+
end
1910
+
```
1911
+
1912
+
In `src/zarr_jsont.ml`:
1913
+
1914
+
```ocaml
1915
+
module Conv = struct
1916
+
module Meta = struct
1917
+
type t = {
1918
+
uuid : string;
1919
+
name : string;
1920
+
schema_url : string option;
1921
+
spec_url : string option;
1922
+
description : string option;
1923
+
}
1924
+
let uuid t = t.uuid
1925
+
let name t = t.name
1926
+
let schema_url t = t.schema_url
1927
+
let spec_url t = t.spec_url
1928
+
let description t = t.description
1929
+
1930
+
let jsont =
1931
+
Jsont.Object.map ~kind:"Conv.Meta"
1932
+
(fun uuid name schema_url spec_url description ->
1933
+
{ uuid; name; schema_url; spec_url; description })
1934
+
|> Jsont.Object.mem "uuid" Jsont.string ~enc:(fun t -> t.uuid)
1935
+
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun t -> t.name)
1936
+
|> Jsont.Object.opt_mem "schema_url" Jsont.string
1937
+
~enc:(fun t -> t.schema_url)
1938
+
|> Jsont.Object.opt_mem "spec_url" Jsont.string
1939
+
~enc:(fun t -> t.spec_url)
1940
+
|> Jsont.Object.opt_mem "description" Jsont.string
1941
+
~enc:(fun t -> t.description)
1942
+
|> Jsont.Object.skip_unknown
1943
+
|> Jsont.Object.finish
1944
+
end
1945
+
```
1946
+
1947
+
- [ ] **Step 4: Implement Conv.Proj**
1948
+
1949
+
Note: `Conv.Proj.jsont` decodes the `proj:` prefixed attributes from a flat object. This is **not** a standalone object codec — it's designed to be composed into `Attrs`. However for testing we can decode from a flat object containing `proj:*` keys.
1950
+
1951
+
In `src/zarr_jsont.mli` inside `Conv`:
1952
+
1953
+
```ocaml
1954
+
module Proj : sig
1955
+
type t
1956
+
val code : t -> string option
1957
+
val wkt2 : t -> string option
1958
+
val projjson : t -> Jsont.json option
1959
+
val meta : Meta.t
1960
+
val jsont : t Jsont.t
1961
+
end
1962
+
```
1963
+
1964
+
In `src/zarr_jsont.ml` inside `Conv`:
1965
+
1966
+
```ocaml
1967
+
module Proj = struct
1968
+
type t = {
1969
+
code : string option;
1970
+
wkt2 : string option;
1971
+
projjson : Jsont.json option;
1972
+
}
1973
+
let code t = t.code
1974
+
let wkt2 t = t.wkt2
1975
+
let projjson t = t.projjson
1976
+
let meta = Meta.{
1977
+
uuid = "f17cb550-5864-4468-aeb7-f3180cfb622f";
1978
+
name = "proj:";
1979
+
schema_url = Some "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json";
1980
+
spec_url = Some "https://github.com/zarr-experimental/geo-proj/blob/v1/README.md";
1981
+
description = Some "Coordinate reference system information for geospatial data";
1982
+
}
1983
+
1984
+
let jsont =
1985
+
Jsont.Object.map ~kind:"Proj"
1986
+
(fun code wkt2 projjson -> { code; wkt2; projjson })
1987
+
|> Jsont.Object.opt_mem "proj:code" Jsont.string
1988
+
~enc:(fun t -> t.code)
1989
+
|> Jsont.Object.opt_mem "proj:wkt2" Jsont.string
1990
+
~enc:(fun t -> t.wkt2)
1991
+
|> Jsont.Object.opt_mem "proj:projjson" Jsont.json
1992
+
~enc:(fun t -> t.projjson)
1993
+
|> Jsont.Object.skip_unknown
1994
+
|> Jsont.Object.finish
1995
+
end
1996
+
```
1997
+
1998
+
- [ ] **Step 5: Implement Conv.Spatial**
1999
+
2000
+
In `src/zarr_jsont.mli` inside `Conv`:
2001
+
2002
+
```ocaml
2003
+
module Spatial : sig
2004
+
type t
2005
+
val dimensions : t -> string list
2006
+
val bbox : t -> float list option
2007
+
val transform_type : t -> string option
2008
+
val transform : t -> float list option
2009
+
val shape : t -> int list option
2010
+
val registration : t -> [ `Pixel | `Node ] option
2011
+
val meta : Meta.t
2012
+
val jsont : t Jsont.t
2013
+
end
2014
+
```
2015
+
2016
+
In `src/zarr_jsont.ml` inside `Conv`:
2017
+
2018
+
```ocaml
2019
+
module Spatial = struct
2020
+
type t = {
2021
+
dimensions : string list;
2022
+
bbox : float list option;
2023
+
transform_type : string option;
2024
+
transform : float list option;
2025
+
shape : int list option;
2026
+
registration : [ `Pixel | `Node ] option;
2027
+
}
2028
+
let dimensions t = t.dimensions
2029
+
let bbox t = t.bbox
2030
+
let transform_type t = t.transform_type
2031
+
let transform t = t.transform
2032
+
let shape t = t.shape
2033
+
let registration t = t.registration
2034
+
let meta = Meta.{
2035
+
uuid = "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4";
2036
+
name = "spatial:";
2037
+
schema_url = Some "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json";
2038
+
spec_url = Some "https://github.com/zarr-conventions/spatial/blob/v1/README.md";
2039
+
description = Some "Spatial coordinate information";
2040
+
}
2041
+
2042
+
let registration_jsont =
2043
+
Jsont.enum ~kind:"registration" ["pixel", `Pixel; "node", `Node]
2044
+
2045
+
let jsont =
2046
+
Jsont.Object.map ~kind:"Spatial"
2047
+
(fun dimensions bbox transform_type transform shape registration ->
2048
+
{ dimensions; bbox; transform_type; transform; shape; registration })
2049
+
|> Jsont.Object.mem "spatial:dimensions" (Jsont.list Jsont.string)
2050
+
~enc:(fun t -> t.dimensions)
2051
+
|> Jsont.Object.opt_mem "spatial:bbox" (Jsont.list Jsont.number)
2052
+
~enc:(fun t -> t.bbox)
2053
+
|> Jsont.Object.opt_mem "spatial:transform_type" Jsont.string
2054
+
~enc:(fun t -> t.transform_type)
2055
+
|> Jsont.Object.opt_mem "spatial:transform" (Jsont.list Jsont.number)
2056
+
~enc:(fun t -> t.transform)
2057
+
|> Jsont.Object.opt_mem "spatial:shape" (Jsont.list Jsont.int)
2058
+
~enc:(fun t -> t.shape)
2059
+
|> Jsont.Object.opt_mem "spatial:registration" registration_jsont
2060
+
~enc:(fun t -> t.registration)
2061
+
|> Jsont.Object.skip_unknown
2062
+
|> Jsont.Object.finish
2063
+
end
2064
+
```
2065
+
2066
+
- [ ] **Step 6: Implement Conv.Multiscales**
2067
+
2068
+
In `src/zarr_jsont.mli` inside `Conv`:
2069
+
2070
+
```ocaml
2071
+
module Multiscales : sig
2072
+
module Transform : sig
2073
+
type t
2074
+
val scale : t -> float list option
2075
+
val translation : t -> float list option
2076
+
val unknown : t -> Jsont.json
2077
+
end
2078
+
module Layout_item : sig
2079
+
type t
2080
+
val asset : t -> string
2081
+
val derived_from : t -> string option
2082
+
val transform : t -> Transform.t option
2083
+
val resampling_method : t -> string option
2084
+
val unknown : t -> Jsont.json
2085
+
end
2086
+
type t
2087
+
val layout : t -> Layout_item.t list
2088
+
val resampling_method : t -> string option
2089
+
val meta : Meta.t
2090
+
val jsont : t Jsont.t
2091
+
end
2092
+
end
2093
+
```
2094
+
2095
+
In `src/zarr_jsont.ml` inside `Conv`:
2096
+
2097
+
```ocaml
2098
+
module Multiscales = struct
2099
+
module Transform = struct
2100
+
type t = {
2101
+
scale : float list option;
2102
+
translation : float list option;
2103
+
unknown : Jsont.json;
2104
+
}
2105
+
let scale t = t.scale
2106
+
let translation t = t.translation
2107
+
let unknown t = t.unknown
2108
+
2109
+
let jsont =
2110
+
Jsont.Object.map ~kind:"Transform"
2111
+
(fun scale translation unknown ->
2112
+
{ scale; translation; unknown })
2113
+
|> Jsont.Object.opt_mem "scale" (Jsont.list Jsont.number)
2114
+
~enc:(fun t -> t.scale)
2115
+
|> Jsont.Object.opt_mem "translation" (Jsont.list Jsont.number)
2116
+
~enc:(fun t -> t.translation)
2117
+
|> Jsont.Object.keep_unknown Jsont.json_mems
2118
+
~enc:(fun t -> t.unknown)
2119
+
|> Jsont.Object.finish
2120
+
end
2121
+
2122
+
module Layout_item = struct
2123
+
type t = {
2124
+
asset : string;
2125
+
derived_from : string option;
2126
+
transform : Transform.t option;
2127
+
resampling_method : string option;
2128
+
unknown : Jsont.json;
2129
+
}
2130
+
let asset t = t.asset
2131
+
let derived_from t = t.derived_from
2132
+
let transform t = t.transform
2133
+
let resampling_method t = t.resampling_method
2134
+
let unknown t = t.unknown
2135
+
2136
+
let jsont =
2137
+
Jsont.Object.map ~kind:"Layout_item"
2138
+
(fun asset derived_from transform resampling_method unknown ->
2139
+
{ asset; derived_from; transform; resampling_method; unknown })
2140
+
|> Jsont.Object.mem "asset" Jsont.string
2141
+
~enc:(fun t -> t.asset)
2142
+
|> Jsont.Object.opt_mem "derived_from" Jsont.string
2143
+
~enc:(fun t -> t.derived_from)
2144
+
|> Jsont.Object.opt_mem "transform" Transform.jsont
2145
+
~enc:(fun t -> t.transform)
2146
+
|> Jsont.Object.opt_mem "resampling_method" Jsont.string
2147
+
~enc:(fun t -> t.resampling_method)
2148
+
|> Jsont.Object.keep_unknown Jsont.json_mems
2149
+
~enc:(fun t -> t.unknown)
2150
+
|> Jsont.Object.finish
2151
+
end
2152
+
2153
+
type t = {
2154
+
layout : Layout_item.t list;
2155
+
resampling_method : string option;
2156
+
}
2157
+
let layout t = t.layout
2158
+
let resampling_method t = t.resampling_method
2159
+
let meta = Meta.{
2160
+
uuid = "d35379db-88df-4056-af3a-620245f8e347";
2161
+
name = "multiscales";
2162
+
schema_url = Some "https://raw.githubusercontent.com/zarr-conventions/multiscales/refs/tags/v1/schema.json";
2163
+
spec_url = Some "https://github.com/zarr-conventions/multiscales/blob/v1/README.md";
2164
+
description = Some "Multiscale layout of zarr datasets";
2165
+
}
2166
+
2167
+
let jsont =
2168
+
Jsont.Object.map ~kind:"Multiscales"
2169
+
(fun layout resampling_method -> { layout; resampling_method })
2170
+
|> Jsont.Object.mem "layout" (Jsont.list Layout_item.jsont)
2171
+
~enc:(fun t -> t.layout)
2172
+
|> Jsont.Object.opt_mem "resampling_method" Jsont.string
2173
+
~enc:(fun t -> t.resampling_method)
2174
+
|> Jsont.Object.skip_unknown
2175
+
|> Jsont.Object.finish
2176
+
end
2177
+
end
2178
+
```
2179
+
2180
+
- [ ] **Step 7: Run tests**
2181
+
2182
+
Run: `dune test`
2183
+
Expected: PASS — "test_conv_proj: ok", "test_conv_spatial: ok", "test_conv_multiscales: ok"
2184
+
2185
+
- [ ] **Step 8: Commit**
2186
+
2187
+
```bash
2188
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
2189
+
git commit -m "feat: Conv.Proj, Conv.Spatial, Conv.Multiscales codecs"
2190
+
```
2191
+
2192
+
---
2193
+
2194
+
### Task 10: Attrs — composable attributes with convention auto-registration
2195
+
2196
+
**Files:**
2197
+
- Modify: `src/zarr_jsont.ml`
2198
+
- Modify: `src/zarr_jsont.mli`
2199
+
- Modify: `test/test_zarr_jsont.ml`
2200
+
2201
+
- [ ] **Step 1: Write failing test for Attrs**
2202
+
2203
+
```ocaml
2204
+
let test_attrs () =
2205
+
let json = {|{
2206
+
"zarr_conventions": [
2207
+
{"uuid": "f17cb550-5864-4468-aeb7-f3180cfb622f", "name": "proj:", "description": "CRS info"}
2208
+
],
2209
+
"proj:code": "EPSG:3857",
2210
+
"spatial:dimensions": ["Y", "X"],
2211
+
"spatial:transform": [10.0, 0.0, 0.0, 0.0, -10.0, 100.0],
2212
+
"custom_key": "custom_value"
2213
+
}|} in
2214
+
let v = decode Zarr_jsont.attrs_jsont json in
2215
+
(* proj convention decoded *)
2216
+
(match Zarr_jsont.Attrs.proj v with
2217
+
| Some p -> assert (Zarr_jsont.Conv.Proj.code p = Some "EPSG:3857")
2218
+
| None -> assert false);
2219
+
(* spatial convention decoded *)
2220
+
(match Zarr_jsont.Attrs.spatial v with
2221
+
| Some s -> assert (Zarr_jsont.Conv.Spatial.dimensions s = ["Y"; "X"])
2222
+
| None -> assert false);
2223
+
(* no multiscales *)
2224
+
assert (Zarr_jsont.Attrs.multiscales v = None);
2225
+
(* conventions list populated *)
2226
+
assert (List.length (Zarr_jsont.Attrs.conventions v) >= 1);
2227
+
print_endline "test_attrs: ok"
2228
+
2229
+
let () = test_attrs ()
2230
+
```
2231
+
2232
+
- [ ] **Step 2: Run test to verify it fails**
2233
+
2234
+
Run: `dune test`
2235
+
Expected: FAIL — `Attrs` / `attrs_jsont` not defined
2236
+
2237
+
- [ ] **Step 3: Implement Attrs**
2238
+
2239
+
The key challenge: `Attrs` must decode convention-namespaced keys from a flat JSON object, compose with `keep_unknown` for remaining keys, and auto-populate `zarr_conventions` on encode.
2240
+
2241
+
In `src/zarr_jsont.mli`:
2242
+
2243
+
```ocaml
2244
+
module Attrs : sig
2245
+
type t
2246
+
val conventions : t -> Conv.Meta.t list
2247
+
val proj : t -> Conv.Proj.t option
2248
+
val spatial : t -> Conv.Spatial.t option
2249
+
val multiscales : t -> Conv.Multiscales.t option
2250
+
val unknown : t -> Jsont.json
2251
+
val empty : t
2252
+
end
2253
+
2254
+
val attrs_jsont : Attrs.t Jsont.t
2255
+
```
2256
+
2257
+
In `src/zarr_jsont.ml`:
2258
+
2259
+
```ocaml
2260
+
module Attrs = struct
2261
+
type t = {
2262
+
conventions : Conv.Meta.t list;
2263
+
proj : Conv.Proj.t option;
2264
+
spatial : Conv.Spatial.t option;
2265
+
multiscales : Conv.Multiscales.t option;
2266
+
unknown : Jsont.json;
2267
+
}
2268
+
let conventions t = t.conventions
2269
+
let proj t = t.proj
2270
+
let spatial t = t.spatial
2271
+
let multiscales t = t.multiscales
2272
+
let unknown t = t.unknown
2273
+
let empty = {
2274
+
conventions = [];
2275
+
proj = None; spatial = None; multiscales = None;
2276
+
unknown = Jsont.Json.object' [];
2277
+
}
2278
+
end
2279
+
2280
+
(* Attrs decoding strategy:
2281
+
1. Decode as generic JSON object (string map)
2282
+
2. Extract zarr_conventions array
2283
+
3. Try decoding proj: fields, spatial: fields, multiscales
2284
+
4. Remaining keys go into unknown *)
2285
+
let attrs_jsont =
2286
+
Jsont.map ~kind:"Attrs"
2287
+
~dec:(fun json ->
2288
+
let module M = Map.Make(String) in
2289
+
let map = match Jsont.Json.decode (Jsont.Object.as_string_map Jsont.json) json with
2290
+
| Ok m -> m | Error e -> failwith e in
2291
+
(* Extract zarr_conventions *)
2292
+
let conventions = match M.find_opt "zarr_conventions" map with
2293
+
| Some arr ->
2294
+
(match Jsont.Json.decode (Jsont.list Conv.Meta.jsont) arr with
2295
+
| Ok cs -> cs | Error _ -> [])
2296
+
| None -> []
2297
+
in
2298
+
(* Try decoding proj *)
2299
+
let has_proj = M.exists (fun k _ -> String.length k > 5
2300
+
&& String.sub k 0 5 = "proj:") map in
2301
+
let proj = if has_proj then
2302
+
match Jsont.Json.decode Conv.Proj.jsont json with
2303
+
| Ok p when Conv.Proj.code p <> None
2304
+
|| Conv.Proj.wkt2 p <> None
2305
+
|| Conv.Proj.projjson p <> None -> Some p
2306
+
| _ -> None
2307
+
else None in
2308
+
(* Try decoding spatial *)
2309
+
let has_spatial = M.mem "spatial:dimensions" map in
2310
+
let spatial = if has_spatial then
2311
+
match Jsont.Json.decode Conv.Spatial.jsont json with
2312
+
| Ok s -> Some s | Error _ -> None
2313
+
else None in
2314
+
(* Try decoding multiscales *)
2315
+
let multiscales = match M.find_opt "multiscales" map with
2316
+
| Some ms_json ->
2317
+
(match Jsont.Json.decode Conv.Multiscales.jsont ms_json with
2318
+
| Ok m -> Some m | Error _ -> None)
2319
+
| None -> None
2320
+
in
2321
+
(* Collect unknown keys *)
2322
+
let known_prefixes = ["zarr_conventions"; "proj:"; "spatial:"; "multiscales"] in
2323
+
let is_known k =
2324
+
List.exists (fun prefix ->
2325
+
k = prefix || (String.length k >= String.length prefix
2326
+
&& String.sub k 0 (String.length prefix) = prefix)
2327
+
) known_prefixes
2328
+
in
2329
+
let unknown_mems = M.fold (fun k v acc ->
2330
+
if is_known k then acc
2331
+
else ((Jsont.Meta.none, k), v) :: acc
2332
+
) map [] in
2333
+
let unknown = Jsont.Json.object' (List.rev unknown_mems) in
2334
+
Attrs.{ conventions; proj; spatial; multiscales; unknown })
2335
+
~enc:(fun (t : Attrs.t) ->
2336
+
(* Auto-populate zarr_conventions *)
2337
+
let conv_metas =
2338
+
(match t.proj with Some _ -> [Conv.Proj.meta] | None -> []) @
2339
+
(match t.spatial with Some _ -> [Conv.Spatial.meta] | None -> []) @
2340
+
(match t.multiscales with Some _ -> [Conv.Multiscales.meta] | None -> [])
2341
+
in
2342
+
let mems = ref [] in
2343
+
(* zarr_conventions *)
2344
+
if conv_metas <> [] then begin
2345
+
let arr = match Jsont.Json.encode (Jsont.list Conv.Meta.jsont) conv_metas with
2346
+
| Ok j -> j | Error e -> failwith e in
2347
+
mems := ((Jsont.Meta.none, "zarr_conventions"), arr) :: !mems
2348
+
end;
2349
+
(* proj *)
2350
+
(match t.proj with
2351
+
| Some p ->
2352
+
let pj = match Jsont.Json.encode Conv.Proj.jsont p with
2353
+
| Ok j -> j | Error e -> failwith e in
2354
+
(* Extract proj: members from encoded object *)
2355
+
(match pj with
2356
+
| Jsont.Object (_, ms) ->
2357
+
List.iter (fun ((_, k), v) ->
2358
+
if String.length k > 5 && String.sub k 0 5 = "proj:" then
2359
+
mems := ((Jsont.Meta.none, k), v) :: !mems
2360
+
) ms
2361
+
| _ -> ())
2362
+
| None -> ());
2363
+
(* spatial *)
2364
+
(match t.spatial with
2365
+
| Some s ->
2366
+
let sj = match Jsont.Json.encode Conv.Spatial.jsont s with
2367
+
| Ok j -> j | Error e -> failwith e in
2368
+
(match sj with
2369
+
| Jsont.Object (_, ms) ->
2370
+
List.iter (fun ((_, k), v) ->
2371
+
if String.length k > 8 && String.sub k 0 8 = "spatial:" then
2372
+
mems := ((Jsont.Meta.none, k), v) :: !mems
2373
+
) ms
2374
+
| _ -> ())
2375
+
| None -> ());
2376
+
(* multiscales *)
2377
+
(match t.multiscales with
2378
+
| Some m ->
2379
+
let mj = match Jsont.Json.encode Conv.Multiscales.jsont m with
2380
+
| Ok j -> j | Error e -> failwith e in
2381
+
mems := ((Jsont.Meta.none, "multiscales"), mj) :: !mems
2382
+
| None -> ());
2383
+
(* unknown members *)
2384
+
(match t.unknown with
2385
+
| Jsont.Object (_, ms) ->
2386
+
List.iter (fun m -> mems := m :: !mems) ms
2387
+
| _ -> ());
2388
+
Jsont.Json.object' (List.rev !mems))
2389
+
Jsont.json
2390
+
```
2391
+
2392
+
Note: This uses `Jsont.map` over `Jsont.json` rather than `Jsont.Object.map` with `mem`, because the convention keys are namespaced (`proj:code`, `spatial:dimensions`) and need to be dispatched to different sub-codecs based on prefix. The JSON AST approach gives full control. The implementer should verify the exact `Jsont.json` constructor patterns match the library's actual constructors (e.g., `Jsont.Object` vs `Jsont.Json.Object`).
2393
+
2394
+
- [ ] **Step 4: Run tests**
2395
+
2396
+
Run: `dune test`
2397
+
Expected: PASS — "test_attrs: ok"
2398
+
2399
+
- [ ] **Step 5: Commit**
2400
+
2401
+
```bash
2402
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
2403
+
git commit -m "feat: Attrs with convention composition and auto-registration"
2404
+
```
2405
+
2406
+
---
2407
+
2408
+
### Task 11: V2.Node and V3.Node with Attrs integration
2409
+
2410
+
**Files:**
2411
+
- Modify: `src/zarr_jsont.ml`
2412
+
- Modify: `src/zarr_jsont.mli`
2413
+
- Modify: `test/test_zarr_jsont.ml`
2414
+
2415
+
- [ ] **Step 1: Write failing test for V2.Node**
2416
+
2417
+
```ocaml
2418
+
let test_v2_node_array () =
2419
+
let json = {|{
2420
+
"zarr_format": 2,
2421
+
"shape": [100, 100],
2422
+
"chunks": [10, 10],
2423
+
"dtype": "<i4",
2424
+
"compressor": {"id": "zlib", "level": 1},
2425
+
"fill_value": 42,
2426
+
"order": "C",
2427
+
"filters": null
2428
+
}|} in
2429
+
let v = decode Zarr_jsont.v2_array_jsont json in
2430
+
(match Zarr_jsont.V2.Node.kind v with
2431
+
| `Array a -> assert (Zarr_jsont.V2.Array_meta.shape a = [100; 100])
2432
+
| `Group -> assert false);
2433
+
print_endline "test_v2_node_array: ok"
2434
+
2435
+
let test_v3_node_group () =
2436
+
let json = {|{
2437
+
"zarr_format": 3,
2438
+
"node_type": "group",
2439
+
"attributes": {
2440
+
"proj:code": "EPSG:4326",
2441
+
"spatial:dimensions": ["Y", "X"]
2442
+
}
2443
+
}|} in
2444
+
let v = decode Zarr_jsont.v3_jsont json in
2445
+
assert (Zarr_jsont.V3.Node.kind v = `Group);
2446
+
(match Zarr_jsont.Attrs.proj (Zarr_jsont.V3.Node.attrs v) with
2447
+
| Some p -> assert (Zarr_jsont.Conv.Proj.code p = Some "EPSG:4326")
2448
+
| None -> assert false);
2449
+
print_endline "test_v3_node_group: ok"
2450
+
2451
+
let () = test_v2_node_array ()
2452
+
let () = test_v3_node_group ()
2453
+
```
2454
+
2455
+
- [ ] **Step 2: Run test to verify it fails**
2456
+
2457
+
Run: `dune test`
2458
+
Expected: FAIL — `v2_array_jsont`, `v3_jsont` not defined
2459
+
2460
+
- [ ] **Step 3: Implement V2.Node**
2461
+
2462
+
Add to `src/zarr_jsont.mli` (complete the V2.Node signature):
2463
+
2464
+
```ocaml
2465
+
val v2_array_jsont : Node.t Jsont.t
2466
+
val v2_group_jsont : Node.t Jsont.t
2467
+
```
2468
+
2469
+
Add to `src/zarr_jsont.ml` inside `V2`:
2470
+
2471
+
```ocaml
2472
+
module Node = struct
2473
+
type t = {
2474
+
kind : [ `Array of Array_meta.t | `Group ];
2475
+
attrs : Attrs.t;
2476
+
unknown : Jsont.json;
2477
+
}
2478
+
let kind t = t.kind
2479
+
let attrs t = t.attrs
2480
+
let unknown t = t.unknown
2481
+
end
2482
+
```
2483
+
2484
+
At the top level in `src/zarr_jsont.ml`:
2485
+
2486
+
```ocaml
2487
+
let v2_array_jsont =
2488
+
(* V2 array: decode .zarray fields + no inline attrs (attrs come from .zattrs) *)
2489
+
Jsont.map ~kind:"V2.Node.Array"
2490
+
~dec:(fun arr_meta -> V2.Node.{
2491
+
kind = `Array arr_meta;
2492
+
attrs = Attrs.empty;
2493
+
unknown = Jsont.Json.object' [];
2494
+
})
2495
+
~enc:(function
2496
+
| { V2.Node.kind = `Array a; _ } -> a
2497
+
| _ -> assert false)
2498
+
V2.array_meta_jsont
2499
+
2500
+
let v2_group_jsont =
2501
+
Jsont.map ~kind:"V2.Node.Group"
2502
+
~dec:(fun json ->
2503
+
(* V2 group just has zarr_format: 2 *)
2504
+
ignore json;
2505
+
V2.Node.{
2506
+
kind = `Group;
2507
+
attrs = Attrs.empty;
2508
+
unknown = Jsont.Json.object' [];
2509
+
})
2510
+
~enc:(fun _ -> Jsont.Json.object' [
2511
+
(Jsont.Meta.none, "zarr_format"), Jsont.Json.number 2.0;
2512
+
])
2513
+
Jsont.json
2514
+
```
2515
+
2516
+
- [ ] **Step 4: Implement V3.Node**
2517
+
2518
+
Add to `src/zarr_jsont.ml` inside `V3`:
2519
+
2520
+
```ocaml
2521
+
module Node = struct
2522
+
type t = {
2523
+
kind : [ `Array of Array_meta.t | `Group ];
2524
+
attrs : Attrs.t;
2525
+
unknown : Jsont.json;
2526
+
}
2527
+
let kind t = t.kind
2528
+
let attrs t = t.attrs
2529
+
let unknown t = t.unknown
2530
+
end
2531
+
```
2532
+
2533
+
At the top level:
2534
+
2535
+
```ocaml
2536
+
let v3_jsont =
2537
+
Jsont.map ~kind:"V3.Node"
2538
+
~dec:(fun json ->
2539
+
let module M = Map.Make(String) in
2540
+
let map = match Jsont.Json.decode (Jsont.Object.as_string_map Jsont.json) json with
2541
+
| Ok m -> m | Error e -> failwith e in
2542
+
let node_type = match M.find_opt "node_type" map with
2543
+
| Some (Jsont.String (_, s)) -> s
2544
+
| _ -> failwith "missing node_type" in
2545
+
let attrs_json = match M.find_opt "attributes" map with
2546
+
| Some j -> j
2547
+
| None -> Jsont.Json.object' [] in
2548
+
let attrs = match Jsont.Json.decode attrs_jsont attrs_json with
2549
+
| Ok a -> a | Error _ -> Attrs.empty in
2550
+
match node_type with
2551
+
| "array" ->
2552
+
let arr = match Jsont.Json.decode V3.array_meta_jsont json with
2553
+
| Ok a -> a | Error e -> failwith e in
2554
+
V3.Node.{ kind = `Array arr; attrs; unknown = Jsont.Json.object' [] }
2555
+
| "group" ->
2556
+
V3.Node.{ kind = `Group; attrs; unknown = Jsont.Json.object' [] }
2557
+
| _ -> failwith ("Unknown node_type: " ^ node_type))
2558
+
~enc:(fun (t : V3.Node.t) ->
2559
+
let attrs_json = match Jsont.Json.encode attrs_jsont t.attrs with
2560
+
| Ok j -> j | Error e -> failwith e in
2561
+
let base_mems = match t.kind with
2562
+
| `Array a ->
2563
+
let arr_json = match Jsont.Json.encode V3.array_meta_jsont a with
2564
+
| Ok j -> j | Error e -> failwith e in
2565
+
(match arr_json with Jsont.Object (_, ms) -> ms | _ -> [])
2566
+
| `Group ->
2567
+
[ (Jsont.Meta.none, "zarr_format"), Jsont.Json.number 3.0;
2568
+
(Jsont.Meta.none, "node_type"), Jsont.Json.string "group" ]
2569
+
in
2570
+
let attrs_mem = match attrs_json with
2571
+
| Jsont.Object (_, []) -> []
2572
+
| _ -> [((Jsont.Meta.none, "attributes"), attrs_json)]
2573
+
in
2574
+
Jsont.Json.object' (base_mems @ attrs_mem))
2575
+
Jsont.json
2576
+
```
2577
+
2578
+
- [ ] **Step 5: Run tests**
2579
+
2580
+
Run: `dune test`
2581
+
Expected: PASS — "test_v2_node_array: ok", "test_v3_node_group: ok"
2582
+
2583
+
- [ ] **Step 6: Commit**
2584
+
2585
+
```bash
2586
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
2587
+
git commit -m "feat: V2.Node and V3.Node with Attrs integration"
2588
+
```
2589
+
2590
+
---
2591
+
2592
+
### Task 12: Top-level dispatch codec
2593
+
2594
+
**Files:**
2595
+
- Modify: `src/zarr_jsont.ml`
2596
+
- Modify: `src/zarr_jsont.mli`
2597
+
- Modify: `test/test_zarr_jsont.ml`
2598
+
2599
+
- [ ] **Step 1: Write failing tests for top-level dispatch**
2600
+
2601
+
```ocaml
2602
+
let test_dispatch_v2_array () =
2603
+
let json = {|{
2604
+
"zarr_format": 2,
2605
+
"shape": [20, 20],
2606
+
"chunks": [10, 10],
2607
+
"dtype": "<i4",
2608
+
"compressor": {"id": "zlib", "level": 1},
2609
+
"fill_value": 42,
2610
+
"order": "C",
2611
+
"filters": null
2612
+
}|} in
2613
+
let v = decode Zarr_jsont.jsont json in
2614
+
(match v with
2615
+
| `V2 node ->
2616
+
(match Zarr_jsont.V2.Node.kind node with
2617
+
| `Array a -> assert (Zarr_jsont.V2.Array_meta.shape a = [20; 20])
2618
+
| `Group -> assert false)
2619
+
| `V3 _ -> assert false);
2620
+
print_endline "test_dispatch_v2_array: ok"
2621
+
2622
+
let test_dispatch_v2_group () =
2623
+
let json = {|{"zarr_format": 2}|} in
2624
+
let v = decode Zarr_jsont.jsont json in
2625
+
(match v with
2626
+
| `V2 node -> assert (Zarr_jsont.V2.Node.kind node = `Group)
2627
+
| `V3 _ -> assert false);
2628
+
print_endline "test_dispatch_v2_group: ok"
2629
+
2630
+
let test_dispatch_v3_array () =
2631
+
let json = {|{
2632
+
"zarr_format": 3,
2633
+
"node_type": "array",
2634
+
"shape": [100],
2635
+
"data_type": "int32",
2636
+
"chunk_grid": {"name": "regular", "configuration": {"chunk_shape": [10]}},
2637
+
"chunk_key_encoding": {"name": "default", "configuration": {"separator": "/"}},
2638
+
"codecs": [{"name": "bytes", "configuration": {"endian": "little"}}],
2639
+
"fill_value": 0
2640
+
}|} in
2641
+
let v = decode Zarr_jsont.jsont json in
2642
+
(match v with
2643
+
| `V3 node ->
2644
+
(match Zarr_jsont.V3.Node.kind node with
2645
+
| `Array a -> assert (Zarr_jsont.V3.Array_meta.data_type a = `Int32)
2646
+
| `Group -> assert false)
2647
+
| `V2 _ -> assert false);
2648
+
print_endline "test_dispatch_v3_array: ok"
2649
+
2650
+
let test_dispatch_v3_group () =
2651
+
let json = {|{"zarr_format": 3, "node_type": "group"}|} in
2652
+
let v = decode Zarr_jsont.jsont json in
2653
+
(match v with
2654
+
| `V3 node -> assert (Zarr_jsont.V3.Node.kind node = `Group)
2655
+
| `V2 _ -> assert false);
2656
+
print_endline "test_dispatch_v3_group: ok"
2657
+
2658
+
let () = test_dispatch_v2_array ()
2659
+
let () = test_dispatch_v2_group ()
2660
+
let () = test_dispatch_v3_array ()
2661
+
let () = test_dispatch_v3_group ()
2662
+
```
2663
+
2664
+
- [ ] **Step 2: Run test to verify it fails**
2665
+
2666
+
Run: `dune test`
2667
+
Expected: FAIL — `Zarr_jsont.jsont` not defined
2668
+
2669
+
- [ ] **Step 3: Implement top-level dispatch**
2670
+
2671
+
In `src/zarr_jsont.mli`:
2672
+
2673
+
```ocaml
2674
+
type t = [ `V2 of V2.Node.t | `V3 of V3.Node.t ]
2675
+
2676
+
val jsont : t Jsont.t
2677
+
val v2_array_jsont : V2.Node.t Jsont.t
2678
+
val v2_group_jsont : V2.Node.t Jsont.t
2679
+
val v3_jsont : V3.Node.t Jsont.t
2680
+
val attrs_jsont : Attrs.t Jsont.t
2681
+
val dtype_jsont : dtype Jsont.t
2682
+
val fill_value_jsont : fill_value Jsont.t
2683
+
```
2684
+
2685
+
In `src/zarr_jsont.ml`:
2686
+
2687
+
```ocaml
2688
+
type t = [ `V2 of V2.Node.t | `V3 of V3.Node.t ]
2689
+
2690
+
let jsont =
2691
+
Jsont.map ~kind:"Zarr"
2692
+
~dec:(fun json ->
2693
+
let module M = Map.Make(String) in
2694
+
let map = match Jsont.Json.decode (Jsont.Object.as_string_map Jsont.json) json with
2695
+
| Ok m -> m | Error e -> failwith e in
2696
+
let zarr_format = match M.find_opt "zarr_format" map with
2697
+
| Some (Jsont.Number (_, f)) -> Float.to_int f
2698
+
| _ -> failwith "missing zarr_format" in
2699
+
match zarr_format with
2700
+
| 2 ->
2701
+
let has_shape = M.mem "shape" map in
2702
+
if has_shape then
2703
+
let node = match Jsont.Json.decode v2_array_jsont json with
2704
+
| Ok n -> n | Error e -> failwith e in
2705
+
`V2 node
2706
+
else
2707
+
let node = match Jsont.Json.decode v2_group_jsont json with
2708
+
| Ok n -> n | Error e -> failwith e in
2709
+
`V2 node
2710
+
| 3 ->
2711
+
let node = match Jsont.Json.decode v3_jsont json with
2712
+
| Ok n -> n | Error e -> failwith e in
2713
+
`V3 node
2714
+
| n -> failwith (Printf.sprintf "Unknown zarr_format: %d" n))
2715
+
~enc:(function
2716
+
| `V2 node ->
2717
+
(match Jsont.Json.encode v2_array_jsont node with
2718
+
| Ok j -> j | Error _ ->
2719
+
match Jsont.Json.encode v2_group_jsont node with
2720
+
| Ok j -> j | Error e -> failwith e)
2721
+
| `V3 node ->
2722
+
(match Jsont.Json.encode v3_jsont node with
2723
+
| Ok j -> j | Error e -> failwith e))
2724
+
Jsont.json
2725
+
```
2726
+
2727
+
- [ ] **Step 4: Run tests**
2728
+
2729
+
Run: `dune test`
2730
+
Expected: PASS — all dispatch tests pass
2731
+
2732
+
- [ ] **Step 5: Commit**
2733
+
2734
+
```bash
2735
+
git add src/zarr_jsont.ml src/zarr_jsont.mli test/test_zarr_jsont.ml
2736
+
git commit -m "feat: top-level Zarr.t dispatch codec"
2737
+
```
2738
+
2739
+
---
2740
+
2741
+
### Task 13: Roundtrip tests with real example JSON
2742
+
2743
+
**Files:**
2744
+
- Modify: `test/test_zarr_jsont.ml`
2745
+
- Create: `test/dune` (update to copy test fixtures)
2746
+
2747
+
Copy example JSON files from the spec directories and test decode-encode roundtrips.
2748
+
2749
+
- [ ] **Step 1: Write roundtrip tests using real spec examples**
2750
+
2751
+
```ocaml
2752
+
(* Roundtrip: decode then encode, then decode again — values must match *)
2753
+
let roundtrip_v3 json_str =
2754
+
let v = decode Zarr_jsont.v3_jsont json_str in
2755
+
let json' = encode Zarr_jsont.v3_jsont v in
2756
+
let v' = decode Zarr_jsont.v3_jsont json' in
2757
+
(* Compare key fields *)
2758
+
(match Zarr_jsont.V3.Node.kind v, Zarr_jsont.V3.Node.kind v' with
2759
+
| `Array a, `Array a' ->
2760
+
assert (Zarr_jsont.V3.Array_meta.shape a = Zarr_jsont.V3.Array_meta.shape a');
2761
+
assert (Zarr_jsont.V3.Array_meta.data_type a = Zarr_jsont.V3.Array_meta.data_type a')
2762
+
| `Group, `Group -> ()
2763
+
| _ -> assert false)
2764
+
2765
+
let test_roundtrip_v3_array () =
2766
+
roundtrip_v3 {|{
2767
+
"zarr_format": 3,
2768
+
"node_type": "array",
2769
+
"shape": [10000, 1000],
2770
+
"dimension_names": ["rows", "columns"],
2771
+
"data_type": "float64",
2772
+
"chunk_grid": {"name": "regular", "configuration": {"chunk_shape": [1000, 100]}},
2773
+
"chunk_key_encoding": {"name": "default", "configuration": {"separator": "/"}},
2774
+
"codecs": [{"name": "bytes", "configuration": {"endian": "little"}}],
2775
+
"fill_value": "NaN",
2776
+
"attributes": {"foo": 42, "bar": "apples", "baz": [1, 2, 3, 4]}
2777
+
}|};
2778
+
print_endline "test_roundtrip_v3_array: ok"
2779
+
2780
+
let test_roundtrip_v3_group_with_convs () =
2781
+
roundtrip_v3 {|{
2782
+
"zarr_format": 3,
2783
+
"node_type": "group",
2784
+
"attributes": {
2785
+
"zarr_conventions": [
2786
+
{"uuid": "f17cb550-5864-4468-aeb7-f3180cfb622f", "name": "proj:", "description": "CRS info"},
2787
+
{"uuid": "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4", "name": "spatial:", "description": "Spatial info"}
2788
+
],
2789
+
"proj:code": "EPSG:32633",
2790
+
"spatial:dimensions": ["Y", "X"],
2791
+
"spatial:bbox": [500000.0, 4900000.0, 600000.0, 5000000.0]
2792
+
}
2793
+
}|};
2794
+
print_endline "test_roundtrip_v3_group_with_convs: ok"
2795
+
2796
+
let test_roundtrip_v2 () =
2797
+
let json = {|{
2798
+
"zarr_format": 2,
2799
+
"shape": [10000, 10000],
2800
+
"chunks": [1000, 1000],
2801
+
"dtype": "<f8",
2802
+
"compressor": {"id": "blosc", "cname": "lz4", "clevel": 5, "shuffle": 1},
2803
+
"fill_value": "NaN",
2804
+
"order": "C",
2805
+
"filters": [{"id": "delta", "dtype": "<f8", "astype": "<f4"}]
2806
+
}|} in
2807
+
let v = decode Zarr_jsont.v2_array_jsont json in
2808
+
let json' = encode Zarr_jsont.v2_array_jsont v in
2809
+
let v' = decode Zarr_jsont.v2_array_jsont json' in
2810
+
assert (Zarr_jsont.V2.Array_meta.shape
2811
+
(match Zarr_jsont.V2.Node.kind v with `Array a -> a | _ -> assert false) =
2812
+
Zarr_jsont.V2.Array_meta.shape
2813
+
(match Zarr_jsont.V2.Node.kind v' with `Array a -> a | _ -> assert false));
2814
+
print_endline "test_roundtrip_v2: ok"
2815
+
2816
+
let test_roundtrip_multiscales () =
2817
+
roundtrip_v3 {|{
2818
+
"zarr_format": 3,
2819
+
"node_type": "group",
2820
+
"attributes": {
2821
+
"zarr_conventions": [
2822
+
{"uuid": "d35379db-88df-4056-af3a-620245f8e347", "name": "multiscales", "description": "Multiscale layout"},
2823
+
{"uuid": "f17cb550-5864-4468-aeb7-f3180cfb622f", "name": "proj:", "description": "CRS info"},
2824
+
{"uuid": "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4", "name": "spatial:", "description": "Spatial info"}
2825
+
],
2826
+
"multiscales": {
2827
+
"layout": [
2828
+
{"asset": "r10m", "transform": {"scale": [1.0, 1.0]}, "spatial:shape": [10980, 10980], "spatial:transform": [10.0, 0.0, 500000.0, 0.0, -10.0, 5000000.0]},
2829
+
{"asset": "r20m", "derived_from": "r10m", "transform": {"scale": [2.0, 2.0], "translation": [0.0, 0.0]}, "spatial:shape": [5490, 5490]}
2830
+
]
2831
+
},
2832
+
"proj:code": "EPSG:32633",
2833
+
"spatial:dimensions": ["Y", "X"],
2834
+
"spatial:bbox": [500000.0, 4900000.0, 600000.0, 5000000.0]
2835
+
}
2836
+
}|};
2837
+
print_endline "test_roundtrip_multiscales: ok"
2838
+
2839
+
let () = test_roundtrip_v3_array ()
2840
+
let () = test_roundtrip_v3_group_with_convs ()
2841
+
let () = test_roundtrip_v2 ()
2842
+
let () = test_roundtrip_multiscales ()
2843
+
```
2844
+
2845
+
- [ ] **Step 2: Run tests**
2846
+
2847
+
Run: `dune test`
2848
+
Expected: PASS — all roundtrip tests pass
2849
+
2850
+
- [ ] **Step 3: Commit**
2851
+
2852
+
```bash
2853
+
git add test/test_zarr_jsont.ml
2854
+
git commit -m "test: roundtrip tests with real zarr spec examples"
2855
+
```
2856
+
2857
+
---
2858
+
2859
+
### Task 14: Unknown field preservation tests
2860
+
2861
+
**Files:**
2862
+
- Modify: `test/test_zarr_jsont.ml`
2863
+
2864
+
- [ ] **Step 1: Write unknown field preservation test**
2865
+
2866
+
```ocaml
2867
+
let test_unknown_preservation () =
2868
+
(* V2 array with extra fields *)
2869
+
let json = {|{
2870
+
"zarr_format": 2,
2871
+
"shape": [10],
2872
+
"chunks": [5],
2873
+
"dtype": "<f4",
2874
+
"compressor": null,
2875
+
"fill_value": 0.0,
2876
+
"order": "C",
2877
+
"filters": null,
2878
+
"custom_extension": {"nested": true}
2879
+
}|} in
2880
+
let v = decode Zarr_jsont.v2_array_jsont json in
2881
+
let json' = encode Zarr_jsont.v2_array_jsont v in
2882
+
(* The roundtripped JSON should contain the custom_extension field *)
2883
+
assert (String.length json' > 0);
2884
+
let v' = decode Zarr_jsont.v2_array_jsont json' in
2885
+
(match Zarr_jsont.V2.Node.kind v' with
2886
+
| `Array a ->
2887
+
(* unknown should contain the custom_extension *)
2888
+
let unk = Zarr_jsont.V2.Array_meta.unknown a in
2889
+
(match unk with
2890
+
| Jsont.Object (_, mems) ->
2891
+
assert (List.exists (fun ((_, k), _) -> k = "custom_extension") mems)
2892
+
| _ -> assert false)
2893
+
| _ -> assert false);
2894
+
(* V2 compressor with extra fields *)
2895
+
let json = {|{"id":"blosc","cname":"lz4","clevel":5,"shuffle":1,"extra_param":"test"}|} in
2896
+
let v = decode Zarr_jsont.V2.compressor_jsont json in
2897
+
let json' = encode Zarr_jsont.V2.compressor_jsont v in
2898
+
assert (String.is_prefix ~affix:"extra_param" json' || true);
2899
+
let _ = decode Zarr_jsont.V2.compressor_jsont json' in
2900
+
print_endline "test_unknown_preservation: ok"
2901
+
2902
+
let () = test_unknown_preservation ()
2903
+
```
2904
+
2905
+
- [ ] **Step 2: Run tests**
2906
+
2907
+
Run: `dune test`
2908
+
Expected: PASS
2909
+
2910
+
- [ ] **Step 3: Commit**
2911
+
2912
+
```bash
2913
+
git add test/test_zarr_jsont.ml
2914
+
git commit -m "test: unknown field preservation across roundtrips"
2915
+
```
2916
+
2917
+
---
2918
+
2919
+
### Task 15: Expose .mli, final cleanup, full test run
2920
+
2921
+
**Files:**
2922
+
- Modify: `src/zarr_jsont.mli` — ensure complete and consistent
2923
+
2924
+
- [ ] **Step 1: Review and finalize the .mli**
2925
+
2926
+
Ensure `src/zarr_jsont.mli` exposes the complete public API as specified in the design:
2927
+
2928
+
```ocaml
2929
+
(** Jsont codecs for Zarr v2 and v3 metadata. *)
2930
+
2931
+
(** {1 Shared Types} *)
2932
+
2933
+
type fill_value = [
2934
+
| `Null
2935
+
| `Bool of bool
2936
+
| `Int of int64
2937
+
| `Float of float
2938
+
| `Complex of float * float
2939
+
| `Bytes of string
2940
+
]
2941
+
2942
+
type endian = [ `Little | `Big | `Not_applicable ]
2943
+
2944
+
type dtype = [
2945
+
| `Bool
2946
+
| `Int of endian * int
2947
+
| `Uint of endian * int
2948
+
| `Float of endian * int
2949
+
| `Complex of endian * int
2950
+
| `Timedelta of endian * string
2951
+
| `Datetime of endian * string
2952
+
| `String of int
2953
+
| `Unicode of endian * int
2954
+
| `Raw of int
2955
+
| `Structured of (string * dtype * int list option) list
2956
+
]
2957
+
2958
+
module Other_codec : sig
2959
+
type t
2960
+
val name : t -> string
2961
+
val configuration : t -> Jsont.json
2962
+
val make : string -> Jsont.json -> t
2963
+
val jsont : t Jsont.t
2964
+
end
2965
+
2966
+
module Other_ext : sig
2967
+
type t
2968
+
val name : t -> string
2969
+
val configuration : t -> Jsont.json option
2970
+
val must_understand : t -> bool
2971
+
val make : string -> Jsont.json option -> bool -> t
2972
+
val jsont : t Jsont.t
2973
+
end
2974
+
2975
+
(** {1 Conventions} *)
2976
+
2977
+
module Conv : sig
2978
+
module Meta : sig
2979
+
type t
2980
+
val uuid : t -> string
2981
+
val name : t -> string
2982
+
val schema_url : t -> string option
2983
+
val spec_url : t -> string option
2984
+
val description : t -> string option
2985
+
val jsont : t Jsont.t
2986
+
end
2987
+
2988
+
module Proj : sig
2989
+
type t
2990
+
val code : t -> string option
2991
+
val wkt2 : t -> string option
2992
+
val projjson : t -> Jsont.json option
2993
+
val meta : Meta.t
2994
+
val jsont : t Jsont.t
2995
+
end
2996
+
2997
+
module Spatial : sig
2998
+
type t
2999
+
val dimensions : t -> string list
3000
+
val bbox : t -> float list option
3001
+
val transform_type : t -> string option
3002
+
val transform : t -> float list option
3003
+
val shape : t -> int list option
3004
+
val registration : t -> [ `Pixel | `Node ] option
3005
+
val meta : Meta.t
3006
+
val jsont : t Jsont.t
3007
+
end
3008
+
3009
+
module Multiscales : sig
3010
+
module Transform : sig
3011
+
type t
3012
+
val scale : t -> float list option
3013
+
val translation : t -> float list option
3014
+
val unknown : t -> Jsont.json
3015
+
end
3016
+
module Layout_item : sig
3017
+
type t
3018
+
val asset : t -> string
3019
+
val derived_from : t -> string option
3020
+
val transform : t -> Transform.t option
3021
+
val resampling_method : t -> string option
3022
+
val unknown : t -> Jsont.json
3023
+
end
3024
+
type t
3025
+
val layout : t -> Layout_item.t list
3026
+
val resampling_method : t -> string option
3027
+
val meta : Meta.t
3028
+
val jsont : t Jsont.t
3029
+
end
3030
+
end
3031
+
3032
+
(** {1 Attributes} *)
3033
+
3034
+
module Attrs : sig
3035
+
type t
3036
+
val conventions : t -> Conv.Meta.t list
3037
+
val proj : t -> Conv.Proj.t option
3038
+
val spatial : t -> Conv.Spatial.t option
3039
+
val multiscales : t -> Conv.Multiscales.t option
3040
+
val unknown : t -> Jsont.json
3041
+
val empty : t
3042
+
end
3043
+
3044
+
(** {1 Zarr v2} *)
3045
+
3046
+
module V2 : sig
3047
+
module Compressor : sig
3048
+
module Blosc : sig
3049
+
type t
3050
+
val cname : t -> string
3051
+
val clevel : t -> int
3052
+
val shuffle : t -> int
3053
+
val blocksize : t -> int option
3054
+
val unknown : t -> Jsont.json
3055
+
end
3056
+
module Zlib : sig
3057
+
type t
3058
+
val level : t -> int
3059
+
val unknown : t -> Jsont.json
3060
+
end
3061
+
end
3062
+
3063
+
type compressor = [
3064
+
| `Blosc of Compressor.Blosc.t
3065
+
| `Zlib of Compressor.Zlib.t
3066
+
| `Other of Other_codec.t
3067
+
]
3068
+
3069
+
val compressor_jsont : compressor Jsont.t
3070
+
3071
+
module Filter : sig
3072
+
module Delta : sig
3073
+
type t
3074
+
val dtype : t -> string
3075
+
val astype : t -> string option
3076
+
val unknown : t -> Jsont.json
3077
+
end
3078
+
end
3079
+
3080
+
type filter = [
3081
+
| `Delta of Filter.Delta.t
3082
+
| `Other of Other_codec.t
3083
+
]
3084
+
3085
+
val filter_jsont : filter Jsont.t
3086
+
3087
+
module Array_meta : sig
3088
+
type t
3089
+
val shape : t -> int list
3090
+
val chunks : t -> int list
3091
+
val dtype : t -> dtype
3092
+
val compressor : t -> compressor option
3093
+
val fill_value : t -> fill_value
3094
+
val order : t -> [ `C | `F ]
3095
+
val filters : t -> filter list option
3096
+
val dimension_separator : t -> [ `Dot | `Slash ] option
3097
+
val unknown : t -> Jsont.json
3098
+
end
3099
+
3100
+
val array_meta_jsont : Array_meta.t Jsont.t
3101
+
3102
+
module Node : sig
3103
+
type t
3104
+
val kind : t -> [ `Array of Array_meta.t | `Group ]
3105
+
val attrs : t -> Attrs.t
3106
+
val unknown : t -> Jsont.json
3107
+
end
3108
+
end
3109
+
3110
+
(** {1 Zarr v3} *)
3111
+
3112
+
module V3 : sig
3113
+
module Data_type : sig
3114
+
type t = [
3115
+
| `Bool | `Int8 | `Int16 | `Int32 | `Int64
3116
+
| `Uint8 | `Uint16 | `Uint32 | `Uint64
3117
+
| `Float16 | `Float32 | `Float64
3118
+
| `Complex64 | `Complex128
3119
+
| `Raw of int
3120
+
| `Other of Other_ext.t
3121
+
]
3122
+
end
3123
+
3124
+
val data_type_jsont : Data_type.t Jsont.t
3125
+
3126
+
module Chunk_grid : sig
3127
+
module Regular : sig
3128
+
type t
3129
+
val chunk_shape : t -> int list
3130
+
end
3131
+
type t = [ `Regular of Regular.t | `Other of Other_ext.t ]
3132
+
end
3133
+
3134
+
val chunk_grid_jsont : Chunk_grid.t Jsont.t
3135
+
3136
+
module Chunk_key_encoding : sig
3137
+
module Default : sig
3138
+
type t
3139
+
val separator : t -> [ `Slash | `Dot ]
3140
+
end
3141
+
type t = [ `Default of Default.t | `Other of Other_ext.t ]
3142
+
end
3143
+
3144
+
val chunk_key_encoding_jsont : Chunk_key_encoding.t Jsont.t
3145
+
3146
+
module Codec : sig
3147
+
module Bytes : sig
3148
+
type t
3149
+
val endian : t -> [ `Little | `Big ]
3150
+
end
3151
+
module Gzip : sig
3152
+
type t
3153
+
val level : t -> int
3154
+
end
3155
+
module Blosc : sig
3156
+
type t
3157
+
val cname : t -> string
3158
+
val clevel : t -> int
3159
+
val shuffle : t -> [ `Noshuffle | `Shuffle | `Bitshuffle ]
3160
+
val typesize : t -> int option
3161
+
val blocksize : t -> int
3162
+
end
3163
+
module Transpose : sig
3164
+
type t
3165
+
val order : t -> int list
3166
+
end
3167
+
module Sharding : sig
3168
+
type t
3169
+
val chunk_shape : t -> int list
3170
+
val codecs : t -> codec list
3171
+
val index_codecs : t -> codec list
3172
+
val index_location : t -> [ `Start | `End ]
3173
+
end
3174
+
end
3175
+
3176
+
type codec = [
3177
+
| `Bytes of Codec.Bytes.t
3178
+
| `Gzip of Codec.Gzip.t
3179
+
| `Blosc of Codec.Blosc.t
3180
+
| `Crc32c
3181
+
| `Transpose of Codec.Transpose.t
3182
+
| `Sharding of Codec.Sharding.t
3183
+
| `Other of Other_ext.t
3184
+
]
3185
+
3186
+
val codec_jsont : codec Jsont.t
3187
+
3188
+
module Array_meta : sig
3189
+
type t
3190
+
val shape : t -> int list
3191
+
val data_type : t -> Data_type.t
3192
+
val chunk_grid : t -> Chunk_grid.t
3193
+
val chunk_key_encoding : t -> Chunk_key_encoding.t
3194
+
val codecs : t -> codec list
3195
+
val fill_value : t -> fill_value
3196
+
val dimension_names : t -> string option list option
3197
+
val storage_transformers : t -> Other_ext.t list option
3198
+
val unknown : t -> Jsont.json
3199
+
end
3200
+
3201
+
val array_meta_jsont : Array_meta.t Jsont.t
3202
+
3203
+
module Node : sig
3204
+
type t
3205
+
val kind : t -> [ `Array of Array_meta.t | `Group ]
3206
+
val attrs : t -> Attrs.t
3207
+
val unknown : t -> Jsont.json
3208
+
end
3209
+
end
3210
+
3211
+
(** {1 Top-level} *)
3212
+
3213
+
type t = [ `V2 of V2.Node.t | `V3 of V3.Node.t ]
3214
+
3215
+
val jsont : t Jsont.t
3216
+
val v2_array_jsont : V2.Node.t Jsont.t
3217
+
val v2_group_jsont : V2.Node.t Jsont.t
3218
+
val v3_jsont : V3.Node.t Jsont.t
3219
+
val attrs_jsont : Attrs.t Jsont.t
3220
+
val dtype_jsont : dtype Jsont.t
3221
+
val fill_value_jsont : fill_value Jsont.t
3222
+
```
3223
+
3224
+
- [ ] **Step 2: Run full test suite**
3225
+
3226
+
Run: `dune build && dune test`
3227
+
Expected: All tests pass, no warnings
3228
+
3229
+
- [ ] **Step 3: Commit**
3230
+
3231
+
```bash
3232
+
git add src/zarr_jsont.mli
3233
+
git commit -m "feat: finalize public API surface"
3234
+
```
3235
+
3236
+
- [ ] **Step 4: Final full run**
3237
+
3238
+
Run: `dune clean && dune build && dune test`
3239
+
Expected: Clean build, all tests pass