docs(spec): a forms register — form, journey and journeyRun

[rubenvdlinde]

What

Spec only. Adds a forms register with form, journey and journeyRun, the API that drives a run, named formats, and a retention job.

Programme context: hydra#581 (ADR-085).

Why

tilburg-woo-ui implements citizen and supplier intake as ~13,640 lines of hand-written React across seven wizards, each re-implementing step state, per-index validation, progress display and submission. None is resumable — closing the tab loses everything.

The declarative half already exists, here and in nc-vue: manifest v2 carries config.steps[], visibleWhen and a closed fieldValidation, and CnFormPage renders them. What is missing is the primitive that spans more than one form: multiple objects, branching between forms, lookup-and-prefill, a review step, and somewhere to keep a half-finished submission.

Naming

journey, not flow. OpenRegister already owns flow for the automation engine — ADR-065, ~40 change specs, FlowController, flow runs, a visual canvas. A journey is a UI-facing sequence; it may trigger a flow, and it is not one.

What the spec pins

• A form's config is validated by the same validateManifestV2() path an app manifest is — not a subset schema maintained alongside it. If the two can drift, they will. The test feeds one fixture through both paths and compares the error objects.
• Branching reuses $defs.visibleWhen verbatim. A second condition grammar is the single most likely way this design rots, so it is forbidden and gated.
• Nothing is written until a step declares writes[]. This preserves the property the React wizards have by accident — an abandoned registration leaves no half-built organisation — while adding the resumability they lack.
• A resume token is a bearer credential for someone's half-filled form. It must not act as an existence oracle: a token/run mismatch and an unknown run return identical responses.
• Retention ships with the schema. A journeyRun holds names, addresses, e-mail, phone numbers and uploads before any of it is a record. The purge reports its row count, because a job that deletes nothing must be distinguishable from one that never ran — this instance's audit retention purge had never executed while looking exactly like a purge with nothing to do.
• Named formats (email, website, nl-phone) replace the per-app validator forks, pinned against the cases tilburg's form-validations.js handles today including its explicit rejections (www.nl, http://.nl, hyphen-only labels, 06/+31 phone handling).

Depends on / feeds

Rendered by nextcloud-vue/journey-runtime (#665); authored by openbuild/journey-designer (#207).

🤖 Generated with Claude Code

[github-actions]

Quality Report — ConductionNL/openregister @ 1f0c7bd

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
check-specs		✅
test-l10n		✅
format		✅
composer			✅	✅ 175/175
npm			✅	✅ 528/528
app:check-code	⏭️
info.xml	✅
REUSE	❌
PHPUnit					✅
Newman					✅
Playwright					✅
Hydra gates					❌

---

Quality workflow — 2026-08-15 08:11 UTC

Download the full PDF report from the workflow artifacts.