Data Pipeline Guide

Medallion architecture diagram: draw the promotion rules, not just three boxes

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The three box bronze, silver, gold picture is on every slide deck about lakehouses and it teaches nobody anything, because the layer names are the least interesting part of the pattern. What a team actually needs drawn is the promotion rule at each boundary: what has to be true about a row before it is allowed into silver, and what a gold table is allowed to assume. Put those rules on the boundaries and the diagram starts settling design arguments instead of decorating them.

Try it free
7 min readFor lakehouse teams whose bronze, silver, and gold definitions have drifted apart

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

218/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Three zones, and a rule written on each boundary

Draw the layers as zones rather than as single boxes, because the layer is a container of tables, not a step. Then write the promotion rule on the boundary between zones, as a short annotation. Between bronze and silver it is typically something like deduplicated on business key, types cast, late arrivals resolved to event time. Between silver and gold it is aggregated to a business grain, joined to conformed dimensions, no source specific columns.

Those rules are what stop the layers drifting. Without them written down somewhere a reader can see, silver gradually accumulates business logic, gold gradually accumulates raw columns, and eighteen months later nobody can say what the layers mean any more. The boundary annotation is cheap insurance and it is the part of the diagram that survives longest.

Keep the layer characteristics on the zone label too. Bronze is append only with the source schema preserved plus an ingestion timestamp; silver is deduplicated and conformed with resolved keys; gold is business level aggregates shaped for specific consumers. Three short labels, one per zone.

It also helps to know what the pattern claims for itself. Databricks calls the medallion architecture a recommended best practice and explicitly not a requirement, says it is common to start data modeling in the silver layer, and describes gold as where you model for reporting and analytics using a dimensional model, with relationships and defined measures. That is a useful correction to how the pattern is usually drawn: the layers are a refinement ladder, not a replacement for a data model, so a gold zone should hold facts and dimensions that relate to each other rather than a shelf of unrelated aggregates.

Real table names, not placeholder boxes

A medallion diagram with nothing inside the zones is a diagram of the pattern, not of your platform, and the pattern is already documented by the vendor. Put the real objects inside: the bronze landing tables per source, the silver conformed entities, the gold marts. Where a layer has more tables than fit, group them by source or by domain and put a count on the group, for example 34 bronze tables across 6 sources.

Reflect your actual namespace in the names, because that is the part people copy into a query editor. On Databricks with Unity Catalog that usually means catalog.schema.table, so bronze reads as prod.bronze.crm_contacts. On Snowflake the layers are usually schemas or databases, so it reads as ANALYTICS.SILVER.CUSTOMER. Draw the container that really exists in your platform rather than the generic one from the reference architecture.

The arrows that matter most are between silver and gold, because that is where the fan out lives and where lineage questions get asked. Bronze to silver is usually one to one and can be summarized. Silver to gold is many to many and is exactly what a reader is trying to work out.

ZONE bronze  (append only, source schema + _ingested_at)
  prod.bronze.crm_contacts     prod.bronze.app_orders     [+31 more, 6 sources]
         |  promotion: dedupe on business key, cast types, resolve late arrivals
         v
ZONE silver  (conformed entities, resolved keys)
  prod.silver.customer   prod.silver.order   prod.silver.product
         |  promotion: aggregate to business grain, join conformed dims
         v
ZONE gold    (business aggregates per consumer)
  prod.gold.revenue_daily  -> Finance board
  prod.gold.customer_360   -> CRM reverse sync
  prod.gold.churn_features -> churn model

The fourth layer question, and what not to draw

Teams often want a fourth layer, called platinum or semantic or serving. The test is whether it is a real storage layer with tables that persist. If it is, draw it as a fourth zone with the same treatment: characteristics on the label, promotion rule on the boundary. If it is a semantic model or a metrics layer that computes on read, it is a serving surface, not a layer, and it belongs outside the medallion zones as a consumer.

Do not draw the orchestration inside the layer zones. The dbt runs or the Databricks jobs that move data between layers are not layers themselves, and putting them inline turns three clean boundaries into six boxes. Name the job on the promotion annotation instead, for example dbt build tag:silver, hourly.

Do not draw quality checks as a separate layer either. They belong at the boundary they guard, as part of the promotion rule, plus one quarantine node hanging off the bronze to silver boundary for the rows that fail. That single quarantine node is the most consulted part of a medallion diagram during an incident and it is missing from most of them.

From pattern to your platform

Describe your catalogs, schemas, and real table families in one paragraph and generate the zoned canvas, then correct the names. The medallion architecture guide covers the pattern itself; this page covers drawing yours.

FAQ

How do you draw a medallion architecture diagram?

Draw bronze, silver, and gold as three zones rather than three boxes, put the real table names or grouped counts inside each, and write the promotion rule on each boundary: what must be true about a row before it enters silver, and what a gold table is allowed to assume. Add a quarantine node for rows that fail promotion.

What goes in bronze, silver, and gold?

Bronze holds raw records in the source schema, append only, with an ingestion timestamp added. Silver holds deduplicated and conformed entities with resolved business keys and cast types, and is where Databricks says data modeling commonly begins. Gold holds business level aggregates shaped for a named consumer, modelled dimensionally with relationships and measures rather than assembled one report at a time.

Should the diagram use catalog and schema names?

Yes. Use the namespace that really exists on your platform, because that is what people copy into a query editor. On Databricks with Unity Catalog that is catalog.schema.table, so a bronze node reads as prod.bronze.crm_contacts. On Snowflake the layers are commonly databases or schemas, so it reads as ANALYTICS.SILVER.CUSTOMER.

Is a fourth platinum layer worth drawing?

Only if it is a real storage layer with tables that persist, in which case it gets the same treatment as the others: characteristics on the zone label and a promotion rule on the boundary. If it is a semantic or metrics layer that computes on read, it is a serving surface and belongs outside the medallion zones as a consumer.

Where do dbt runs or Databricks jobs go on a medallion diagram?

On the promotion annotation between zones, not as inline boxes. Writing dbt build tag:silver, hourly on the boundary keeps three clean layer transitions instead of turning them into six boxes, and it still tells the reader which job to look at when a layer is stale.

How many tables should appear inside each layer?

Enough to be recognizable, grouped once it stops being readable. Name the tables people actually talk about, and collapse the rest into a group node with a count such as 34 bronze tables across 6 sources, keeping the full list in the written documentation beside the diagram.