BPMN Under the Hood: XML, JSON, and the Future of Process Modeling
Business Process Model and Notation (BPMN) is the ISO standard for mapping business workflows into diagrams that both analysts and developers can understand. But behind every pretty diagram is a file format doing the heavy lifting. Most people interact with BPMN through drag-and-drop editors, but the serialization format underneath matters a lot when you are versioning processes, integrating with CI/CD pipelines, or exchanging models between tools.
BPMN started as XML and that is still the canonical interchange format. But JSON implementations have gained real traction in the web tooling space. This post covers both formats with a concrete example so you can decide which fits your use case.
Here is the invoice approval process mapped as a flowchart:
graph TD
A(["Invoice Received"]) --> B["Review Invoice"]
B --> C{"Approved?"}
C -->|Yes| D(["Approved"])
C -->|No| E(["Rejected"])
That flow took 5 lines of plain text. Now look at the BPMN XML equivalent below 35+ lines with namespace declarations, diagram interchange coordinates, and resource assignment expressions. This is the core maintenance problem with XML-based process definitions: the markup that describes the process is tangled up with the markup that describes how to draw it. Changing one node's position means editing DI coordinates. Adding a participant means updating namespace references. A single logical change touches multiple concerns in the document.
Mermaid.js handles layout automatically you describe what nodes and edges exist, and the library computes the coordinates at render time. That separation of concerns is the same advantage JSON-based BPMN representations offer over the XML standard, and it is why web-native tooling increasingly favours JSON.
BPMN XML: The Standard
The Object Management Group (OMG) defines BPMN 2.0 using an XML Schema. Every compliant tool exports to this format. It is verbose, strict, and unambiguous. A .bpmn file contains the process flow, the visual layout (DI, or Diagram Interchange), and metadata about shapes and connections.
Here is a simple invoice approval process in BPMN XML:
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
targetNamespace="http://example.com/invoice">
<process id="invoiceApproval" name="Invoice Approval" isExecutable="true">
<startEvent id="start" name="Invoice Received" />
<userTask id="review" name="Review Invoice">
<potentialOwner>
<resourceAssignmentExpression>
<formalExpression>approver</formalExpression>
</resourceAssignmentExpression>
</potentialOwner>
</userTask>
<exclusiveGateway id="decision" name="Approved?" gatewayDirection="Diverging" />
<endEvent id="approved" name="Approved">
<terminateEventDefinition />
</endEvent>
<endEvent id="rejected" name="Rejected" />
<sequenceFlow id="flow1" sourceRef="start" targetRef="review" />
<sequenceFlow id="flow2" sourceRef="review" targetRef="decision" />
<sequenceFlow id="flow3" sourceRef="decision" targetRef="approved">
<conditionExpression xsi:type="tFormalExpression">${approved == true}</conditionExpression>
</sequenceFlow>
<sequenceFlow id="flow4" sourceRef="decision" targetRef="rejected">
<conditionExpression xsi:type="tFormalExpression">${approved == false}</conditionExpression>
</sequenceFlow>
</process>
<bpmndi:BPMNDiagram>
<bpmndi:BPMNPlane bpmnElement="invoiceApproval">
<bpmndi:BPMNShape id="shape_start" bpmnElement="start">
<dc:Bounds x="50" y="100" width="36" height="36" />
</bpmndi:BPMNShape>
</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
</definitions>
Key observations. The XML is precise but heavy. The process logic, resource assignments, and diagram layout all live in one document. That is great for portability but a lot of markup to read or diff by hand.
BPMN as JSON
JSON-based BPMN representations emerged because web tooling runs on JavaScript, and parsing XML in the browser is comparatively painful. Camunda 8 uses a JSON-based process definition format for its Zeebe engine. Mermaid.js follows the same pattern it defines diagrams as lightweight JSON-like text blocks and renders them as SVGs without touching XML at all. The bpmn-js library represents the diagram internally as a JSON object. There is no single JSON standard equivalent to the OMG XML schema, but the ecosystem is converging around a few common shapes.
The same invoice approval process in a JSON representation:
{
"id": "invoiceApproval",
"name": "Invoice Approval",
"version": 1,
"nodes": [
{ "id": "start", "type": "startEvent", "name": "Invoice Received" },
{ "id": "review", "type": "userTask", "name": "Review Invoice",
"assignee": "approver" },
{ "id": "decision", "type": "exclusiveGateway", "name": "Approved?" },
{ "id": "approved", "type": "endEvent", "name": "Approved" },
{ "id": "rejected", "type": "endEvent", "name": "Rejected" }
],
"edges": [
{ "id": "flow1", "from": "start", "to": "review" },
{ "id": "flow2", "from": "review", "to": "decision" },
{ "id": "flow3", "from": "decision", "to": "approved",
"condition": "approved == true" },
{ "id": "flow4", "from": "decision", "to": "rejected",
"condition": "approved == false" }
]
}
The JSON version is roughly half the size, easier to read, and maps naturally to the data structures a frontend or runtime engine works with. The trade-off is that there is no universal schema, so interoperability between tools is not guaranteed.
XML vs JSON: Side by Side
| Criterion | BPMN XML | BPMN JSON |
|---|---|---|
| Standardisation | OMG specification, widely adopted | No single standard, multiple conventions |
| Verbosity | High (namespaces, DI, metadata) | Low to moderate |
| Schema strictness | XSD validation, strict typing | Informal, tool-specific |
| Human readability | Cluttered, hard to diff | Clean, easy to diff in PRs |
| Browser/JS tooling | Requires XML parser, heavier | Native JSON, lighter |
| Tool interoperability | Excellent (Camunda, Flowable, etc.) | Limited, varies by vendor |
| CI/CD friendliness | Harder to generate programmatically | Trivial to generate and manipulate |
| Diagram layout (DI) | Embedded in the XML | Separate or auto-layout |
Learn More About Mermaid.js
Mermaid.js is an open-source diagramming tool that renders Markdown-inspired text definitions into SVGs. It supports flowcharts, sequence diagrams, Gantt charts, class diagrams, and more. The project is maintained on GitHub at github.com/mermaid-js/mermaid, with documentation, a live editor, and integrations for GitHub, Notion, and Confluence.
Practical Takeaways
If you need to exchange process models between different tools or maintain strict compliance with the BPMN 2.0 specification, use XML. It is the only format that every BPMN tool understands. This matters for enterprise projects where models move between modeling tools, simulation engines, and runtime execution environments.
If you are building a web application that renders or executes process models internally, JSON is often the better choice. It is easier to parse, generate, and version in a Git workflow. The diff between two JSON process definitions tells you exactly what changed, which is harder to spot in XML even with pretty-printing.
The pragmatic pattern I have seen work well is to store processes as JSON during development and convert to standard BPMN XML at export time. Tools like bpmn-js do this internally anyway -- the editor works with a JSON model and serialises to XML when saving. That gives you the best of both worlds: fast iteration and standards-compliant output.
The Bottom Line
The XML-to-JSON shift that has happened across REST APIs, config files, and data pipelines is also playing out in process modeling. XML remains the interchange standard and that is not changing any time soon. But for runtime execution, web tooling, and day-to-day development work, JSON-based BPMN representations are increasingly where the action is. Choose your format based on where the process spends most of its time: in transit between tools (XML) or in code being built and deployed (JSON).
The model itself matters more than how you serialise it, but the serialisation still matters a lot.