Skip to main content
canonic’s context lives in three committed surfaces: plain files in your git repo, reviewed like code. Each answers a different question.
LayerFileAnswersOwned by
Semanticssemantics/**/*.yaml”How do I query this safely?”: tables, types, grains, joins, measuresauto-maintained
Knowledgeknowledge/**/*.md”What does this mean to the business?”: definitions, caveats, policiesauto-maintained
Contractscontracts/**/*.yaml”Which definition is canonical, and what must the answer obey?“human-owned

​
The split rule

  • Changes how the SQL runs → semantics.
  • A human needs it to trust the answer → knowledge.
  • Governs which definition is authoritative or what an answer must satisfy → contracts.
The key idea: a knowledge page explains why “amount includes refunds unless filtered.” A contract makes the SQL obey it. Documented caveats become enforced guardrails, so the warning can’t be silently ignored.

​
Why three surfaces, not one

Each layer has a different owner and a different update cadence:
  • Semantics is machine-derived from your live schema (tables, columns, grains, joins) and safe to auto-refresh on every canonic ingest: it describes physical reality, so it should track physical reality.
  • Knowledge carries business prose that’s also auto-drafted from evidence (dbt descriptions, Notion pages, BI usage), but is meant to be refined by a human over time: it’s read-heavy context, not enforcement.
  • Contracts decide what’s authoritative and mandatory. This is deliberately human-owned: which of two conflicting “revenue” definitions wins, and which guardrails are non-negotiable, are governance decisions canonic surfaces but never makes for you.
This is also why ingestion is propose-only: a human_curated or board_approved fact in any layer is never silently overwritten by new evidence; at most, a conflict is flagged for review.

Semantics

Tables, grains, joins, and measures: what the compiler queries against.

Knowledge

Business meaning, caveats, and policies: searchable and graph-linked.

Contracts

Canonical bindings and guardrails: what the compiler must obey.