Forms With Collision Control

When multiple people edit the same form definition simultaneously, someone loses their work. This is not a minor inconvenience. In enterprise environments where forms drive critical business processes, an overwritten form schema can cascade into broken workflows, invalid data collection, and hours of reconstruction. Form.io’s collision control exists specifically to prevent this scenario.

Collision control is not the same as revision history. Revisions let you look backward at what changed. Collision control operates proactively, detecting when two users attempt to modify the same form and intervening before destructive saves occur. The distinction matters because recovery is always more expensive than prevention.

The Problem: Forms Are Shared Artifacts

Form.io stores forms as JSON schemas. When you drag a field onto the builder, you are modifying a document that lives in MongoDB. That document has one authoritative state at any moment. If User A loads the form, makes changes, and saves, while User B loaded the same form earlier, made different changes, and saves afterward, User B’s save obliterates User A’s work.

This is standard last-write-wins behavior, and it breaks down the moment your organization has more than one person building forms. The pattern fails in predictable situations. Two developers working on different sections of a complex form. A form admin fixing a typo while an architect restructures the layout. Someone testing in a staging environment while someone else works in production. The scenarios multiply as teams scale.

Traditional web applications address this with either pessimistic locking (preventing concurrent edits entirely) or optimistic concurrency (detecting conflicts at save time). Form.io implements the optimistic approach through collision detection that compares document versions and alerts users before data loss occurs.

How Collision Detection Works

When you open a form in the Form.io builder, the system loads the current form JSON along with version metadata. This metadata includes a revision identifier and timestamp. When you save your changes, the platform compares your form’s version against the current server version.

If the versions match, your save proceeds normally. If they differ, meaning someone else saved changes while you were editing, the system alerts you to the collision. You can then choose how to proceed: discard your changes, force your save (overwriting the other changes), or manually merge the modifications.

This detection happens at the API level. The underlying mechanism uses MongoDB’s document versioning to track form state. Every modification increments the form’s internal version number. Save requests include the version number the client started with, enabling the server to detect when that version has become stale.

The collision detection applies to form schema changes, not to submission data. Submission data follows a different lifecycle where concurrent writes to different submissions do not conflict with each other. Collision control specifically protects the form definition itself.

Configuration and Availability

Collision control is part of Form.io’s Security Module, which bundles several enterprise features including form revisions, submission revisions, audit logging, and action logs. The module requires an Enterprise subscription and appropriate licensing configuration.

Once enabled at the project level, collision detection activates automatically for all forms in that project. There is no per-form toggle. Either your project has collision control or it does not. This all-or-nothing approach simplifies administration but means you cannot selectively enable it for some forms while leaving others unprotected.

The feature interacts with Form.io’s Teams and Permissions system. Collision detection does not replace access control. It operates as a safety net for users who legitimately have edit permissions. If someone should not be editing a form at all, restrict their role rather than relying on collision detection to handle unauthorized changes.

Revision History as Collision Recovery

When collision detection triggers, you have decisions to make. The revision system provides context for those decisions by showing exactly what changed between versions. Every published form revision records who made the change, when they made it, and optionally a note explaining the modification.

The revision interface displays a chronological list of all form versions. Each entry includes a Version ID (Vid), the user who published that revision, the timestamp, and any revision notes. You can view any historical version, compare it against the current form, and restore previous versions if needed.

Restoration does not overwrite history. When you restore an old revision, Form.io creates a new revision containing that historical state. The revision chain remains intact. This approach means you can never lose work through the revision interface itself. Even mistakes in restoration are recoverable by restoring an earlier revision.

For complex merges where two users made complementary changes, you might restore an earlier version, then manually reapply the changes from both branches. The Form JSON view helps here since you can compare raw JSON between versions to identify exactly which components differ.

Integration with the Custom Form Builder

Form.io’s custom form builder generates JSON schemas through a drag-and-drop interface. Every component placement, configuration change, and layout adjustment modifies that underlying JSON. Collision control protects all of these modifications, not just the obvious ones like adding or removing fields.

