Containment & Child Objects

account_tree Sometimes the clearest way to describe a model isn’t a web of arrows — it’s a hierarchy. A business concept like Customer isn’t just related to its hub, satellites, and links; it contains them. ADL models this directly: a data object can hold other data objects as child objects, and the Design screen draws them nested inside their parent.

How containment works

Containment is just a relationship with the type contains. The parent owns the relationship, and it points at the child:

{
  "name": "Customer contains HUB_CUSTOMER",
  "type": "contains",
  "cardinality": "NotDefined",
  "relatedDataObjectId": "4be15484-6450-4e43-a417-64c9a539de88"
}

That’s the whole storage model — a normal entry in the parent object’s relationships list. Because it’s plain metadata, containment is versioned, diffable, and template-accessible like everything else in ADL.

A few rules keep hierarchies sane:

An object can be contained by only one parent at a time.
Multi-level nesting is supported: containers can hold other containers.
Cycles aren’t allowed: ADL refuses containment that would make an object its own ancestor.

Creating child objects

There are two main ways to nest an object into another:

On the Design canvas (Model mode), drag an object into a container and drop it. ADL authors the contains relationship on the parent for you. Drag it back out to remove the containment.
On the Relationships tab of a data object, add a relationship and choose the type contains (it’s one of the suggested types). Cardinality doesn’t apply to containment and is set automatically.

The Relationships tab shows both directions: an outgoing contains row is chipped Child (this object contains the related one), and an incoming one is chipped Parent (this object is nested inside the owner). Incoming rows are read-only — containment is managed on the parent — with a shortcut to open it.

What you see

On the Design screen in Model mode, children render inside their parent’s node, and the contains edge itself is hidden: the nesting is the relationship. Collapsing a container rolls its internal relationships up into aggregated edges.
Nesting is a Model-mode visualization; in the Design screen’s Directed Graph mode, the same relationship participates as a regular edge.
The tree navigator (the object tree on the Design screen) mirrors the hierarchy, listing child objects under their parent.

For projects with configured relationship rules, a rule can also mark other relationship types as rendering like containment — so a domain-specific type of your own can nest objects the same way.

Where it shines: business concept ensembles

The Data Vault Physical Data Warehouse sample uses containment for ensembles: business concepts like Customer, Membership, Offer, and Segment are modeled as concepts that contain their Data Vault components — the hub, its satellites, and related links. On the Design screen, a stakeholder sees five business concepts; expanding one reveals the technical objects inside it. Same metadata, two altitudes.

This works well anywhere a hierarchy communicates better than a graph:

Business concepts containing their technical implementations (Data Vault ensembles).
Subject areas or domains containing their objects.
A logical entity containing the physical variants derived from it.

Tips

Use sticky-note-styled concepts as containers. A business concept with a sticky-note style makes an inviting drop target and reads clearly as a grouping, not a table.
Group for your audience. Containment pairs naturally with personas — a business persona can look at concepts while a developer persona works with the objects inside.
Containment is metadata, not just layout. Unlike dragging nodes around, nesting survives redraws and travels with the project — and templates can read the contains relationships too.

What’s next?

Design is where containment is drawn and edited.
Data Objects covers the Relationships tab with Parent/Child rows.
Perspectives lets you save arranged views of your nested model.