Part 6 of 1060% complete

2026-09-20•4 min read

Part 6: Generating BPMN 2.0 XML safely from the AST

With a validated AST in hand, serialization is almost mechanical — which is the point. Every design decision was made upstream; this part is about writing XML correctly: no string concatenation, deterministic output, and a clean seam for engine-specific extensions.

Why StAX, not string templates

XMLStreamWriter (JDK built-in, javax.xml.stream) handles escaping, quoting, and namespace bookkeeping. String concatenation looks tempting for XML this regular — right up until a task name contains & or a condition expression contains <, and your “generator” ships malformed XML. StAX also streams: a 500-node process doesn’t materialize anything but the output characters.

The constraint StAX adds in non-repairing mode — where namespaces are written manually — is discipline: declare every prefix on the root once, write every element with an explicit (prefix, localName, namespace) triple, and the output is deterministic because nothing is inferred.

Namespaces and the definitions root

1
object BpmnNs {
2
    const val BPMN   = "http://www.omg.org/spec/BPMN/20100524/MODEL"
3
    const val BPMNDI = "http://www.omg.org/spec/BPMN/20100524/DI"
4
    const val DC     = "http://www.omg.org/spec/DD/20100524/DC"
5
    const val DI     = "http://www.omg.org/spec/DD/20100524/DI"
6
    const val XSI    = "http://www.w3.org/2001/XMLSchema-instance"
7
    const val FLOWABLE = "http://flowable.org/bpmn"
8
    const val CAMUNDA  = "http://camunda.org/schema/1.0/bpmn"
9
}

1
w.writeStartDocument("UTF-8", "1.0")
2
w.writeStartElement("bpmn", "definitions", BpmnNs.BPMN)
3
w.writeNamespace("bpmn", BpmnNs.BPMN)
4
w.writeNamespace("bpmndi", BpmnNs.BPMNDI)
5
w.writeNamespace("dc", BpmnNs.DC)
6
w.writeNamespace("di", BpmnNs.DI)
7
w.writeNamespace("xsi", BpmnNs.XSI)
8
w.writeNamespace("bpmndsl", "https://o612.in/bpmn/dsl")
9
for ((prefix, uri) in engine.namespaces()) {
10
    w.writeNamespace(prefix, uri)
11
}
12
w.writeAttribute("id", "${c.id}_definitions")
13
w.writeAttribute("name", c.name ?: c.id)
14
w.writeAttribute("targetNamespace", targetNamespace)

bpmndsl is the library’s own extension namespace — process variables serialize there. Engine namespaces come from the EngineExtensionSerializer (Part 9), so the writer emits xmlns:flowable only when the Flowable adapter is in use.

Document skeleton

BPMN’s definitions element is a flat container. Order of the major groups doesn’t affect validity, but a fixed order makes output diffable:

1
writeMessages(c, w)          // <bpmn:message> declarations
2
writeErrors(c, w)            // <bpmn:error> for errorEventDefinition refs
3
writeCollaboration(c, w)     // participants + message flows
4
for (p in c.processes) {
5
    writeProcess(c, p, w)    // executable and non-executable processes
6
}
7
if (layout != null) {
8
    writeDiagram(c, layout, w)   // Part 7
9
}

1
<bpmn:message id="rfqRequested"/>
2
<bpmn:message id="supplierQuotationReceived"/>
3
<bpmn:collaboration id="enterpriseProcurement" name="Enterprise Procurement and Supplier Onboarding">
4
    <bpmn:participant id="buyerOrganization" name="Buyer Organization" processRef="buyerProcurementProcess"/>
5
    <bpmn:participant id="supplier" name="Supplier" processRef="supplierInteractionProcess"/>
6
    <bpmn:messageFlow id="msgRfqToSupplier" sourceRef="sendRfq" targetRef="receiveRfq" messageRef="rfqRequested"/>
7
    <!-- …six more message flows… -->
8
</bpmn:collaboration>

Process: laneSet before flow elements

Inside <bpmn:process>, the schema sequence places laneSet ahead of flowElements. The writer emits documentation, the variables extension, the lane set, then nodes and flows:

1
w.writeStartElement("bpmn", "process", BpmnNs.BPMN)
2
w.writeAttribute("id", p.id)
3
p.name?.let { w.writeAttribute("name", it) }
4
w.writeAttribute("isExecutable", p.isExecutable.toString())
5
writeDoc(p.documentation, w)
6
writeProcessVariables(p, w)
7
writeLaneSet(p, w)
8
writeScopeNodes(p.nodes, p.sequenceFlows, w)
9
writeScopeFlows(p.sequenceFlows, w)
10
w.writeEndElement()

