Skip to content

docs(zarr-metadata): say that to_json returns arrays as tuples - #4608

Merged
d-v-b merged 3 commits into
zarr-developers:mainfrom
d-v-b:docs/zarr-metadata-to-json-tuples
Nov 9, 2026
Merged

d-v-b merged 3 commits into
zarr-developers:mainfrom
d-v-b:docs/zarr-metadata-to-json-tuples

Conversation

@d-v-b

@d-v-b d-v-b commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

This is a docs-only change that clarifies that to_json tuplizes JSON arrays. So the output document might not match exactly the input document

[ x ] I'm a person

🤖 AI text below 🤖

Agent summary

The to_json docstrings and the models guide now say what to_json returns: a copy in which each JSON array is a tuple, as the package's JSON types spell an array, so it does not compare equal to what json.loads returns. They point to comparing models instead. The guide had said to_json returns plain containers.

A downstream user (refkv) reported that ZarrV3ArrayMetadata.from_json(doc).to_json() == doc is false and that isinstance(x, list) checks on the result fail. Tuples are deliberate: every JSON TypedDict in the package declares arrays as tuple[...], and to_json returns what its type declares, as pydantic's model_dump() keeps tuple fields as tuples. The docs were what was wrong.

  • The six model to_json docstrings (v3 array, group, consolidated metadata; v2 array, group, .zmetadata) say each array is a tuple and each object a new dict, and point to from_json(document) == model for comparison.
  • docs/models.md replaces "to_json returns plain containers" with the same explanation, noting that model comparison also treats an omitted default as equal to the default written out.

The agent rebased the branch onto main after #4605 split the landing page into guide pages; the sentence it corrects moved from docs/index.md to docs/models.md. just check in packages/zarr-metadata passes.

🤖 Generated with Claude Code

d-v-b and others added 2 commits November 9, 2026 11:55
The guide said `to_json` returns plain containers, while another section
said it returns tuples. Each model's `to_json` docstring now says that
every JSON array is a tuple, as the package's JSON types spell one, so
the result does not compare equal to `json.loads` output, and points to
comparing models instead. Prompted by refkv's report.

Assisted-by: ClaudeCode:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Assisted-by: ClaudeCode:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
@github-actions github-actions Bot added needs release notes Automatically applied to PRs which haven't added release notes zarr-metadata Specific to the zarr-metadata sub-package labels Nov 9, 2026
@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 zarr-metadata | 🛠️ Build #35753893 | 📁 Comparing 1c0d0a1 against latest (9783489)

  🔍 Preview build  

2 files changed
± models/index.html
± api/model/index.html

@d-v-b
d-v-b marked this pull request as ready for review November 9, 2026 12:47
@d-v-b
d-v-b merged commit e12ca8d into zarr-developers:main Nov 9, 2026
45 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs release notes Automatically applied to PRs which haven't added release notes zarr-metadata Specific to the zarr-metadata sub-package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant