Specification Format

The YAML specification is the canonical representation for Draw.io Skill 2.2.0.

Mermaid, CSV, and imported .drawio files are convenience inputs. They should all normalize into this structure before rendering.

Minimal Example

meta:
  theme: tech-blue
  layout: horizontal

nodes:
  - id: api
    label: API Gateway
    type: service
  - id: db
    label: PostgreSQL
    type: database

edges:
  - from: api
    to: db
    type: data
    label: Query

Top-Level Sections

meta

Diagram-wide settings.

meta:
  theme: tech-blue
  layout: horizontal
  routing: orthogonal
  profile: default
  figureType: architecture
  title: Example Diagram
  source: generated

Common fields:

• theme: tech-blue, academic, academic-color, nature, dark, high-contrast
• layout: horizontal, vertical, hierarchical
• routing: orthogonal, rounded
• profile: default, academic-paper, engineering-review
• figureType: architecture, roadmap, workflow when profile=academic-paper
• source: generated, replicated, or edited

modules

Logical containers for related nodes.

modules:
  - id: backend
    label: Backend

nodes

Required. Each node needs a stable id and label.

nodes:
  - id: api
    label: API Gateway
    type: service
    module: backend
    position:
      x: 160
      y: 96
    icon: aws.api-gateway

edges

Optional, but most diagrams use them.

edges:
  - from: api
    to: db
    type: data
    label: Query
    labelPosition: center

Replication Metadata

Replicated diagrams usually include:

meta:
  source: replicated
  replication:
    colorMode: preserve-original
    background: "#FFF7ED"
    palette:
      - hex: "#FDBA74"
        role: service fill
        appliesTo: nodes
        confidence: high

colorMode can be:

• preserve-original
• theme-first

Type Auto-Detection

When type is omitted, labels can still map to:

• database
• decision
• terminal
• queue
• user
• document
• formula
• default fallback: service

Formula detection should only rely on:

• $$...$$
• \(...\)
• `...`

Validation Expectations

The compiler validates:

• schema and ID correctness
• theme, profile, and layout values
• academic figureType when paper mode is enabled
• layout consistency
• edge quality
• academic-paper requirements when enabled

Use strict mode when warnings should fail the build.

Migration from A-H Format

The old A-H format is legacy guidance. The canonical mapping is now:

Legacy idea	YAML location
layout	meta.layout
modules	modules[]
nodes	nodes[]
edges	edges[]
visual style	meta.theme and style overrides
export intent	local CLI or Desktop export path

Related

• Design System
• CLI Tool
• Replicating Diagrams