Validator

The atlas-assets package includes a validator that checks an atlas-assets tree for compliance with this specification and reports errors and warnings. It works against a local directory or a public S3 prefix.

Installation

The validator is an optional feature. Install it with the validate extra:

pip install atlas-assets[validate]

Usage

Validate a local directory or an s3:// prefix:

atlas-assets-validate ./my-atlas-assets
atlas-assets-validate s3://allen-atlas-assets/

Options:

  • --level {structural,full} – validation depth (default structural). full adds the content checks described below.

  • --format {text,json} – output format (default text).

  • --strict – exit non-zero on warnings as well as errors.

  • --region – AWS region for s3:// locations (default us-west-2; also read from $AWS_REGION / $AWS_DEFAULT_REGION).

Public S3 buckets are read with unsigned requests, so no credentials are required. The command exits 0 when no errors are found and 1 when there are errors (or any warnings under --strict).

What it checks

Findings are either errors or warnings:

Errors indicate a violation of a MUST/REQUIRED rule:

  • a required file or directory is missing (e.g. data_description.json, manifest.json, template.ome.zarr);

  • a required JSON file does not parse;

  • an asset has no version directory.

Warnings flag likely problems and deviations from recommendations:

  • unexpected top-level, asset-type, or version-level entries;

  • naming-convention deviations (naming is a guideline, not a requirement);

  • a missing processing.json, which is required only for computed assets;

  • an unrecognized version-directory format;

  • a manifest that omits a draft “minimal required” key.

Content checks (--level full)

With --level full the validator also reads file contents:

  • Metadata – data_description.json and processing.json are validated against aind-data-schema. This step is skipped with a note if aind-data-schema is not installed.

  • Manifest cross-references – every manifest.json reference (by location) must resolve to an existing asset.

  • Terminology CSV – required columns, unique identifier and annotation_value, resolvable parent_identifier, no cycles, and #RRGGBB color values.

  • OME-Zarr – OME-Zarr version ≥ 0.5, spatial axes in millimeters, compressed chunks, and the annotation_values array on annotation sets.

Content validation requires the validate extra (obstore, zarr, aind-data-schema) and Python 3.11+.