Skip to content

refactor(zarr-metadata)!: call an extension-point value a declaration - #432

Closed
d-v-b wants to merge 23 commits into
mainfrom
refactor/zarr-metadata-field-terminology
Closed

refactor(zarr-metadata)!: call an extension-point value a declaration#432
d-v-b wants to merge 23 commits into
mainfrom
refactor/zarr-metadata-field-terminology

Conversation

@d-v-b

@d-v-b d-v-b commented Nov 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

🤖 AI text below 🤖

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.

Why

Before this change the package used "field" in two senses. extra_fields, ExtraFieldDefinition, ZarrV3ExtensionField and must_understand_fields use it for a key of a metadata object, as the spec does in its "Additional fields" section and in its definition of an extension point ("a field in a metadata document"). AcceptedField, ZarrV3CodecField and fields() used it for the value found at an extension point, a sense the spec has no word for. The second sense is now "declaration"; the docs already spoke of "codec declarations".

An earlier version of this PR also renamed "member" to "field" for a JSON name/value pair, to follow zarrs. That half is dropped. The v3 core spec uses "field", "key" and "member" for this without preference, RFC 8259 says "member", and the package already said "member", so there was nothing to fix.

What stays

  • "member" for a name/value pair of a JSON object, as before.
  • extra_fields, ExtraFieldDefinition, ZarrV3ExtensionField, must_understand_fields: the spec's sense. Prose that said "extra member" or "extension member" now says "extra field" and "extension field", after these names.
  • StructField and struct "field records"; pydantic's field sense (the ...MetadataField types in zarr_metadata.pydantic).
  • _accepted_field, _unclaimed_field and _refused_field, the pickle-rebuild functions, keep their names so existing pickles load.
  • The released CHANGELOG.md.

zarr-python itself imports none of the renamed names.

Checks

On the tree with upstream main merged in: the suite passes, pyright reports 0 errors over src and tests, ruff is clean apart from four unused-noqa findings that exist identically on main, and mkdocs build --strict passes.

Stack notes

Fork PR #434 (guide pages) is based on this branch and must be rebased when this branch changes.

🤖 Generated with Claude Code

