ontology_term lookup can be scoped to an ontology but not to a branch

[sorenwacker]

Summary

An ontology_term field can be scoped to whole ontologies via ontologies: [...], but not to a branch within one. A column meant to hold a technology type will therefore accept any term from the ontology, including terms from unrelated branches. Profiles whose columns each draw on a different branch of the same ontology cannot express that distinction at all.

Cause

OntologyService.search builds the OLS request from the query, a row limit, a field list, an optional whole-ontology filter and an optional exact flag (src/metaseed/services/ontology.py:336-344, and the same shape again at :422-429):

params: dict[str, Any] = {
    "q": query,
    "rows": rows,
    "fieldList": "iri,label,short_form,obo_id,ontology_name,ontology_prefix,description",
}
if ontology:
    params["ontology"] = ontology.lower()
if exact:
    params["exact"] = "true"

No parameter restricts results to the descendants of a given term, and there is no field key that could carry one. A field's own ontology_term is documented as what the column means (docs/guides/ontology-lookup.md), not a constraint on its values, so it cannot serve this purpose without changing that meaning.

Impact

Present in existing profiles: miappe 1.2 scopes four fields to po, pato, to, uo and co_321, so a field intended for a plant anatomical entity accepts any Plant Ontology term.

It becomes acute for a profile built from a single domain ontology, where every controlled column draws on a different branch of that one ontology. A JERM-derived profile has ten such columns — assay type, technology type, sample characteristics, assay characteristics, factors studied, measured item, and four file-format branches. Scoped per ontology they are all equivalent: each accepts the whole ontology, so nothing distinguishes a technology type from a file format. The only workaround today is to inline each branch's terms with options, which freezes them at one ontology version and discards the reason for using a lookup.

Proposal

Add a field key carrying the branch, and pass a descendant restriction to OLS:

- name: technology_type
  type: ontology_term
  ontologies: [jerm]
  within: JERM:00025        # only terms beneath Technology type are valid
  ontology_term: JERM:00025 # unchanged: what the column means

OLS's search API supports restricting results to the descendants of a term, so the change is mostly a matter of passing it through plus a spec key to carry it. Points worth settling in the design:

• whether within also constrains on validation, or only narrows the picker — the two have different blast radii for existing datasets
• behaviour when the ontology is unreachable, which by the project's own rule should report "not checked" rather than fail
• whether within implies ontologies, since a branch identifies its ontology

Note

ontology_term on a field meaning "what this column is" rather than "what values are allowed" is easy to misread, and the two look identical in YAML. If within is added, the guide should contrast them explicitly.