From 5ddb75fe3593541343a7fcc40d4e32632ac07457 Mon Sep 17 00:00:00 2001
From: Davis Vann Bennett <davis.v.bennett@gmail.com>
Date: Mon, 2 Nov 2026 14:48:49 +0100
Subject: [PATCH 1/2] docs(zarr-metadata): condense the 0.6.0 release notes

Replace the ten bugfix fragments of PR 4574 with three, two of them
marked breaking, and shorten the PR 4592 fragment to the rename and the
names a user is most likely to have imported. The removed detail stays
in the pull requests. Bugfix prose drops from about 800 words to 300.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/zarr-metadata/changes/4574.bugfix.1.md  |  8 +-------
 packages/zarr-metadata/changes/4574.bugfix.10.md |  5 -----
 packages/zarr-metadata/changes/4574.bugfix.2.md  |  5 +----
 packages/zarr-metadata/changes/4574.bugfix.3.md  |  6 +-----
 packages/zarr-metadata/changes/4574.bugfix.4.md  |  7 -------
 packages/zarr-metadata/changes/4574.bugfix.5.md  | 11 -----------
 packages/zarr-metadata/changes/4574.bugfix.6.md  |  8 --------
 packages/zarr-metadata/changes/4574.bugfix.7.md  | 12 ------------
 packages/zarr-metadata/changes/4574.bugfix.8.md  |  4 ----
 packages/zarr-metadata/changes/4574.bugfix.9.md  | 12 ------------
 packages/zarr-metadata/changes/4592.removal.md   | 11 +----------
 11 files changed, 4 insertions(+), 85 deletions(-)
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.10.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.4.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.5.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.6.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.7.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.8.md
 delete mode 100644 packages/zarr-metadata/changes/4574.bugfix.9.md

