Drawio Agents Code Validator

Draw.io Code Validator

Purpose

This skill defines an 8-stage validation pipeline for Draw.io mxGraph XML. Run this pipeline on EVERY diagram before presenting it to the user or saving it to a file. The pipeline catches structural, style, and geometry errors in order of severity — blocking errors first, warnings second.

Critical Rules (Memorize These)

1. ALWAYS run ALL 8 stages — NEVER skip a stage, even if earlier stages pass.
2. Stages 1-4 are BLOCKING — If ANY stage from 1 to 4 fails, STOP and fix before continuing. NEVER deliver XML that fails a blocking stage.
3. Stages 5-8 produce WARNINGS — Fix these when possible, but they do NOT block delivery.
4. ALWAYS report errors in severity order — BLOCKING errors first, then WARNINGS.
5. ALWAYS provide a fix for each error — NEVER report an error without its correction.
6. NEVER silently fix errors — Report what was found AND what was corrected.
7. ALWAYS validate the COMPLETE file — NEVER validate a partial snippet and assume the rest is correct.

Pipeline Overview

Stage 1: XML Well-Formedness .......... BLOCKING
Stage 2: Structure Check .............. BLOCKING
Stage 3: ID Uniqueness ................ BLOCKING
Stage 4: Parent-Child Integrity ....... BLOCKING
Stage 5: Style Validation ............. WARNING
Stage 6: Geometry Check ............... WARNING
Stage 7: Connection Validation ........ WARNING
Stage 8: Perimeter Check .............. WARNING

If Stage 1 fails, Stages 2-8 CANNOT run (no parseable tree). If Stage 2 fails, Stages 4-8 produce unreliable results. Stages 3-8 are independent of each other and ALWAYS run regardless of other warning-stage results.

Stage 1: XML Well-Formedness (BLOCKING)

What: Verify the XML document is syntactically valid.

Checks:

On Failure: STOP pipeline. Report the exact location (tag name, approximate position) and the fix.

Auto-Fix Capabilities:

• Add missing self-close slash (> to /> on childless elements)
• Escape unescaped & to & in attribute values
• Remove fabricated Base64 content and replace with empty <mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel>

Stage 2: Structure Check (BLOCKING)

What: Verify the mandatory mxGraph document structure exists.

Checks:

On Failure: STOP pipeline. Insert missing structural cells.

Auto-Fix Capabilities:

• Insert <mxCell id="0"/> if missing
• Insert <mxCell id="1" parent="0"/> if missing
• Remove illegal attributes from structural cells
• Wrap bare <root> in <mxGraphModel>

Stage 3: ID Uniqueness (BLOCKING)

What: Verify every cell has a unique identifier.

Checks:

On Failure: STOP pipeline. Report every duplicate pair with their cell values/labels for identification.

Auto-Fix Capabilities:

• Reassign duplicate IDs to new unique values (sequential integers starting from max existing ID + 1)
• Update all parent, source, and target references that pointed to the reassigned ID
• NEVER reassign id="0" or id="1"

Stage 4: Parent-Child Integrity (BLOCKING)

What: Verify every parent reference resolves to an existing cell.

Checks:

On Failure: STOP pipeline. Report each broken reference with the orphaned cell's ID and value.

Auto-Fix Capabilities:

• Set parent="1" on orphaned cells (assigns them to the default layer)
• Break circular references by resetting the child's parent to "1"

Stage 5: Style Validation (WARNING)

What: Verify style strings use correct syntax, known properties, and valid values.

Checks:

Known Style Properties (non-exhaustive — common ones):

fillColor, strokeColor, fontColor, fontSize, fontFamily, fontStyle,
rounded, dashed, shadow, opacity, html, whiteSpace, align, verticalAlign,
overflow, container, collapsible, swimlane, startSize, endSize,
shape, perimeter, arcSize, spacing, spacingTop, spacingBottom,
spacingLeft, spacingRight, labelPosition, verticalLabelPosition,
edgeStyle, startArrow, endArrow, startFill, endFill, curved,
jettySize, orthogonalLoop, exitX, exitY, exitDx, exitDy,
entryX, entryY, entryDx, entryDy, sourcePerimeterSpacing,
targetPerimeterSpacing, strokeWidth, rotation, direction,
gradientColor, gradientDirection, glass, sketch, comic,
jumpStyle, jumpSize, fixedSize, resizable, movable, deletable,
connectable, noLabel, imageWidth, imageHeight, image, aspect

Valid Shape Names (built-in):

rectangle, ellipse, rhombus, triangle, hexagon, cylinder, cylinder3,
cloud, actor, swimlane, line, image, document, parallelogram, step,
trapezoid, process, callout, note, cross, plus, card, umlLifeline,
folder, internalStorage, manualInput, delay, display, merge, or,
offPageConnector, tape, tapeData, sumEllipse, sortShape, collate,
doubleEllipse, singleArrow, doubleArrow, curlyBracket, link

Shapes starting with shape=mxgraph. are valid stencil library references.

Auto-Fix Capabilities:

• Add html=1; to styles missing it
• Add whiteSpace=wrap; to vertex styles missing it
• Replace true/false with 1/0 in boolean properties
• Remove spaces around = in style properties

Stage 6: Geometry Check (WARNING)

What: Verify geometry attributes are correct for the cell type.

Checks:

