The Ultimate Guide to the Medallion Data Architecture

June 2026

A practical guide to the medallion data architecture: what bronze, silver, and gold should really mean, how the layers behave under batch and CDC, and how to keep the pattern useful instead of ceremonial.

Start Here: What the Medallion Data Architecture Actually Is

Medallion architecture is a way of organizing analytical data into layered contracts, usually called bronze, silver, and gold. The important idea is not the color names. It is that each layer has a different job, a different tolerance for mess, and a different promise to downstream users.

The simplest version is this: bronze preserves source truth, silver makes the data reusable, and gold publishes business-facing outputs. That pattern can live in a lakehouse, a warehouse, or a hybrid setup. It is not tied to one vendor, and it is not only about storage layout. It is about keeping ingestion, conformance, and published semantics from collapsing into one hard-to-reason-about layer.

A concrete example looks like this. Raw PostgreSQL orders, Stripe invoices, and product events land first with enough fidelity to replay or debug them later. Silver models then standardize keys, timestamps, identities, and entity definitions across those sources. Gold marts finally answer questions such as daily booked revenue, active accounts, or product adoption by plan. Each layer does useful work, but each one also deliberately stops short of the next contract.

The mistake is to hear "bronze, silver, gold" and think you already understand the pattern. Lots of teams can name the layers. Fewer can explain what logic belongs in each one, how history is preserved, how CDC changes the design, or how downstream teams know whether a gold table is safe to trust. This guide is about those harder questions.

• Medallion is strongest when many sources feed shared analytics or AI-facing datasets and the team needs clear boundaries between raw fidelity, reusable entities, and published outputs.
• Medallion is not just three schemas; without clear contracts, the colors become decorative rather than useful.
• Medallion is compatible with warehouses and lakehouses; the pattern is architectural, not vendor-specific.
• Medallion is not mandatory; for small, static, or single-purpose workloads, a simpler layout may be the better design.

What Problem Medallion Is Trying to Solve

Medallion architecture exists because analytical systems become chaotic quickly when every concern lands in the same place. Raw source quirks, cleanup rules, cross-source joins, business definitions, and dashboard-specific calculations all start fighting for space in one layer. The result is familiar: duplicated logic, unclear ownership, and no safe place to recover from upstream mistakes.

ProblemMedallion responseWhy it helpsUpstream systems change shapeKeep a raw bronze boundarySchema evolution and replay stay visible instead of being buried inside business logicMany downstream consumers need the same cleaned entitiesCentralize conformance in silverKeys, types, and shared definitions stop being copied into every dashboard or martMetrics need stable published interfacesPublish curated gold martsBusiness users consume clearer contracts instead of reverse-engineering raw and staging logicThe stack needs to evolve without breaking trustSeparate technical layers from consumer-facing layersTeams can repair or redesign lower layers without rewriting every downstream artifact immediately

That does not mean medallion removes complexity. It relocates complexity into clearer boundaries. You still have to decide grain, history, ownership, tests, and performance. The advantage is that those decisions become more legible because each layer is allowed to do fewer kinds of work.

Medallion Is a Contract System, Not a Folder Structure

One of the most useful shifts is to stop thinking of bronze, silver, and gold as places and start thinking of them as contracts. A layer becomes real only when you can answer four questions about it: what belongs there, what must not happen there, who owns it, and who is allowed to depend on it.

LayerPrimary contractWhat should not dominate the layerBronzePreserve source fidelity, replayability, and low-level lineageBusiness metrics, cross-domain truth, or consumer-specific semanticsSilverCreate stable, reusable, conformed entities and technical cleanup logicExecutive KPI packaging or dashboard-specific shortcutsGoldPublish business-facing marts and stable analytical interfacesRaw source quirks, unreviewed cleanup rules, or hidden technical surprises

This framing matters because teams often build three schemas and still have no medallion architecture. Bronze is full of business logic, silver is a dumping ground for every half-finished join, and gold is just whichever table a dashboard author happened to prefer. The names exist, but the contracts do not.

Useful contracts also make review easier. When a change lands in silver, reviewers can ask whether it improves conformance or just sneaks a metric definition into the wrong place. When a change lands in gold, reviewers can ask whether it is actually publishing a stable consumer interface or just repackaging staging logic under a friendlier name.

The Bronze Contract: Fidelity, Metadata, and Replay

Bronze is the layer most teams underestimate. They either treat it as a junk drawer or try to make it analytics-ready too early. Both are mistakes.

A good bronze layer preserves the source shape closely enough that engineers can explain what arrived, when it arrived, and how to reprocess it if something goes wrong. In Skippr's public model, bronze is where raw extracted data lands after the discover and sync steps. That already tells you something important: bronze belongs to the ingestion contract first.

