Contract schema

Contracts are split across four directories, each validated against its own Pydantic model at load time. See Contracts & guardrails for the concepts behind these fields.

Directory	Model	Loaded by
`contracts/metrics/*.yaml`	`MetricBinding`	`load_metric_bindings`
`contracts/guardrails/.yaml` (excluding `finality-.yaml`)	`Guardrail`	`load_guardrails`
`contracts/guardrails/finality-*.yaml`	`FinalityRule`	`load_finality`
`contracts/assertions/*.yaml`	`Assertion`	`load_assertions`
`contracts/policies/tenancy.yaml`	`TenancyPolicy`	`load_tenancy_policy`
`contracts/policies/roles.yaml`	`RolePolicy`	`load_role_policy`

A finality rule is filename-discriminated from a guardrail: both live under contracts/guardrails/, but only files named finality-*.yaml load as FinalityRule. Everything else in that directory loads as Guardrail.

`contracts/metrics/*.yaml`: `MetricBinding`

metric: revenue
owner: "@data-platform"
canonical:
  kind: single
  source: orders
  measure: total_revenue
provenance: human_curated
aliases: ["net revenue", "rev"]
status: active

Field	Type	Default	Governs
`metric`	`str`	n/a (required)	The logical metric name the binding resolves.
`owner`	`str \| null`	`null`	Team/person accountable for the definition.
`canonical`	`CanonicalRef`	n/a (required)	The compilation strategy and its parameters, see below.
`provenance`	`Provenance`	`human_curated`	`board_approved` \| `human_curated` \| `inferred`.
`label`	`str \| null`	`null`	Human-readable display name.
`aliases`	`list[str]`	`[]`	Alternate names resolving to this binding (must not duplicate `metric` itself).
`deprecated_alternatives`	`list[DeprecatedAlternative]`	`[]`	Known non-canonical definitions, explicitly flagged as superseded.
`examples`	`list[Example]`	`[]`	Usage-backed example queries (from assertions, observed queries, or usage evidence).
`status`	`Status`	`active`	`active` \| `deprecated`. Only `active` bindings are checked for duplicate names/aliases across the project.

A metric binding is what turns a name like revenue into something the compiler can actually run. metric is the name callers ask for, canonical is the recipe for computing it, and owner/aliases/examples exist to keep the binding discoverable and accountable rather than a bare formula nobody can trace back to a person or a prior query. status: deprecated lets you keep an old binding around for history without it competing for a name a newer binding now owns. Ambiguity rule: if a requested name matches zero or more than one active binding, the compiler returns a structured AMBIGUOUS/UNRESOLVED error rather than guessing.

`canonical` (`CanonicalRef`): one shape per `kind`

kind selects a compilation strategy, and each kind needs a different subset of the fields below. Missing a required field for the chosen kind raises a located error at load time rather than failing later at query time. Most metrics are single, a direct pointer at one measure on one source. The other kinds exist for shapes a plain source-and-measure pair can’t express on its own: ratio and weighted_avg combine two other metrics after they’re each aggregated independently, semi_additive handles point-in-time values like balances that can’t just be summed across every dimension, distinct_count and percentile recompute their value at whatever grain the query asks for instead of pre-aggregating, and opaque is the escape hatch for a measure that’s only trustworthy at the exact grain it was computed at.

`kind`	Required fields	Compiles as
`single` (default)	`source`, `measure`	Resolve to one `(source, measure)` pair.
`ratio`	`numerator`, `denominator` (metric names)	Aggregate numerator & denominator independently, divide after.
`weighted_avg`	`weighted_sum`, `weight` (metric names)	Weighted-sum ÷ weight.
`semi_additive`	`source`, `measure`, `collapse_dimension`, `collapse_agg`	Sum over every dimension except `collapse_dimension`, which collapses via `collapse_agg`.
`distinct_count`	`source`, `distinct_on` (column name)	Recompute `count(distinct …)` at the requested grain.
`percentile`	`source`, `column`, `quantile` ∈ (0, 1)	Recompute the quantile at the requested grain from base rows.
`opaque`	`source`, `measure`, `native_grain` (non-empty list of dimension columns)	Serve only at its declared native grain. Any other grain returns `UNSUPPORTED_MEASURE`.

