Migrate from a homegrown YAML setup

Plenty of teams already describe their pipeline in YAML — a bespoke schema someone wrote, sources and tables and a few conventions that grew over time. Adopting Kirimana is not a rewrite of that. It is a translation onto a standard — ODCS v3 contracts — done in stages, so you keep running the whole way through and never take a big-bang cutover. This page covers the three moves: map what you have, scaffold from the live system, and adopt incrementally.

Why ODCS v3, and what changes

Your homegrown YAML almost certainly encodes the same concepts a contract does — a table, its columns and types, an owner, a domain, maybe a freshness expectation. What it lacks is a shared vocabulary and a validator. Moving to ODCS v3 gives you both: a contract shape other tools understand, and kiri checks that hold the shape honest. The kiri.* namespaces (kiri.sla, kiri.pii, kiri.lineage, and the rest) are where your bespoke extensions land, so nothing you already express is lost — it gets a typed home instead of a convention.

Step 1 — Map the exercise

Before generating anything, do a mapping pass on paper. For each concept in your YAML, find its ODCS equivalent:

Your homegrown YAML	ODCS v3 contract
A table definition	A contract with its schema block
Column name, type, nullability	Contract properties
Owner / team	Contract owner
Domain or subject-area tag	Contract domain
A freshness or quality rule	kiri.sla.freshness / kiri.sla.quality_threshold
A PII or sensitivity marker	kiri.pii / classification

The point of the mapping is to surface the handful of concepts that don’t map cleanly — those are where you’ll spend your review time, and it’s far cheaper to find them on paper than mid-generation.

Step 2 — Scaffold from the live warehouse

You do not hand-transcribe your YAML into contracts. Instead, you introspect the live system and let Kirimana scaffold a governed starting point, then reconcile that scaffold against what your homegrown YAML claims.

kiri discover reads a live warehouse read-only and emits a scaffold with heuristic medallion-layer and classification suggestions:

kiri discover --output scaffold

Useful knobs: --schemas scans only named schemas; --max-tables runs a smoke pass over a subset; --layout layer --domain sales emits per-(domain, layer) manifests. Row data never leaves your perimeter unless you explicitly opt in with the sample-egress flags, and PII-suspect columns are excluded from any sample. AI-augmented descriptions are off by default and require a hard spend cap when enabled.

For a source system reached over a database connection, kiri migrate analyze introspects it into sources/*.yml, reading only the system catalog. Low-confidence classifications carry a # REVIEW: flag so nothing is silently trusted:

kiri migrate analyze --output sources/legacy.yml

Now you have two artifacts describing the same reality: the scaffold Kirimana derived from the live system, and your homegrown YAML. Diff them. Where they agree, you’re done; where they disagree, one of the two is wrong — often the homegrown YAML has drifted from the warehouse, and the scaffold is the truer picture.

Step 3 — Adopt incrementally: lint first, apply later

Do not point kiri apply at production on day one. Adopt in two phases.

Phase one — lint only. Bring the scaffolded contracts into a repo and run validation without applying anything. Contract validation and the layer-policy checks (kiri migrate lint-models for generated dbt models) tell you where the contracts are malformed, where a raw secret sits in YAML that should be a ${vault:…} ref, and where the medallion layering is inconsistent — all without touching the workspace. Iterate here until the project is clean. This phase is pure gain and zero risk: you are learning what a governed version of your pipeline looks like while the old one keeps running untouched.

Phase two — apply, one domain at a time. Once contracts lint clean, start materialising — but scope it. kiri release plan and kiri release apply both take --domain, so you can promote one information domain into a dev or test environment, verify it, and leave the rest of the estate on the old path until you’re ready. kiri release plan --to dev shows the exact diff before anything changes; treat it as the contract for the apply.

Because promotion is keyed on a git SHA and scoped by domain, you migrate at whatever pace the team can absorb — a domain a week if that’s what review capacity allows — with every step planned, applied, and audited the same way. There is no point at which you must have the whole homegrown pipeline converted to keep going.

Kirimana is in private beta at v1.0.0-beta.1; the discover, analyze, lint, and release verbs above are the supported adoption path today.