Evaluate & redesign the generated JSON model against BPMN domain-model standards

[emaarco]

Summary

The current JSON output (BpmnJsonGenerator) represents a BPMN process as a flat flowNodes list, where structure (nesting, boundary attachment, sequence flows) has to be reconstructed from string ID references between nodes. Before we lock down the JSON output as a stable, public format, we want to evaluate it against established BPMN domain models outside of XML and design an optimized schema.

Current state

Flat list, relationships as redundant ID references (previousElements + followingElements + separate top-level sequenceFlows), hierarchy only via parentId, boundary events via attachedToRef/attachedElements:

{
  "processId": "newsletterSubscription",
  "flowNodes": [
    {
      "id": "serviceTask_incrementSubscriptionCounter",
      "displayName": "Increment subscription counter",
      "elementType": "SERVICE_TASK",
      "attachedElements": ["CompensationEvent_OnSubscriptionCounter"],
      "previousElements": ["StartEvent_SubmitRegistrationForm"],
      "followingElements": ["SubProcess_Confirmation"],
      "properties": { "type": "ServiceTask", "implementationValue": "counterClass" }
    },
    {
      "id": "Timer_EveryDay",
      "elementType": "TIMER_BOUNDARY_EVENT",
      "parentId": "SubProcess_Confirmation",          // nesting
      "attachedToRef": "Activity_ConfirmRegistration", // attachment
      "followingElements": ["Activity_SendConfirmationMail"],
      "properties": { "type": "Timer", "timerType": "Duration", "timerValue": "PT1M" }
    }
    // ... + top-level: messages[], signals[], errors[], escalations[],
    //     compensations[], sequenceFlows[], variants[]
  ]
}

Suspected weaknesses (to be verified):

• Relationships encoded three times (previousElements, followingElements, top-level sequenceFlows) → redundancy / consistency risk.
• Nesting (sub-processes) is flat via parentId instead of a real tree structure.
• properties is a "grab bag" with many nullable fields (timer/message/signal mixed) instead of type-discriminated objects.
• Inconsistent reference containers (attachedToRef string vs. attachedElements list).

Desired state

1. Research: Collect & compare existing JSON / non-XML BPMN domain models — e.g. bpmn-moddle / bpmn-io moddle-JSON, camunda-bpmn-moddle, Zeebe / Camunda 8 REST deployment representations, possibly the internal bpmn-js model, element-templates schema.
2. Evaluation: Map our output against these models — what do they do better/differently for hierarchy, sequence flows, boundary attachment, event definitions?
3. Proposal: Design an optimized JSON schema as an ADR (create-adr skill), including migration impact (breaking?) and a rationale for why it represents a BPMN in a meaningful way.

Scope

• ✅ Research, comparison table, redesign proposal as an ADR.
• ❌ No implementation in this ticket — pure design spike.