Atlas Forms
Path Syntax
Binding paths use dot notation to address properties within the source object. The engine resolves paths at load time to read initial values, and at change time to write updated values. The same syntax applies to both $json and $context sources.
Basic Dot Notation
// Source object:
// { "firstName": "Jane", "lastName": "Smith" }
"path": "firstName" // → "Jane"
"path": "lastName" // → "Smith"Nested Objects
// Source object:
// { "address": { "street": "10 High St", "city": "London", "country": "GB" } }
"path": "address.street" // → "10 High St"
"path": "address.city" // → "London"
"path": "address.country" // → "GB"Deeply Nested
// Source object:
// { "company": { "billing": { "address": { "postcode": "EC1A 1BB" } } } }
"path": "company.billing.address.postcode" // → "EC1A 1BB"Array Indexing
// Source object:
// { "contacts": [ { "type": "email", "value": "jane@example.com" },
// { "type": "phone", "value": "+44 20 1234 5678" } ] }
"path": "contacts[0].value" // → "jane@example.com"
"path": "contacts[1].value" // → "+44 20 1234 5678"
"path": "contacts[1].type" // → "phone"Root-Level Array
// Source object:
// [ "apple", "banana", "cherry" ]
"path": "[0]" // → "apple"
"path": "[2]" // → "cherry"Path Syntax Reference
| Syntax | Accesses | Example Path | Example Source |
|---|---|---|---|
field | Top-level property | firstName | { firstName: "Jane" } |
a.b | Nested property | address.city | { address: { city: "London" } } |
a.b.c | Deeply nested | a.b.c | { a: { b: { c: 42 } } } |
arr[n] | Array element by index | items[0] | { items: ["first", "second"] } |
arr[n].field | Property of array element | contacts[0].email | { contacts: [{ email: "..." }] } |
What Happens When the Path Does Not Exist?
| Scenario | Behaviour |
|---|---|
Path resolves to undefined | Control initial value is undefined → uses control's defaultValue if set, otherwise empty |
Intermediate object is null | Same as undefined — treated as missing |
| Array index out of bounds | Same as undefined |
| Path on a non-object | Logged as a warning; value treated as undefined |
Use Shallow Paths Where Possible
Shallow paths (e.g.,
firstName) are easier to map when your API returns flat DTOs. If your API returns nested objects, use a transform on the server to flatten before passing as initialValues, rather than using deeply nested binding paths. Shallow paths are also easier to maintain when the API schema changes.