File types and extensions

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

When you attach or import a file, three signals decide which language it is, and they are consulted in a fixed order. Knowing the order explains almost every surprising import.

The short version: a marker inside the file beats the extension, and the extension beats whatever language you said it was.

#When you need this page

  • Importing existing diagrams and getting the wrong language.

  • Bulk imports, where the extensions have to be right.

  • Understanding why an .xml file became a draw.io diagram.

#The detail

Field

What it does

1. A marker inside the file

<mxfile> is draw.io. @startuml is PlantUML. A Vega $schema picks Vega or Vega-Lite.

2. The filename extension

Matched longest first, so .excalidraw.json beats .json and .bpmn20.xml beats .xml.

3. The language you passed

Only a fallback, so a mislabelled file still stores correctly.

Nothing matched

Stored as Mermaid.

#Extensions by language

Language

Extensions

Mermaid

.mermaid, .mmd

PlantUML

.plantuml, .puml, .pu, .iuml, .wsd

draw.io

.drawio, .drawio.xml, .dio, .xml

Excalidraw

.excalidraw, .excalidraw.json

BPMN

.bpmn, .bpmn20.xml

DMN

.dmn

Graphviz

.dot, .gv, .graphviz

C4-PlantUML

.c4plantuml, .c4puml

D2

.d2

DBML

.dbml

ERD

.erd

Structurizr

.structurizr, .dsl

Nomnoml

.nomnoml

Vega

.vega.json

Vega-Lite

.vegalite.json

BlockDiag family

.blockdiag, .actdiag, .seqdiag, .nwdiag, .packetdiag, .rackdiag

Bytefield

.bytefield

WaveDrom

.wavedrom

WireViz

.wireviz, .wv

Symbolator

.symbolator

TikZ

.tikz, .tex

Pikchr

.pikchr

Ditaa

.ditaa

Svgbob

.svgbob

Visio

.vsdx, .vssx

#A few things that catch people out

  • A plain .xml is read as draw.io. A BPMN file must keep .bpmn20.xml or it will be misread.

  • .png and .svg are importable only when they are draw.io exports, which carry the XML inside the image.

  • Legacy Visio binaries (.vsd, .vdx, .vss, .vsx) are not supported. Re-save as .vsdx first.

The page you only need when something is odd.