On this page
Confirm the node and metadata version
Record a neutral store ID, root path, metadata file path, digest, Zarr format, node type, and metadata reader version. The Zarr Specification, (opens in a new tab) specification names zarr.json as the array metadata document in v3 and defines mandatory fields. Do not infer v3 from a directory name or accept a v2 field set as if it were v3 without recording the version boundary.
The source dates in this guide use 22 October 2026 as retrieval evidence for documentation without a verified publication date. They are not publication claims. Where a verified publication date is available, it is recorded in the source ledger.
| Metadata field | Record | Stop if |
|---|---|---|
| zarr_format | Declared integer and reader | Version is inferred from a library default |
| node_type | Array, group, or unknown | Group metadata is parsed as an array |
| shape | Ordered dimension lengths | Rank cannot be determined |
| data_type | Declared core or extension type | Extension definition is unavailable |
| chunk_grid | Grid name and configuration | Grid rank differs from shape |
| metadata path | Resolved path and digest | A stale cache replaces the source |
Keep v2 and v3 reports separate. Names such as dtype, chunks, or compressor can be useful observations of another version, but translating them to v3 fields is a transformation that needs its own record.
Match shape, chunk grid, and chunk keys
The Zarr Specification, (opens in a new tab) specification defines a logical regular grid and the key encoding that maps grid coordinates to store keys. Compare array rank to chunk-shape rank, verify each logical chunk extent, and derive the expected coordinate-to-key mapping. Then compare that logical expectation with physically stored keys: a present key must resolve to the intended cell, while an absent key may be represented by fill_value and is not automatically a grid gap.
| Comparison | Safe observation | Open question |
|---|---|---|
| Shape and rank | Dimension tuple and rank | Does a scalar or empty dimension have special handling? |
| Chunk shape | Length per array dimension | Are zero-length dimensions handled by the grid? |
| Logical grid | Expected cells and chunk extents from metadata | Does a dimension or chunk shape leave the logical grid undefined? |
| Stored keys | Observed physical keys and resolved coordinates | Is a present key ambiguous, extra, or mapped to the wrong cell? |
| Absent chunk | Missing key plus declared fill behavior | Is absence treated as a gap without checking fill_value? |
| Chunk key | Encoded coordinate and resolved path | Did a separator or prefix change? |
| Store path | Relative key under declared root | Could path traversal escape the store? |
| Dimension names | Declared names or absent | Are names preserved across conversion? |
Synthetic v3 metadata
{"zarr_format":3,"node_type":"array","shape":["fixture_rows","fixture_columns"],"data_type":"fixture-float32","chunk_grid":{"name":"regular","configuration":{"chunk_shape":["fixture_row_chunk","fixture_column_chunk"]}},"chunk_key_encoding":{"name":"default","configuration":{}},"state":"metadata-only"}Keep fill value and codec order together
The Zarr Specification, (opens in a new tab) specification makes fill_value mandatory and says the permitted values depend on the data type. It also defines codecs as bidirectional transforms whose representations change across the pipeline. Record the declared fill value, data type, codec names and configuration in order, and the reader’s decoded representation. Do not replace an absent chunk with a numeric zero unless the metadata says that zero is the fill value for that type.
| Storage evidence | Record | Stop if |
|---|---|---|
| Fill value | Exact JSON value and data type | A reader default is not recorded |
| Codec list | Order, name, and configuration | An extension codec is unknown |
| Decoded shape | Shape and type after each boundary | Pipeline output is assumed |
| Chunk bytes | Key, digest, and byte length | Bytes are read without codec context |
| Missing chunk | Absent, empty, or unreadable | Missing is turned into zero without policy |
| Attributes | Names and bounded redacted summaries | Private text is copied into the packet |
A fill value describes uninitialized portions of an array. It does not describe a producer’s missing-data policy, a quality score, or a physical zero. Keep fill behavior, actual stored chunks, and semantic missingness in different columns.
Compare metadata to a bounded read and round trip
Use a synthetic array to exercise metadata validation, key resolution, decode, and re-encode. Capture the source metadata digest, expected chunk coordinates, observed keys, decoded shape and type, and any transformed metadata. A successful read of one chunk does not prove that every expected key exists or that a missing chunk has the intended fill semantics.
| Check | Observed result | Question to resolve |
|---|---|---|
| Expected key set | Derived keys for the declared grid | Are all cells represented? |
| Existing key set | Keys found under the store root | Are extra keys stale or extension data? |
| Decoded chunk | Shape, type, and codec result | Did the reader coerce values? |
| Missing cell | Missing key and fill behavior | Is missing equivalent to uninitialized? |
| Re-encoded metadata | Changed fields and digest | Did a library normalize the contract? |
| Extension | Name, definition, and scope | Can another reader reproduce it? |
Stop on metadata mismatch
Stop conditions
- Stop if the Zarr version, node type, metadata path, or extension definition is unknown.
- Stop if shape, chunk grid rank, chunk shape, or key encoding cannot be reconciled.
- Stop if a fill value is missing, has the wrong type, or is supplied only by a reader default.
- Stop if a codec is unavailable, reordered, or applied to bytes with an unknown representation.
- Stop if a present key maps ambiguously, or if missing, extra, or stale physical keys are treated as logical coverage without recording fill behavior.
- Stop before reading real chunks when attributes or keys expose private paths or identifiers.
Pair this worksheet with the data provenance log for store and transformation history and the data card template for collection context. Metadata alignment does not prove array completeness, scientific meaning, privacy clearance, or permission.
For a supported non-health collection, after the owner has authority to describe the scope and a controlled metadata packet, the qualified appraisal request path may be a preparation step. It does not read Zarr chunks, benchmark storage, assess scientific meaning, create a quote, match a buyer, or grant a license.