What distinguishes a silver-layer table from a bronze one beyond the naming convention?

## A layer is a contract, not a directory The most common misreading of medallion architecture is that it is a filing scheme — put raw things in a bronze schema, cleaned things in a silver schema, done. What actually makes the pattern work is that each layer publishes a **contract**: a set of assumptions a consumer is entitled to make without re-reading the upstream code. Two tables can be byte-identical in content and belong to different layers, because what differs is what has been promised, tested and owned. ## What bronze promises Exactly one thing: fidelity. This row is what the source delivered, in this batch, at this time. Bronze promises nothing about uniqueness (retries produce duplicates), nothing about types (a date may be a string, a number may carry a currency symbol), nothing about completeness (a delivery may be partial), and nothing about semantics (a column named `status` means whatever the source system means by it). Consumers of bronze are on their own, which is why direct consumption of bronze by dashboards is a smell. ## What silver promises Silver's contract typically has five parts. **Grain.** The table states what one row is — one order, one order line, one customer, one device-day — and that statement is enforced, not aspirational. A grain uniqueness test is the cheapest and highest-value test in a warehouse: ```sql SELECT order_id, COUNT(*) AS n FROM silver_orders GROUP BY order_id HAVING COUNT(*) > 1; ``` **Types and nullability.** Real dates, real decimals, declared not-null columns. Downstream code stops defensively casting. **Identity.** Business keys are resolved: the same customer arriving from the billing system, the CRM and the web events is one identity with one key, so joins across sources are meaningful. **Conformance.** Currencies converted or normalised with a stated rule, country and status codes mapped to one vocabulary, units standardised. This is what makes two silver tables joinable without a translation layer in between. **Rejection policy.** Records that fail validation are handled deliberately — quarantined to a side table with a reason, or counted and dropped — rather than silently disappearing. ## What gold promises on top Gold adds *business* meaning: which rows count as revenue, how returns and cancellations are treated, what "active customer" means, what grain a fact table is at and which dimensions decorate it. It also carries the strongest stability promise, because its column names are the ones embedded in dashboards and downstream extracts. Silver correctness questions are "is this the right data"; gold questions are "is this the right definition". ## The same idea under other names Analytics-engineering projects commonly say **staging → intermediate → marts**. Staging is the thin typed layer directly over raw; intermediate holds the reusable cleaning, deduplication and key resolution — the rest of silver; marts are gold. Older enterprise warehouses said landing / integration / presentation. Recognising the mapping is worth more in an interview than defending a particular vocabulary, because teams mix them freely and the guarantees are what transfer. ## How to tell a layer from a copy Ask what a consumer gains by reading this table instead of the one upstream. Legitimate answers: "it is deduplicated to one row per order and that is tested", "the currency is normalised to USD with a documented rate rule", "customer identity is resolved across three systems", "this is the finance definition of net revenue". Illegitimate answers: "it has nicer column names", "it was easier to query", "the other one is slow", "the marketing team wanted their own". Renaming columns is not a guarantee; convenience is not a contract. ## Enforcement is the part people skip A contract nobody checks decays within a quarter. Minimum viable enforcement is a grain-uniqueness test, not-null tests on the columns downstream code assumes are populated, and referential checks on the keys used for joins — run on every build, failing loudly. Alongside that, an owner who is paged when it breaks and a one-line description of what a row means. The detailed taxonomy of data tests and documentation practice is its own subject; the point here is that the layer boundary is only as real as the checks standing on it. ## Why the distinction matters operationally When a downstream number is wrong, layered contracts let you binary-search the pipeline: run the silver grain test, and either it fails — cleaning is at fault — or it passes and you look at the gold business rule, or at bronze to see whether the source changed. Without contracts, every investigation starts from the raw data again, and the layers have bought you nothing but storage.