API reference¶

Main interface.

Classes:

`ArrayTypeSchema`(array_type)	Array type schema.
`AttrSchema`([type, value, units, ...])	Attribute schema.
`AttrsSchema`(attrs[, require_all_keys, ...])	Attribute mapping schema.
`ChunksSchema`(chunks)	Chunks schema.
`CoordsSchema`(coords[, require_all_keys, ...])	Schema container for Coordinates
`DTypeSchema`(dtype)	Data type schema.
`DataArraySchema`([dtype, shape, dims, name, ...])	A lightweight xarray.DataArray validator.
`DatasetSchema`([data_vars, require_all_keys, ...])	A lightweight xarray.Dataset validator.
`DimsSchema`(dims[, ordered])	Dimensions schema.
`NameSchema`(name)	Name schema.
`ShapeSchema`(shape)	Shape schema.
`ValidationContext`([path, mode, result])	Context for tracking validation state during schema tree traversal.
`ValidationMode`(value)	Validation behaviour mode.
`ValidationResult`([errors])	Result of schema validation with error location mapping.

Exceptions:

SchemaError

Custom schema error.

class xarray_validate.ArrayTypeSchema(array_type)[source]¶

Bases: BaseSchema

Array type schema.

Parameters:: array_type (str or type) – Array type definition.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from a string.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(array[, context])	Validate array type against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from a string.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(array, context=None)[source]¶

Validate array type against this schema.

Parameters:

array (Any) – Array to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

class xarray_validate.AttrSchema(type=None, value=None, units=None, units_compatible=None)[source]¶

Bases: BaseSchema

Attribute schema.

Parameters:

type (type, optional) – Attribute type definition. None may be used as a wildcard.
value (Any) – Attribute value definition. None may be used as a wildcard.
units (str, optional) – Exact unit validation (tolerates different spellings/abbreviations). Uses pint to validate that the attribute value represents the same unit. For example, units="metre" accepts “metre”, “m”, or “meter”. Requires pint to be installed.
units_compatible (str, optional) – Compatible units validation (allows unit conversions). Uses pint to validate that the attribute value is compatible with the specified unit. For example, units_compatible="metre" accepts “meter”, “kilometre”, “millimetre”, etc. Requires pint to be installed.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from a dictionary.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(attr[, context])	Validate attribute against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from a dictionary.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(attr, context=None)[source]¶

Validate attribute against this schema.

Parameters:

attr (Any) – Attribute value to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

class xarray_validate.AttrsSchema(attrs, require_all_keys=True, allow_extra_keys=True)[source]¶

Bases: BaseSchema

Attribute mapping schema.

Parameters:

attrs (dict) – Attribute definitions.
require_all_keys (bool) – Whether to require to all coordinates included in attrs.
allow_extra_keys (bool) – Whether to allow coordinates not included in attrs dict.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from a dictionary.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(attrs[, context])	Validate attributes dictionary against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from a dictionary.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(attrs, context=None)[source]¶

Validate attributes dictionary against this schema.

Parameters:

attrs (dict) – Attributes dictionary to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

class xarray_validate.ChunksSchema(chunks)[source]¶

Bases: BaseSchema

Chunks schema.

Parameters:: chunks (dict or bool) – Chunks definition. If bool, whether the validated object should be chunked. If dict, mapping of dimension name to chunk size. None may be used as a wildcard.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from a dictionary.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(chunks, dims, shape[, context])	Validate chunks against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from a dictionary.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(chunks, dims, shape, context=None)[source]¶

Validate chunks against this schema.

Parameters:

chunks (tuple) – Chunks from DataArray.chunks
dims (tuple of str) – Dimension keys from array.
shape (tuple of int) – Shape of array.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

class xarray_validate.CoordsSchema(coords, require_all_keys=True, allow_extra_keys=True)[source]¶

Bases: BaseSchema

Schema container for Coordinates

Parameters:

coords (dict) –
Dict of coordinate keys and DataArraySchema objects. Keys can be either exact coordinate names or patterns:
- Exact match: 'time' matches only ‘time’
- Glob pattern: 'x_*' matches x_0, x_1, x_foo, etc.
- Regex pattern: '{x_\\d+}' matches x_0, x_1, but not x_foo
require_all_keys (bool, default: True) – Whether to require to all coordinates included in coords. Only applies to exact keys, not pattern keys.
allow_extra_keys (bool, default: True) – Whether to allow coordinates not included in coords dict. Coordinates matching pattern keys are not considered “extra”.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from basic Python types.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(coords[, context])	Validate object against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from basic Python types.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(coords, context=None)[source]¶

Validate object against this schema.

Parameters:

value – Object to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

class xarray_validate.DTypeSchema(dtype)[source]¶

