Medallion: One Naming Convention Among Several
Bronze, silver, gold is a widely used set of names for raw, staging and curated. It is a convention, not a requirement, and it is not an architecture.
Who needs this, what one row is, and why the obvious build breaks
Every lesson starts from the consumer, because designing from the source outward is this domain's characteristic mistake.
What does calling a layer "bronze" tell a consumer that calling it "raw" does not — and what does the medal metaphor quietly imply that is false?
An engineer joining a team and reading table names, and an analyst deciding which table to query. Both are trying to answer one question — what is this dataset for and may I rely on it — and a name can only help with that if the team agreed what the names mean and wrote it down (Dataset Documentation).
Naming conventions operate on datasets, not on rows. The grain of a bronze table is whatever the source delivers, of a silver table one row per entity, of a gold table a declared analytical grain — which is to say the grain is decided by the layer's *purpose*, and the medal name is a label attached to that purpose after the fact (Raw, Staging, Curated: Layers by Purpose).
Adopt bronze/silver/gold because it appears in the reference architecture for the platform you bought, and assign every dataset to one of the three. It gives the team a shared vocabulary on day one, which is a genuine benefit and the main reason the convention spread.
The metaphor implies a quality ladder, so people infer that gold data is more trustworthy than silver. It is not: gold is more *specific*, and a gold table built on a wrong business rule is confidently wrong at a higher polish (The Pipeline Succeeded. The Data Is Wrong.).
- The metaphor implies a quality ladder, so people infer that gold data is more trustworthy than silver. It is not: gold is more *specific*, and a gold table built on a wrong business rule is confidently wrong at a higher polish (The Pipeline Succeeded. The Data Is Wrong.).
- A dataset does not fit. A reference table that arrives clean and needs no transformation gets copied through all three layers unchanged, costing three builds and providing three identical copies (Compute Waste).
- The team spends design meetings arguing whether a dataset is silver or gold, which is an argument about a label rather than about a boundary, and it has no correct answer (Model Layering).
- Someone builds a gold table directly on bronze because it was faster, skipping the deduplication and conformance silver was supposed to guarantee. The names held; the boundary did not (Duplicate Rows).
- A fourth concern appears — an intermediate layer of shared joins — and there is no medal for it, so it goes into silver, which now contains both conformed sources and business-rule-laden intermediates.
- A consumer is told to use gold and finds a gold table that has no owner, no declared grain and no tests, because the name was applied and the contract never was (Data Contracts).
What is actually happening
- Bronze, silver and gold are names for the three jobs described in [[data-layers]] — preserve what arrived, make it structurally usable, apply meaning for consumers. The convention adds vocabulary; it does not add structure.
- The convention became widespread because a major lakehouse vendor used it in its reference material, and shared vocabulary is genuinely valuable — a new engineer who knows the convention can read a table list and form a correct first hypothesis (The Lakehouse).
- It is explicitly not required. A platform using raw/staging/curated, landing/base/marts, or source/intermediate/reporting is not missing anything. Any claim that a data platform must have bronze, silver and gold layers is a claim about naming presented as a claim about engineering, and it should be refused as such.
- The metaphor carries an implication the underlying design does not: metals rank. Raw, staging and curated name *purposes* and rank nothing. Bronze, silver and gold name a hierarchy, and people reason from hierarchies whether or not you asked them to (Trusting Data).
- Where the convention does real work is in access policy and discovery. "Consumers may query gold" is an enforceable statement if the layer is a real boundary with real grants — and it is a slogan if the boundary is a prefix on a table name (Data Access Control).
- The number three is also a convention. Some platforms need two, many need a fourth intermediate layer, and a few need per-domain variations. Forcing every dataset into exactly three buckets is the most common way the convention causes harm (Data Mesh is where per-domain variation usually starts).
The same three jobs, under five sets of names
The most useful thing to know about medallion is that it is a synonym set. Below are conventions in common use, aligned by purpose. Reading across a row shows that the disagreements between houses are lexical; reading down a column shows the three jobs that every platform performs whether or not it names them.
The fourth column is where conventions differ substantively rather than lexically. Some schemes have a name for shared intermediate models and some do not, and a scheme without one pushes those models into whichever adjacent layer is more tolerant — usually silver, which is how silver becomes the layer nobody can describe.
To say it plainly, because the field frequently does not: there is no requirement that a data platform use bronze, silver and gold. A platform with raw and curated only, well documented and properly bounded, is better engineered than one with three medals and no contracts. The convention is a communication tool and it should be evaluated as one.
| Purpose | Medallion | Warehouse-house | Transformation-tool | Lake-house | Has a name for shared intermediates? |
|---|---|---|---|---|---|
| Preserve what arrived, unmodified, for reprocessing | Bronze | Raw | Sources / raw | Landing | n/a |
| Deduplicate, cast, conform names, represent deletes | Silver | Staging | Staging | Base | No — intermediates usually land here |
| Apply business meaning, set analytical grain, define metrics | Gold | Curated | Marts | Reporting | No — sometimes split into marts |
| Materialise joins shared by several downstream models | — (no medal) | Intermediate | Intermediate | — (varies) | Yes, in the two middle columns |
| Pre-aggregate for one heavy read pattern | Gold (again) | Mart | Marts | Serving | Usually merged with the layer above |
The bronze/silver/gold vocabulary is associated with particular lakehouse vendors' reference material, and the exact wording and recommended structure in that material changes between documentation revisions. Treat the alignment above as a map of common usage rather than as any vendor's current definition, and check their documentation if you need to match it precisely.
What the metaphor makes people believe
Names are not neutral. Raw, staging and curated describe *what has been done* to a dataset. Bronze, silver and gold describe *how valuable it is*, and readers act on that difference without noticing they are doing it. The result is a specific set of recurring failures that platforms using purpose-names get less often.
The most consequential is quality inference. A consumer told "use gold" reasonably concludes that gold data is checked. Whether it is checked depends entirely on whether someone attached tests, and the name provides no evidence either way.
The second is the pass-through. If the platform has three tiers and every dataset must sit in one, a dataset that needs no transformation gets written three times to satisfy the scheme. That is a real cost paid to a metaphor, and it is worth noticing that no purpose-named scheme creates the same pressure.
| Trigger | Symptom | Cause | Response |
|---|---|---|---|
| An analyst treats a gold table as authoritative. | A number is used in a decision; it turns out no test was ever attached to that table. | Quality inferred from the layer name rather than from a contract. | Publish contract status alongside the name — owner, grain, tests, freshness — in the catalog, so the name is a location and the contract is the claim. |
| A gold model is built directly on bronze. | Duplicates appear in a metric weeks later, after a redelivery. | The layer boundary is a naming convention with no enforcement in the dependency graph. | Make gold-on-bronze a build failure. A convention that can be violated silently is documentation, not a boundary. |
| A clean reference table exists three times. | Three identical datasets, three nightly builds, no transformation between them. | The scheme requires every dataset to have a tier, so the dataset was copied to satisfy it. | Let datasets skip layers they do not need. The layer is justified by the boundary it creates, and a pass-through creates none. |
| A design meeting stalls on classification. | An hour spent deciding whether a dataset is silver or gold. | The question has no correct answer because it is about a label, not a boundary. | Replace it with two answerable questions: does anything restart from here, and which consumers depend on this shape? The medal follows from the answers. |
| Two teams cannot share a dataset. | One team's gold is the other team's silver; neither will consume the other's. | The convention was adopted independently by each team with different implied contracts. | Define the convention centrally and in writing, or accept per-team naming and rely on catalogued contracts instead. The failure mode is shared words with unshared meanings. |
Adopt it, or do not — but decide it as a naming question
The decision is genuinely open and genuinely small. It is worth ten minutes and a written definition, and it is not worth a design review. What deserves the design review is the set of boundaries underneath: what may enter each layer, who may read it, what each layer must declare, and where the build fails if the rule is broken.
The comparison below is the whole lesson in two rows. A platform can have perfect medal naming and no boundaries, or purpose-based naming and rigorous boundaries, and only one of those is well engineered. The convention is a label on the architecture; it is never the architecture.
If you are joining a platform that already has a convention, keep it. Renaming layers is a change with broad blast radius and no functional benefit, and the engineering attention is better spent on whichever gold tables have no declared grain.
What would the convention change here, concretely?
when The team's primary tooling and documentation use the vocabulary, or several teams need a shared vocabulary and none exists yet.
cost Slight friction with tools whose examples use other names, and the ongoing need to explain that the metals are not a quality ranking.
when Your transformation tool's conventions already say staging and marts, or the team reasons better about purposes than about tiers.
cost Occasional translation when reading lakehouse material or hiring people who learned the medals. Genuinely minor.
when One or two sources, few models, and no shared conformance work worth isolating.
cost A later migration if the platform grows — which is cheap while the model count is small and expensive once it is not.
when Several models share expensive joins, or serving marts have materially different contracts from the models behind them.
cost More builds, more storage, and a naming scheme that no longer maps to any reference diagram. Both are acceptable prices for real boundaries.
when One engineer, one source, a platform whose shape is still being discovered.
cost Renaming later, which is annoying and bounded. Premature convention is the more expensive mistake at this size.
Tables are prefixed by tier. Consumers are told to use gold. Several gold models select from bronze because it was quicker. Some gold tables have no owner and no tests. The three names appear in the architecture document and nowhere in the grants.
Consumers hold grants on the consumer-facing layer only. The transformation tool fails the build if a consumer-facing model references the raw layer. Every consumer-facing dataset declares a grain, an owner, a freshness expectation and known gaps, and carries at least one business test.
The properties consumers actually rely on — that duplicates were removed, that the grain is what it claims, that someone owns the definition — come from enforcement and contracts, none of which a naming convention provides. Names help people navigate; grants, dependency rules and tests are what make the navigation trustworthy.
How to build it
Most important first.
- Pick a naming convention, write down what each name promises, and enforce it with grants and dependency rules. The choice of words matters far less than the existence of the written definition.
- If you adopt medallion, define the three explicitly in your own terms — what may enter bronze, what silver guarantees, what gold must declare — rather than relying on shared intuition about metals. Two teams using the same names with different meanings is worse than two teams using different names.
- Allow a fourth layer without renaming everything. An intermediate layer of shared, materialised joins is a normal need and does not have a medal, which is a limitation of the convention rather than a signal that the layer is wrong.
- Enforce the boundary in the dependency graph: a gold model may reference silver, not bronze. A tool that models dependencies can make this a build error rather than a code-review comment (The Transformation DAG).
- Never let the layer name substitute for a contract. Every gold dataset needs a declared grain, an owner, a freshness expectation and a list of known gaps, exactly as it would if the layer were called anything else (Data Ownership).
- Resist arguments about which medal a dataset belongs to by converting them into arguments about boundaries: what restarts from here, and which consumers depend on this shape? Those questions have answers.
What this actually promises
Naming the guarantee you do not have is worth more than naming the one you do — everything downstream inherits the weakest promise in the chain.
- The names guarantee nothing on their own. A table prefixed
gold_has exactly the properties its transformation gave it and whatever tests were attached to it (Data Tests). - Where the convention is enforced by grants and dependency rules, it guarantees a real boundary: consumers cannot read bronze, and gold models cannot reference it. That guarantee comes from the enforcement, not from the naming.
- Bronze guarantees fidelity to delivery and nothing about completeness, exactly as raw does (Keeping Raw History: The Recovery Position and the Liability).
- Gold guarantees only what its contract declares. Absent a declared grain, a gold table guarantees less than a well-documented staging model (Grain: What Does One Row Represent?).
Can I trust it?
A green pipeline is evidence that code ran. These four fields are the evidence that the data is right.
- The check the convention most needs is a dependency audit: assert that no gold model references a bronze table. It is a query against the lineage graph, it runs in seconds, and it catches the most common way medallion platforms become medallion-shaped rather than medallion-structured (Data Lineage).
- A second check asserts that every gold dataset has an owner, a declared grain and at least one business test attached. A gold table with none of those is a naming claim rather than a product.
- They miss whether the names mean the same thing to everyone using them, which is a documentation and onboarding problem that no automated check reaches (Who Owns Data Quality).
- The convention says nothing about freshness, and the metaphor invites the wrong assumption in both directions: some read gold as the most refined and therefore most current, others as the most processed and therefore most delayed.
- In practice each layer's freshness is set by its own build schedule and the depth of the chain above it, exactly as it would be under any naming.
- Publishing a freshness figure per named layer helps, because it replaces the metaphor with a number the consumer can check against their own need (Freshness Monitoring).
- Renaming layers later is disruptive out of proportion to its value: every reference, every dashboard, every saved query and every piece of tribal knowledge points at the old names. Choose once and move on (Impact Analysis).
- The convention has to absorb new needs — a domain-specific layer, an intermediate materialisation, a serving mart. Adding a name outside the metal scheme is usually better than stretching one of the three to cover it.
- As a platform grows, the boundary that matters shifts from "which layer" to "which domain owns this", and the medal names say nothing about ownership. That gap is where per-domain conventions start to appear (Data Products).
- Recovery is a property of the layers' purposes, not their names: rebuild from the deepest intact layer, which is bronze if the bug is in ingestion and silver if the bug is in a business rule (Reprocessing vs Retrying).
- A platform where gold models read bronze directly has lost the ability to rebuild the middle, because there is no middle for those models. The recovery cost of a violated boundary is paid at the worst possible moment (Planning a Backfill).
- Bronze retention is the recovery window, argued exactly as raw retention would be, and the medal name gives it no special status in that argument (Data Retention).
What can go wrong
- Gold models built directly on bronze, so the guarantees silver was supposed to provide never applied to them.
- Silver used as a dumping ground for anything that is neither raw nor consumer-facing, until it contains both conformance and business logic and its contract is meaningless.
- Datasets copied unchanged through all three layers because the convention says there are three layers.
- The mitigation failing: a dependency rule that forbids gold-on-bronze, configured for the models that existed when it was written and never applied to the models added since (Contract Enforcement).
- Consumers trusting gold because of the name rather than because of a contract, and treating a gold table with no tests as authoritative.
- Two teams in the same company using the same three names with materially different meanings, discovered when they try to share a dataset (Two Dashboards, Two Numbers).
- "A data platform needs bronze, silver and gold layers." It needs the three purposes. The names are a convention and any consistent set works equally well. Treating the medals as a requirement is the specific error this lesson exists to correct.
- "Gold means high quality." Gold means specific and consumer-facing. Quality comes from tests and contracts, and a gold table with neither is less trustworthy than a tested silver one (Data Quality).
- "Medallion is an architecture." It is a naming scheme for layers. The architecture is the set of boundaries, contracts, grants and dependency rules underneath — and two platforms with identical medal names can have completely different ones (Data Architecture Patterns).
- "Three layers is the right number." Three is a convention. Two is often right for a small platform; four is common once shared intermediate models appear.
- "Adopting the convention gives us the boundaries." Adopting the convention gives you the words. The boundaries come from grants, dependency rules and tests, all of which have to be built separately.
- The bronze layer carries the same governance weight as any raw layer: complete, source-shaped, and inside an analytical system with broad access. The medal name does not soften that and occasionally distracts from it.
- A layer naming convention is useful for policy precisely because it is coarse: "no consumer grants on bronze" is a policy that can be checked automatically, which is more than most governance rules manage (Data Classification).
- Deletion and retention obligations apply per dataset and per classification, not per layer. A platform that reasons about retention in medals will get the retention of a sensitive gold table wrong.
Operating it
- A lineage query counting edges from gold models to bronze tables. Ideally zero; any non-zero value is a list of models to fix.
- Per-layer read counts from the query log. Consumers reading bronze is the signal that the boundary is decorative (The Data Catalog).
- The proportion of gold datasets with a declared owner, grain and test. This is a platform-health number that is easy to compute and uncomfortable to look at.
- Build cost per layer, because a convention that forces pass-through copies shows up as builds that transform nothing (Cost Attribution).
- At small scale, three layers are often one more than necessary, and a two-layer platform — raw and curated — is a perfectly respectable answer that the convention discourages.
- At larger model counts, the three names stop discriminating: a platform with four hundred silver models needs a second axis — domain, source, owner — and the medal is no longer the useful part of the name.
- At multi-team scale, the convention has to be centrally defined or it fragments, and a fragmented convention is worse than none because it looks like agreement (Data Governance).
- The convention itself costs nothing. The literal application of it — every dataset through every layer — costs a build and a copy per pass-through.
- Bronze retention is the same storage argument as raw retention: a small, permanent line that buys the recovery window (Storage Lifecycle).
- The largest indirect cost is meeting time spent classifying datasets into medals, which produces no artefact anyone can test (Data Platform Anti-Patterns).
- A shared vocabulary buys onboarding speed and costs precision: three words cannot describe every dataset's role, and forcing them to produces either pass-through copies or arguments.
- Enforcing the layer boundary with grants buys real isolation and costs analyst convenience, since the freshest data becomes unreachable for the people most likely to want it.
- Following a vendor's reference convention buys alignment with its documentation and examples, and costs a slight loss of ability to think about your platform in terms that fit it rather than the reference (No Cargo-Cult Infrastructure is the infrastructure version of the same caution).
Layer naming map
Change an input and watch which number moves — and which one does not. Everything here comes from a model in this repository, not from a measurement.
| Idea | dbt convention | Medallion | Classic warehousing |
|---|---|---|---|
sources / raw_ | Bronze | Landing / staging area | |
stg_ | Bronze → Silver | Cleansed / conformed | |
int_ | Silver | Integration layer | |
fct_ / dim_ / mart_ | Gold | Presentation / dimensional model | |
| exposures | (not named) | Reporting layer |
Where this applies
Almost nothing here is universal. These labels say what each claim is specific to, and where a different engine, format, warehouse or scale would differ.
- TOOL-SPECIFICThe convention originates in lakehouse reference material and is most idiomatic there; a warehouse-centric platform using a transformation tool with its own staging/marts conventions gains nothing by renaming, and loses alignment with that tool's documentation and defaults.
- ORG-SPECIFICThe value of a shared naming convention scales with the number of people who read table names without asking anyone: in a three-person team it is nearly free and nearly pointless, while across ten teams a centrally defined convention is one of the cheaper coordination mechanisms available.
- SIMPLIFIEDPresenting the layer structure as exactly three named tiers is a teaching simplification; real platforms commonly carry an intermediate materialisation layer and per-domain serving datasets that the three-name scheme has no vocabulary for.
Where the depth lives
This domain teaches how data moves and how you know it arrived intact. It hands the rest off by name.
- — DevOps / Production Engineering owns the enforcement mechanics this lesson leans on: a build that fails when a dependency rule is violated is a CI concern, and a convention without CI behind it is a wiki page.