diff --git a/packages/zarr-metadata/changes/4574.bugfix.1.md b/packages/zarr-metadata/changes/4574.bugfix.1.md
index 0d387acd14..b49e3cfa85 100644
--- a/packages/zarr-metadata/changes/4574.bugfix.1.md
+++ b/packages/zarr-metadata/changes/4574.bugfix.1.md
@@ -1,7 +1 @@
-**Breaking:** A problem in a v2 struct dtype is located where the document
-    writes it. A record's problem was located under a `fields` key the
-    document does not have, at `("dtype", "fields", 0, 1)`; it is now at
-    `("dtype", 0, 1)`, and carries the value found there as its `input`.
-    `declarations()` places each record's type there too. A definition's
-    functions still find the record types in `nested` at
-    `("fields", 0, 1)`, their place in the configuration.
+**Breaking:** Every problem is now located where the document writes the value. The v2 readers and the v2 models' `from_key_value` locate a problem in the file that holds it, such as `(".zarray", "order")` or `(".zattrs", "x")`, instead of in the merged document, and a v2 array node reading's `at` is now `(".zarray",)`. A problem in a v2 struct record is at `("dtype", 0, 1)` instead of under a `fields` key the document does not have, and a codec's problem is at the configuration the document writes, or at the codec itself when it writes none.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.10.md b/packages/zarr-metadata/changes/4574.bugfix.10.md
deleted file mode 100644
index e06b2d6d3d..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.10.md
+++ /dev/null
@@ -1,5 +0,0 @@
-Each problem `read_consolidated_metadata_v3` finds in the inline
-    `consolidated_metadata` member itself, such as a `kind` that is not
-    `"inline"` or a key that is not a node path, carries the value found at
-    its location as its `input`, as every other reader's problems do. Its
-    `input` was unset.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.2.md b/packages/zarr-metadata/changes/4574.bugfix.2.md
index 4342fc151c..b0a67f448e 100644
--- a/packages/zarr-metadata/changes/4574.bugfix.2.md
+++ b/packages/zarr-metadata/changes/4574.bugfix.2.md
@@ -1,4 +1 @@
-A v2 dtype written as the string `"struct"` is refused as a string that is
-    not a NumPy typestr, like any other, instead of being read as a struct
-    with no records. `struct` is the name the definition of a records array
-    is filed under, not part of the v2 dtype grammar.
+**Breaking:** The v2 readers now agree with the v3 readers. A `.zarray` member the spec does not define may hold `NaN` and the infinities, a `.zmetadata` key that does not name its node's path, such as `/a/.zarray`, is refused instead of being read as the node at `a`, and a `.zgroup` that holds `attributes` is an `invalid_value` rather than an `unknown_key`, so a caller who tolerates unknown keys no longer drops those attributes.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.3.md b/packages/zarr-metadata/changes/4574.bugfix.3.md
index adec05b00c..b69507e86d 100644
--- a/packages/zarr-metadata/changes/4574.bugfix.3.md
+++ b/packages/zarr-metadata/changes/4574.bugfix.3.md
@@ -1,5 +1 @@
-A group listed in v3 consolidated metadata whose own document has a problem,
-    such as attributes that are not an object, is reported for that problem
-    alone. It was also reported for disagreeing with the outer listing's copy
-    of the same node, a difference that came only from the problem. A copy
-    whose only problem is an unknown key is still compared.
+Various mistakes in v2 and consolidated metadata are now reported once, at their own location, with the right kind and message. A float where an integer from a fixed set is required, such as `"zarr_format": 2.0`, is an `invalid_type`, and a v2 typestr with a part its family does not take, such as `<f4[ns]`, or a time typestr without a unit, is a single `invalid_value` that names the part. A struct record of the wrong length or with a non-string name, the string `"struct"` given as a v2 dtype, a node that v3 consolidated metadata lists and whose own document has a problem, and a malformed inline `consolidated_metadata` member are each reported for their own problem alone, with the value found there as the problem's `input`.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.4.md b/packages/zarr-metadata/changes/4574.bugfix.4.md
deleted file mode 100644
index c9dffad04b..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.4.md
+++ /dev/null
@@ -1,7 +0,0 @@
-A v2 struct record of the wrong length is reported as "expected an array of
-    2 or 3 elements", where the message named only the three-element form. A
-    two-element record whose name is not a string, `[5, "<f4"]`, is reported
-    at the name, where it was reported as a record of the wrong length. The
-    checker behind `zarr_metadata.typed_json.check` tries an array only
-    against the union branches of its length, and names a union of arrays of
-    fixed lengths by those lengths.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.5.md b/packages/zarr-metadata/changes/4574.bugfix.5.md
deleted file mode 100644
index fc9592094b..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.5.md
+++ /dev/null
@@ -1,11 +0,0 @@
-**Breaking:** The v2 readers agree with the v3 readers in three places. A
-    `.zarray` member the spec does not define may hold `NaN` and the
-    infinities, as a v3 member that nothing claims may, in a store and in a
-    `.zmetadata` alike. A `.zmetadata` key that does not name its node's
-    path, such as `/a/.zarray` or `a//b/.zarray`, is refused, as a v3
-    listing refuses such a key, instead of being read as the node at `a` or
-    `a/b`; zarr-python looks an entry up by its node's path and never finds
-    one written otherwise. A `.zgroup` that holds `attributes` is an
-    `invalid_value`, as a `.zarray` that holds them is, not an
-    `unknown_key`, so a caller who tolerates unknown keys does not drop the
-    attributes it holds.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.6.md b/packages/zarr-metadata/changes/4574.bugfix.6.md
deleted file mode 100644
index 73ad98f4d2..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.6.md
+++ /dev/null
@@ -1,8 +0,0 @@
-A v2 typestr with a part its family does not take, such as `<f4[ns]` or
-    `|O4`, is refused with one `invalid_value` problem that names the part:
-    "expected a typestr of the float family without a unit, got "<f4[ns]"".
-    It was refused as one `unknown_key` problem per internal configuration
-    key (`unit`, `scale_factor`, `itemsize`), a kind a caller who tolerates
-    unknown keys leaves out, so such a caller read the typestr as valid. A
-    time typestr without a unit, `<M8`, is an `invalid_value` too, not a
-    `missing_key`.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.7.md b/packages/zarr-metadata/changes/4574.bugfix.7.md
deleted file mode 100644
index 4d1227150c..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.7.md
+++ /dev/null
@@ -1,12 +0,0 @@
-A definition's rules are located where the document writes the declaration. A
-    `bytes` codec written as `"bytes"` or `{"name": "bytes"}`, with values
-    of several bytes, reports its missing `endian` at
-    `codecs.N.configuration`, the configuration it does not write, as a
-    codec that requires a configuration does; it was reported at
-    `codecs.N.configuration.endian`, inside a configuration that is not
-    there. A codec handed values it cannot encode, such as a `bytes` codec
-    handed a data type of varying size, is reported at `codecs.N` however it
-    is spelled, where it was reported at `codecs.N.configuration`: a chunk
-    rule's problem at the configuration as a whole is the codec's. A
-    definition's `rules` still report such a problem at the configuration
-    the document writes.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.8.md b/packages/zarr-metadata/changes/4574.bugfix.8.md
deleted file mode 100644
index d7149876ab..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.8.md
+++ /dev/null
@@ -1,4 +0,0 @@
-A float given where a document requires one of a set of integers, such as
-    `"zarr_format": 2.0`, is an `invalid_type`, as `4.0` in `shape` is and
-    as a blosc `"shuffle": 1.0` already was. It was an `invalid_value`
-    wherever the set stood alone, so one mistake had two kinds.
diff --git a/packages/zarr-metadata/changes/4574.bugfix.9.md b/packages/zarr-metadata/changes/4574.bugfix.9.md
deleted file mode 100644
index e51f5dc30f..0000000000
--- a/packages/zarr-metadata/changes/4574.bugfix.9.md
+++ /dev/null
@@ -1,12 +0,0 @@
-**Breaking:** `read_node_metadata_v2`, `read_repaired_node_metadata_v2`
-    and the v2 models' `from_key_value` locate each problem in the file that
-    holds it, `(".zarray", "order")` or `(".zattrs", "x")`, as
-    `read_consolidated_metadata_v2` locates it in its entry. They located
-    problems in the merged document, so a `.zarray` that wrote `attributes`
-    beside a `.zattrs` that was not an object gave two problems at
-    `("attributes",)`, a location in neither file. An array node's reading
-    locates its declarations there too: its new `at` is `(".zarray",)`, so
-    `declarations()` gives `(".zarray", "dtype")` and `with_problems` pairs each
-    declaration with its problems. Its model reads the merged document, so the
-    model's own `reading` locates the declaration at `("dtype",)`, and no longer
-    equals the node reading.
diff --git a/packages/zarr-metadata/changes/4592.removal.md b/packages/zarr-metadata/changes/4592.removal.md
index 5080a931ea..982ec30d05 100644
--- a/packages/zarr-metadata/changes/4592.removal.md
+++ b/packages/zarr-metadata/changes/4592.removal.md
@@ -1,10 +1 @@
-Rename the word for a value at an extension point: it is now a *declaration* (it was a *field*). A name/value pair in a JSON metadata object stays a *member*. The package already said *field* in the JSON sense in `extra_fields`, `ExtraFieldDefinition`, `ZarrV3ExtensionField` and `must_understand_fields`, after the spec's "additional fields", so one word meant two things. The public names change with no aliases:
-
-- `AcceptedField`, `UnclaimedField`, `RefusedField` and `ResolvedField` are now `AcceptedDeclaration`, `UnclaimedDeclaration`, `RefusedDeclaration` and `ResolvedDeclaration`.
-- `ZarrV3DataTypeField`, `ZarrV3ChunkGridField`, `ZarrV3ChunkKeyEncodingField`, `ZarrV3CodecField`, `ZarrV3StaticCodecField`, `ZarrV3StorageTransformerField` and `ZarrV2DataTypeField` are now the same names ending in `Declaration`, and a kind's `field_aliases` is now `declaration_aliases`.
-- `ZarrV3MetadataFieldJSON` is now `ZarrV3DeclarationJSON`, and `field_json_schema_v3` is now `declaration_json_schema_v3`.
-- A reading's `fields()` is now `declarations()`, and a model's `unclaimed_fields` is now `unclaimed_declarations`.
-- The first parameter of `with_problems` is now `declarations` (it was `fields`).
-- The JSON Schemas that `node_metadata_json_schema_v3` and `declaration_json_schema_v3` write name each alias under `$defs` by its new name, so a `$ref` to `#/$defs/ZarrV3CodecField` is now `#/$defs/ZarrV3CodecDeclaration`, and likewise for the other kinds.
-
-Messages that said *field* or *metadata field* for an extension-point value now say *declaration*, as in "expected a declaration (string or extension object)". Prose that said *extra member* or *extension member* now says *extra field* and *extension field*, after the names. `extra_fields`, `ExtraFieldDefinition`, `ZarrV3ExtensionField`, `StructField` and the pydantic `...MetadataField` types keep their names.
+**Breaking:** The value found at an extension point, a data type, chunk grid, chunk key encoding, codec or storage transformer, is now called a *declaration*. The word *field* also meant a key of a metadata object, as in `extra_fields`, so one word meant two things. The public names change with no aliases: `AcceptedField`, `UnclaimedField`, `RefusedField` and `ResolvedField` end in `Declaration`, as do `ZarrV3CodecField` and the other kind-specific `...Field` types; a reading's `fields()` is `declarations()`; a model's `unclaimed_fields` is `unclaimed_declarations`; `ZarrV3MetadataFieldJSON` is `ZarrV3DeclarationJSON`; `field_json_schema_v3` is `declaration_json_schema_v3`; and the JSON Schema `$defs` use the new names. `extra_fields`, `ExtraFieldDefinition`, `ZarrV3ExtensionField` and `StructField` keep their names.

