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

{
  "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.

{
  "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.

{
  "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

SurfaceClients / North StudioExample

Fields and valuesRequired text and business choices

Clients

NS

North StudioActive client · Professional services

StatusActive ⌄

Notes and follow-up

The client wants a proposal for a new project. Clarify requirements and confirm the budget before review.

Editable text on the Surface

Record settings