Form Fields

A form's fields array is an ordered list of field definitions rendered top to bottom. Each field is one of five kinds, discriminated by a kind property. Table-bound fields inherit their type and validation from a table column; standalone fields are typed inline; calculation, section, and signature fields cover computed values, dividers, and signatures.

forms:
  - id: 1
    name: signup
    title: Create your account
    submitTo: { table: users }
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: newsletter, inputType: checkbox, label: Subscribe to updates }

Field Kinds

Common Field Properties

Every input-bearing field kind (table-field, standalone, calculation, signature) shares a common base.

Table-Bound Fields

A kind: table-field references a column on the form's submitTo.table. The field type, validation, and persistence all come from the table schema — the form supplies only display concerns plus, for attachment columns, upload options.

fields:
  - kind: table-field
    column: subject
    label: What can we help with?
    placeholder: Briefly describe the issue
  - kind: table-field
    column: priority
    helpText: Urgent issues are triaged first

Attachment columns (single-attachment, multiple-attachments) automatically render a file input. See File Uploads for the upload pipeline and bucket binding.

Standalone Fields

A kind: standalone field is typed inline via inputType and is not written to a table column directly. It is ideal for forms that route to an automation or live only in the submission ledger.

Available inputType values: short-text, long-text, email, url, phone, number, date, datetime, select, multi-select, checkbox, radio, rating, attachment.

fields:
  - kind: standalone
    name: rating
    inputType: rating
    label: How was your experience?
    required: true
  - kind: standalone
    name: source
    inputType: select
    label: How did you hear about us?
    options:
      - { value: search, label: Search engine }
      - { value: referral, label: Referral }
      - { value: social, label: Social media }

Calculation, Section & Signature Fields

fields:
  - { kind: standalone, name: quantity, inputType: number, label: Quantity }
  - { kind: standalone, name: unit_price, inputType: number, label: Unit price }
  - kind: calculation
    name: total
    label: Total
    formula: '{{quantity}} * {{unit_price}}'
    format: currency

Prefill

The top-level prefill map seeds field values at render time. Keys are form field names; values are either a literal default or a reference:

forms:
  - id: 1
    name: lead-capture
    title: Request a demo
    submitTo: { table: leads }
    prefill:
      utm_source: $query.utm_source
      utm_campaign: $query.utm_campaign
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: utm_source, inputType: short-text, hidden: true }
      - { kind: standalone, name: utm_campaign, inputType: short-text, hidden: true }

Inline Relationship Create

When a form is embedded inside a parent record's detail page (e.g. a "+ New ticket" button on a Project page), the $parent.{path} prefill source ties the new child back to its parent automatically. This is configured on the page form control via inlinePrefill.

forms:
  - id: 1
    name: new-ticket
    submitTo: { table: tickets }
    fields:
      - { kind: table-field, column: title, required: true }
      - { kind: table-field, column: project_id }
      - { kind: table-field, column: reporter_id }

pages:
  - id: 1
    name: project-detail
    path: /portal/projects/:id
    components:
      - type: form
        formRef: new-ticket
        inlinePrefill:
          prefill:
            project_id: $parent.id # locked to the current project
            reporter_id: $user.id
          lockPrefill: true

On submit, the engine revalidates parent existence to defend against stale $parent references. Both single and multi-relationship columns are supported.

Related Pages

• Forms Overview — form metadata, submit targets, access control.
• Conditional Logic — visibleWhen / requiredWhen / disabledWhen.
• Field Groups — labeled sections that group these fields on one page.
• Prefill — the prefill map in full, including hidden-field attribution.
• Multi-Step Forms — distributing fields across steps.
• File Uploads — attachment input options and bucket binding.
• Relational Fields — the relationship columns $parent targets.
• Form Controls — the page component that hosts formRef + inlinePrefill.