Indicium

A versioned standard for a typed scientific claim bound to the evidence that grounds it.

What it is

Indicium is a small, standalone, versioned standard for a typed scientific claim bound to the evidence that grounds it. One LinkML source of truth generates pydantic models, JSON Schema, SHACL shapes and OWL. It reuses community ontologies rather than reinventing them:

The one thing Indicium mints is the binding: a claim, its typed evidence, and the source that evidence points to, provenance-stamped. That binding is the load-bearing contribution. The claim structure is borrowed from Bucur; the value Indicium standardizes is the typed grounding of claims in evidence.

Indicium is a vocabulary and a standard, not a tool and not a store. Every tool that mints claims imports it, so a claim minted by any of them is structurally identical to one minted by another, merges with it, and never travels without its evidence trace.

The name

Indicium (Latin) is "a sign or mark that points to the truth"; in law, the evidentiary indication. The package is named for what it standardizes: every claim carries its indicia, the traces that justify believing it.

• indicium (singular) is the standard and this package.
• indicia (plural) is the body of evidence attached to a claim, and the term consumer APIs use for the produced collection.

Install

Requires Python 3.11 or newer.

pip install indicium-standard      # distribution name
python -c "import indicium"        # import name

Optional extras:

pip install "indicium-standard[astra]"     # ASTRA bridge (PyYAML)
pip install "indicium-standard[codegen]"   # regenerate the artefacts from the LinkML source

The 2.0.0 upload to PyPI is pending (RELEASING.md). Until pip install indicium-standard finds it, install from the repository:

pip install "git+https://github.com/HolobiomicsLab/indicium"

The distribution is indicium-standard; the import package is indicium. The PyPI name indicium belongs to an unrelated, abandoned key-value-store package that also ships a top-level indicium module. Installing both into the same environment will clobber the import. Always depend on indicium-standard.

Quickstart

Validate a claim against the SHACL shapes (adapted from tests/test_validate.py):

import rdflib
from indicium import ASB_BASE, validate_graph

claim = f"""
@prefix asb: <{ASB_BASE}> .
<urn:claim:1> a asb:Claim ;
    asb:context "in vitro" ;
    asb:subject "compound A" ;
    asb:qualifier "inhibits" ;
    asb:relation "inhibits growth of" ;
    asb:object "cell line B" .
"""
conforms, report = validate_graph(rdflib.Graph().parse(data=claim, format="turtle"))
print(conforms)  # True

incomplete = f"""
@prefix asb: <{ASB_BASE}> .
<urn:claim:2> a asb:Claim ; asb:context "in vitro" .
"""
conforms, report = validate_graph(rdflib.Graph().parse(data=incomplete, format="turtle"))
print(conforms)  # False

report names each missing slot. The quickstart continues with the typed model and the adapters; every Python example in this README and on the Home, Quickstart and URI scheme pages runs in the test suite (tests/test_docs_examples.py).

Vocabulary and IRIs

Import the namespace bases; never copy the IRI string into your own code. A hardcoded base keeps pointing at the old namespace when the standard moves, and the SHACL shapes then match nothing: every graph validates as conforms=True while no constraint is actually checked.

from indicium import ASB_BASE, INDICIUM_BASE, asb_term

asb_term("Claim")   # 'https://w3id.org/asb#Claim'

ASB = "https://w3id.org/asb#"   # don't: silently dead after a move

docs/uri-scheme.md has the redirect chains, the identifier conventions for claims and evidence, and what the /indicium registration will point at. tests/test_namespace_resolves.py fetches each namespace when INDICIUM_NETWORK_TESTS=1 is set.

Ecosystem

Indicium is the shared layer; the projects below mint, store or consume its claims.

AgenticScienceBuilder, Scriptorium, KGmemory, the asb-skills-<domain> collections and the indicium-adapters family are not public yet.

Development

uv sync --frozen --extra codegen --extra docs
uv run pytest -q              # includes the conformance suite (parity with the Scriptorium SHACL)
make lint                     # ruff over src/ and scripts/
make gen                      # regenerate model.py, shapes.ttl, ontology.ttl, schema.json
make context                  # regenerate the packaged JSON-LD context from the LinkML URI bindings
make schema-assets            # make gen and make context, then copy the artefacts and the changelog into docs/
uv run mkdocs build --strict  # the documentation site, as docs.yml deploys it

docs/changelog.md is a copy of CHANGELOG.md (make docs-changelog); edit only the latter. make gen writes canonical Turtle, so a second run is byte-identical to the committed files; release.yml fails when it is not.

Namespace bases are stable identifiers. Their registration and the vocabulary site are prepared separately from the Python release; they do not provide an instance store. Read the URI scheme and the SEPIO compatibility notes before exporting RDF.

Release and versioning policy

Indicium follows Semantic Versioning, read for a vocabulary:

• Term IRIs are immutable after a tagged release. Published data embeds them.
• Additive changes are minor: a new class, slot or enum value.
• An IRI change or a slot removal is major, as is a tighter cardinality. This is why the move of the asb: base to https://w3id.org/asb# is 2.0.0.

A tag v<version> that matches pyproject.toml and a dated CHANGELOG.md section runs the release (.github/workflows/release.yml): the checks, tests, documentation build and installed-wheel check first, then the upload of the wheel and the sdist to PyPI through Trusted Publishing, then the GitHub release with the same files and the three schema artefacts. RELEASING.md is the maintainer checklist. Changes are listed in CHANGELOG.md.

Citation

CITATION.cff holds the citation metadata, which GitHub offers as "Cite this repository". No DOI exists yet. BibTeX, derived from that file with cffconvert -f bibtex (citation key renamed):

@misc{nothias_indicium,
  author = {Nothias, Louis-Félix},
  title  = {Indicium: a standard for typed scientific claims bound to their evidence},
  url    = {https://github.com/HolobiomicsLab/indicium}
}

License

MIT, see LICENSE. Developed at the Holobiomics Lab, CNRS / Université Côte d'Azur.