@bpmn-ld/bpmn-ld 0.0.0-stage → 0.1.0

package/skills/bpmn-ld/references/patterns.md

@@ -0,0 +1,292 @@
+# Process patterns
+
+One worked example per common pattern. Every example is valid BPMN-LD and has no analyzer findings. Copy the closest one and adapt it. Rule identifiers are those of the analyzer; the full catalogue is `docs/conventions/process-analysis.md`.
+
+## Parallel branches
+
+Use a diverging `ParallelGateway` to start branches that all run, and a converging `ParallelGateway` to wait for all of them. Worked example: `examples/positive/parallel-branches.jsonld`.
+
+Set `gatewayDirection` to `Diverging` on the split and `Converging` on the join.
+
+### Common mistakes
+
+- Joining parallel branches with an `ExclusiveGateway`: `split-join-parallel-to-exclusive` (warning), the flow after the join runs once per branch.
+- A split with fewer than two outgoing flows: `gateway-diverging-too-few-outgoing` (error).
+- A join with fewer than two incoming flows: `gateway-converging-too-few-incoming` (error).
+
+## Exclusive choices
+
+Use an `ExclusiveGateway` to take exactly one branch. Put a `conditionExpression` on all but one outgoing flow and name the remaining flow in the gateway's `default`. Merge the branches with a converging `ExclusiveGateway`. Worked example: `examples/positive/exclusive-choice.jsonld`.
+
+### Common mistakes
+
+- Merging exclusive branches with a `ParallelGateway`: `split-join-exclusive-to-parallel` (warning), the join waits for a token that never arrives.
+- A split with a single outgoing flow: `gateway-diverging-too-few-outgoing` (error).
+- A branch that ends in a task with no outgoing flow: `node-dead-end` (warning). Route it to the merge or to an end event.
+
+## Loops
+
+Model a loop with a converging `ExclusiveGateway` in front of the repeated work and a diverging `ExclusiveGateway` after it whose default flow goes back to the converging gateway. The other flow must lead out of the loop. Worked example: `examples/positive/loop.jsonld`.
+
+### Common mistakes
+
+- A loop with no exit flow: `node-cannot-reach-end` (warning), the tasks in the loop can never complete.
+- An entry gateway that only has the loop-back flow incoming: `gateway-converging-too-few-incoming` (error). It also needs the flow from the start.
+
+## Sub-processes
+
+Use a `SubProcess` with its own nested `flowElements`, including its own start and end event. Connect it to the outer flow like a task. Sequence flows must not cross the sub-process boundary. Worked example: `examples/positive/sub-process.jsonld`.
+
+### Common mistakes
+
+- A sub-process without a start event: `start-event-missing` (error), reported on the sub-process.
+- A sub-process without an end event: `end-event-missing` (warning).
+
+## Boundary events
+
+Use a `BoundaryEvent` with `attachedToRef` naming the host activity and an event definition such as `TimerEventDefinition`. Give it an outgoing flow for the exceptional path. The host keeps its normal outgoing flow. Worked example: `examples/positive/boundary-event.jsonld`.
+
+### Common mistakes
+
+- A boundary event with no outgoing flow: `node-dead-end` (warning).
+- Attaching the boundary event to a host that is itself unreachable: `node-unreachable` (warning).
+- A boundary event whose `attachedToRef` names an element that does not exist: `structural-validity` (error).
+- A boundary event with no `attachedToRef` at all is not attached to any host: `node-unreachable` (warning).
+
+## Event sub-processes
+
+Use a `SubProcess` with `triggeredByEvent` set to `true` for work that reacts to an event while the surrounding scope is running. It has no incoming or outgoing sequence flow. Inside it, the start event carries the trigger in `eventDefinitions` and `isInterrupting`: `true` stops the surrounding scope when the event occurs, `false` lets it continue and runs the event sub-process beside it. `isInterrupting` defaults to `true`. Use `parallelMultiple` set to `true` on a catch event with several event definitions only when all of them must occur; without it any one of them triggers the event. Worked example: `examples/positive/event-sub-process.jsonld`.
+
+### Common mistakes
+
+- A start event with `isInterrupting` set to `false` outside an event sub-process, for example because `triggeredByEvent` is missing from the sub-process: `non-interrupting-start-outside-event-sub-process` (warning).
+- A sequence flow into or out of an event sub-process: it is rejected by the SHACL shapes, so connect nothing to it.
+- An event sub-process without a start event: `start-event-missing` (error).
+
+## Instantiating gateways
+
+Use an `EventBasedGateway` with `instantiate` set to `true` when a process is started by whichever of several events occurs first, for example one of two different messages. Leave out the start event and give the gateway no incoming sequence flow; its outgoing flows go to the catch events that can start the process. `eventGatewayType` is `Exclusive` by default, where the first event wins, and `Parallel` when all following events must occur. A `ReceiveTask` with `instantiate` set to `true` and no incoming flow starts a process when its message arrives. `instantiate` defaults to `false`. Such a process needs no `StartEvent`, so `start-event-missing` is not reported for it. Worked example: `examples/positive/instantiating-gateway.jsonld`.
+
+### Common mistakes
+
+- A start event left in front of an instantiating gateway, so the gateway has an incoming flow: `instantiating-gateway-with-incoming-flow` (error).
+- `instantiate` set on a gateway or receive task in the middle of the flow: it then has an incoming flow and raises the same error; set `instantiate` to `false` or remove it.
+- A process with neither a start event nor an instantiating element: `start-event-missing` (error).
+
+## Script tasks
+
+Use a `ScriptTask` for automatic work that a process engine does by running a short script. Put the script text in `script` and name its language in `scriptFormat`, for example `text/javascript` or `groovy`; both are plain strings, both are optional, and neither is checked against the other. The script is text only: keep it short, and use a `ServiceTask` when the work is a call to another system. Both properties belong to `ScriptTask` only; the schema rejects them on other task types. Worked example: `examples/positive/script-task.jsonld`.
+
+### Common mistakes
+
+- `script` or `scriptFormat` on a `UserTask` or `ServiceTask`: the schema rejects them, so change the type to `ScriptTask`.
+- A script task with no outgoing sequence flow: `node-dead-end` (error).
+- A process whose only entry is the script task, without a start event: `start-event-missing` (error).
+
+## Task implementation
+
+Set `implementation` on a `ServiceTask`, `SendTask`, `ReceiveTask`, `UserTask` or `BusinessRuleTask` to name the technology that carries out the task. It is a plain string: a URI such as `http://example.org/forms/review`, or one of the BPMN values `##WebService` and `##unspecified`. Leave it out when the technology is not known; do not write the BPMN default, because an absent `implementation` already means it. Do not put the implementation in the `name`. Worked example: `examples/positive/task-implementation.jsonld`.
+
+### Common mistakes
+
+- `implementation` on a `ManualTask`, `ScriptTask` or plain `Task`: the schema rejects it, so change the type to one of the five task types.
+- `implementation` given as a boolean or a number: it must be a string.
+- A task with no outgoing sequence flow: `node-dead-end` (error).
+- A process without a start event: `start-event-missing` (error).
+
+## Process attributes
+
+Set `processType` on a `Process` to `Public` for a process that shows only its interactions with other participants, `Private` for one that shows its internal behavior, or leave it out when the process is not classified. It is written as a bare term, not a string with a namespace. Set `isExecutable` to `true` when an engine is meant to run the process and to `false` when it only documents the work. Set `isClosed` to `true` on a `Process` or a `Collaboration` that allows only the modelled interactions. Leave out `processType` and `isClosed` when they have their defaults, `None` and `false`: absence already means them. These attributes belong to `Process` and `Collaboration`, not to `SubProcess` or `Participant`. Worked example: `examples/positive/process-attributes.jsonld`.
+
+### Common mistakes
+
+- `processType` other than `None`, `Public` or `Private`, such as `"Sideways"`: the schema rejects it.
+- `isExecutable` or `isClosed` written as the string `"true"`: it must be a JSON boolean.
+- `processType` or `isExecutable` on a `SubProcess` or a `Collaboration`: the schema rejects it.
+- A process without a start event: `start-event-missing` (error).
+- A message flow that points to a missing node: `structural-validity` (error).
+
+## Ad-hoc sub-processes
+
+Use an `AdHocSubProcess` for a set of activities that are done in an order decided while the work runs, until a condition says the work is complete. Put the activities in its `flowElements` without a start event, an end event or sequence flows between them; sequence flows are only for the few activities that must follow each other. Set `ordering` to `Parallel` when several activities may run at the same time or to `Sequential` when only one runs at a time; both are bare terms. Put the condition that ends the sub-process in `completionCondition`, a `FormalExpression` with a `body` and optionally a `language`. `cancelRemainingInstances` is `true` by default, so activities still running when the condition holds are cancelled; set it to `false` to let them finish. The sub-process itself sits in the flow of its parent like any other activity. `ordering`, `completionCondition` and `cancelRemainingInstances` belong to `AdHocSubProcess` only; the schema rejects them on a `SubProcess`. Worked example: `examples/positive/ad-hoc-sub-process.jsonld`.
+
+### Common mistakes
+
+- An ad-hoc sub-process without a `completionCondition`: `ad-hoc-completion-condition-missing` (warning).
+- `ordering` other than `Parallel` or `Sequential`, such as `"Random"`: the schema rejects it.
+- `cancelRemainingInstances` written as the string `"false"`: it must be a JSON boolean.
+- A `completionCondition` written as a plain string instead of a `FormalExpression` object: the schema rejects it.
+- A start event or end event added inside the ad-hoc sub-process because it was modelled like a regular sub-process; they are not needed, and a regular `SubProcess` is the better choice when the order is fixed.
+- A process around the ad-hoc sub-process without a start event: `start-event-missing` (error).
+
+## Transactions
+
+Use a `Transaction` for a set of activities that either complete together or are undone together. It is a sub-process, so it holds its own `flowElements`, needs its own start event and end event with sequence flows between its content, and sits in the flow of its parent like any other activity. Set `method` to say how its effects are undone: `Compensate`, `Image` or `Store`, all bare terms. `Compensate` is the default and is assumed when `method` is absent, so write it only when you want it stated. `method` belongs to `Transaction` only; the schema rejects it on a `SubProcess`. Worked example: `examples/positive/transaction.jsonld`.
+
+### Common mistakes
+
+- `method` other than `Compensate`, `Image` or `Store`, such as `"Rollback"` or the XML form `"##Store"`: the schema rejects it.
+- `method` written on a `SubProcess` or `AdHocSubProcess`: the schema rejects it.
+- A transaction without a start event: `start-event-missing` (error).
+- A transaction without an end event: `end-event-missing` (warning).
+
+## Activity compensation
+
+Use a compensation activity to undo the work of a completed activity. Mark the undo activity with `isForCompensation` set to `true`, attach a `BoundaryEvent` with a `CompensateEventDefinition` to the activity that is undone, and link the two with an `Association` in the `artifacts` of the same process or sub-process: `sourceRef` is the boundary event, `targetRef` is the compensation activity, and `associationDirection` `One` draws the arrowhead. A compensation activity has no incoming or outgoing sequence flows; the association is what triggers it. `startQuantity` and `completionQuantity` are optional non-negative integers on any activity (task, sub-process, ad-hoc sub-process or transaction) and both default to 1; write them only when they differ from 1 or you want them stated. Worked example: `examples/positive/activity-compensation.jsonld`.
+
+### Common mistakes
+
+- A compensation activity with `isForCompensation` but no association to it, or an association that points at another activity: `compensation-activity-without-association` (warning).
+- A sequence flow into or out of a compensation activity, instead of an association from the boundary event.
+- The association written in `flowElements` instead of `artifacts`: the schema rejects it.
+- `isForCompensation` as a string such as `"yes"`, or a quantity that is negative, fractional or a string: the schema rejects it.
+- `startQuantity` or `completionQuantity` on an event or gateway: the schema rejects it.
+- A process without a start event: `start-event-missing` (error).
+
+## Targeted compensation
+
+Use targeted compensation when a process has to undo one named, completed activity on purpose, and not only when an error handler runs. Set up the compensation as in Activity compensation: the activity that is undone has a compensation `BoundaryEvent` and an `Association` in `artifacts` from that boundary event to the compensation activity (`isForCompensation` set to `true`). Then add an `IntermediateThrowEvent` or an `EndEvent` with a `CompensateEventDefinition` in the normal flow and give the definition `activityRef`, a plain id string of the activity to compensate, such as `"activityRef": "BookHotel"`. Set `waitForCompletion` to `true` when the process must wait until the compensation has finished before it continues; leave it out for the default. `activityRef` belongs on the `CompensateEventDefinition` of the throw event, not on the boundary event, and it names the activity that is undone, not the compensation activity and not the boundary event. A definition names at most one activity, and the id must be that of an activity (a task, sub-process, ad-hoc sub-process or transaction) in the same document. A throw event with a `CompensateEventDefinition` and no `activityRef` compensates every completed activity of its scope. Worked example: `examples/positive/targeted-compensation.jsonld`.
+
+### Common mistakes
+
+- A compensation activity with `isForCompensation` but no association from the compensation boundary event: `compensation-activity-without-association` (warning).
+- `activityRef` that names an id nobody defines, or the id of an event, gateway or flow: `structural-validity` (error).
+- `activityRef` written as a list, so that one throw event definition names two activities: the shapes reject it; use one throw event per activity.
+- `activityRef` written on a signal event definition, a task or any element other than a compensate event definition: the schema rejects it.
+- A process without a start event: `start-event-missing` (error).
+
+## Link events
+
+Use a link event pair as an off-page connector inside one process: a throw event passes control to a catch event without a sequence flow between them, which keeps a large diagram free of crossing lines. Give the throw event an `IntermediateThrowEvent` and the catch event an `IntermediateCatchEvent`, each with a `LinkEventDefinition`, and give every link event definition an `id` and the same `name`: the name is what pairs them. Then connect them by id. The throw definition has `target`, a single id string of the catch definition. The catch definition has `source`, a list of the ids of the throw definitions that jump to it, such as `"source": ["LinkThrow_A", "LinkThrow_B"]`, so several throws can share one catch. Both properties refer to the `LinkEventDefinition` itself, not to the event that contains it, and the id must belong to a link event definition of the same document. A throw event has no outgoing sequence flow and a catch event has no incoming one. The analyzer does not follow link events yet, so a correctly linked pair still gives `node-dead-end` (warning) on each throw event and `node-cannot-reach-end` (warning) on the nodes before it; report them as expected and do not remove the link to silence them. Worked example: `examples/positive/link-event.jsonld`.
+
+### Common mistakes
+
+- `target` or `source` that names an event instead of its link event definition, or an id nobody defines: `structural-validity` (error).
+- A throw event without a matching catch event of the same `name`, or two catch events with the same name in one process: the exported XML fails `check-xml` in bpmnlint.
+- `target` written as a list: a throw definition has at most one target.
+- `source` written as a single string: it is always a list.
+- A process without a start event: `start-event-missing` (error).
+
+## Immediate flows and lane partitions
+
+Set `"isImmediate": true` on a `SequenceFlow` when the model says that no other activity of the process may happen between its source and its target; `false` states the opposite, and leaving it out says nothing. It is a boolean, not a string, and only a sequence flow has it. Lanes can carry the element that defines their partition. `partitionElement` is a nested node on a `Lane`: give it an `id` and a concrete `type` such as `Participant`, and keep it to the `id`, because the exported XML names its class with `xsi:type` and bpmn-moddle reads it as a plain base element. `partitionElementRef` is the id of any element of the same document, for example the `partitionElement` of an enclosing lane, so a nested lane can say that it refines the partition of its parent. A lane has at most one of each, and a reference to an id that no node defines is not checked by BPMN-LD, so name only ids that exist. `examples/positive/lane-partition.jsonld` shows two immediate flows, a flow that states nothing, a lane with a `partitionElement` and a nested lane that refers to it.
+
+### Common mistakes
+
+- `isImmediate` as a string such as `"yes"`, or on an element that is not a sequence flow: the schema rejects it.
+- `partitionElement` or `partitionElementRef` on anything but a `Lane`, or `partitionElement` written as an id string: the schema rejects it.
+- `partitionElement` with a `type` that is not a BPMN-LD class, or written without a `type`: the schema rejects it.
+- Two partition elements or two partition references on one lane: SHACL reports it.
+- `partitionElement` with more properties than `id`: the exported XML is valid but bpmn-moddle reports an unknown attribute.
+- A process without a start event: `start-event-missing` (error).
+
+## Diagram properties
+
+A model that carries its own diagram uses the diagram context next to the core context, `"contexts/di.jsonld"`, and a `BPMNDiagram` node in `@graph` that points to its process or collaboration through its plane. A `BPMNDiagram` may have a `name` string and a `resolution`, a number in dots per inch. A `BPMNEdge` may have `messageVisibleKind`, `"initiating"` or `"non_initiating"`, the bare terms of a closed set, to say which message of a choreography task the edge shows. All three are optional and say nothing when left out. Layout never adds them. It leaves a diagram that has them unchanged, completes a partial one around them, and with `--force` carries the `name` and `resolution` of the first diagram and the `messageVisibleKind` of each edge whose element still exists over to the new diagram. Worked example: `examples/positive/diagram-properties.jsonld`.
+
+### Common mistakes
+
+- `messageVisibleKind` other than `"initiating"` or `"non_initiating"`, such as `"both"`, or a boolean: the schema rejects it.
+- `messageVisibleKind` on a `BPMNShape` or `BPMNPlane`: the schema rejects it.
+- `resolution` as a string such as `"high"`, or on a `BPMNPlane`: the schema rejects it.
+- `name` as a number, or on a `BPMNPlane`: the schema rejects it.
+- Two names, two resolutions or two message visible kinds: SHACL reports it.
+- A process without a start event: `start-event-missing` (error).
+- A message flow that names an element that does not exist: `structural-validity` (error).
+
+## Multiple participants
+
+Use a `Collaboration` with one `Participant` per party, each pointing to its own `Process` through `processRef`, and `messageFlows` between send-type nodes and receive-type nodes of different processes. Put the collaboration and the processes in `@graph`. Each process has its own start event; a process started by a message uses a start event with a `MessageEventDefinition`. Message flows are not sequence flows and never replace them. Worked example: `examples/positive/collaboration.jsonld`.
+
+### Common mistakes
+
+- A process in the collaboration without a start event: `start-event-missing` (error), reported on that process. This only applies when no message flow targets the start event; removing a start event that a message flow targets is a dangling reference and gives `structural-validity` (error) instead.
+- A message flow whose `sourceRef` or `targetRef` does not resolve: `structural-validity` (error).
+
+## Messages
+
+Use a `Message` for the content that two participants exchange, and refer to it from the message flow that carries it and from the message event definitions that send or receive it. A `Message` is a root element: it is a top-level node in `@graph`, next to the collaboration and the processes, with an `id` and an optional `name`. It is never nested inside a process or a collaboration. Refer to it by its id with `messageRef` on a `MessageFlow` or on a `MessageEventDefinition`, as a plain string such as `"messageRef": "Message_Order"`. A flow or event definition names at most one message, and the id must be that of a `Message` defined in the same document. `Message` also takes `itemRef` and `MessageEventDefinition`, `SendTask`, `ReceiveTask` and `ServiceTask` take `operationRef`, the ids of an item definition and of an operation; neither is modelled yet, so they are not checked and the exported XML then contains a reference that bpmn-moddle cannot resolve, so leave them out unless the user asks for them. Worked example: `examples/positive/message.jsonld`.
+
+### Common mistakes
+
+- A `Message` nested inside a process or collaboration instead of standing in `@graph`: the schema rejects it.
+- `messageRef` that names an id nobody defines, or the id of a task or event: `structural-validity` (error).
+- `messageRef` written on a user task, a sequence flow or any other element that does not take it: the schema rejects it. Send and receive tasks take it, see Message references on tasks.
+- A process without a start event: `start-event-missing` (error).
+
+## Message references on tasks
+
+Use `messageRef` on a `SendTask` or a `ReceiveTask` to say which `Message` the task sends or receives. The value is the id of a `Message` defined in the same document, a plain string such as `"messageRef": "Message_Order"`, and a task names at most one message. The message normally travels on a message flow of the collaboration, so write the matching `MessageFlow` too: a send task is the `sourceRef` of a message flow with the same `messageRef`, and a receive task is its `targetRef`. A message flow without a `messageRef` also matches. A receive task that starts a process has `instantiate` set to `true` and needs no start event. `operationRef` is accepted on `SendTask`, `ReceiveTask` and `ServiceTask`, but operations are not modelled yet, so the reference is not checked and the exported XML then contains an `operationRef` that bpmn-moddle cannot resolve; leave it out unless the user asks for it. Worked example: `examples/positive/task-message-references.jsonld`.
+
+### Common mistakes
+
+- A send or receive task with a `messageRef` and no message flow that leaves it (send) or enters it (receive) and carries that message: `task-message-without-message-flow` (warning). Add the message flow, or correct the `messageRef` of the flow or the task so that they name the same message.
+- `messageRef` that names an id nobody defines, or the id of a task or event: `structural-validity` (error).
+- `messageRef` written on a service task, a user task or a script task: the schema rejects it.
+- `operationRef` written on a user task or a script task: the schema rejects it.
+- A process without a start event, unless a receive task with `instantiate` starts it: `start-event-missing` (error).
+
+## Signals
+
+Use a `Signal` for a broadcast that one process throws and any number of processes catch. A `Signal` is a root element: it is a top-level node in `@graph`, next to the collaboration and the processes, with an `id` and an optional `name`. It is never nested inside a process. Refer to it by its id with `signalRef` on every `SignalEventDefinition`, as a plain string such as `"signalRef": "Signal_Shipped"`. An event definition names at most one signal, and the id must be that of a `Signal` defined in the same document. A signal is thrown by an `IntermediateThrowEvent` or an `EndEvent` and caught by a `StartEvent`, an `IntermediateCatchEvent` or a `BoundaryEvent`; the catch event may be in another process. Give the throw and the catch event definitions the same `signalRef`. `Signal` also takes `structureRef`, the id of an item definition; item definitions are not modelled yet, so it is not checked and the exported XML then contains a reference that bpmn-moddle cannot resolve, so leave it out unless the user asks for it. Worked example: `examples/positive/signal.jsonld`.
+
+### Common mistakes
+
+- A signal throw event whose `signalRef` no start, intermediate catch or boundary event references: `signal-throw-without-catch` (warning). Add the catch event with the same `signalRef`, or correct the `signalRef` of the existing one. A throw or catch event whose signal event definition has no `signalRef` is not checked and matches nothing, so always write it.
+- A `Signal` nested inside a process or collaboration instead of standing in `@graph`: the schema rejects it.
+- `signalRef` that names an id nobody defines, or the id of a task or event: `structural-validity` (error).
+- `signalRef` written on a message event definition or any element other than a signal event definition: the schema rejects it.
+- A process without a start event, unless a signal start event starts it: `start-event-missing` (error).
+
+## Errors
+
+Use an `Error` for a business failure that an end event throws and a boundary event or an event sub-process start event handles. An `Error` is a root element: it is a top-level node in `@graph`, next to the processes, with an `id`, an optional `name` and an optional `errorCode` (a string). It is never nested inside a process. Refer to it by its id with `errorRef` on every `ErrorEventDefinition`, as a plain string such as `"errorRef": "Error_PaymentFailed"`. An event definition names at most one error, and the id must be that of an `Error` defined in the same document. Write `errorCode` on the `Error`, not on the event definition. An error is thrown by an `EndEvent` and caught by a `BoundaryEvent` attached to the activity or sub-process that contains the throw, or by the `StartEvent` of an event sub-process (`triggeredByEvent` set to `true`). Give the throw and the catch event definitions the same `errorRef`. A catch event definition without an `errorRef` catches every error. `Error` also takes `structureRef`, the id of an item definition; item definitions are not modelled yet, so it is not checked and the exported XML then contains a reference that bpmn-moddle cannot resolve, so leave it out unless the user asks for it. Worked example: `examples/positive/error.jsonld`.
+
+### Common mistakes
+
+- An error end event whose `errorRef` no boundary event or event sub-process start event references: `error-throw-without-catch` (warning). Add the boundary event or the event sub-process with the same `errorRef`, or correct the `errorRef` of the existing one. The match is by id across the whole document. An end event whose error definition has no `errorRef` is not checked, so always write it; a catch event without an `errorRef` catches every error.
+- An `Error` nested inside a process or collaboration instead of standing in `@graph`: the schema rejects it.
+- `errorRef` that names an id nobody defines, or the id of a task or event: `structural-validity` (error).
+- `errorRef` written on a signal event definition or any element other than an error event definition: the schema rejects it.
+- A process without a start event: `start-event-missing` (error).
+
+## Escalations
+
+Use an `Escalation` for a situation that an intermediate throw event or an end event raises to a higher level and that a boundary event or an event sub-process start event handles. An `Escalation` is a root element: it is a top-level node in `@graph`, next to the processes, with an `id`, an optional `name` and an optional `escalationCode` (a string). It is never nested inside a process. Refer to it by its id with `escalationRef` on every `EscalationEventDefinition`, as a plain string such as `"escalationRef": "Escalation_ManagerReview"`. An event definition names at most one escalation, and the id must be that of an `Escalation` defined in the same document. Write `escalationCode` on the `Escalation`, not on the event definition. An escalation is thrown by an `IntermediateThrowEvent` or an `EndEvent` and caught by a `BoundaryEvent` attached to the activity or sub-process that contains the throw, which may be non-interrupting (`cancelActivity` set to `false`) so that the activity carries on, or by the `StartEvent` of an event sub-process (`triggeredByEvent` set to `true`). Give the throw and the catch event definitions the same `escalationRef`. A catch event definition without an `escalationRef` catches every escalation. `Escalation` also takes `structureRef`, the id of an item definition; item definitions are not modelled yet, so it is not checked and the exported XML then contains a reference that bpmn-moddle cannot resolve, so leave it out unless the user asks for it. Worked example: `examples/positive/escalation.jsonld`.
+
+### Common mistakes
+
+- An escalation throw event whose `escalationRef` no boundary event or event sub-process start event references: `escalation-throw-without-catch` (warning). Add the boundary event or the event sub-process with the same `escalationRef`, or correct the `escalationRef` of the existing one. The match is by id across the whole document. A throw event whose escalation definition has no `escalationRef` is not checked, so always write it; a catch event without an `escalationRef` catches every escalation.
+- An `Escalation` nested inside a process or collaboration instead of standing in `@graph`: the schema rejects it.
+- `escalationRef` that names an id nobody defines, or the id of a task or event: `structural-validity` (error).
+- `escalationRef` written on an error event definition or any element other than an escalation event definition: the schema rejects it.
+- A process without a start event: `start-event-missing` (error).
+
+## Shared event definitions
+
+Use a shared event definition when several events must carry the same trigger and the user wants it defined once, for example one timer that starts two processes, or one signal definition that a throw event and a catch event both use. A shared event definition is a root element: it is a top-level node in `@graph`, next to the processes, of one of the event definition types (`TimerEventDefinition`, `SignalEventDefinition`, `MessageEventDefinition` and so on) with an `id` and its usual properties, such as `timeCycle` or `signalRef`. It is never nested inside a process. An event points to it with `eventDefinitionRef`, always a list of ids such as `"eventDefinitionRef": ["Definition_Daily"]`, on a `StartEvent`, `IntermediateCatchEvent`, `BoundaryEvent`, `IntermediateThrowEvent` or `EndEvent`; the schema rejects it on every other element. The id must be that of an event definition of the same document. An event can have both nested `eventDefinitions` and `eventDefinitionRef`, but when the trigger belongs to one event only, nest it in `eventDefinitions` as before, and never write the same definition both ways. A shared signal definition still refers to its `Signal` by `signalRef`. The rules that match throw and catch events, such as `signal-throw-without-catch`, read only the definitions nested in `eventDefinitions`, so a signal, error or escalation that is reached through `eventDefinitionRef` alone is neither checked nor counted as a catch; use nested definitions when the analyzer should check the pairing. bpmnlint reports a signal, error, escalation or message that only a shared definition references as unused, so expect that one warning. `ImplicitThrowEvent` is a further throw event type of the BPMN schema with no properties of its own; use it only when the user or a source model asks for it, and place it in `flowElements` like an `IntermediateThrowEvent`. Worked example: `examples/positive/event-definition-ref.jsonld`.
+
+### Common mistakes
+
+- `eventDefinitionRef` that names an id nobody defines, or the id of a task, a signal or any other element that is not an event definition: `structural-validity` (error).
+- `eventDefinitionRef` written as a single string: it is always a list.
+- A shared event definition that is not a top-level node but is nested in the `eventDefinitions` of one event: it can still be referenced by id, but it is not shared in the sense of a root element and the exported XML is harder to read; put it in `@graph`.
+- Relying on `eventDefinitionRef` for the signal, error or escalation that `signal-throw-without-catch` and its sibling rules should pair: the rules do not follow the reference.
+- A process without a start event: `start-event-missing` (error).
+
+## Conditions
+
+Use a `ConditionalEventDefinition` in an event's `eventDefinitions` when the event is triggered by a condition that becomes true, for example an intermediate catch event that waits until a limit is approved or a boundary event that interrupts work when an order is withdrawn. Put the condition in `condition`, a `FormalExpression` object with a `body` and optionally a `language`, written as `{ "type": "FormalExpression", "language": "https://www.w3.org/TR/xpath20/", "body": "applicant/creditLimit > 0" }`. A conditional event definition has at most one `condition`; leave the event without a condition only while the model is a sketch, because the exported XML then carries an empty condition. `condition` belongs to `ConditionalEventDefinition` only; the schema rejects it on other event definitions.
+
+A converging `ComplexGateway` takes an `activationCondition`, a `FormalExpression` in the same form, that decides when the gateway fires although not all incoming flows have arrived. A gateway has at most one, and the schema rejects it on every other gateway type. bpmnlint reports every complex gateway as `no-complex-gateway` (error), so use one only when the user asks for it or the source model has it; prefer an inclusive or exclusive gateway otherwise.
+
+Any `FormalExpression` may also carry `evaluatesToTypeRef`, the id of an item definition that describes the type of the value it returns. Item definitions are not modelled yet, so the reference is not checked and the exported XML contains a reference that bpmn-moddle cannot resolve; leave it out unless the user asks for it. Worked example: `examples/positive/conditions.jsonld`.
+
+### Common mistakes
+
+- A `condition` or `activationCondition` written as a plain string instead of a `FormalExpression` object: the schema rejects it.
+- `condition` on a `TimerEventDefinition` or another event definition, or `activationCondition` on an exclusive, inclusive or parallel gateway: the schema rejects it.
+- Two conditions in a list on one event definition, or two activation conditions on one gateway: SHACL rejects it.
+- A `FormalExpression` without a `body`: SHACL rejects it.
+- A process around the conditional events without a start event: `start-event-missing` (error).
+- A boundary event with a conditional event definition whose `attachedToRef` names an id nobody defines: `structural-validity` (error).

