Validation

validate() checks any fileset (an image, a plate, a well or a bioformats2raw collection) and returns a FilesetReport. The same check is available on the command line.

ome_zarr_io.validate(path, strict=False)

Validate an OME-Zarr 0.5 fileset and summarize what it contains.

Unlike Reader, this never fails on malformed metadata: every problem found is recorded in the returned report’s errors instead of being raised.

A plate is validated as a whole: its own metadata, every well it lists and every field of view (and label image) in those wells. A well is validated together with its fields. Each issue’s location says which node it was found in.

Parameters:

  • path (str | Path) – Path (or URL) to the root OME-Zarr group. Images, plates, wells and bioformats2raw layouts are recognized; only a root image is described in detail (axes, levels, channels, labels).

  • strict (bool) – If True, validate against the strict_* schemas.

Returns:

A FilesetReport. bool(report) is True when the fileset is valid.

Raises:

FileNotFoundError – If path does not exist (for URLs: if no Zarr group is found there).

Return type:

FilesetReport

class ome_zarr_io.FilesetReport(path, strict=False, kind='image', spec_version=None, zarr_format=None, creator=None, axes=<factory>, levels=<factory>, channels=<factory>, labels=<factory>, details=<factory>, errors=<factory>)

Validity of an OME-Zarr fileset plus a summary of what it contains.

A fileset is the whole hierarchy of Zarr groups under one path: an image, a plate (with its wells and fields), a well, or a bioformats2raw collection. kind says which.

Parameters:
path: str

Path or URL that was validated.

strict: bool = False

Whether the stricter strict_* schemas were used.

kind: str = 'image'

The kind of node the path is, one of "image", "plate", "well" or "bf2raw".

spec_version: str | None = None

OME-Zarr version declared in the metadata, if any.

zarr_format: int | None = None

Zarr format of the root group (OME-Zarr 0.5 requires 3).

creator: str | None = None

Name of the tool that wrote the fileset, if it declares one.

axes: List[Dict[str, Any]]

Axes of a root image.

levels: List[LevelInfo]

Resolution levels of a root image.

channels: List[ChannelInfo]

Channels of a root image, from its OMERO metadata.

labels: List[LabelInfo]

Label images of a root image.

details: Dict[str, Any]

Short facts about a plate, well or bioformats2raw root.

errors: List[ValidationIssue]

Every problem found; empty when the fileset is valid.

property is_valid: bool

True if no validation issues were found.

to_dict()

JSON-serializable representation of the report.

Return type:

Dict[str, Any]

raise_if_invalid()

Raise jsonschema.exceptions.ValidationError if the fileset is invalid.

Return type:

None

class ome_zarr_io.ValidationIssue(path, message, location='image')

A single problem found while validating a fileset.

Parameters:
path: str

Dotted location of the offending value, e.g. "ome.multiscales.0.axes".

message: str

What is wrong.

location: str = 'image'

The node the problem is in, one of "image", "plate", "well", "labels/<name>", or the node’s path inside a plate or well, for example "A/1", "A/1/0" or "A/1/0/labels/cells".

Report details

These classes describe parts of a FilesetReport.

class ome_zarr_io.report.LevelInfo(path, shape=None, chunks=None, dtype=None, scale=None, translation=None)

One resolution level of a multiscale pyramid.

Parameters:
path: str
shape: Tuple[int, ...] | None = None
chunks: Tuple[int, ...] | None = None
dtype: str | None = None
scale: List[float] | None = None
translation: List[float] | None = None
class ome_zarr_io.report.ChannelInfo(index, label=None, color=None, window=None)

A channel described by the OMERO metadata.

Parameters:
index: int
label: str | None = None
color: str | None = None
window: Dict[str, Any] | None = None
class ome_zarr_io.report.LabelInfo(name, n_levels=0, dtype=None, has_colors=False, has_properties=False, source=None)

A label image attached under the labels/ group.

Parameters:

  • name (str)

  • n_levels (int)

  • dtype (str | None)

  • has_colors (bool)

  • has_properties (bool)

  • source (str | None)

name: str
n_levels: int = 0
dtype: str | None = None
has_colors: bool = False
has_properties: bool = False
source: str | None = None

Schema validator

The lower-level validator that validate() is built on.

class ome_zarr_io.OMEZarrValidator(schema_version='0.5')

Validates OME-Zarr metadata against JSON schemas.

Initialize the validator with a specific schema version.

Parameters:

schema_version (str) – The OME-Zarr schema version to use (default: “0.5”)

validate_metadata(metadata, schema_type='ome_zarr')

Validate metadata against a specific schema.

Parameters:

  • metadata (Dict[str, Any]) – The metadata to validate

  • schema_type (str) – The type of schema to validate against (e.g., “image”, “plate”, “well”, “label”, “ome_zarr”)

Returns:

True if validation passes

Raises:

  • ValidationError – If validation fails

  • ValueError – If schema type is not found

Return type:

bool

validate_image_metadata(metadata)

Validate image metadata specifically.

Parameters:

metadata (Dict[str, Any]) – The zarr.json attributes containing OME metadata

Returns:

True if validation passes

Return type:

bool

validate_plate_metadata(metadata)

Validate plate metadata specifically.

Parameters:

metadata (Dict[str, Any]) – The zarr.json attributes containing OME metadata

Returns:

True if validation passes

Return type:

bool

validate_well_metadata(metadata)

Validate well metadata specifically.

Parameters:

metadata (Dict[str, Any]) – The zarr.json attributes containing OME metadata

Returns:

True if validation passes

Return type:

bool

validate_label_metadata(metadata)

Validate label metadata specifically.

Parameters:

metadata (Dict[str, Any]) – The zarr.json attributes containing OME metadata

Returns:

True if validation passes

Return type:

bool

iter_issues(metadata, schema_type='ome_zarr')

Get all validation errors as structured (path, message) pairs.

Parameters:

  • metadata (Dict[str, Any]) – The metadata to validate

  • schema_type (str) – The type of schema to validate against

Returns:

List of (path, message) tuples, where path is the location of the offending value within metadata as a tuple of keys/indices.

Raises:

ValueError – If schema type is not found

Return type:

List[Tuple[Tuple[Any, …], str]]

get_validation_errors(metadata, schema_type='ome_zarr')

Get all validation errors without raising an exception.

Parameters:

  • metadata (Dict[str, Any]) – The metadata to validate

  • schema_type (str) – The type of schema to validate against

Returns:

List of validation error messages

Return type:

list