Skip to content

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.

tycoon semantics --help

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 of mart_*). v0.1.7 swaps this for a layer-aware lookup driven by the dbt manifest + a tycoon.yml override block — see #30 for the design discussion. The tycoon semantics CLI shape doesn't change; only the internal mart-discovery path does.

scaffold

tycoon semantics scaffold [--out PATH] [--force]

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:

# @generated by tycoon semantics — remove this line to opt out of regeneration

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

tycoon semantics doctor [--path PATH]

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:

transform:
  auto_osi_scaffold: true

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_views from 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.