The ontology is the semantic spine of Marsovius. Every module reads through it. Every dashboard, every workflow, every agent grounds on it. Designing it well is the most consequential hour of any engagement.

What lives in the ontology

Object types — Customer, Invoice, Asset, Subject. Each declares properties, a key, the source it maps to, and the actions allowed on it.
Link types — typed relationships between objects (Customer pays Invoice).
Action types — write-backs executed against the source connector. Every mutation flows through an action; nothing escapes the contract.
Computed properties — derived values bound to a function. Read through the ontology like any other field.

A typed object is not a database row. It carries semantics: a display, a lineage, validations, formatters, write-back rules. Every app that wants a good representation of an object reads it through the ontology service rather than re-querying a raw table.

Where it is stored

The canonical store is a small set of YAML files under ontology/ in marsovius-platform — one file per object type, one per link type. The API loads them at startup into OBJECT_TYPES and LINK_TYPES, and exposes a hot-reload endpoint for live edits. The editor surface is Codex — the ontology editor module — and the explorer is Lyceum.

Per-workspace folders (ontology/{slug}/...) are the target; today the ontology is shared and tagged by workspace. See the platform's docs/ROADMAP.md for the migration.

Versioning

The ontology is held in git. Every change is reviewed in code. A workflow built today is reproducible two years from now from the same commit.

How a legate designs the first ontology

A senior data architect from the customer pairs with the legate for one week. They walk the existing operational systems, identify the seven to twelve object types that matter most, and check each against the customer's regulatory and operational reality. The result is committed to the customer's repository and signed.

Where to read next

The modules — Codex, Lyceum, and the rest.
The platform's docs/MODULES.md for the canonical etymology.
The platform's docs/apps/codex.md for the ontology editor's implementation detail.