diff --git a/packages/zarr-metadata/README.md b/packages/zarr-metadata/README.md
index a01ed26842..d4f3c6579a 100644
--- a/packages/zarr-metadata/README.md
+++ b/packages/zarr-metadata/README.md
@@ -2,410 +2,46 @@
 
 Documentation: <https://zarr-metadata.readthedocs.io/>
 
-Basic tools for modelling Zarr metadata, with minimal dependencies.
+Types, models and validators for Zarr metadata documents, with minimal
+dependencies.
 
 `zarr-metadata` is developed in the
 [zarr-python repository](https://github.com/zarr-developers/zarr-python/tree/main/packages/zarr-metadata)
-and released independently of `zarr` itself. Install it with:
+and released independently of `zarr`. Install it with:
 
 ```
 pip install zarr-metadata
 ```
 
-## Who needs this
-
-This library supports software that interacts with Zarr metadata documents.
-
 ## What this is
 
-This is *not* a full Zarr implementation. It's a collection of data structures and routines that
-closely model the content of the Zarr specifications, such as:
-
-- **Typed JSON shapes** ([`zarr_metadata.v2`](https://zarr-metadata.readthedocs.io/en/latest/api/v2/) and
-  [`zarr_metadata.v3`](https://zarr-metadata.readthedocs.io/en/latest/api/v3/)): `TypedDict` definitions and
-  `Literal` aliases for the JSON documents specified by the
-  [Zarr v2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html) and
-  [Zarr v3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html)
-  specifications, plus types for
-  [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/) and a
-  few widely-used-but-unspecified entities (e.g. consolidated metadata).
-- **Document models** ([`zarr_metadata.model`](https://zarr-metadata.readthedocs.io/en/latest/api/model/)): immutable
-  models of whole metadata documents, each one a document and the scope
-  it was read in, with readers that report every problem at its
-  location, and store-key (de)serialization. A document
-  produced by `to_json` shares no mutable state with the model that produced
-  it.
-- **Definitions and scopes** ([`zarr_metadata.definition`](https://zarr-metadata.readthedocs.io/en/latest/api/definition/),
-  with each format's kinds in `zarr_metadata.v3.definition` and
-  `zarr_metadata.v2.definition`): each extension's configuration as a
-  `TypedDict` with its rules, and the scope that decides which definitions
-  read a document. `zarr_metadata.v3` and `zarr_metadata.v2` export every
-  definition and scope of their format, such as `BYTES_CODEC` and
-  `CORE_AND_EXTENSIONS_CONTEXT`.
-- **JSON type checking** ([`zarr_metadata.typed_json`](https://zarr-metadata.readthedocs.io/en/latest/api/typed_json/)):
-  `check` checks a JSON value against any `TypedDict` and reports every
-  problem with its location.
-- **Problems** ([`zarr_metadata.problems`](https://zarr-metadata.readthedocs.io/en/latest/api/problems/)): the problem
-  values every reader returns, and the error that carries them.
-- **JSON Schema** ([`zarr_metadata.json_schema`](https://zarr-metadata.readthedocs.io/en/latest/api/json_schema/)): the
-  JSON Schema of a `TypedDict`, a v3 declaration, or a whole `zarr.json`.
-- **Optional Pydantic integration** ([`zarr_metadata.pydantic`](https://zarr-metadata.readthedocs.io/en/latest/api/pydantic/),
-  requires Pydantic 2.13 or newer): each model as a Pydantic field type that
-  validates raw documents through the same strict parser.
-
-## What this is for
-
-- **Static Type Checking** The public `TypedDict` definitions describe the static JSON shape of Zarr
-  metadata.
-
-- **Dynamic JSON validation** For strict, loc-aware validation of JSON loaded from disk, use the
-  model parser:
-
-  ```python test="true" session="readme"
-  import json
-  from zarr_metadata.model import ZarrV3ArrayMetadata
-
-  with open("zarr.json", "rb") as f:
-      raw = json.load(f)
-
-  metadata = ZarrV3ArrayMetadata.from_json(raw)
-  ```
-
-  The optional Pydantic integration delegates raw input to the same strict
-  parser and returns the same normalized model class:
-
-  ```python test="true" session="readme"
-  from pydantic import TypeAdapter
-  import zarr_metadata.pydantic as zmp
-
-  adapter: TypeAdapter[zmp.ZarrV3ArrayMetadataField] = TypeAdapter(zmp.ZarrV3ArrayMetadataField)
-  metadata = adapter.validate_python(raw)
-  encoded = metadata.to_key_value()["zarr.json"]
-  ```
-
-  A field annotated `Annotated[ZarrV3ArrayMetadata, zmp.InScope(CONTEXT)]`
-  is read in `CONTEXT`, whatever the validation context holds, and a model
-  instance given to it is read again in `CONTEXT`.
-
-  Note that a bare `TypeAdapter` over a public `TypedDict` is a **coercive** shape
-  adapter, not a Zarr conformance validator; it may coerce values or discard
-  members that the strict model parser rejects. This is better suited for handling input provided
-  from Python objects (e.g., user-authored dicts) than JSON.
-
-## Validation boundary
-
-The readers and model constructors enforce the declared document structure and a small set
-of context-free consistency rules, e.g.:
-- fixed format literals,
-- finite JSON numbers outside `attributes` and the members nothing in scope reads
-- non-negative dimensions
-- one `dimension_names` entry per array dimension.
-
-In a v3 document, validation also checks each extension point: the data
-type, the chunk grid, the chunk key encoding, each codec, and each storage
-transformer. Each one is checked by the definition that claims its name in
-a scope. The scope is `CORE_AND_EXTENSIONS_CONTEXT` unless a `context` is passed.
-`ZARR_PYTHON_CONTEXT` adds the data types that zarr-python writes but no
-specification registers.
-If the definition rejects a configuration, the reader rejects it too,
-and a configuration key the definition does not declare is reported as
-`unknown_key`. If no definition in the scope claims a name, the reader
-does not check that extension point, and the consumer decides whether to
-support it.
-
-Some checks relate one part of a v3 document to another:
-
-- The fill value is checked against the data type the document names, by
-  that data type's definition.
-- The chunk grid is checked against the shape, by the grid's definition.
-- The codecs are checked as a pipeline. In order, each codec's definition
-  checks the codec against the chunk it receives. This includes a shard's
-  inner codecs and index codecs.
-
-The readers do no arithmetic on values. For example, they do not check
-whether a fill value survives a `cast_value` round trip.
-
-Some choices that the spec text leaves open, or answers in two ways:
-
-- **`attributes` may hold `NaN`, `Infinity` and `-Infinity`.** The spec
-  does not interpret attributes, and zarr-python and xarray write these
-  numbers there (for example, a CF `_FillValue`). The models read them,
-  and `to_key_value` writes them back as bare tokens, which a strict JSON
-  parser rejects. So may a member the spec does not define when no
-  definition in scope claims it: nothing reads it, so it is kept as
-  written. `check`, from `zarr_metadata.typed_json`, rejects a non-finite
-  number anywhere, including in attributes.
-- **A reader walks at most 256 levels of nesting.** A value nested deeper
-  is an `invalid_value` problem at the first level past the limit,
-  wherever it is. Every reader, writer and comparison uses one stack
-  frame per level, and `copy.deepcopy` (and `pickle` before Python 3.12)
-  uses two. A document at the limit therefore uses about half of the
-  interpreter's default recursion limit, and the rest is left for the
-  caller.
-- **`consolidated_metadata: null` is a problem.** A zarr-python 3.0.x bug
-  wrote it. The spec requires an object, and the package accepts only an
-  object. A reader of those stores removes the key before reading.
-- **An extension name must follow the spec's naming rule**,
-  `^[a-z][a-z0-9-_.]+$`, or be a URI, which earlier versions of the spec
-  required. Any other name is rejected before any definition is
-  consulted, so `""` and `"foo/bar"` are problems, not unknown extensions.
-- **`must_understand: false` is rejected at every extension point**,
-  including codecs and storage transformers, although the core spec names
-  only the data type, chunk grid and chunk key encoding. A reader that
-  skips a codec reads wrong bytes, just as a reader that skips a data type
-  reads wrong values. On an unknown top-level member, `must_understand`
-  keeps its meaning: a reader can skip that member.
-- **A v2 datetime or timedelta dtype must have a unit**, as in `<M8[ns]`,
-  because the v2 spec requires the unit in brackets. zarr-python 3 writes
-  `<M8` or `<m8` for a NumPy `datetime64` or `timedelta64` with no unit,
-  and the package refuses those dtypes. A codec's dtype parameter, such as
-  the `dtype` of a `delta` filter, may leave out the unit, because
-  numcodecs writes it that way and runs it.
-- **A v2 codec's dtype parameter is checked against the core v2 data
-  types**, whatever scope the array is read in, because numcodecs reads
-  the parameter with NumPy. So a scope that widens a data type, for
-  example to read `<f16`, does not widen what a codec's dtype parameter
-  may be.
-
-A v3 `regular` chunk grid's chunk lengths must be at least 1, even along a
-dimension of length 0. The regular grid spec says "Chunk sizes must be
-greater than zero". The core spec's wording, "non-zero when the
-corresponding dimensions of the arrays have non-zero length", requires
-less, but does not explicitly allow anything more. So a document with a
-chunk length of 0, which zarr-python 3.0 and 3.1 wrote for an empty
-dimension, is rejected.
+A collection of data structures and routines that closely model the
+metadata rules in the Zarr v2 and v3 specifications and in zarr-extensions:
 
-The readers are strict, so a document that a known writer bug made
-invalid has problems. The repair readers in `zarr_metadata.model`
-(`read_repaired_node_metadata_v3`, `read_repaired_node_metadata_v2` and
-`read_repaired_consolidated_metadata_v2`) undo these bugs first, then
-read the result strictly, and return each change they made as a `Repair`:
+- `TypedDict` shapes for every document and configuration.
+- Immutable document models. Their readers report every problem at its
+  location.
+- **Contexts**, which say exactly which codecs, data types and other
+  extensions a program reads.
 
-- A chunk length of 0 in a v3 `regular` chunk grid, along an empty
-  dimension, which zarr-python 3.0 and 3.1 wrote, is written as 1.
-- `consolidated_metadata: null` on a v3 group, which zarr-python 3.0 and
-  3.1 wrote, is removed.
-- The `consolidated_metadata` member that zarr-python 3 writes into each
-  `.zgroup` entry of a `.zmetadata` below the root is removed.
-- A non-finite v2 fill value that zarr-python 3.0.0 to 3.0.6 wrote as a
-  bare `NaN`, `Infinity` or `-Infinity` is written as the string the v2
-  spec uses, such as `"NaN"`.
-- A non-finite float or complex fill value in a v3 group's consolidated
-  metadata, which zarr-python 3.0.0 to 3.0.6 wrote as a bare token, is
-  written as the string the v3 spec uses, such as `"NaN"`.
-
-The repair readers do not undo these known writer bugs, so a document
-with one of them is refused:
-
-- zarr-python 3.0.7 to 3.0.10 wrote the fill value of an `S` or `V`
-  array in a `.zmetadata` entry as a JSON array of byte values. The
-  array's own `.zarray` file holds the base64 string that the package
-  reads.
-- zarr-python 3.0.7 and 3.0.8 wrote the fill value of a v2 datetime
-  array as an ISO 8601 string, not as a count of ticks.
-- zarr-python 3.0 and 3.1 wrote a chunk length of 0 in a v3 `regular`
-  chunk grid along a dimension that is not empty, for an explicit chunk
-  length of 0.
-- Some releases of zarr-python from 3.0 to 3.2 wrote a chunk length of
-  `true` in a v3 `regular` chunk grid for `chunks=True`, and some
-  releases of 3.0 and 3.1 wrote `false` for `chunks=False`.
-
-`read_array_metadata_v3` reads a document once and returns everything the
-read found:
-
-- each declaration as the scope read it: an `AcceptedDeclaration` when a definition
-  claims its name, an `UnclaimedDeclaration` when none does, or a
-  `RefusedDeclaration`, together with the declaration's location and the kind it was
-  read as;
-- each codec, with the chunk it receives;
-- every problem;
-- the model, when there are no problems.
-
-`from_json` returns that model, or raises the problems. A consumer can
-apply its own policy by walking the declarations, without reading anything
-twice. `with_problems` pairs each declaration with its problems: those located
-in the declaration and in the declarations it contains. This matches how zod's
-`flattenError` groups issues. `canonical_of` returns the simplest
-spelling of a declaration that has no problems, without reading it again. For
-example, the code below finds the declarations that go beyond the core spec (a
-declaration with no name is already a problem), and the simplest spelling of
-each declaration:
-
-```python test="true" session="readme"
-from zarr_metadata.model import read_array_metadata_v3
-from zarr_metadata.definition import canonical_of, with_problems
-from zarr_metadata.v3.definition import CORE_CONTEXT
-
-reading = read_array_metadata_v3(raw)
-beyond_core = [
-    loc
-    for loc, declaration in reading.declarations()
-    if declaration.name is not None
-    and CORE_CONTEXT.claimant(declaration.read_as, declaration.name) is None
-]
-simplest = {
-    loc: canonical_of(declaration, problems)
-    for loc, declaration, problems in with_problems(reading.declarations(), reading.problems)
-}
-metadata = reading.metadata  # None when reading.problems is not empty
-```
-
-`read_group_metadata_v3` reads a group the same way. It checks the
-envelope of the group's `consolidated_metadata`, and does not read the
-documents the member lists (see below). `read_node_metadata_v3` reads
-a `zarr.json` of either kind as the node type its `node_type` names, the
-same way a discriminated union uses its tag. A document whose `node_type`
-is neither reads as `ZarrV3UnknownNodeMetadataReading`, with the problems.
-Only its `zarr_format` is read, so a document of another format is
-reported as not v3. `node_metadata_from_json_v3` and
-`node_metadata_from_key_value_v3` build the model of either kind, the same
-way the models' own `from_json` and `from_key_value` build one.
-
-Consolidated metadata holds the hierarchy below its group, with the group
-as the root. The document of the node at `/a/b` is stored under the key
-`a/b`. The documents and the group must form a tree: only groups have
-child nodes, and the parent of every node is present.
-`ZarrV3ConsolidatedMetadata` checks this when it reads the documents. `NodeName` and
-`NodePath`, in `zarr_metadata.v3`, are the types of strings that satisfy
-the spec's rules for node names and paths. They are modeled on the zarrs
-types with the same names. `validate_node_name_v3`, `is_node_name_v3` and
-`parse_node_name_v3`, and the matching `node_path` functions, check a
-string against those rules.
-
-A top-level member that the spec does not define is an extra field. A
-scope can hold a definition for one, by its key, in the
-`array_extra_fields` or `group_extra_fields` slot of `ZarrV3Context`. A
-member whose key a definition claims is read by that definition: an extra field is a declaration
-written as the member alone, `{key: value}`. Any other extra field is kept as
-written, as an `UnclaimedDeclaration`.
-The scope is what a reader recognizes, so the model's
-`must_understand_fields` lists each unclaimed member that does not say
-`"must_understand": false`: the spec requires a reader to fail to open a
-node with any such member. It covers extra fields only. A data type, chunk
-grid, chunk key encoding, codec or storage transformer that nothing in
-scope claims is an `UnclaimedDeclaration` too, also when it sits inside another
-declaration, such as a codec inside a shard. A model's `unclaimed_declarations` lists
-every declaration nothing in scope claims, at any depth, by its location, and
-leaves out the members that waive `must_understand`: a reader can open
-the node when it is empty. `CORE_CONTEXT` holds
-`CONSOLIDATED_METADATA_EXTRA_FIELD`, which reads a group's
-`consolidated_metadata` as the envelope the spec fixes. A group's
-`consolidated()` reads the documents that member lists, in the group's
-own scope.
-
-A v3 model consists of its document and the scope it was read in.
-`ZarrV3ArrayMetadata(document, context=None)` reads the document in the
-scope (`CORE_AND_EXTENSIONS_CONTEXT` when none is given) and raises
-`MetadataValidationError` with every problem, so an invalid model is never
-built. `to_json` returns the document as it was written, and
-`to_key_value` writes that same document to store bytes.
-
-Every typed attribute is a view of that read: each declaration as the scope read
-it (an `AcceptedDeclaration` or an `UnclaimedDeclaration`), and `shape`, `attributes`
-and the members that hold no declaration as the read refined them. These views are read-only
-at every level: a list in the document is shown as a tuple, and an object
-as a read-only mapping. `to_json` returns plain containers.
-
-To change a model, call `update`. It replaces members of the document with
-the given JSON members and reads the result in the model's own scope, so
-you do not pass the scope again. A member the spec defines is given by its
-name, and any other member in `extra_fields`, a mapping from its key to its
-value, or to `UNSET` to remove it. A name `update` does not take raises
-`TypeError`, so a misspelled member is never written. `with_context` reads the document in
-another scope. `refined_in` also reads the document in another scope, but
-only one that claims what this scope left unclaimed and contradicts
-nothing; otherwise it raises `ScopeConflictError`.
-
-A group does not read the documents its `consolidated_metadata` lists.
-Consolidated metadata is a convention of the reference implementation,
-not core metadata, so a group holds the member as written, after it
-checks the envelope that the core spec fixes. A reader can use the
-member as a source of child documents in place of the store: read one
-document with `read_node_metadata_v3` when that node is opened, or read
-all of them with `ZarrV3ConsolidatedMetadata`, or with
-`read_consolidated_metadata_v3`, which returns problems instead of
-raising them. A document with a problem then fails only when it is read.
-Pass `context=group.context` to read the documents in the group's own
-scope; with no `context`, they are read in `CORE_AND_EXTENSIONS_CONTEXT`.
-
-To write consolidated metadata, build a `ZarrV3ConsolidatedMetadata` and
-pass it to the group's `update`. The group reads the listed models in its
-own scope, refuses one that its scope reads differently, and writes the
-document. The model reads every document strictly, and also accepts node
-models as entries. Such an entry is accepted when its claims refine into
-the model's scope, and refused at its path otherwise. To consolidate
-children that were read in several scopes, consolidate them in the
-`union` of those scopes. Every reader takes `context=None` for the
-default scope, `CORE_AND_EXTENSIONS_CONTEXT`.
-
-Two models are equal when they represent the same document, even if each
-is spelled differently. Values the package interprets (each declaration, and the
-fill value against its data type) are compared by their canonical
-spelling, as returned by `canonical_of` and `canonical_fill_value`. For
-example, `"NaN"` and `"0x7fc00000"` are the same `float32` fill value,
-`0.0` and `-0.0` are two different fill values, and a v3 blosc codec
-under `noshuffle`, which ignores `typesize`, is the same codec with or
-without one. A v2
-document's dtype, codecs and fill value are compared the same way: `<b1`
-and `|b1` are one dtype, in `dtype` and in a codec's dtype parameter
-alike, and a v2 codec that leaves out a parameter is
-the same as one that writes the numcodecs default, so
-`{"id": "zstd", "level": 0}` equals
-`{"id": "zstd", "level": 0, "checksum": false}`. A v2 blosc `typesize`
-is kept whatever the `shuffle`, unlike in v3: v2 codecs are defined by
-numcodecs, which writes it into each chunk's header, so two v2 blosc
-codecs that differ only in it encode different bytes, though they decode
-the same data. The v3 spec defines its blosc codec, and says `noshuffle`
-ignores `typesize`. A v2 node with no `.zattrs` equals one with an
-empty `.zattrs`, as a v3 document with and without an empty
-`attributes` are equal. Values the package does
-not interpret (attributes, extra fields, and the configuration of a declaration
-that nothing in the scope claims) are compared as JSON text. JSON text
-distinguishes `true` from `1` and `-0.0` from `0.0`, and treats `NaN` as
-equal to itself. Equal models have equal hashes, but may write different
-documents, because `to_json` writes each document as it was given. A
-model holds nothing that can be changed in place.
-
-`node_metadata_json_schema_v3` writes the rules the readers apply as a
-JSON Schema (draft 2020-12). Use it in an editor that checks a `zarr.json`
-while you write it, or with a validator in another language. Each
-extension point is described as a declaration as its scope reads it: a claimed
-configuration follows its definition's TypedDict, including bounds, and a
-name that nothing in the scope claims may have any configuration. The fill
-value must be a valid fill value for the data type the document names.
-`declaration_json_schema_v3(kind, *, context=None)` writes the schema of one declaration, and
-`json_schema` writes the schema of any TypedDict as `check` reads it. All
-three are in `zarr_metadata.json_schema`. A schema describes each member on its own, not the rules that
-relate members to each other, so a document the schema accepts may still
-have a problem. Every JSON document the readers accept, the schema also
-accepts. A schema validator reads JSON as a parser produces it, with
-arrays as lists. A model's `to_json` returns tuples, which a Python
-validator does not accept as arrays.
+This is *not* a full Zarr implementation. Nothing here reads or writes
+chunks, encodes or decodes data, or performs store I/O.
 
 ```python test="true" session="readme"
 import json
-from zarr_metadata.json_schema import node_metadata_json_schema_v3
+from zarr_metadata import ZarrV3ArrayMetadata
 
-with open("zarr.schema.json", "w") as f:
-    json.dump(node_metadata_json_schema_v3(), f, indent=2)
-```
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
 
-## Scope
-
-At minimum, this library supports what Zarr-Python needs: the complete
-Zarr v2 and v3 specs, consolidated metadata, and a subset of the metadata
-defined in `zarr-extensions`. We are generally open to contributions that
-add types, models, or validation for Zarr metadata with a
-published spec.
+metadata = ZarrV3ArrayMetadata.from_json(raw)
+```
 
-Runtime array behavior is out of scope: nothing here encodes or decodes
-chunks, resolves codec or data type names to implementations, or performs
-store I/O. The models begin and end at the metadata documents themselves —
-`from_key_value` / `to_key_value` map documents to store keys and bytes,
-and everything past that belongs to consumer libraries.
+`from_json` returns the model, or raises `MetadataValidationError` with
+every problem it found. The
+[documentation](https://zarr-metadata.readthedocs.io/) has a guide for
+each kind of use, and the API reference.
 
-## Reference
+## License
 
-- [API reference](https://zarr-metadata.readthedocs.io/en/latest/api/)
-- [Release notes](https://zarr-metadata.readthedocs.io/en/latest/release-notes/)
-- [License (MIT)](https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-metadata/LICENSE.txt)
+[MIT](https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-metadata/LICENSE.txt)
diff --git a/packages/zarr-metadata/changes/4604.feature.md b/packages/zarr-metadata/changes/4604.feature.md
new file mode 100644
index 0000000000..21ba7def2d
--- /dev/null
+++ b/packages/zarr-metadata/changes/4604.feature.md
@@ -0,0 +1 @@
+`zarr_metadata.model.read_openable_node_metadata_v3` reads a v3 `zarr.json` as `read_node_metadata_v3` does, and also reports each declaration a reader must understand to open the node that nothing in scope claims, such as an unknown codec or an unknown top-level member without `"must_understand": false`, as a problem of the new kind `unclaimed_declaration`. Its reading has no problems exactly when a reader that understands the scope can open the node, so a validator does not have to check `unclaimed_declarations` itself. The other readers still accept unclaimed declarations, and the `from_json` and reader docstrings now point to `unclaimed_declarations` and the new reader.
diff --git a/packages/zarr-metadata/changes/4605.doc.md b/packages/zarr-metadata/changes/4605.doc.md
new file mode 100644
index 0000000000..65a09f4e1f
--- /dev/null
+++ b/packages/zarr-metadata/changes/4605.doc.md
@@ -0,0 +1 @@
+The documentation now has a short landing page that points each kind of reader to a guide page, instead of one long page. New guide pages cover models and readers, the rules the readers check, consolidated metadata, repairing known writer bugs, writing an extension, JSON Schema and Pydantic. Each claim the pages make about a Zarr specification links to the section of the spec that makes it, and the consolidated metadata page says what the specs do and do not settle, with links to the zarr-specs pull requests and issues and to the original zarr-python implementation. The pages say "context" for a `Context` where some said "scope".
diff --git a/packages/zarr-metadata/changes/4609.feature.md b/packages/zarr-metadata/changes/4609.feature.md
new file mode 100644
index 0000000000..ab6ec78e93
--- /dev/null
+++ b/packages/zarr-metadata/changes/4609.feature.md
@@ -0,0 +1 @@
+Export `base64_fill_value_rules` from `zarr_metadata.v3.data_type.bytes`, the rule that rejects a fill value string that is not standard-alphabet base64, so a data type defined outside the package can pass it as `fill_value_rules` for a `Base64Bytes` fill value, or yield from it in a rule of its own. The guide to parsing and validation now shows how to define a data type with `fill_value_rules`.
diff --git a/packages/zarr-metadata/docs/api/index.md b/packages/zarr-metadata/docs/api/index.md
index a3e7be2665..fae1f6fd03 100644
--- a/packages/zarr-metadata/docs/api/index.md
+++ b/packages/zarr-metadata/docs/api/index.md
@@ -9,7 +9,7 @@ The package is organized to mirror the structure of the Zarr specifications:
 - [`zarr_metadata.json_schema`](json_schema.md) — JSON Schema output for
   any `TypedDict`, one v3 declaration, or a whole v3 `zarr.json`
 - [`zarr_metadata.model`](model.md) — document models (each one a
-  document and the scope it was read in), the readers that return
+  document and the context it was read in), the readers that return
   problems instead of raising them, and the `UNSET` sentinel
 - [`zarr_metadata.problems`](problems.md) — `ValidationProblem`,
   `ProblemKind`, `Problems` and `MetadataValidationError`, which every
@@ -21,7 +21,7 @@ The package is organized to mirror the structure of the Zarr specifications:
   typing spec defines them, with every problem located
 - [`zarr_metadata.v2`](v2.md) — `TypedDict` shapes for Zarr v2 documents
   (`.zarray`, `.zgroup`, `.zattrs`, `.zmetadata`), and
-  `zarr_metadata.v2.definition`: the v2 kinds of metadata, the scope
+  `zarr_metadata.v2.definition`: the v2 kinds of metadata, the context
   `CORE_V2_CONTEXT`, and the readers of one `dtype` or codec. Each dtype family's
   definition is in `zarr_metadata.v2.data_type`, and each codec's in
   `zarr_metadata.v2.codec`
@@ -32,10 +32,11 @@ The package is organized to mirror the structure of the Zarr specifications:
 - [`zarr_metadata.definition`](definition.md) — what both formats share
   for reading a declaration: `Definition`, `resolve`, the three results of a
   reading (`AcceptedDeclaration`, `UnclaimedDeclaration`, `RefusedDeclaration`), and the
-  scope type `Context`. Its module docstring is the guide
+  context type `Context`. Its module docstring is the guide
 - [`zarr_metadata.v3.definition`](v3/definition.md) — the five v3 kinds
   of metadata (`CodecDefinition`, `DataTypeDefinition`, ...), the codec
-  pipeline types, and the v3 scopes `CORE_CONTEXT` and `CORE_AND_EXTENSIONS_CONTEXT`
+  pipeline types, and the v3 contexts `CORE_CONTEXT`,
+  `CORE_AND_EXTENSIONS_CONTEXT` and `ZARR_PYTHON_CONTEXT`
 
 The document types, models, and spec vocabulary — including the store keys —
 are re-exported at the top level, so
diff --git a/packages/zarr-metadata/docs/consolidated-metadata.md b/packages/zarr-metadata/docs/consolidated-metadata.md
new file mode 100644
index 0000000000..47c80eea2d
--- /dev/null
+++ b/packages/zarr-metadata/docs/consolidated-metadata.md
@@ -0,0 +1,143 @@
+# Consolidated metadata
+
+Consolidated metadata is a copy of every metadata document below a group,
+kept in one place. A reader can then open a whole hierarchy with one read.
+
+Consolidated metadata is a convention of zarr-python, the reference
+implementation. Neither Zarr specification defines it in full. This page
+first says what is settled, then describes the API.
+
+## Status in the specifications
+
+**Zarr v2.** The v2 spec has no consolidated metadata.
+
+- The `.zmetadata` file was designed in zarr-python
+  [PR 268](https://github.com/zarr-developers/zarr-python/pull/268). It
+  merged in November 2018 and shipped in zarr-python 2.3.0.
+- The
+  [zarr-python 2 tutorial](https://zarr.readthedocs.io/en/v2.18.3/tutorial.html#consolidating-metadata)
+  describes it.
+- zarr-specs [issue 113](https://github.com/zarr-developers/zarr-specs/issues/113),
+  on standardizing the format, is open.
+
+**Zarr v3.** The core spec names the member but does not define its
+entries.
+
+- zarr-specs [PR 309](https://github.com/zarr-developers/zarr-specs/pull/309)
+  proposes the `consolidated_metadata` member, with the `kind: "inline"`
+  envelope that zarr-python 3 writes. It follows
+  [issue 136](https://github.com/zarr-developers/zarr-specs/issues/136). It
+  has been open since August 2024 and is not merged.
+- [PR 373](https://github.com/zarr-developers/zarr-specs/pull/373) merged
+  in July 2026. Since then, the core spec names the member "for historical
+  reasons" and fixes its envelope
+  ([spec text](https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816)).
+  The envelope is an object with:
+    - `must_understand: false`,
+    - `kind: "inline"`,
+    - a `metadata` object.
+- PR 373 closed
+  [issue 371](https://github.com/zarr-developers/zarr-specs/issues/371).
+  That issue found a problem with the v3.1.0 extension rules. Read
+  strictly, they put every consolidated group zarr-python 3 had written out
+  of spec, because the envelope has no `name`.
+
+This package reads the envelope the spec fixes. It reads the entries as
+zarr-python writes them.
+
+## Zarr v3
+
+Consolidated metadata holds the hierarchy below its group, with the group
+as the root.
+
+- The document of the node at `/a/b` is stored under the key `a/b`. The
+  [stored representation](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#stored-representation)
+  strips the leading `/` of a path.
+- The documents and the group must form a tree. Only groups have child
+  nodes, and the parent of every node is present.
+  `ZarrV3ConsolidatedMetadata` checks this when it reads the documents.
+
+`NodeName` and `NodePath`, in `zarr_metadata.v3`, are string types. They
+satisfy the spec's rules for
+[node names](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#node-names)
+and paths. They are modeled on the zarrs types with the same names. These
+functions check a string against those rules:
+
+- `validate_node_name_v3`, `is_node_name_v3` and `parse_node_name_v3`,
+- the matching `node_path` functions.
+
+### Reading
+
+A group does not read the documents its `consolidated_metadata` lists.
+Consolidated metadata is a convention of the reference implementation, not
+core metadata. So the group checks the
+[envelope that the core spec fixes](https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816),
+then holds the member as written. `CORE_CONTEXT` holds
+`CONSOLIDATED_METADATA_EXTRA_FIELD`, the definition that reads this
+envelope.
+
+A reader can use the member as a source of child documents, in place of
+the store. There are two ways:
+
+- Read one document with `read_node_metadata_v3` when that node is opened.
+- Read all of them at once, with one of:
+    - the group's `consolidated()`,
+    - `ZarrV3ConsolidatedMetadata`,
+    - `read_consolidated_metadata_v3`, which returns problems instead of
+      raising them.
+
+Either way, a document with a problem fails only when it is read.
+
+Which context the documents are read in:
+
+- `consolidated()` uses the group's own context.
+- The other three take a `context`. Pass `context=group.context` to use the
+  group's own context. With no `context`, they use
+  `CORE_AND_EXTENSIONS_CONTEXT`.
+
+### Writing
+
+To write consolidated metadata:
+
+1. Build a `ZarrV3ConsolidatedMetadata`.
+2. Pass it to the group's `update`.
+
+The group reads the listed models in its own context. It refuses a model
+that its context reads differently. Then it writes the document.
+
+`ZarrV3ConsolidatedMetadata` reads every document strictly. It also
+accepts node models as entries. It accepts such an entry when the entry's
+claims refine into the model's context. Otherwise it refuses the entry at
+its path. To consolidate children read in several contexts, consolidate
+them in the `union` of those contexts.
+
+## Zarr v2
+
+A v2 hierarchy's consolidated metadata is the `.zmetadata` document at the
+root of the store. zarr-python 2.3 and later write it. It is an object
+with:
+
+- `zarr_consolidated_format: 1`,
+- a `metadata` object. This maps each metadata file's path to that file's
+  contents, under keys such as `a/.zarray`, `a/.zattrs` and `a/b/.zgroup`.
+
+The format comes from zarr-python
+[PR 268](https://github.com/zarr-developers/zarr-python/pull/268). No
+specification defines it.
+
+`ZarrV2ConsolidatedMetadata` reads such a document.
+`read_consolidated_metadata_v2` does the same, but returns problems instead
+of raising them. Both take a `context`. The default is `CORE_V2_CONTEXT`.
+
+How the entries are read:
+
+- Each `.zarray` or `.zgroup` entry is read as a node, merged with its
+  sibling `.zattrs`.
+- A `.zattrs` with no sibling is kept, but forms no node.
+- Any other entry must be JSON, and is kept.
+
+`to_json` returns the entries keyed by file, as written.
+
+The `.zmetadata` that zarr-python 3 writes for a v2 hierarchy has a known
+bug. `read_repaired_consolidated_metadata_v2` undoes it. See
+[Repairing known writer bugs](repair.md).
diff --git a/packages/zarr-metadata/docs/context.md b/packages/zarr-metadata/docs/context.md
index b97bf86f88..299115368e 100644
--- a/packages/zarr-metadata/docs/context.md
+++ b/packages/zarr-metadata/docs/context.md
@@ -4,7 +4,7 @@ Resolving metadata documents requires a context, a `Context`, that defines which
 
 ## Why do we need a context
 
-The Zarr V3 spec defines the JSON structure of `zarr.json` for arrays and groups exactly, by defining the fields that must be present and the JSON types they must have. But the __interpretation__ of those fields as actual data types, codecs, chunk grids, etc is not strictly defined by the spec. Relating a JSON value like `"bytes"` to the `bytes` codec requires a mapping from names to codec types.
+The Zarr V3 spec defines the JSON structure of `zarr.json` for arrays and groups exactly. It defines the members that must be present and the JSON types they must have. But the __interpretation__ of those members as actual data types, codecs, chunk grids, etc is not strictly defined by the spec. Relating a JSON value like `"bytes"` to the `bytes` codec requires a mapping from names to codec types.
 
 `zarr-metadata` makes this explicit by validating JSON documents with a __context object__. That context object contains definitions of codecs, data types, etc, which can be matched to the declarations in the JSON document.
 
@@ -47,7 +47,7 @@ document: ZarrV3ArrayMetadataJSON = {
 }
 ```
 
-In the above code snippet we define a `zarr.json` document with three codec declarations (we will just call them codecs for brevity): one named `bytes`, another named `gzip`, and a third named `unknown`. The `bytes` codec here is correctly configured according to the `bytes` codec spec. The `gzip` declaration here violates the `gzip` codec spec because the `level` configuration field is too high. And the `unknown` codec is unknown, it has no specification and cannot be resolved.
+In the above code snippet we define a `zarr.json` document with three codec declarations. (We will just call them codecs for brevity.) They are named `bytes`, `gzip` and `unknown`. The `bytes` codec here is correctly configured according to the `bytes` codec spec. The `gzip` declaration here violates the `gzip` codec spec because the `level` configuration member is too high. And the `unknown` codec is unknown, it has no specification and cannot be resolved.
 
 These three codecs represent three different scenarios that this library handles, two with distinct failure modes. We demonstrate how this works in the next code snippet.
 
@@ -101,7 +101,7 @@ These are the three scenarios:
 
 - `bytes` is parsed to an `AcceptedDeclaration`. A definition in the context claims the name `bytes`, and the configuration passes its checks.
 - The malformed `gzip` is parsed to a `RefusedDeclaration`. A definition claims the name `gzip`, but the configuration fails one of its checks: a `level` of 99 is outside the range gzip allows. The read reports the problem, with its location in the document, and builds no model, so `reading.metadata` is `None`. Building the model directly raises the same problem as a `MetadataValidationError`.
-- The `unknown` codec is parsed to an `UnclaimedDeclaration`. Nothing in the context claims the name, so it is kept as written and not checked. This is not a problem: the spec lets a document name codecs a reader does not know.
+- The `unknown` codec is parsed to an `UnclaimedDeclaration`. Nothing in the context claims the name, so it is kept as written and not checked. This is not a problem: the spec [lets a document name codecs](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#extension-codecs) defined outside it, which a reader may not know.
 
 So one JSON document can be valid in one context and invalid in another. This is why a model is a document _and_ the context it was read in: the context defines the interpretation of the document. A model keeps its context, and moving it to another context reads the document again. Our `small` model was valid in its original context, but it is not valid in the new one:
 
diff --git a/packages/zarr-metadata/docs/extensions.md b/packages/zarr-metadata/docs/extensions.md
new file mode 100644
index 0000000000..5b6162c1b9
--- /dev/null
+++ b/packages/zarr-metadata/docs/extensions.md
@@ -0,0 +1,116 @@
+# Writing an extension
+
+A v3 document may name a codec, data type, chunk grid, chunk key encoding
+or storage transformer that this package does not define. Each of these is
+an
+[extension point](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#extension-points)
+of the v3 spec.
+
+The readers leave such a declaration unclaimed. To check it, a program
+adds a **definition** to the context it reads in.
+
+The [`zarr_metadata.definition`](api/definition.md) module docstring is the
+full reference. This page is the short version.
+
+A definition is a value, not a class to subclass. It has:
+
+- a `name`,
+- a `TypedDict` for the configuration's JSON,
+- a `rules` function, when the type cannot express every rule. The function
+  yields the spec violations in a configuration.
+
+A v3 codec definition also says:
+
+- what kind of codec it is,
+- whether its output size is fixed by its input size.
+
+```python test="true" session="extensions"
+from collections.abc import Iterator
+from typing import Annotated, NotRequired
+
+from annotated_types import Ge
+from typing_extensions import TypedDict
+
+from zarr_metadata import ValidationProblem
+from zarr_metadata.definition import Nested
+from zarr_metadata.v3.definition import CORE_AND_EXTENSIONS_CONTEXT, CodecDefinition, ZarrV3Context
+
+
+class AcmeLz4Configuration(TypedDict, closed=True):
+    acceleration: Annotated[int, Ge(1)]
+    dictionary: NotRequired[str]
+    dictionary_size: NotRequired[Annotated[int, Ge(1)]]
+
+
+def acme_lz4_rules(
+    configuration: AcmeLz4Configuration, nested: Nested
+) -> Iterator[ValidationProblem]:
+    if "dictionary" in configuration and "dictionary_size" not in configuration:
+        yield ValidationProblem(
+            ("dictionary_size",), "a dictionary needs its size", "missing_key"
+        )
+
+
+ACME_LZ4 = CodecDefinition(
+    name="acme.lz4",
+    configuration=AcmeLz4Configuration,
+    kind="bytes_bytes",
+    size="dynamic",
+    rules=acme_lz4_rules,
+)
+CONTEXT = CORE_AND_EXTENSIONS_CONTEXT.union(ZarrV3Context(codecs=[ACME_LZ4]))
+```
+
+Pass `context=CONTEXT` to any reader or model constructor. A document that
+names `acme.lz4` is then checked against this definition.
+
+## Rules for the pieces
+
+**The `TypedDict`**
+
+- It must be a `typing_extensions.TypedDict`.
+- It must say how undeclared keys are handled: `closed=True`,
+  `extra_items=`, or `closed=False`. An open-by-default `TypedDict` is
+  refused, because it would accept a misspelled key silently.
+
+**Its members** must be JSON shapes:
+
+- `int`, `float`, `bool`, `str`, `None` or `JSONValue`,
+- a `Literal`,
+- `tuple[T, ...]` or `tuple[T1, T2]`,
+- a union,
+- a `TypedDict` or `Mapping[str, V]`,
+- a `NewType` or a type alias.
+
+A number may carry bounds from annotated-types: `Gt`, `Ge`, `Lt`, `Le` or
+`Interval`. Any other `Annotated` metadata is refused when the definition
+is built.
+
+**The rules function**
+
+- It runs only on a configuration within its bounds, so it can rely on
+  them.
+- It reports the location of each problem. The value there becomes the
+  problem's `input`.
+- Show values in messages with `zarr_metadata.problems.shown`. Then they
+  read like the package's own messages.
+
+**Pickling.** Define each function at module top level. A model holds the
+definitions that read it, so the model can be pickled only if they can.
+
+## Other kinds of definition
+
+Other kinds declare more:
+
+- A data type declares its fill value (`fill_value`, `fill_value_rules`,
+  `fill_value_canonical`). It also declares how its values are stored
+  (`storage`).
+- A chunk grid declares which shapes it fits (`shape_rules`) and its chunk
+  lengths (`chunk_lengths`).
+- A codec declares:
+    - what it checks about the chunk it receives (`chunk_rules`),
+    - what it hands on (`transition`),
+    - any pipelines it contains (`pipelines`).
+
+The [`zarr_metadata.v3.definition`](api/v3/definition.md) docstring
+describes each of these.
diff --git a/packages/zarr-metadata/docs/index.md b/packages/zarr-metadata/docs/index.md
index b139dfd307..da545079e3 100644
--- a/packages/zarr-metadata/docs/index.md
+++ b/packages/zarr-metadata/docs/index.md
@@ -1,411 +1,92 @@
 # zarr-metadata
 
-Basic tools for modelling Zarr metadata, with minimal dependencies.
+Types, models and validators for Zarr metadata documents, with minimal
+dependencies.
 
 `zarr-metadata` is developed in the
 [zarr-python repository](https://github.com/zarr-developers/zarr-python/tree/main/packages/zarr-metadata)
-and released independently of `zarr` itself. Install it with:
+and released independently of `zarr`. Install it with:
 
 ```
 pip install zarr-metadata
 ```
 
-## Who needs this
-
-This library supports software that interacts with Zarr metadata documents.
-
 ## What this is
 
-This is *not* a full Zarr implementation. It's a collection of data structures and routines that
-closely model the content of the Zarr specifications, such as:
-
-- **Typed JSON shapes** ([`zarr_metadata.v2`](api/v2.md) and
-  [`zarr_metadata.v3`](api/v3/index.md)): `TypedDict` definitions and
-  `Literal` aliases for the JSON documents specified by the
-  [Zarr v2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html) and
-  [Zarr v3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html)
-  specifications, plus types for
-  [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/) and a
-  few widely-used-but-unspecified entities (e.g. consolidated metadata).
-- **Document models** ([`zarr_metadata.model`](api/model.md)): immutable
-  models of whole metadata documents, each one a document and the scope
-  it was read in, with readers that report every problem at its
-  location, and store-key (de)serialization. A document
-  produced by `to_json` shares no mutable state with the model that produced
-  it.
-- **Definitions and scopes** ([`zarr_metadata.definition`](api/definition.md),
-  with each format's kinds in `zarr_metadata.v3.definition` and
-  `zarr_metadata.v2.definition`): each extension's configuration as a
-  `TypedDict` with its rules, and the scope that decides which definitions
-  read a document. `zarr_metadata.v3` and `zarr_metadata.v2` export every
-  definition and scope of their format, such as `BYTES_CODEC` and
-  `CORE_AND_EXTENSIONS_CONTEXT`.
-- **JSON type checking** ([`zarr_metadata.typed_json`](api/typed_json.md)):
-  `check` checks a JSON value against any `TypedDict` and reports every
-  problem with its location.
-- **Problems** ([`zarr_metadata.problems`](api/problems.md)): the problem
-  values every reader returns, and the error that carries them.
-- **JSON Schema** ([`zarr_metadata.json_schema`](api/json_schema.md)): the
-  JSON Schema of a `TypedDict`, a v3 declaration, or a whole `zarr.json`.
-- **Optional Pydantic integration** ([`zarr_metadata.pydantic`](api/pydantic.md),
-  requires Pydantic 2.13 or newer): each model as a Pydantic field type that
-  validates raw documents through the same strict parser.
-
-## What this is for
-
-- **Static Type Checking** The public `TypedDict` definitions describe the static JSON shape of Zarr
-  metadata.
-
-- **Dynamic JSON validation** For strict, location-aware validation of JSON loaded from disk, use the
-  model parser:
-
-  ```python test="true" session="index"
-  import json
-  from zarr_metadata.model import ZarrV3ArrayMetadata
-
-  with open("zarr.json", "rb") as f:
-      raw = json.load(f)
-
-  metadata = ZarrV3ArrayMetadata.from_json(raw)
-  ```
-
-  The optional Pydantic integration delegates raw input to the same strict
-  parser and returns the same normalized model class:
-
-  ```python test="true" session="index"
-  from pydantic import TypeAdapter
-  import zarr_metadata.pydantic as zmp
-
-  adapter: TypeAdapter[zmp.ZarrV3ArrayMetadataField] = TypeAdapter(zmp.ZarrV3ArrayMetadataField)
-  metadata = adapter.validate_python(raw)
-  encoded = metadata.to_key_value()["zarr.json"]
-  ```
-
-  A field annotated `Annotated[ZarrV3ArrayMetadata, zmp.InScope(CONTEXT)]`
-  is read in `CONTEXT`, whatever the validation context holds, and a model
-  instance given to it is read again in `CONTEXT`.
-
-  Note that a bare `TypeAdapter` over a public `TypedDict` is a **coercive** shape
-  adapter, not a Zarr conformance validator; it may coerce values or discard
-  members that the strict model parser rejects. This is better suited for handling input provided
-  from Python objects (e.g., user-authored dicts) than JSON.
-
-## Validation boundary
-
-The readers and model constructors enforce the declared document structure and a small set
-of context-free consistency rules, e.g.:
-- fixed format literals,
-- finite JSON numbers outside `attributes` and the members nothing in scope reads
-- non-negative dimensions
-- one `dimension_names` entry per array dimension.
-
-In a v3 document, validation also checks each extension point: the data
-type, the chunk grid, the chunk key encoding, each codec, and each storage
-transformer. Each one is checked by the definition that claims its name in
-a scope. The scope is `CORE_AND_EXTENSIONS_CONTEXT` unless a `context` is passed.
-`ZARR_PYTHON_CONTEXT` adds the data types that zarr-python writes but no
-specification registers.
-If the definition rejects a configuration, the reader rejects it too,
-and a configuration key the definition does not declare is reported as
-`unknown_key`. If no definition in the scope claims a name, the reader
-does not check that extension point, and the consumer decides whether to
-support it.
-
-Making the context and explicit part of metadata parsing allows different libraries, which might support different
-sets of Zarr features, to formally represent exactly the codecs, data types, etc they support when
-parsing metadata.
-
-Some checks relate one part of a v3 document to another:
-
-- The fill value is checked against the data type the document names, by
-  that data type's definition.
-- The chunk grid is checked against the shape, by the grid's definition.
-- The codecs are checked as a pipeline. In order, each codec's definition
-  checks the codec against the chunk it receives. This includes a shard's
-  inner codecs and index codecs.
-
-The readers do no arithmetic on values. For example, they do not check
-whether a fill value survives a `cast_value` round trip.
-
-Some choices that the spec text leaves open, or answers in two ways:
+A collection of data structures and routines that closely model the
+metadata rules in the [Zarr v2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html)
+and [Zarr v3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html)
+specifications and in [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/):
 
-- **`attributes` may hold `NaN`, `Infinity` and `-Infinity`.** The spec
-  does not interpret attributes, and zarr-python and xarray write these
-  numbers there (for example, a CF `_FillValue`). The models read them,
-  and `to_key_value` writes them back as bare tokens, which a strict JSON
-  parser rejects. So may a member the spec does not define when no
-  definition in scope claims it: nothing reads it, so it is kept as
-  written. `check`, from `zarr_metadata.typed_json`, rejects a non-finite
-  number anywhere, including in attributes.
-- **A reader walks at most 256 levels of nesting.** A value nested deeper
-  is an `invalid_value` problem at the first level past the limit,
-  wherever it is. Every reader, writer and comparison uses one stack
-  frame per level, and `copy.deepcopy` (and `pickle` before Python 3.12)
-  uses two. A document at the limit therefore uses about half of the
-  interpreter's default recursion limit, and the rest is left for the
-  caller.
-- **`consolidated_metadata: null` is a problem.** A zarr-python 3.0.x bug
-  wrote it. The spec requires an object, and the package accepts only an
-  object. A reader of those stores removes the key before reading.
-- **An extension name must follow the spec's naming rule**,
-  `^[a-z][a-z0-9-_.]+$`, or be a URI, which earlier versions of the spec
-  required. Any other name is rejected before any definition is
-  consulted, so `""` and `"foo/bar"` are problems, not unknown extensions.
-- **`must_understand: false` is rejected at every extension point**,
-  including codecs and storage transformers, although the core spec names
-  only the data type, chunk grid and chunk key encoding. A reader that
-  skips a codec reads wrong bytes, just as a reader that skips a data type
-  reads wrong values. On an unknown top-level member, `must_understand`
-  keeps its meaning: a reader can skip that member.
-- **A v2 datetime or timedelta dtype must have a unit**, as in `<M8[ns]`,
-  because the v2 spec requires the unit in brackets. zarr-python 3 writes
-  `<M8` or `<m8` for a NumPy `datetime64` or `timedelta64` with no unit,
-  and the package refuses those dtypes. A codec's dtype parameter, such as
-  the `dtype` of a `delta` filter, may leave out the unit, because
-  numcodecs writes it that way and runs it.
-- **A v2 codec's dtype parameter is checked against the core v2 data
-  types**, whatever scope the array is read in, because numcodecs reads
-  the parameter with NumPy. So a scope that widens a data type, for
-  example to read `<f16`, does not widen what a codec's dtype parameter
-  may be.
+- **Typed JSON shapes**: `TypedDict` definitions for every document and
+  configuration, for static type checking at the boundary of a Zarr
+  application.
+- **Document models**: immutable models of whole documents, with readers
+  that report every problem at its location in the document.
+- **Contexts**: a model is a document read in a **context**. A context
+  is a collection of definitions for codecs, data types, chunk grids and so
+  on. Not every Zarr implementation supports the same features. A context
+  makes a program say exactly which features it reads.
 
-A v3 `regular` chunk grid's chunk lengths must be at least 1, even along a
-dimension of length 0. The regular grid spec says "Chunk sizes must be
-greater than zero". The core spec's wording, "non-zero when the
-corresponding dimensions of the arrays have non-zero length", requires
-less, but does not explicitly allow anything more. So a document with a
-chunk length of 0, which zarr-python 3.0 and 3.1 wrote for an empty
-dimension, is rejected.
+This is *not* a full Zarr implementation. Nothing here reads or writes
+chunks, encodes or decodes data, or performs store I/O.
 
-The readers are strict, so a document that a known writer bug made
-invalid has problems. The repair readers in `zarr_metadata.model`
-(`read_repaired_node_metadata_v3`, `read_repaired_node_metadata_v2` and
-`read_repaired_consolidated_metadata_v2`) undo these bugs first, then
-read the result strictly, and return each change they made as a `Repair`:
-
-- A chunk length of 0 in a v3 `regular` chunk grid, along an empty
-  dimension, which zarr-python 3.0 and 3.1 wrote, is written as 1.
-- `consolidated_metadata: null` on a v3 group, which zarr-python 3.0 and
-  3.1 wrote, is removed.
-- The `consolidated_metadata` member that zarr-python 3 writes into each
-  `.zgroup` entry of a `.zmetadata` below the root is removed.
-- A non-finite v2 fill value that zarr-python 3.0.0 to 3.0.6 wrote as a
-  bare `NaN`, `Infinity` or `-Infinity` is written as the string the v2
-  spec uses, such as `"NaN"`.
-- A non-finite float or complex fill value in a v3 group's consolidated
-  metadata, which zarr-python 3.0.0 to 3.0.6 wrote as a bare token, is
-  written as the string the v3 spec uses, such as `"NaN"`.
-
-The repair readers do not undo these known writer bugs, so a document
-with one of them is refused:
-
-- zarr-python 3.0.7 to 3.0.10 wrote the fill value of an `S` or `V`
-  array in a `.zmetadata` entry as a JSON array of byte values. The
-  array's own `.zarray` file holds the base64 string that the package
-  reads.
-- zarr-python 3.0.7 and 3.0.8 wrote the fill value of a v2 datetime
-  array as an ISO 8601 string, not as a count of ticks.
-- zarr-python 3.0 and 3.1 wrote a chunk length of 0 in a v3 `regular`
-  chunk grid along a dimension that is not empty, for an explicit chunk
-  length of 0.
-- Some releases of zarr-python from 3.0 to 3.2 wrote a chunk length of
-  `true` in a v3 `regular` chunk grid for `chunks=True`, and some
-  releases of 3.0 and 3.1 wrote `false` for `chunks=False`.
-
-`read_array_metadata_v3` reads a document once and returns everything the
-read found:
-
-- each declaration as the scope read it: an `AcceptedDeclaration` when a definition
-  claims its name, an `UnclaimedDeclaration` when none does, or a
-  `RefusedDeclaration`, together with the declaration's location and the kind it was
-  read as;
-- each codec, with the chunk it receives;
-- every problem;
-- the model, when there are no problems.
-
-`from_json` returns that model, or raises the problems. A consumer can
-apply its own policy by walking the declarations, without reading anything
-twice. `with_problems` pairs each declaration with its problems: those located
-in the declaration and in the declarations it contains. This matches how zod's
-`flattenError` groups issues. `canonical_of` returns the simplest
-spelling of a declaration that has no problems, without reading it again. For
-example, the code below finds the declarations that go beyond the core spec (a
-declaration with no name is already a problem), and the simplest spelling of
-each declaration:
-
-```python test="true" session="index"
-from zarr_metadata.model import read_array_metadata_v3
-from zarr_metadata.definition import canonical_of, with_problems
-from zarr_metadata.v3.definition import CORE_CONTEXT
-
-reading = read_array_metadata_v3(raw)
-beyond_core = [
-    loc
-    for loc, declaration in reading.declarations()
-    if declaration.name is not None and CORE_CONTEXT.claimant(declaration.read_as, declaration.name) is None
-]
-simplest = {
-    loc: canonical_of(declaration, problems)
-    for loc, declaration, problems in with_problems(reading.declarations(), reading.problems)
-}
-metadata = reading.metadata  # None when reading.problems is not empty
-```
-
-`read_group_metadata_v3` reads a group the same way. It checks the
-envelope of the group's `consolidated_metadata`, and does not read the
-documents the member lists (see below). `read_node_metadata_v3` reads
-a `zarr.json` of either kind as the node type its `node_type` names, the
-same way a discriminated union uses its tag. A document whose `node_type`
-is neither reads as `ZarrV3UnknownNodeMetadataReading`, with the problems.
-Only its `zarr_format` is read, so a document of another format is
-reported as not v3. `node_metadata_from_json_v3` and
-`node_metadata_from_key_value_v3` build the model of either kind, the same
-way the models' own `from_json` and `from_key_value` build one.
-
-Consolidated metadata holds the hierarchy below its group, with the group
-as the root. The document of the node at `/a/b` is stored under the key
-`a/b`. The documents and the group must form a tree: only groups have
-child nodes, and the parent of every node is present.
-`ZarrV3ConsolidatedMetadata` checks this when it reads the documents. `NodeName` and
-`NodePath`, in `zarr_metadata.v3`, are the types of strings that satisfy
-the spec's rules for node names and paths. They are modeled on the zarrs
-types with the same names. `validate_node_name_v3`, `is_node_name_v3` and
-`parse_node_name_v3`, and the matching `node_path` functions, check a
-string against those rules.
-
-A top-level member that the spec does not define is an extra field. A
-scope can hold a definition for one, by its key, in the
-`array_extra_fields` or `group_extra_fields` slot of `ZarrV3Context`. A
-member whose key a definition claims is read by that definition: an extra field is a declaration
-written as the member alone, `{key: value}`. Any other extra field is kept as
-written, as an `UnclaimedDeclaration`.
-The scope is what a reader recognizes, so the model's
-`must_understand_fields` lists each unclaimed member that does not say
-`"must_understand": false`: the spec requires a reader to fail to open a
-node with any such member. It covers extra fields only. A data type, chunk
-grid, chunk key encoding, codec or storage transformer that nothing in
-scope claims is an `UnclaimedDeclaration` too, also when it sits inside another
-declaration, such as a codec inside a shard. A model's `unclaimed_declarations` lists
-every declaration nothing in scope claims, at any depth, by its location, and
-leaves out the members that waive `must_understand`: a reader can open
-the node when it is empty. `CORE_CONTEXT` holds
-`CONSOLIDATED_METADATA_EXTRA_FIELD`, which reads a group's
-`consolidated_metadata` as the envelope the spec fixes. A group's
-`consolidated()` reads the documents that member lists, in the group's
-own scope.
-
-A v3 model consists of its document and the scope it was read in.
-`ZarrV3ArrayMetadata(document, context=None)` reads the document in the
-scope (`CORE_AND_EXTENSIONS_CONTEXT` when none is given) and raises
-`MetadataValidationError` with every problem, so an invalid model is never
-built. `to_json` returns the document as it was written, and
-`to_key_value` writes that same document to store bytes.
-
-Every typed attribute is a view of that read: each declaration as the scope read
-it (an `AcceptedDeclaration` or an `UnclaimedDeclaration`), and `shape`, `attributes`
-and the members that hold no declaration as the read refined them. These views are read-only
-at every level: a list in the document is shown as a tuple, and an object
-as a read-only mapping. `to_json` returns plain containers.
-
-To change a model, call `update`. It replaces members of the document with
-the given JSON members and reads the result in the model's own scope, so
-you do not pass the scope again. A member the spec defines is given by its
-name, and any other member in `extra_fields`, a mapping from its key to its
-value, or to `UNSET` to remove it. A name `update` does not take raises
-`TypeError`, so a misspelled member is never written. `with_context` reads the document in
-another scope. `refined_in` also reads the document in another scope, but
-only one that claims what this scope left unclaimed and contradicts
-nothing; otherwise it raises `ScopeConflictError`.
-
-A group does not read the documents its `consolidated_metadata` lists.
-Consolidated metadata is a convention of the reference implementation,
-not core metadata, so a group holds the member as written, after it
-checks the envelope that the core spec fixes. A reader can use the
-member as a source of child documents in place of the store: read one
-document with `read_node_metadata_v3` when that node is opened, or read
-all of them with `ZarrV3ConsolidatedMetadata`, or with
-`read_consolidated_metadata_v3`, which returns problems instead of
-raising them. A document with a problem then fails only when it is read.
-Pass `context=group.context` to read the documents in the group's own
-scope; with no `context`, they are read in `CORE_AND_EXTENSIONS_CONTEXT`.
-
-To write consolidated metadata, build a `ZarrV3ConsolidatedMetadata` and
-pass it to the group's `update`. The group reads the listed models in its
-own scope, refuses one that its scope reads differently, and writes the
-document. The model reads every document strictly, and also accepts node
-models as entries. Such an entry is accepted when its claims refine into
-the model's scope, and refused at its path otherwise. To consolidate
-children that were read in several scopes, consolidate them in the
-`union` of those scopes. Every reader takes `context=None` for the
-default scope, `CORE_AND_EXTENSIONS_CONTEXT`.
-
-Two models are equal when they represent the same document, even if each
-is spelled differently. Values the package interprets (each declaration, and the
-fill value against its data type) are compared by their canonical
-spelling, as returned by `canonical_of` and `canonical_fill_value`. For
-example, `"NaN"` and `"0x7fc00000"` are the same `float32` fill value,
-`0.0` and `-0.0` are two different fill values, and a v3 blosc codec
-under `noshuffle`, which ignores `typesize`, is the same codec with or
-without one. A v2
-document's dtype, codecs and fill value are compared the same way: `<b1`
-and `|b1` are one dtype, in `dtype` and in a codec's dtype parameter
-alike, and a v2 codec that leaves out a parameter is
-the same as one that writes the numcodecs default, so
-`{"id": "zstd", "level": 0}` equals
-`{"id": "zstd", "level": 0, "checksum": false}`. A v2 blosc `typesize`
-is kept whatever the `shuffle`, unlike in v3: v2 codecs are defined by
-numcodecs, which writes it into each chunk's header, so two v2 blosc
-codecs that differ only in it encode different bytes, though they decode
-the same data. The v3 spec defines its blosc codec, and says `noshuffle`
-ignores `typesize`. A v2 node with no `.zattrs` equals one with an
-empty `.zattrs`, as a v3 document with and without an empty
-`attributes` are equal. Values the package does
-not interpret (attributes, extra fields, and the configuration of a declaration
-that nothing in the scope claims) are compared as JSON text. JSON text
-distinguishes `true` from `1` and `-0.0` from `0.0`, and treats `NaN` as
-equal to itself. Equal models have equal hashes, but may write different
-documents, because `to_json` writes each document as it was given. A
-model holds nothing that can be changed in place.
-
-`node_metadata_json_schema_v3` writes the rules the readers apply as a
-JSON Schema (draft 2020-12). Use it in an editor that checks a `zarr.json`
-while you write it, or with a validator in another language. Each
-extension point is described as a declaration as its scope reads it: a claimed
-configuration follows its definition's TypedDict, including bounds, and a
-name that nothing in the scope claims may have any configuration. The fill
-value must be a valid fill value for the data type the document names.
-`declaration_json_schema_v3(kind, *, context=None)` writes the schema of one declaration, and
-`json_schema` writes the schema of any TypedDict as `check` reads it. All
-three are in `zarr_metadata.json_schema`. A schema describes each member on its own, not the rules that
-relate members to each other, so a document the schema accepts may still
-have a problem. Every JSON document the readers accept, the schema also
-accepts. A schema validator reads JSON as a parser produces it, with
-arrays as lists. A model's `to_json` returns tuples, which a Python
-validator does not accept as arrays.
+Reading a `zarr.json` from disk looks like this:
 
 ```python test="true" session="index"
 import json
-from zarr_metadata.json_schema import node_metadata_json_schema_v3
+from zarr_metadata import ZarrV3ArrayMetadata
 
-with open("zarr.schema.json", "w") as f:
-    json.dump(node_metadata_json_schema_v3(), f, indent=2)
-```
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
 
-## Scope
+metadata = ZarrV3ArrayMetadata.from_json(raw)
+```
 
-At minimum, this library supports what Zarr-Python needs: the complete
-Zarr v2 and v3 specs, consolidated metadata, and a subset of the metadata
-defined in `zarr-extensions`. We are generally open to contributions that
-add types, models, or validation for Zarr metadata with a
-published spec.
+`from_json` returns the model, or raises `MetadataValidationError` with
+every problem it found.
+
+## Where to go next
+
+- **You want type hints for Zarr JSON.** The `TypedDict`s are in
+  [`zarr_metadata.v3`](api/v3/index.md) and [`zarr_metadata.v2`](api/v2.md).
+  `check` in [`zarr_metadata.typed_json`](api/typed_json.md) turns any of
+  them into a runtime check.
+- **You validate metadata you did not write.** Start with
+  [Parsing and validation](parsing-validation.md). It says what the readers
+  check and why. Then read [Models and readers](models.md) for the API.
+  [What the readers check](validation-rules.md) lists the rules and the
+  decisions made where the spec is silent.
+- **You support codecs or data types this package does not know.** Read
+  [Context](context.md), then [Writing an extension](extensions.md).
+- **You read stores written by older versions of zarr-python.** See
+  [Repairing known writer bugs](repair.md).
+- **You work with hierarchies.** See
+  [Consolidated metadata](consolidated-metadata.md).
+- **You build tools around the metadata.** [JSON Schema](json-schema.md)
+  writes the readers' rules for an editor or another language.
+  [Pydantic](pydantic.md) wraps each model as a field type.
+- **You want the module-by-module view.** The [API reference](api/index.md)
+  describes each module, and the module docstrings are the detailed guide.
+
+## What the library covers
+
+At minimum, this library supports what zarr-python needs:
+
+- the complete Zarr v2 and v3 specs,
+- consolidated metadata,
+- a subset of the metadata defined in zarr-extensions.
+ We are generally open to contributions that
+add types, models, or validation for Zarr metadata with a published spec.
+
+The models begin and end at the metadata documents themselves.
+`from_key_value` and `to_key_value` map documents to store keys and bytes.
+Everything past that belongs to consumer libraries. That includes resolving
+a codec or data type name to an implementation.
+
+This boundary limits how far some codec combinations can be validated. For example,
+the readers cannot check that a `cast_value` codec maps scalars one to one.
 
-Runtime array behavior is out of scope: nothing here encodes or decodes
-chunks, resolves codec or data type names to implementations, or performs
-store I/O. The models begin and end at the metadata documents themselves —
-`from_key_value` / `to_key_value` map documents to store keys and bytes,
-and everything past that belongs to consumer libraries. The "no encoding / decoding" rule does constrain
-how extensively we can validate certain codec combinations. For example, we cannot check that the `cast_value`
-codec bijectively maps scalars.
 ## Reference
 
 - [API reference](api/index.md)
diff --git a/packages/zarr-metadata/docs/json-schema.md b/packages/zarr-metadata/docs/json-schema.md
new file mode 100644
index 0000000000..4a4af875f7
--- /dev/null
+++ b/packages/zarr-metadata/docs/json-schema.md
@@ -0,0 +1,42 @@
+# JSON Schema
+
+`zarr_metadata.json_schema` writes the rules the readers apply as JSON
+Schema (draft 2020-12). Use it in two ways:
+
+- in an editor that checks a `zarr.json` while you write it,
+- with a validator in another language.
+
+The module has three functions:
+
+- `node_metadata_json_schema_v3(context=None)` writes the schema of a whole
+  v3 `zarr.json`, array or group.
+- `declaration_json_schema_v3(kind, *, context=None)` writes the schema of
+  one declaration read as `kind`.
+- `json_schema(typed_dict)` writes the schema of any of the package's
+  `TypedDict`s, as `check` from `zarr_metadata.typed_json` reads it.
+
+The schema describes each extension point as its context reads it:
+
+- A claimed configuration follows its definition's TypedDict, including
+  bounds.
+- A name that nothing in the context claims may have any configuration.
+- The fill value must be valid for the data type the document names.
+
+## Limits
+
+- A schema describes each member on its own. It does not describe the rules
+  that relate members to each other. So a document the schema accepts may
+  still have a problem.
+- The reverse holds: every JSON document the readers accept, the schema
+  also accepts.
+- A schema validator reads JSON as a parser produces it, with arrays as
+  lists. A model's `to_json` returns tuples, and a Python validator does
+  not accept a tuple as an array.
+
+```python test="true" session="json-schema"
+import json
+from zarr_metadata.json_schema import node_metadata_json_schema_v3
+
+with open("zarr.schema.json", "w") as f:
+    json.dump(node_metadata_json_schema_v3(), f, indent=2)
+```
diff --git a/packages/zarr-metadata/docs/models.md b/packages/zarr-metadata/docs/models.md
new file mode 100644
index 0000000000..713dd2fe21
--- /dev/null
+++ b/packages/zarr-metadata/docs/models.md
@@ -0,0 +1,220 @@
+# Models and readers
+
+A model is a metadata document plus the context it was read in. This page
+covers:
+
+- how a document becomes a model,
+- what a model exposes,
+- how to change a model,
+- when two models are equal.
+
+The [Context](context.md) page explains why the context is part of the
+model. This page is about using it.
+
+## Readers and readings
+
+Every document type has a reader in `zarr_metadata.model`. A reader does
+one read and returns a **reading**. A reading holds everything the read
+found, as values. Nothing is raised.
+
+`read_array_metadata_v3` returns:
+
+- Each declaration as the context read it, with its location and the kind
+  it was read as. The declaration is one of:
+    - an `AcceptedDeclaration`, when a definition claims its name;
+    - an `UnclaimedDeclaration`, when no definition does;
+    - a `RefusedDeclaration`, when a definition claims it but finds problems.
+- Each codec, with the chunk it receives.
+- Every problem.
+- The model, when there are no problems.
+
+The model's `from_json` returns that model, or raises
+`MetadataValidationError` with the same problems.
+
+A consumer can walk the declarations to apply its own policy. Nothing is
+read twice. Two helpers support this:
+
+- `with_problems` pairs each declaration with its problems. These are the
+  problems located in the declaration and in the declarations it contains.
+  This matches how zod's `flattenError` groups issues.
+- `canonical_of` returns the simplest spelling of a declaration that has no
+  problems. It does not read the declaration again.
+
+The code below finds the declarations that go beyond the core spec. (A
+declaration with no name is already a problem.) It also finds the simplest
+spelling of each declaration.
+
+```python test="true" session="models"
+import json
+from zarr_metadata.model import read_array_metadata_v3
+from zarr_metadata.definition import canonical_of, with_problems
+from zarr_metadata.v3.definition import CORE_CONTEXT
+
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
+
+reading = read_array_metadata_v3(raw)
+beyond_core = [
+    loc
+    for loc, declaration in reading.declarations()
+    if declaration.name is not None and CORE_CONTEXT.claimant(declaration.read_as, declaration.name) is None
+]
+simplest = {
+    loc: canonical_of(declaration, problems)
+    for loc, declaration, problems in with_problems(reading.declarations(), reading.problems)
+}
+metadata = reading.metadata  # None when reading.problems is not empty
+```
+
+The other v3 readers work the same way:
+
+- `read_group_metadata_v3` reads a group. It checks the envelope of the
+  group's `consolidated_metadata`. It does not read the documents that
+  member lists. See [Consolidated metadata](consolidated-metadata.md).
+- `read_node_metadata_v3` reads a `zarr.json` of either kind. It picks the
+  kind from the document's
+  [`node_type`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#node-type),
+  the way a discriminated union uses its tag. If `node_type` names neither
+  kind, the result is a `ZarrV3UnknownNodeMetadataReading` with the
+  problems. Only `zarr_format` is read in that case, so a document of
+  another format is reported as not v3.
+- `node_metadata_from_json_v3` and `node_metadata_from_key_value_v3` build
+  the model of either kind. They work like the models' own `from_json` and
+  `from_key_value`.
+
+Every reader takes `context=None`. The default context is
+`CORE_AND_EXTENSIONS_CONTEXT`.
+
+## A model is a document read in a context
+
+`ZarrV3ArrayMetadata(document, context=None)` reads the document in the
+context. With no context, it uses `CORE_AND_EXTENSIONS_CONTEXT`. If the
+read finds problems, it raises `MetadataValidationError` with all of them.
+An invalid model is never built.
+
+- `to_json` returns the document as it was written.
+- `to_key_value` writes that same document to store bytes.
+
+Every typed attribute is a view of the read:
+
+- Each declaration appears as the context read it: an
+  `AcceptedDeclaration` or an `UnclaimedDeclaration`.
+- `shape`, `attributes` and the other members that hold no declaration
+  appear as the read refined them.
+
+These views are read-only at every level. A list in the document appears
+as a tuple. An object appears as a read-only mapping. `to_json` returns
+plain containers. Nothing in a model can be changed in place.
+
+To change a model, use one of these methods:
+
+- `update` replaces members of the document and reads the result in the
+  model's own context. You do not pass the context again.
+    - Give a member the spec defines by its name.
+    - Give any other member in `extra_fields`. This is a mapping from the
+      member's key to its value, or to `UNSET` to remove it.
+    - A name `update` does not take raises `TypeError`, so a misspelled
+      member is never written.
+- `with_context` reads the document in another context.
+- `refined_in` also reads the document in another context. The new context
+  must claim what this context left unclaimed and contradict nothing.
+  Otherwise it raises `ScopeConflictError`.
+
+## Extra fields
+
+An extra field is a top-level member that the spec does not define. The
+core spec hands such members to its
+[extension rules](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#unknown).
+
+A context can hold a definition for an extra field, filed by its key. The
+definition goes in the `array_extra_fields` or `group_extra_fields` slot of
+`ZarrV3Context`.
+
+- If a definition claims the key, it reads the member. The declaration is
+  the member alone, `{key: value}`.
+- Otherwise the member is kept as written, as an `UnclaimedDeclaration`.
+
+The spec calls these members
+[additional fields](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#additional-fields).
+The names `extra_fields`, `ExtraFieldDefinition` and
+`must_understand_fields` follow it. That heading comes from
+[PR 373](https://github.com/zarr-developers/zarr-specs/pull/373). It
+renamed the section that v3.1.0 calls
+[Unknown](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#unknown).
+As of v3.1.0, no tagged release has the new heading. So the link points at
+the latest spec. Pin it once a release has the heading.
+
+Elsewhere, this package uses these words:
+
+- *member*: a name/value pair of a JSON object.
+- *declaration*: the value at an extension point.
+- *field*: a field of a Python class, such as a dataclass or a pydantic
+  model. Following the spec and NumPy, it also means a part of a structured
+  data type (`StructField`).
+
+A model has two lists of what its context does not recognize:
+
+- `must_understand_fields` lists each unclaimed extra field that does not
+  say `"must_understand": false`. The spec
+  [requires](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#must-understand)
+  a reader to fail to open a node with any such member. This list covers
+  extra fields only.
+- `unclaimed_declarations` lists every declaration that nothing in the
+  context claims, by its location. It covers every kind: data type, chunk
+  grid, chunk key encoding, codec, storage transformer and extra field. It
+  looks at any depth, such as a codec inside a shard. It leaves out the
+  members that waive `must_understand`. When it is empty, a reader can open
+  the node.
+
+## Equality
+
+Two models are equal when they represent the same document, even if they
+spell it differently.
+
+Values the package interprets are compared by their canonical spelling.
+These are each declaration, and the fill value read against its data type.
+`canonical_of` and `canonical_fill_value` return that spelling. For example:
+
+- `"NaN"` and `"0x7fc00000"` are the
+  [same `float32` fill value](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/data-types/index.html#permitted-fill-values).
+- `0.0` and `-0.0` are two different fill values.
+- A v3 blosc codec with `noshuffle`
+  [ignores `typesize`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/blosc/index.html#configuration-parameters).
+  So it is the same codec with or without one.
+
+A v2 document's
+[dtype](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#data-type-encoding),
+codecs and fill value are compared the same way:
+
+- `<b1` and `|b1` are one dtype. This holds in `dtype` and in a codec's
+  dtype parameter.
+- A v2 codec that leaves out a parameter equals one that writes the
+  numcodecs default. So `{"id": "zstd", "level": 0}` equals
+  `{"id": "zstd", "level": 0, "checksum": false}`.
+- A v2 blosc `typesize` is always kept, whatever the `shuffle`. This
+  differs from v3. Numcodecs defines the v2 codecs, and it writes
+  `typesize` into each chunk's header. So two v2 blosc codecs that differ
+  only in `typesize` encode different bytes, though they decode the same
+  data. In v3, the
+  [blosc spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/blosc/index.html#configuration-parameters)
+  says `noshuffle` ignores `typesize`.
+- A v2 node with no `.zattrs` equals one with an empty `.zattrs`. The
+  [v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#attributes)
+  says the key "does not have to be present, and if it is absent the
+  attributes should be treated as empty".
+
+In the same way, a v3 document with no `attributes` equals one whose
+`attributes` is empty.
+
+Values the package does not interpret are compared as JSON text. These
+are:
+
+- attributes,
+- extra fields,
+- the configuration of a declaration that nothing in the context claims.
+
+JSON text tells `true` from `1`, and `-0.0` from `0.0`. It treats `NaN` as
+equal to itself.
+
+Equal models have equal hashes. They may still write different documents,
+because `to_json` writes each document as it was given.
diff --git a/packages/zarr-metadata/docs/parsing-validation.md b/packages/zarr-metadata/docs/parsing-validation.md
index e8c111ea93..abdea3c790 100644
--- a/packages/zarr-metadata/docs/parsing-validation.md
+++ b/packages/zarr-metadata/docs/parsing-validation.md
@@ -3,10 +3,9 @@
 ## The problem statement
 
 Suppose your program opens a Zarr array written by a stranger. You want to decode some of the chunks of
-the array. For this to work, your program must transform its representation of the array metadata document from a raw blob of UTF-8-encoded bytes to a schema for an array and its chunks.
+the array. For this to work, your program must transform the array metadata document. It starts as a raw blob of UTF-8-encoded bytes. It must end as a schema for an array and its chunks.
 
-We can break this process down into stages, where each stage introduces more elaborate **context** for parsing
-the metadata, and consequently introduces more elaborate problems that can be discovered. We will walk through
+We can break this process down into stages. Each stage brings in more **context** for parsing the metadata. So each stage can discover more kinds of problems. We will walk through
 these stages here, using Zarr V3 array metadata as the example. Group metadata and Zarr V2 metadata are not covered here.
 
 !!! note
@@ -25,52 +24,66 @@ This procedure yields one of two values:
 
 ### JSON document shape
 
-At this stage we check that the document is a JSON object with per-field structure consistent with rules in the Zarr V3 spec.
+At this stage we check that the document is a JSON object with per-member structure consistent with rules in the Zarr V3 spec.
 
-After confirming that the object named `zarr.json` is indeed valid JSON, we now need to check that the structure of this object is consistent with the rules in the Zarr V3 spec, namely the rules about the [structure of array metadata](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#array-metadata).
+We have confirmed that the object named `zarr.json` is valid JSON. Now we check that its structure follows the Zarr V3 spec's rules about the [structure of array metadata](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#array-metadata).
 
 At this stage we need to ensure that:
 
-- every **required** field is present
-- every **required** and **optional** field has the correct shape
+- every **required** member is present
+- every **required** and **optional** member has the correct shape
 
-The correct shape varies per field. The Zarr V3 spec defines a **generic metadata element type** that is reused for data types, codecs, etc. Inhabitants of that type are:
+The correct shape varies per member. The Zarr V3 spec defines a [**generic metadata element type**](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#extension-definition) that is reused for data types, codecs, etc. Inhabitants of that type are:
 
 - strings
-- JSON objects with a `"name"` field and optionally `"configuration"` and `"must_understand"` fields
+- JSON objects with a `"name"` member and optionally `"configuration"` and `"must_understand"` members
 
-The `data_type` field must comply with this shape. The `codecs` field must be a non-empty JSON array of values that comply with this shape.
+The `data_type` member must comply with this shape. The `codecs` member must be a non-empty JSON array of values that comply with this shape.
 
-The spec does not define a shape for **extra** fields. Instead, the [relevant section of the spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#unknown) says that a reader must refuse to open an array with an extra field, unless that field is a JSON object with `"must_understand": false`. Like an unknown name, which we will see later, an extra field is not a problem with the document. It's a field that some readers can't use. So at this stage we don't check extra fields; we just note which of them a reader must understand.
+The spec does not define a shape for **extra** fields. Instead, the [relevant section of the spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#unknown) says that a reader must refuse to open an array with an extra field. The exception is a field that is a JSON object with [`"must_understand": false`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#must-understand). Like an unknown name, which we will see later, an extra field is not a problem with the document. It's a field that some readers can't use. So at this stage we don't check extra fields; we just note which of them a reader must understand.
 
 !!! note
-    At this stage we don't need to know **which** data type, or chunk grid, or codecs, are declared in the metadata document. We are only looking at **how** those fields are declared. We will resolve the raw JSON to a specific data type, chunk grid, etc. in a later validation pass.
+    At this stage we don't need to know **which** data type, or chunk grid, or codecs, are declared in the metadata document. We are only looking at **how** those members are declared. We will resolve the raw JSON to a specific data type, chunk grid, etc. in a later validation pass.
 
 This procedure yields one of two values:
 
 1. A JSON object that adheres to the required shape
-2. An enumeration of localized problems, like "`/data_type`: invalid type" or "`/codecs`: missing key", or "`/codecs/0`: invalid type". The latter example refers to the first element of the `codecs` array using [JSON pointer syntax](https://www.rfc-editor.org/info/rfc6901/). Localizing problems to a **position** in the document is important to ensure that an interested user or a repair routine can diagnose and fix that problem.
+2. An enumeration of localized problems, like "`/data_type`: invalid type" or "`/codecs`: missing key", or "`/codecs/0`: invalid type". The latter example refers to the first element of the `codecs` array using [JSON pointer syntax](https://www.rfc-editor.org/info/rfc6901/). Each problem is localized to a **position** in the document. That lets a user or a repair routine diagnose and fix it.
 
-For a program that repairs broken `zarr.json` documents, the list of problems is a useful return value. It informs a repair procedure (if one is possible). But a program that ultimately decodes chunks of the array must only accept the shape-compliant JSON object, and subject it to the next stage of validation.
+For a program that repairs broken `zarr.json` documents, the list of problems is a useful return value. It informs a repair procedure (if one is possible). But a program that decodes chunks of the array must accept only the shape-compliant JSON object. It then passes that object to the next stage of validation.
 
 ### Context-free consistency checks
 
-At this stage we check if correlated fields in the document are consistent.
+At this stage we check if correlated members in the document are consistent.
 
-Some of the fields in the array metadata document are semantically coupled in a way that can be directly checked at the structural level. As of this writing, the only such fields are the `shape` field (a JSON array of non-negative integers), and the `dimension_names` field (an optional JSON array of strings or `null`s).
+Some of the members in the array metadata document are semantically coupled in a way that can be directly checked at the structural level. As of this writing, there are only two such members:
 
-The length of the `shape` field must match the length of the `dimension_names` field, if that field is declared.
+- `shape`, a JSON array of non-negative integers;
+- `dimension_names`, an optional JSON array of strings or `null`s.
+
+The length of the `shape` member must match the length of the `dimension_names` member, if that member is declared.
 
 This procedure yields one of two values:
 
-1. A Zarr-metadata-shaped JSON object with consistent `shape` and `dimension_names` fields
-2. A problem localized to the `dimension_names` field. Strictly speaking, we can't say which of the two fields is wrong. But we treat `shape` as the reference for the number of axes in the array, so the problem goes on the field that disagrees with it. `shape` is required, and other fields like `chunk_grid` depend on it; `dimension_names` is optional, and only names the axes. This metadata has to be repaired; there's no other way to handle it.
+1. A Zarr-metadata-shaped JSON object with consistent `shape` and `dimension_names` members
+2. A problem localized to the `dimension_names` member. Strictly speaking, we can't say which of the two members is wrong. But we treat `shape` as the reference for the number of axes in the array. So the problem goes on the member that disagrees with it. `shape` is required, and other members like `chunk_grid` depend on it; `dimension_names` is optional, and only names the axes. This metadata has to be repaired; there's no other way to handle it.
 
 ### Resolving and validating each declaration
 
-At this stage we check that each metadata object names a known type, given a registry of data types, codec types, etc., and that its configuration is valid for that type.
+At this stage we use a registry of data types, codec types, etc. We check two things for each metadata object:
+
+1. It names a type in the registry.
+2. Its configuration is valid for that type.
+
+We take the JSON given for these members:
+
+- `data_type`,
+- each element of `codecs`,
+- `chunk_grid`,
+- `chunk_key_encoding`,
+- each element of `storage_transformers`.
 
-We take the JSON given for the `data_type`, elements of `codecs`, `chunk_grid`, `chunk_key_encoding`, and `storage_transformers` fields and attempt to **resolve** that JSON into a concrete data type, chunk grid, etc.
+We attempt to **resolve** that JSON into a concrete data type, chunk grid, etc.
 
 In the previous stages, we just had two elements to work with:
 
@@ -79,20 +92,20 @@ In the previous stages, we just had two elements to work with:
 
 This stage introduces a third element to our process: a registry of data types, codecs, chunk grids, etc. We "resolve" anonymous JSON metadata into a data type or codec by finding a type matching that JSON in the registry.
 
-That registry is keyed by string identifiers, which almost all[^1] data types, codecs, etc. present. And the result of this stage is no longer context-free: it depends on the contents of the registry, i.e. which codec, data type, etc. definitions are in scope.
+That registry is keyed by string identifiers, which almost all[^1] data types, codecs, etc. present. The result of this stage is no longer context-free. It depends on the contents of the registry: which codec, data type, etc. definitions are in the context.
 
 For example, the string `"float64"` should resolve to the 64-bit floating point data type with the same name defined in the [Zarr V3 spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/data-types/index.html#core-data-types).
 
-We say "should" because that's what the Zarr V3 spec says about this. There is not a hard requirement that all implementations resolve the string `"float64"` to the 64-bit floating point data type. Someone could write their own (deviant) Zarr implementation that gives the name `"float64"` to a boolean data type. The mapping from JSON identifier (a string) to metadata type (a definition) is held by the registry that entered scope at this stage of validation.
+We say "should" because that's what the Zarr V3 spec says about this. There is not a hard requirement that all implementations resolve the string `"float64"` to the 64-bit floating point data type. Someone could write their own (deviant) Zarr implementation that gives the name `"float64"` to a boolean data type. The registry holds the mapping from JSON identifier (a string) to metadata type (a definition). This stage of validation is where the registry comes in.
 
 For each declaration, we do two steps:
 
 1. **Resolve** the name. We look up the name of the declaration in the registry.
 2. **Validate** the configuration. If we found a match, we must then ensure that the configuration of the JSON value works for the type we resolved.
 
-What if a name isn't in the registry? This is **not** a problem with the document. The document might be perfectly valid, and written by a program with a bigger registry than ours. An unknown name tells us something about our registry, not about the document. So we don't report it as a problem. Instead we mark the declaration as **unknown**, skip the second step, and leave it to the program that reads the document to decide what to do with it. A program that only needs to list the arrays in a hierarchy might be fine with an unknown codec. A program that decodes chunks is not, and it can try again with a more comprehensive registry.
+What if a name isn't in the registry? This is **not** a problem with the document. The document might be perfectly valid, and written by a program with a bigger registry than ours. An unknown name tells us something about our registry, not about the document. So we don't report it as a problem. Instead we mark the declaration as **unknown** and skip the second step. The program that reads the document decides what to do with it. A program that only needs to list the arrays in a hierarchy might be fine with an unknown codec. A program that decodes chunks is not, and it can try again with a more comprehensive registry.
 
-If the name is in the registry, we validate the configuration. Suppose our metadata JSON had the following `chunk_grid` field: `"chunk_grid": {"name": "regular", "configuration": "error"}`. If we resolved the name of the chunk grid (`"regular"`) to the [regular chunk grid](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/chunk-grids/regular-grid/index.html) defined in the core spec, then we must do additional checks on the structure of the `configuration` field before we can interpret this chunk grid. In this case, the spec requires that the `configuration` field be a JSON object with a `chunk_shape` field, which is a JSON array of positive integers. Our `"configuration": "error"` field has the wrong type, so this is a problem localized to `/chunk_grid/configuration`.
+If the name is in the registry, we validate the configuration. Suppose our metadata JSON had the following `chunk_grid` member: `"chunk_grid": {"name": "regular", "configuration": "error"}`. Say we resolved the name `"regular"` to the [regular chunk grid](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/chunk-grids/regular-grid/index.html) defined in the core spec. Before we can interpret this chunk grid, we must check the structure of the `configuration` member. The spec requires `configuration` to be a JSON object with a `chunk_shape` member. `chunk_shape` must be a JSON array of positive integers. Our `"configuration": "error"` member has the wrong type, so this is a problem localized to `/chunk_grid/configuration`.
 
 Validating a configuration might require resolving more declarations. Consider this example:
 
@@ -111,18 +124,18 @@ Validating a configuration might require resolving more declarations. Consider t
 }
 ```
 
-The name `"sharding_indexed"` should resolve to the [codec with the same name](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/sharding-indexed/index.html), and the definition of that codec states that its `codecs` field contains more codec metadata. These JSON array elements go through the same two steps, recursively: `"not_a_codec"` is not in the registry, so it is marked as unknown, not reported as a problem.
+The name `"sharding_indexed"` should resolve to the [codec with the same name](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/sharding-indexed/index.html). That codec's definition says its `codecs` member contains more codec metadata. These JSON array elements go through the same two steps, recursively: `"not_a_codec"` is not in the registry, so it is marked as unknown, not reported as a problem.
 
 Repeating these steps, recursively if necessary, for all metadata objects, we yield one of two values:
 
 1. A Zarr metadata object where each declaration is either unknown, or resolved to a type and internally consistent with the definition of that type
 2. An enumeration of localized validation problems.
 
-### Consistency checks between fields
+### Consistency checks between members
 
 At this stage we check that our resolved metadata is consistent across the entire metadata document.
 
-Here we are in the space of interactions between metadata objects. It's a big space. One key invariant that cuts across many fields is dimensionality, i.e. the number of array axes. The `chunk_grid` and `shape` fields must agree on the dimensionality of the array. That is,
+Here we are in the space of interactions between metadata objects. It's a big space. One key invariant that cuts across many members is dimensionality, i.e. the number of array axes. The `chunk_grid` and `shape` members must agree on the dimensionality of the array. That is,
 
 ```json
 {
@@ -131,22 +144,28 @@ Here we are in the space of interactions between metadata objects. It's a big sp
 }
 ```
 
-is a snippet of an invalid metadata document because the `shape` field applies to an array with three axes while the `chunk_grid` field applies to an array with just one. As with `dimension_names`, `shape` is the reference, so the problem is localized to `/chunk_grid/configuration/chunk_shape`. Dimensionality shows up in codecs too: the `order` of a [`transpose`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/transpose/index.html) codec must name each array axis exactly once.
+is a snippet of an invalid metadata document. The `shape` member describes an array with three axes. The `chunk_grid` member describes an array with just one. As with `dimension_names`, `shape` is the reference, so the problem is localized to `/chunk_grid/configuration/chunk_shape`. Dimensionality shows up in codecs too: the `order` of a [`transpose`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/transpose/index.html) codec must name each array axis exactly once.
 
-The `fill_value` field is another example. The spec does not define a single shape for `fill_value`. Instead, each data type defines which JSON values it accepts as a fill value. So `"fill_value": "hello"` might be fine for a string data type, but it's a problem for `"float64"`. We can only check `fill_value` after we have resolved `data_type`.
+The `fill_value` member is another example. The spec does not define a single shape for `fill_value`. Instead, each data type defines which JSON values it accepts as a fill value. So `"fill_value": "hello"` might be fine for a string data type, but it's a problem for `"float64"`. We can only check `fill_value` after we have resolved `data_type`.
 
-The `codecs` field has the most interactions of all, because a list of codecs is a **pipeline**. The spec divides codecs into three kinds:
+The `codecs` member has the most interactions of all, because a list of codecs is a **pipeline**. [The spec](https://github.com/zarr-developers/zarr-specs/blob/v3.1.0/docs/v3/core/index.rst#L931-L1024) divides codecs into three kinds:
 
 - array → array codecs, like `transpose`, which take an array and return an array
 - array → bytes codecs, like `bytes`, which take an array and return bytes
 - bytes → bytes codecs, like `gzip`, which take bytes and return bytes
 
-A valid pipeline is zero or more array → array codecs, then exactly one array → bytes codec, then zero or more bytes → bytes codecs. We can't check this ordering until we know the kind of each codec, and we only know that after resolution.
+A valid pipeline has, in order:
+
+1. zero or more array → array codecs,
+2. exactly one array → bytes codec,
+3. zero or more bytes → bytes codecs.
+
+We can't check this ordering until we know the kind of each codec, and we only know that after resolution.
 
 Each codec in the pipeline is also handed a value produced by everything that came before it. The first codec is handed a chunk with the data type of the array and the shape of the chunk grid's chunks. An array → array codec may change that shape or data type before handing it on. Some codecs have rules about what they are handed. For example:
 
-- The `bytes` codec requires an `endian` field in its configuration when the data type it is handed takes more than one byte per element. `{"name": "bytes"}` is valid for a `uint8` array, but a problem for a `float64` array.
-- The `sharding_indexed` codec requires that its inner `chunk_shape` evenly divides the shape of the chunk it is handed, which is the outer chunk (or shard) shape.
+- The [`bytes`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/bytes/index.html#configuration-parameters) codec requires an `endian` member in its configuration when the data type it is handed takes more than one byte per element. `{"name": "bytes"}` is valid for a `uint8` array, but a problem for a `float64` array.
+- The [`sharding_indexed`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/sharding-indexed/index.html#configuration-parameters) codec requires that its inner `chunk_shape` evenly divides the shape of the chunk it is handed. That chunk is the outer chunk, or shard.
 
 To check these rules, we walk the pipeline in order, tracking the chunk that each codec is handed. For codecs that hold pipelines of their own, like `sharding_indexed`, we walk those inner pipelines too.
 
@@ -161,7 +180,7 @@ This procedure yields one of two values:
 
 `zarr-metadata` does not run each stage as a separate function. Instead, a single read of the document collects the problems from every stage, so a caller gets the full list of problems at once.
 
-The **registry** from the resolve-and-validate stage is called a **scope** in this library. For Zarr V3 it is a [`ZarrV3Context`](api/v3/definition.md) object, with one slot for each kind of declaration (`data_types`, `codecs`, `chunk_grids`, ...), and every reader takes a `context` argument. The default scope is `CORE_AND_EXTENSIONS_CONTEXT`, which holds the data types, codecs, chunk grids, etc. defined in the Zarr V3 spec and in [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/). `CORE_CONTEXT` holds only the definitions from the Zarr V3 spec. `ZARR_PYTHON_CONTEXT` adds to `CORE_AND_EXTENSIONS_CONTEXT` the data types that zarr-python writes but no specification registers (`null_terminated_bytes` for NumPy's `S`, `raw_bytes` for NumPy's `V`, and `variable_length_bytes`), so a strict check of what zarr-python writes passes it.
+The **registry** from the resolve-and-validate stage is called a **context** in this library. For Zarr V3 it is a [`ZarrV3Context`](api/v3/definition.md) object. It has one slot for each kind of declaration (`data_types`, `codecs`, `chunk_grids`, ...). Every reader takes a `context` argument. The default context is `CORE_AND_EXTENSIONS_CONTEXT`, which holds the data types, codecs, chunk grids, etc. defined in the Zarr V3 spec and in [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/). `CORE_CONTEXT` holds only the definitions from the Zarr V3 spec. `ZARR_PYTHON_CONTEXT` adds the data types that zarr-python writes but no specification registers.
 
 `read_array_metadata_v3` reads a JSON document and returns a "reading". `reading.problems` is a tuple of the problems, and `reading.metadata` is the validated model, or `None` if there are problems. Each problem has a `loc`, which is its position in the document as a tuple, a `kind`, like `missing_key` or `invalid_value`, and a human-readable `message`:
 
@@ -189,7 +208,7 @@ for problem in reading.problems:
 
 If you only want the model, `ZarrV3ArrayMetadata.from_json(raw)` returns it, or raises `MetadataValidationError` with every problem in `.problems`.
 
-To read one declaration on its own, such as a codec, use `resolve` from `zarr_metadata.definition`. It takes the declaration, the kind of declaration, and the scope, and returns the declaration as read and its problems:
+To read one declaration on its own, such as a codec, use `resolve` from `zarr_metadata.definition`. It takes the declaration, the kind of declaration, and the context, and returns the declaration as read and its problems:
 
 ```python test="true" session="parsing-validation"
 from zarr_metadata.definition import resolve
@@ -203,14 +222,39 @@ for problem in problems:
 # ('configuration', 'level') invalid_value
 ```
 
-A declaration with an unknown name is called **unclaimed**, because no definition in the scope claims that name. It is not reported as a problem: it is read as an `UnclaimedDeclaration`, and the checks that depend on it are skipped, as described above. So an empty `reading.problems` does not mean that every declaration is known. A program that decodes chunks should also check that no declaration is unclaimed. A model's `unclaimed_declarations` lists each one, at any depth, by its location, and leaves out an extra field that says `"must_understand": false`, with everything in it, since a reader may ignore it. A reading with problems has no model, and a node with problems cannot be opened either:
+A declaration with an unknown name is called **unclaimed**, because no definition in the context claims that name. It is not reported as a problem: it is read as an `UnclaimedDeclaration`, and the checks that depend on it are skipped, as described above. So an empty `reading.problems` does not mean that every declaration is known. A program that decodes chunks should also check that no declaration is unclaimed. A model's `unclaimed_declarations` lists each one, at any depth, by its location. It leaves out an extra field that says `"must_understand": false`, with everything in it, since a reader may ignore it.
+
+To report each of these as a problem too, read the document with `read_openable_node_metadata_v3`. Its problems are:
+
+1. the problems of `read_node_metadata_v3`,
+2. then one problem of kind `unclaimed_declaration` for each declaration that a reader must understand and that nothing in the context claims.
+
+So its reading has no problems exactly when a reader that understands the context can open the node:
 
 ```python test="true" session="parsing-validation"
-unclaimed = None if reading.metadata is None else reading.metadata.unclaimed_declarations
-can_open = unclaimed is not None and len(unclaimed) == 0
+from zarr_metadata.model import read_openable_node_metadata_v3
+
+openable = read_openable_node_metadata_v3(
+    {
+        "zarr_format": 3,
+        "node_type": "array",
+        "shape": [4],
+        "data_type": "uint8",
+        "chunk_grid": {"name": "regular", "configuration": {"chunk_shape": [2]}},
+        "chunk_key_encoding": {"name": "default"},
+        "fill_value": 0,
+        "codecs": [{"name": "bytes"}, {"name": "my_codec"}],
+        "my_member": {"name": "my_member"},
+        "ignorable": {"must_understand": False},
+    }
+)
+for problem in openable.problems:
+    print(problem.loc, problem.kind)
+# ('codecs', 1) unclaimed_declaration
+# ('my_member',) unclaimed_declaration
 ```
 
-To make an unknown data type or codec known, add its definition to the scope's slot and read the document again:
+To make an unknown data type or codec known, add its definition to the context's slot and read the document again:
 
 ```python test="true" session="parsing-validation"
 from zarr_metadata.definition import EmptyConfiguration
@@ -225,6 +269,50 @@ context = CORE_AND_EXTENSIONS_CONTEXT.union(ZarrV3Context(codecs=[MY_CODEC]))
 reading = read_array_metadata_v3(raw, context=context)
 ```
 
-`union` keeps every definition the scope has, and raises `ScopeConflictError` if `MY_CODEC` has a name the scope already files with another definition. To replace a definition on purpose, use `copy`, which, like pydantic's `model_copy(update=...)`, replaces whole each slot it is given and keeps the others. A slot can be given as a mapping from each definition's name to it, so `CORE_AND_EXTENSIONS_CONTEXT.copy(update={"codecs": {**CORE_AND_EXTENSIONS_CONTEXT.codecs, "gzip": MY_GZIP}})` replaces the gzip definition with your own. Passing `copy(update={"codecs": [MY_CODEC]})` instead would leave `MY_CODEC` as the only codec.
+`union` keeps every definition the context has, and raises `ScopeConflictError` if `MY_CODEC` has a name the context already files with another definition. To replace a definition on purpose, use `copy`, which, like pydantic's `model_copy(update=...)`, replaces whole each slot it is given and keeps the others. A slot can be given as a mapping from each definition's name to it, so `CORE_AND_EXTENSIONS_CONTEXT.copy(update={"codecs": {**CORE_AND_EXTENSIONS_CONTEXT.codecs, "gzip": MY_GZIP}})` replaces the gzip definition with your own. Passing `copy(update={"codecs": [MY_CODEC]})` instead would leave `MY_CODEC` as the only codec.
+
+A data type's definition also says what its fill value may be. `fill_value` is the fill value's JSON shape, as a type annotation. `fill_value_rules` is a function of the configuration, the nested declarations and the fill value, that yields each problem the shape cannot express. For example, `Base64Bytes` is a string, so an annotation accepts any string, and the rule `base64_fill_value_rules` rejects one that is not base64. A rule of your own can yield from it, then check what depends on the configuration:
+
+```python test="true" session="parsing-validation"
+import base64
+
+from typing_extensions import TypedDict
+
+from zarr_metadata.definition import fill_value_problems
+from zarr_metadata.problems import ValidationProblem
+from zarr_metadata.v3.data_type.bytes import Base64Bytes, base64_fill_value_rules
+from zarr_metadata.v3.definition import DataTypeDefinition
+
+
+class PackedConfiguration(TypedDict, closed=True):
+    length_bytes: int
+
+
+def packed_fill_value_rules(configuration, nested, value):
+    # The fill value is base64, of at most `length_bytes` bytes.
+    problems = list(base64_fill_value_rules(configuration, nested, value))
+    yield from problems
+    if not problems and len(base64.b64decode(value)) > configuration["length_bytes"]:
+        yield ValidationProblem((), "expected fewer bytes than the type holds", "invalid_value")
+
+
+PACKED = DataTypeDefinition(
+    name="acme.packed",
+    configuration=PackedConfiguration,
+    fill_value=Base64Bytes,
+    fill_value_rules=packed_fill_value_rules,
+)
+context = CORE_AND_EXTENSIONS_CONTEXT.union(ZarrV3Context(data_types=[PACKED]))
+data_type, _ = resolve(
+    {"name": "acme.packed", "configuration": {"length_bytes": 2}}, DataTypeDefinition, context
+)
+for fill_value in ("YWI=", "not base64!", "YWJj"):
+    print(fill_value, [problem.message for problem in fill_value_problems(data_type, fill_value)])
+# YWI= []
+# not base64! ['expected standard-alphabet base64, got "not base64!"']
+# YWJj ['expected fewer bytes than the type holds']
+```
+
+A reader of a document in this context checks its fill value with these rules, and so does a pydantic field. A JSON Schema written for the context does not contain the rules, so it accepts any string here.
 
-[^1]: The one exception is the `r*` data type, which is identified by a templated string with no `configuration` object. This mixes the identifier with the configuration in the same JSON value, which is not good design. So this library normalizes `r*` into the same form as all the other metadata objects: the declaration `"r16"` keeps its name, and is read by the `r*` definition with the configuration `{"bits": 16}`.
+[^1]: The one exception is the [`r*` data type](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#data-types), which is identified by a templated string with no `configuration` object. This mixes the identifier with the configuration in the same JSON value, which is not good design. So this library normalizes `r*` into the same form as all the other metadata objects. The declaration `"r16"` keeps its name. The `r*` definition reads it with the configuration `{"bits": 16}`.
diff --git a/packages/zarr-metadata/docs/pydantic.md b/packages/zarr-metadata/docs/pydantic.md
new file mode 100644
index 0000000000..5316c00534
--- /dev/null
+++ b/packages/zarr-metadata/docs/pydantic.md
@@ -0,0 +1,66 @@
+# Pydantic
+
+`zarr_metadata.pydantic` is an optional integration.
+
+- It requires Pydantic 2.13 or newer.
+- The core package does not depend on Pydantic.
+
+Each exported name is a Pydantic field type over one of the models. A raw
+document given to the field goes through the same strict reader as
+`from_json`. The value of the field is an instance of the model class
+itself.
+
+```python test="true" session="pydantic"
+import json
+from pydantic import BaseModel, TypeAdapter
+import zarr_metadata.pydantic as zmp
+
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
+
+adapter: TypeAdapter[zmp.ZarrV3ArrayMetadataField] = TypeAdapter(zmp.ZarrV3ArrayMetadataField)
+metadata = adapter.validate_python(raw)
+encoded = metadata.to_key_value()["zarr.json"]
+
+
+class ArrayManifest(BaseModel):
+    path: str
+    metadata: zmp.ZarrV3ArrayMetadataField
+
+
+manifest = ArrayManifest.model_validate({"path": "a/b", "metadata": raw})
+```
+
+A static type checker sees `manifest.metadata` as a
+`zarr_metadata.model.ZarrV3ArrayMetadata`.
+
+A failed read raises a Pydantic `ValidationError`. It has one line error
+per problem, in the format Pydantic uses for its own errors.
+
+## Choosing the context
+
+A field type reads its document in the context given by Pydantic's
+validation context:
+
+- If the validation context is a `Context`, every field type of that
+  format reads in it.
+- If it is a mapping:
+    - the v3 field types read in its `"zarr_metadata_context"` item;
+    - the v2 field types read in its `"zarr_metadata_context_v2"` item.
+- If no context is given for a format, its field types read in that
+  format's default: `CORE_AND_EXTENSIONS_CONTEXT` or `CORE_V2_CONTEXT`.
+
+To pin a field to one context, annotate it with `InScope`. A field
+annotated `Annotated[ZarrV3ArrayMetadata, zmp.InScope(CONTEXT)]` is read in
+`CONTEXT`, whatever the validation context holds. A model instance given to
+it is read again in `CONTEXT`.
+
+## A bare `TypeAdapter` is not a validator
+
+A `TypeAdapter` over one of the public `TypedDict`s is a **coercive** shape
+adapter. It is not a Zarr conformance validator. It may coerce values, or
+discard fields that the strict reader rejects.
+
+- It suits input built from Python objects, such as user-authored dicts.
+- For JSON read from a store, use the field types above, or the readers
+  directly.
diff --git a/packages/zarr-metadata/docs/repair.md b/packages/zarr-metadata/docs/repair.md
new file mode 100644
index 0000000000..f4f197e40e
--- /dev/null
+++ b/packages/zarr-metadata/docs/repair.md
@@ -0,0 +1,59 @@
+# Repairing known writer bugs
+
+The readers are strict. If a known writer bug made a document invalid, the
+readers report problems.
+
+The repair readers in `zarr_metadata.model` handle these documents:
+
+- `read_repaired_node_metadata_v3`
+- `read_repaired_node_metadata_v2`
+- `read_repaired_consolidated_metadata_v2`
+
+Each one works in three steps:
+
+1. Undo the known bugs.
+2. Read the result strictly.
+3. Return each change it made as a `Repair`.
+
+## Bugs the repair readers undo
+
+- **A chunk length of 0 along an empty dimension**, in a v3
+  [`regular` chunk grid](https://zarr-specs.readthedocs.io/en/latest/v3/chunk-grids/regular-grid/index.html#description).
+  zarr-python 3.0 and 3.1 wrote it. The repair writes 1.
+- **`consolidated_metadata: null` on a v3 group.** zarr-python 3.0 and 3.1
+  wrote it. The spec
+  [requires an object](https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816).
+  The repair removes the key.
+- **A `consolidated_metadata` member in a `.zgroup` entry of a
+  `.zmetadata`**, below the root. zarr-python 3 writes it. The
+  [v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#groups)
+  allows no key but `zarr_format` in a `.zgroup`. The repair removes the
+  member.
+- **A bare `NaN`, `Infinity` or `-Infinity` as a v2 fill value.**
+  zarr-python 3.0.0 to 3.0.6 wrote it. The repair writes the string the
+  [v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#fill-value-encoding)
+  uses, such as `"NaN"`.
+- **A bare non-finite float or complex fill value in a v3 group's
+  consolidated metadata.** zarr-python 3.0.0 to 3.0.6 wrote it. The repair
+  writes the string the
+  [v3 spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/data-types/index.html#permitted-fill-values)
+  uses, such as `"NaN"`.
+
+## Bugs the repair readers do not undo
+
+A document with one of these bugs is refused:
+
+- **The fill value of an `S` or `V` array as a JSON array of byte values**,
+  in a `.zmetadata` entry. zarr-python 3.0.7 to 3.0.10 wrote it. The
+  array's own `.zarray` file holds the
+  [base64 string](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#fill-value-encoding)
+  the v2 spec requires, and the package reads that file.
+- **The fill value of a v2 datetime array as an ISO 8601 string**, not as a
+  count of ticks. zarr-python 3.0.7 and 3.0.8 wrote it.
+- **A chunk length of 0 along a dimension that is not empty**, in a v3
+  `regular` chunk grid. zarr-python 3.0 and 3.1 wrote it for an explicit
+  chunk length of 0.
+- **A chunk length of `true` or `false`** in a v3 `regular` chunk grid.
+  Some releases of zarr-python from 3.0 to 3.2 wrote `true` for
+  `chunks=True`. Some releases of 3.0 and 3.1 wrote `false` for
+  `chunks=False`.
diff --git a/packages/zarr-metadata/docs/validation-rules.md b/packages/zarr-metadata/docs/validation-rules.md
new file mode 100644
index 0000000000..5a0b194c21
--- /dev/null
+++ b/packages/zarr-metadata/docs/validation-rules.md
@@ -0,0 +1,148 @@
+# What the readers check
+
+The readers and model constructors enforce the declared document
+structure. They also check a small set of consistency rules that need no
+context. For example:
+
+- fixed format literals
+  ([`zarr_format`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#zarr-format)
+  and
+  [`node_type`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#node-type)),
+- finite JSON numbers, except in `attributes` and in members that nothing
+  in the context reads,
+- non-negative
+  [dimensions](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#array-metadata-shape),
+- one
+  [`dimension_names`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#dimension-names)
+  entry per array dimension.
+
+## Extension points
+
+In a v3 document, the readers also check each
+[extension point](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#extension-points):
+
+- the data type,
+- the chunk grid,
+- the chunk key encoding,
+- each codec,
+- each storage transformer.
+
+The definition that claims a name in the context checks that extension
+point. The context is `CORE_AND_EXTENSIONS_CONTEXT` unless you pass a
+`context`.
+
+- If the definition rejects a configuration, the reader rejects it too.
+- A configuration key the definition does not declare is reported as
+  `unknown_key`.
+- If no definition claims a name, the reader does not check that extension
+  point. The consumer decides whether to support it.
+
+The [Context](context.md) page shows this with an example.
+
+## Checks across the document
+
+Some checks relate one part of a v3 document to another:
+
+- The
+  [fill value](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#fill-value)
+  is checked against the data type the document names. The data type's
+  definition does this check.
+- The
+  [chunk grid](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#chunk-grids)
+  is checked against the shape. The grid's definition does this check.
+- The codecs are checked as a
+  [pipeline](https://github.com/zarr-developers/zarr-specs/blob/v3.1.0/docs/v3/core/index.rst#L931-L1024).
+  In order, each codec's definition checks the codec against the chunk it
+  receives. This includes a
+  [shard's](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/sharding-indexed/index.html#configuration-parameters)
+  inner codecs and index codecs.
+
+The readers do no arithmetic on values. For example, they do not check
+whether a fill value survives a `cast_value` round trip.
+
+## Decisions the spec leaves open
+
+The spec leaves some choices open, or answers them in two ways. Here is
+what the package does.
+
+**`attributes` may hold `NaN`, `Infinity` and `-Infinity`.**
+
+- The spec
+  [does not interpret attributes](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#attributes).
+- zarr-python and xarray write these numbers there, for example as a CF
+  `_FillValue`.
+- The models read them. `to_key_value` writes them back as bare tokens,
+  which a strict JSON parser rejects.
+- The same goes for a member the spec does not define, when no definition
+  in the context claims it. Nothing reads it, so it is kept as written.
+- `check`, from `zarr_metadata.typed_json`, rejects a non-finite number
+  anywhere, including in attributes.
+
+**A reader walks at most 256 levels of nesting.**
+
+- A value nested deeper is an `invalid_value` problem at the first level
+  past the limit, wherever it is.
+- Every reader, writer and comparison uses one stack frame per level.
+  `copy.deepcopy` uses two, and so does `pickle` before Python 3.12.
+- So a document at the limit uses about half of the interpreter's default
+  recursion limit. The rest is left for the caller.
+
+**`consolidated_metadata: null` is a problem.**
+
+- A zarr-python 3.0.x bug wrote it.
+- The spec
+  [requires an object](https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816),
+  and the package accepts only an object.
+- The [repair readers](repair.md) remove the key before reading.
+
+**An extension name must follow the spec's
+[naming rule](https://github.com/zarr-developers/zarr-specs/blob/v3.1.0/docs/v3/core/index.rst#L1571-L1607)**,
+`^[a-z][a-z0-9-_.]+$`, or be a URI.
+
+- Earlier versions of the spec required URIs.
+- Any other name is rejected before any definition is consulted.
+- So `""` and `"foo/bar"` are problems, not unknown extensions.
+
+**`must_understand: false` is rejected at every extension point**,
+including codecs and storage transformers.
+
+- The
+  [core spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#must-understand)
+  names only the data type, chunk grid and chunk key encoding.
+- But a reader that skips a codec reads wrong bytes. That is just as bad as
+  a reader that skips a data type and reads wrong values.
+- On an unknown top-level member, `must_understand` keeps its meaning: a
+  reader can skip that member.
+
+**A v3 `regular` chunk grid's chunk lengths must be at least 1**, even
+along a dimension of length 0.
+
+- The
+  [regular grid spec](https://zarr-specs.readthedocs.io/en/latest/v3/chunk-grids/regular-grid/index.html#description)
+  says "Chunk sizes must be greater than zero".
+  [zarr-specs#379](https://github.com/zarr-developers/zarr-specs/pull/379)
+  added that sentence after v3.1.0.
+- The
+  [core spec's wording](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#concepts-and-terminology)
+  requires less: "non-zero when the corresponding dimensions of the arrays
+  have non-zero length". But it does not explicitly allow anything more.
+- So the package rejects a chunk length of 0. zarr-python 3.0 and 3.1 wrote
+  one for an empty dimension.
+
+**A v2 datetime or timedelta dtype must have a unit**, as in `<M8[ns]`.
+
+- The
+  [v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#data-type-encoding)
+  requires the unit in brackets.
+- zarr-python 3 writes `<M8` or `<m8` for a NumPy `datetime64` or
+  `timedelta64` with no unit. The package refuses those dtypes.
+- A codec's dtype parameter may leave out the unit. An example is the
+  `dtype` of a `delta` filter. Numcodecs writes it that way and runs it.
+
+**A v2 codec's dtype parameter is checked against the core v2 data
+types**, whatever context the array is read in.
+
+- Numcodecs reads the parameter with NumPy.
+- So a context that widens a data type does not widen what a codec's dtype
+  parameter may be. For example, a context that reads `<f16` as a dtype
+  still refuses it as a codec's dtype parameter.
diff --git a/packages/zarr-metadata/mkdocs.yml b/packages/zarr-metadata/mkdocs.yml
index b19c0932d2..2fa6a46e08 100644
--- a/packages/zarr-metadata/mkdocs.yml
+++ b/packages/zarr-metadata/mkdocs.yml
@@ -19,8 +19,16 @@ hooks:
 
 nav:
   - index.md
-  - Parsing / Validation: parsing-validation.md
-  - Context: context.md
+  - Guide:
+      - Parsing and validation: parsing-validation.md
+      - Context: context.md
+      - Models and readers: models.md
+      - What the readers check: validation-rules.md
+      - Consolidated metadata: consolidated-metadata.md
+      - Repairing known writer bugs: repair.md
+      - Writing an extension: extensions.md
+      - JSON Schema: json-schema.md
+      - Pydantic: pydantic.md
   - API Reference:
       - api/index.md
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_metadata.definition</code>': api/definition.md
diff --git a/packages/zarr-metadata/src/zarr_metadata/_json.py b/packages/zarr-metadata/src/zarr_metadata/_json.py
index 69829d32f4..d5de1537a2 100644
--- a/packages/zarr-metadata/src/zarr_metadata/_json.py
+++ b/packages/zarr-metadata/src/zarr_metadata/_json.py
@@ -20,7 +20,14 @@
 from zarr_metadata._common import JSONValue
 from zarr_metadata._sentinel import UNSET
 
-ProblemKind = Literal["missing_key", "invalid_type", "invalid_value", "invalid_json", "unknown_key"]
+ProblemKind = Literal[
+    "missing_key",
+    "invalid_type",
+    "invalid_value",
+    "invalid_json",
+    "unknown_key",
+    "unclaimed_declaration",
+]
 """Machine-readable classification of a `ValidationProblem`.
 
 - `missing_key`: a required key (document key or store key) is absent.
@@ -35,6 +42,10 @@
   open since 2023), and many readers reject such a key. It has its own
   kind so that a caller who tolerates it can distinguish it from a wrong
   value, and so that it never hides other problems in the same object.
+- `unclaimed_declaration`: a declaration that nothing in scope claims, which
+  a reader must understand to open the node. Only
+  `read_openable_node_metadata_v3` reports it: the other readers accept an
+  unclaimed declaration, since that is what keeps the format open.
 """
 
 
diff --git a/packages/zarr-metadata/src/zarr_metadata/definition/__init__.py b/packages/zarr-metadata/src/zarr_metadata/definition/__init__.py
index 019725679a..2ba4055ba6 100644
--- a/packages/zarr-metadata/src/zarr_metadata/definition/__init__.py
+++ b/packages/zarr-metadata/src/zarr_metadata/definition/__init__.py
@@ -116,40 +116,42 @@
 a closure cannot be pickled, and a `functools.partial` can be pickled
 but does not compare equal to its loaded copy.
 
-    from collections.abc import Iterator
-    from typing import Annotated, NotRequired
+```python
+from collections.abc import Iterator
+from typing import Annotated, NotRequired
 
-    from annotated_types import Ge
-    from typing_extensions import TypedDict
+from annotated_types import Ge
+from typing_extensions import TypedDict
 
-    from zarr_metadata import ValidationProblem
-    from zarr_metadata.definition import Nested
-    from zarr_metadata.v3.definition import CORE_AND_EXTENSIONS_CONTEXT, CodecDefinition, ZarrV3Context
+from zarr_metadata import ValidationProblem
+from zarr_metadata.definition import Nested
+from zarr_metadata.v3.definition import CORE_AND_EXTENSIONS_CONTEXT, CodecDefinition, ZarrV3Context
 
 
-    class AcmeLz4Configuration(TypedDict, closed=True):
-        acceleration: Annotated[int, Ge(1)]
-        dictionary: NotRequired[str]
-        dictionary_size: NotRequired[Annotated[int, Ge(1)]]
+class AcmeLz4Configuration(TypedDict, closed=True):
+    acceleration: Annotated[int, Ge(1)]
+    dictionary: NotRequired[str]
+    dictionary_size: NotRequired[Annotated[int, Ge(1)]]
 
 
-    def acme_lz4_rules(
-        configuration: AcmeLz4Configuration, nested: Nested
-    ) -> Iterator[ValidationProblem]:
-        if "dictionary" in configuration and "dictionary_size" not in configuration:
-            yield ValidationProblem(
-                ("dictionary_size",), "a dictionary needs its size", "missing_key"
-            )
+def acme_lz4_rules(
+    configuration: AcmeLz4Configuration, nested: Nested
+) -> Iterator[ValidationProblem]:
+    if "dictionary" in configuration and "dictionary_size" not in configuration:
+        yield ValidationProblem(
+            ("dictionary_size",), "a dictionary needs its size", "missing_key"
+        )
 
 
-    ACME_LZ4 = CodecDefinition(
-        name="acme.lz4",
-        configuration=AcmeLz4Configuration,
-        kind="bytes_bytes",
-        size="dynamic",
-        rules=acme_lz4_rules,
-    )
-    CONTEXT = CORE_AND_EXTENSIONS_CONTEXT.union(ZarrV3Context(codecs=[ACME_LZ4]))
+ACME_LZ4 = CodecDefinition(
+    name="acme.lz4",
+    configuration=AcmeLz4Configuration,
+    kind="bytes_bytes",
+    size="dynamic",
+    rules=acme_lz4_rules,
+)
+CONTEXT = CORE_AND_EXTENSIONS_CONTEXT.union(ZarrV3Context(codecs=[ACME_LZ4]))
+```
 
 The TypedDict declares how keys it does not declare are handled. With
 `closed=True`, such a key is a problem, as above. With `extra_items=`,
diff --git a/packages/zarr-metadata/src/zarr_metadata/json_schema.py b/packages/zarr-metadata/src/zarr_metadata/json_schema.py
index 2296b78652..7ff4bde29d 100644
--- a/packages/zarr-metadata/src/zarr_metadata/json_schema.py
+++ b/packages/zarr-metadata/src/zarr_metadata/json_schema.py
@@ -15,13 +15,15 @@
 accepts a number with no fractional part, such as `1.0`, as an integer,
 while `check` requires `1`:
 
-    from zarr_metadata.json_schema import json_schema
-
-    json_schema(GzipCodecConfiguration)
-    # {'$schema': 'https://json-schema.org/draft/2020-12/schema',
-    #  'type': 'object',
-    #  'properties': {'level': {'type': 'integer', 'minimum': 0, 'maximum': 9}},
-    #  'required': ['level'], 'additionalProperties': False}
+```python
+from zarr_metadata.json_schema import json_schema
+
+json_schema(GzipCodecConfiguration)
+# {'$schema': 'https://json-schema.org/draft/2020-12/schema',
+#  'type': 'object',
+#  'properties': {'level': {'type': 'integer', 'minimum': 0, 'maximum': 9}},
+#  'required': ['level'], 'additionalProperties': False}
+```
 
 **One v3 declaration.** `declaration_json_schema_v3(kind, context=None)` writes one declaration
 read as `kind` in the scope `context`: a declaration that a definition in
diff --git a/packages/zarr-metadata/src/zarr_metadata/model/__init__.py b/packages/zarr-metadata/src/zarr_metadata/model/__init__.py
index 0228861744..2501347273 100644
--- a/packages/zarr-metadata/src/zarr_metadata/model/__init__.py
+++ b/packages/zarr-metadata/src/zarr_metadata/model/__init__.py
@@ -25,7 +25,12 @@
 `read_repaired_node_metadata_v3` or `read_repaired_node_metadata_v2`.
 They undo each bug with `repair_node_metadata_v3` or
 `repair_node_metadata_v2` before the strict read, and report what they
-changed. `zarr_metadata.json_schema` writes a JSON Schema of what the v3
+changed. A reader accepts a declaration that nothing in its scope claims
+(an unknown codec, or an unknown top-level member), and a model lists each
+one a reader must understand in `unclaimed_declarations`. To also report
+each one as a problem, so that a reading has no problems exactly when a
+reader can open the node, use `read_openable_node_metadata_v3`.
+`zarr_metadata.json_schema` writes a JSON Schema of what the v3
 readers read, except for the rules. One declaration on its own is read with
 `zarr_metadata.definition.resolve`.
 
@@ -91,6 +96,7 @@
     read_consolidated_metadata_v3,
     read_group_metadata_v3,
     read_node_metadata_v3,
+    read_openable_node_metadata_v3,
 )
 from zarr_metadata.model._repair import (
     Repair,
@@ -160,6 +166,7 @@
     "read_group_metadata_v3",
     "read_node_metadata_v2",
     "read_node_metadata_v3",
+    "read_openable_node_metadata_v3",
     "read_repaired_consolidated_metadata_v2",
     "read_repaired_node_metadata_v2",
     "read_repaired_node_metadata_v3",
diff --git a/packages/zarr-metadata/src/zarr_metadata/model/_array_v3.py b/packages/zarr-metadata/src/zarr_metadata/model/_array_v3.py
index 061819fb3d..fa175ed005 100644
--- a/packages/zarr-metadata/src/zarr_metadata/model/_array_v3.py
+++ b/packages/zarr-metadata/src/zarr_metadata/model/_array_v3.py
@@ -443,14 +443,14 @@ def must_understand_subset(
     }
 
 
-def waived_members(values: Mapping[str, ZarrV3ExtensionField]) -> list[str]:
+def waived_members(values: Mapping[str, object]) -> list[str]:
     """The keys of the extra fields in `values` (by key, as written) that say `"must_understand": false`, which a reader may ignore."""
     return [key for key, value in values.items() if _waived(value)]
 
 
-def _waived(value: ZarrV3ExtensionField) -> bool:
+def _waived(value: object) -> bool:
     """Whether `value`, an extra field as written, is an object that says `"must_understand": false`."""
-    return isinstance(value, Mapping) and value.get("must_understand") is False
+    return is_object(value) and value.get("must_understand") is False
 
 
 class ZarrV3ArrayMetadataUpdate(TypedDict, total=False, closed=True):
@@ -835,6 +835,10 @@ def from_json(
         Raises `MetadataValidationError` with every problem the read finds.
         `read_array_metadata_v3` returns the reading this model is built
         from, and the problems of a document that has any.
+        A declaration that nothing in `context` claims, such as an unknown
+        codec or an unknown top-level member, is not a problem; the model
+        lists each one a reader must understand in `unclaimed_declarations`.
+        `read_openable_node_metadata_v3` reports each one as a problem.
         """
         return cls(data, context=context)
 
@@ -919,7 +923,9 @@ def read_array_metadata_v3(
     type. Unknown top-level keys are allowed (they map to
     `extra_fields`). A reader must understand each one that does not
     declare `must_understand: false`; the model reports these as
-    `must_understand_fields`.
+    `must_understand_fields`, and every declaration a reader must
+    understand, at any depth, as `unclaimed_declarations`.
+    `read_openable_node_metadata_v3` reports each of those as a problem.
 
     To apply a policy over the declarations (for example, allow only the core
     spec's declarations), iterate over the reading's `declarations()`. A value that
diff --git a/packages/zarr-metadata/src/zarr_metadata/model/_group_v3.py b/packages/zarr-metadata/src/zarr_metadata/model/_group_v3.py
index 42f3e61357..82aad927ab 100644
--- a/packages/zarr-metadata/src/zarr_metadata/model/_group_v3.py
+++ b/packages/zarr-metadata/src/zarr_metadata/model/_group_v3.py
@@ -450,7 +450,10 @@ def from_json(
         scope that claims the member, as `CORE_CONTEXT` does, this is a problem,
         because the spec requires an object. Use
         `read_repaired_node_metadata_v3` to read such a store. A member the
-        spec does not define is kept in `extra_fields`.
+        spec does not define is kept in `extra_fields`, and is not a
+        problem when nothing in `context` claims it; the model lists each
+        such member a reader must understand in `unclaimed_declarations`.
+        `read_openable_node_metadata_v3` reports each one as a problem.
         """
         return cls(data, context=context)
 
@@ -769,6 +772,44 @@ def read_node_metadata_v3(
     return ZarrV3UnknownNodeMetadataReading(problems)
 
 
+def read_openable_node_metadata_v3(
+    value: object, *, context: ZarrV3Context | None = None
+) -> ZarrV3NodeMetadataReading:
+    """Read `value`, a v3 `zarr.json`, in `context` as `read_node_metadata_v3` does, and also report each declaration a reader must understand to open the node that nothing in `context` claims.
+
+    The spec requires a reader to refuse a node with a declaration it does
+    not understand: an unknown codec, data type or chunk grid, or an
+    unknown top-level member that does not say `"must_understand": false`.
+    `read_node_metadata_v3` accepts these, as `UnclaimedDeclaration`s,
+    since that is what keeps the format open. This reader reports each one
+    as a problem of kind `unclaimed_declaration`, at its location, and
+    gives no model when there is one. A member that says
+    `"must_understand": false` is ignored whole, with every declaration in
+    it, as `unclaimed_declarations` ignores it. So the reading has no
+    problems exactly when a reader that understands `context` can open the
+    node. The documents a group's `consolidated_metadata` lists are not
+    read, as `read_group_metadata_v3` does not read them.
+    """
+    reading = read_node_metadata_v3(value, context=context)
+    # A node reading is only of an array or a group when `value` is an object.
+    if isinstance(reading, ZarrV3UnknownNodeMetadataReading) or not is_object(value):
+        return reading
+    waived = waived_members({key: value[key] for key in reading.extra_fields})
+    unclaimed = [
+        ValidationProblem(
+            loc,
+            f"nothing in scope claims the {kind_name(declaration.read_as)} {declaration.name!r}, "
+            "which a reader must understand to open the node",
+            "unclaimed_declaration",
+        )
+        for loc, declaration in unclaimed_declarations_of(reading.declarations(), waived).items()
+    ]
+    if len(unclaimed) == 0:
+        return reading
+    problems = (*reading.problems, *with_input(unclaimed, value))
+    return dataclasses.replace(reading, problems=problems, metadata=None)
+
+
 ZarrV3NodeMetadata = TypeAliasType("ZarrV3NodeMetadata", ZarrV3ArrayMetadata | ZarrV3GroupMetadata)
 """The model of a v3 `zarr.json`: an array model or a group model, as its `node_type` declares."""
 
@@ -875,7 +916,8 @@ def read_group_metadata_v3(
     Unknown top-level keys are allowed (they map to `extra_fields`). A
     reader must understand each one that does not declare
     `must_understand: false`; the model reports these as
-    `must_understand_fields`. A `consolidated_metadata` member, if
+    `must_understand_fields`, and `read_openable_node_metadata_v3` reports
+    each one as a problem. A `consolidated_metadata` member, if
     present and claimed by the scope, as `CORE_CONTEXT` claims it, is checked
     against the envelope the core spec fixes. The documents it lists are
     not read; `read_consolidated_metadata_v3` reads them. This is the
diff --git a/packages/zarr-metadata/src/zarr_metadata/pydantic.py b/packages/zarr-metadata/src/zarr_metadata/pydantic.py
index 4434660d8f..308519c0ef 100644
--- a/packages/zarr-metadata/src/zarr_metadata/pydantic.py
+++ b/packages/zarr-metadata/src/zarr_metadata/pydantic.py
@@ -29,9 +29,11 @@
 
 For example:
 
-    TypeAdapter(zmp.ZarrV3ArrayMetadataField).validate_python(document, context=CONTEXT)
-    ArrayManifest.model_validate(data, context={"zarr_metadata_context": CONTEXT})
-    Mixed.model_validate(data, context={"zarr_metadata_context": V3, "zarr_metadata_context_v2": V2})
+```python
+TypeAdapter(zmp.ZarrV3ArrayMetadataField).validate_python(document, context=CONTEXT)
+ArrayManifest.model_validate(data, context={"zarr_metadata_context": CONTEXT})
+Mixed.model_validate(data, context={"zarr_metadata_context": V3, "zarr_metadata_context_v2": V2})
+```
 
 An existing model instance passes through unchanged when no scope is
 given. When one is, the instance is read again in it with `refined_in`, so
@@ -63,11 +65,13 @@
 
 Usage:
 
-    import zarr_metadata.pydantic as zmp
+```python
+import zarr_metadata.pydantic as zmp
 
-    class ArrayManifest(BaseModel):
-        path: str
-        metadata: zmp.ZarrV3ArrayMetadataField
+class ArrayManifest(BaseModel):
+    path: str
+    metadata: zmp.ZarrV3ArrayMetadataField
+```
 
 Static type checkers see each field type as its core model class, so
 `manifest.metadata` is a `zarr_metadata.model.ZarrV3ArrayMetadata`.
diff --git a/packages/zarr-metadata/src/zarr_metadata/typed_json.py b/packages/zarr-metadata/src/zarr_metadata/typed_json.py
index 30ed95f695..982a3d4868 100644
--- a/packages/zarr-metadata/src/zarr_metadata/typed_json.py
+++ b/packages/zarr-metadata/src/zarr_metadata/typed_json.py
@@ -6,14 +6,16 @@
 value against the TypedDict and returns a value of the TypedDict (or
 None) and every problem, each located in the value:
 
-    import json
+```python
+import json
 
-    from zarr_metadata import ZarrV3ArrayMetadataJSON
-    from zarr_metadata.typed_json import check
+from zarr_metadata import ZarrV3ArrayMetadataJSON
+from zarr_metadata.typed_json import check
 
-    document, problems = check(json.loads(raw), ZarrV3ArrayMetadataJSON)
-    for problem in problems:
-        print(problem.loc, problem.kind, problem.message)
+document, problems = check(json.loads(raw), ZarrV3ArrayMetadataJSON)
+for problem in problems:
+    print(problem.loc, problem.kind, problem.message)
+```
 
 `check` reads a TypedDict as the typing spec defines it, regardless of
 how its module writes annotations:
diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/data_type/__init__.py b/packages/zarr-metadata/src/zarr_metadata/v3/data_type/__init__.py
index 528215df03..a1da0f902a 100644
--- a/packages/zarr-metadata/src/zarr_metadata/v3/data_type/__init__.py
+++ b/packages/zarr-metadata/src/zarr_metadata/v3/data_type/__init__.py
@@ -37,6 +37,7 @@
     BytesDataTypeName,
     BytesFillValue,
     base64_bytes,
+    base64_fill_value_rules,
 )
 from zarr_metadata.v3.data_type.complex64 import (
     COMPLEX64_DATA_TYPE,
@@ -338,6 +339,7 @@
     "ZarrPythonRawBytesDataTypeName",
     "ZarrPythonRawBytesFillValue",
     "base64_bytes",
+    "base64_fill_value_rules",
     "hex_float16",
     "hex_float32",
     "hex_float64",
diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/data_type/_byte.py b/packages/zarr-metadata/src/zarr_metadata/v3/data_type/_byte.py
index cfc7adddec..f9eda83e16 100644
--- a/packages/zarr-metadata/src/zarr_metadata/v3/data_type/_byte.py
+++ b/packages/zarr-metadata/src/zarr_metadata/v3/data_type/_byte.py
@@ -28,6 +28,23 @@ def base64_problems(value: str) -> Iterator[ValidationProblem]:
         )
 
 
+def base64_fill_value_rules(
+    configuration: object, nested: object, value: object
+) -> Iterator[ValidationProblem]:
+    """Check that a fill value written as a string is standard-alphabet base64: a data type's `fill_value_rules`.
+
+    `Base64Bytes` is a `NewType` of `str`, so a fill value annotated with
+    it accepts any string. Pass this rule as the data type's
+    `fill_value_rules` to reject a string that is not base64. A value of
+    any other shape is not checked here, so the rule also serves a fill
+    value that may be written another way, such as
+    `tuple[ByteValue, ...] | Base64Bytes`. A rule that checks more, such
+    as the number of bytes, yields from this one first.
+    """
+    if isinstance(value, str):
+        yield from base64_problems(value)
+
+
 def base64_decoded(value: str) -> bytes | None:
     """The bytes that `value` encodes in standard-alphabet base64; None when it is not such base64."""
     try:
@@ -41,4 +58,10 @@ def base64_spelling(data: bytes) -> str:
     return base64.b64encode(data).decode("ascii")
 
 
-__all__ = ["ByteValue", "base64_decoded", "base64_problems", "base64_spelling"]
+__all__ = [
+    "ByteValue",
+    "base64_decoded",
+    "base64_fill_value_rules",
+    "base64_problems",
+    "base64_spelling",
+]
diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/data_type/bytes.py b/packages/zarr-metadata/src/zarr_metadata/v3/data_type/bytes.py
index b92facd4af..f7e5c572aa 100644
--- a/packages/zarr-metadata/src/zarr_metadata/v3/data_type/bytes.py
+++ b/packages/zarr-metadata/src/zarr_metadata/v3/data_type/bytes.py
@@ -5,10 +5,8 @@
 """
 
 import base64
-from collections.abc import Iterator
 from typing import Final, Literal
 
-from zarr_metadata._json import ValidationProblem
 from zarr_metadata._numpy import Base64Bytes, base64_bytes
 from zarr_metadata.definition._definition import (
     EmptyConfiguration,
@@ -18,7 +16,11 @@
     DataTypeDefinition,
     variable_length,
 )
-from zarr_metadata.v3.data_type._byte import ByteValue, base64_problems, base64_spelling
+from zarr_metadata.v3.data_type._byte import (
+    ByteValue,
+    base64_fill_value_rules,
+    base64_spelling,
+)
 
 BYTES_DATA_TYPE_NAME: Final = "bytes"
 """The `data_type` value for the variable-length `bytes` type."""
@@ -34,14 +36,6 @@
 """
 
 
-def _fill_value_rules(
-    configuration: EmptyConfiguration, nested: Nested, value: BytesFillValue
-) -> Iterator[ValidationProblem]:
-    """Check that a string fill value is standard-alphabet base64. A fill value written as byte values is not checked here."""
-    if isinstance(value, str):
-        yield from base64_problems(value)
-
-
 def _fill_value_canonical(
     configuration: EmptyConfiguration, nested: Nested, value: BytesFillValue
 ) -> str:
@@ -60,7 +54,7 @@ def _fill_value_canonical(
     name=BYTES_DATA_TYPE_NAME,
     configuration=EmptyConfiguration,
     fill_value=BytesFillValue,
-    fill_value_rules=_fill_value_rules,
+    fill_value_rules=base64_fill_value_rules,
     fill_value_canonical=_fill_value_canonical,
     storage=variable_length,
 )
@@ -79,4 +73,5 @@ def _fill_value_canonical(
     "BytesDataTypeName",
     "BytesFillValue",
     "base64_bytes",
+    "base64_fill_value_rules",
 ]
diff --git a/packages/zarr-metadata/src/zarr_metadata/v3/data_type/variable_length_bytes.py b/packages/zarr-metadata/src/zarr_metadata/v3/data_type/variable_length_bytes.py
index 28803e9d80..11c7da2e69 100644
--- a/packages/zarr-metadata/src/zarr_metadata/v3/data_type/variable_length_bytes.py
+++ b/packages/zarr-metadata/src/zarr_metadata/v3/data_type/variable_length_bytes.py
@@ -10,14 +10,12 @@
 """
 
 import base64
-from collections.abc import Iterator
 from typing import Final, Literal
 
-from zarr_metadata._json import ValidationProblem
 from zarr_metadata._numpy import Base64Bytes
 from zarr_metadata.definition._definition import EmptyConfiguration, Nested
 from zarr_metadata.v3._definition import DataTypeDefinition, variable_length
-from zarr_metadata.v3.data_type._byte import base64_problems, base64_spelling
+from zarr_metadata.v3.data_type._byte import base64_fill_value_rules, base64_spelling
 
 VARIABLE_LENGTH_BYTES_DATA_TYPE_NAME: Final = "variable_length_bytes"
 """The `data_type` value for the `variable_length_bytes` type."""
@@ -29,13 +27,6 @@
 """Permitted JSON shape of the `fill_value` field for `variable_length_bytes`: a `Base64Bytes` string, which is what zarr-python writes and reads."""
 
 
-def _fill_value_rules(
-    configuration: EmptyConfiguration, nested: Nested, value: VariableLengthBytesFillValue
-) -> Iterator[ValidationProblem]:
-    """Check that the fill value is standard-alphabet base64."""
-    yield from base64_problems(value)
-
-
 def _fill_value_canonical(
     configuration: EmptyConfiguration, nested: Nested, value: VariableLengthBytesFillValue
 ) -> str:
@@ -47,7 +38,7 @@ def _fill_value_canonical(
     name=VARIABLE_LENGTH_BYTES_DATA_TYPE_NAME,
     configuration=EmptyConfiguration,
     fill_value=VariableLengthBytesFillValue,
-    fill_value_rules=_fill_value_rules,
+    fill_value_rules=base64_fill_value_rules,
     fill_value_canonical=_fill_value_canonical,
     storage=variable_length,
 )
diff --git a/packages/zarr-metadata/tests/model/test_unclaimed_declarations.py b/packages/zarr-metadata/tests/model/test_unclaimed_declarations.py
index 02b5521882..e66914b6d2 100644
--- a/packages/zarr-metadata/tests/model/test_unclaimed_declarations.py
+++ b/packages/zarr-metadata/tests/model/test_unclaimed_declarations.py
@@ -7,6 +7,7 @@
 import pytest
 from typing_extensions import TypedDict
 
+from zarr_metadata import UNSET
 from zarr_metadata.definition import UnclaimedDeclaration
 from zarr_metadata.model import (
     ZarrV2ArrayMetadata,
@@ -15,6 +16,8 @@
     ZarrV3ArrayMetadata,
     ZarrV3GroupMetadata,
     ZarrV3NodeMetadata,
+    read_node_metadata_v3,
+    read_openable_node_metadata_v3,
 )
 from zarr_metadata.v3 import CORE_CONTEXT
 from zarr_metadata.v3.definition import (
@@ -190,3 +193,78 @@ def test_node_type_tells_a_type_checker_which_model_a_node_is() -> None:
     for node in nodes:
         if node.zarr_format == 3 and node.node_type == "group":
             assert node.consolidated() is None
+
+
+@pytest.mark.parametrize(
+    ("document", "context", "unclaimed", "problems"),
+    [
+        (ARRAY, CORE_CONTEXT, set(), set()),
+        ({**ARRAY, "codecs": ("bytes", ZSTD)}, CORE_CONTEXT, {("codecs", 1)}, set()),
+        (
+            {**ARRAY, "codecs": (SHARD,)},
+            CORE_CONTEXT,
+            {("codecs", 0, "configuration", "codecs", 1)},
+            set(),
+        ),
+        ({**ARRAY, "acme": 1}, CORE_CONTEXT, {("acme",)}, set()),
+        ({**ARRAY, "acme": {"must_understand": False}}, CORE_CONTEXT, set(), set()),
+        ({**GROUP, "acme": {"name": "acme"}}, CORE_CONTEXT, {("acme",)}, set()),
+        ({**GROUP, "acme": {"must_understand": False}}, CORE_CONTEXT, set(), set()),
+        (
+            {**ARRAY, "acme.mirror": {"codec": {"name": "acme.zip"}}},
+            MIRRORING,
+            {("acme.mirror", "codec")},
+            set(),
+        ),
+        (
+            {**ARRAY, "acme.mirror": {"codec": {"name": "acme.zip"}, "must_understand": False}},
+            MIRRORING,
+            set(),
+            set(),
+        ),
+        (
+            {**ARRAY, "fill_value": "x", "codecs": ("bytes", ZSTD)},
+            CORE_CONTEXT,
+            {("codecs", 1)},
+            {("fill_value",)},
+        ),
+        ({**GROUP, "node_type": "acme"}, CORE_CONTEXT, set(), {("node_type",)}),
+        ("not a node", CORE_CONTEXT, set(), {()}),
+    ],
+    ids=[
+        "all-claimed",
+        "a-codec",
+        "a-codec-inside-a-shard",
+        "an-extra-member",
+        "a-waived-extra-member",
+        "a-group-member",
+        "a-waived-group-member",
+        "a-codec-inside-a-claimed-member",
+        "a-codec-inside-a-claimed-member-that-waives",
+        "with-other-problems",
+        "an-unknown-node-type",
+        "not-an-object",
+    ],
+)
+def test_read_openable_node_metadata_v3_reports_what_a_reader_must_understand(
+    document: object,
+    context: Any,  # noqa: ANN401 - a v3 scope
+    unclaimed: set[tuple[str | int, ...]],
+    problems: set[tuple[str | int, ...]],
+) -> None:
+    """`read_openable_node_metadata_v3` keeps every problem `read_node_metadata_v3` finds and adds one of kind `unclaimed_declaration` at the location of each declaration `unclaimed_declarations` lists, with what the document writes there as its input, whether or not the document has other problems. It gives a model exactly when there are no problems, and the model is the one `read_node_metadata_v3` gives."""
+    plain = read_node_metadata_v3(document, context=context)
+    reading = read_openable_node_metadata_v3(document, context=context)
+    assert reading.problems[: len(plain.problems)] == plain.problems
+    assert {problem.loc for problem in plain.problems} == problems
+    added = reading.problems[len(plain.problems) :]
+    assert {problem.loc for problem in added} == unclaimed
+    assert all(problem.kind == "unclaimed_declaration" for problem in added)
+    assert all(problem.input is not UNSET for problem in added)
+    if plain.metadata is not None:
+        assert set(plain.metadata.unclaimed_declarations) == unclaimed
+    if len(reading.problems) == 0:
+        assert reading.metadata == plain.metadata
+        assert reading.metadata is not None
+    else:
+        assert reading.metadata is None
diff --git a/packages/zarr-metadata/tests/test_docs.py b/packages/zarr-metadata/tests/test_docs.py
index 7726151126..a05596075d 100644
--- a/packages/zarr-metadata/tests/test_docs.py
+++ b/packages/zarr-metadata/tests/test_docs.py
@@ -8,12 +8,14 @@
 
 from __future__ import annotations
 
+import textwrap
 from collections import defaultdict
 from pathlib import Path
 
 import pytest
 from pytest_examples import CodeExample, EvalExample, find_examples
 
+import zarr_metadata.definition
 from zarr_metadata.model import ZarrV3ArrayMetadata
 
 PACKAGE_ROOT = Path(__file__).parent.parent
@@ -71,3 +73,31 @@ def test_every_python_block_says_whether_it_runs() -> None:
         )
     ]
     assert unmarked == []
+
+
+def test_the_extensions_page_example_is_the_definition_module_docstring_example() -> None:
+    """The acme.lz4 example on the extensions page is, line for line, the example in the `zarr_metadata.definition` module docstring. Only the page's copy runs under these tests, so this is what keeps the docstring's copy from drifting."""
+    page_blocks = [
+        example
+        for example in _examples()
+        if example.path == PACKAGE_ROOT / "docs" / "extensions.md"
+        and example.prefix_settings().get("session") == "extensions"
+    ]
+    assert len(page_blocks) == 1, (
+        "expected exactly one extensions-session block on docs/extensions.md"
+    )
+    docstring = zarr_metadata.definition.__doc__
+    assert docstring is not None, "zarr_metadata.definition has no module docstring"
+    lines = docstring.splitlines()
+    marker = "from collections.abc import Iterator"
+    starts = [i for i, line in enumerate(lines) if line.strip() == marker]
+    assert len(starts) == 1, f"expected one line {marker!r} in the docstring, found {len(starts)}"
+    assert lines[starts[0] - 1].strip() == "```python", (
+        f"expected {marker!r} to open a ```python fence in the docstring"
+    )
+    end = starts[0]
+    while end < len(lines) and lines[end].strip() != "```":
+        end += 1
+    assert end < len(lines), "the docstring's ```python fence is not closed"
+    docstring_example = textwrap.dedent("\n".join(lines[starts[0] : end])).strip()
+    assert page_blocks[0].source.strip().splitlines() == docstring_example.splitlines()
diff --git a/packages/zarr-metadata/tests/v3/data_type/bytes/test_validators.py b/packages/zarr-metadata/tests/v3/data_type/bytes/test_validators.py
index 7f41d878f8..c104b81bf4 100644
--- a/packages/zarr-metadata/tests/v3/data_type/bytes/test_validators.py
+++ b/packages/zarr-metadata/tests/v3/data_type/bytes/test_validators.py
@@ -1,16 +1,16 @@
-"""Cover the `base64_bytes` brand validator.
+"""Cover the `base64_bytes` brand validator and the `base64_fill_value_rules` fill value rule.
 
 The pydantic-driven fixture tests don't enforce the base64 alphabet or
 length-multiple-of-4 constraint because `Base64Bytes` is a `NewType`,
 which pydantic treats as plain `str`. Direct coverage of the validator
-function lives here.
+function and the rule built on it lives here.
 """
 
 from __future__ import annotations
 
 import pytest
 
-from zarr_metadata.v3.data_type.bytes import base64_bytes
+from zarr_metadata.v3.data_type.bytes import base64_bytes, base64_fill_value_rules
 
 VALID = [
     "",  # empty is valid base64 (length 0, multiple of 4)
@@ -41,3 +41,16 @@ def test_valid(value: str) -> None:
 def test_invalid(value: str) -> None:
     with pytest.raises(ValueError, match="standard-alphabet base64"):
         base64_bytes(value)
+
+
+# A value written in another shape, such as byte values, is the annotation's to check.
+@pytest.mark.parametrize("value", [*VALID, (1, 2, 3), None])
+def test_base64_fill_value_rules_accepts(value: object) -> None:
+    assert list(base64_fill_value_rules({}, (), value)) == []
+
+
+@pytest.mark.parametrize("value", INVALID)
+def test_error_base64_fill_value_rules_rejects_a_string_that_is_not_base64(value: str) -> None:
+    assert [(p.loc, p.kind) for p in base64_fill_value_rules({}, (), value)] == [
+        ((), "invalid_value")
+    ]