1
<bpmn:process id="buyerProcurementProcess" name="Buyer Procurement Process" isExecutable="true">
2
    <bpmn:extensionElements>
3
        <bpmndsl:processVariables>
4
            <bpmndsl:variable name="requisitionId" type="string" required="true"/>
5
            <!-- … -->
6
        </bpmndsl:processVariables>
7
    </bpmn:extensionElements>
8
    <bpmn:laneSet id="buyerProcurementProcess_laneSet">
9
        <bpmn:lane id="requestingDepartment" name="Requesting Department">
10
            <bpmn:flowNodeRef>requisitionCreated</bpmn:flowNodeRef>
11
            <bpmn:flowNodeRef>submitRequisition</bpmn:flowNodeRef>
12
            <bpmn:flowNodeRef>correctRequisition</bpmn:flowNodeRef>
13
        </bpmn:lane>
14
        <!-- …five more lanes… -->
15
    </bpmn:laneSet>

The node writer — the one function that does the mapping

Every flow node serializes through a single when on the sealed hierarchy — adding a node type without updating the writer is a compile error, which is exactly what when exhaustiveness buys you:

1
val tag = when (n) {
2
    is StartEvent -> "startEvent"
3
    is EndEvent -> "endEvent"
4
    is IntermediateCatchMessageEvent -> "intermediateCatchEvent"
5
    is BoundaryEventNode -> "boundaryEvent"
6
    is UserTask -> "userTask"
7
    is ServiceTask -> "serviceTask"
8
    is ReceiveTask -> "receiveTask"
9
    is SendTask -> "sendTask"
10
    is EmbeddedSubprocess -> "subProcess"
11
    is ExclusiveGateway -> "exclusiveGateway"
12
    is ParallelGateway -> "parallelGateway"
13
    is InclusiveGateway -> "inclusiveGateway"
14
    is EventBasedGateway -> "eventBasedGateway"
15
}
16
w.writeStartElement("bpmn", tag, BpmnNs.BPMN)
17
w.writeAttribute("id", n.id)
18
n.name?.let { w.writeAttribute("name", it) }
19
if (n is BoundaryEventNode) {
20
    w.writeAttribute("attachedToRef", n.attachedToRef)
21
    if (!n.cancelActivity) w.writeAttribute("cancelActivity", "false")
22
}
23
if (n is ReceiveTask) n.messageRef?.let { w.writeAttribute("messageRef", it) }
24
if (n is SendTask)    n.messageRef?.let { w.writeAttribute("messageRef", it) }
25
if (n is ExclusiveGateway || n is InclusiveGateway) {
26
    n.defaultFlow?.let { w.writeAttribute("default", it) }
27
}
28
for ((k, v) in engine.elementAttributes(n)) { /* vendor attrs, Part 9 */ }

incoming/outgoing bookkeeping

BPMN flow elements redundantly declare their edges — <bpmn:incoming>/<bpmn:outgoing> children repeat what sourceRef/targetRef on the flows already say. Engines don’t need them; strict tools warn without them. The writer derives them rather than trusting the author:

1
val incoming = flows.filter { it.targetRef == n.id }
2
val outgoing = flows.filter { it.sourceRef == n.id }
3
// …
4
for (f in incoming) { w.writeStartElement("bpmn","incoming",BpmnNs.BPMN); w.writeCharacters(f.id); w.writeEndElement() }
5
for (f in outgoing) { w.writeStartElement("bpmn","outgoing",BpmnNs.BPMN); w.writeCharacters(f.id); w.writeEndElement() }

Redundancy that is computed, never authored, cannot drift out of sync.

Event definitions

Event definitions are nested elements that turn a generic element into a typed event — <bpmn:boundaryEvent> plus <bpmn:timerEventDefinition> is a timer boundary event; plus messageEventDefinition is a message boundary event:

1
is BoundaryTimerEvent -> {
2
    w.writeStartElement("bpmn", "timerEventDefinition", BpmnNs.BPMN)
3
    w.writeAttribute("id", "${n.id}_timer")
4
    writeTimerBody(n.timer, w)
5
    w.writeEndElement()
6
}

1
private fun writeTimerBody(t: TimerDefinition, w: XMLStreamWriter) {
2
    val (tag, value) = when {
3
        t.duration != null -> "timeDuration" to t.duration
4
        t.cycle    != null -> "timeCycle"    to t.cycle
5
        else               -> "timeDate"     to t.date
6
    }
7
    w.writeStartElement("bpmn", tag, BpmnNs.BPMN)
8
    w.writeAttribute("xsi", BpmnNs.XSI, "type", "bpmn:tFormalExpression")
9
    w.writeCharacters(value!!)
10
    w.writeEndElement()
11
}

