fix(metadata): read Zarr V3.1 short-hand extension names

[d-v-b]

This PR adds support for the string shorthand metadata declaration added in the 3.1 revision of the zarr spec

🤖 AI text below 🤖

Read array metadata that uses Zarr V3.1 short-hand extension names, such as "codecs": ["bytes", "crc32c"] or "chunk_key_encoding": "default". Previously, such documents raised TypeError: Expected dict, got <class 'str'>. Metadata is still written in the object form that Zarr V3.0 readers require.

Refs #3188. Spec compliance fix, intended for a patch release.

Spec

zarr-specs v3 core, "Short-hand names": "Instead of extension objects, short-hand names MAY be used if no configuration metadata is required. They are equivalent to extension objects with just a name key." data_type, chunk_grid, chunk_key_encoding, each entry of codecs, and each entry of storage_transformers "MUST conform to the extension-definition". The note under codecs says writers that need Zarr v3.0 compatibility must not use the short-hand form, which is why zarr-python keeps writing objects. zarrs changed its writer to always emit objects because zarr-python rejected the short-hand (zarrs/zarrs#488), but other writers may still emit it.

Change

A single helper, zarr.core.common.expand_short_hand_name, turns a bare string into {"name": s}. It runs in the one parser for each extension point:

• parse_codecs, which also handles the codecs and index_codecs nested inside a sharding codec.
• parse_chunk_key_encoding.
• parse_chunk_grid. A bare "regular" is still invalid because the grid needs a configuration. It now fails with the missing-configuration ValueError instead of a TypeError.
• parse_storage_transformers. Opening an array that declares storage transformers is still refused.

data_type already accepted a bare name. The public ChunkKeyEncodingLike type is not widened, so create_array's signature is unchanged.

packages/zarr-metadata already accepts the short-hand form at every extension point and needs no change.

Tests

• New cases in test_array_metadata_roundtrip cover:

  • a short-hand codec
  • short-hand mixed with the object form
  • short-hand codecs nested in sharding
  • a short-hand chunk key encoding
  • a short-hand storage transformer

  Each case asserts that the object form is written back.

• One test per error case:

  • a short-hand name for an extension that requires a configuration (chunk_grid, gzip, sharding_indexed)
  • an unknown short-hand codec name
  • an unknown short-hand chunk key encoding name

The 10 new test cases fail on main and pass with this change. The full suite passes locally without -W ignore.

Not addressed

#3188 also covers must_understand on extension objects. Currently {"name": "bytes", "must_understand": true} and false both parse silently, and the key is dropped on write. That is left for a separate change, so this PR does not close the issue.

Notes

• Supersedes the fork draft fix(metadata): read Zarr V3.1 short-hand extension names d-v-b/zarr-python#403 (same branch).

• ZEP9: Parse Metadata Objects #2866 (stale since 2025-05) is an earlier, broader attempt at the same issue. It edits each codec's from_dict.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.72%. Comparing base (bd0dc84) to head (d0e7392).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4506      +/-   ##
==========================================
+ Coverage   94.71%   94.72%   +0.01%     
==========================================
  Files          94       94              
  Lines       13663    13670       +7     
==========================================
+ Hits        12941    12949       +8     
+ Misses        722      721       -1     

Files with missing lines	Coverage Δ
src/zarr/core/chunk_key_encodings.py	98.59% <100.00%> (+0.02%)	⬆️
src/zarr/core/common.py	93.83% <100.00%> (+0.60%)	⬆️
src/zarr/core/metadata/v3.py	96.92% <100.00%> (+0.01%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.