Part 5 of 1050% complete

2026-09-19•5 min read

Part 5: Validation as a first-class feature

A DSL that generates XML you only hope is valid is a code generator with a faith problem. Validation here is not a linter bolted on afterward — it is the stage that makes the DSL trustworthy, and it runs on the immutable AST before any XML exists. This part builds BpmnValidator, which returns structured diagnostics rather than throwing on the first problem.

Structured diagnostics

A diagnostic is data, not an exception. It carries enough to print a useful message and to feed an IDE-style report or a CI gate:

1
enum class Severity { ERROR, WARNING }
2

3
data class Diagnostic(
4
    /** Stable machine-readable code, e.g. "BPMN-FLOW-001". */
5
    val code: String,
6
    val severity: Severity,
7
    val message: String,
8
    /** Element the diagnostic is attached to. */
9
    val elementId: String? = null,
10
    /** Other elements involved, e.g. both ends of an unresolved reference. */
11
    val relatedIds: List<String> = emptyList(),
12
    /** Practical suggestion for fixing the problem. */
13
    val remediation: String? = null,
14
)

Stable codes matter more than polished messages: tests assert on codes, CI can suppress a specific warning, and documentation can reference BPMN-FLOW-001 without depending on prose. The distinction between ERROR (output would be invalid or undeployable) and WARNING (structurally legal but suspicious — unreachable node, boundary event with no handler) is what lets validation gate a build without crying wolf.

The shape of the validator

1
class BpmnValidator {
2

3
    fun validate(collaboration: CollaborationDefinition): List<Diagnostic> {
4
        val d = mutableListOf<Diagnostic>()
5
        validateIdentifiers(collaboration, d)
6
        for (process in collaboration.processes) {
7
            validateProcess(collaboration, process, d)
8
        }
9
        validateCollaboration(collaboration, d)
10
        return d.sortedWith(compareBy({ it.severity }, { it.code }, { it.elementId }))
11
    }
12
}

Deterministic ordering of diagnostics — same model, same list, same order — is a small discipline that pays off in tests and review diffs.

Identifier validation

BPMN ids are XML IDs: unique across the entire document, not just within a process. The check is a single pass over every id-bearing element:

1
private fun validateIdentifiers(c: CollaborationDefinition, d: MutableList<Diagnostic>) {
2
    val seen = LinkedHashMap<String, String>()
3

4
    fun check(id: String, kind: String) {
5
        if (id.isBlank()) { d += /* BLANK_ID error */; return }
6
        val previous = seen.putIfAbsent(id, kind)
7
        if (previous != null) {
8
            d += Diagnostic(
9
                DiagnosticCodes.DUPLICATE_ID, Severity.ERROR,
10
                "Duplicate id '$id' used by both $previous and $kind; " +
11
                    "BPMN ids are XML IDs and must be unique document-wide",
12
                elementId = id,
13
                remediation = "Rename one of the elements.",
14
            )
15
        }
16
    }
17

18
    check(c.id, "collaboration")
19
    c.participants.forEach { check(it.id, "participant") }
20
    c.processes.forEach { p ->
21
        check(p.id, "process")
22
        p.lanes.forEach { check(it.id, "lane") }
23
        p.allNodes().forEach { check(it.id, "flow node") }
24
        p.allSequenceFlows().forEach { check(it.id, "sequence flow") }
25
    }
26
    c.messages.forEach { check(it.id, "message") }
27
    c.messageFlows.forEach { check(it.id, "message flow") }
28
}

allNodes() and allSequenceFlows() — the flattened views that include subprocess contents — are what make document-wide uniqueness cheap to check.

Process validation: one pass per scope

validateScope runs once for the process and once for every embedded subprocess — the subprocess interior is a closed scope with its own start/end requirements:

1
private fun validateScope(
2
    scopeId: String,
3
    nodes: List<FlowNode>,
4
    flows: List<SequenceFlow>,
5
    d: MutableList<Diagnostic>,
6
) {
7
    val byId = nodes.associateBy { it.id }
8

9
    if (nodes.none { it is StartEvent }) d += /* NO_START_EVENT error */
10
    if (nodes.none { it is EndEvent })   d += /* NO_END_EVENT error */
11

12
    val outgoing = flows.groupBy { it.sourceRef }
13
    val incoming = flows.groupBy { it.targetRef }
14
    // …flow resolution, direction rules, reachability…
15
}

Reference resolution. A sequence flow whose endpoints don’t resolve within its own scope is an error — this also catches cross-scope smuggling, because a subprocess flow referencing a parent node won’t resolve in the subprocess’s byId map, and vice versa.

Direction rules. Start events can’t have incoming flows; end events can’t have outgoing; boundary events can’t have incoming (they’re entered via attachment) and should have outgoing — a boundary event with nowhere to send its token fires and discards.

1
for (n in nodes) {
2
    val out = outgoing[n.id].orEmpty()
3
    val inc = incoming[n.id].orEmpty()
4
    when (n) {
5
        is StartEvent -> if (inc.isNotEmpty()) d += directionError(n.id, "start event", "incoming")
6
        is EndEvent -> if (out.isNotEmpty()) d += directionError(n.id, "end event", "outgoing")
7
        is BoundaryEventNode -> {
8
            if (inc.isNotEmpty()) d += directionError(n.id, "boundary event", "incoming")
9
            if (out.isEmpty()) d += Diagnostic(
10
                DiagnosticCodes.BOUNDARY_NO_OUTGOING, Severity.WARNING,
11
                "Boundary event '${n.id}' has no outgoing sequence flow; it will fire and discard the token",
12
                elementId = n.id,
13
            )
14
        }
15
        else -> Unit
16
    }
17
}

Reachability. A node that no start event can reach is dead modeling — usually a forgotten edge. Computed by DFS over outgoing edges:

1
val reachable = mutableSetOf<String>()
2
val stack = ArrayDeque<String>()
3
fun drain() {
4
    while (stack.isNotEmpty()) {
5
        val cur = stack.removeLast()
6
        if (!reachable.add(cur)) continue
7
        outgoing[cur].orEmpty().forEach { stack.addLast(it.targetRef) }
8
    }
9
}
10
nodes.filterIsInstance<StartEvent>().forEach { stack.addLast(it.id) }
11
drain()
12
// Boundary events are entered via attachment, not sequence flow: they are
13
// reachable whenever their host activity is reachable.
14
nodes.filterIsInstance<BoundaryEventNode>()
15
    .filter { it.attachedToRef in reachable }
16
    .forEach { stack.addLast(it.id) }
17
drain()

Common pitfall: the first version of this pass seeded only start events, and every node downstream of a boundary event was flagged unreachable. Boundary events have no incoming edges by design — treat reachable hosts as reachability roots for their boundary events. The same two-pass trick works in reverse for “can reach an end event” (walk incoming backwards).

Gateway validation

Three checks encode gateway semantics:

1
if (g is ExclusiveGateway || g is InclusiveGateway) {
2
    g.defaultFlow?.let { def ->
3
        if (out.none { it.id == def }) {
4
            d += /* DEFAULT_FLOW_INVALID: default must name an outgoing flow */
5
        }
6
    }
7
    if (out.size > 1) {
8
        val undecided = out.filter { it.condition == null && it.id != g.defaultFlow }
9
        if (undecided.isNotEmpty()) d += /* MISSING_CONDITION warning */
10
    }
11
}
12
if (g is ParallelGateway) {
13
    val conditioned = out.filter { it.condition != null }
14
    if (conditioned.isNotEmpty()) d += /* CONDITION_FORBIDDEN error */
15
}

Conditions on outgoing flows are also checked at the edge level: BPMN permits conditionExpression only on flows leaving activities and exclusive/inclusive gateways. A conditioned flow leaving a parallel gateway is an error (the condition is silently ignored by engines — modeling intent that evaporates). Conditions leaving an event or a basic receive/send chain are equally invalid.