From 1ca035b2af347ddc83b82f1f3d98a48daaef1371 Mon Sep 17 00:00:00 2001
From: Davis Vann Bennett <davis.v.bennett@gmail.com>
Date: Mon, 2 Nov 2026 14:50:28 +0100
Subject: [PATCH 2/2] docs(zarr-metadata): state the codec problem locations
 and two more renames correctly

Roborev caught that the condensed note inverted where a codec's problems
land, against tests/v3/test_pipelines.py, and that the rename note
dropped declaration_aliases and the with_problems parameter.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/zarr-metadata/changes/4574.bugfix.1.md | 2 +-
 packages/zarr-metadata/changes/4592.removal.md  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/zarr-metadata/changes/4574.bugfix.1.md b/packages/zarr-metadata/changes/4574.bugfix.1.md
index b49e3cfa85..53a5935723 100644
--- a/packages/zarr-metadata/changes/4574.bugfix.1.md
+++ b/packages/zarr-metadata/changes/4574.bugfix.1.md
@@ -1 +1 @@
-**Breaking:** Every problem is now located where the document writes the value. The v2 readers and the v2 models' `from_key_value` locate a problem in the file that holds it, such as `(".zarray", "order")` or `(".zattrs", "x")`, instead of in the merged document, and a v2 array node reading's `at` is now `(".zarray",)`. A problem in a v2 struct record is at `("dtype", 0, 1)` instead of under a `fields` key the document does not have, and a codec's problem is at the configuration the document writes, or at the codec itself when it writes none.
+**Breaking:** Every problem is now located where the document writes the value. The v2 readers and the v2 models' `from_key_value` locate a problem in the file that holds it, such as `(".zarray", "order")` or `(".zattrs", "x")`, instead of in the merged document, and a v2 array node reading's `at` is now `(".zarray",)`. A problem in a v2 struct record is at `("dtype", 0, 1)` instead of under a `fields` key the document does not have, a codec's missing configuration member, such as the `endian` of a `bytes` codec, is reported inside the configuration it writes, or at `codecs.N.configuration` when it writes none, and a codec handed values it cannot encode is reported at `codecs.N` however it is spelled.
diff --git a/packages/zarr-metadata/changes/4592.removal.md b/packages/zarr-metadata/changes/4592.removal.md
index 982ec30d05..323ce4de30 100644
--- a/packages/zarr-metadata/changes/4592.removal.md
+++ b/packages/zarr-metadata/changes/4592.removal.md
@@ -1 +1 @@
-**Breaking:** The value found at an extension point, a data type, chunk grid, chunk key encoding, codec or storage transformer, is now called a *declaration*. The word *field* also meant a key of a metadata object, as in `extra_fields`, so one word meant two things. The public names change with no aliases: `AcceptedField`, `UnclaimedField`, `RefusedField` and `ResolvedField` end in `Declaration`, as do `ZarrV3CodecField` and the other kind-specific `...Field` types; a reading's `fields()` is `declarations()`; a model's `unclaimed_fields` is `unclaimed_declarations`; `ZarrV3MetadataFieldJSON` is `ZarrV3DeclarationJSON`; `field_json_schema_v3` is `declaration_json_schema_v3`; and the JSON Schema `$defs` use the new names. `extra_fields`, `ExtraFieldDefinition`, `ZarrV3ExtensionField` and `StructField` keep their names.
+**Breaking:** The value found at an extension point, a data type, chunk grid, chunk key encoding, codec or storage transformer, is now called a *declaration*. The word *field* also meant a key of a metadata object, as in `extra_fields`, so one word meant two things. The public names change with no aliases: `AcceptedField`, `UnclaimedField`, `RefusedField` and `ResolvedField` end in `Declaration`, as do `ZarrV3CodecField` and the other kind-specific `...Field` types; a reading's `fields()` is `declarations()`; a model's `unclaimed_fields` is `unclaimed_declarations`; `ZarrV3MetadataFieldJSON` is `ZarrV3DeclarationJSON`; `field_json_schema_v3` is `declaration_json_schema_v3`; a kind's `field_aliases` is `declaration_aliases`; the first parameter of `with_problems` is `declarations`; and the JSON Schema `$defs` use the new names. `extra_fields`, `ExtraFieldDefinition`, `ZarrV3ExtensionField` and `StructField` keep their names.