Hub positive-suite triage — status, ABox, annotations, validation, gaps

🚧 BLOCKED on the Workspace/Project layer — camunda/camunda-hub#24437

Positive Hub test generation cannot run end-to-end yet, independent of the ABox/annotation work below. Every createFile/createFolder requires a projectKey, but:

there is no create-project API, and
the v2 spec we're pinned to exposes only /files and /folders — no /projects or /workspaces path at all.

camunda/camunda-hub#24437 (still open) shows the Workspace → Project → Folder → File container model is mid-build. Until a projectKey can exist and be targeted, positive generation is blocked. The negative / request-validation suite is unaffected (it needs no project and already runs). Net: it's currently too early for positive Hub tests — revisit once #24437 lands.

The annotation-sourcing direction (Option A vs B) and ownership are a separate decision — see the @jwulf comment below.

Everything else here is prep, ready for when the block clears.

Prep: draft ABox + PR

Draft ABox committed and opened as draft PR #369 (feat/hub-abox-360), off main. Three slices at configs/camunda-hub/ontology/ (all pass AJV validation against the TBox schemas):

entity-kinds.json — File + Folder, shape: entity, CRUD triple (createX/getX/deleteX).
global-context-seeds.json — projectKeyVar → projectKey (the tenantId-style seed for the producerless required key).
scenario-templates.json — EntityLifecycle.

Not needed: semantics.json (producer-bound keys come from spec annotations, like OCA's entity keys); edges/artifact-kinds/runtime-states (loader no-ops on absent slices — confirmed).

Spec annotations required

The Hub spec has no x-semantic-* on its keys (only 2 unrelated pagination-cursor tags). Following the OCA server-minted-key recipe, it needs:

new key schemas FileKey/FolderKey with x-semantic-type,
FileResult.fileKey / FolderResult.folderKey + the get/delete path params $ref-ing those schemas,
x-semantic-provider: ["fileKey"] / ["folderKey"] on the create responses.

No x-semantic-establishes/requires for this shape (Authorization in OCA doesn't have them either).

Validation — ran the planner on a throwaway annotated copy

File — proven. Graph extraction found the createFile → getFile/deleteFile chains; scenario generation produced the create→get prerequisite scenario with productionMap: { FileKey: createFile } and the projectKeyVar seed bound. The annotation recipe + ABox work end-to-end for the flat case.
Folder — blocked by gap 4 below.

The four generator gaps

No read-back template for in-API-mutable entities. UpdatedFieldVisibleOnReadBack applies to runtime-entity only, and the schema forbids mutators on shape: entity. So updateFile/updateFolder get no read-after-write coverage — Hub entities are client-CRUD, not runtime-emitted.
Optimistic concurrency unmodeled. updateFile requires the current revision (from FileResult.revision) and returns 409 on a stale value. No support for feeding an entity's own observed version token back into a mutator (the 409 is a negative-test opportunity).
Field-established containment edges. folderKey on createFile / parentFolderKey on createFolder establish containment via a create-body field, observed via the parent's getFolder.content.{files,folders}[] — not via dedicated assign*/search*ForX ops. EdgeLifecycle assumes a dedicated establish/observe op pair.
Composite get-by-id breaks canonical-path validation. getFolder returns a detail wrapper (FolderDetailResult = the folder plus content.folders[]/content.files[]). Once keys are typed, they also appear nested in those arrays, and the planner rejects it: getFolder: 'content.folders[].folderKey' not in canonical response shape. Not an annotation error — it's Hub modeling "get folder" as "folder + its contents." Either the validator tolerates a composite observe-by-id response, or getFolder needs different handling. Confirmed intentional by camunda/camunda-hub#24434 (GET /folders/{folderKey} returns metadata + content).

Gaps 1–3 are ontology/emitter extensions; gap 4 blocks Folder specifically. None affect File.

When #24437 lands, sequence is

Decide annotation sourcing (A vs B) + ownership — @jwulf comment below.
Land File annotations via the chosen path → File EntityLifecycle ships (proven).
Resolve gap 4 → unblock Folder.
Tackle gaps 1–3 (read-back, concurrency, containment) as ontology/emitter features.

Generate Camunda Hub API tests and triage ontology / emitter gap #360

Description

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions