# ontology.guru — full instructions for agents

> 120 published ontologies, read and catalogued by hand. 50 serve a source-verified class hierarchy; 70 serve none and say why. Static JSON on a CDN: no key, no rate limit, CORS open.

Generated from the catalogue itself, so the counts below cannot drift from what the API serves.

## What this is for

Use it when you need to answer "is there already an ontology for this?" — before
designing a bespoke schema, when mapping one vocabulary onto another, or when you
need to know whether a given ontology can legally be redistributed.

Do not use it as a source of truth about an ontology's *full* contents. The
hierarchies here are readable subsets. The upstream file, linked on every entry,
is the authority.

## The trust contract

This catalogue's whole point is that it distinguishes what was checked from what
was not. If you flatten that distinction when you summarise it, you have thrown
away the only thing it offers over a search engine.

### hierarchy.status

`verified` — the class tree was parsed out of the ontology's own published file.
The entry then carries `hierarchy.source` (the URL fetched), `hierarchy.retrievedAt`
(the date), `hierarchy.classesInSource`, `hierarchy.classesShown`, and
`hierarchy.extractionCommand` (the script that did it, so you can reproduce it).
Only these entries have a `classHierarchy` array.

`withheld` — **no hierarchy is served, and that is deliberate.** Never render this
as an empty or zero-class ontology. `hierarchy.reason` is one of:

- `licence` (5 entries) — the licence does not permit redistribution
- `unverified` (61 entries) — no extraction from the published source file has been done yet
- `unverified-licence` (1 entry) — the licence terms could not be established with enough confidence to republish
- `wrong-artifact` (1 entry) — the published file is not a class hierarchy (e.g. it is a shape graph or a vocabulary of properties)
- `wrong-shape` (2 entries) — the published file parsed, but its class structure was too flat or too tangled to publish honestly

`hierarchy.explanation` carries the prose reason where one was recorded, and
`hierarchy.officialSource` is where to go instead.

### licence.verified

`true` for 26 of 120 entries. Those carry the operative terms: `licence.id`
(SPDX where one exists), `licence.name`, `licence.url`, `licence.attribution`,
`licence.shareAlike`, `licence.redistribution`, `licence.notice` (the exact
attribution string to reproduce), `licence.caveat`, and `licence.verifiedAt`.

`false` for the remaining 94. Those carry only `licence.label` — the catalogue's
original classification, never checked against the licence text. When you report
one, say it is unverified.

### licence.redistribution

- `attribution_required` — you may republish it if you carry the notice in `licence.notice`
- `no` — do not republish it
- `redistribution` — you may republish the ontology
- `reference_only` — link to it, do not copy it
- `unverified` — the terms were never established — treat as "do not republish"

1 entry carries `licence.shareAlike: true`. Share-alike propagates to whatever you
generate from it — if you derive a schema from one of these, the derivative
inherits the obligation. Check before you build on it.

Licence summaries here are made in good faith from primary sources and are not legal advice. Check the licence yourself before you redistribute anything.

## Endpoints

All responses are `application/json`. All are static files except the last.

### GET /api/catalog.json

Every entry in one document. Top level: `generatedAt`, `site`, `counts`
(`total`, `verified`, `withheld`), `notice`, and `ontologies` — an array of
entries. Each entry has `id`, `name`, `fullName`, `category`, `description`,
`homepage`, `maintainer`, `tags`, `useCases`, `licence`, `hierarchy`, `url`
(the human page) and `api` (the per-entry JSON).

No pagination — fetch it once and filter locally rather than making 120 requests.

### GET /api/ontology/<id>.json

One entry: everything in the catalog entry, plus

- `classHierarchy` — a flat array of `{ id, parent }` nodes, **present only when `hierarchy.status` is `verified`**. `id` is the class name as it appears in the source; `parent` is another node's `id`, or `null` for the root. Rebuild the tree by joining on `parent`.
- `workedExample` — a real SPARQL query against this ontology, with `title`, `query`, `result`, and `resultBindings`. Null where none was written.
- `sampleData` — a small instance graph with `nodes` and `edges`, modelled with this ontology, for showing what the data actually looks like. Null where none was written.

**The root node is usually synthetic.** 40 of the 50 verified trees have a root
literally named `Root`, inserted because the source file has several top-level
classes and a forest does not draw well. `Root` is **not a class in the
ontology** — do not report it as one, and do not count it when you quote a class
count. The 10 trees that have a genuine single root: `bfo` (`Entity`), `dolce` (`Entità`), `gfo` (`Entity`), `cidoc-crm` (`CRM实体`), `shacl` (`Resource`), `d3fend` (`D3FEND Core`), `disease-ontology` (`disease`), `obi` (`Thing`), `plant-ontology` (`plant anatomical entity`), `stato` (`entity`).

