K-Dense-AI/scientific-agent-skills / skills/ontology-term-resolution
ontology-term-resolution
VerifiedResolves free-text scientific labels to ontology term IDs and validates existing CURIEs against the EBI Ontology Lookup Service (OLS4). Also looks up prefixes in Bioregistry, resolves compact identifiers via Identifiers.org, maps lab shorthand with ZOOMA, and builds Ontobee term pages. Use whenever an ontology identifier must be produced or checked - annotating tissue, cell type, disease, phenotype, assay, chemical, organism, sex, or developmental stage fields; preparing metadata for GEO, ENA, BioSamples, CELLxGENE, HCA, or ISA-Tab submission; auditing a metadata table of term IDs; checking whether a term is obsolete and what replaced it; or deciding HPO vs HP. Triggers include "ontology term", "ontology ID", "CURIE", "controlled vocabulary", "UBERON", "CL:", "MONDO", "HPO", "EFO", "ChEBI", "NCBITaxon", "GO term", "PATO", "Zooma", "Bioregistry", "Identifiers.org", "Ontobee", "annotate this tissue/cell type/disease", and any request to emit or verify an identifier shaped like PREFIX:0001234.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.3 KB |
| references/companion-apis.md | markdown | 9.4 KB |
| references/curation-rules.md | markdown | 5.9 KB |
| references/ols4-api.md | markdown | 7.5 KB |
| references/ontology-registry.md | markdown | 6.1 KB |
| scripts/id_client.py | script | 11.5 KB |
| scripts/lookup_prefix.py | script | 6.3 KB |
| scripts/map_terms.py | script | 7.3 KB |
| scripts/ols_client.py | script | 15.5 KB |
| scripts/resolve_terms.py | script | 8.3 KB |
| scripts/validate_terms.py | script | 10.7 KB |
| scripts/zooma_client.py | script | 5.2 KB |
references/ols4-api.md
View on GitHub# EBI OLS4 API reference
Reviewed 2026-10-01 against the [official OpenAPI description](https://www.ebi.ac.uk/ols4/v3/api-docs),
[compatibility API guide](https://www.ebi.ac.uk/ols4/ols3help),
[current implementation](https://github.com/EBISPOT/ols4/tree/dev/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v1),
and unauthenticated public requests. The bundled client uses the OLS3-compatible `/api`
interface; `/api/v2` is a different response contract. No API key is needed.
Base URL: `https://www.ebi.ac.uk/ols4/api`. Send a descriptive User-Agent, keep concurrency low,
and back off on 429 or transient server errors. Treat HTML or malformed JSON as service failure,
not an empty scientific result. The client retries transient failures three times.
## `GET /search` — text to candidates
| Parameter | Effect |
| --- | --- |
| `q` | Required query text. |
| `ontology` | Comma-separated OLS ids (`uberon`, `ordo`), selecting ontology documents, including imports. |
| `type` | Entity type; the helper requests `class`. |
| `queryFields` | `label,synonym` for a restricted lexical search; omitted for all indexed fields. |
| `exact` | Match mode, not proof of exact label equality; check the returned strings locally. |
| `obsoletes` | Current v1 implementation filters on this boolean: `false` current-only, `true` obsolete-only. |
| `local` | `true` excludes imported copies; not enabled by the bundled search by default. |
| `allChildrenOf` | Term IRI, encoded once by query serialization. Hierarchical descendants include is-a, part-of, develops-from. |
| `childrenOf` | Current v1 implementation uses the same hierarchical-ancestor filter as `allChildrenOf`; do not assume direct-child-only semantics. |
| `rows`, `start` | Page length and zero-based result offset, not a page number. |
| `fieldList` | Fields to return, comma-separated. |
| `groupField` | Current implementation groups by IRI for any value other than `false`; the helper instead deduplicates locally. |
Response: `response.numFound`, `response.start`, `response.docs`. The helper requests `iri`,
`obo_id`, `label`, `synonym`, scoped `exact_synonyms`, `related_synonyms`, `broad_synonyms`,
`narrow_synonyms`, `ontology_name`, `is_defining_ontology`, `type`, `short_form`.
The plural scoped synonym fields are now supported. `synonym` is their combined lexical list.
A live snapshot illustrates why local classification matters:
```text
q=liver&ontology=uberon&exact=true -> 161 hits
q=liver&ontology=uberon&exact=true&queryFields=label -> 1 hit
```
`iecur` and `jecur` are **related** synonyms of liver in the reviewed release. Matching their
spelling does not make the synonym relation exact. `--exact-only` retains exact labels and
explicit exact-synonym matches, rejecting other scopes and partial matches.
`is_obsolete` and `term_replaced_by` are still omitted from search records, even if requested.
The public description says `obsoletes=true` includes obsolete terms, but the current source
and live probe show an obsolete-only filter. `search(..., include_obsolete=True)` therefore
merges a current-only query and an obsolete-only query (up to `rows` from each).
`ontology=uberon&q=hepatocyte` returns imported `CL:0000182`; adding `local=true` removes it.
A search restricted to an ontology document does not enforce a required CURIE namespace.
Use term validation with `--expect-ontology` before accepting the result.
The same IRI can occur in several ontology documents. Deduplicate and prefer defining copies,
but remember that a bounded search can miss competing exact matches or the defining copy.
Do not treat the first result or an exact spelling as an automatic annotation decision.
## `GET /ontologies/{ontology}/terms?obo_id={CURIE}` — term detail
Returns `_embedded.terms`; a missing term can return 404. Inspect `is_obsolete`,
`term_replaced_by`, `is_defining_ontology`, the definition, and `obo_synonym` (including scope).
OLS is a lookup index of ontology releases, not proof that an annotation fits a sample.
```text
EFO:0001067 -> obsolete_parasitic infection
is_obsolete: true
term_replaced_by: http://purl.obolibrary.org/obo/MONDO_0005135
```
Replacement values are IRIs. The helper converts only recognized OBO/EFO/Orphanet namespaces;
unknown replacement IRIs remain visible unchanged. Never split an arbitrary URL's last
underscore and assume it is an ontology CURIE. Replacements and `consider` annotations need
separate review; do not assume they are semantically interchangeable with the obsolete term.
## `GET /terms?iri={IRI}` — copies and index fallback
A missing `obo_id` index entry is not proof of nonexistence. The client tries known IRI patterns,
queries OLS, follows all HAL `_links.next` pages, and prefers the home defining copy.
`_resolved_via` and `_home_ontology` record that choice.
`MONDO:0000001` now resolves directly by `obo_id`; the older index-hole example is fixed.
`Orphanet:558` still required IRI fallback at review. `ORPHA:558` (Bioregistry's preferred form)
and `Orphanet:558` use home ontology `ordo` and the same Orphanet IRI template.
An imported-only result warns; it does not prove the source ontology deleted the term.
A failed fallback means not found **in this OLS lookup**, not in every ontology source.
| Namespace | Candidate IRI pattern, requiring subsequent OLS confirmation |
| --- | --- |
| OBO | `http://purl.obolibrary.org/obo/{PREFIX}_{local}` |
| EFO | `http://www.ebi.ac.uk/efo/EFO_{local}` |
| Orphanet / ORPHA | `http://www.orpha.net/ORDO/Orphanet_{local}` |
Other namespace conventions need a registry-supplied or original IRI, not speculative rewriting.
## Hierarchy and release provenance
Follow term `_links.hierarchicalAncestors.href` for all hierarchical relations; follow
`_links.ancestors.href` for subclass/is-a ancestry only. The client follows pagination,
upgrades service-generated HTTP links to HTTPS, and fails on incomplete traversal rather than
returning a false `wrong_branch`. An empty ancestor set is meaningful only after a successful
complete response. `validate_terms.py --branch-relation is-a` selects subclass-only checks;
the default and search `--branch` include hierarchical relations.
A part of an organ is not necessarily a subclass of that organ. CARO also places cell under
anatomical structure, so even a valid ancestry test cannot enforce a tissue-only namespace.
Use both branch and namespace constraints. The validator accepts the branch root itself;
search descendant filtering need not include the root. The root must be current.
`GET /ontologies/{id}/terms/roots` is a presentation of ontology roots, which may include imported
upper-level terms. Use explicit schema-approved roots instead of interpreting this as a category
contract. `GET /ontologies/{id}` provides `config.versionIri`, `config.version`, `loaded`, and
`updated` (nullable). Preserve these, lookup time, original input, selected IRI and raw responses.
OLS's currently loaded release can differ from a submission schema's pinned release.
## Related services
See `companion-apis.md` for Bioregistry, Identifiers.org, ZOOMA and Ontobee.
[OxO2](https://github.com/EBISPOT/oxo2) is now live at `https://www.ebi.ac.uk/spot/oxo/`;
the legacy `/api/search` route returned HAL JSON in this review. The blanket statement that
OxO is retired and every API route returns HTML is incorrect. This skill does not implement
an OxO client. For cross-ontology work inspect the current service contract, mapping predicate,
provenance and inference distance, or use a published SSSOM mapping set. Bare database xrefs
are leads, not guaranteed `skos:exactMatch` assertions.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |