BioLedger ISA-Tab — API Reference

Auto-generated from bioledger_isatab_schema.models/manifest/validate at build time — do not hand-edit.

`ISAStudySpec`

Structured output from the ISAForge agent.

Field	Type	Required	Default	Description
`investigation_id`	`str`	yes	—	Investigation identifier.
`title`	`str`	yes	—	Investigation title.
`description`	`str`	yes	—	Investigation description.
`study_id`	`str`	yes	—	Study identifier.
`study_title`	`str`	yes	—	Study title.
`study_description`	`str`	yes	—	Study description.
`ontology_sources`	`list[OntologySourceSpec]`	no	—	Ontologies referenced by this study's terms.
`sources`	`list[SourceSpec]`	no	—	Biological source materials in this study.
`samples`	`list[SampleSpec]`	no	—	Samples derived from the sources.

`OntologySourceSpec`

A Term Source declared in i_investigation.txt (e.g. an ontology).

Field	Type	Required	Default	Description
`name`	`str`	yes	—	Ontology short name, e.g. "OBI".
`file`	`str`	no	—	Ontology URI, e.g. "http://purl.obolibrary.org/obo/obi.owl".
`version`	`str`	no	—	Ontology version, if known.

`SourceSpec`

A biological source material (Source Name column).

Field	Type	Required	Default	Description
`name`	`str`	yes	—	Source name, unique within the study.
`characteristics`	`list[CharacteristicSpec]`	no	—	Characteristics attached to this source (e.g. organism).

`SampleSpec`

A sample derived from a source (Sample Name column).

Field	Type	Required	Default	Description
`name`	`str`	yes	—	Sample name, unique within the study.
`derived_from`	`str`	no	—	Name of the source this sample was derived from.
`characteristics`	`list[CharacteristicSpec]`	no	—	Characteristics attached to this sample.

`CharacteristicSpec`

A single Characteristics[...] value attached to a source or sample.

Field	Type	Required	Default	Description
`term`	`str`	yes	—	The characteristic's term/value, e.g. an organism name.
`ontology_ref`	`str`	no	—	IRI of the matching ontology term, if resolved.

`Manifest`

Parsed manifest.yaml for a single study directory.

Field	Type	Required	Default	Description
`study_type`	`"reference_genome" \| "experimental_data"`	yes	—	One of `reference_genome` or `experimental_data`.
`files`	`list[ManifestFile]`	yes	—	Downloadable files for this study.
`assembly_accession`	`str \| None`	no	—	Required for `reference_genome` studies; must match the directory name.
`insdc_accession`	`str \| None`	no	—	Required for `experimental_data` studies; must match the directory name.
`organism`	`str \| None`	no	—	Human-readable organism name.
`strain`	`str \| None`	no	—	Human-readable strain/isolate name.

`ManifestFile`

A single downloadable file in a study manifest.

At least one checksum (sha256 or md5) is required and is verified after download. md5 exists because large public FASTQ at ENA/SRA are published with md5 only — computing sha256 would require downloading multi-GB files. Prefer sha256 where the source provides it.

sra_accession optionally tags a file as originating from an SRA run (e.g. SRR7133733). When the SRA-Toolkit fast-path is enabled via BIOLEDGER_USE_SRA_TOOLKIT=1, the downloader uses prefetch + fasterq-dump instead of HTTPS. Note: this path skips the manifest md5 (bytes differ after local re-compression) and records a fresh sha256 instead — see the download module for details.

Field	Type	Required	Default	Description
`filename`	`str`	yes	—	Canonical local name; must match the ISA-Tab assay table entry.
`url`	`str`	yes	—	https preferred (the downloader is httpx-based; no FTP support).
`format`	`str`	yes	—	File format, e.g. fastq, fasta, bam.
`sha256`	`str \| None`	no	—	Preferred checksum.
`md5`	`str \| None`	no	—	Accepted when the source only publishes md5 (e.g. ENA FASTQ).
`sra_accession`	`str \| None`	no	—	Optional SRA run accession (SRR/ERR/DRR) for the SRA-Toolkit fast-path.

Validation rules

`validate_isatab()`

Validate ISA-Tab directory for essential attributes.

Checks: - i_investigation.txt exists and is parseable - At least one study with title and description - At least one assay with data files - Data files have clear locations (local path or URL) - Organism characteristic present in sources - Assay type/technology type specified

`validate_manifest()`

Validate manifest.yaml for a study directory.

Returns a list of issue dicts {"severity": ..., "field": ..., "message": ...} where severity is "error" or "warning". An empty list means the manifest is valid. Callers decide whether warnings should fail.

Checks: - manifest.yaml exists and parses (errors) - study_type present and valid (error) - assembly_accession / insdc_accession present and matches directory name (error) - files list non-empty, each with filename/url/format and at least one of sha256/md5 (error) - study_type vs accession prefix consistency (warning only)