# File types and extensions

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.

---

## Related

[Rendering limitsSizes, timeouts, and what anonymous readers see.](https://help.gocapable.com/diagrams/rendering-limits.html)

[Diagram macro referenceEvery field on the macro, and what it changes.](https://help.gocapable.com/diagrams/diagram-macro-reference.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_The page you only need when something is odd._