The limit worth stating: this validator does not simulate token semantics. It cannot prove that a complex net of inclusive joins never deadlocks — only that the obvious shapes (unreachable joins, starved defaults, conditioned parallel splits) are absent. Full token-flow verification is a model-checking problem; Part 10 lists it as an extension.

Lane and collaboration validation

Lanes check three things: every flowNodeRef resolves to a top-level node of the same process; no node claims membership in two lanes; and — by our layout convention — every top-level node is in a lane (warning, not error, because a laneless node is legal BPMN even if unrenderable in our layout). Boundary events are exempt from the lane rule: they render attached to their host and inherit its lane visually.

1
for (mf in c.messageFlows) {
2
    mf.messageRef?.let { ref ->
3
        if (ref !in messageIds) d += /* MSG_REF_UNRESOLVED */
4
    }
5
    val srcPool = participantOfNode[mf.sourceRef] ?: mf.sourceRef.takeIf { it in participantIds }
6
    val tgtPool = participantOfNode[mf.targetRef] ?: mf.targetRef.takeIf { it in participantIds }
7
    if (srcPool == null || tgtPool == null) d += /* MSG_FLOW_ENDPOINT: endpoint resolves to nothing */
8
    if (srcPool == tgtPool) d += Diagnostic(
9
        DiagnosticCodes.MSG_FLOW_SAME_POOL, Severity.ERROR,
10
        "Message flow '${mf.id}' connects two elements inside participant '$srcPool'; " +
11
            "message flows must cross participant boundaries (use a sequence flow inside one process)",
12
        elementId = mf.id, relatedIds = listOf(mf.sourceRef, mf.targetRef),
13
    )
14
}

Collaboration checks also reject gateways as message endpoints (a gateway can’t send or receive a message — it’s control flow, not a participant in one) and warn when no process is executable, which is legal BPMN but pointless for deployment.

Boundary and subprocess checks

1
when (val host = byId[b.attachedToRef]) {
2
    null -> d += /* BOUNDARY_TARGET: host doesn't exist in this scope */
3
    is ActivityNode -> Unit   // the only legal target
4
    else -> d += Diagnostic(
5
        DiagnosticCodes.BOUNDARY_TARGET, Severity.ERROR,
6
        "Boundary event '${b.id}' attaches to '${b.attachedToRef}', which is a ${host::class.simpleName}; " +
7
            "boundary events may only attach to activities (tasks and subprocesses)",
8
        elementId = b.id,
9
        remediation = "Attach the boundary event to an ActivityNode.",
10
    )
11
}

This is the check that makes Part 4’s design decision enforceable: attach a boundary timer to a catch event and you get BPMN-BND-001, not a corrupted diagram.

Diagram validation — a separate pass

validateDiagram(collaboration, layout) runs after layout and checks the DI half of the contract:

1
fun validateDiagram(c: CollaborationDefinition, layout: DiagramLayout): List<Diagnostic> {
2
    val d = mutableListOf<Diagnostic>()
3
    for (p in c.processes) {
4
        for (n in p.allNodes()) {
5
            val shape = layout.shapes[n.id]
6
                ?: run { d += /* DI_MISSING_SHAPE error */; continue }
7
            if (shape.width <= 0 || shape.height <= 0) d += /* DI_BAD_BOUNDS */
8
        }
9
        // lane ⊆ participant containment
10
        for (lane in p.lanes) {
11
            val laneBounds = layout.shapes[lane.id] ?: continue
12
            val poolBounds = participant?.let { layout.shapes[it.id] }
13
            if (poolBounds != null && !poolBounds.contains(laneBounds)) d += /* DI_LANE_OUTSIDE_POOL */
14
            for (ref in lane.flowNodeRefs) {
15
                val nodeBounds = layout.shapes[ref] ?: continue
16
                if (!laneBounds.contains(nodeBounds)) d += /* DI_NODE_OUTSIDE_LANE */
17
            }
18
        }
19
        // boundary event must touch its host's border
20
        for (b in p.allNodes().filterIsInstance<BoundaryEventNode>()) {
21
            val bs = layout.shapes[b.id]; val host = layout.shapes[b.attachedToRef]
22
            if (bs != null && host != null && !bs.intersects(host)) d += /* DI_BOUNDARY_DETACHED */
23
        }
24
        for (f in p.allSequenceFlows()) checkEdge(f.id, layout, d)
25
    }
26
    for (mf in c.messageFlows) checkEdge(mf.id, layout, d)
27
    return d
28
}

