refactor(zarr-metadata): make every public type name parse against a naming grammar

Three grammars now cover the public surface, enforced by a conformance
test that walks every public module's __all__:

- core document/model names: ZarrV{2,3} + entity + optional role suffix
  (JSON / JSONPartial / Partial / StoreKey)
- extension-entity names: registered entity + exactly one role suffix
  (CodecMetadata, DataTypeName, FillValue, ...)
- a closed standalone-vocabulary allowlist for role-less scalar and
  diagnostic types, with a staleness guard

The three .z-file document types were the only names that fit no grammar
and are renamed: ZArrayMetadata -> ZarrV2ZArrayJSON, ZGroupMetadata ->
ZarrV2ZGroupJSON, ZAttrsMetadata -> ZarrV2ZAttrsJSON. The leading V2 of
V2ChunkKeyEncodingMetadata is that encoding's registered entity name, not
a format version; its module docstring now says so.

Assisted-by: ClaudeCode:claude-fable-5

Author: d-v-b

packages/zarr-metadata/changes/4119.removal.md

@@ -17,6 +17,9 @@ entity names are reserved for the `zarr_metadata.model` dataclasses:
 - `DataTypeMetadataV2` → `ZarrV2DataTypeMetadata`
 - `ArrayOrderV2` → `ZarrV2ArrayOrder`
 - `ArrayDimensionSeparatorV2` → `ZarrV2ArrayDimensionSeparator`
+- `ZArrayMetadata` → `ZarrV2ZArrayJSON` (the strict on-disk `.zarray` document)
+- `ZGroupMetadata` → `ZarrV2ZGroupJSON` (the strict on-disk `.zgroup` document)
+- `ZAttrsMetadata` → `ZarrV2ZAttrsJSON` (the `.zattrs` document)
 
 The old names are removed, not aliased. The `zarr_metadata.pydantic` field
 types take the bare entity names (`ZarrV3ArrayMetadata`, ...), matching the
