govoplan-workflow/docs/BPMN_INTEROPERABILITY.md

BPMN Interoperability

GovOPlaN distinguishes BPMN notation and XML interchange from executable workflow semantics.

Current Contract

• GET /api/v1/workflow/bpmn/profile publishes the exact native support profile.
• POST /api/v1/workflow/bpmn/inspect safely parses bounded BPMN 2.0 XML, inventories every BPMN model element, detects duplicate IDs and selected dangling references, and classifies elements as interchange-only, natively mappable, or natively executable.
• XML entities, DTD-based expansion, oversized documents, and malformed roots are rejected.
• The native GovOPlaN graph remains the authoritative executable definition.

Inspection is not XML Schema validation and does not claim that every BPMN semantic construct can be executed. A future bpmn-js/bpmn-moddle adapter can provide complete visual notation and XML round-tripping without forcing unsupported elements into the native runner.

Execution Boundary

Adding a BPMN shape is not equivalent to implementing its token semantics, event subscriptions, compensation, transactions, choreography, or conformance behavior. Each executable mapping therefore needs:

1. an explicit native semantic mapping;
2. validation rules and lifecycle behavior;
3. resumability and idempotency tests;
4. migration and round-trip fixtures;
5. a declared fallback when the installed runtime cannot execute it.

Unsupported constructs remain visible and preserved by the future interchange adapter, but activation must remain blocked until an execution adapter declares support.