Bases: BaseSchema

Data type schema.

This schema type validates NumPy’s data type objects.

Parameters:: dtype (DTypeLike) – DataArray dtype. Generic dtypes np.integer and np.floating are supported.

Examples

Basic instantiation and validation work like this:

>>> schema = DTypeSchema("float64")
>>> schema.validate(np.dtype("float64"))

Validation uses numpy.issubdtype() and is therefore strict:

>>> schema.validate(np.dtype("float32"))
Traceback (most recent call last):
...
SchemaError: dtype mismatch: got dtype('float32'), expected dtype('float64')

Generics are supported. For instance:

>>> DTypeSchema("floating").validate(np.ones(5, dtype="float16").dtype)
>>> DTypeSchema("integer").validate(np.ones(5, dtype="int32").dtype)

For flexibility, multiple dtypes can be passed. Validation will pass if at least one validates:

>>> schema = DTypeSchema(["float64", "float32"])
>>> schema.validate(np.dtype("float64"))
>>> schema.validate(np.dtype("float32"))
>>> schema.validate(np.dtype("float16"))
Traceback (most recent call last):
...
SchemaError: dtype mismatch: got dtype('float16'), expected one of
             (dtype('float32'), dtype('float64'))

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from a dtype-like object.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(dtype[, context])	Validate dtype against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from a dtype-like object.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(dtype, context=None)[source]¶

Validate dtype against this schema.

Parameters:

dtype (DTypeLike) – Dtype to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

class xarray_validate.DataArraySchema(dtype=None, shape=None, dims=None, name=None, coords=None, chunks=None, attrs=None, array_type=None, checks=NOTHING)[source]¶

Bases: BaseSchema

A lightweight xarray.DataArray validator.

Parameters:

dtype (DTypeLike or str or DTypeSchema, optional) – Data type validation schema. If a string is specified, it must be a valid NumPy data type value.
shape (ShapeT or tuple or ShapeSchema, optional) – Shape validation schema.
dims (DimsT or list of str or DimsSchema, optional) – Dimensions validation schema.
name (str, optional) – Name validation schema.
coords (CoordsSchema, optional) – Coordinates validation schema.
chunks (bool or dict or ChunksSchema, optional) – If bool, specifies whether the DataArray is chunked or not, agnostic to chunk sizes. If dict, includes the expected chunks for the DataArray.
attrs (AttrsSchema, optional) – Attributes validation schema.
array_type (type, optional) – Type of the underlying data in a DataArray (e.g. numpy.ndarray).
checks (list of callables, optional) – List of callables that will further validate the DataArray.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from basic Python types.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(da[, context, mode])	Validate an xarray.DataArray against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from basic Python types.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(da, context=None, mode=None)[source]¶

Validate an xarray.DataArray against this schema.

Parameters:

da (DataArray) – DataArray to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.
mode ({"eager", "lazy"}, optional) – Validation mode. If unset, the global default mode (eager) is used.

Returns:

In eager mode, this method returns None. In lazy mode, it returns a ValidationResult object.

Return type:

ValidationResult or None

class xarray_validate.DatasetSchema(data_vars=None, require_all_keys=True, allow_extra_keys=True, coords=None, attrs=None, checks=NOTHING)[source]¶

Bases: BaseSchema

A lightweight xarray.Dataset validator.

Parameters:

data_vars (dict, optional) –
Per-variable DataArraySchemas. Keys can be either exact variable names or patterns:
- Exact match: 'temperature' matches only ‘temperature’
- Glob pattern: 'x_*' matches x_0, x_1, x_foo, etc.
- Regex pattern: '{x_\\d+}' matches x_0, x_1, but not x_foo
require_all_keys (bool, default: True) – Whether to require all data variables included in data_vars. Only applies to exact keys, not pattern keys.
allow_extra_keys (bool, default: True) – Whether to allow data variables not included in data_vars dict. Variables matching pattern keys are not considered “extra”.
coords (CoordsSchema, optional) – Coordinate validation schema.
attrs (AttrsSchema, optional) – Attributes value validation schema.
checks (list of callables, optional) – List of callables that will further validate the Dataset.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from basic Python types.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(ds[, context, mode])	Validate an xarray.DataArray against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from basic Python types.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(ds, context=None, mode=None)[source]¶

Validate an xarray.DataArray against this schema.

Parameters:

ds (Dataset) – Dataset to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.
mode ({"eager", "lazy"}, optional) – Validation mode. If unset, the global default mode (eager) is used.

Returns:

In eager mode, this method returns None. In lazy mode, it returns a ValidationResult object.

Return type:

ValidationResult or None

class xarray_validate.DimsSchema(dims, ordered=True)[source]¶

Bases: BaseSchema

