zarr_metadata.pydantic

zarr_metadata.pydantic

Optional pydantic (v2) integration: field types over the core models.

Importing this module requires pydantic; the core package deliberately does not depend on it, so this module is never imported by zarr_metadata itself.

Each exported name is an Annotated field type over the corresponding core model class — the instances ARE the core classes, so values interoperate freely with non-pydantic code (equality, isinstance, nesting). Validation delegates to the library: a raw document is judged by zarr_metadata.rules (structure and composition together) and then normalized through from_json, so pydantic's field-level coercion can never bypass either layer; an existing model instance passes through unchanged, and serialization emits the canonical document via to_json. MetadataValidationError subclasses ValueError, so a failed parse surfaces as a pydantic ValidationError carrying the loc-annotated problem messages.

The v2 consolidated field type and the bare metadata-field type carry no composition rules and are validated structurally.

Usage:

import zarr_metadata.pydantic as zmp

class ArrayManifest(BaseModel):
    path: str
    metadata: zmp.ZarrV3ArrayMetadata

Static type checkers see each field type as its core model class, so manifest.metadata is a zarr_metadata.model.ZarrV3ArrayMetadata.

ZarrV2ArrayMetadata module-attribute

ZarrV2ArrayMetadata = Annotated[
    InstanceOf[_model.ZarrV2ArrayMetadata],
    BeforeValidator(
        _coerce_to(
            _model.ZarrV2ArrayMetadata,
            _judged_by(
                _rules.validate_array_metadata_v2,
                _model.ZarrV2ArrayMetadata.from_json,
            ),
        ),
        json_schema_input_type=_ZarrV2ArrayMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV2ArrayMetadata.to_json,
        return_type=_ZarrV2ArrayMetadataSchema,
    ),
]

Field type for a v2 array metadata document (merged .zarray + .zattrs form).

ZarrV2ConsolidatedMetadata module-attribute

ZarrV2ConsolidatedMetadata = Annotated[
    InstanceOf[_model.ZarrV2ConsolidatedMetadata],
    BeforeValidator(
        _coerce_to(
            _model.ZarrV2ConsolidatedMetadata,
            _model.ZarrV2ConsolidatedMetadata.from_json,
        ),
        json_schema_input_type=_ZarrV2ConsolidatedMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV2ConsolidatedMetadata.to_json,
        return_type=_ZarrV2ConsolidatedMetadataSchema,
    ),
]

Field type for a v2 .zmetadata document.

ZarrV2GroupMetadata module-attribute

ZarrV2GroupMetadata = Annotated[
    InstanceOf[_model.ZarrV2GroupMetadata],
    BeforeValidator(
        _coerce_to(
            _model.ZarrV2GroupMetadata,
            _judged_by(
                _rules.validate_group_metadata_v2,
                _model.ZarrV2GroupMetadata.from_json,
            ),
        ),
        json_schema_input_type=_ZarrV2GroupMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV2GroupMetadata.to_json,
        return_type=_ZarrV2GroupMetadataSchema,
    ),
]

Field type for a v2 group metadata document (merged .zgroup + .zattrs form).

ZarrV3ArrayMetadata module-attribute

ZarrV3ArrayMetadata = Annotated[
    InstanceOf[_model.ZarrV3ArrayMetadata],
    BeforeValidator(
        _coerce_to(
            _model.ZarrV3ArrayMetadata,
            _judged_by(
                _rules.validate_array_metadata_v3,
                _model.ZarrV3ArrayMetadata.from_json,
            ),
        ),
        json_schema_input_type=_ZarrV3ArrayMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV3ArrayMetadata.to_json,
        return_type=_ZarrV3ArrayMetadataSchema,
    ),
]

Field type for a v3 array metadata document (zarr.json content).

ZarrV3ConsolidatedMetadata module-attribute

ZarrV3ConsolidatedMetadata = Annotated[
    InstanceOf[_model.ZarrV3ConsolidatedMetadata],
    BeforeValidator(
        _coerce_to(
            _model.ZarrV3ConsolidatedMetadata,
            _judged_by(
                _validate_consolidated_v3,
                _model.ZarrV3ConsolidatedMetadata.from_json,
            ),
        ),
        json_schema_input_type=_ZarrV3ConsolidatedMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV3ConsolidatedMetadata.to_json,
        return_type=_ZarrV3ConsolidatedMetadataSchema,
    ),
]

Field type for v3 inline consolidated metadata.

ZarrV3GroupMetadata module-attribute

ZarrV3GroupMetadata = Annotated[
    InstanceOf[_model.ZarrV3GroupMetadata],
    BeforeValidator(
        _coerce_to(
            _model.ZarrV3GroupMetadata,
            _judged_by(
                _rules.validate_group_metadata_v3,
                _model.ZarrV3GroupMetadata.from_json,
            ),
        ),
        json_schema_input_type=_ZarrV3GroupMetadataSchema,
    ),
    PlainSerializer(
        _model.ZarrV3GroupMetadata.to_json,
        return_type=_ZarrV3GroupMetadataSchema,
    ),
]

Field type for a v3 group metadata document (zarr.json content).

ZarrV3MetadataField module-attribute

ZarrV3MetadataField = Annotated[
    InstanceOf[_model.ZarrV3NamedConfig],
    BeforeValidator(
        _coerce_to(
            _model.ZarrV3NamedConfig,
            _model.ZarrV3NamedConfig.from_json,
        ),
        json_schema_input_type=_ZarrV3MetadataFieldSchema,
    ),
    PlainSerializer(
        _model.ZarrV3NamedConfig.to_json,
        return_type=_ZarrV3MetadataFieldSchema,
    ),
]

Field type for one normalized v3 metadata extension envelope.

__all__ module-attribute

__all__ = [
    "ZarrV2ArrayMetadata",
    "ZarrV2ConsolidatedMetadata",
    "ZarrV2GroupMetadata",
    "ZarrV3ArrayMetadata",
    "ZarrV3ConsolidatedMetadata",
    "ZarrV3GroupMetadata",
    "ZarrV3MetadataField",
]