The model is a graph of standard objects

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 the one container, which you can pick up and hand to somebody.

It is a bag packed to a published standard. Every item in it is labelled, and where each kind of item goes is prescribed rather than left to whoever did the packing.

Most of what is in the bag has no shape

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 shape at all and is never drawn. 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, and all of it is the model.

You very likely knew this already; the difficulty is that nobody acts on it. Handed an IFC file, the ordinary thing is to open it in a viewer, look at the walls, and form a judgement about the one part of the file that happens to be visible. It is the same mistake that makes people believe IFC is a poor format: judging the whole by the surface that shows. It is also why Finding things and Checking the model both exist, because looking at a model is not the same as knowing what is in it.

The words are not Bonsai’s

Every object in the file is an instance of a class from the IFC schema, and the schema is published by buildingSMART rather than by the makers of any program that edits it, Bonsai included. A wall is an IfcWall, a door an IfcDoor, a space an IfcSpace.

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

The consequence is worth stating plainly, because it sounds like a limitation and is the opposite. No program can quietly add to that vocabulary. If the schema has no way to express something, neither Bonsai nor anybody else’s software can make a word up and write it into your file as though the standard had always had it. That constraint is exactly what makes it possible for a dozen unrelated programs to open the same file and agree about what is in it. A format that let every vendor add its own vocabulary would be a format that only its own vendor could read.

Which is not to say you can never name anything yourself. The standard provides for the case: where none of the predefined types fits, the value you set is USERDEFINED, and the object carries a name of your own alongside it. The word is yours; where it goes is not. Anybody else’s software knows the field to look in, and knows that what it finds there is yours rather than the standard’s own. The escape hatch is part of the published vocabulary rather than a way round it - the same arrangement as the custom property sets in Properties and materials.

Objects, and the relationships between them

The other half of the schema is relationships, and in IFC a relationship is itself a thing in the file rather than a line drawn between two others. 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 an entity in its own right, with its own identity.

One of them is worth separating out now, because it is easily mistaken for another. Containment says where a thing is - the storey it stands on. Aggregation says what a thing is made of: a curtain wall is an assembly of panels and mullions, a stair of flights and landings. The whole is contained in the storey; the parts belong to the whole rather than to the storey. Both point from an object to something above it and they answer different questions, so check which one you are looking at before concluding that somebody has filed things badly.

That is the shape of the whole model: objects, and objects that join objects. Which relationships matter, and how you work with them, is the next several pages - The spatial tree, Types and occurrences, Properties and materials and Representations.

Two kinds of name

Objects in an IFC file keep their identity, and there are two mechanisms for it, which are easy to confuse.

The line numbers in the file - #1043 and the like - are step ids, and Bonsai keeps them stable across saves. That sounds like an implementation detail and is the reason Revisions work at all: because an object stays on the same line, a plain textual comparison of two saves says which objects changed, rather than reading as a rewrite of the whole file.

GlobalIds are the other kind, and they are for travel between organisations. They are long, unique, and they follow an object out of your file and into somebody else’s federated model, which is what an issue raised against your work needs in order to point at anything. Bonsai has comparatively little use for them day to day. They come into their own in Other people’s models.

The standard has versions

The vocabulary is itself versioned, and a file declares which version it speaks in its header. Bonsai will write IFC2X3, IFC4 or IFC4X3, and ships a starter template for each.

These are not software version numbers and they do not date anything. They are three real standards, all in current use, differing in what they can express. So a consultant who asks you for IFC2X3 is asking for something substantive rather than being difficult.

It is also a decision rather than a preference, because the versions do not travel equally well in both directions. Upgrading is the supported direction - IFC2X3 to IFC4, IFC4 to IFC4X3 - because each later schema is broadly a superset of the one before. Going back down is lossy by definition: the later schema has words the earlier one does not, and what cannot be said is dropped. The sharpest case is in The spatial tree - IFC2X3 cannot carry georeferencing at all. So settle the schema at the start of a job rather than at the end of one.

The bag is borrowed. Ursula Le Guin’s The Carrier Bag Theory of Fiction (1986) 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 is not a bad illustration.

One qualification on the bag, and it is a real one: not everything travels inside it. Issues, comments and the questions people raise about a model go separately, which is the subject of Other people’s models.

Last updated 4 September 2026.