--- title: "Forms and settings" url: https://developers.dagio.ai/forms/ --- # Forms and settings ## A Form serves an operation A Form collects the information needed to perform an Action. Use it to create a client, change settings or prepare a launch. It does not replace the readable, editable record Surface. The Model connects a Form to its operation and Fields. The Field definition owns types and constraints; the Form selects control, label and order. Service-side checks remain authoritative even when the interface already validated input. | Presentation choice | Expected value | Purpose | | -------------------- | ----------------------------------------------------------- | -------------------------- | | Field | Reference to a declared Field | Reuse canonical data | | Control | Text, long text, choice, number, date, boolean or reference | Match the type and options | | Initial value | Declared default or authorized context | Avoid unnecessary input | | Required on creation | Information necessary for the operation | Create a valid record | | Description | Short business guidance | Explain what to provide | ## Creation and editing In **New client**, request Company and Status, defaulting Status to Prospect. After creation, open the record rather than another exhaustive form. Notes, contact details and links grow in the Surface. If the app asks where to add an item, choose a reference from the offered list before completing the Form, such as the book that will contain a chapter. The first result is not selected automatically. Before confirmation, if that reference changes or becomes unavailable, refresh your choice before continuing. If a confirmation response is lost, resuming it retains the choice from the original request. From an open record, an Action such as **Add chapter** can use that exact book as its parent. Check the displayed destination before confirming: creating the child does not replace the parent record or choose another book. The Action remains unavailable in read-only mode or when the reference is no longer authorized. For a linked Field, keep the saved reference or search for and choose another record from the offered list. Clearing the reference is available only when that Field permits it. Searching and choosing do not change the relationship yet: the choice is checked and recorded with the Form confirmation. If its response is lost, resume that same confirmation instead of choosing a target again. Use **Settings** for configuration that does not belong in the main content. A Field retains its value when used in both a Form and a Surface section. If creation requests rich content, it uses the same document editor in place of the previous record, alongside the other Form values. Settings does not contain a second copy of the body. After confirmation, Surface opens the record that was actually created. ## Preserve input When an Action requires evidence, the review presents the criteria, results and sources to check before confirmation. Opening a source does not confirm the Action; your input stays in the Form. Blocking issues remain distinct from information that is still incomplete. The “Human review recorded” notice describes a review that is already retained; it does not start a new execution. When the Model binds a Form to Surface content, rich content stays in the Surface editor. Fields and settings use the same declared controls; **Settings** does not contain another copy of the body. The affected body and values are confirmed in one operation, without a second document save. Formatting, links and document attributes do not pass through a Markdown text conversion. Objects retain their identity and protections; an Hx heading does not constitute a business binding. Before confirming a native document change, review its actual before/after content in the same readonly document view. If that view cannot admit the exact document or its images, confirmation stays unavailable and your original input is retained. Embedded PNG/JPEG images are checked from their actual bytes; a live or unpinned image reference is not replaced by a guessed current image. A document Action proposed in a chat card keeps exactly that proposal for review; it does not replace it with another open editing draft. Confirmation retains the same documents and operation key. Recovering an uncertain response checks that original operation, without pretending that a previously displayed document is a fresh preview or overwriting newer unsubmitted work. When the Model explicitly declares AI context for a launch Form, its prepared and reviewed proposal can include the entered values and rich content bound to the exact document body or declared Surface object. This is proposed content, not a saved document or a launched Flow. Editing that proposal withdraws its AI context until a new valid proposal has been prepared and reviewed. If the complete required context exceeds its limits, Surface refuses the request rather than truncating the document or dropping required sources. A Form holds a draft until confirmation. Closing it, returning or receiving remote updates must respect that draft. Permission refusal, validation errors and uncertain responses identify what needs correcting or checking. Retrying must not create two clients when the first operation was already accepted. If the document changes during review, Surface retains the input and asks you to check the relevant version; it does not silently merge changes. A lost response resumes the same confirmation and values. Once saving is confirmed, a failure to open the record is recovered by reopening it, not by repeating the Action. Explicitly cancelling a new creation abandons its unconfirmed input. Changing views is not cancellation. Before reloading the application, finish or cancel the current creation; retaining its input in the session is not presented as saving the new document. For example, creating North Studio fails because Company is empty. The error attaches to that Field while the email already entered remains available. ## Applied examples : Short creation, complete record Creation asks for Company and Status. Optional notes are expanded later on the Surface. ### Configuration Fragment placed in `forms[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-model-foundation/). ```json { "contract": "WorkspaceForm@2", "key": "new-client", "label": "New client", "actionKey": "create-client", "targetDefinitionPath": "workspace/clients/surface/client", "mode": "create", "fields": [ { "contract": "WorkspaceFormControl@2", "repeatable": false, "key": "company", "label": "Company", "input": "text", "binding": { "kind": "field", "fieldKey": "company" }, "required": true, "ruleKeys": [], "options": [] }, { "contract": "WorkspaceFormControl@2", "repeatable": false, "key": "status", "label": "Status", "input": "choice", "binding": { "kind": "field", "fieldKey": "status" }, "required": true, "ruleKeys": [], "options": [ "prospect", "active" ] } ], "ruleKeys": [] } ``` ### Variation and connection Fragment placed in `forms[].fields[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-model-foundation/). ```json { "contract": "WorkspaceFormControl@2", "repeatable": false, "key": "notes", "label": "Notes", "input": "multiline", "binding": { "kind": "field", "fieldKey": "notes" }, "required": false, "ruleKeys": [], "options": [] } ``` ### UI layout example The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations. 1. Company * 2. Status * 3. Notes 4. Create client