Containment - the spatial tree

Every physical thing in an IFC model is meant to be contained in a spatial element. A wall belongs to a storey, the storey belongs to a building, the building sits on a site, and the site belongs to the project. The tree itself is required: a storey that belongs to nothing makes the file invalid. Putting things into the tree isn’t policed the same way, and a wall that belongs to nowhere is still a valid file, but as the rest of this page shows, almost nothing can use a wall that isn’t contained somewhere.

This hierarchical arrangement is defined by the IFC standard; this is the spatial tree:

IfcProject
  IfcSite
    IfcBuilding
      IfcBuildingStorey
        IfcSpace

Two relationships are involved. The spatial tree itself is held together by aggregation: a building is made of its storeys, the way a stair is made of its flights. Containment is what puts objects (rather than spatial elements) into that tree - your wall is contained in a storey.

This page is about containment; aggregation and the model’s other relationships are described separately.

Containment is how an object knows where it is

The temptation is to read the tree as a filing cabinet - a tidy way of grouping things, like folders. It isn’t. It is the route for every object to find its own location in the building.

Ask your model a question that mentions a floor and this is the mechanism that answers it. A drawing label that prints the storey name, or a schedule grouped by building, works by starting at the object and walking up the tree until it meets the kind of container it was asking about. Nothing else in the file records that a door is on the second floor. The tree records it, and only the tree.

So an uncontained element isn’t merely untidy. It has no storey, so it has no floor level, so it appears on no plan, in no schedule grouped by anything, and with a blank where its location should be. It is in the file and it is nowhere in the building.

Bonsai doesn’t really let you forget

A new project in Bonsai isn’t empty. Bonsai creates a file with a basic tree - a project, a site, a building and a storey - so there is somewhere for the first wall to go.

Bonsai keeps track of a default container, the storey you are currently working on, so every building element you create is assigned to it at the moment of creation. Opening an existing file works the same way: Bonsai picks the first storey it finds, and that is where your new elements go unless you change the default container.

Spatial elements such as buildings and storeys can have their own coordinate space (sometimes called a UCS), so switching to a different container will switch the X and Y directions if they differ.

Models that arrive from elsewhere can vary: an uncontained element is one of the commoner things to find in a file somebody has exported for you, and nothing on screen will tell you, so it is worth looking.

Where a thing is vs. where it is drawn

An object’s place in the spatial tree and its position in three-dimensional space are separate facts, and don’t have to be related.

An element contained in Level 2 can be modelled at any height at all, including below the ground floor, and this wouldn’t make the file invalid: the tree is a statement about the building, the coordinates are a statement about geometry, and the standard doesn’t require the two to agree. What Bonsai does when you draw something is put it in the storey you are working on - a sensible guess, not a measurement. It doesn’t consult the elevation, and it can’t notice later if the object moves.

You do want the two to agree, but this is something you maintain rather than something you are given, so it is something to test. The geometry can’t be appealed to as a second opinion, and looking at a model tells you only what it looks like, which is why checking the model is a separate activity.

What to unlearn from Revit

A level in the Revit world is a datum as much as a label: a plane at a height, which views are taken from and which objects are constrained to, so the level is part of what holds the geometry where it is. An IfcBuildingStorey does none of that work. It is a container; its elevation is an attribute like any other rather than its purpose, and building elements are not constrained to this elevation.

Another habit to unlearn is assuming there is just one building. IFC expects buildings to be in a site and allows several sites each with multiple buildings: a project can hold three buildings, or no building at all. If you have ever fought a single-building assumption on a campus job, this is the part to enjoy.

The project is at the top of the tree

At the top of the tree, above sites, is the project, and there can be only one. The units, georeferencing and schema version belong to the project as a whole rather than to anything in the tree beneath it.

Containment is the one relationship you can’t leave out

Types can be omitted, properties can be sparse, an object can have no geometry at all, and the model remains usable. An object with no container is one that quietly disappears from every drawing and every schedule, all while staying perfectly visible on your screen.

Last updated 6 October 2026.