1
<bpmn:boundaryEvent id="quotationSlaExceeded" name="72h supplier SLA" attachedToRef="waitForQuotation">
2
    <bpmn:outgoing>flowSlaToReminder</bpmn:outgoing>
3
    <bpmn:timerEventDefinition id="quotationSlaExceeded_timer">
4
        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">PT72H</bpmn:timeDuration>
5
    </bpmn:timerEventDefinition>
6
</bpmn:boundaryEvent>

Condition expressions

1
f.condition?.let { cond ->
2
    w.writeStartElement("bpmn", "conditionExpression", BpmnNs.BPMN)
3
    w.writeAttribute("xsi", BpmnNs.XSI, "type", "bpmn:tFormalExpression")
4
    if (cond.language != "juel") w.writeAttribute("language", cond.language)
5
    w.writeCharacters(cond.body)
6
    w.writeEndElement()
7
}

1
<bpmn:sequenceFlow id="flowBudgetBranch" name="budget approval" sourceRef="approvalsSplit" targetRef="approveBudget">
2
    <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">${budgetApprovalRequired}</bpmn:conditionExpression>
3
</bpmn:sequenceFlow>

The extension seam

EngineExtensionSerializer is the one seam through which vendor-specific output enters otherwise-standard XML:

1
interface EngineExtensionSerializer {
2
    fun namespaces(): Map<String, String> = emptyMap()
3
    fun elementAttributes(node: FlowNode): Map<String, String> = emptyMap()
4
    fun extensionElements(node: FlowNode): List<ExtensionElement> = emptyList()
5
    object None : EngineExtensionSerializer
6
}

The writer consults it in three places: extra xmlns: declarations on definitions, prefixed attributes on each node element (flowable:candidateGroup="procurement-officers"), and children inside <bpmn:extensionElements> (for structured extensions like flowable:field). ExtensionElement itself serializes recursively — prefix, local name, attributes, children, text:

1
private fun writeExtensionElement(e: ExtensionElement, w: XMLStreamWriter) {
2
    if (e.prefix != null) {
3
        val ns = engine.namespaces()[e.prefix]
4
            ?: error("Extension prefix '${e.prefix}' has no registered namespace")
5
        w.writeStartElement(e.prefix, e.name, ns)
6
    } else {
7
        w.writeStartElement("bpmn", e.name, BpmnNs.BPMN)
8
    }
9
    for ((k, v) in e.attributes) w.writeAttribute(k, v)
10
    e.text?.let { w.writeCharacters(it) }
11
    e.children.forEach { writeExtensionElement(it, w) }
12
    w.writeEndElement()
13
}

The error() on an unknown prefix is deliberate fail-fast: a malformed namespace is worse than a crash at authoring time.

Determinism

Everywhere the writer iterates, it iterates the AST’s declaration order — LinkedHashMap and List preserve it end to end. Running the writer twice on the same input produces byte-identical output, which Part 8 turns into a test. This is not a nice-to-have: diffs of generated XML are how generated workflows get reviewed.

Verification

bpmn-moddle — the parser that backs bpmn-js — reads the generated file with zero warnings. More meaningfully for correctness: BPMN semantic XML without DI is deployable but renders as a blank canvas; with DI it both deploys and draws. That requires Part 7.

Common pitfalls

Writing attachedToRef on the activity instead of the boundary event — the attribute belongs to the boundaryEvent element pointing at its host.
Skipping incoming/outgoing — some strict parsers warn or reject; compute them from the flow list.
String-concatenated XML — first & in a label and the file is malformed. Use a real writer.
Declaring xmlns:flowable unconditionally — emit engine namespaces only when the adapter actually uses them.
Emitting nodes and flows interleaved with laneSet — laneSet precedes flowElements in the schema.

Reference implementation

The StAX writer — BpmnNs, the Xml element wrapper, EngineExtensionSerializer, and writeToString — is BpmnXmlWriter.kt in the bpmn-xml module of pcnixsys/bpmn-dsl-kotlin.

The semantic XML alone would open in a viewer as nothing — all structure, no coordinates. Part 7 builds the layout engine that produces BPMN DI: columns from longest-path layering, rows from lanes, boundary events pinned to their hosts, and orthogonal edge routing — deterministic, complete, and honest about its limits.

KotlinBPMN