The Enterprise Form Builder Module extends this further by allowing you to provide form building capabilities to your own users through a white-labeled interface. When your application embeds the form builder for end-user customization, collision control still operates. Your customers benefit from the same protection that your internal teams have.

This matters for multi-tenant deployments where different organizations customize forms independently. Tenant A’s users editing their forms cannot collide with Tenant B’s users because tenants operate in isolated project contexts. Collision detection handles conflicts within each tenant’s scope.

When Collision Control Falls Short

Collision detection tells you that a conflict occurred. It does not automatically resolve the conflict. Complex forms with dozens of components and nested structures require human judgment to merge properly. Two developers might have made changes to completely separate parts of a form, in which case manual merging is straightforward. Or they might have both modified the same field with incompatible settings, in which case someone must decide which change wins.

The system also cannot prevent all forms of data loss. If two users save to different environments (production versus staging) and those environments later synchronize, the collision happens outside Form.io’s detection scope. Environment management through Stages and proper deployment workflows address this, but collision control alone does not span environment boundaries.

Draft mode provides a partial workaround for work-in-progress forms. Saving as a draft does not create a published revision, letting you iterate on changes without affecting other users who are working from the published version. Only one draft can exist at a time per form, so drafts themselves can still experience conflicts in multi-editor scenarios.

Architectural Considerations

Collision control imposes minimal performance overhead. Version comparison happens during the save operation, adding a single document lookup to verify version consistency. The check scales linearly with the number of concurrent editors rather than with form complexity or submission volume.

For teams using the Form.io API directly apidocs.form.io, collision detection operates through HTTP headers. When fetching a form, the response includes version metadata. When saving, include that metadata in your request. The API returns conflict errors (HTTP 409) when versions mismatch, letting your integration code handle collisions programmatically.

Self-hosted deployments need no additional infrastructure for collision control. The feature relies on MongoDB’s document versioning capabilities that exist in any supported MongoDB deployment. No external services, message queues, or coordination servers are required.

Workflow Recommendations

Collision control works best as part of a broader form governance strategy. Consider these patterns for teams with multiple form builders.

Assign form ownership. Even with collision detection, having a single responsible owner per form reduces the frequency of conflicts. Owners make major structural changes while others contribute feedback through revision notes or out-of-band communication.

Use drafts for extended work. If a form change requires multiple sessions to complete, save as draft rather than publishing intermediate states. Other editors see the published version while you iterate on the draft.

Coordinate deployments with Stages. Production forms should change through a promotion workflow from staging rather than direct edits. This creates natural synchronization points where conflicts surface predictably.

Leverage revision notes. When saving, document what you changed and why. Future editors (including yourself) benefit from understanding the intent behind each revision when resolving conflicts.

Review the Change Log regularly. Audit logs show all form access and modifications across your project, helping identify patterns of concurrent editing before they become recurring conflicts.

What Collision Control Does Not Replace

Collision control protects form definitions during collaborative editing. It does not address several related but distinct concerns.

It does not prevent unauthorized changes. Use Roles and Permissions to control who can edit forms.

It does not synchronize forms across environments. Use Stages and deployment workflows to manage environment promotion.

It does not merge changes automatically. Human review is required when conflicts occur.

It does not version submission data. Submission Revisions, a separate Security Module feature, tracks changes to individual submissions rather than form definitions.

It does not replace backups. While revisions preserve historical form states, database backups remain necessary for disaster recovery.

Related Capabilities

Collision control integrates with Form.io’s broader versioning and governance features:

  • Form Revisions provides the historical record that collision detection relies on for conflict resolution
  • Form Change Logs records all access and modification events for audit and compliance
  • Teams & Permissions controls who can edit forms in the first place
  • Decoupled Form Updates enables live form changes without redeploying applications
  • Auto Save Forms handles submission-in-progress preservation, distinct from form definition versioning

Resources