Add unified parse_json runtime type checker (#3285) [draft / proof-of-direction]

[vup903]

Summary

This is a draft / proof-of-direction PR for #3285, opened to show the intended approach and get early feedback before migrating all call sites — per @d-v-b's request in the issue thread.

It introduces a single unified runtime type checker, parse_json(value, type_annotation), that consolidates the scattered per-field parse_* helpers (there are currently ~42 of them across src/zarr). The function validates a JSON-decoded value against a type annotation and returns data assignable to that annotation (coercing where sensible, e.g. parse_json([1, 2, 3], tuple[int, int, int]) -> (1, 2, 3)), or raises a clear error.

What's in this draft

• src/zarr/core/json_parse.py — parse_json plus sub-parsers, scoped to the JSON-relevant categories named in the issue:
  • primitives: None, str, int, float, bool (with a bool-vs-int-safe check: True is not accepted for int, and 1 is not accepted for bool)
  • Literal[...]
  • unions / Optional
  • fixed and variadic tuple
  • Sequence[T] / list[T] → returned as a tuple
  • Mapping[str, T] / dict[str, T]
  • TypedDict
• tests/test_json_parse.py — 94 tests covering every category, incl. the bool/int edge cases, coercion, unions, nested TypedDict.
• Pilot migration of three representative helpers to delegate to parse_json, with public signatures and behavior unchanged:
  • core/common.py::parse_order → parse_json(data, Literal["C", "F"])
  • core/common.py::parse_bool → parse_json(data, bool)
  • core/metadata/v3.py::parse_zarr_format → parse_json(data, Literal[3]), re-wrapping the error as MetadataValidationError to preserve the original exception type and message.

Focused suites pass locally (Python 3.12, test.py3.12-optional env): test_common, test_config, test_metadata, and test_json_parse → 430 passed.

Open questions for maintainers (direction feedback)

1. Module name/location — src/zarr/core/json_parse.py is a placeholder; happy to move it (e.g. into a typing/metadata utility module).
2. Exceptions — parse_json raises plain ValueError / TypeError since it's field-agnostic; field-specific callers (like parse_zarr_format) re-wrap into their domain error. Does that split match what you'd want?
3. TypedDict + NotRequired — the current _parse_typeddict reads __required_keys__ / __optional_keys__ directly. Under from __future__ import annotations with class-syntax TypedDicts, typing_extensions can't see the NotRequired wrapper at class-creation time, so an optional key can be mis-classified as required. The robust fix is to resolve hints via typing_extensions.get_type_hints(..., include_extras=True) and inspect for Required/NotRequired. I've left this for the follow-up once the overall direction is confirmed, since none of the three pilot helpers are TypedDicts.

If the direction looks right, I'll migrate the remaining parse_* call sites incrementally in follow-up commits.

Closes #3285 once fully migrated (draft for now).