Auto-Fix Capabilities:

• Add relative="1" to edge geometries missing it
• Add as="geometry" to <mxGeometry> elements missing it
• Set minimum width/height of 40x40 for vertices with missing or zero dimensions

Stage 7: Connection Validation (WARNING)

What: Verify edges connect to valid cells with correct routing.

Checks:

Valid Edge Styles:

orthogonalEdgeStyle, elbowEdgeStyle, entityRelationEdgeStyle,
isometricEdgeStyle, segmentEdgeStyle, straightEdgeStyle (not a real value — omit edgeStyle for straight)

Valid Arrow Names:

classic, block, open, oval, diamond, diamondThin, box,
halfCircle, dash, cross, circlePlus, circle, ERone,
ERmany, ERmanyToMany, ERoneToMany, ERzeroToMany,
ERzeroToOne, ERoneToOne, none

Auto-Fix Capabilities:

• Remove source/target attributes that reference non-existent cells
• Add endArrow=classic to edges missing arrow configuration

Stage 8: Perimeter Check (WARNING)

What: Verify that shape perimeters match their shape types for correct edge connection points.

Checks:

Shape-to-Perimeter Mapping:

Auto-Fix Capabilities:

• Add the correct perimeter= property based on the shape type
• Remove mismatched perimeter values and replace with the correct one

Error Report Format

ALWAYS report validation results using this structure:

VALIDATION RESULT: [PASS | FAIL]

BLOCKING ERRORS (must fix):
  [S1-E1] Stage 1 — XML Well-Formedness
    Severity: BLOCKING
    Location: <mxCell id="5" ...>
    Error: Unclosed tag — missing self-close slash
    Fix: Change <mxCell id="5" value="Test"> to <mxCell id="5" value="Test" />

  [S4-E1] Stage 4 — Parent-Child Integrity
    Severity: BLOCKING
    Location: <mxCell id="7" parent="99" ...>
    Error: Parent "99" does not exist
    Fix: Change parent="99" to parent="1"

WARNINGS (should fix):
  [S5-W1] Stage 5 — Style Validation
    Severity: WARNING
    Location: <mxCell id="3" style="rounded=1;" ...>
    Error: Missing html=1 in style
    Fix: Change style to "rounded=1;html=1;"

  [S8-W1] Stage 8 — Perimeter Check
    Severity: WARNING
    Location: <mxCell id="4" style="ellipse;html=1;" ...>
    Error: Ellipse shape missing ellipsePerimeter
    Fix: Change style to "ellipse;html=1;perimeter=ellipsePerimeter;"

SUMMARY: 2 blocking errors, 2 warnings
AUTO-FIXED: [list of auto-applied fixes, if any]

Validation Decision Tree

START
  |
  v
[Stage 1: XML Well-Formedness]
  FAIL --> Report BLOCKING errors --> Attempt auto-fix --> Re-run Stage 1
           STILL FAIL --> STOP. Report "XML is unparseable. Manual fix required."
  PASS
  |
  v
[Stage 2: Structure Check]
  FAIL --> Report BLOCKING errors --> Auto-fix (insert structural cells) --> Re-run Stage 2
           STILL FAIL --> STOP. Report structural errors.
  PASS
  |
  v
[Stage 3: ID Uniqueness]
  FAIL --> Report BLOCKING errors --> Auto-fix (reassign IDs) --> Re-run Stage 3
  PASS
  |
  v
[Stage 4: Parent-Child Integrity]
  FAIL --> Report BLOCKING errors --> Auto-fix (reset orphans to parent="1") --> Re-run Stage 4
  PASS
  |
  v
[Stage 5: Style Validation]       -- runs regardless of Stage 6-8 results
[Stage 6: Geometry Check]          -- runs regardless of Stage 5,7-8 results
[Stage 7: Connection Validation]   -- runs regardless of Stage 5-6,8 results
[Stage 8: Perimeter Check]         -- runs regardless of Stage 5-7 results
  |
  Collect all WARNINGS
  |
  v
[Generate Report]
  BLOCKING errors found?
    YES --> Overall: FAIL. Apply auto-fixes and re-validate.
    NO  --> Overall: PASS (with warnings if any).

Integration with Related Skills

• drawio-errors-xml — Provides the detailed error catalog (E-001 through E-019) referenced by this validator. When this pipeline detects an error, reference the corresponding E-code from that skill.
• drawio-errors-rendering — Covers visual rendering issues that occur AFTER XML is structurally valid. Stage 5 and Stage 8 of this pipeline catch many rendering issues at the XML level.
• drawio-core-xml-format — Defines the expected XML structure that Stage 1 and Stage 2 validate against.
• drawio-syntax-styles — Defines the valid style properties and values that Stage 5 validates against.
• drawio-syntax-connections — Defines edge connection patterns that Stage 7 validates against.

Quick Reference: Minimum Valid XML

ALWAYS validate against this minimum structure:

<mxfile compressed="false">
  <diagram id="page-1" name="Page-1">
    <mxGraphModel>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- content cells here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Every content cell MUST have:

• A unique id attribute
• A parent attribute referencing an existing cell
• Either vertex="1" or edge="1"
• A style attribute containing at minimum html=1
• A child <mxGeometry as="geometry" ... /> element

Reference Links

• Complete Reference
• Working Examples
• Anti-Patterns