The core idea
Medallion Architecture is often explained with a simple diagram: data moves from Bronze to Silver to Gold, becoming cleaner and more useful at each step.
That explanation is directionally correct, but it leaves out the part that matters most in real systems: what responsibility belongs in each layer, and where should a transformation actually happen?
Without clear boundaries, Bronze becomes partially transformed, Silver becomes a mixture of staging and business logic, and Gold slowly turns into another general-purpose transformation layer. The architecture still has three names, but the separation of concerns has disappeared.
A useful Medallion Architecture is not defined by the number of schemas or folders it contains. It is defined by the responsibilities assigned to each layer.
Raw source data, ingestion metadata and traceability.
Consistency, validation, deduplication and reusable data contracts.
Purpose-built analytical models, metrics and data products.
Why Medallion Architecture exists
The purpose of the Medallion pattern is to separate different stages of data processing so that each stage has a clear contract.
Raw source data should not be mixed with cleaned data. Technical standardization should not be mixed unnecessarily with reporting-specific calculations. Business-facing datasets should not depend directly on unstable source structures.
That separation makes pipelines easier to reason about, test, troubleshoot and evolve.
Bronze preserves what arrived. Silver establishes what can be trusted. Gold publishes what the business should consume.
Bronze: preserve the source
Bronze is the landing layer. Its primary responsibility is to preserve incoming data in a form that remains close to the original source. The goal is not to make the data beautiful. The goal is to make ingestion reliable, observable and reproducible.
A Bronze table will often include the original source fields together with ingestion metadata such as load timestamp, source file, batch identifier or processing timestamp. That metadata becomes extremely valuable when something goes wrong later.
If a Silver transformation suddenly produces fewer records than expected, Bronze should make it possible to answer where a record came from, when it was ingested, which source file or extraction produced it, and whether the problem already existed at the source.
This does not mean Bronze can never perform technical operations. Parsing, extraction of ingestion metadata or minimal technical normalization may be necessary just to persist the data reliably. The important principle is that Bronze should not silently redefine the meaning of the source data.
If the source sends "00123" as a string, converting it immediately into integer 123 may appear harmless, but it can remove information that later turns out to matter. Bronze should favour traceability over convenience.
Silver: establish trustworthy data
Silver is where data becomes dependable enough to be reused across multiple downstream use cases. This is normally where the majority of data-engineering logic belongs.
Typical Silver responsibilities include type enforcement, standardization, deduplication, null handling, record alignment, schema validation, data-quality rules and integration between related datasets.
The key distinction is that Silver transformations should establish a consistent technical and business interpretation of the data, without tailoring everything to one individual dashboard or report.
Suppose three source systems represent customer identifiers differently. Bronze should preserve those representations. Silver is the appropriate place to resolve them into a consistent structure that downstream consumers can rely on.
A good Silver layer allows downstream teams to stop repeatedly solving the same cleaning problems. Instead of every report implementing its own version of "Which customer record should I use?" or "Which timestamp is valid?", those decisions are made once and represented consistently.
Gold: serve business use cases
Gold exists for consumption. The datasets here should be designed around how the organization actually uses data rather than how source systems happen to store it.
This is where reporting models, aggregates, business metrics, feature datasets and domain-specific analytical structures may live.
For example, a Silver layer may contain standardized orders, products, customers and payments. A Gold dataset might then expose daily revenue by product category, customer-level performance metrics or a reporting-ready sales model.
Gold should also avoid becoming a dumping ground for every downstream request. A useful Gold layer contains intentional, well-defined data products rather than an uncontrolled collection of tables created for individual queries.
What should not happen in each layer
Many Medallion implementations become difficult to maintain because responsibilities slowly leak between layers.
- Bronze should generally not contain complex business rules, reporting calculations or aggressive data cleaning.
- Silver should not simply copy Bronze tables without adding meaningful trust or consistency. It should also avoid becoming highly customized for individual dashboards.
- Gold should not repeatedly repair data-quality problems that should already have been resolved upstream.
One useful test is to ask: If three different downstream teams need the same transformation, should they each implement it separately?
If the answer is no, that logic probably belongs in Silver. If the transformation exists specifically to represent one analytical or business use case, Gold is usually the better place.
Where data validation belongs
Validation does not belong exclusively to one layer. Different validation questions should be asked at different stages.
Can the incoming data be accepted and traced? Are files present, payloads readable and structural changes visible?
Are identifiers present? Are types correct? Are duplicates handled? Do relationships and data-quality rules hold?
Do published metrics reconcile? Are aggregates complete? Does the dataset satisfy the consumer-facing contract?
Treating validation as a continuous responsibility across the pipeline is more effective than attaching a single "data quality" step somewhere in the middle.
Handling schema evolution
Schema evolution is one of the places where clear layer responsibilities become especially useful. Source systems change: columns appear, columns disappear, data types change and previously required fields become optional.
Bronze should make those changes visible rather than hiding them. Silver should decide how those changes affect the trusted data contract.
For example, a source may change an identifier from INT to BIGINT. Bronze may accept and preserve the incoming structure, while Silver determines whether the trusted schema should also change and whether downstream systems are affected.
This creates a controlled boundary between unstable source systems and stable consumer-facing data.
Incremental processing across the layers
Medallion Architecture does not imply that every layer must be rebuilt in full. In production systems, Bronze, Silver and Gold commonly process data incrementally.
Newly arrived files or newly extracted source records.
Changed records since the previous successful execution.
Affected partitions, aggregates or business entities.
The important part is not simply making a pipeline incremental. It is defining how changes propagate safely between layers, including keys, late-arriving data, updates, deletes, deduplication and replay.
A pipeline that is fast but cannot correctly reproduce data after a failure is not a reliable pipeline. Incremental design should preserve both efficiency and recoverability.
Common implementation mistakes
One common mistake is creating Bronze, Silver and Gold schemas and assuming the architecture is finished. The names alone provide no architectural value.
Another mistake is performing nearly identical transformations in several Gold tables because the shared logic was never established in Silver. The opposite can also happen: Silver becomes overloaded with every possible business calculation, making it difficult to reuse outside the original reporting context.
Another frequent problem is losing source traceability too early. When ingestion metadata is discarded, debugging becomes significantly harder because downstream records can no longer be connected easily to their origin.
Finally, teams sometimes optimize for the shortest possible pipeline rather than the clearest ownership of transformations. Fewer steps are not automatically better. A slightly longer pipeline with clear contracts between layers is often easier to operate than a shorter pipeline where every stage performs multiple unrelated responsibilities.
A practical decision framework
When deciding where a transformation belongs, the most useful question is not "Is this Bronze, Silver or Gold logic?" Instead, ask what responsibility the transformation represents.
Capture and preserve
If the goal is to retain incoming data and its origin, keep the logic close to Bronze.
Make it trustworthy
If the goal is consistency, validation and reuse across consumers, it belongs close to Silver.
Shape for consumption
If the goal is a specific business or analytical use case, it belongs close to Gold.
There will always be exceptions. Real platforms are more complicated than architecture diagrams. The objective is not to follow three rigid definitions; it is to create boundaries that make the system understandable.
Final takeaway
Think in data contracts, not layer names.
Bronze gives you confidence that you can trace and reproduce what arrived. Silver gives you confidence that the data has a consistent and trustworthy interpretation. Gold gives consumers data that is intentionally designed for the way they need to use it.
When those responsibilities remain clear, Medallion Architecture becomes more than a diagram. It becomes a practical engineering model for building data platforms that can evolve without becoming difficult to understand or maintain.