Some relationships in your data are compositions: the referenced thing only makes sense in the context of its parent and disappears with it. An order has line items; a survey has questions; an invoice has tax breakdown rows. Yellow models this with owned references — an instance reference constraint flagged as Owned = true.

This walkthrough builds an Order + OrderLine composition end to end.

1. The two models

Create two models in your schema:

OrderLine — represents one line on an order.

  • product — Instance reference to a Product (regular reference; products exist independently).
  • quantity — Integer, required.
  • unitPrice — Decimal, required.
  • lineTotal — Decimal, virtual (quantity * unitPrice).

Order — the parent.

  • number — String, primary property.
  • customer — Instance reference to a Customer.
  • lines — Collection of references to OrderLine.
  • total — Decimal, virtual (sum of lines.lineTotal).
  • createdOn — DateTime.

2. Mark the line collection as owned

On Order.lines, add a Collection constraint with:

  • Item type = INSTANCE_REFERENCE
  • Target model = OrderLine

Then add an Instance reference constraint to the collection's item, with:

  • Target model = OrderLine
  • Owned = true

The Owned flag changes how Yellow treats the relationship:

  • Creating an Order with new OrderLine instances saves them in the same batch — the lines do not exist before their parent.
  • Editing the order can add, remove, or reorder lines inline.
  • Deleting the order soft-deletes every line it owns. Deleting a non-owned reference would leave the target untouched.

3. The form behaviour

Open the Order model and create a new order. The lines collection shows an embedded + Add line button instead of a dropdown — because the lines are owned, the editor knows to create them in place rather than pick from existing ones.

Adding a line opens the OrderLine form inline. Fill it in, save the parent, and both the order and its lines are committed together.

4. Audit and history

Owned references collapse the audit trail: viewing an order's history shows the lines that were active at that point in time. Restoring an earlier version of the order restores its lines too.

When to use owned vs plain references

Use owned when… Use plain reference when…
The child has no meaning without the parent (line items, breakdown rows). The target exists independently (a customer, a product).
Deleting the parent should remove the child. The same target is reused by many parents.
The user expects to manage both at once in a single form. The user picks the target from an existing list.

5. A non-owned reference, by contrast

Order.customer is a plain reference — customers are shared across orders. The form shows a dropdown of existing customers. Deleting an order leaves the customer alone.

The two relationships sit on the same model deliberately: orders own their lines, but they reference customers.