Every visible semantic node gets a shape; every sequence flow and message flow gets an edge with ≥2 waypoints. These are rendering invariants — a model can be semantically perfect and still open as a blank canvas without them.

Testing the validator — on purpose-broken models

The test suite proves detection, not just acceptance:

1
@Test
2
fun `conditions after a parallel gateway are rejected`() {
3
    val c = bpmnCollaboration("badPar") {
4
        participant("pool") {
5
            executable = true
6
            process("proc") {
7
                lane("work") {
8
                    startEvent("start"); parallelGateway("split")
9
                    serviceTask("a") {}; serviceTask("b") {}
10
                    parallelGateway("join"); endEvent("done")
11
                }
12
                sequenceFlow("f0", "start", "split")
13
                conditionalFlow("f1", "split", "a", "\${x}")
14
                sequenceFlow("f2", "split", "b")
15
                sequenceFlow("f3", "a", "join"); sequenceFlow("f4", "b", "join")
16
                sequenceFlow("f5", "join", "done")
17
            }
18
        }
19
    }
20
    assertTrue(DiagnosticCodes.CONDITION_FORBIDDEN in codes(c))
21
}
22

23
@Test
24
fun `message flows may not connect two nodes in the same pool`() { /* … MSG_FLOW_SAME_POOL … */ }

The boundary-attachment test is more interesting because the DSL can’t express the invalid case — that’s the point of the type system — so the test constructs the invalid AST directly:

1
@Test
2
fun `boundary events may not attach to events or gateways`() {
3
    val invalid = /* …a process whose "wait" is an IntermediateCatchMessageEvent… */
4
    val badNode = BoundaryTimerEvent(
5
        id = "badBoundary", attachedToRef = "wait",
6
        timer = TimerDefinition.duration("PT1H"),
7
    )
8
    val patched = invalid.copy(
9
        processes = listOf(proc.copy(nodes = proc.nodes + badNode)),
10
    )
11
    assertTrue(DiagnosticCodes.BOUNDARY_TARGET in codes(patched))
12
}

This is the honest division of labor: the DSL prevents invalid models at compile time; the validator catches the ones that can be expressed — wrong references, wrong endpoints, unresolved shapes — and the tests prove each one is actually caught.

Common pitfalls

Validating per-process only — subprocesses are their own scope; skipping their interior check lets a subprocess exist with no start event.
Warning fatigue — if everything is an error, nothing is. Reserve ERROR for invalid output; WARNING for “legal but probably not what you meant.”
Assertions instead of diagnostics — an assert/check thrown on the first problem reports one issue at a time. Collect all diagnostics so a single run prints every problem.
Only validating semantics — a model can be semantically valid and have a broken or missing diagram. Both halves need checks.

Reference implementation

BpmnValidator, Diagnostic, and the full DiagnosticCodes registry live in Validation.kt in the bpmn-validation module of pcnixsys/bpmn-dsl-kotlin. The procurement example validates with zero errors and zero warnings; the test suite carries a negative test per diagnostic family.

Part 6 writes the validated AST out as BPMN 2.0 XML using StAX — namespaces, incoming/outgoing bookkeeping, conditionExpression, event definitions, and the extension-element hook the Flowable adapter plugs into.

KotlinBPMN