Containment - the spatial tree

Every physical thing in an IFC model is assigned to somewhere. Not usually, not by convention - as a matter of structure. 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.

IfcProject
  IfcSite
    IfcBuilding
      IfcBuildingStorey
        IfcSpace

That is the spatial tree, and an element that is not somewhere on it is not properly in your model, however solid it looks in the viewport.

One distinction is worth drawing straight away, because The model is a graph of standard objects makes a point of it. The 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 things into that tree - your wall is contained in a storey. Two different relationships, and it is the second one this page is about.

Containment is how an object knows where it is

The temptation is to read the tree as filing - a tidy way of grouping things, like folders. It is not. It is the route by which every object finds out anything about 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, a schedule grouped by building, a door tag that includes the room it opens into - each of those 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 is not 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 does not really let you forget

The good news is that this is largely handled for you, and handled early.

Bonsai keeps a default container - the storey you are currently working on - and every element you create is assigned to it at the moment of creation. You do not opt in, and there is no separate step to remember. When you open a project Bonsai works one out for itself, walking down from the project through the first site and the first building to the first storey it finds.

That leaves one way to make an orphan of your own: creating something when there is no container to put it in, which in practice means a project that has no storey yet. It is worth knowing, because it tends to happen in the first ten minutes of a project rather than in the middle of one.

Models that arrive from elsewhere are another matter. An uncontained element is one of the commoner things to find in a file somebody has exported for you, and since nothing on screen will tell you, it is worth going and looking.

Where a thing is, and where it is drawn

An object’s place in the spatial tree and its position in three-dimensional space are two separate facts, and nothing holds them together.

An element contained in Level 2 can be modelled at any height at all, including below the ground floor, and the file is not thereby invalid. Nothing stops you and no validator will complain, because neither has grounds to: the tree is a statement about the building, the coordinates are a statement about geometry, and the standard does not require the two to agree. What Bonsai does when you draw something is put it in the storey you are working on. That is a sensible guess, not a measurement - it does not consult the elevation, and it cannot notice later if the object moves.

You want the two to agree, obviously. The point is that agreement is something you maintain rather than something you are given, and it is therefore something to test. Which is the same lesson as the section above arriving from the other side: the tree is the only record of which floor a door is on, and the geometry cannot be appealed to as a second opinion. It is also the argument Checking the model is built on, that looking at a model tells you what it looks like and nothing more.

What to unlearn from Revit

If you are arriving from Revit, the habit to examine is what you think a level is.

A level in that world is primarily a datum - a horizontal plane at a height, which things get associated with. An IfcBuildingStorey is a container, and its elevation is one of its attributes rather than its purpose. The difference shows up in what you can say. Objects belong to a storey, so the question “what is on this floor” has an exact answer that does not depend on anybody’s geometry being tidy.

The other habit is assuming there is one building. IFC expects a site above the building and allows several of each: a project can hold three buildings on one site, or a site with no building on it at all. If you have ever fought a single-building assumption on a campus job, this is the part to enjoy.

Two project-level decisions to get right early

Units and georeferencing are properties of the project rather than of anything in it, they are set once, and they are irritating to change later. Both are worth five minutes at the start.

Units are chosen when the project is created - Bonsai’s new-project menu offers metric and imperial starting points, and the choice applies to the whole file. IFC stores lengths in the project’s units, so this is not a display preference that you can flip when a consultant complains.

Georeferencing is the question of where in the world the model sits. The minimum is a projected coordinate reference system, named by its code in the public EPSG registry, and it is worth being precise about what counts. A model whose coordinates are large real-world numbers is not thereby georeferenced. Without a declared reference system those are just big numbers, and nobody receiving the file can tell what they are measured from.

There is one hard constraint, and it is the clearest illustration of why schema version is a real question. IFC2X3 cannot carry georeferencing at all. If your project needs to sit properly on a site, that decides the version for you, and it decides it on day one rather than on the day the surveyor asks. The georeferencing guide covers the detail, including true north, which is a separate matter from grid north and catches people out.

Why this page comes first among the details

Containment is the first of the relationships in The model is a graph of standard objects, and it is the one with the least room for opinion. Types can be omitted, properties can be sparse, an object can have no geometry at all - and the model remains usable. Containment is the one where leaving it out quietly removes an object from every drawing and every schedule you will ever generate out of the model, while leaving it perfectly visible on your screen.

Last updated 4 September 2026.