d-v-b and others added 6 commits October 31, 2026 22:45
@d-v-b
ci(examples): run example scripts once in their own job (zarr-develop…
d105210 
…ers#4586)

* ci(examples): run example scripts once in their own job

Each example's PEP 723 header defines its environment, so running
tests/test_examples.py in every pytest matrix job repeated the same
work. Its header-rewriting helper also depended on the test
environment's packaging and tomlkit, which broke the min_deps job on
Python 3.12.3. A new `just examples` recipe uses `uv add --script` to
point each header at the local checkout, and one CI job runs it.

`uv add` resolves the header, and that showed two examples declaring
requires-python >=3.11 although zarr requires 3.12. Those headers now
say >=3.12. tomlkit was only used by the removed test, so it is
dropped from the test dependency group.

Assisted-by: ClaudeCode:claude-opus-5-5

* test(examples): run the example scripts through pytest

The previous commit ran the examples from a bash loop, which stops at
the first failing script, so one broken example hid the others. The
examples now run from tests/test_examples.py again, one test per
script. The tests are marked `examples` and skipped unless pytest gets
--run-examples, as slow_hypothesis tests are with
--run-slow-hypothesis, so the matrix jobs skip them. `just examples`
passes the option, and the CI job runs it in the test.py3.13-minimal
hatch environment.

Assisted-by: ClaudeCode:claude-opus-5-5

* chore(just): rename the examples recipe to test-examples

`just examples` could mean listing or building the examples.
`test-examples` says what the recipe does, and follows the
`<group>-<variant>` naming of recipes like `coverage-html` and
`docs-build`.

Assisted-by: ClaudeCode:claude-opus-5-5
@d-v-b @claude
feat(zarr-metadata): add Hypothesis strategies for metadata fields (z…
4a72dd4 
…arr-developers#4575)

* feat(zarr-metadata): add Hypothesis strategies for metadata fields

Add `zarr_metadata.testing.strategies`, behind a new `testing` extra.
It ships Hypothesis strategies that draw valid Zarr v3 metadata fields,
one for every codec, data type, chunk grid and chunk key encoding the
package defines that holds no other field.

- Each kind's strategy takes what its configurations depend on: a data
  type's fill values take its configuration, a chunk grid takes the
  array shape, and a codec takes the `Chunk` it is handed.
- `fields` draws every envelope spelling the spec allows, or only the
  canonical one.
- Strategies are a mapping keyed by definition, so an extension author
  can add strategies for their own definitions.

The tests read every draw back in `CORE_AND_EXTENSIONS` and require no
problems. They also check:
- that every definition in scope has a strategy, apart from the three
  that hold nested fields;
- reach, with targets derived from each configuration's TypedDict:
  each optional key present and absent, each `Literal` value, and a
  non-canonical spelling where one exists;
- fill-value spellings and envelope forms.

Strategies follow the spec where the package is looser. Core data types
are drawn only as bare strings, and regular-grid chunk lengths are never
zero ("Chunk sizes must be greater than zero"), although the package's
rules accept both today.

Assisted-by: ClaudeCode:claude-opus-5-5

* chore(zarr-metadata): number the strategies changelog fragment after #414

Assisted-by: ClaudeCode:claude-opus-5-5

* chore(zarr-metadata): number the strategies changelog fragment after PR 4575

The fragment was numbered after fork PR 414, so the changelog linked to
an unrelated upstream PR.

Assisted-by: ClaudeCode:claude-opus-5-5

* fix(zarr-metadata): draw a fresh empty configuration on every draw

`st.just({})` (crc32c) and `st.just(EmptyConfiguration())` (every data
type with nothing to configure) handed out one dict for every draw, and
`fields` puts the configuration in the field as it is. A test that
changed the configuration it drew changed every later draw, which
Hypothesis reports as a flaky strategy. Both are now
`st.builds(EmptyConfiguration)`.

Export `Configurations` and `NOTHING_KNOWN` from
`zarr_metadata.testing.strategies`: they appear in the signatures of
`DefinitionStrategy.unconstrained` and `codec_configurations`.

Assisted-by: ClaudeCode:claude-opus-5-5

* fix(zarr-metadata): check every drawn field, and draw hex scale_offset values

`fields` read a field only when asked for the canonical spelling, so a
caller's configurations the definition refuses were drawn silently in
the default spelling. Every field is now read, in a scope built once per
call rather than once per draw, and a refused one raises in both
spellings. A definition no Zarr v3 scope holds, such as a v2 codec, is
a `TypeError` when `fields` is called, not a `StopIteration` on a draw.

A float `scale_offset` codec's `offset` and `scale` are fill values of
its type, so they are now also drawn as the hex string of their bits.
The docstring no longer claims a non-zero scale makes decoding defined:
a tiny one still overflows.

The codec chunk test now draws chunks of an unknown data type and with
unknown lengths, which every codec takes.

Assisted-by: ClaudeCode:claude-opus-5-5

* fix(zarr-metadata): draw scale_offset for every number type, and widen Strategies keys

`scale_offset` drew nothing for complex numbers, numpy times and data
types the package does not define, though its rules refuse only data
types whose values are not numbers, and a numpy time "is compatible
with any codec that supports arrays of signed 64-bit integers". A numpy
time is now drawn as that integer, a complex number as a pair of
finite floats, and a type the package does not define takes the
identity configuration. None now means only what `CodecStrategy` says
it means: no configuration takes the chunk.

`Strategies` is keyed by `Any`: a mapping's key type is invariant, so a
mapping an extension author builds, keyed by a `CodecDefinition`, was
not a `Mapping[Definition[Any], ...]` to pyright.

A rectilinear dimension of unknown length may now be drawn with no
edges, which its rules accept.

Assisted-by: ClaudeCode:claude-opus-5-5

* refactor(zarr-metadata): share the strategies' empty configuration and rank cap

`EMPTY_CONFIGURATIONS` and `MAX_RANK` are defined once, in `_strategy`,
rather than once in each module that draws them. A numpy time's
`scale_offset` values are now drawn finite, never the integer numpy
reads as `NaT`, as the docstring says. The `fields` docstring now says
that a codec's chunk rules are not checked, since no chunk is known.

Assisted-by: ClaudeCode:claude-opus-5-5

* test(zarr-metadata): cover scale_offset over a data type the package does not define

The identity configuration `scale_offset` draws for a data type the
package does not define had no test, since the chunk test draws only
the package's own data types. A test now reads an extension `bfloat16`
in a scope of its own and checks the codec takes every draw.

Also splits the `_scope_of` error message across two literals and drops
a doubled blank line in `_data_type`.

Assisted-by: ClaudeCode:claude-opus-5-5

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@d-v-b
chore(deps): bump cast-value.rs (zarr-developers#4584)
be4d9d4 
* chore(deps): bump cast-value.rs to >=0.5.2

* chore(deps): raise the runtime cast-value-rs floor to 0.5.1

The previous commit raised the packaging floor to 0.5.1 but left the
runtime check at 0.4.2. cast-value-rs 0.5.0 makes casts exact at integer
and float range limits; 0.5.0 was never published to PyPI, so the floor
is 0.5.1. Also update the error message, the version-check test cases,
and uv.lock.

Assisted-by: ClaudeCode:claude-opus-5-5

* test(cast_value): derive version-check cases from the minimum

The cases hard-coded versions near the floor, so every floor bump meant
rewriting them. Build them from CAST_VALUE_RS_MIN_VERSION instead, and
drop cases that repeated the same comparison. A floor bump now touches
only pyproject.toml and the constant.

Assisted-by: ClaudeCode:claude-opus-5-5
@d-v-b
refactor(zarr-metadata)!: call a JSON key a field and an extension-po…
268a470 
…int value a declaration

Match zarrs and the v3 spec. A name/value pair in a JSON metadata object
is now a field everywhere (it was a member), which frees "field" from its
old term-of-art meaning: a value at an extension point that a scope
resolves, which is now a declaration.

The public names for that concept follow: AcceptedField and its siblings
become AcceptedDeclaration etc., the ZarrV3*Field aliases become
ZarrV3*Declaration, ZarrV3MetadataFieldJSON becomes ZarrV3DeclarationJSON,
a reading's fields() becomes declarations(), and unclaimed_fields becomes
unclaimed_declarations. Messages that said member now say field. The
pickle-rebuild functions keep their names so existing pickles load.

Assisted-by: ClaudeCode:claude-opus-5-5
@d-v-b
docs(zarr-metadata): say which fields hold declarations and complete …
c31062e 
…the rename's changelog

Review fixes for the field/declaration rename: an extra field is a
declaration written as the field alone, the array models' plain fields
are the ones that hold no declaration, must_understand_fields covers
extra fields only, and the context guide matches definitions to
declarations. The fragment drops four names that were never public and
adds spec_fields, the declaration wording of messages, and the renamed
JSON Schema $defs keys.

Assisted-by: ClaudeCode:claude-opus-5-5
@d-v-b
docs(zarr-metadata): number the field/declaration fragment after its PR
2b11adc 
Assisted-by: ClaudeCode:claude-opus-5-5
@d-v-b
docs(zarr-metadata): keep the field/declaration fragment unnumbered u…
59f0357 
…ntil it goes upstream

towncrier links fragments to upstream zarr-python PRs, and upstream #432
is an unrelated merged PR; this change has only a fork PR so far.

Assisted-by: ClaudeCode:claude-opus-5-5
@d-v-b d-v-b mentioned this pull request Nov 1, 2026
Closed
d-v-b and others added 7 commits November 1, 2026 18:40
@d-v-b @claude
feat(zarr-metadata)!: read what zarr-python writes in a ZARR_PYTHON_C…
bc177b3 
…ONTEXT scope (zarr-developers#4583)

* feat(zarr-metadata)!: read what zarr-python writes in a ZARR_PYTHON_CONTEXT scope

Add definitions for the extensions zarr-python writes. zarr-extensions
registers `fixed_length_utf32` and the `vlen-utf8` and `vlen-bytes`
codecs, so they join CORE_AND_EXTENSIONS_CONTEXT. zarr-python's own
`null_terminated_bytes` and `variable_length_bytes`, which no
specification registers, are only in the new ZARR_PYTHON_CONTEXT, so the
default scope stays spec-pure.

Rename CORE to CORE_CONTEXT and CORE_AND_EXTENSIONS to
CORE_AND_EXTENSIONS_CONTEXT, so that a scope's name says it is a context.

Fixes #423

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): number the changelog fragments for PR 426

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): number the changelog fragments for PR 4583

Assisted-by: ClaudeCode:claude-opus-5-5

* fix(zarr-metadata): keep the old scope names and tighten the string rules

Keep `CORE` and `CORE_AND_EXTENSIONS` importable from `zarr_metadata.v3`
and `zarr_metadata.v3.definition` as the same scopes with a
DeprecationWarning, so a consumer such as pydantic-zarr keeps working
across the rename.

Check that `vlen-utf8` encodes `string` and `vlen-bytes` encodes `bytes`
(or zarr-python's `variable_length_bytes`), as zarr-extensions says,
instead of accepting any data type whose values vary in size.

Do not count trailing null bytes against the size of a
`null_terminated_bytes` fill value, since they are padding. Spell a
`fixed_length_utf32` fill value without its trailing U+0000 padding, so
`"a"` and `"a\u0000"` have one canonical spelling.

Assisted-by: ClaudeCode:claude-opus-5-5

* feat(zarr-metadata): read zarr-python's raw_bytes and rename CORE_V2

Add zarr-python's `raw_bytes` data type (NumPy's `V`) to
ZARR_PYTHON_CONTEXT, so the scope reads every data type zarr-python
writes. Its names start with `ZarrPython`, since `RawBytes` already names
the spec's raw bits. A fill value longer than `length_bytes` is a problem,
because zarr-python cuts it short, and the canonical spelling pads it with
null bytes, as zarr-python writes it.

Rename CORE_V2 to CORE_V2_CONTEXT, so every scope's name ends in
`_CONTEXT`. The old name keeps working with a DeprecationWarning, through
the same `renamed_scope` helper as the v3 names, which moves to
`zarr_metadata._renamed`.

Share the base64 decoding and spelling of fill values in `_byte.py`, and
say that the vlen codecs' `configuration` key is optional, since
zarr-python writes an empty object.

Assisted-by: ClaudeCode:claude-opus-5-5

* refactor(zarr-metadata): declare the v2 scope's old name once

Move CORE_V2_CONTEXT and its table of old names into `v2/_core.py`, as
`v3/_core.py` holds the v3 scopes, so `zarr_metadata.v2` and
`zarr_metadata.v2.definition` share one table.

Say why a `fixed_length_utf32` fill value counts its trailing U+0000 code
points, as the spec requires, while `null_terminated_bytes` follows
zarr-python and does not, and test a value that only its padding makes too
long.

Assisted-by: ClaudeCode:claude-opus-5-5

* fix(zarr-metadata): give main's strategies the renamed scopes and new definitions

The Hypothesis strategies merged from main (zarr-developers#4575) imported `CORE`,
`CORE_AND_EXTENSIONS` and `CORE_V2` from modules that now hold only the
`_CONTEXT` names, and their coverage test requires a strategy for every
definition in `CORE_AND_EXTENSIONS_CONTEXT`. Rename the imports, and add
strategies for `fixed_length_utf32`, `vlen-utf8` and `vlen-bytes`; each
vlen codec draws nothing for a data type it does not read.

Assisted-by: ClaudeCode:claude-opus-5-5

* fix(zarr-metadata): draw zarr-python's own data types in the testing strategies

`DEFAULT_STRATEGIES` holds a strategy for each definition the package
defines, but `null_terminated_bytes`, `variable_length_bytes` and
`raw_bytes` had none, so `fields()` raised `LookupError` for them. Draw
each, and check the strategies against `ZARR_PYTHON_CONTEXT`, which
holds every definition. Say that the documents in
test_zarr_python_scope.py leave out the compressors zarr-python adds.

Assisted-by: ClaudeCode:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(zarr-metadata): pin the registered extensions to CORE_AND_EXTENSIONS_CONTEXT

The strategies are now checked against `ZARR_PYTHON_CONTEXT`, which no
longer proves that `fixed_length_utf32`, `vlen-utf8` and `vlen-bytes`
are in `CORE_AND_EXTENSIONS_CONTEXT`. Assert it directly.

Assisted-by: ClaudeCode:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(zarr-metadata): let the vlen strategies ask their codec's rules

Each vlen codec strategy named its compatible data types a second time;
draw nothing for exactly the chunks the codec's own chunk rules refuse,
so the two cannot drift. Draw `fixed_length_utf32` fill values with
trailing U+0000 padding too, which the canonical spelling removes.

Assisted-by: ClaudeCode:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@d-v-b
docs(zarr-metadata): number the field/declaration fragment after its …
53bf61f 
…fork PR

CI's changelog check requires an integer PR number, so an orphan
fragment cannot land. 432 is the fork PR; renumber it to the upstream
PR when this goes upstream.

Assisted-by: ClaudeCode:claude-opus-5-5
@Yi-111-a @d-v-b
fix(codecs): reshape flattened numcodecs filter output on encode (zar…
7e81965 
…r-developers#4560)

* fix(codecs): reshape flattened numcodecs filter output on encode (zarr-developersgh-4553)

* chore: add release notes fragment for zarr-developersgh-4553

* fix(codecs): reshape filter output to the resolved output shape

---------

Co-authored-by: Davis Bennett <davis.v.bennett@gmail.com>
@d-v-b
feat(zarr-metadata): re-export each v3 extension package's submodule …
c5039b9 
…names (zarr-developers#4588)

* feat(zarr-metadata): re-export each v3 extension package's submodule names

`zarr_metadata.v3.data_type`, `.codec`, `.chunk_grid` and
`.chunk_key_encoding` export every name their submodules export, so
`from zarr_metadata.v3.data_type import BoolDataTypeName` works again, as
it did before 0.6.0 (downstream zarrista imports the data type names that
way). Each submodule stays the name's home: the packages are aliases,
like the top-level namespace and the format front doors, and a new test
pins that each re-exports exactly its submodules' names as the same
objects. The naming checks skip the alias packages, whose names they
already check in the submodules.

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): number the re-export fragment after upstream zarr-developers#4588

Assisted-by: ClaudeCode:claude-opus-5-5
@clbarnes @d-v-b
Test against python 3.15 (zarr-developers#4544)
51a6b77 
Co-authored-by: Davis Bennett <davis.v.bennett@gmail.com>
@d-v-b
docs(zarr-metadata): document every public object (zarr-developers#4590)
9e44021 
* docs(zarr-metadata): document every public object

Add a docstring to every public object, and a test that fails on an
undocumented public object, a public module with no reference page, or a
v2 on-disk field docstring that drifts from its in-memory counterpart.

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): document the public API main added since the last pass

Cover the vlen codecs, the fixed-width string data types and the strategy
records, and render zarr_metadata.testing, which has no __all__.

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): renumber the changelog fragment to the merging PR

Drop the struct sentence, since main already renders that page.

Assisted-by: ClaudeCode:claude-opus-5-5
@d-v-b @claude
Merge upstream/main into refactor/zarr-metadata-field-terminology
6e2d66e 
Resolve the rename against the four zarr-metadata changes main gained:
the ZARR_PYTHON_CONTEXT scope and the *_CONTEXT constant names (zarr-developers#4583),
the v3 submodule re-exports (zarr-developers#4588), the Hypothesis strategies (zarr-developers#4575)
and the docstrings for every public object (zarr-developers#4590).

Every conflict was the rename on one side and new upstream text on the
other, so each is resolved as the upstream text with the rename applied.
The rename is carried into upstream's additions: the new docstrings say
"field" for a JSON key and "declaration" for an extension-point value,
and the strategies module's `fields` strategy is `declarations`, with
`FieldForm` now `DeclarationForm` in its tests. The zarr-developers#4575 changelog
fragment uses the new name, since neither name has been released.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@d-v-b d-v-b mentioned this pull request Nov 2, 2026
Draft
d-v-b and others added 3 commits November 2, 2026 11:23
@d-v-b
test(codecs): check numcodecs filters encode to their declared shape (z…
7105939 
…arr-developers#4591)

Replace the PackBits round-trip test, which passed with or without the
zarr-developersgh-4553 fix, with one parametrized test asserting that every numcodecs
filter's encoded chunk has the shape `resolve_metadata` declares. It
covers the 2-element PackBits chunk, where the packed length equals the
chunk size. Rewrite the 4560 changelog fragment without private names.

Assisted-by: ClaudeCode:claude-opus-5-5
@d-v-b @claude
docs(zarr-metadata): stop claiming the v3 spec prefers "field" over "…
bd13c7a 
…member"

The v3 core spec uses both words for a name/value pair in a metadata
object ("the member chunk_shape", "the fill_value metadata field"), so
only zarrs motivates the choice. Also say "context", not "scope".

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@d-v-b @claude
refactor(zarr-metadata)!: keep "member" for a JSON name/value pair
720bd54 
Drop the member-to-field half of the rename. The v3 core spec uses
"field", "key" and "member" for a name/value pair without preference,
RFC 8259 says "member", and the package already said "member", so only
zarrs motivated the change. The field-to-declaration half stays: it
removes the collision between the extension-point sense of "field" and
the JSON sense in extra_fields, ExtraFieldDefinition and friends.

Every line that upstream main writes with "member" is restored by
aligning the two trees token by token. spec_fields is spec_members
again, member_changes keeps its name, and ZarrV3ConsolidatedMetadata
takes member= again. Prose that said "extra member" or "extension
member" now says "extra field" and "extension field", after the names.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@d-v-b d-v-b changed the title refactor(zarr-metadata)!: call a JSON key a field and an extension-point value a declaration refactor(zarr-metadata)!: call an extension-point value a declaration Nov 2, 2026
d-v-b and others added 6 commits November 2, 2026 11:58
@d-v-b @claude
refactor(zarr-metadata): finish the member and declaration wording ro…
c1a9f11 
…borev flagged

Four docstrings said "the fields that hold no declaration" for members;
the pickle-rebuild comment said the functions keep their _declaration
names when they keep their _field names; and two test helpers in the
strategies tests still said "fields" for declarations.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@d-v-b @claude
test(zarr-metadata): name the schema-acceptance test after the declar…
54c30cb 
…ation it reads

Last test in the package whose name said "field" for a declaration.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@d-v-b @claude
refactor(zarr-metadata): restore "member" where the rename changed a …
8a7c6bf 
…name in both senses

Thirteen test names changed in both the member and the declaration
sense at once, so the token alignment that restored "member" skipped
them; they take their upstream spelling with only the declaration half
applied. Seven docstrings get the same treatment, and the two envelope
docstrings that said "an extra field" for an undeclared envelope member
now say "an extra envelope member", so "extra field" keeps one meaning.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@d-v-b @claude
docs(zarr-metadata): say the model checks the members of a document
fb171da 
Last module docstring with "field" in the name/value-pair sense.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@d-v-b
Merge branch 'main' into refactor/zarr-metadata-field-terminology
40ce94b
@d-v-b @claude
docs(zarr-metadata): number the declaration-rename fragment after ups…
c3b822f 
…tream PR 4592

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
d-v-b added a commit that referenced this pull request Nov 2, 2026
@d-v-b @claude
refactor(zarr-metadata)!: call an extension-point value a declaration (…
310075a 
…zarr-developers#4592)

* refactor(zarr-metadata)!: call a JSON key a field and an extension-point value a declaration

Match zarrs and the v3 spec. A name/value pair in a JSON metadata object
is now a field everywhere (it was a member), which frees "field" from its
old term-of-art meaning: a value at an extension point that a scope
resolves, which is now a declaration.

The public names for that concept follow: AcceptedField and its siblings
become AcceptedDeclaration etc., the ZarrV3*Field aliases become
ZarrV3*Declaration, ZarrV3MetadataFieldJSON becomes ZarrV3DeclarationJSON,
a reading's fields() becomes declarations(), and unclaimed_fields becomes
unclaimed_declarations. Messages that said member now say field. The
pickle-rebuild functions keep their names so existing pickles load.

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): say which fields hold declarations and complete the rename's changelog

Review fixes for the field/declaration rename: an extra field is a
declaration written as the field alone, the array models' plain fields
are the ones that hold no declaration, must_understand_fields covers
extra fields only, and the context guide matches definitions to
declarations. The fragment drops four names that were never public and
adds spec_fields, the declaration wording of messages, and the renamed
JSON Schema $defs keys.

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): number the field/declaration fragment after its PR

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): keep the field/declaration fragment unnumbered until it goes upstream

towncrier links fragments to upstream zarr-python PRs, and upstream #432
is an unrelated merged PR; this change has only a fork PR so far.

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): number the field/declaration fragment after its fork PR

CI's changelog check requires an integer PR number, so an orphan
fragment cannot land. 432 is the fork PR; renumber it to the upstream
PR when this goes upstream.

Assisted-by: ClaudeCode:claude-opus-5-5

* docs(zarr-metadata): stop claiming the v3 spec prefers "field" over "member"

The v3 core spec uses both words for a name/value pair in a metadata
object ("the member chunk_shape", "the fill_value metadata field"), so
only zarrs motivates the choice. Also say "context", not "scope".

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* refactor(zarr-metadata)!: keep "member" for a JSON name/value pair

Drop the member-to-field half of the rename. The v3 core spec uses
"field", "key" and "member" for a name/value pair without preference,
RFC 8259 says "member", and the package already said "member", so only
zarrs motivated the change. The field-to-declaration half stays: it
removes the collision between the extension-point sense of "field" and
the JSON sense in extra_fields, ExtraFieldDefinition and friends.

Every line that upstream main writes with "member" is restored by
aligning the two trees token by token. spec_fields is spec_members
again, member_changes keeps its name, and ZarrV3ConsolidatedMetadata
takes member= again. Prose that said "extra member" or "extension
member" now says "extra field" and "extension field", after the names.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* refactor(zarr-metadata): finish the member and declaration wording roborev flagged

Four docstrings said "the fields that hold no declaration" for members;
the pickle-rebuild comment said the functions keep their _declaration
names when they keep their _field names; and two test helpers in the
strategies tests still said "fields" for declarations.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* test(zarr-metadata): name the schema-acceptance test after the declaration it reads

Last test in the package whose name said "field" for a declaration.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* refactor(zarr-metadata): restore "member" where the rename changed a name in both senses

Thirteen test names changed in both the member and the declaration
sense at once, so the token alignment that restored "member" skipped
them; they take their upstream spelling with only the declaration half
applied. Seven docstrings get the same treatment, and the two envelope
docstrings that said "an extra field" for an undeclared envelope member
now say "an extra envelope member", so "extra field" keeps one meaning.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(zarr-metadata): say the model checks the members of a document

Last module docstring with "field" in the name/value-pair sense.

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(zarr-metadata): number the declaration-rename fragment after upstream PR 4592

Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
@d-v-b

d-v-b commented Nov 2, 2026

Copy link
Copy Markdown
Owner Author

🤖 AI text below 🤖

Superseded by zarr-developers#4592, which merged this branch upstream.

@d-v-b d-v-b closed this Nov 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@d-v-b @Yi-111-a @clbarnes