💡 Why modern metadata-driven teams no longer draw diagrams — they generate them.
1️⃣ The End of Manual Diagramming
In classic data modeling, diagrams were the main artifact — we used tools like PowerDesigner or ERwin to draw boxes and lines, define relationships, and label attributes. The visuals were the models.
Today, that relationship has flipped. In metadata-driven environments, the model comes first, and the diagram is a view — automatically generated from the underlying metadata.
This shift — from drawing to generating — may seem subtle, but it changes how we think about data modeling altogether.
2️⃣ Why Generation Matters
When diagrams are generated from code or metadata, several benefits follow naturally:
- [[Consistency]] — visuals always reflect the latest version of the model.
- [[Scalability]] — diagrams can be recreated across dozens of domains automatically.
- [[Standardization]] — layout, colors, and styles follow the same templates.
- Traceability — every diagram corresponds to a versioned metadata snapshot in Git.
- Accessibility — diagrams can be published in docs, wikis, or portals without exporting anything manually.
Instead of people adjusting arrows and fonts, we let metadata rules and templates handle the visual part. The result is not less visual — it’s more reliable.
3️⃣ The Five Main Approaches
Several technologies now enable diagram generation from code or metadata, each with its own strengths.
Let’s look at the five that have become key in modern metadata-driven modeling:
🧩 1. Mermaid — Lightweight and Markdown-Friendly
Mermaid has gained massive popularity because it integrates directly into Markdown environments like GitHub, Notion, Confluence, and many documentation tools. Its syntax is simple and text-based — perfect for quick visualization inside code repositories.
Example:
erDiagram
CUSTOMER ||–o{ ORDER : places
ORDER ||–|{ LINE_ITEM : contains
CUSTOMER {
string id
string name
}
ORDER {
string id
date order_date
}
Mermaid is ideal when:
- You want lightweight ER or flow diagrams embedded directly in documentation.
- Developers or data engineers already live in Markdown or Git.
- You need to visualize parts of a model quickly.
Limitation: Mermaid is less suited for large enterprise models or complex styling requirements.
🧩 2. Draw.io — Template-Based and Extensible
Draw.io (now often used as diagrams.net) offers a more visual environment, but with excellent automation potential. Its files are stored as XML, which means models can be generated or parsed using scripts.
This makes it an excellent fit for metadata-as-code pipelines — especially when combined with Python or YAML-based generators. In practice:
- The diagram layout can be templated.
- Entities, relationships, and colors are created from YAML.
- The Draw.io plugin in VS Code lets you visualize the model directly in your modeling workspace.
Draw.io works best when:
- You want a balance between flexibility and automation.
- You already use VS Code as your modeling environment.
- You need to share consistent visuals with business users.
Limitation: Not as text-friendly as Mermaid or PlantUML, and complex diagrams can become heavy.
🧩 3. PlantUML — Scriptable and Developer-Oriented
PlantUML is the most powerful of the three when it comes to scripting and integration. It supports ERDs, class diagrams, sequence diagrams, and even ontology-like relationships.
Because it’s code-based, it can easily be integrated in CI/CD pipelines and paired with AI generation (e.g., ChatGPT prompts producing PlantUML syntax).
Example:
@startuml
entity Customer {
id : string
name : string
}
entity Order {
id : string
order_date : date
}
Customer ||–o{ Order : places
@enduml
PlantUML is ideal when:
- You want full automation and developer control.
- You plan to use AI to draft models or transformations.
- You need output that integrates easily with other modeling or documentation tools.
Limitation: Layout is functional, not aesthetic — great for engineers, less friendly for business audiences.
🧩 4. GraphViz — The Hidden Engine Behind Many Generators
While tools like Mermaid, Draw.io, and PlantUML are visible to users, GraphViz often powers the diagrams behind the scenes — especially in enterprise automation contexts.
GraphViz uses the DOT language, a declarative syntax to define nodes and edges. It’s exceptionally good at automatically arranging complex networks, making it ideal for data lineage, process flows, and entity-relationship visualizations where layout matters as much as logic.
Example:
digraph DataFlow {
Customer -> Order -> Invoice;
Customer -> SupportTicket;
}
GraphViz shines when:
- You need fully automated generation at scale (e.g., hundreds of lineage diagrams).
- The diagrams are rendered programmatically, not manually edited.
- You’re integrating visuals into Python, Airflow, or data warehouse automation scripts.
Many data automation platforms and metadata tools (including those used by large banks and insurers) rely on GraphViz for rendering lineage and model diagrams — sometimes even as a backend for PlantUML or custom visualization layers.
Limitation: GraphViz focuses on layout and rendering, not interactivity or visual editing — it’s the engine, not the canvas.
🧩 5. yEd — Interactive Visualization and Layout Mastery
yEd is a powerful desktop application often used for interactive exploration of automatically generated diagrams. It can import GraphML, CSV, or JSON files — formats easily produced by metadata pipelines — and apply advanced automatic layout algorithms (hierarchical, orthogonal, organic) to make large graphs understandable at a glance.
Unlike command-line generators, yEd lets users fine-tune and annotate layouts visually after they’ve been generated, without losing the underlying metadata linkage.
Example workflow:
YAML metadata → GraphML via Python → yEd import → auto-layout → annotated export
yEd is ideal when:
- You want to explore or refine generated diagrams visually.
- You need publication-quality layouts (e.g., lineage, ERD, process maps).
- Your metadata tools already produce GraphML or CSV exports.
Limitation: It’s not text-based or scriptable like PlantUML or GraphViz, but it provides unmatched control and layout intelligence for large, complex models.
6️⃣ Integrating Diagram Generation into Metadata Workflows
The power of these formats isn’t in choosing one, but in how they integrate into metadata-driven workflows.
A typical setup could look like this:
YAML model definitions
↓
Python/Jinja generator
↓
PlantUML or Draw.io output (for diagrams)
↓
Mermaid snippets (for documentation)
↓
GraphViz or yEd for layout automation and refinement
↓
Publish to Confluence / Notion / GitHub Pages
Each serves its role:
- PlantUML for technical validation.
- Draw.io for business-friendly visualization.
- Mermaid for lightweight embedding in documentation.
- ==GraphViz== ==as the rendering engine for lineage and flows.==
- yEd for visual fine-tuning and presentation-quality output.
Together, they make visualization part of the continuous metadata integration pipeline — automatically generated with every model update.
7️⃣ AI and Diagram Generation
AI adds a new dimension: it can infer model structures from text, SQL, or existing metadata and output them directly in PlantUML, Mermaid, or Draw.io XML.
This enables workflows such as:
- “Generate a logical ER diagram from this YAML metadata.”
- “Summarize the relationships and produce a visual.”
- “Convert this dbt project into a conceptual diagram.”
Still, deterministic validation and rendering remain crucial — ensuring that the AI-generated diagrams follow enterprise standards and naming rules.
8️⃣ The Bigger Picture — From Tools to Templates
This evolution from manual drawing to automatic generation mirrors a broader trend:
we no longer model with diagrams — we explain models through diagrams.
In my previous articles (“From ERDs and Lineage to Executable Metadata”, “Collaborative Data Modeling in VS Code”, “Do We Still Need Traditional Data Modeling Tools?”), this principle already emerged: metadata, not diagrams, is the source of truth.
Mermaid, Draw.io, PlantUML, GraphViz, and yEd simply make that metadata visible — each serving a different audience and level of technical depth.
9️⃣ Closing Thought
Whether you’re an engineer scripting PlantUML, a metadata architect automating Draw.io, a documentation writer embedding Mermaid, a lineage developer leveraging GraphViz, or a designer refining visuals in yEd — the message is the same:
Diagrams are outputs, not artifacts.
When they are generated from code, they stop being illustrations and become living views of the data platform itself.
And that, more than anything, is what it means to move from traditional data modeling to model-driven data engineering.