• Preserve source fidelity: keep fields, keys, and source structure legible enough that later layers can reason from them.
• Keep technical metadata: load timestamps, source identifiers, checkpoint context, and similar technical facts make debugging and recovery possible.
• Respect source evolution: additive changes and nested structure should be preserved or surfaced explicitly rather than flattened blindly into confusion.
• Avoid premature business logic: bronze should not decide churn, revenue, attribution, or customer health.

A concrete bronze anti-pattern is a raw orders landing table that already filters out cancelled orders, converts currencies into one corporate reporting standard, and joins customer plan names into every row. That may look convenient for one dashboard, but it destroys the layer's value as a faithful recovery surface.

CDC adds nuance here. In some systems, bronze holds append-only mutation history. In others, teams keep raw landed state plus a technical final-state table used before silver conformance begins. The key is not one universal storage shape. The key is that bronze and any adjacent technical apply surfaces remain technical contracts, not consumer-ready business outputs.

The Silver Contract: Conformance, Entities, and Reusable Truth

Silver is where the medallion pattern either becomes useful or collapses into a bigger bronze. Its job is to make the data reusable.

This usually means standardizing names and types, normalizing timestamps and timezones, deduplicating entities, reconciling keys across sources, and creating domain-level tables that multiple gold marts can safely build on. In other words, silver is where you stop asking "what did the source emit?" and start asking "what stable technical entity should the rest of the stack depend on?"

• Conform keys and identities: customer IDs, account IDs, and product references need stable rules across sources.
• Normalize time and types: currency, timestamps, booleans, enums, and null handling should stop surprising downstream models.
• Deduplicate and reconcile: silver is a strong home for entity cleanup and source stitching that several marts will reuse.
• Test aggressively: uniqueness, relationships, accepted values, and domain assumptions should usually surface here before they reach gold.

Use a simple example. Bronze may contain raw PostgreSQL customers, Stripe billing records, and product events with different timestamps and identifiers. Silver can define one conformed dim_account and one cleaned fct_subscription_event with agreed keys and time logic. Gold should not have to rediscover those rules from scratch for every metric.

Silver becomes dangerous when it absorbs too much business interpretation. If the only way to understand whether a table belongs in silver is to know the CFO's current reporting preferences, the layer has probably drifted too far toward gold.

The Gold Contract: Published Interfaces, Not Just Pretty Tables

Gold is where the medallion architecture becomes visible to the business. That visibility is exactly why gold needs the strictest interface discipline.

A gold model should answer a recognizable business question or publish a stable domain interface: daily revenue, active subscriptions, account health, pipeline conversion, or cohort retention. The table name, grain, columns, tests, and change path should all make sense to someone downstream who does not want to reverse-engineer bronze or silver.

Gold qualityWhy it mattersClear grainConsumers need to know whether a row is a customer, an invoice, a day, or a cohortStable definitionsPublished marts lose trust quickly if metric meaning changes casuallyVersioned change pathBreaking changes need ownership and communication, not surprise diffsPerformance awarenessGold is where predictable query patterns justify stronger materialization and tuning choices

A healthy gold layer is not "whatever analysts query most." It is the part of the warehouse or lakehouse where the team is willing to say, "yes, other people should rely on this." That makes gold less about cosmetics and more about publication discipline.

Current State, History, and Deletes Across the Layers

One of the hardest medallion design questions is where current state ends and where history begins. The colors alone do not answer that.

Bronze often holds raw history because it preserves what arrived and when. Silver may define current-state entities, historized dimensions, or event-like canonical facts depending on the use case. Gold usually publishes the business-facing interpretation of those choices, such as current ARR by account, retention cohorts by signup month, or revenue recognized by day.

Deletes and corrections make this real quickly. If an order is updated, refunded, then deleted, the architecture needs a clean answer for which layer preserves the mutation trail, which layer publishes the latest entity state, and which layer exposes the business-facing metric consequence.

Use one concrete path. A Stripe invoice is first created, then marked paid, then refunded two days later. Bronze should preserve the raw landed invoice records or raw mutation trail plus the technical metadata that explains when each version arrived. If the pipeline uses a supported CDC source and destination pair, a technical final-state apply layer may also maintain the current invoice state before silver begins. Silver can then publish a conformed billing fact that knows this invoice was paid and later refunded. Gold can finally decide what that means for daily booked revenue, net revenue, or refund-rate reporting. Each layer answers a different question, and the confusion starts when one layer tries to answer all of them at once.

• Bronze is a strong place for raw arrival truth: append-only events, raw loaded rows, or replay-safe technical state.
• Silver is a strong place for modeled history and current state: SCD-style dimensions, cleaned event facts, or conformed entity tables.
• Gold should publish the business interpretation: stable outputs for dashboards, planning, and decision-making.
• Do not let history handling stay implicit: a medallion stack without an explicit history story eventually creates contradictory marts.

