OpenEik · Guide
Buildings as code
OpenEik keeps a building the way software keeps its source: small named files in folders, with versions, branches, reviews and merges.
The idea
Software teams solved a problem that building projects still have: many people changing one thing at the same time without overwriting each other. Code lives in small files under version control. Every change is visible as a short diff, someone reviews it, and only then is it merged into the shared line of work. The full history stays, and any earlier state can be brought back.
OpenEik, the open building format, gives a building the same shape. The model is a folder of small text files, one per wall, door, window, type or level. A change to the building is a change to a few of those files. That makes it possible to see what changed, to review it, to work on alternatives side by side and to merge them, with the tools and habits software already has. AI agents benefit in the same way: they already work well in code bases, and a building kept as one works the same way for them.
| In a code base | In an OpenEik building |
|---|---|
| Source files in meaningful folders | One record per file: architecture/level-0/wall/study-wall-1.json |
| Types and imports | Element types with their layers; references such as typeId, levelId, hostId |
| A compiler; build output is not committed | Bodies, joins, quantities and drawings derived from the records; nothing derived is stored |
| Type checker and linter | Schemas and a whole-model check, with errors that name the record |
| Commits, branches, merges | Versions, alternatives, a merge by record and by field |
| Pull requests and code owners | Proposals that a person accepts; folders owned by a discipline |
| README, AGENTS.md | AGENTS.md in the folder, with the model's conventions |
The building as a folder
An OpenEik model is a folder. Its layout is fixed, so every tool finds the same thing in the same place:
eik.json the format and the units
AGENTS.md conventions, for agents and people
project/project.json the project
project/levels.json the levels, in order
project/materials/<id>.json materials, and grids, title blocks …
types/<discipline>/<category>/<id>.json types
<discipline>/<level>/<category>/<id>.json elements
drawings/<discipline>/views/… views and their details
drawings/<discipline>/sheets/<id>.json sheets
.eik/ hidden: derived data, never the model
A few rules make the folder dependable:
- One record per file. A wall is one file, its type is another. A change to the wall touches the wall's file and nothing else.
- The path follows from the record. An element lives under the discipline that owns it, its level and its category, in a file named after its id. Move a wall to another level and it is the same wall in a new place.
- Ids last. Every record keeps its id for its whole life, readable and stable, such as
study-window-east. Other records refer to it by that id: the window names the wall it sits in withhostId. - Units are stated once.
eik.jsonnames the format and the units: millimetres, Z up.
The same model can also travel as a single file or as an archive of the folder; the folder is the form made for working in.
Download the example buildings from openeik.org/samples and open the folder in any editor. The L-house has under two hundred files, and each one reads on its own.
Intent, not geometry
A record says what a thing is, not what it looks like when finished. A wall says where it runs, how high it is, which type it has and which roof it is attached to. Its type says its layers. That is all that is stored.
Everything else is derived, the way a compiler builds a program from its source: the layer bodies, the corners and tees where walls meet, the cut against the roof, the holes for doors and windows, the areas and volumes, and the plans, sections and elevations. Derived data may be kept in the hidden .eik/ folder to save work, but it is never part of the model, so two lines of work can never disagree about it.
This is why a small change stays small. Make the wall 300 mm higher and one number changes. The wall's body, its joints and every drawing that shows it follow from that number.
Files written for small diffs
Every file is written in one fixed text form, so the same record always gives the same bytes:
- members sorted by name, one member per line;
- a point on one line, a list of points one point per line;
- numbers in their shortest exact form, UTF-8, a final newline.
With that, a changed value is a changed line. Saving an unchanged model gives an identical folder, and comparing two states shows only what someone actually changed. Each record also has a hash, the SHA-256 of its canonical JSON, so two equal records are recognised as equal wherever they appear.
Changes are checked commands
An application changes a model through commands: create, update, delete, move, copy and the like. Each command is typed and validated before anything changes. A batch of commands is applied all or nothing, and the answer says what it touched.
Every record carries a revision. A command that updates a record can name the revision it read, and it is refused if someone else has changed the record since. That is how two people, or a person and an agent, can work on one model without silently overwriting each other.
Editing a file by hand is allowed too. A hand edit is checked when the folder is read, and a broken reference or an invalid value is reported with the file it is in.
Versions
A model's history is kept the way git keeps code. Every record and every folder is stored once, named by its hash. A version points at the state of the whole model and at the version or versions before it, with who made it, when, and a summary of the changes.
- A version is never rewritten. Going back to an earlier state makes a new version on top, so nothing is lost.
- Two versions that hold the same model have the same root hash, so equal states are recognised at once.
- Comparing two versions reports changes record by record: added, removed, changed or moved, with the fields that differ. Folders with equal hashes are skipped, so a comparison of a large building stays quick.
Alternatives and merges
A line of work has a name. The main line is main; an alternative design is a line of its own, such as alternatives/brick-facade. Work on an alternative does not touch the main line until it is merged.
A merge joins two lines of work against the version both started from. It works on records, never on lines of text:
| What happened to a record | Result of the merge |
|---|---|
| Changed on one side only | That side's record is taken |
| Added on one side | It is added |
| Deleted on one side, untouched on the other | It is deleted |
| Changed on both sides, in different fields | Merged field by field: one side moved the window, the other changed its type, and both changes are kept |
| The same field changed differently on both sides | A conflict, reported by its path |
| Changed on one side, deleted on the other | A conflict |
Lists whose items have ids, such as a type's layers or a sheet's viewports, merge item by item. A conflict is never decided silently: the record keeps one side until a person chooses. And a merge that would leave a model broken, such as a door whose wall was deleted on the other side, is refused with the records named.
Proposals, owners and review
On a real project several firms write one building. OpenEik gives each discipline its own folders: architecture, structure, ventilation, plumbing, electrical and so on. A project can say which party owns which folders, and a change to a folder needs its owner's approval, as code owners approve changes to their part of a code base.
A change offered to someone else's line of work is a proposal, the building's version of a pull request. It shows the changes record by record, and it becomes part of the model only when a person accepts it. An application that works beside the model, such as a structural analysis, keeps its own results in a folder of its own and offers its changes the same way, never by writing into the building's records.
EikHub is a host built on this: buildings branch, get reviewed and merge there, with the changes shown in 3D and on the drawings.
Ordinary tools still work
Because the model is plain files, it can be kept in git or any other version control system, opened in a text editor, searched with grep and read by an AI agent's ordinary file tools. The stored form keeps git's diffs short and readable.
A plain text merge of two edited files is often right, but it does not know records: it can join two edits that are each valid into a model that is not, and it cannot follow a record that moved. Merge with a tool that applies the rules above and checks the result whole.
Terms
Record
One thing in the model, a wall, a type, a level, in a file of its own.
Id
A record's name for its whole life. Other records refer to it by its id.
Revision
A counter on each record that goes up with every change, so a stale edit can be refused.
Derived
Bodies, joins, quantities and drawings, worked out from the records and never stored as the model.
Version
A saved state of the whole model, with its author, time and parents. Never rewritten.
Alternative
A named line of work beside the main line, for a design option.
Merge
Joining two lines of work record by record and field by field, then checking the whole model.
Proposal
Changes offered for review, accepted by a person before they enter the model.
The full rules are in the OpenEik specification at openeik.org: the code base, commands and history parts.