Ids are lowercase kebab-case and stable. Get the full list from `/api/catalog.json`
or the index at the bottom of this file — do not guess them.

### GET /api/verified.json

`{ "count": 50, "ids": [...] }`. The cheapest way to filter before you trust a tree.

### POST /api/recommend

Body `{"prompt": "what you are modelling"}`, max 500 characters. Returns
`combination` (prose on how the suggestions fit together), `recommendations`
(each with `id`, `name`, `url`, `verified`, `licence`, `why`), `caveat`, and
`model`.

This one is not static: it calls a language model on a personal key. Treat it as
best-effort — it can be slow, rate-limited, or down, and its suggestions are
suggestions. The deterministic endpoints above are the ones to build on.

## MCP server

If your client speaks the [Model Context Protocol](https://modelcontextprotocol.io), connect to
`https://ontology.guru/mcp` and skip the REST endpoints entirely. It is stateless Streamable HTTP:
POST one JSON-RPC message per request, no key, no session, no auth, every origin allowed.

Both protocol eras are served from the same endpoint — the `initialize` handshake used by
`2025-03-26` through `2025-11-25`, and the handshake-free `2026-07-28` revision where the
protocol version rides in `params._meta` and the `MCP-Protocol-Version` / `Mcp-Method` /
`Mcp-Name` headers must mirror the body. A POST with no version header is treated as
`2025-03-26`. GET and DELETE return `405`; there is no server-initiated stream and no session
to end.

Tools (all read-only):

- `search_ontologies` — Search 120 published ontologies by keyword, domain, licence, or whether their class hierarchy was verified against the published source file. Start here — it is deterministic and free. Returns matching entries with licence and hierarchy status.
- `get_ontology` — Full record for one ontology by id, including its class hierarchy when that hierarchy was extracted from the published source file. Ids come from search_ontologies — never guess one.
- `check_licence` — The operative licence terms for one ontology: whether you may redistribute it, whether attribution is required and with exactly what notice, and whether share-alike propagates to anything you derive from it. Says plainly when the licence was never verified.
- `list_verified` — Every id whose class hierarchy was extracted from the ontology's own published file. The cheapest way to filter before trusting a tree.
- `recommend_ontologies` — Describe what you are modelling in prose and get suggested ontologies — often a combination — with a reason for each. This one calls a language model, so it is slower, best-effort, and can be unavailable. Prefer search_ontologies when you already know the domain or keywords; use this when the problem is easier to describe than to search.

```bash
# Everything the server offers
curl -s https://ontology.guru/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq -r '.result.tools[].name'

# A search, without the handshake — the server is stateless, so none is needed
curl -s https://ontology.guru/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0","id":2,"method":"tools/call",
  "params":{"name":"search_ontologies","arguments":{"query":"provenance","verifiedOnly":true}}
}' | jq -r '.result.structuredContent.results[].id'
```

Add it to Claude Code with:

```bash
claude mcp add --transport http ontology-guru https://ontology.guru/mcp
```

## Recipes

```bash
# Which entries can I actually trust a hierarchy from?
curl -s https://ontology.guru/api/verified.json | jq -r '.ids[]'

# One entry, reduced to the three things that usually matter
curl -s https://ontology.guru/api/ontology/prov-o.json \
  | jq '{id, licence: .licence.id, status: .hierarchy.status, classes: (.classHierarchy | length)}'

# Everything in a domain that is both verified and freely redistributable
curl -s https://ontology.guru/api/catalog.json | jq -r '
  .ontologies[]
  | select(.category == "Healthcare")
  | select(.hierarchy.status == "verified")
  | select(.licence.redistribution == "redistribution" or .licence.redistribution == "attribution_required")
  | "\(.id)\t\(.licence.id)"'

# The attribution string you must reproduce, for everything you plan to ship
curl -s https://ontology.guru/api/catalog.json \
  | jq -r '.ontologies[] | select(.licence.notice) | .licence.notice'

# Ask for a recommendation in prose
curl -s -X POST https://ontology.guru/api/recommend \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "sensor readings from building equipment"}' \
  | jq '.recommendations[] | {id, licence, why}'
```

## Pitfalls

1. **Do not treat `withheld` as "has no classes".** `snomed-ct` is withheld because the licence does not permit redistribution — it is a large ontology, not an empty one.
2. **Do not present `classHierarchy` as the complete ontology.** Compare `classesShown` with `classesInSource` and say which you are showing.
3. **Do not repeat a licence label as fact when `licence.verified` is false.** 94 of 120 entries are in that state.
4. **Do not invent ids.** They are stable and enumerable; a guessed id 404s.
5. **Do not build a pipeline on `/api/recommend`.** It is a model call on a personal key. Use `catalog.json` for anything that has to be reproducible.
6. **Cite provenance when you report a tree.** `hierarchy.source` and `hierarchy.retrievedAt` exist so your answer can carry them.

## Coverage by domain

- AI & Machine Learning — 3 entries, 3 verified
- Agriculture & Environment — 2 entries, 0 verified
- Blockchain — 1 entry, 0 verified
- Commerce — 3 entries, 0 verified
- Cybersecurity — 7 entries, 1 verified
- Energy — 2 entries, 0 verified
- Finance — 3 entries, 0 verified
- Foundational — 15 entries, 6 verified
- Geospatial — 2 entries, 1 verified
- Government — 3 entries, 0 verified
- Healthcare — 12 entries, 0 verified
- Industry — 3 entries, 0 verified
- IoT & Sensors — 2 entries, 2 verified
- Knowledge Graphs — 10 entries, 0 verified
- Legal — 3 entries, 0 verified
- Life Sciences — 14 entries, 13 verified
- Media & Culture — 3 entries, 1 verified
- NLP & Linguistics — 2 entries, 1 verified
- Robotics — 2 entries, 0 verified
- Smart Infrastructure — 3 entries, 2 verified
- Social & Events — 1 entry, 0 verified
- Software & Data — 2 entries, 1 verified
- Web Standards — 22 entries, 19 verified

Licence labels in use: `Commercial`, `Copyleft`, `Mixed`, `Open`, `Research`, `Restricted`, `Unverified`.

## Complete index

`id` — name (category) · licence label · hierarchy status

- `bfo` — BFO (Foundational) · Open · verified, 38/38 classes shown
- `dolce` — DOLCE (Foundational) · Open, unverified · verified, 70/79 classes shown
- `sumo` — SUMO (Foundational) · Open, unverified · withheld (unverified)
- `ufo` — UFO (Foundational) · Open, unverified · verified, 40/51 classes shown
- `gfo` — GFO (Foundational) · Open, unverified · verified, 62/77 classes shown
- `yamato` — YAMATO (Foundational) · Open, unverified · withheld (unverified)
- `gist` — gist (Foundational) · Open · verified, 70/97 classes shown
- `cidoc-crm` — CIDOC-CRM (Foundational) · Open, unverified · verified, 39/76 classes shown
- `emmo` — EMMO (Foundational) · Open, unverified · withheld (unverified)
- `iof-core` — IOF Core (Foundational) · Open, unverified · withheld (unverified)
- `iso-15926` — ISO 15926 (Foundational) · Mixed, unverified · withheld (unverified)
- `wikidata` — Wikidata (Knowledge Graphs) · Open, unverified · withheld (unverified)
- `dbpedia` — DBpedia (Knowledge Graphs) · Open, unverified · withheld (unverified)
- `yago` — YAGO (Knowledge Graphs) · Open, unverified · withheld (unverified)
- `conceptnet` — ConceptNet (Knowledge Graphs) · Open, unverified · withheld (unverified)
- `wordnet` — WordNet (Knowledge Graphs) · Open, unverified · withheld (unverified)
- `geonames` — GeoNames (Knowledge Graphs) · Open, unverified · withheld (unverified)
- `schema-org` — Schema.org (Web Standards) · Copyleft · verified, 80/1032 classes shown
- `rdf` — RDF (Web Standards) · Open, unverified · verified, 16/16 classes shown
- `owl` — OWL (Web Standards) · Open, unverified · verified, 31/31 classes shown
- `skos` — SKOS (Web Standards) · Open · verified, 5/5 classes shown
- `sparql` — SPARQL (Web Standards) · Open, unverified · withheld (unverified)
- `prov-o` — PROV-O (Web Standards) · Open · verified, 32/32 classes shown
- `shacl` — SHACL (Web Standards) · Open, unverified · verified, 40/42 classes shown
- `dublin-core` — Dublin Core (Web Standards) · Open · verified, 24/24 classes shown
- `foaf` — FOAF (Web Standards) · Open · verified, 17/17 classes shown
- `ssn-sosa` — SSN/SOSA (Web Standards) · Open · verified, 22/22 classes shown
- `dcat` — DCAT (Web Standards) · Open · verified, 11/11 classes shown
- `snomed-ct` — SNOMED CT (Healthcare) · Restricted · withheld (licence)
- `hl7-fhir` — HL7 FHIR (Healthcare) · Open · withheld (wrong-shape)
- `loinc` — LOINC (Healthcare) · Open · withheld (licence)
- `mesh` — MeSH (Healthcare) · Open · withheld (unverified)
- `gene-ontology` — Gene Ontology (Life Sciences) · Open, unverified · verified, 80/38246 classes shown
- `chebi` — ChEBI (Life Sciences) · Open, unverified · verified, 80/218542 classes shown
- `hpo` — HPO (Life Sciences) · Open, unverified · verified, 80/19837 classes shown
- `biopax` — BioPAX (Life Sciences) · Open, unverified · verified, 66/69 classes shown
- `fibo` — FIBO (Finance) · Open, unverified · withheld (unverified)
- `stix` — STIX (Cybersecurity) · Open, unverified · withheld (unverified)
- `mitre-attack` — ATT&CK (Cybersecurity) · Open, unverified · withheld (unverified)
- `d3fend` — D3FEND (Cybersecurity) · Open, unverified · verified, 80/4455 classes shown
- `saref` — SAREF (IoT & Sensors) · Open, unverified · verified, 70/99 classes shown
- `brick-schema` — Brick Schema (Smart Infrastructure) · Open, unverified · verified, 80/1804 classes shown
- `geosparql` — GeoSPARQL (Geospatial) · Open, unverified · verified, 8/8 classes shown
- `aio` — AIO (AI & Machine Learning) · Open, unverified · verified, 70/443 classes shown
- `ml-schema` — ML-Schema (AI & Machine Learning) · Open, unverified · verified, 26/26 classes shown
- `nif` — NIF (NLP & Linguistics) · Open, unverified · verified, 21/21 classes shown
- `activitypub` — ActivityPub (Social & Events) · Open, unverified · withheld (unverified)
- `cora` — CORA (Robotics) · Open, unverified · withheld (unverified)
- `spdx` — SPDX (Software & Data) · Open, unverified · verified, 70/91 classes shown
- `ethon` — EthOn (Blockchain) · Open, unverified · withheld (unverified)
- `oeo` — OEO (Energy) · Open, unverified · withheld (unverified)
- `iptc` — IPTC NewsCodes (Media & Culture) · Open, unverified · withheld (unverified)
- `europeana` — Europeana (Media & Culture) · Open, unverified · withheld (unverified)
- `cyc` — Cyc (Foundational) · Mixed, unverified · withheld (unverified)
- `proton` — PROTON (Foundational) · Open, unverified · withheld (unverified)
- `cosmo` — COSMO (Foundational) · Open, unverified · withheld (unverified)
- `ochre` — OCHRE (Foundational) · Open, unverified · withheld (unverified)
- `babelnet` — BabelNet (Knowledge Graphs) · Research, unverified · withheld (unverified)
- `kbpedia` — KBpedia (Knowledge Graphs) · Open, unverified · withheld (unverified)
- `nell` — NELL (Knowledge Graphs) · Research, unverified · withheld (unverified)
- `google-kg` — Google KG (Knowledge Graphs) · Commercial, unverified · withheld (unverified)
- `rdfs` — RDFS (Web Standards) · Open, unverified · verified, 8/8 classes shown
- `owl-time` — OWL-Time (Web Standards) · Open · verified, 22/22 classes shown
- `qudt` — QUDT (Web Standards) · Open · verified, 68/90 classes shown
- `bibo` — BIBO (Web Standards) · Open, unverified · verified, 70/71 classes shown
- `spar` — SPAR (Web Standards) · Open, unverified · verified, 12/12 classes shown
- `goodrelations` — GoodRelations (Web Standards) · Open, unverified · verified, 38/38 classes shown
- `void` — VoID (Web Standards) · Open · withheld (unverified)
- `org` — ORG (Web Standards) · Open · verified, 15/15 classes shown
- `sioc` — SIOC (Web Standards) · Open, unverified · verified, 16/16 classes shown
- `vivo-isf` — VIVO-ISF (Web Standards) · Open, unverified · withheld (unverified)
- `vcard` — vCard (Web Standards) · Open · verified, 63/63 classes shown
- `icd-10` — ICD-10 (Healthcare) · Restricted · withheld (wrong-artifact)
- `rxnorm` — RxNorm (Healthcare) · Open · withheld (unverified)
- `umls` — UMLS (Healthcare) · Restricted · withheld (licence)
- `meddra` — MedDRA (Healthcare) · Restricted · withheld (licence)
- `ncit` — NCIt (Healthcare) · Unverified · withheld (unverified)
- `omop-cdm` — OMOP CDM (Healthcare) · Open · withheld (wrong-shape)
- `dicom` — DICOM (Healthcare) · Unverified · withheld (unverified-licence)
- `cdisc` — CDISC (Healthcare) · Restricted · withheld (licence)
- `disease-ontology` — Disease Ontology (Life Sciences) · Open, unverified · verified, 80/12247 classes shown
- `uberon` — Uberon (Life Sciences) · Open, unverified · verified, 80/14978 classes shown
- `obi` — OBI (Life Sciences) · Open, unverified · verified, 80/5240 classes shown
- `envo` — ENVO (Life Sciences) · Open, unverified · verified, 80/6482 classes shown
- `cell-ontology` — Cell Ontology (Life Sciences) · Open, unverified · verified, 80/3336 classes shown
- `sequence-ontology` — Sequence Ontology (Life Sciences) · Open, unverified · verified, 80/2405 classes shown
- `ncbi-taxonomy` — NCBI Taxonomy (Life Sciences) · Open, unverified · withheld (unverified)
- `efo` — EFO (Life Sciences) · Open, unverified · verified, 80/23336 classes shown
- `edam` — EDAM (Life Sciences) · Open, unverified · verified, 80/3540 classes shown
- `plant-ontology` — Plant Ontology (Life Sciences) · Open, unverified · verified, 80/1659 classes shown
- `xbrl` — XBRL (Finance) · Open, unverified · withheld (unverified)
- `fpml` — FpML (Finance) · Open, unverified · withheld (unverified)
- `gs1` — GS1 (Commerce) · Open, unverified · withheld (unverified)
- `eclass` — eCl@ss (Commerce) · Mixed, unverified · withheld (unverified)
- `unspsc` — UNSPSC (Commerce) · Open, unverified · withheld (unverified)
- `mason` — MASON (Industry) · Open, unverified · withheld (unverified)
- `isa-95` — ISA-95 (Industry) · Commercial, unverified · withheld (unverified)
- `archimate` — ArchiMate (Industry) · Open, unverified · withheld (unverified)
- `lkif` — LKIF (Legal) · Open, unverified · withheld (unverified)
- `akoma-ntoso` — Akoma Ntoso (Legal) · Open, unverified · withheld (unverified)
- `eli` — ELI (Legal) · Open, unverified · withheld (unverified)
- `esco` — ESCO (Government) · Open, unverified · withheld (unverified)
- `ceds` — CEDS (Government) · Open, unverified · withheld (unverified)
- `ocds` — OCDS (Government) · Open, unverified · withheld (unverified)
- `agrovoc` — AGROVOC (Agriculture & Environment) · Open, unverified · withheld (unverified)
- `sweet` — SWEET (Agriculture & Environment) · Open, unverified · withheld (unverified)
- `citygml` — CityGML (Geospatial) · Open, unverified · withheld (unverified)
- `stato` — STATO (AI & Machine Learning) · Open, unverified · verified, 49/1053 classes shown
- `cve` — CVE (Cybersecurity) · Open, unverified · withheld (unverified)
- `cwe` — CWE (Cybersecurity) · Open, unverified · withheld (unverified)
- `capec` — CAPEC (Cybersecurity) · Open, unverified · withheld (unverified)
- `uco` — UCO (Cybersecurity) · Open, unverified · withheld (unverified)
- `wot-td` — WoT TD (IoT & Sensors) · Open, unverified · verified, 8/8 classes shown
- `fiware` — FIWARE (Smart Infrastructure) · Open, unverified · withheld (unverified)
- `bot` — BOT (Smart Infrastructure) · Open, unverified · verified, 9/9 classes shown
- `music-ontology` — Music Ontology (Media & Culture) · Open, unverified · verified, 66/70 classes shown
- `ontolex-lemon` — OntoLex-Lemon (NLP & Linguistics) · Open, unverified · withheld (unverified)
- `ddi` — DDI (Software & Data) · Open, unverified · withheld (unverified)
- `cim` — CIM (Energy) · Commercial, unverified · withheld (unverified)
- `knowrob` — KnowRob (Robotics) · Open, unverified · withheld (unverified)