The model is a graph

An IFC file is a carrier bag full of everything to do with a building project. Geometry, yes, but also schedules, tasks, costs, materials, the people and organisations involved, the systems that run through the building - all of it in one container.

It is a bag packed to a published standard. Every item in it is labelled, and relationships between them are prescribed rather than left to whoever did the packing.

Not quite everything is in the bag: issues, comments and the questions people raise about a model go separately, maybe as BCF issues or using other issue trackers.

Most things in the bag have no 3D geometry

Open a model in a viewer and you see walls, slabs, columns and pipes, because those are the objects that happen to carry geometry. They are a minority of what is in the file.

The rest has no specific geometry: property sets, classification references, materials and their layers, tasks and their sequences, cost items, actors and the organisations they belong to, systems and the elements assigned to them, groups and zones. None of that appears in a viewport, but this is most of a well-constructed IFC model.

Given an IFC file, you might open it in a viewer, look at the walls, and judge the parts of the file that happen to be visible. But looking at an IFC model isn’t the same as knowing what is in it; in Bonsai there are dedicated ways of finding things and checking the model.

The terminology is IFC’s, not Bonsai’s

Every object in the file belongs to a class from the IFC schema, and the schema is published by buildingSMART, not by the authors of Bonsai. A wall is an IfcWall, a door an IfcDoor, a space an IfcSpace.

There are two levels to this. The class says what kind of thing it is, and a predefined type narrows it down: an IfcWall may also be PARTITIONING, or SHEAR, or PARAPET - this list of permitted predefined type names is part of the IFC standard too.

This sounds like a limitation but it has real benefits. No program can quietly add to that vocabulary, Bonsai included, and that constraint is exactly what makes it possible for many unrelated programs to open the same file and agree about what is in it.

That doesn’t mean you can never name anything yourself. Where none of the predefined types fits, the value you set is USERDEFINED, and the object can then carry your custom name (typically all-caps). The word is yours, but everybody else’s software knows where to look, and knows that what it finds there is yours rather than the IFC standard’s. A similar arrangement is used for custom property sets.

Objects, and the relationships between them

The schema also defines relationships, and in IFC a relationship is itself an entity in the file. A wall is contained in a storey; a door is an occurrence of a door type; a wall has a property set attached to it; an opening voids a wall and a window fills that opening. Each of those is a relationship entity in its own right, with its own identity.

Two of these relationships are easily confused. Containment says where a thing belongs - the storey it stands in. Aggregation says that a thing is composed of other things: a curtain wall is an assembly of panels and mullions, a stair of flights and landings. Elements are contained in a storey, but assembled elements belong to the aggregate, which can then be contained in the storey.

This is how things are arranged in the bag: objects, plus the relationships that join them. The word for a structure like this is a graph - not a chart with axes on it, but a network of things and the connections between them, like a family tree or a route map. Your building is a graph, and any question you have is answered by starting at some object and following the connections.

The relationships you will work with most each have a page: the spatial tree, types and occurrences, properties and materials and representations.

Names and identifiers

An object in an IFC file can be identified in multiple ways, and they are easy to confuse.

The Name is the label people read: W01, or Level 2 corridor. It is an ordinary attribute and can be edited freely. IFC doesn’t require names to be unique, though many project specifications do, so uniqueness is something you check for rather than something the format gives you.

The Tag is the mark of one particular occurrence - a door number, a serial number - and it is what a tag on a drawing usually prints. Only elements and their types have one; a space or a storey doesn’t.

The Description is a longer name that you would want to appear in a table, but not as a label on a drawing.

The step id is the line number in the file - #1043 and the like - and Bonsai keeps it stable across saves. It sounds like an implementation detail, but it is what lets revisions track which objects changed between two saves.

The GlobalId is a unique 22-character code, such as 1yLHjxekzC6RoKjk8PwIoc, and it is what travels between organisations. It follows an object out of your file and into somebody else’s federated model; an issue raised against your work needs to point to this GlobalId. Bonsai has little use for GlobalIds day to day; they come into their own when you work with other people’s models.

The vocabulary is versioned

The schema is published in versions - IFC2X3, IFC4 and IFC4X3 are among those in current use - and each file is written to one of them. Choosing one is among the decisions to settle when you start a project.

The bag is a metaphor borrowed from Ursula Le Guin’s The Carrier Bag Theory of Fiction (1986), which argues that the container was the first and most underrated of tools, and that we tell stories about the spear instead because a thing that comes to a point makes the better story. A file format built to hold everything about a building isn’t a bad illustration.

Last updated 6 October 2026.