Nested fields

xDBML lets fields have structured types: objects with their own sub-fields, arrays of elements, oneOf alternatives, maps, sets, and so on. The diagram renders these structures as indented rows inside the entity card, with disclosure carets that let you collapse or expand them.

📸 Screenshot placeholder

[Screenshot needed] Filename suggestion: nested-fields-expanded.png Caption: An entity card with a nested object and an array of objects, both expanded to show their children. Should show: a single entity card (e.g. a customer record from the e-commerce or FHIR example) tall enough to show several levels of nesting. At least one object {...} field expanded, one array of object expanded, and ideally one polymorphic oneOf row visible. Disclosure carets (▾ or ▸) clearly visible on the parent rows.

Indented rows

When a field's type is structured, the field appears as a normal row, and its children appear as indented rows immediately below it. Indentation depth equals nesting depth: a top-level field is at indent 0, its direct children at indent 1, their children at indent 2, and so on.

The indent unit is small (12 pixels), so even deeply nested fields stay within the entity card width. Indent guide lines, drawn as faint vertical strips, help your eye follow which child belongs to which parent.

The disclosure caret

Parent rows (rows whose field has children) carry a small caret at the start of the row:

• ▾ (downward-pointing) when expanded; clicking collapses
• ▸ (rightward-pointing) when collapsed; clicking expands

Clicking the caret toggles the collapse state. Only that one row's children are affected; other parent rows keep their state. Collapsing hides all descendants, not just direct children.

The caret has a generous transparent hit area around the visible icon, so accidentally-imprecise clicks still register.

Synthetic rows

Some structural types have intermediate rows that don't correspond to user-written field names. These are called synthetic rows and are rendered in italic to distinguish them from real fields:

Synthetic rows you'll see:

• [item] for the element type of an array. If the array's element has its own name in the source (some xDBML variants allow this), that name appears instead.
• {card}, {check}, etc. for the named alternatives of a oneOf, anyOf, or allOf polymorphism. The braces signal "this is one of multiple alternatives."
• <key> and <value> for the key and value types of a map.
• <item> for the element type of a set.
• [0], [1], etc. for the positions in a tuple.

You can't click a synthetic row to inspect it (in the current version); clicking it opens the inspector for the parent named field. A future version may add synthetic-row inspection for showing the structural details of array/oneOf/map types.

What gets collapsed and what stays

Collapsing a parent hides all of its descendants, regardless of depth. So collapsing a top-level addresses array hides not only [item] but also every field inside the array element's object type. Expanding shows them all back.

If you want to collapse only some descendants, click the carets at the depth you want; each parent toggles independently. The diagram supports any pattern of partial collapsing.

Collapse state persists

The collapse state for every field path is saved to your browser's local storage, scoped per entity. So if you collapse addresses.[item] in the customers entity, that state is restored on reload, even if you edit the schema between sessions (as long as the field path still exists).

If you rename a field or restructure the entity such that a previously-collapsed path no longer exists, the stored state is harmless: it simply doesn't apply to anything.

Selecting a nested field

Clicking on any field row, at any depth, selects that field. The inspector opens and shows the full dotted path under "Identification" so you know exactly where in the structure the field lives.

The inspector's "Path" line might read addresses.[item].street or payment_method.{card}.last4 to reflect the synthetic rows traversed to reach the leaf.

Why nesting is part of xDBML

Nested structures are a first-class concept in document databases (MongoDB, Cosmos, Couchbase) and increasingly in relational databases that support JSON columns. xDBML supports them natively so a single language can describe both flat relational tables and richly nested document schemas. The playground's nesting visualization is built to handle both cases without forcing a flatten-to-rows transformation.

What's next

• Entity cards: the cards that hold the nested rows.
• Visual cues at a glance: the compact reference for all of the visual signals.
• Inspector pane: the metadata view that shows full structural detail on selection.