feat(zarr-metadata)!: must_understand false refused at every extension point

[d-v-b]

🤖 AI text below 🤖

One reading of the spec, in its own PR so it can be decided on its own: an array document may not declare any of its extension points ignorable.

What it changes. validate_array_metadata_v3 now refuses must_understand: false on a codec or a storage transformer, as it already did on a data type, a chunk grid and a chunk key encoding. Ignoring a codec gives wrong bytes as surely as ignoring a data type gives wrong values. The spec names only those three points, which this package reads as an oversight rather than a licence. must_understand: false keeps its meaning where it has one: an unknown top-level extension field, which a reader really can skip. The JSON schema that zarr_metadata.pydantic generates for an array document says the same: every extension point has the mandatory envelope, and the test that holds schema and runtime together covers all five.

What breaks. A document that declares a codec or a storage transformer ignorable, which the package accepted before, now has a problem at codecs.N.must_understand or storage_transformers.N.must_understand, so is_array_metadata_v3 says no and parse_array_metadata_v3, from_json and from_key_value raise. The fragment is marked Breaking:. zarr itself does not read through these validators, so what zarr opens is unchanged.

Not in this PR. A metadata field read on its own, outside a document (validate_metadata_field_v3, parse_metadata_field_v3, ZarrV3NamedConfig, the pydantic ZarrV3MetadataField), still takes must_understand: false, and the envelope's allow_must_understand_false keyword stays. The envelope's bool is public API: seventeen TypedDicts and the ZarrV3NamedConfig model declare it. Making the envelope refuse false itself would retype all of them, which is worth doing only once this reading is accepted. Until then a model built by hand can hold what its reader refuses: ZarrV3ArrayMetadata.create_default().update(codecs=(ZarrV3NamedConfig(name="bytes", configuration={}, must_understand=False),)) builds, and its to_key_value, which validates what it writes as the reader does, raises with the problem at codecs.0.must_understand. Closing that gap in the types is the follow-up if the reading is accepted.

Review question: is refusing must_understand: false at codecs and storage transformers the right reading of the spec?

The stack. This is layer 1b of the zarr-metadata stack whose layers 0 (#4420, #4421, #4422) and 1 (#4432, the TypedDict checker) have merged. It is based on main and stands alone. The later layers are open on my fork: metadata fields read against their definitions (d-v-b#350, with its core reviewable alone in d-v-b#349), then the field in a document (d-v-b#355). They apply the same refusal when they judge a field's envelope, and a test there holds the two readers together at all five points, so if this reading is rejected, those call sites change with it.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 zarr-metadata | 🛠️ Build #34784666 | 📁 Comparing b510d0a against latest (c383b22)

  🔍 Preview build  

1 file changed

± api/model/index.html

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.37%. Comparing base (8dc50b8) to head (69ed30c).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4433   +/-   ##
=======================================
  Coverage   94.37%   94.37%           
=======================================
  Files          93       93           
  Lines       13174    13174           
=======================================
  Hits        12433    12433           
  Misses        741      741           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[d-v-b]

🤖 AI text below 🤖

Landed with #4434, which carried these commits (squash 8dc50b81b), so main already holds everything here and there is nothing left to merge. #4436 renames this PR's changelog fragment to 4434.feature.1.md, so the entry links the PR that merged it.