Full field list on CanonicalRef:

Field	Type	Default	Used by
`kind`	`BindingKind`	`single`	All.
`source`	`str \| null`	`null`	`single`, `semi_additive`, `distinct_count`, `percentile`, `opaque`.
`measure`	`str \| null`	`null`	`single`, `semi_additive`, `opaque`.
`numerator` / `denominator`	`str \| null`	`null`	`ratio` (both are metric names).
`weighted_sum` / `weight`	`str \| null`	`null`	`weighted_avg` (both are metric names).
`on_zero_denominator`	`OnZeroDenominator`	`null` (coerced)	`ratio`/`weighted_avg`: `null` \| `zero` \| `error` when the denominator is zero.
`collapse_dimension`	`str \| null`	`null`	`semi_additive`: the dimension that collapses (typically time).
`collapse_agg`	`CollapseAgg \| null`	`null`	`semi_additive`: `last` \| `first` \| `avg` \| `min` \| `max`.
`distinct_on`	`str \| null`	`null`	`distinct_count`: column to count distinct values of.
`column`	`str \| null`	`null`	`percentile`: column the quantile is computed over.
`quantile`	`float \| null`	`null`	`percentile`: value in (0, 1).
`native_grain`	`list[str] \| null`	`null`	`opaque`: dimension columns the metric is pre-aggregated to.
`population_filter`	`str \| null`	`null`	All `kind`s: SQL predicate AND-ed into every leaf query’s `WHERE` before aggregation, defining the population the metric is about (e.g. excluding test accounts).

`deprecated_alternatives[]` (`DeprecatedAlternative`)

Field	Type	Default	Governs
`source`	`str`	n/a (required)	The superseded source.
`ref`	`str`	n/a (required)	The superseded measure/column reference.
`reason`	`str`	n/a (required)	Why it was superseded.

`examples[]` (`Example`)

Field	Type	Default	Governs
`query`	`ExampleQuery`	n/a (required)	`{ metrics: list[str], dimensions: list[str] = [], filters: list[str] = [] }`.
`origin`	`str`	n/a (required)	Typed discriminator: `observed_query`, `assertion:<id>`, or `usage_evidence:<id>`.
`frequency`	`int \| null`	`null`	Observed count, when available (omitted for assertion-sourced examples).

`contracts/guardrails/*.yaml`: `Guardrail`

id: revenue-excludes-refunds
applies_to: { source: orders, measure: total_revenue }
kind: mandatory_filter
filter: "status != 'refunded'"
severity: error
rationale: "Refunds are reversals, not revenue."

Field	Type	Default	Governs
`id`	`str`	n/a (required)	Guardrail identifier.
`applies_to`	`AppliesTo`	n/a (required)	Target: `{ source, measure }` or `{ metric }`, exactly one shape, never both or neither.
`kind`	`GuardrailKind`	n/a (required)	`mandatory_filter` \| `required_dimension` \| `restrict_source` \| `min_trust`, see below.
`filter`	`str \| null`	`null`	Required (non-empty) when `kind: mandatory_filter`.
`restrict_to`	`RestrictTo \| null`	`null`	Required when `kind: restrict_source`: `{ role: "final" \| "provisional" }`.
`level`	`str \| null`	`null`	Required when `kind: min_trust`, one of `caution` \| `provisional` \| `trusted`, the minimum trust tier the query must meet. See Trust score.
`dimension`	`str \| null`	`null`	Required (non-empty) when `kind: required_dimension`, the dimension name the query must group by or filter on.
`context`	`str \| null`	`null`	Required (non-empty) when `kind: restrict_source` or `kind: min_trust`. Optional for `required_dimension` (omit to apply in every context, including no context at all). The named context the restriction applies in (e.g. `board_reporting`).
`severity`	`Severity`	`error`	`error` blocks the query. `warn` lets it through with a `warnings[]` entry instead. See below for how this applies per `kind`.
`rationale`	`str`	n/a (required)	Why the rule exists, surfaced to the caller.
`phase`	`str \| null`	`null`	Optional compiler-pipeline phase hint.

