Jaco van der Laan

Organizing Diagrams and Metadata in VSCode

18/09/2025  ·  Data Architecture  ·  Data Engineering  ·  Data Modeling

article base/visualisation-diagramming
‹ ›

Use Visual Studio Code as a complete environment for working with metadata-driven diagrams — with draw.io integration, YAML validation, Git versioning, and linked navigation between visuals and code.

Summary

🗂 Organize diagrams, mappings, and SQL files in one project

🧩 Use the draw.io VSCode plugin to view and link diagrams

🔗 Link diagram components to YAML/SQL using IDs and tooltips

🧠 Maintain mappings in code, not in the GUI

🛠 Validate metadata, automate generation, and enforce standards

🤖 Use GitHub Copilot and YAML schema support for speed and correctness

Part 4: Visual Studio Code as the Metadata Hub

In this fourth article, we explore how to structure, edit, validate, and link together your metadata and diagrams inside Visual Studio Code (VSCode). This setup transforms VSCode into the ideal environment for working on metadata-driven architectures — with full control, traceability, and collaboration.

🧩 Why Use VSCode for Metadata and Diagrams?

VSCode allows you to:

  • Keep metadata (YAML/JSON) and diagrams (.drawio) together in one project
  • Use version control (Git) for all components
  • Navigate between diagram elements and their corresponding code (mappings, SQL)
  • Use schema validation, autocomplete, linting, and plugins

This results in:

  • ✅ Consistency
  • ✅ Developer comfort
  • ✅ Visual-documentation bridges for business users

📁 Recommended Project Structure

A clean file structure helps organize and link everything:

├── mappings
│ ├── customer_orders.yaml
│ └── products_to_dwh.yaml
├── diagrams
│ ├── customer_orders.drawio
│ └── products_to_dwh.drawio
├── sql
│ ├── customer_orders.sql
│ └── products_to_dwh.sql
├── metadata.duckdb
└── README.md

🔌 Essential VSCode Extensions

Here are the key plugins to support your workflow:

✅ Draw.io Integration

  • Open .drawio diagrams directly inside VSCode
  • View and edit diagrams without switching tools

✅ YAML / JSON Schema Validator

  • Validate your metadata definitions
  • Auto-complete fields based on schema
  • Highlight structural issues early

✅ Bookmarks / Link Navigator

  • Allow you to jump from selected text or diagram box IDs to related files
  • You can simulate clickable navigation using custom annotations or bookmarks

✅ GitLens

  • Git history and blame for all files (diagrams included)

🔗 Linking Diagrams to Code

We recommend establishing a naming convention or ID mapping system that links components:

Diagram Box → Mapping File

  • Add id="customer_orders" in the diagram XML
  • Have a customer_orders.yaml mapping file
  • Use tooltips or labels inside the box for guidance

Example tooltip:

Mapping: customer_orders.yaml

Model: customer_orders.sql

This makes it easy for team members to:

  • Know what the diagram box refers to
  • Click or CTRL+P → open the related file

Advanced: implement a script that syncs or checks consistency between boxes and file names.

✍️ Non-Visual Mapping Maintenance

Diagrams are for viewing — not editing mappings. Here’s how to manage mappings efficiently:

  • Maintain YAML/JSON as the source of truth
  • Validate against schemas in real-time
  • Generate .drawio from these files (as described in Part 2)
  • Only use draw.io plugin for quick visual reference or stakeholder validation

Why this works:

  • Developers prefer text-based control
  • CI/CD systems can validate code, not GUI edits
  • Visuals stay in sync without becoming a bottleneck

🧠 GitHub Copilot: Your Assistant

GitHub Copilot can:

  • Help write mapping YAML files
  • Suggest field names, transformations, and join conditions
  • Accelerate diagram or SQL file generation logic
  • Help enforce conventions

This makes VSCode even more powerful as a metadata development environment.

🧪 Validations and Dev Tools

Use Python scripts or extensions to:

  • Check that all boxes in diagrams map to a YAML or SQL file
  • Verify completeness of mappings
  • Detect unused files or broken links
  • Validate syntax and structure of YAML

Integrate with:

  • pytest or custom test runners
  • pre-commit hooks
  • CI tools like GitHub Actions

🗂️ Benefits of This Setup

📌 Summary

With draw.io and metadata side by side in VSCode:

  • 💡 You get the clarity of diagrams
  • 🔧 The power of code-first modeling
  • 📐 The control of validation and automation

This environment is ideal for modern data modeling teams who want the best of both worlds.

In the next article, we’ll explore how to publish diagrams and metadata to Confluence, combining business-readability with technical traceability.