The Binding Object

ControlBinding Type

// packages/types-js/src/form.types.ts

interface ControlBinding {
  /** The data source to read from and write to */
  source:   '$json' | '$context';

  /** Dot-notation path within the source object */
  path:     string;

  /** If true: reads from source on load, but does NOT write back on change */
  readOnly?: boolean;

  /** Optional transform pair applied on read and write */
  transform?: {
    /** Applied when reading from the source — format for display */
    read?:  string;  // Named transform registered with registerBindingTransform()
    /** Applied when writing to the source — parse before save */
    write?: string;  // Named transform registered with registerBindingTransform()
  };
}

Minimal Binding

{
  "binding": {
    "source": "$json",
    "path":   "applicant.firstName"
  }
}

Read-Only Binding

// Shows the value but does not write it back when the user changes it
// Useful for displaying context data alongside editable fields
{
  "id":    "tenant-name",
  "type":  "label",
  "binding": {
    "source":   "$context",
    "path":     "tenant.displayName",
    "readOnly": true
  }
}

Binding With Transform

// Display a stored ISO date string (2026-01-15) as a localised date (15 Jan 2026)
// Parse the user's localised input back to ISO before saving
{
  "id":   "contract-date",
  "type": "date-picker",
  "binding": {
    "source": "$json",
    "path":   "contract.startDate",
    "transform": {
      "read":  "isoToLocaleDate",   // registered transform
      "write": "localeDateToIso"    // registered transform
    }
  }
}

Field Reference

Controls Without a Binding

Omitting the binding property is valid and common for display-only controls (labels, dividers, articles, charts) and for controls whose values are not persisted (e.g., a search bar that filters an in-page list):

// No binding — value is local to the form and not submitted
{
  "id":   "search-filter",
  "type": "text",
  "placeholder": "Search..."
  // binding omitted: value held in form state but not written to any external path
}