Building a Versioned Metadata Schema for Model-Driven Mobile Forms

Treat Form Metadata as a Deployable Contract

The safest release for a generated mobile form is often a versioned metadata document rather than a new application binary. When the installed runtime already understands the required field types, validators, visibility operators, and localization keys, the publisher can change the form without replacing the native client.

That distinction matters in field deployments. A label correction may look harmless, yet editing a live document in place can disrupt cached forms, older clients, saved drafts, or submissions waiting offline. Publishing the correction as a new immutable schema version lets connected devices adopt it after verification while offline devices continue using their last approved copy.

Draw the Runtime Boundary First

The metadata path covers enterprise forms interpreted by a bounded mobile runtime, including devices that connect only occasionally. Changes requiring a new native control, operating-system permission, storage capability, or interpreter feature belong in a binary release. Downloaded executable code and major workflow-engine changes remain outside this design.

Server-side validation still applies to every submitted value. Client metadata improves form behavior; it never establishes a trusted security boundary.

Give Every Form Version a Stable Identity

Build the schema envelope before defining individual fields. The envelope tells publishers, runtimes, and support tools exactly which document they are handling.

• formId identifies the form family across all releases.
• schemaVersion supplies a monotonically increasing retrieval and audit key. The integer alone does not prove compatibility.
• minimumRuntimeVersion prevents an incapable interpreter from opening the document.
• status separates drafts from published versions, while effectiveAt defines the activation instant.
• defaultLocale points to the fallback resources packaged with the cached schema.
• id is the permanent data key. The mutable labelKey controls the prompt shown to a user.

Prompt text must never double as a stored key. Renaming “Asset number” to “Asset tag” should leave payloads and integration mappings untouched. If the business meaning behind assetTag changes, allocate a new field ID and define an explicit migration.

Keep drafts on a separate retrieval path. A production manifest should reference only a validated document whose content hash was recorded when it was published.

Model Labels, Validation, and Visibility Explicitly

Separate Meaning from Presentation

Start each field with its stable ID, data type, nullability, and default value. Add presentation properties such as controlHint, labelKey, and displayOrder afterward. If two fields share the same display order, ascending immutable field ID provides a deterministic tie breaker.

Locale bundles should resolve labels through keys. Package the default locale with the offline cache so a missing translation can fall back to a readable prompt instead of exposing a raw field ID or an empty label.

Compile Rules as Typed Data

Represent validation with named declarative operators and typed operands. An integer field using numericInput, for example, can be required and constrained by a range from 0 to 500. The compiler must preserve those bounds as integers rather than compare them as strings.

Visibility rules follow the same discipline. A condition where requiresFollowUp equals true may reveal followUpDetails. Before publication, the schema compiler should reject undeclared field references and operators missing from the runtime capability list. Executable script strings have no place in the form document.

Evolve Forms Without Stranding Older Clients

Review every proposed diff in three passes:

• Additive: A nullable inspectionPhotoCaption field with a null default can be safe when older runtimes ignore unknown optional properties and downstream consumers tolerate an absent key.
• Behavior-changing: Making that caption mandatory can invalidate an already-saved draft. Tightening a maximum length or changing a visibility condition has similar consequences.
• Breaking: Changing meterReading from a decimal measurement to formatted text alters its stored meaning. Introduce meterReadingText and retain the original value for historical records.

Runtime interpreters should ignore unknown optional properties while rejecting unsupported required capabilities. That rule permits controlled extension without allowing a client to silently omit essential behavior.

Retire Fields in Stages

A field moves through introduction, deprecation, removal from new entries, preservation for historical records, and eventual retirement. Version 18 might stop showing an old field on new forms; version 19 can remove its presentation metadata after queued submissions, retention requirements, and downstream mappings have been checked.

Compatibility review must include cached schemas, packaged locale fallbacks, saved drafts, queued submissions, and every payload consumer.

Make the Runtime Deterministic When Devices Go Offline

A reliable interpreter treats downloaded metadata as a candidate until the complete document passes verification.

1. Fetch the active manifest at startup or an approved refresh point.
2. Verify the envelope and recorded content hash.
3. Compare required capabilities with the installed runtime.
4. Write the candidate to a staging cache.
5. Parse fields within published size and depth limits.
6. Compile recognized rules into a stable order.
7. Promote the candidate to the approved cache only after every check succeeds.
8. Render controls and validate input against that approved version.

A practical parser policy can cap documents at roughly 1 MiB, nesting at 32 levels, and visibility dependency chains at 64 fields. These figures are implementation limits that must be documented with the runtime rather than treated as universal schema properties.

If a download is truncated, its hash differs, an operator is unknown, or a required capability is absent, retain the last verified schema. Candidate validation must never overwrite the working cache.

Pin Before Entry

Opening a form pins that session to one schema version. A background refresh cannot change controls or validation mid-entry—particularly when a technician resumes a draft after hours offline.

Persist formId and schemaVersion beside every local draft and queued submission. Send both identifiers with the payload when connectivity returns. A manifest refresh interval of roughly 6 to 24 hours suits many intermittent field deployments, with an explicit user refresh available before starting a new form.

Publish Form Versions Through a Reversible Rollout

Advance the Manifest, Preserve the Documents

Move a release through signed-off draft validation, representative test devices, a constrained production audience, broad activation, and retirement. Each transition updates a manifest pointer. Published schema documents remain immutable.

Device validation should run for about one to three business days across the oldest supported runtime, the current runtime, empty and existing caches, and an offline resume path. Hold limited production activation for roughly 4 to 24 hours or one complete field shift, whichever is longer, before broadening access.

Operational logs should record formId, schemaVersion, runtime version, manifest retrieval result, schema verification result, validator code, and submission outcome. Omit entered values unless a separately approved diagnostic policy requires them.

Keep at least the active schema and one previously verified version addressable. When a release fails, repoint the manifest to the verified version instead of repairing the production document in place. Retire a version only after no supported draft, queued submission, retention process, or integration mapping depends on it.

Use immutable, version-pinned schemas as the sole production path for model-driven mobile forms.