Ontology

The ontology layer is the top of Definite's meaning stack — the layer above the semantic layer. It is where you name the business concepts your organization talks about — customer, revenue, return, even a plain business term like company — independent of how (or whether) they are modeled in the lakehouse.

A concept points outward through soft, typed links to whatever backs it:

a semantic object (model / dimension / measure / relationship),
a raw lakehouse table or column,
a python / transformation script,
an external doc or URL,
or nothing at all — a standalone concept is first-class.

Links are soft references: the save path enforces each target's shape but only warns about its existence, so you can author ontology before the underlying models, scripts, or tables exist. A target that does not resolve against the catalog comes back in the save response's warnings list; the object saves either way.

The two storage tables (semantic.ontology_objects and semantic.ontology_links) physically live in the semantic schema, but they are owned by the ontology layer.

HTTP API

All endpoints require a bearer token (the same session token the CLI uses).

Method	Path	What it does
`GET`	`/api/v1/ontology`	List every concept. Add `?q=` for token-aware ranked search across names, aliases, guidance, metadata, and linked targets. Returns `{objects:[…]}`.
`GET`	`/api/v1/discovery/search?q=...`	Recommended analytical entry point: search ontology and semantic metadata together.
`POST`	`/api/v1/ontology/resolve`	Bind one surface token to a single concept. Body `{term, context?}`; returns `{term, resolved, binding, value, confidence, alternatives, candidates}`. `confidence` is `high` / `medium` / `ambiguous` / `none`.
`GET`	`/api/v1/ontology/{name}`	One concept bundled with its links. `{object}`.
`PUT`	`/api/v1/ontology/{name}`	Atomic save — body is an `OntologyObjectSpec` (replace-semantics: a link you drop from the body is removed). `{object}`.
`DELETE`	`/api/v1/ontology/{name}`	Drop one concept and all of its links. `204`.

The CLI

Ontology commands are thin wrappers over the API. Same auth and --api-url flags as definite run — explicit --token, then DEFINITE_TOKEN, then the session saved by definite login.

Command	What it does
`definite discover <query>`	Search ontology and semantic metadata together before querying data.
`definite ontology list`	List every concept (name, kind, label).
`definite ontology search <query>`	Find concepts by name, alias, guidance, or linked target.
`definite ontology resolve <term>`	Bind one code, value, or short word to a single concept. `--context "<text>"` breaks homonym ties; a genuine tie prints every candidate instead of guessing.
`definite ontology get <name>`	Show one concept as YAML — pipe to a file to round-trip.
`definite ontology save -f <file>`	Create or replace one concept from a YAML file. Atomic.
`definite ontology delete <name>`	Drop one concept and all of its links. `--yes` to skip the prompt.

Add --format json on any subcommand to get machine output (Fi runs do this automatically when stdout is not a TTY).

YAML format

One file, one concept. The body is the API's OntologyObjectSpec shape.

A revenue metric concept linked to a semantic measure, a source column, and a default time dimension:

name: revenue
kind: metric_concept
label: Revenue
aliases: [sales, gmv, gross revenue]
description: Realized sales from order items.
guidance:
  preferred_for: [sales reporting, revenue trends]
  avoid: [products.retail_price as realized revenue]
links:
  - relation_type: measured_by
    target: measure:thelook_order_items.total_revenue
  - relation_type: source_column
    target: column:thelook.order_items.sale_price
  - relation_type: default_time
    target: dimension:thelook_order_items.created_date

Standalone concepts

A concept needs no lakehouse backing. A pure business term — something everyone in the company says, but that nothing in the warehouse models yet — is a legal, first-class concept with an empty links list:

name: company
kind: entity
label: Company
aliases: [account, organization, org]
description: A business we sell to or partner with.
links: []

Zero-link concepts are never rejected. They let you capture the shared vocabulary first and wire up the links — to semantic objects, tables, scripts, or docs — later, as the data catches up to the language.

Supported target forms

target is a soft typed reference. Shape is enforced; the linked object does not have to exist when you save.

table: / column: targets are resolved against the lake's information_schema, and model: / dimension: / measure: / relationship: targets against the semantic.* tables. Anything that does not resolve is reported in the save response's warnings list, each entry carrying a severity:

severity	meaning
`unresolved`	the target's parent does not exist yet — a model nobody has authored, a schema that has not landed. Expected while the data catches up to the language; always advisory.
`missing`	the parent does exist and the target is not in it — a dropped column, a table named against the wrong schema. This is a real error and is what a future enforcement mode rejects.

Note that on-prem runs USE LAKE, so targets are schema-qualified only: a LAKE.-prefixed target is a shape error and is rejected outright.

ontology:<name>
model:<model>
dimension:<model>.<dimension>
measure:<model>.<measure>
relationship:<model>.<relationship>
table:<schema>.<table>
column:<schema>.<table>.<column>
script:<path> — a python / transformation reference (e.g. script:transforms/revenue.py)
doc:<ref> — an external definition (a doc id or path)
url:<ref> — an external URL

Unified Fi discovery flow

For every analytical question, Fi starts with one unified discovery call that searches ontology concepts and semantic models/measures/dimensions. It reads both result sets, describes likely concepts and models, and follows linked semantic definitions before falling back to raw tables. A concept that links to a measure: or dimension: routes the agent straight to a certified definition; a standalone concept tells the agent the term is real but not yet modeled. Empty discovery is not evidence that the lakehouse lacks the data.