A good design question is simple: if a user asks "what was true on March 1?" and "what is true now?" can the architecture answer both without awkward hacks? If not, the layers probably exist in name only.

How Batch, Incremental, and CDC Behave Inside a Medallion System

Medallion architecture does not force one ingestion pattern. It has to work with the load behavior the source actually needs.

Load patternHow it usually lands in medallionMain design pressureBatch snapshotBronze keeps current-state extracts or batch slices; silver decides how to normalize and preserve comparison logicGrowing rerun cost and weak delete visibilityIncremental syncBronze lands new or changed data based on tracked progress; silver absorbs late-arriving or corrected rows deliberatelyWatermark quality, late data, and backfill rulesCDCBronze and adjacent technical apply layers preserve mutation truth, and on supported source/destination pairs can also maintain correct final-state tables before silver and gold model on topOrdering, deletes, replay safety, and deciding which layer owns which state representation

This is one place where medallion can get sloppy. Teams say "bronze is raw" and stop there, even though a CDC-backed system also needs a view on correct final state before most silver models make sense. Or they say "silver is cleaned" without deciding whether cleaned means current-state conformance, historized conformance, or both.

The useful rule is to keep the responsibilities explicit. Bronze and any technical apply layers should preserve low-level truth and replay logic. Silver should publish reusable conformed entities. Gold should publish business-facing contracts. The exact storage layout can vary, but the responsibility boundaries should not stay vague.

A practical test is to trace one changed row. If a PostgreSQL subscription record flips from active to cancelled, bronze should still let engineers see the raw landed change and its technical metadata. On a supported CDC path, the technical apply layer can produce the correct latest-state subscription row. Silver can then update one conformed subscription entity with stable account and plan keys. Gold can decide whether that change affects churn, end-of-month active subscriptions, or some other business-facing metric. That sequence is more useful than asking the bronze table to be both the replay surface and the final reporting interface.

A Worked Example: PostgreSQL, Stripe, and Product Events to Snowflake

Use one realistic example to make the architecture less abstract. Imagine a B2B SaaS company with:

• PostgreSQL for accounts, subscriptions, and app-generated orders.
• Stripe exports or landed billing data for invoices, payments, and refunds.
• Product events arriving through a stream or file path.
• Snowflake as the analytical destination.
• dbt for staged and business-facing models.

A healthy medallion layout might look like this:

LayerExample relationsWhy they live thereBronzeRAW.postgres_orders, RAW.stripe_invoices, RAW.product_eventsSource-shaped landed data plus technical metadata for replay, freshness, and debuggingSilversaas_silver.stg_orders, saas_silver.dim_account, saas_silver.fct_subscription_eventsConformed account identity, cleaned timestamps, normalized statuses, and reusable event factsGoldsaas_gold.daily_revenue, saas_gold.account_health, saas_gold.retention_cohortsPublished business-facing marts with stable grain and definitions

A useful test of the architecture is whether a new dashboard should start from gold, whether a new reusable domain model should start from silver, and whether a source discrepancy investigation should start from bronze. If the answer is "it depends, check six places," the layering is not doing enough work yet.

This is also where medallion shows its practical value. A refund logic change may require reworking a silver billing model and a few gold marts, but it should not require rethinking how raw invoices landed or forcing every dashboard author to reinvent billing semantics independently.

Testing, Ownership, and Change Management by Layer

Medallion works best when each layer has a different testing and ownership posture.

LayerTypical testsTypical owner concernBronzeFreshness, load completeness, schema evolution visibility, basic row-shape sanityDid the source land correctly and can we recover if it did not?SilverUniqueness, relationships, accepted values, conformance rules, domain-level invariantsAre reusable entities technically correct and stable enough for several marts?GoldBusiness assertions, metric checks, interface stability, SLA-sensitive row and value validationCan downstream consumers trust this published output?

Ownership should mirror that. Bronze is often owned by the ingestion or platform side. Silver tends to sit with analytics engineering or the shared modeling layer. Gold often needs explicit domain ownership because published metrics and marts are social contracts as much as technical ones.

That also means breaking changes should get stricter as you move upward. A bronze schema addition may be acceptable with good visibility. A silver key change needs careful review. A gold grain change probably needs communication, versioning, or both.

Performance and Cost Discipline in Medallion Systems

Medallion architecture helps organize logic, but it does not automatically control cost. In fact, a poorly run medallion stack can duplicate data and compute across several layers while still producing unclear outputs.