Dimensions schema.

Parameters:

dims (sequence of (str or None)) – DataArray dimensions. None may be used as a wildcard.
ordered (bool, optional) – If False, allow different dimension ordering.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from basic Python types.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(dims[, context])	Validate dimensions against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶

Instantiate schema from basic Python types.

Two input types are supported:

a sequence of strings;
a dictionary that contains a dims entry (with a sequence of strings as value) and an optional ordered entry (with a boolean as value).

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(dims, context=None)[source]¶

Validate dimensions against this schema.

Parameters:

dims (sequence of str) – Dimensions to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

class xarray_validate.NameSchema(name)[source]¶

Bases: BaseSchema

Name schema.

Parameters:: name (str) – Name definition.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from a string.
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(name[, context])	Validate name against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from a string.

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(name, context=None)[source]¶

Validate name against this schema.

Parameters:

name (str) – Name to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

exception xarray_validate.SchemaError[source]¶

Bases: Exception

Custom schema error.

Methods:

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class xarray_validate.ShapeSchema(shape)[source]¶

Bases: BaseSchema

Shape schema.

Parameters:: shape (sequence of (int or None)) – Shape of the DataArray. None may be used as a wildcard.

Methods:

`convert`(value)	Attempt conversion of `value` to this schema type.
`deserialize`(obj)	Instantiate schema from a sequence of integers (use None as a wildcard).
`from_yaml`(path)	Load schema from a YAML file.
`serialize`()	Serialize schema to basic Python types.
`validate`(shape[, context])	Validate shape against this schema.

classmethod convert(value)¶: Attempt conversion of value to this schema type.

classmethod deserialize(obj)[source]¶: Instantiate schema from a sequence of integers (use None as a wildcard).

classmethod from_yaml(path)¶

Load schema from a YAML file.

Parameters:: path (path-like) – Path to the YAML file containing the schema definition.
Return type:: Schema instance deserialized from the YAML file.
Raises:: ImportError – If ruamel.yaml is not installed.

serialize()[source]¶: Serialize schema to basic Python types.

validate(shape, context=None)[source]¶

Validate shape against this schema.

Parameters:

shape (tuple of int) – Shape to validate.
context (ValidationContext, optional) – Validation context for tracking tree traversal state.

Return type:

None

Raises:

SchemaError – If validation fails.

class xarray_validate.ValidationContext(path=NOTHING, mode=ValidationMode.EAGER, result=NOTHING)[source]¶

Bases: object

Context for tracking validation state during schema tree traversal.

Parameters:

path (list of str, optional) – Current validation path through the schema tree.
mode (ValidationMode or str, default: ValidationMode.EAGER) – Validation behavior mode (eager or lazy). Strings are converted to lowercase and passed to the ValidationMode constructor.
result (ValidationResult, optional) – Shared result object for collecting errors in lazy mode.

Methods:

`get_errors`()	Get all collected errors with their paths.
`get_path_string`()	Get current path as dot-separated string.
`handle_error`(error)	Handle validation error based on mode.
`push`(component)	Create a new context with an additional path component.

Attributes:

has_errors

Check if any errors have been collected.

get_errors()[source]¶: Get all collected errors with their paths.

get_path_string()[source]¶: Get current path as dot-separated string.

handle_error(error)[source]¶

Handle validation error based on mode.

In EAGER mode: raise the error immediately
In LAZY mode: collect error in result object

Parameters:: error (SchemaError) – Validation error to handle.

property has_errors¶: Check if any errors have been collected.

push(component)[source]¶

Create a new context with an additional path component.

Parameters:: component (str) – Path component to add (e.g., ‘dtype’, ‘coords.x’, ‘data_vars.temperature’)
Returns:: New context with extended path sharing the same mode and result.
Return type:: ValidationContext

class xarray_validate.ValidationMode(value)[source]¶

Bases: Enum

Validation behaviour mode.

Attributes:

`EAGER`	Raise SchemaError on first validation failure (default behavior)
`LAZY`	Collect all validation errors and return them in ValidationResult

EAGER = 'eager'¶: Raise SchemaError on first validation failure (default behavior)

LAZY = 'lazy'¶: Collect all validation errors and return them in ValidationResult

class xarray_validate.ValidationResult(errors=NOTHING)[source]¶

Bases: object

Result of schema validation with error location mapping.

Parameters:: errors (list of tuple[str, SchemaError]) – List of (path, error) pairs mapping errors to tree locations.

Methods:

`add_error`(path, error)	Add an error at the specified path.
`get_error_summary`()	Get a formatted summary of all validation errors.

add_error(path, error)[source]¶: Add an error at the specified path.

get_error_summary()[source]¶: Get a formatted summary of all validation errors.