Sheet 01 / Semantic model scaffold / Apache Ossie (incubating)
Every tool in a company holds its own private idea of what “revenue” means. This kit sets up one place to write the real definition down — in an open format that dashboards, spreadsheets and AI assistants can all read — and one command creates it.
$ git clone https://github.com/cskwork/ossie-domain-kit $ ./ossie-domain-kit/bootstrap-ossie-domain.sh retail ~/git/retail-ossie $ cd ~/git/retail-ossie && make validate ######## models/retail/retail_example_model.yaml Validation PASSED — all models PASSED
01
In plain terms
Monday morning. Someone asks a simple question — how much did we sell last month? — and gets three numbers back.
A written-down dictionary of the business: what counts as a customer, what counts as revenue, which orders don't count at all. Plain text files, kept in version control, that every tool reads instead of each one guessing.
An open standard for writing that dictionary down, so it belongs to you rather than to whichever BI vendor you happened to buy. Previously called OSI, Open Semantic Interchange; now a project at the Apache Software Foundation.
Standards do not maintain themselves. This kit creates the repository — the folder layout, the automated checks, the rules — so that a team can start one in a minute and still trust it a year later.
The reason this got urgent: AI assistants now write the query for you. Given a definition, they use it. Given none, they invent one — and present the result with exactly the same confidence.
— why a semantic layer stopped being a nice-to-have
02
The premise
apache/ossie is where the specification is developed — a Go CLI, converters, a Python package, ASF release machinery. A repo that merely uses Ossie to describe one domain wants almost none of it, and a fork makes it awkward to track upstream while carrying your own models.
examples/, tangled with upstream's ownschema/SOURCE.md and NOTICE03
Output
A working repository, not a folder of TODOs. The example model validates on the first run, so a green build is the starting state rather than the goal.
retail-ossie/ ├── models/retail/ │ └── retail_example_model.yaml ← passing starter, replace it ├── schema/ │ ├── osi-schema.json ← vendored from core-spec/ │ └── SOURCE.md ← upstream ref + commit SHA ├── core-spec → schema/ ← validator compatibility link ├── scripts/validate.py ← vendored from validation/ ├── docs/ │ ├── overview.md ← catalogue · conventions · decisions │ └── verification.md ← proving models match real schemas ├── .claude/skills/ossie-domain-model ├── .github/workflows/validate.yml ├── AGENTS.md ← rules for coding agents ├── Makefile ← validate · verify · check └── README.md · LICENSE · NOTICE + git init, first commit
The bootstrap resolves the upstream commit SHA and writes it into the generated repo. Six months later you can still say exactly which revision of the spec a model was written against — and what changed when you bump it.
constThe schema pins version to one literal string, read out of the
fetched schema rather than hardcoded. A spec bump breaks every model at once.
That is the intended signal, not a bug.
The upstream validator takes one file per run and resolves its schema at
../core-spec/. Bootstrap creates a core-spec → schema/
compatibility link, while the generated Makefile loops per file.
04
Two questions
A model can satisfy the schema perfectly and still describe a column that does not exist. That is worse than having no model: an agent will confidently write SQL against the fiction. So the Makefile keeps two questions apart.
make validate — spec complianceFour passes over every model:
make verify — reality
Do these tables and columns actually exist, with these types? This one cannot be
generic — it depends on whether your source of truth is a DDL dump,
information_schema, a dbt manifest or an ERD export. It ships as a
loud no-op, never a silent pass, and docs/verification.md
walks through each case.
Every model then carries an honest grade in the catalogue:
Never invent a column. If you cannot find it in an artefact, leave it out and say so — a plausible-looking wrong column is the single most damaging thing you can add here.
— AGENTS.md, rule 1, shipped in every generated repo
05
Agent-ready
Semantic models are exactly the work people now hand to coding agents — and exactly the work where a confident guess does lasting damage. So the guardrails ship with the repo.
Six hard rules, the authoring loop, the full model shape, and a symptom → cause table for the errors the validator actually emits. Read by Claude Code, Codex and anything else that honours the convention.
An authoring skill: bootstrap or extend a repo, draft against the spec, validate, and review someone else's model. Two references — a spec cheat sheet and a guide to gathering evidence from DDL, dbt, ORM entities and SQL mappers.
information_schema over a DDL dump, over a dbt manifest,
over an ERD, over ORM entities, over SQL mappers. Anything below rank four yields an
inferred model — and the catalogue has to say so.
06
Usage
./bootstrap-ossie-domain.sh <domain> [target] — fetch, pin, stamp,
git init. Nothing is ever pushed; the remote is your call.
Read the source of truth, replace the example, record where each definition came
from in the file header. make validate until it passes.
Wire make verify to your warehouse, dump or manifest — then grade
each model honestly in docs/overview.md.
| Flag | Effect |
|---|---|
<domain> | Domain slug, lowercase [a-z0-9-]. Names the model folder and the starter file. |
[target-dir] | Where to create the repo. Defaults to ./<domain>-ossie. Refuses a non-empty directory. |
--from-clone DIR | Vendor from a local apache/ossie clone at the requested ref — offline, without switching its checkout. |
--ref REF | Upstream branch, tag or SHA to pull from. Defaults to osi-0.1.1-rc1 (0.1.1 RC). |
--no-git | Skip git init and the initial commit. |
--no-skill | Do not install the authoring skill into .claude/skills/. |
07 / Start
Agents, dashboards and analysts should all answer “what is net revenue?” the same way. Give that answer somewhere to live.