`kind`	Behavior	Status
`mandatory_filter`	The predicate is always AND-ed into the compiled `WHERE`, regardless of `severity`. `severity: warn` additionally adds a `warnings[]` entry.	Enforced
`restrict_source`	In a given `context`, only the source matching `restrict_to.role` is permitted.	Enforced
`required_dimension`	The query must group by or filter on `dimension` (by its canonical name, a qualified `alias.dim` form, or a declared alias) or be rejected.	Enforced
`min_trust`	In a given `context`, blocks (`severity: error`) or warns if the computed trust tier is below `level`.	Enforced

A guardrail attaches a rule to either a specific (source, measure) pair or a whole metric, chosen by which shape you fill in under applies_to. Which fields besides kind are required depends entirely on that kind: a mandatory_filter needs filter, a restrict_source needs restrict_to and context, a min_trust needs level and context, a required_dimension needs dimension. severity decides how hard the rule bites: for restrict_source, min_trust, and required_dimension, error stops the query outright while warn lets it through with a warnings[] entry instead. mandatory_filter has no “block” action to gate, its predicate is always injected, and severity: warn there only adds the warnings[] entry. rationale is what actually gets shown to whoever hit the block (or the warning), so it’s worth writing for a person, not just as a code comment.

`contracts/guardrails/finality-*.yaml`: `FinalityRule`

metric: revenue
realizations:
  - { source: orders,    role: final,       watermark: "business_day - 1 day" }
  - { source: orders_rt, role: provisional }
coalescing: "window <= watermark ? final : provisional"
result_flag: per_row
board_only_final: true

Field	Type	Default	Governs
`metric`	`str`	n/a (required)	The metric these realizations apply to.
`realizations`	`list[Realization]`	`[]`	Physical sources along the freshness axis, see below.
`coalescing`	`str \| null`	`null`	Expression selecting which realization backs a given time window.
`result_flag`	`str \| null`	`null`	How the `final`/`provisional` tag is attached to results (e.g. `per_row`).
`board_only_final`	`bool`	`false`	Pairs with a `restrict_source` guardrail so a restricted context sees only the `final` source.

`realizations[]` (`Realization`)

Field	Type	Default	Governs
`source`	`str`	n/a (required)	The semantic source backing this realization.
`role`	`str`	n/a (required)	`"final"` or `"provisional"`.
`watermark`	`str \| null`	`null`	Cutoff expression for this realization.
`tz`	`str \| null`	`null`	Timezone the watermark is evaluated in.

A finality rule exists for a metric that can be served from more than one physical realization of the same data, typically a slower, fully-reconciled table and a faster, real-time one. realizations lists each candidate source along with its role, final or provisional, and coalescing is the expression that decides which realization actually backs a given time window in the result. board_only_final is the piece that ties this to a guardrail: pair it with a restrict_source guardrail so a sensitive context (board reporting, say) only ever sees the final realization, never the faster but not-yet-settled one.

`contracts/assertions/*.yaml`: `Assertion`

id: revenue-2025-q1
query: { metrics: [revenue], filters: ["order_date in 2025-Q1"] }
expect: { rows: 1, values: { revenue: 4218334.10 }, tolerance: 0.01 }
source_of_truth: "Finance close, FY25 Q1"

Field	Type	Default	Governs
`id`	`str`	n/a (required)	Assertion identifier.
`query`	`dict[str, Any]`	n/a (required)	A semantic query (`metrics`, `dimensions`, `filters`) run through the compiler.
`expect`	`AssertionExpect`	`{}`	Expected result, see below.
`source_of_truth`	`str \| null`	`null`	Where the expected value came from (e.g. a finance close).

`expect` (`AssertionExpect`)

