Metadata-Version: 2.4
Name: biomero-schema
Version: 0.3.0b4
Summary: CLI tool to validate and parse JSON files against a schema
Author-email: Schema Validator <validator@example.com>
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0.3
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Dynamic: license-file

# <img src="https://raw.githubusercontent.com/NL-BioImaging/OMERO.biomero/refs/tags/v1.2.1/webapp/src/img/biomero-logo.svg" alt="BIOMERO" height="28" style="height:28px; width:auto; vertical-align:middle;"> BIOMERO Schema

[![Tests](https://github.com/NL-BioImaging/biomero-schema/actions/workflows/test.yml/badge.svg)](https://github.com/NL-BioImaging/biomero-schema/actions/workflows/test.yml)
[![Documentation](https://github.com/NL-BioImaging/biomero-schema/actions/workflows/docs.yml/badge.svg)](https://nl-bioimaging.github.io/biomero-schema/)
[![PyPI](https://img.shields.io/pypi/v/biomero-schema)](https://pypi.org/project/biomero-schema/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

> 🚀 **This package is part of <img src="https://raw.githubusercontent.com/NL-BioImaging/OMERO.biomero/refs/tags/v1.2.1/webapp/src/img/biomero-logo.svg" alt="BIOMERO" height="16" style="height:16px; width:auto; vertical-align:middle;"> BIOMERO 2.0** — For complete deployment and FAIR infrastructure setup, start with the [**NL-BIOMERO Documentation**](https://nl-bioimaging.github.io/NL-BIOMERO/) 📖

Shared, versioned Pydantic contracts for the BIOMERO ecosystem.

[Documentation](https://nl-bioimaging.github.io/biomero-schema/) ·
[Python API](https://nl-bioimaging.github.io/biomero-schema/api/workflow/) ·
[Pixel identity reference](https://nl-bioimaging.github.io/biomero-schema/pixel-identity/)

The package keeps two contract areas separate:

- `biomero_schema.models` is BIOMERO's normalized representation of a workflow
  descriptor.
- `biomero_schema.zarr`, `biomero_schema.imports`, and
  `biomero_schema.shallower` define internal
  cross-service contracts for managed Zarr sources, pixel identity, shallow
  collections, importer lifecycle operations, and remote shallowing reports
  and receipts.

## Workflow descriptors

Workflow providers normally describe their tools using an external workflow
format. The adapters in `biomero_schema.adapters` detect and convert supported
formats into the validated `WorkflowSchema` from this package:

```text
BIAFLOWS descriptor.json ─┐
                         ├─> biomero adapters ─> WorkflowSchema ─> BIOMERO services
BILAYERS config.yaml ─────┘
```

Currently supported inputs are:

| Provider format | BIOMERO support |
| --- | --- |
| [BILAYERS `config.yaml`](https://bilayers.org/understanding-config/) | Converts the container, command, citations, inputs, parameters, and declared outputs. This is the preferred route for Zarr-to-Zarr and Plate-aware workflows. |
| [BIAFLOWS/Cytomine descriptor](https://neubias-wg5.github.io/creating_bia_workflow_and_adding_to_biaflows_instance.html) | Converts the supported legacy `cytomine-0.1` subset. It remains useful for established TIFF-oriented BIAFLOWS workflows. |
| Native `biomero-0.1` descriptor | Validates directly. This is primarily BIOMERO's normalized service representation, although integrations may produce it explicitly. |

CWL and OpenAPI descriptors are not yet supported. The adapters were moved
here from [`biomero.schema_parsers`](https://github.com/NL-BioImaging/biomero/blob/main/biomero/schema_parsers.py)
so descriptors can be converted without the BIOMERO runtime:

```python
from biomero_schema.adapters import parse_descriptor

workflow = parse_descriptor(yaml.safe_load(open("config.yaml")))
```

The adapter determines which fields from an external format are currently
converted.

See [Workflow descriptors](https://nl-bioimaging.github.io/biomero-schema/workflow-descriptors/)
for the conversion boundary and supported mappings.

## Installation

Python 3.11 or newer is required.

```bash
pip install biomero-schema
```

For development:

```bash
git clone https://github.com/NL-BioImaging/biomero-schema.git
cd biomero-schema
pip install -e .
```

The repository also supports [Pixi](https://pixi.sh/):

```bash
pixi run test
```

## Native descriptor validation

The CLI validates the normalized BIOMERO descriptor. BILAYERS (`.yaml`) and
BIAFLOWS descriptors are detected and converted before validation, and
`parse --json` writes the converted descriptor.

```bash
biomero-schema validate config.yaml
biomero-schema parse config.yaml --json > descriptor.json
biomero-schema validate descriptor.json
biomero-schema parse descriptor.json
biomero-schema parse descriptor.json --pretty
biomero-schema schema
```

A maintained native example is available at
[`tests/example_workflow.json`](tests/example_workflow.json).

## Cross-service contracts

Consumers should import the shared models rather than duplicating JSON fields:

```python
from biomero_schema.zarr import CanonicalZarrSource

source = CanonicalZarrSource.from_dict(payload)
wire_payload = source.to_dict()
json_schema = CanonicalZarrSource.model_json_schema()
```

The camelCase output from `to_dict()` is the stable wire representation. Every
contract family carries its own integer `schema`, independently of the workflow
descriptor version.

The shallow-Zarr manifest is an experimental, versioned BIOMERO storage
contract, not RFC-8 metadata. Its portable image/label graph is separate from
BIOMERO storage and provenance bindings so that a future standards adapter can
reuse the graph without redefining the operational data.

See [Remote shallower contracts](https://nl-bioimaging.github.io/biomero-schema/remote-shallower-contracts/)
for the report formats, trusted receipt hand-off, and compatibility requirements.
These models do not enable shallow storage or remote execution; feature
configuration belongs to the consuming services.

## Documentation development

```bash
python -m pip install -e .
python -m pip install -r docs/requirements.txt
mkdocs serve
```

Use `mkdocs build --strict` to reproduce the documentation CI build. See
[`docs/contributing.md`](docs/contributing.md) for publishing details.
