Form runtime documentation

Overview

Form runtime is a standalone Next.js application that renders interactive questionnaires from a JSON definition (FormJson), validates answers with ODK-like rules (relevance, constraints, calculate fields), supports internationalization and accessibility, and submits answers to your backend or a local API. It can run as a public fill experience, an embedded demo, or a builder preview target.

Functional capabilities

Form definition

• Contract: FormJson — id, meta (title, description, tags, version, locale, optional i18nOverrides, optional submitUrl / submitJwt), and a tree of questions.
• Normalization: persisted API payloads (including survey export shapes with surveyMeta) are coerced via normalizePersistedFormToFormJson.

Question types with dedicated UI

These types are wired in widgetRegistry and render full controls: text, integer, decimal, select_one, select_multiple, rating, acknowledge, note, calculate, image, audio, video, file.

Containers: group and repeat nest children; repeats support row add/remove, per-row validation, and parameters such as repeat count / ODK template flags where implemented in schema and storage.

Other declared types (e.g. date, time, datetime, geo types, range, barcode) currently resolve to UnsupportedWidget — they appear as an unsupported notice unless you extend the registry.

Visibility and logic

• Relevance: relevantExpression and builder skip logic drive which questions are shown (visibility.ts).
• Constraints: constraintExpression with optional constraintMessage / per-locale constraintMessages; messages support ${field}-style interpolation after locale resolution.
• Calculate: read-only fields from calculation; derived values are merged into the answer map for visibility, validation, and submit.
• Expression engine: documented subset (not full XPath 2.0) — see validation/expression.ts and the Phase 2 semantics doc in the repo.

Validation behavior

• FormRuntime supports validationMode: submit (default), change (debounced), or blur.
• On submit failure: field errors, an error summary (ordered by render order), and scroll/focus to the first invalid field.
• Required fields, regex helper in constraints, and rating uniqueness rules are enforced in validateForm.ts.

Internationalization

Built-in bundles for validation and UI copy (formRuntime namespace), with meta.locale and optional meta.i18nOverrides merging author strings. The document lang attribute follows the resolved language.

Accessibility

Field regions use stable data-field-key, composed aria-describedby, aria-errormessage when invalid, and appropriate roles for groups/ratings/media. Inline errors use live regions consistent with the error summary pattern.

Drafts and offline

• Drafts: answers persisted in IndexedDB per form id/version; can be restored on reload until a successful submit clears them.
• Offline submission: when the network fails or the device is offline, submissions can be queued in an outbox and retried (client drain + status messaging).

Submission

If meta.submitUrl and meta.submitJwt are set (typical when Django serves fill JSON), POST is sent to that URL with the JWT header expected by the backend. Otherwise the runtime posts to /api/submissions on the same origin with JSON body including form_id and answers (buildSubmitRequest).