camunda / camunda/api-test-generator
Ontology: per-field-site affordance layer for model-element selection
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 0
- Forks
- 3
- Avg merge
- 13h 41m
- Merged PRs (30d)
- 23
Description
Context
Follow-up from #172 (PR #367). That fix made createProcessInstance.startInstructions[].elementId
resolve to a real, broker-accepted model element by adding:
providesElements: {id,type}[]on deployment fixtures (the model's typed-element ABox), andmodelElementTypeson theElementIdsemantic type (acceptable elementtypes, in
preference order, excludingstartEvent).
This is correct and decoupled (no BPMN vocabulary in planner code), and it works. But it places a
per-field-site constraint onto the semantic type, which is conceptually the wrong layer.
The abstraction gap
ElementId is a single semantic shared across many request sites, each with different
acceptable-element rules:
| Site | Acceptable elements |
|---|---|
createProcessInstance.startInstructions[].elementId |
any flow node except start event |
runtimeInstructions[].afterElementId |
flow nodes incl. end event |
modifyProcessInstance.activateInstructions[].elementId |
activatable elements |
…terminateInstructions[].elementInstanceKey |
active element instances (runtime, not model) |
migration mappingInstructions source/target |
mappable elements |
| element filters | any referenced element |
Putting modelElementTypes on the ElementId semantic flattens a per-site predicate onto the
type. It's harmless today because only createProcessInstance uses the literal model-derived
fallback (all other sites use runtime emission: __PENDING__ + step-extract), but it won't
generalise: the moment a second site needs a literal model element with a different rule, the
single modelElementTypes list is wrong for one of them.
Proposed direction
Introduce a middle ontology layer — affordance — between semantics (field meaning) and
runtime-states (server state machine):
(model-element kind) x (request-field role/site) -> selection predicate + expected runtime-state effect
Concretely:
- A small local element-type taxonomy (subsumption:
serviceTaskis-ataskis-aactivity
is-aflowNode;startEventis-aeventis-aflowNode; ...) so rules can be expressed as
flowNode \ startEventrather than enumerating every concrete type. - A field-site affordance vocabulary keyed by request field-role (not by semantic type), each
binding a selection predicate over the taxonomy plus the expected runtime-state effect for the
test expectation. - Migrate
modelElementTypesoff theElementIdsemantic and onto the per-site affordance.
sBPMN assessment
sBPMN 2.0 was evaluated as the element-type TBox. It would give us
the subsumption hierarchy for free, but it's heavyweight, BPMN-specific external OWL, and the repo
already has its own ontology idiom (semantics / runtime-states / artifact-kinds). Recommendation:
a lightweight local taxonomy over importing sBPMN wholesale. sBPMN can inform the taxonomy's
shape.
Notes
providesElementson fixtures is the right ABox either way — no change needed there.- This is an "ask first" new ontology sub-tree per AGENTS.md; design review before implementation.
Spun off from #172.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with AGENTS.md and review the existing semantics, runtime-states, artifact-kinds, ElementId, and modelElementTypes introduced for #172 and PR #367. Compare the proposed local taxonomy and field-site affordance vocabulary against the listed request sites. Done means a reviewed design for the new ontology subtree and migration plan before implementation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- testing-qa, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100