Field	Type	Default	Governs
`rows`	`int \| null`	`null`	Expected row count.
`values`	`dict[str, Any]`	`{}`	Expected value per output column.
`tolerance`	`float \| null`	`null`	Relative tolerance for numeric comparison (e.g. `0.01` = 1%). `null` means exact match.

An assertion is a known-good query paired with the answer it should produce, usually sourced from a finance close or another trusted report. query is run through the exact same compiler path a real caller would hit, so an assertion tests the whole stack, not just the metric definition in isolation. source_of_truth matters more than it looks: it’s the thing that lets a reviewer trust the expected value in the first place, an assertion with no traceable origin is just a number someone typed in. canonic assert runs every assertion through the compiler and gates on the result. canonic query --harness runs matching assertions inline against a single query.

`contracts/policies/tenancy.yaml`: `TenancyPolicy`

See Tenancy & access control for the concepts behind this file. At most one per project. Its presence is the feature switch for row-level tenant isolation.

schema: tenancy/v1
claim: merchant_id
on_missing_principal: deny

scoped_sources:
  - { source: orders,      column: merchant_id }
  - { source: order_items, column: merchant_id }

shared_sources:
  - dim_date

undeclared_source: deny

Field	Type	Default	Governs
`schema`	`Literal["tenancy/v1"]`	n/a (required)	Schema discriminator.
`claim`	`str`	n/a (required)	The verified-token claim carrying the tenant identity.
`on_missing_principal`	`deny \| allow_unscoped`	`deny`	Behavior when tenancy is active but the request carries no resolvable tenant.
`scoped_sources`	`list[ScopedSource]`	`[]`	Sources tenant-scoped on a named column, see below.
`shared_sources`	`list[str]`	`[]`	Source names explicitly declared tenant-neutral: no predicate is injected for them.
`undeclared_source`	`deny \| warn`	`deny`	Behavior when a query reaches a source in neither `scoped_sources` nor `shared_sources`.

`scoped_sources[]` (`ScopedSource`)

Field	Type	Default	Governs
`source`	`str`	n/a (required)	The scoped source’s name.
`column`	`str`	n/a (required)	The column carrying the tenant id: the injected predicate is `<source>.<column> = :tenant`.

Validation rules, enforced at load time with a file+line location:

scoped_sources and shared_sources must be disjoint: a source name appearing in both fails validation.
tenancy_for(source) is total over every source in the project once this file is present: a source reachable by a query but declared in neither list is Undeclared, governed by undeclared_source rather than treated as unrestricted.

`contracts/policies/roles.yaml`: `RolePolicy`

See Tenancy & access control for the two runtime gaps (dimensions enforcement, knowledge.allow_tags defaults) that matter when authoring this file.

schema: roles/v1
claim: roles
default_role: merchant_viewer

roles:
  merchant_viewer:
    metrics:    { allow: ["revenue", "order_count", "aov"] }
    dimensions: { deny: ["customer_email", "customer_phone"] }
    knowledge:  { allow_tags: ["public", "merchant"] }
    run_sql:    false
  merchant_admin:
    inherits: merchant_viewer
    dimensions: { deny: [] }
    masking:
      - { column: customers.customer_email, strategy: partial }
  platform_analyst:
    tenancy_exempt: true
    metrics: { allow: ["*"] }
    run_sql: true

Field	Type	Default	Governs
`schema`	`Literal["roles/v1"]`	n/a (required)	Schema discriminator.
`claim`	`str`	n/a (required)	The token claim carrying the caller’s role list (array of strings, or a single string).
`default_role`	`str \| null`	`null`	Applied when the token carries no role claim. Must be a declared role, see validation rules below. If unset, a principal with no roles resolves to deny-everything.
`roles`	`dict[str, RoleDef]`	`{}`	Named role definitions, keyed by role name.

`roles{}` (`RoleDef`): one entry per role name