• Do not duplicate wide logic mindlessly: silver should be reusable, but it should not become ten near-identical copies of the same cleaned table for different teams.
• Materialize where the contract justifies it: predictable gold query patterns often deserve stronger materialization and tuning than transient cleanup steps.
• Retain raw data deliberately: bronze is valuable, but retention, partitioning, and replay policies still need discipline.
• Watch full refresh behavior: if silver and gold rebuilds touch giant facts casually, the architecture becomes expensive noise.
• Treat performance as layer-specific: bronze optimizes for fidelity, silver for reusable correctness, and gold for stable consumer-facing access.

A useful anti-pattern to avoid is "gold as a performance cache for broken silver." If every dashboard needs its own bespoke gold table because silver is unreliable or confusing, the architecture is compensating for upstream weakness instead of expressing a strong contract.

When Medallion Is the Wrong Pattern

Medallion architecture is useful, but it is not a law of nature.

• Very small, stable workloads: if one source feeds one report and the definitions rarely change, three explicit layers may be more ceremony than value.
• Single-purpose analytical jobs: some pipelines only need one well-defined transformed table and do not benefit from a full layered contract system.
• Teams without ownership discipline: if nobody will maintain the contracts, the layers become labels on chaos.
• Pre-load transformation requirements: if data must be heavily transformed or masked before it can land, a warehouse-first medallion story may not be the right core pattern.
• Over-eager abstraction: if the team builds bronze, silver, and gold for every tiny source regardless of need, the architecture can slow down useful delivery.

The right question is not "should every modern stack use medallion?" It is "does this workload benefit from separating raw fidelity, reusable conformance, and published outputs clearly enough to justify the extra structure?"

Common Medallion Failure Patterns

Most medallion failures are recognizable.

• Bronze with business logic: raw landing is already filtered and interpreted, so recovery and trust both suffer.
• Silver as a dumping ground: every join, metric, and half-finished cleanup lands there until the layer becomes impossible to reason about.
• Gold built directly on bronze: teams skip conformance under deadline pressure and then wonder why business definitions drift.
• No history strategy: current state, event history, and deletion handling are never made explicit, so marts contradict each other over time.
• Too many unofficial gold tables: every analyst publishes their own "final" output and the architecture loses its contract value.
• Color names without ownership: the schemas exist, but nobody can explain which changes require review, who signs off, or which marts are safe for broad reuse.

The common thread is simple: the pattern is adopted as a naming scheme instead of as an operating model.

How Skippr Fits a Practical Medallion Stack

Skippr fits best when the goal is not to talk about bronze, silver, and gold abstractly, but to stand up the first useful version of that architecture with visible phases and ordinary artifacts. The documented path is explicit: discover the source shape, sync raw data into bronze, model a dbt project for silver and gold, and validate the result against the destination.

• Documented bronze, silver, gold structure: the public docs define bronze as raw extracted data, silver as cleaned and typed staging models, and gold as business-ready marts in separate schemas.
• Deterministic lower-layer responsibilities: schema discovery, type reconciliation, incremental checkpoints, and CDC reconciliation logic for supported source and destination pairs stay outside model guesswork.
• Generated dbt project for upper layers: source definitions, staging models, and project files are written as standard dbt assets you can inspect and extend.
• Clear data boundary: your data stays within your system and in your destination while the cloud path handles authentication and control-plane services.
• Reviewable architecture bootstrap: the early medallion path is narrower because raw landing and model scaffolding do not require stitching together several separate products first.

That is useful because medallion projects often stall at the transition point between "we landed raw data" and "we have a reviewed silver and gold structure that people can build on." Skippr is strongest in that gap: establishing the first visible layer contracts and giving the team ordinary artifacts to refine instead of a black box to trust.

For related reading, pair this guide with The Ultimate Guide to Data Ingestion, The Ultimate Guide to ELT, The Ultimate Guide to Data Modeling, The Ultimate Guide to dbt, the shorter Medallion Architecture Guide, and the Core Concepts docs.

Your Practical Medallion Checklist

If you want one section to keep open while designing the pattern, use this one.

• Define bronze, silver, and gold as contracts with explicit allowed work, not just as folder names.
• Keep bronze technically honest: source fidelity, metadata, replay value, and no premature business interpretation.
• Make silver the home of reusable conformance, not the accidental home of every final metric.
• Treat gold as a published interface with clear grain, stable meaning, and change discipline.
• Decide where current state, event history, and deletes are represented before the first important mart is built.
• Match the layer design to the load pattern: batch, incremental, and CDC do not stress medallion in the same way.
• Use tests and ownership rules that get stricter as you move upward toward consumer-facing contracts.
• Choose medallion where the structure buys clarity, not because the color names feel modern.

That sequence reflects how strong medallion systems actually get built. First make the contracts clear. Then land one useful path. Then harden the layer boundaries before the architecture spreads across the business.