package/skills/bpmn-ld/references/render-output.md

@@ -0,0 +1 @@
+Read render output: with `--json` and `-o`, output is `{ "warnings": [], "errors": [] }`. Exit 0 means SVG written. Exit 2 means unusable input; see `errors`. Warnings list elements the renderer skipped or could not draw; report them, they do not invalidate the model. A single diagram is written to the exact `-o` path; further diagrams get a numeric suffix.

package/skills/bpmn-ld/references/rule-catalogue.md

@@ -0,0 +1,183 @@
+# Analyzer rule catalogue
+
+Every rule identifier that `npm run analyze` can report in `findings[].rule`, with its severity, what it means, what usually causes it and how to fix it. Errors block completion; warnings do not.
+
+## `structural-validity`
+
+Severity: error.
+
+Explanation: the document is not structurally valid, so the graph rules were skipped. The finding has no node and its message is the validation failure.
+
+Typical causes: a `sourceRef` or `targetRef` that points to an id that does not exist or to a non flow node, a misspelled term, a value of the wrong type, a duplicate id.
+
+Typical fix: run `npm run validate -- <work>`, correct each reported message, then analyze again.
+
+## `start-event-missing`
+
+Severity: error.
+
+Explanation: a process or sub-process has no start event, so it can never begin. The finding names the process or sub-process.
+
+Typical causes: the start event was forgotten, was given the wrong type, or was placed in the wrong `flowElements` list (for example outside the sub-process).
+
+Typical fix: add a `StartEvent` to the scope and connect it with a sequence flow to the first activity.
+
+## `end-event-missing`
+
+Severity: warning.
+
+Explanation: a process or sub-process has no end event. BPMN makes end events optional, but without one the completion of the process is implicit.
+
+Typical causes: the end event was forgotten, or the process intentionally ends at the last activity.
+
+Typical fix: add an `EndEvent` and connect the final activity to it. It may be left as is when implicit completion is intended.
+
+## `node-unreachable`
+
+Severity: warning.
+
+Explanation: a flow node cannot be reached from any start event of its scope, so it never runs.
+
+Typical causes: a missing or wrongly targeted incoming sequence flow, a node left over from an edit, or a boundary event whose host is itself unreachable.
+
+Typical fix: connect the node to the flow with an incoming sequence flow, or remove it. Event sub-processes, compensation activities and link or signal driven nodes are exempt.
+
+## `node-dead-end`
+
+Severity: warning.
+
+Explanation: a flow node that is not an end event has no outgoing sequence flow, so a branch silently stops.
+
+Typical causes: a missing outgoing flow, or a gateway branch that was never finished.
+
+Typical fix: connect the node to the next element or to an end event. It may be acceptable when the branch is deliberately terminal, but an explicit end event is clearer.
+
+## `node-cannot-reach-end`
+
+Severity: warning.
+
+Explanation: no end event can be reached from this flow node, although it may have outgoing flows. The branch can never complete.
+
+Typical causes: a loop without an exit, or a branch that ends in a dead end further on.
+
+Typical fix: add an exit from the loop, for example an exclusive gateway whose other branch leads to an end event. It may be acceptable for a deliberately endless process.
+
+## `gateway-diverging-too-few-outgoing`
+
+Severity: error.
+
+Explanation: a gateway with direction Diverging has fewer than two outgoing flows, so it splits nothing.
+
+Typical causes: a branch flow was forgotten, or the gateway direction is wrong for a gateway that only merges.
+
+Typical fix: add the missing outgoing flow, set `gatewayDirection` to Converging if it merges, or remove the gateway.
+
+## `gateway-converging-too-few-incoming`
+
+Severity: error.
+
+Explanation: a gateway with direction Converging has fewer than two incoming flows, so it merges nothing.
+
+Typical causes: a branch flow was forgotten or targets another node, or the gateway direction is wrong for a gateway that splits.
+
+Typical fix: connect every branch to the gateway, set `gatewayDirection` to Diverging if it splits, or remove the gateway.
+
+## `split-join-exclusive-to-parallel`
+
+Severity: warning.
+
+Explanation: an exclusive split is merged by a parallel join. Only one branch is taken, but the parallel join waits for all of them, so the process may deadlock. The finding names the join.
+
+Typical causes: the join was modelled with the wrong gateway type.
+
+Typical fix: change the join to an exclusive gateway. It is acceptable only when several exclusive splits upstream make every incoming branch fire.
+
+## `split-join-parallel-to-exclusive`
+
+Severity: warning.
+
+Explanation: a parallel split is merged by an exclusive join. All branches run, and each one passes the exclusive join separately, so the flow after it may be activated more than once. The finding names the join.
+
+Typical causes: the join was modelled with the wrong gateway type.
+
+Typical fix: change the join to a parallel gateway. It is acceptable only when the duplicated activation is intended.
+
+## `non-interrupting-start-outside-event-sub-process`
+
+Severity: warning.
+
+Explanation: a start event has `isInterrupting` set to `false` but is not in an event sub-process (a sub-process with `triggeredByEvent` set to `true`). A non-interrupting start event only has meaning when it starts an event sub-process, so the flag has no effect. The finding names the start event.
+
+Typical causes: a message or timer start that was meant to run beside the main flow was put in the process or in a regular sub-process, or `triggeredByEvent` was left off the sub-process.
+
+Typical fix: if the start event should react to an event while the scope runs, move it into a sub-process with `triggeredByEvent` set to `true`. Otherwise remove `isInterrupting` or set it to `true`.
+
+## `instantiating-gateway-with-incoming-flow`
+
+Severity: error.
+
+Explanation: an event-based gateway with `instantiate` set to `true` starts a new process instance when one of the events after it occurs, so it must not have an incoming sequence flow. The finding names the gateway. A scope with an instantiating gateway or an instantiating receive task needs no start event.
+
+Typical causes: a start event was kept in front of the gateway, or `instantiate` was set on a gateway that is in the middle of the flow.
+
+Typical fix: if the gateway should start the process, remove the incoming sequence flow (and the start event in front of it). If it only waits for events in the middle of the flow, remove `instantiate` or set it to `false`.
+
+## `ad-hoc-completion-condition-missing`
+
+Severity: warning.
+
+Explanation: an `AdHocSubProcess` has no `completionCondition`. The completion condition is the expression that ends an ad-hoc sub-process, so without it nothing defines when it is complete. The finding names the ad-hoc sub-process. The activities inside an ad-hoc sub-process have no prescribed order, so the analyzer does not ask for a start event, an end event or sequence flows inside it.
+
+Typical causes: the condition was left out, or the sub-process was modelled as a regular sub-process and later changed to an ad-hoc one.
+
+Typical fix: add a `completionCondition` to the ad-hoc sub-process, a `FormalExpression` with a `body` that becomes true when the work is done. If the activities should run in a fixed order, use a regular `SubProcess` with sequence flows instead.
+
+## `compensation-activity-without-association`
+
+Severity: warning.
+
+Explanation: an activity has `isForCompensation` set to `true` but no association in its process or sub-process that starts at a compensation boundary event (a boundary event with a `CompensateEventDefinition`) has it as `targetRef`. A compensation activity runs only when a compensation event reaches it through an association, so without one the activity can never run. The finding names the compensation activity. An association from a task, a gateway or any other event does not count. The analyzer does not report a compensation boundary event as a dead end.
+
+Typical causes: the association was left out, it points at a different activity, it starts at something other than a compensation boundary event, or it was written in the wrong scope, for example in the parent process instead of the sub-process that holds the activity.
+
+Typical fix: add an `Association` to the `artifacts` of the scope that holds the activity, with the compensation boundary event as `sourceRef` and the compensation activity as `targetRef`. If the activity is an ordinary step, remove `isForCompensation` and connect it with sequence flows.
+
+## `task-message-without-message-flow`
+
+Severity: warning.
+
+Explanation: a `SendTask` or a `ReceiveTask` has a `messageRef`, but the collaboration has no message flow that matches it. For a send task the message flow must leave the task (the task is its `sourceRef`), for a receive task it must enter the task (the task is its `targetRef`), and the message flow must carry the same message or no message at all. A message flow that carries a different message, one that runs in the other direction and one that connects the participant instead of the task do not match. The finding names the task.
+
+Typical causes: the message flow was left out, it carries another message or none that matches, it points the other way, it connects the participant boundary instead of the task, or the task was given a `messageRef` in a process that is not part of a collaboration.
+
+Typical fix: add a `MessageFlow` to the `messageFlows` of the collaboration with the task as `sourceRef` (send) or `targetRef` (receive) and the same `messageRef` as the task. If the flows are right, correct the `messageRef` of the task. If the task does not exchange a message with another participant, remove its `messageRef`.
+
+## `signal-throw-without-catch`
+
+Severity: warning.
+
+Explanation: an `IntermediateThrowEvent` or an `EndEvent` has a `SignalEventDefinition` with a `signalRef`, but no `StartEvent`, `IntermediateCatchEvent` or `BoundaryEvent` anywhere in the document has a `SignalEventDefinition` with the same `signalRef`. A signal is broadcast to every process, so the catch event can be in any process or sub-process, but when none references the signal nothing reacts to it. The finding names the throw event. A throw event without a `signalRef` is not checked, and a catch event without a `signalRef` does not match any signal.
+
+Typical causes: the catch event references a different signal, the catch event was left out, the `signalRef` of the catch event is missing, or the catch event is in a document that is modelled separately.
+
+Typical fix: add a catch event, such as a signal start event, an intermediate catch event or a boundary event, with a `SignalEventDefinition` whose `signalRef` is the same signal. If the catch event exists, correct its `signalRef`. If nothing needs to react, remove the throw event or use a plain end event.
+
+## `error-throw-without-catch`
+
+Severity: warning.
+
+Explanation: an `EndEvent` has an `ErrorEventDefinition` with an `errorRef`, but no `BoundaryEvent` and no `StartEvent` anywhere in the document has an `ErrorEventDefinition` with the same `errorRef`. BPMN errors are caught by a boundary event on an activity or by the start event of an event sub-process. The match is by the id of the error across the whole document; it is not checked that the catch event encloses the throw event. A catch event with an `ErrorEventDefinition` that has no `errorRef` catches every error and matches every throw event. An end event whose error definition has no `errorRef` is not checked. The finding names the end event.
+
+Typical causes: the catch event references a different error, the boundary event or event sub-process was left out, or it is attached to the wrong activity and was never added after the error was introduced.
+
+Typical fix: add a boundary event on the activity or sub-process that contains the throw, or an event sub-process with an error start event, with an `ErrorEventDefinition` whose `errorRef` is the same error. If the catch event exists, correct its `errorRef`. If nothing needs to handle the error, use a plain end event instead.
+
+## `escalation-throw-without-catch`
+
+Severity: warning.
+
+Explanation: an `IntermediateThrowEvent` or an `EndEvent` has an `EscalationEventDefinition` with an `escalationRef`, but no `BoundaryEvent` (interrupting or not) and no `StartEvent` anywhere in the document has an `EscalationEventDefinition` with the same `escalationRef`. BPMN escalations are caught by a boundary event on an activity or by the start event of an event sub-process. The match is by the id of the escalation across the whole document; it is not checked that the catch event encloses the throw event. A catch event with an `EscalationEventDefinition` that has no `escalationRef` catches every escalation and matches every throw event. A throw event whose escalation definition has no `escalationRef` is not checked. The finding names the throw event.
+
+Typical causes: the catch event references a different escalation, the boundary event or event sub-process was left out, or it is attached to the wrong activity and was never added after the escalation was introduced.
+
+Typical fix: add a boundary event on the activity or sub-process that contains the throw, or an event sub-process with an escalation start event, with an `EscalationEventDefinition` whose `escalationRef` is the same escalation. If the catch event exists, correct its `escalationRef`. If nothing needs to react, use a plain end event or remove the throw event.

