--- title: "Fields and values" url: https://developers.dagio.ai/fields/ --- # Fields and values ## Define data once A Field belongs to a Surface definition. It has a stable key, value type and constraints. Views and Forms reuse that definition; displaying a Field in two places does not create two values. Storage type and interface control answer different questions. A status choice can be stored as text and displayed in a dropdown. Notes remain text, while their Surface presentation becomes an editable section. | Definition field | Options / expected values | Description | | ---------------- | ----------------------------------------- | ------------------------------------------ | | key | Stable key, such as company or status | Identifies the Field in references | | type | boolean, date, datetime, number, text | Canonical value type | | required | true or false | Requires a value under the object contract | | repeatable | true or false | Admits a list of values of the same type | | default | Declared value type; list when repeatable | Admitted initial value | | options | String list for declared choices | Constrains suggested and admitted values | ## Choose Surface or Settings Placement belongs to record presentation. A Fields section selects paths such as `fields/company` or `fields/notes`. Settings configuration selects Fields for the **Settings** form. Use the Surface for information people read and enrich frequently; use Settings for configuration. Creation requirements are independent of placement. If Company is necessary to create a client, **New client** must request it even though it later appears in the Surface. The interface must not make creation impossible by hiding a required value. A long-text Field and a Surface’s rich body are not the same data. The former keeps its Field value; the latter uses its content binding in the Form and the same document editor. Selecting a `multiline` control does not by itself turn a Field into a document. Fields placed in the Surface or **Settings** and the declared body share the same edit confirmation, without competing saves. ## Review your changes after an update If a record changes while you are editing, **Read the current record** preserves your draft and reads its current version. For stored, non-repeatable Fields, Surface can prepare a new review of only your explicit changes, including `0`, `false` or a cleared value. Values that were merely loaded are not treated as edited. Check the result before saving: rereading saves nothing. If the same Field changed in the meantime, even if it returned to its original value, preparation is refused and your draft stays intact. This path does not merge the title, rich content or relationships. If a submission's confirmation is not received, retry the same request instead of preparing another change. ## Example: client status ```json { "key": "status", "type": "text", "required": true, "repeatable": false, "default": "prospect", "options": ["prospect", "active", "inactive"] } ``` Stored values remain stable; the Model associates readable labels such as Prospect, Active and Inactive. A record can show a combobox, a table a badge and a Query a filter using this same value. ## Repeated values and long text Use repetition for multiple values rather than numbered Fields. Traits, skills or contact methods can grow without adding trait1, trait2 and trait3 to the Model. A long text section uses its heading as a landmark with editable content beneath it; the Surface still owns object content, identity and protection rules. Linked value inspection reads authorized sources without changing records or activating a relationship. It distinguishes an absent value, empty text, `0` and `false`; an unavailable inventory does not become an empty result. View choices keep the labels declared for the collection, record or Home. A declaration without a usage label remains unavailable instead of receiving an invented title. To activate a linked value, use Owner access to both Workspaces and their affected Spaces to review every source record and explicitly choose an authorized target, or no link when the source field allows it. Existing values never guess the target. Review the complete before-and-after impact before confirming; an interrupted confirmation is retried as the same request. Editing the relation’s labels, state, limits or preview views preserves its existing links and reference captures. Reassigning those links is a separate explicit review, not a side effect of changing the settings. When a Field offers a configured relationship, choose from the offered references and respect the displayed limits. This selection concerns links: it does not replace the Field input or the Form draft. ## Applied examples : Required text and business choices Company uses required text input; Status uses a declared list of choices. ### Configuration Fragment placed in `forms[].fields[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-model-foundation/). ```json { "contract": "WorkspaceFormControl@2", "repeatable": false, "key": "company", "label": "Company", "input": "text", "binding": { "kind": "field", "fieldKey": "company" }, "required": true, "ruleKeys": [], "options": [] } ``` ### 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": "status", "label": "Status", "input": "choice", "binding": { "kind": "field", "fieldKey": "status" }, "required": true, "ruleKeys": [], "options": [ "prospect", "active" ] } ``` ### 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. Client identity 2. Notes and follow-up 3. Settings 4. Linked quotes