# What Is the Medallion Diagram Type for Data Storage in diagram‑design? > Learn about the Medallion diagram type for data storage in diagram-design. Visualize hierarchical data lakes and warehouses with this multi-tier layout. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: deep-dive - Published: 2026-08-14 --- **The Medallion diagram type is a parametric, multi‑tier data‑storage layout that visualizes hierarchical data lakes or warehouses, where each tier represents a distinct quality or access level such as raw, anonymized, staging, aggregated, and archive.** The `diagram-design` repository by Cathryn Lavery provides a specialized diagram type for documenting modern data architectures. The Medallion diagram stands out for its deterministic, code-driven approach to generating reproducible SVG visualizations of data storage hierarchies. Unlike general-purpose drawing tools, this implementation uses a YAML inputs schema to guarantee consistent output across environments and teams. ## Key Characteristics of the Medallion Diagram Type The Medallion diagram type is optimized for scenarios where understanding data lineage, ownership, and quality tiers matters more than generic box-and-line diagrams. ### Purpose and Use Cases According to the reference specification in [`skills/diagram-design/references/type-medallion.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-medallion.md), this diagram type excels at: - Documenting **multi‑tier storage systems** where data progresses through quality stages - Showing **tier content, ownership, and promotion flow** in a single view - Communicating **tooling and format decisions** per storage layer - Tracing **data lineage** between buckets with explicit transformation labels The name derives from the visual pattern: tiers arranged horizontally like stacked medallions, with arcs showing promotion paths flowing over the top. ### Parametric Design Architecture Every Medallion diagram is generated from a **YAML inputs schema** that drives coordinates via deterministic layout formulas. This ensures: - **Reproducible SVG output** — identical inputs produce identical pixels - **Version-controlled diagrams** — diffs show meaningful structural changes - **Programmatic generation** — CI/CD pipelines can render diagrams from infrastructure-as-code The layout engine calculates all positions mathematically; no manual nudging or pixel-pushing is required or supported. ## Tier Styling and Configuration ### Four Built-In Tier Styles The Medallion diagram type defines four visual styles applied per tier: | Style | Visual Treatment | Typical Use | |-------|------------------|-------------| | `outer` | Distinct border treatment | Entry points (raw ingestion) | | `default` | Standard fill and stroke | Processing tiers | | `focal` | Emphasized header band | Primary consumer-facing tier | | `cold` | Dashed stroke pattern | Archive or compliance storage | Exactly **one tier must be marked `focal: true`**. The focal tier receives visual emphasis through its header band and serves as the diagram's conceptual center of gravity. ### Per-Tier Data Fields Each tier defines structured metadata in its `fields` property: - **`tool`** — ingestion or processing technology - **`format`** — storage format and partitioning strategy - **`writer`** — role or team responsible for writes - **`example`** — array of representative data contents Color overrides are permitted on `default` and `outer` tiers, but **prohibited on focal and cold tiers** to preserve visual semantics. ## Promotion Arcs and Data Flow ### Cubic Bézier Layout Data movement between tiers renders as **cubic Bézier arcs positioned over the top** of the tier strip. The implementation in [`type-medallion.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-medallion.md) specifies: - Anchor points at **top-center of source and target tier rectangles** - Control points fixed at **y = 0** (above the diagram) - Guaranteed visibility: arcs and labels never overlap tier content This design choice prioritizes readability over arbitrary aesthetic curves. ### SVG Path Implementation The resulting SVG path uses absolute coordinates with calculated control points: ```svg ``` The `{accent}` token resolves to a theme-aware color value. Dark mode automatically swaps token pairs like `paper ↔ ink` without YAML changes. ### Promotion Style Variants Three arc styles convey different semantics: - **`normal`** — standard data promotion - **`focal`** — flow into or out of the focal tier (emphasized) - **`lifecycle`** — compliance-driven archival or deletion ## Optional Path Row for Write Methods The Medallion diagram supports an optional **`paths`** array describing how data moves between tiers. Up to two path cards appear beneath the tier strip: ```yaml paths: - { tag: "SQL PATH", title: "Trino INSERT INTO … SELECT", sub: "filter·reshape·join·aggregate — set‑based transforms" } - { tag: "NOTEBOOK PATH", title: "DuckDB + Python/R in JupyterHub", sub: "stats·ML·interactive analysis — row‑iterative work" } ``` This bridges the gap between *what* (tiers) and *how* (implementation patterns). ## Complete YAML Example: Five-Tier Architecture This production-ready definition from the reference demonstrates all features working together: ```yaml title: "Five‑Tier Medallion Architecture" subtitle: "Quarterly survey through Raw → Anonymized → Staging → Aggregated → Archive" tiers: - { name: "Raw", bucket: "raw-bucket", style: "outer", fields: { tool: "NiFi · raw write", format: "CSV · Parquet · JSON", writer: "Data Engineer", example: ["Q1 dump · w/ PII", "verbatim CAPI export"] } } - { name: "Anonymized", bucket: "anon-bucket", style: "default", fields: { tool: "Trino INSERT", format: "Iceberg · partitioned", writer: "Data Engineer", example: ["no name · address", "stable household ID"] } } - { name: "Staging", bucket: "staging-bucket", style: "default", color: "#c9a23a", fields: { tool: "Trino · JupyterHub", format: "Iceberg·cleaned", writer: "Data Scientist", example: ["weighted records", "harmonised codings"] } } - { name: "Aggregated", bucket: "aggregated-bucket", style: "focal", focal: true, fields: { tool: "Trino INSERT · SAS JDBC", format: "Iceberg·indicators", writer: "Data Scientist", example: ["unemployment rate", "labour participation"] } } - { name: "Archive", bucket: "archive-bucket", style: "cold", fields: { tool: "MinIO lifecycle", format: "cold tier·immutable", writer: "Data Administrator", example: ["historical Q1–Q4 sets", "5+ years retained"] } } promotions: - { from: 0, to: 1, label: "PII REMOVE", style: "normal" } - { from: 1, to: 2, label: "CLEAN+WEIGHT", style: "normal" } - { from: 2, to: 3, label: "AGGREGATE", style: "focal" } - { from: 3, to: 4, label: "LIFECYCLE", style: "lifecycle" } paths: - { tag: "SQL PATH", title: "Trino INSERT INTO … SELECT", sub: "filter·reshape·join·aggregate — set‑based transforms" } - { tag: "NOTEBOOK PATH", title: "DuckDB + Python/R in JupyterHub", sub: "stats·ML·interactive analysis — row‑iterative work" } dark: false ``` Tier indices in `promotions` are **zero-based** and reference position in the `tiers` array. ## Source Files and Further Reference | File | Location | Purpose | |------|----------|---------| | [`type-medallion.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-medallion.md) | `skills/diagram-design/references/` | Complete specification with inputs schema, layout formulas, and styling rules | | [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) | `skills/diagram-design/` | Master index of all diagram types including Medallion | | [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) | Repository root | Visual preview and quick-start links | The reference file includes a reproducibility checklist for verifying SVG output across environments — essential for teams treating diagrams as build artifacts. ## Summary - The **Medallion diagram type** visualizes multi‑tier data storage with explicit quality stages and promotion flows - **Parametric YAML-driven design** guarantees reproducible, version-controlled SVG output - **Four tier styles** (`outer`, `default`, `focal`, `cold`) encode semantic roles with strict color override rules - **Over-the-top Bézier arcs** show data lineage without obscuring tier content - **Optional path row** documents implementation patterns for cross-tier data movement - **Automatic dark mode** swaps color tokens without configuration changes ## Frequently Asked Questions ### What makes the Medallion diagram type different from generic flowcharts? The Medallion diagram type is **domain-specific for data storage architectures**. Unlike general flowchart tools, it enforces a horizontal tier layout with standardized metadata fields (tool, format, writer, examples) and mathematically calculated promotion arcs. The parametric design eliminates manual positioning while ensuring all diagrams in an organization share consistent visual grammar. ### Can I have more than one focal tier in a Medallion diagram? No. The schema requires **exactly one `focal: true` marker** across all tiers. Attempting to define zero or multiple focal tiers violates the specification and will fail validation. The focal tier receives distinctive visual treatment to guide viewer attention to the primary consumption point in your data architecture. ### How does dark mode work in Medallion diagrams? Dark mode operates through **token substitution** rather than duplicating color definitions. The renderer swaps semantic tokens like `paper` and `ink` based on the `dark: boolean` flag in YAML. This approach keeps specifications minimal while ensuring accessible contrast ratios in both themes without manual color picking. ### Where are promotion arc coordinates calculated? The layout formulas in [`type-medallion.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-medallion.md) define arc geometry: control points anchor at **y = 0** above the diagram, with source and target points at tier top-center. These calculations happen deterministically from tier widths and positions — you provide `from` and `to` indices only, never raw coordinates.