tycoon semantics¶
Emit and validate Open Semantic Interchange (OSI) YAML from your dbt marts. dbt MetricFlow stays the source of truth — the OSI file is a portable view downstream consumers (Snowflake Cortex, ThoughtSpot, RelationalAI, ...) can ingest directly without per-tool integration.
Two subcommands: scaffold, doctor.
Conservative dial¶
Tycoon scaffolds datasets and dimensional fields, but not metrics
or relationships. OSI metrics are SQL expressions like SUM(orders.amount),
and tycoon can't reasonably guess which sums or distinct-counts you actually
want. The scaffold is a valid skeleton — you fill in the metrics that matter,
tycoon never overwrites them on re-run (sentinel pattern, see below).
| Column type | What tycoon emits |
|---|---|
INTEGER, BIGINT, DECIMAL, FLOAT, ... (numeric) |
Field with no dimension — measure-eligible base for user-defined metrics |
*_id, *_key, bare id |
Field with dimension: {} — even when numeric, these are identifiers |
DATE, TIME, TIMESTAMP[TZ] |
Field with dimension: {is_time: true} |
VARCHAR, BOOLEAN, anything else |
Field with dimension: {} |
Mart selection is prefix-based: mart_*, fct_*, dim_*, obt_*. Anything
else (staging, intermediate, ephemeral models) is skipped.
v0.1.6 stopgap. Prefix matching works for projects that follow the dbt-community naming convention but breaks for projects with custom prefixes (e.g.
published_*instead ofmart_*). v0.1.7 swaps this for a layer-aware lookup driven by the dbt manifest + atycoon.ymloverride block — see #30 for the design discussion. Thetycoon semanticsCLI shape doesn't change; only the internal mart-discovery path does.
scaffold¶
Reads marts from your warehouse DuckDB, writes
<dbt_project_dir>/semantic/osi.yaml. The default location is
project-level (one file with all datasets) — downstream consumers
expect a single OSI document.
Sentinel + --force¶
The first line of the generated file is:
On re-run, tycoon checks for this line. If it's still there, the file
is regenerated (any hand edits below are lost — you're meant to keep
them in metrics/relationships, see below). If you removed the line,
tycoon skips the file with a warning. --force overrides the sentinel
check.
What re-runs preserve¶
Nothing inside the YAML body is preserved across re-runs. The whole
file is rewritten from the warehouse. If you've added metrics or
relationships you want to keep, remove the sentinel line — that
opts you out of regeneration permanently. Or --force to overwrite
on a one-off basis.
A future enhancement (issue #28 follow-up) may add per-section preservation. For v0.1.6, the rule is simple: sentinel = regenerable, no sentinel = yours.
Options¶
| Flag | Default | Notes |
|---|---|---|
--out / -o |
<dbt_project_dir>/semantic/osi.yaml |
Override the output path. |
--force / -f |
false |
Overwrite a file whose sentinel was removed. |
Example output¶
─── OSI semantic-layer scaffold ───
✓ Wrote /Users/me/proj/dbt_project/semantic/osi.yaml — 3 dataset(s):
dim_customer, fct_orders, mart_revenue
ℹ Next: edit `metrics:` and `relationships:` by hand, then
tycoon semantics doctor to validate.
doctor¶
Validates an OSI YAML against the vendored OSI v0.1.1 JSON Schema. Exits 0 on schema-valid, 1 on any validation error.
The schema is bundled with tycoon — no network access needed.
Example¶
─── OSI semantic-layer doctor ───
✗ /Users/me/proj/dbt_project/semantic/osi.yaml has 2 validation error(s):
• semantic_model/0/datasets/0/fields/2/dimension: Additional
properties are not allowed ('is_categorical' was unexpected)
• semantic_model/0/metrics/0/expression: 'dialects' is a required
property
Integration with tycoon doctor¶
The top-level tycoon doctor command also runs the OSI check, but
non-fatally — it reports validation failures without exiting non-zero,
so the rest of the environment audit still surfaces.
Use tycoon semantics doctor when you need a hard exit code (e.g. in
CI) or when you're iterating on the OSI file specifically.
Auto-trigger after dbt build¶
Set this in tycoon.yml:
Then tycoon data transform run and tycoon data transform build
will re-emit the OSI file after a successful dbt run. Default is
false for v0.1.6 — opt in once you've validated the Conservative
scaffold matches your project conventions. Auto-invocation is
best-effort: failures never bubble into the dbt command's success
path.
What's next (deferred)¶
- Path C — Rill
metrics_viewsfrom OSI. Deferred until Rill joins the OSI consortium. tycoon semantics push <consumer>— possible v0.1.7+ surface for shipping the OSI file directly to Snowflake Cortex / ThoughtSpot / RelationalAI registries.