package/skills/bpmn-ld/references/vocabulary-summary.md

@@ -0,0 +1,65 @@
+# Vocabulary summary
+
+A short list of the terms used most when writing BPMN-LD. Names follow BPMN 2.0: classes are UpperCamelCase values of `type`, properties are lowerCamelCase. The complete generated list is `docs/reference/vocabulary.md`.
+
+## Document
+
+- `@context`: a list with the core context path first, then an object with `@base`. References resolve against `@base`, so they are plain id strings.
+- `id`: unique identifier of every element, for example `Task_ReviewOrder`.
+- `type`: the class of the element.
+- `name`: human-readable label.
+- A document with one process is the process object itself. Several top-level nodes, such as a collaboration, its processes and its messages, go in `@graph`.
+
+## Process and containers
+
+| Term | Use |
+| --- | --- |
+| `Process` | Top-level container. Holds `flowElements`. Optional `processType` (`None`, `Public` or `Private`), `isExecutable` and `isClosed`. |
+| `SubProcess` | Activity that holds its own `flowElements`. Set `triggeredByEvent` to `true` for an event sub-process. |
+| `AdHocSubProcess` | Sub-process whose activities have no prescribed order. Optional `ordering` (`Parallel` or `Sequential`), `completionCondition` (a `FormalExpression`) and `cancelRemainingInstances` (default `true`). |
+| `Transaction` | Sub-process whose activities complete or are undone together. Optional `method` (`Compensate`, `Image` or `Store`; `Compensate` by default). |
+| `flowElements` | List of flow nodes and sequence flows. |
+| `artifacts` | List of `Association`s of a process or sub-process. An `Association` has `sourceRef`, `targetRef` and an optional `associationDirection` (`None`, `One` or `Both`); a compensation boundary event is linked to its compensation activity this way. |
+
+## Events
+
+`StartEvent`, `EndEvent`, `IntermediateCatchEvent`, `IntermediateThrowEvent`, `ImplicitThrowEvent`, `BoundaryEvent` (with `attachedToRef` and `cancelActivity`). A start event has `isInterrupting`, which is `false` for a non-interrupting start of an event sub-process. A catch event with several event definitions has `parallelMultiple`, `true` when all must occur. Give an event a trigger with `eventDefinitions`, a list of `MessageEventDefinition`, `TimerEventDefinition`, `SignalEventDefinition`, `ErrorEventDefinition`, `EscalationEventDefinition`, `TerminateEventDefinition`, `ConditionalEventDefinition`, `LinkEventDefinition`, `CompensateEventDefinition` or `CancelEventDefinition`. A throw event with a `CompensateEventDefinition` can compensate one activity: `activityRef` is the id of that activity, and `waitForCompletion` makes the process wait. A `LinkEventDefinition` (with the same `name` on a throw and a catch event) pairs a throw with a catch event: the throw definition has `target`, the id of its catch definition, and the catch definition has `source`, a list of the ids of the throw definitions. An event definition defined once at the top level of the document is shared by listing its id in `eventDefinitionRef` of any catch or throw event.
+
+## Activities
+
+`Task`, `UserTask`, `ServiceTask`, `ManualTask`, `ScriptTask` (with `script` and `scriptFormat`), `BusinessRuleTask`, `SendTask`, `ReceiveTask` (with `instantiate`, `true` when it starts the process), `SubProcess`, `AdHocSubProcess`, `Transaction`. Every activity takes optional `isForCompensation` (default `false`), `startQuantity` and `completionQuantity` (non-negative integers, default 1). `UserTask`, `ServiceTask`, `BusinessRuleTask`, `SendTask` and `ReceiveTask` take an optional `implementation` string. `SendTask` and `ReceiveTask` take an optional `messageRef` (the id of a `Message`), and they and `ServiceTask` an optional `operationRef` that is not checked.
+
+## Gateways
+
+`ExclusiveGateway`, `ParallelGateway`, `InclusiveGateway`, `EventBasedGateway` (with `instantiate`, `true` when it starts the process, and `eventGatewayType`, `Exclusive` or `Parallel`), `ComplexGateway`. A gateway or activity names its default outgoing flow with `default`, whose value is the id of a sequence flow.
+
+## Sequence flow
+
+`SequenceFlow` (optional boolean `isImmediate`) with `sourceRef` and `targetRef` (ids of flow nodes in the same process or sub-process). Optional `conditionExpression`:
+
+```json
+{ "type": "FormalExpression", "language": "https://262.ecma-international.org/", "body": "approved === true" }
+```
+
+The default flow of a gateway carries no condition.
+
+The same expression form is used by `condition` on a `ConditionalEventDefinition`, `activationCondition` on a `ComplexGateway` and `completionCondition` on an `AdHocSubProcess`. A `FormalExpression` may carry `evaluatesToTypeRef`, the id of an item definition; item definitions are not modelled yet, so leave it out.
+
+## Collaboration and lanes
+
+`Collaboration` (optional `isClosed`) with `participants` (`Participant`, each with `processRef`) and `messageFlows` (`MessageFlow` with `sourceRef`, `targetRef` and an optional `messageRef`). `LaneSet` in `laneSets` with `lanes` (`Lane`, each with `flowNodeRef`). A `Lane` may name the element that defines its partition: `partitionElement` is a nested node of any concrete class (usually just `id` and `type`), `partitionElementRef` is the id of an element of the document. Both are optional and at most one of each.
+
+## Root elements, messages, signals, errors and escalations
+
+A root element stands at the top level of the document, in `@graph` next to the processes and collaborations. `Message`, `Signal`, `Error` and `Escalation` (each with an optional `name`; an `Error` also has `errorCode` and an `Escalation` `escalationCode`) are four, and every event definition type can stand there too; others are added over time. Refer to it by id: `messageRef` on a `MessageFlow`, a `MessageEventDefinition`, a `SendTask` or a `ReceiveTask` names the `Message` it carries, sends or receives, `signalRef` on a `SignalEventDefinition` names the `Signal` it throws or catches, `errorRef` on an `ErrorEventDefinition` names the `Error` it throws or catches, and `escalationRef` on an `EscalationEventDefinition` names the `Escalation` it throws or catches, and `eventDefinitionRef` (a list) on a catch or throw event names the top-level event definitions it uses.
+
+## Diagram
+
+A model that carries its own diagram adds `contexts/di.jsonld` to `@context` and a `BPMNDiagram` to `@graph`. `BPMNDiagram` has an optional `name` string, an optional `resolution` number (dots per inch) and a `plane` (`BPMNPlane`) whose `planeElements` hold `BPMNShape` and `BPMNEdge` nodes. A `BPMNEdge` may have `messageVisibleKind`, `initiating` or `non_initiating`. Layout adds a diagram when there is none; leave it to layout unless the user gives diagram details.
+
+## Rules of thumb
+
+- Every process needs a start event; give it an end event too, or the analyzer warns.
+- Every non-end node needs an outgoing flow and every node needs an incoming flow, or the analyzer warns.
+- A diverging exclusive gateway needs at least two outgoing flows, a converging one at least two incoming.
+- Unknown terms are rejected. Use only terms from this list or `docs/reference/vocabulary.md`.

package/skills/bpmn-ld/template.jsonld

@@ -0,0 +1,14 @@
+{
+  "@context": [
+    "/ABSOLUTE/PATH/TO/REPO/contexts/core.jsonld",
+    { "@base": "https://example.org/models/my-process/" }
+  ],
+  "id": "Process_1",
+  "type": "Process",
+  "name": "My process",
+  "flowElements": [
+    { "id": "StartEvent_1", "type": "StartEvent", "name": "Start" },
+    { "id": "EndEvent_1", "type": "EndEvent", "name": "End" },
+    { "id": "Flow_1", "type": "SequenceFlow", "sourceRef": "StartEvent_1", "targetRef": "EndEvent_1" }
+  ]
+}

package/templates/combined.jsonld

@@ -0,0 +1,3 @@
+{
+  "@context": ["core.jsonld", "di.jsonld"]
+}