@@ -30,3 +33,9 @@ snake_case functions put it last (`ARRAY_METADATA_STORE_KEY_V2`,
 whose bare name is taken by (or reserved for) a `zarr_metadata.model`
 dataclass; raw field-level types the models hold verbatim
 (`ZarrV2CodecMetadata`, `ZarrV3ExtensionField`) keep their bare names.
+Extension-entity types put the registered entity name first and end in
+exactly one role suffix (`BloscCodecMetadata`, `Uint8DataTypeName`) — the
+`V2` in `V2ChunkKeyEncodingMetadata` is that encoding's entity name, not a
+format version, which is always spelled `ZarrV2`/`ZarrV3`. Every public
+type name is checked against this grammar by
+`tests/test_public_api.py::test_public_type_names_comply_with_naming_grammar`.

packages/zarr-metadata/src/zarr_metadata/__init__.py

@@ -22,20 +22,20 @@
 from zarr_metadata.v2.array import (
     ARRAY_DIMENSION_SEPARATOR_V2,
     ARRAY_ORDER_V2,
-    ZArrayMetadata,
     ZarrV2ArrayDimensionSeparator,
     ZarrV2ArrayMetadataJSON,
     ZarrV2ArrayMetadataJSONPartial,
     ZarrV2ArrayOrder,
     ZarrV2DataTypeMetadata,
+    ZarrV2ZArrayJSON,
 )
-from zarr_metadata.v2.attributes import ZAttrsMetadata
+from zarr_metadata.v2.attributes import ZarrV2ZAttrsJSON
 from zarr_metadata.v2.codec import ZarrV2CodecMetadata
 from zarr_metadata.v2.consolidated import ZarrV2ConsolidatedMetadataJSON
 from zarr_metadata.v2.group import (
     ZarrV2GroupMetadataJSON,
     ZarrV2GroupMetadataJSONPartial,
-    ZGroupMetadata,
+    ZarrV2ZGroupJSON,
 )
 from zarr_metadata.v3._common import ZarrV3MetadataFieldJSON
 from zarr_metadata.v3.array import (
@@ -338,9 +338,6 @@
     "V2ChunkKeyEncodingName",
     "V2ChunkKeyEncodingSeparator",
     "ValidationProblem",
-    "ZArrayMetadata",
-    "ZAttrsMetadata",
-    "ZGroupMetadata",
     "ZarrV2ArrayDimensionSeparator",
     "ZarrV2ArrayMetadata",
     "ZarrV2ArrayMetadataJSON",
@@ -355,6 +352,9 @@
     "ZarrV2GroupMetadataJSON",
     "ZarrV2GroupMetadataJSONPartial",
     "ZarrV2GroupMetadataPartial",
+    "ZarrV2ZArrayJSON",
+    "ZarrV2ZAttrsJSON",
+    "ZarrV2ZGroupJSON",
     "ZarrV3ArrayMetadata",
     "ZarrV3ArrayMetadataJSON",
     "ZarrV3ArrayMetadataJSONPartial",

packages/zarr-metadata/src/zarr_metadata/v2/__init__.py

@@ -1,26 +1,26 @@
 """Zarr v2 metadata types."""
 
 from zarr_metadata.v2.array import (
-    ZArrayMetadata,
     ZarrV2ArrayDimensionSeparator,
     ZarrV2ArrayMetadataJSON,
     ZarrV2ArrayOrder,
     ZarrV2DataTypeMetadata,
+    ZarrV2ZArrayJSON,
 )
-from zarr_metadata.v2.attributes import ZAttrsMetadata
+from zarr_metadata.v2.attributes import ZarrV2ZAttrsJSON
 from zarr_metadata.v2.codec import ZarrV2CodecMetadata
 from zarr_metadata.v2.consolidated import ZarrV2ConsolidatedMetadataJSON
-from zarr_metadata.v2.group import ZarrV2GroupMetadataJSON, ZGroupMetadata
+from zarr_metadata.v2.group import ZarrV2GroupMetadataJSON, ZarrV2ZGroupJSON
 
 __all__ = [
-    "ZArrayMetadata",
-    "ZAttrsMetadata",
-    "ZGroupMetadata",
     "ZarrV2ArrayDimensionSeparator",
     "ZarrV2ArrayMetadataJSON",
     "ZarrV2ArrayOrder",
     "ZarrV2CodecMetadata",
     "ZarrV2ConsolidatedMetadataJSON",
     "ZarrV2DataTypeMetadata",
     "ZarrV2GroupMetadataJSON",
+    "ZarrV2ZArrayJSON",
+    "ZarrV2ZAttrsJSON",
+    "ZarrV2ZGroupJSON",
 ]

packages/zarr-metadata/src/zarr_metadata/v2/array.py

@@ -55,13 +55,13 @@
 """Tuple of permitted values for the `dimension_separator` field of v2 array metadata."""
 
 
-class ZArrayMetadata(TypedDict):
+class ZarrV2ZArrayJSON(TypedDict):
     """
     On-disk `.zarray` file content.
 
     Strict shape of the JSON document persisted at `<path>/.zarray` for
     a v2 array. User attributes live in a sibling `.zattrs` file and are
-    NOT part of this type; see `ZAttrsMetadata`.
+    NOT part of this type; see `ZarrV2ZAttrsJSON`.
 
     See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
     """
@@ -87,7 +87,7 @@ class ZarrV2ArrayMetadataJSON(TypedDict):
     `attributes` field so a single TypedDict represents the complete
     in-memory state of a v2 array node. Consumers that read or write a
     real `.zarray` file should split / merge `attributes` accordingly,
-    or use `ZArrayMetadata` (strict on-disk) plus `ZAttrsMetadata` directly.
+    or use `ZarrV2ZArrayJSON` (strict on-disk) plus `ZarrV2ZAttrsJSON` directly.
 
     See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
     """
@@ -152,10 +152,10 @@ class ZarrV2ArrayMetadataJSONPartial(TypedDict, total=False):
 __all__ = [
     "ARRAY_DIMENSION_SEPARATOR_V2",
     "ARRAY_ORDER_V2",
-    "ZArrayMetadata",
     "ZarrV2ArrayDimensionSeparator",
     "ZarrV2ArrayMetadataJSON",
     "ZarrV2ArrayMetadataJSONPartial",
     "ZarrV2ArrayOrder",
     "ZarrV2DataTypeMetadata",
+    "ZarrV2ZArrayJSON",
 ]

packages/zarr-metadata/src/zarr_metadata/v2/attributes.py

@@ -7,16 +7,16 @@
 
 from zarr_metadata._common import JSONValue
 
-ZAttrsMetadata = Mapping[str, JSONValue]
+ZarrV2ZAttrsJSON = Mapping[str, JSONValue]
 """On-disk `.zattrs` file content.
 
 A JSON object holding user-defined attributes for a v2 array or group.
 Spec-defined keys for arrays / groups live in sibling `.zarray` / `.zgroup`
-files (modeled by `ZArrayMetadata` / `ZGroupMetadata`). This type does not
+files (modeled by `ZarrV2ZArrayJSON` / `ZarrV2ZGroupJSON`). This type does not
 constrain the keys or values of the attributes mapping.
 """
 
 
 __all__ = [
-    "ZAttrsMetadata",
+    "ZarrV2ZAttrsJSON",
 ]

packages/zarr-metadata/src/zarr_metadata/v2/consolidated.py

@@ -10,9 +10,9 @@
 
 from typing_extensions import TypedDict
 
-from zarr_metadata.v2.array import ZArrayMetadata
-from zarr_metadata.v2.attributes import ZAttrsMetadata
-from zarr_metadata.v2.group import ZGroupMetadata
+from zarr_metadata.v2.array import ZarrV2ZArrayJSON
+from zarr_metadata.v2.attributes import ZarrV2ZAttrsJSON
+from zarr_metadata.v2.group import ZarrV2ZGroupJSON
 
 
 class ZarrV2ConsolidatedMetadataJSON(TypedDict):
@@ -24,17 +24,17 @@ class ZarrV2ConsolidatedMetadataJSON(TypedDict):
     that path. The keys include the filename suffix, not just the node
     path; the value's shape is determined by which file the key points at:
 
-    - `<path>/.zarray` -> `ZArrayMetadata`
-    - `<path>/.zgroup` -> `ZGroupMetadata`
-    - `<path>/.zattrs` -> `ZAttrsMetadata`
+    - `<path>/.zarray` -> `ZarrV2ZArrayJSON`
+    - `<path>/.zgroup` -> `ZarrV2ZGroupJSON`
+    - `<path>/.zattrs` -> `ZarrV2ZAttrsJSON`
 
     The TypedDict cannot discriminate the value shape on the key suffix
     at the type level; consumers should narrow at runtime by inspecting
     `key.endswith(".zarray")` etc.
     """
 
     zarr_consolidated_format: int
-    metadata: Mapping[str, ZArrayMetadata | ZGroupMetadata | ZAttrsMetadata]
+    metadata: Mapping[str, ZarrV2ZArrayJSON | ZarrV2ZGroupJSON | ZarrV2ZAttrsJSON]
 
 
 __all__ = [

packages/zarr-metadata/src/zarr_metadata/v2/group.py

@@ -11,14 +11,14 @@
 from zarr_metadata._common import JSONValue
 
 
-class ZGroupMetadata(TypedDict):
+class ZarrV2ZGroupJSON(TypedDict):
     """
     On-disk `.zgroup` file content.
 
     Strict shape of the JSON document persisted at `<path>/.zgroup` for
     a v2 group. The spec defines exactly one field. User attributes live
     in a sibling `.zattrs` file and are NOT part of this type; see
-    `ZAttrsMetadata`.
+    `ZarrV2ZAttrsJSON`.
 
     See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
     """
@@ -34,8 +34,8 @@ class ZarrV2GroupMetadataJSON(TypedDict):
     and `.zattrs` (user attributes). On disk these are persisted as two
     separate files; this type folds them so a single TypedDict represents
     the complete in-memory state of a v2 group node. Consumers that read
-    or write the real on-disk files should use `ZGroupMetadata` (strict
-    `.zgroup`) plus `ZAttrsMetadata` directly.
+    or write the real on-disk files should use `ZarrV2ZGroupJSON` (strict
+    `.zgroup`) plus `ZarrV2ZAttrsJSON` directly.
 
     See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
     """
@@ -75,7 +75,7 @@ class ZarrV2GroupMetadataJSONPartial(TypedDict, total=False):
 
 
 __all__ = [
-    "ZGroupMetadata",
     "ZarrV2GroupMetadataJSON",
     "ZarrV2GroupMetadataJSONPartial",
+    "ZarrV2ZGroupJSON",
 ]

packages/zarr-metadata/src/zarr_metadata/v3/chunk_key_encoding/v2.py

@@ -4,6 +4,12 @@
 Intended only to allow existing v2 arrays to be converted to v3 without
 having to rename chunks. Not recommended for new arrays.
 
+Naming note: these are Zarr **v3** types. The leading `V2` in
+`V2ChunkKeyEncodingMetadata` (and friends) is the encoding's registered
+*entity name* (`"v2"`), not the format-version marker that `ZarrV2...`
+names carry — this package's version-prefixed names always spell it
+`ZarrV2` / `ZarrV3`.
+
 See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#chunk-key-encoding
 """
 

packages/zarr-metadata/tests/test_public_api.py

@@ -1,5 +1,7 @@
 """Test that the curated front-door names are accessible from the top-level zarr_metadata package."""
 
+import importlib
+import pkgutil
 import re
 from typing import get_args
 
@@ -23,12 +25,12 @@ def _group_rank(s: str) -> int:
     # Category A — metadata-document types
     "ZarrV2ArrayMetadataJSON",
     "ZarrV2ArrayMetadataJSONPartial",
-    "ZArrayMetadata",
+    "ZarrV2ZArrayJSON",
     "ZarrV2GroupMetadataJSON",
     "ZarrV2GroupMetadataJSONPartial",
-    "ZGroupMetadata",
+    "ZarrV2ZGroupJSON",
     "ZarrV2ConsolidatedMetadataJSON",
-    "ZAttrsMetadata",
+    "ZarrV2ZAttrsJSON",
     "ZarrV2CodecMetadata",
     "ZarrV3ArrayMetadataJSON",
     "ZarrV3ArrayMetadataJSONPartial",
@@ -217,6 +219,109 @@ def test_all_is_grouped_and_unique() -> None:
     assert len(zm.__all__) == len(set(zm.__all__))
 
 
+# --- naming grammar ---------------------------------------------------------
+
+# Core document/model names: the format version comes first (`ZarrV2` /
+# `ZarrV3`), then the CamelCase entity, then an optional role suffix
+# (`JSON`, `JSONPartial`, `Partial`, `StoreKey`) — validated loosely here
+# because `JSON` decomposes into single-letter words under any strict
+# word-splitting regex.
+_CORE_NAME = re.compile(r"^ZarrV[23](?:[A-Z][a-z0-9]*)+$")
+
+# Zarr v3 extension-entity names: the registered entity comes first (`Blosc`,
+# `Uint8`, ... — `V2` here is the *entity name* of the v2-compatibility chunk
+# key encoding, not a format-version marker, which is always spelled
+# `ZarrV2`/`ZarrV3`), followed by exactly one role suffix.
+_EXTENSION_ROLES = (
+    "CodecConfiguration",
+    "CodecMetadata",
+    "CodecName",
+    "CodecObject",
+    "ChunkGridConfiguration",
+    "ChunkGridMetadata",
+    "ChunkGridName",
+    "ChunkGridObject",
+    "ChunkKeyEncodingConfiguration",
+    "ChunkKeyEncodingMetadata",
+    "ChunkKeyEncodingName",
+    "ChunkKeyEncodingObject",
+    "ChunkKeyEncodingSeparator",
+    "DataTypeName",
+    "FillValue",
+    "Configuration",
+    "Component",
+)
+_EXTENSION_NAME = re.compile(r"^(?:[A-Z][a-z0-9]*)+?(?:" + "|".join(_EXTENSION_ROLES) + r")$")
+
+# Standalone vocabulary: scalar Literal aliases, structural helper shapes, and
+# the validation diagnostics. Closed by hand — a new name belongs here only if
+# it is genuinely role-less; anything document- or entity-shaped must fit the
+# grammars above instead.
+_STANDALONE_VOCAB = frozenset(
+    {
+        "Base64Bytes",
+        "BloscCName",
+        "BloscShuffle",
+        "CastOutOfRangeMode",
+        "CastRoundingMode",
+        "Endianness",
+        "HexFloat16",
+        "HexFloat32",
+        "HexFloat64",
+        "JSONValue",
+        "MetadataValidationError",
+        "NumpyDatetime64",
+        "NumpyTimeUnit",
+        "NumpyTimedelta64",
+        "ProblemKind",
+        "RectilinearDimSpec",
+        "ScalarMap",
+        "ScalarMapEntry",
+        "ShardingIndexLocation",
+        "Struct",
+        "StructField",
+        "ValidationProblem",
+    }
+)
+
+
+def _public_type_names() -> set[tuple[str, str]]:
+    """Every (module, CamelCase name) pair exported via a public `__all__`."""
+    module_names = {"zarr_metadata"}
+    for info in pkgutil.walk_packages(zm.__path__, prefix="zarr_metadata."):
+        if not any(part.startswith("_") for part in info.name.split(".")[1:]):
+            module_names.add(info.name)
+    out: set[tuple[str, str]] = set()
+    for module_name in module_names:
+        module = importlib.import_module(module_name)
+        for name in getattr(module, "__all__", ()):
+            if name.startswith("_") or name.isupper() or name.islower():
+                continue
+            out.add((module_name, name))
+    return out
+
+
+def test_public_type_names_comply_with_naming_grammar() -> None:
+    """Every public type name parses against the package naming grammar:
+    version-first core names, entity-plus-role extension names, or the closed
+    standalone vocabulary."""
+    exported = _public_type_names()
+    violations = [
+        f"{module}.{name}"
+        for module, name in sorted(exported)
+        if name not in _STANDALONE_VOCAB
+        and not _CORE_NAME.match(name)
+        and not _EXTENSION_NAME.match(name)
+    ]
+    assert not violations, f"names outside the naming grammar: {violations}"
+
+
+def test_standalone_vocab_is_not_stale() -> None:
+    """Every allowlisted vocabulary name is still actually exported."""
+    exported_names = {name for _, name in _public_type_names()}
+    assert exported_names >= _STANDALONE_VOCAB
+
+
 def test_promoted_pairs_drift() -> None:
     pairs = [
         (zm.ENDIANNESS, zm.Endianness),

packages/zarr-metadata/tests/v2/array/test_fixtures.py

@@ -1,7 +1,7 @@
 """Decode v2 array metadata fixtures via pydantic.
 
 Each `*.json` file in this directory is a representative on-disk
-`.zarray` that should validate cleanly as `ZArrayMetadata` (the strict
+`.zarray` that should validate cleanly as `ZarrV2ZArrayJSON` (the strict
 on-disk shape). User attributes live in sibling `.zattrs` files and are
 not part of these fixtures.
 
@@ -17,11 +17,11 @@
 import pytest
 from pydantic import TypeAdapter
 
-from zarr_metadata.v2.array import ZArrayMetadata
+from zarr_metadata.v2.array import ZarrV2ZArrayJSON
 
 FIXTURES_DIR = Path(__file__).parent
 FIXTURES = sorted(FIXTURES_DIR.glob("*.json"))
-ADAPTER = TypeAdapter(ZArrayMetadata)
+ADAPTER = TypeAdapter(ZarrV2ZArrayJSON)
 
 
 @pytest.mark.parametrize("fixture", FIXTURES, ids=lambda p: p.stem)