[User Story] Document the local meaning of configured forms and fields #5

New Issue

2026-08-21T00:07:35+02:00

zemion commented

2026-08-21 00:07:35 +02:00

Depends on GovOPlaN/govoplan-core#292 and GovOPlaN/govoplan-docs#21.

User story

As a form configurator or information owner, I want to document what a configured form and each relevant field mean in our institution, why information is collected, and how it should be interpreted, so that applicants, caseworkers, and administrators apply the form consistently.

Scope

Forms exposes documentation-safe semantic subjects for a form definition and stable nested field identifiers. Authored content remains in Docs. Form schema, labels, validation, requiredness, and submitted values remain authoritative in Forms and are never copied into semantic prose as configuration.

Acceptance criteria

A configured form definition is exposed as a semantic-documentation subject.
Each addressable field uses a stable identifier that survives label and ordering changes; sections may be added where identifiers are equally stable.
Subject metadata includes only safe localized labels, hierarchy, configured revision/fingerprint, provenance, and contextual route/anchor.
Forms re-authorizes subject resolution for tenant and principal without exposing inaccessible forms or fields.
Configurators can enter Docs authoring from the form builder for a form or field and return without losing unsaved form changes.
Published semantics are available from the form/field contextual-help surface for permitted audiences.
Field semantics can express meaning, collection purpose, interpretation guidance, intended use, non-intended use, and examples without overriding schema or validation.
Form publication/revision changes mark affected semantic content for review using defined fingerprint rules.
Deleted fields become explicit orphaned references; identifier reuse cannot silently attach old documentation to a new field.
Tests cover stable identity, authorization, revision changes, deletion/recreation, tenant isolation, contextual links, and disabled-module behavior.
Forms user/admin documentation explains the integration and its limitations.

Parent epic: GovOPlaN/govoplan#49 Depends on GovOPlaN/govoplan-core#292 and GovOPlaN/govoplan-docs#21. ## User story As a form configurator or information owner, I want to document what a configured form and each relevant field mean in our institution, why information is collected, and how it should be interpreted, so that applicants, caseworkers, and administrators apply the form consistently. ## Scope Forms exposes documentation-safe semantic subjects for a form definition and stable nested field identifiers. Authored content remains in Docs. Form schema, labels, validation, requiredness, and submitted values remain authoritative in Forms and are never copied into semantic prose as configuration. ## Acceptance criteria - [x] A configured form definition is exposed as a semantic-documentation subject. - [x] Each addressable field uses a stable identifier that survives label and ordering changes; sections may be added where identifiers are equally stable. - [x] Subject metadata includes only safe localized labels, hierarchy, configured revision/fingerprint, provenance, and contextual route/anchor. - [x] Forms re-authorizes subject resolution for tenant and principal without exposing inaccessible forms or fields. - [x] Configurators can enter Docs authoring from the form builder for a form or field and return without losing unsaved form changes. - [x] Published semantics are available from the form/field contextual-help surface for permitted audiences. - [x] Field semantics can express meaning, collection purpose, interpretation guidance, intended use, non-intended use, and examples without overriding schema or validation. - [x] Form publication/revision changes mark affected semantic content for review using defined fingerprint rules. - [x] Deleted fields become explicit orphaned references; identifier reuse cannot silently attach old documentation to a new field. - [x] Tests cover stable identity, authorization, revision changes, deletion/recreation, tenant isolation, contextual links, and disabled-module behavior. - [x] Forms user/admin documentation explains the integration and its limitations.

zemion added the module/forms module/docs

labels 2026-08-21 00:07:35 +02:00

zemion referenced this issue from GovOPlaN/govoplan

2026-08-21 00:08:04 +02:00

[Epic] Author configured-system semantics in Docs #49

zemion commented

2026-08-21 16:40:33 +02:00

Implemented and released as v0.1.19 in b9132d0.

Forms now exposes tenant-authorized, documentation-safe subjects for form definitions, sections, and fields. Stable lineage survives label/order changes; deletion and identifier reuse remain distinguishable; configured fingerprints drive explicit review state. The builder provides Docs authoring/help links with dirty-state protection, while Forms remains authoritative for schema, validation, and submitted values.

Verification:

16 Forms tests covering identity, authorization, revisions, deletion/recreation, tenant isolation, and integration behavior
Ruff, TypeScript, manifest-shape, dependency, and complete focused workspace checks

Implemented and released as `v0.1.19` in b9132d0. Forms now exposes tenant-authorized, documentation-safe subjects for form definitions, sections, and fields. Stable lineage survives label/order changes; deletion and identifier reuse remain distinguishable; configured fingerprints drive explicit review state. The builder provides Docs authoring/help links with dirty-state protection, while Forms remains authoritative for schema, validation, and submitted values. Verification: - 16 Forms tests covering identity, authorization, revisions, deletion/recreation, tenant isolation, and integration behavior - Ruff, TypeScript, manifest-shape, dependency, and complete focused workspace checks

zemion closed this issue

2026-08-21 16:40:34 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan-forms#5