Field	Type	Default	Governs
`inherits`	`str \| null`	`null`	A single parent role name, see the field-level-override rule below.
`metrics`	`AllowDenyPolicy`	`{allow: null, deny: []}`	Which metric names this role may query.
`dimensions`	`AllowDenyPolicy`	`{allow: null, deny: []}`	Which dimension names this role may query. Parsed and validated, but not enforced at query time today.
`knowledge`	`KnowledgePolicy`	`{allow_tags: []}`	`{allow_tags: list[str]}`: which knowledge-page tags this role may search/read.
`run_sql`	`bool`	`false`	Whether this role may call `run_sql` at all.
`tenancy_exempt`	`bool`	`false`	Bypasses tenant-predicate injection entirely.
`masking`	`list[MaskingRule]`	`[]`	Column-masking rules, see below.

AllowDenyPolicy (metrics/dimensions): allow: null (default) is unrestricted subject to deny. allow: [] is a deliberate allow-nothing. "*" in allow is the explicit wildcard. deny always wins over allow.

`masking[]` (`MaskingRule`)

Field	Type	Default	Governs
`column`	`str`	n/a (required)	`<source>.<column>`: the canonical source/column, never a join alias. The rule applies to every alias resolving to that source, self-joins included.
`strategy`	`null \| hash \| partial`	n/a (required)	`null`: replaced with SQL `NULL`. `hash`: `MD5(CAST(... AS TEXT))`. `partial`: first two characters kept, rest replaced with `'***'`.

Validation rules, enforced at load time with a file+line location:

default_role, if set, must name a role declared in roles.
inherits, if set, must resolve to a declared role and the resulting chain must be acyclic: a role that (directly or transitively) inherits from itself fails validation.
inherits is single-parent field-level override, not list-merge: a role that explicitly authors a field (even to an empty list) replaces the parent’s value for that field wholesale. A field left untouched inherits the parent’s value unchanged.

Getting Started

Concepts

CLI Reference

MCP / Agent Integration

Guides

Reference

Contract schema

`contracts/metrics/*.yaml`: `MetricBinding`

`canonical` (`CanonicalRef`): one shape per `kind`

`deprecated_alternatives[]` (`DeprecatedAlternative`)

`examples[]` (`Example`)

`contracts/guardrails/*.yaml`: `Guardrail`

`contracts/guardrails/finality-*.yaml`: `FinalityRule`

`realizations[]` (`Realization`)

`contracts/assertions/*.yaml`: `Assertion`

`expect` (`AssertionExpect`)

`contracts/policies/tenancy.yaml`: `TenancyPolicy`

`scoped_sources[]` (`ScopedSource`)

`contracts/policies/roles.yaml`: `RolePolicy`

`roles{}` (`RoleDef`): one entry per role name

`masking[]` (`MaskingRule`)

​contracts/metrics/*.yaml: MetricBinding

​canonical (CanonicalRef): one shape per kind

​deprecated_alternatives[] (DeprecatedAlternative)

​examples[] (Example)

​contracts/guardrails/*.yaml: Guardrail

​contracts/guardrails/finality-*.yaml: FinalityRule

​realizations[] (Realization)

​contracts/assertions/*.yaml: Assertion

​expect (AssertionExpect)

​contracts/policies/tenancy.yaml: TenancyPolicy

​scoped_sources[] (ScopedSource)

​contracts/policies/roles.yaml: RolePolicy

​roles{} (RoleDef): one entry per role name

​masking[] (MaskingRule)

`contracts/metrics/*.yaml`: `MetricBinding`

`canonical` (`CanonicalRef`): one shape per `kind`

`deprecated_alternatives[]` (`DeprecatedAlternative`)

`examples[]` (`Example`)

`contracts/guardrails/*.yaml`: `Guardrail`

`contracts/guardrails/finality-*.yaml`: `FinalityRule`

`realizations[]` (`Realization`)

`contracts/assertions/*.yaml`: `Assertion`

`expect` (`AssertionExpect`)

`contracts/policies/tenancy.yaml`: `TenancyPolicy`

`scoped_sources[]` (`ScopedSource`)

`contracts/policies/roles.yaml`: `RolePolicy`

`roles{}` (`RoleDef`): one entry per role name

`masking[]` (`MaskingRule`)