Choose your silver modeling technique

Before you scaffold a single silver contract, Kirimana makes you pick how the silver layer is shaped. There are three techniques, and the choice is deliberately front-loaded: kiri init refuses to guess it, because it is expensive to change once silver contracts exist.

• flat — cleaned, deduplicated, typed tables that stay close to the source shape. One silver table per meaningful source entity, no historization unless you ask for it. The lowest-ceremony option.
• data_vault — Data Vault 2.0: hubs (business keys), links (relationships), and satellites (descriptive attributes, SCD2 by hashdiff), plus optional PIT and bridge query-acceleration tables. Insert-only, auditable, built for many sources feeding one entity.
• kimball_dimensional — conformed dimensions and facts already at silver: SCD1/SCD2 dimensions with surrogate keys, transaction and aggregate facts, degenerate dimensions. Silver is already shaped for analytics.

The decision, in one command

You choose at bootstrap and it is required:

kiri init acme-dw --silver-technique data_vault --adapter databricks

--silver-technique accepts exactly flat, data_vault, or kimball_dimensional. kiri init is fail-closed here on purpose: it will not default the technique for you, because switching later means migrating every silver contract you have already written.

The choice lands in kiri.yml:

silver:
  technique: data_vault

When to pick which

There is no universally correct answer — the right technique depends on how many sources feed each entity, how much auditability you owe, and how much modelling your team wants to carry at silver.

Pick flat when a source is already close to the shape you want, one system owns each entity, and you don’t need full history at silver. It is the fastest path from bronze to a usable, governed table. History is still available per-contract via SCD2 when a specific table needs it; you just don’t pay for it everywhere.

Pick data_vault when many sources feed the same business entity, when you need an insert-only, fully auditable record of what arrived and when, or when relationships between entities change often and you want to absorb that without rewrites. Hubs isolate the business key, links isolate relationships, and satellites isolate attributes — so a new source or a changed attribute is an additive load, not a schema migration. It carries the most structure and pays back in change resilience.

Pick kimball_dimensional when your team already thinks in stars and you want conformed dimensions and facts as early as silver, rather than modelling them only at gold. Silver dimensions carry SCD type, business keys, and a surrogate-key strategy directly.

If you’re genuinely unsure, flat is the reversible default in spirit — the least structure to walk back. But make the call consciously: the CLI wants you to.

The lock, and why it exists

The technique is locked after your first silver contract. Until a silver-state contract exists, changing silver.technique in kiri.yml is just an edit. Once one exists, the technique is load-bearing: lint rules, the referential-integrity model, hash-key computation, and the graph plan all key off it. Changing it then is a migration, not a config tweak — so Kirimana treats the first silver contract as the point of no easy return, and expects you to have chosen on purpose at kiri init.

Preview what the locked technique implies before you commit work to it:

kiri silver plan

This prints the resolved silver technique plus the plan for what a silver apply would build under it — no destructive action.

Technique-specific lints

Each technique brings its own governance rules, and kiri contract lint runs the set that matches your project:

• Data Vault adds referential-integrity checks — a satellite must point at a real parent hub or link, a link must carry the declared business keys on both sides, and a raw-vault satellite must not embed business rules. Foreign-key structural checks (FK-001…FK-004) run via kiri fk gate; the dangling-parent and self-cycle checks are hard fails that cannot be suppressed. Data Vault also has a dedicated silver-quality catalogue (kiri dv quality list / run) with gateable check IDs.
• Flat and Kimball run the technique-neutral relationship gate (kiri.relationships.foreign_keys) plus, for Kimball, the dimension/fact shape rules — a dimension needs a SCD type, business keys, and a surrogate-key strategy; a fact needs a grain and measures with declared additivity.

The referential model itself (kiri.relationships.*) is technique-neutral and validated for any silver technique, so a declared foreign key means the same thing whether the layer underneath it is flat, Kimball, or Data Vault.

All three feed the same gold

Whatever you choose at silver, gold is always a Kimball star schema. Facts and SCD Type 2 dimensions, surrogate keys, conformed dimensions across marts — that shape is the same for a flat, Kimball, or Data Vault silver layer. The technique decides how silver absorbs and audits change; it does not fork your analytics surface.

Kirimana even normalises the gold surrogate-key strategy to your silver technique by default: Data Vault dimensions hash, Kimball dimensions sequence, flat dimensions hash. You can override per dimension, but the sensible default follows the technique you picked here.

So the decision is real but bounded: it governs the middle of your warehouse, and it leaves the two ends — the ODCS contract format at the top and the Kimball gold star at the bottom — identical across all three techniques. Choose for how your sources and history behave, not for what your dashboards will look like.

Where next

• Model a silver contract — real YAML shapes for all three techniques.
• Model gold — facts and dimensions — the star schema every technique lands in.