Understanding Forms
A Form is a reusable merchant artifact describing a collection schema known at design time. It has a stable identity, immutable revisions, and Releases independent from the processes that use it.
Definition and schema
The definition form carries the durable identity of the Form: identifier frm_…, key, name, description, merchant, and activation state. Executable content is the schema of its Working revision: an ordered list of fields. Each field separates its data contract value_type from its UI control control, then carries its constraints and protection policy.
The Form keeps a stable identity; Working evolves, a Release publishes a snapshot, and a saved process pins an exact revision.
The Form describes the reusable schema. The node custom_form is the user action that presents this schema in a process and waits for the participant's response.
Fields and protection
Field types supported by the current contract are:
text, textarea, email, phone, password, url, integer, number, rate, country, currency, amount, address, select, radio, checkbox, date, datetime, file
Choice fields carry their options, file fields declare an allowed upload purpose, and available constraints depend on type: lengths, numeric bounds, safe pattern, or file count. Semantic controls directly produce the Ormuz values expected: amount produces a common.amount in minor units with an explicit currency, address produces a single common.address, and country, currency, url or rate controls preserve their canonical subtype. Field keys are unique within a schema.
A field may also declare a protection class:
normal, sensitive, secret. That classification then follows the collected value into the process; it is not merely a visual attribute of Form Studio.
Working, revisions, and Releases
Changing the schema creates a new Form revision immutable revision and moves the
working_revision_id pointer of the definition. Schema writes use the expected revision and
content_hash to reject a save based on a Working revision that has become stale.
A Form Release publishes one precise revision. Definition status active remains a separate dimension: it replaces neither Working, revision, nor Release.
When a process uses a Form, its snapshot preserves the exact Form revision and content hash. A later change to Form Working therefore does not retroactively modify already-saved process snapshots. See Use a Form in a process.
Form or dynamic form?
| Need | Contract | When to use |
|---|---|---|
| Reuse a named schema edited and versioned independently from the process | form resource + revision fdr_… | custom_form |
| Build questions during execution | common.form_spec produced at runtime, without a persisted Form resource | dynamic_form |
A dynamic form is frozen in the user action that presents it, but it does not become a reusable Form. Use a Form when schema identity, independent editing, and versioning are part of the product need.