OpenEik 0.1: the specification
| Version | 0.1.0-draft |
| Date | 14 October 2026, revised to 29 October 2026 |
| Status | Working draft. Not stable: any part may change before 0.1.0 |
| Reference implementation | Stomra's engine and its ek command: the text written from commit ff8574ec (11 October 2026) and kept in step with it since; the schemas generated from commit bcfd44c7 (28 October 2026) |
| Licence | CC-BY-4.0 for this text, with a royalty-free patent commitment under OWFa 1.0 (PATENTS.md); CC0-1.0 for the schemas and the examples; Apache-2.0 for the tools and packages |
OpenEik is an open building model laid out as a code base. A building is a folder of small JSON records in meaningful paths: one record per file, types and references in place of interfaces and imports, a compiler that derives bodies and quantities from the records, typed commands that are checked before anything changes, versions with diffs and merges, and an interface for AI agents. IFC is an export, not the base.
This specification is written from the reference implementation. Where the implementation and the specification plan differ, this text follows the implementation and says so in Open questions and changes from the plan.
Contents
| Part | File | What it fixes |
|---|---|---|
| I | Foundations | Scope, conformance language, units and axes, level semantics, ids, references, versions, errata and deprecation, unknown members, extensions |
| II | Language | The records: project, levels, materials, types and layers, elements by category, views, the framing expression language, profiles, application records, a supplier's declared geometry, railings for product systems; heating, ventilation and plumbing: systems, insulation, heat, components in a pipe, and their views' filters, frames, tags and symbols |
| III | Code base | The folder: layout, file kinds, the stored form, hashes, kept files, reading and writing, the single-file form, its file extension and media type |
| IV | Compiler | What is derived and never stored; the geometric rules 0.1 fixes; the structural subset; reference behaviour; declared geometry and railing lines |
| V | Commands | Typed writes: the command set, preconditions, validation, batches, dry runs, answers, determinism |
| VI | History | Objects, trees, versions and refs; diff; three-way merge by record and field; remotes, push and pull; applications' results and proposals |
| VII | Agent interface | The contract for agents: tree, tiered reads, the filter, budgets, honesty fields, the write loop, the guide, the headless host |
| VIII | Bridges | IFC and other exports (informative in 0.1); reading IFC once to start a project (proposed for 0.2) |
| Conformance | The conformance classes and what each must do | |
| Open questions and changes from the plan | Where the implementation and the plan differ, and what is still open | |
| Security and privacy considerations | Personal data in models and their history, agents, trust in results and proposals, what hashes guarantee, paths, resource limits, kept files, credentials, schemas | |
| Terminology and references | The terms the text defines and where each is defined; the normative and informative references | |
| XIII | Electrical installations | Proposed for 0.2, not part of 0.1: devices and boards, circuits, feed chains, control, cable carriers and modelled cables |
| XIV | Drawings | Proposed for 0.2, not part of 0.1: sheets, the provenance of annotations, the drawing profile, people and keys, issued drawings in a restricted SVG, revisions, read sets and freshness, revision clouds, the register, issues, reviews, sign-offs and the PDF rendition |
| XV | Assets | Proposed for 0.2, not part of 0.1: binary files kept by the SHA-256 of their bytes, as pointers in versions with the bytes beside them; their kinds and limits; stores, push, fetch, pull and clone; withheld assets; references; security and privacy |
| XVI | Ownership | Proposed for 0.2, not part of 0.1: the parties of a project and the paths each owns, in project/owners.json; globs and the last matching rule; the approvals a change needs, and what a host and a tool do |
| XVII | Commands with an envelope | Proposed for 0.2, not part of 0.1: the envelope around a batch (an operation id, who sends it, the target and its base, the mode, the intent); refusals with codes, JSON pointers into the command and fixes; a precondition on every command; the answer; security and privacy |
| XVIII | Review and issue | Proposed for 0.2, not part of 0.1: a review round on a version of the model in 3D, with viewpoints; an issue that releases a version and names its prints; an issue signed by its sender and its recipients; a host's signed receipt, and the keys a host publishes for it; terms accepted; prints that say they are prints, an IFC naming its version |
The machine-readable parts are beside this text:
../schemas/: a JSON Schema (2020-12) for every kind of file in a folder, andindex.json, which maps paths to schemas; in../schemas/applications/, the schemas of the result manifest and the proposal file (Part VI, 8).../registry/: the extension registry, the prefixes applications register for their own members and files (Part I, 11), with its schema in../schemas/registry/.../examples/: two folders written by the reference implementation, their files named as Part III, 2 says.../tools/check.mjs: checks a folder against the schemas and the rules of Part III.
Conventions of this text
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY and OPTIONAL are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals, as shown here.
- A section marked informative states no requirement. Everything else is normative.
- "Reference:" after a rule names the part of the reference implementation that shows it, by file and function. The rule is the requirement; the reference is evidence, and where the two disagree the disagreement is recorded in Open questions and changes from the plan.
- Paths are written with
/.<id>in a path is the record's id as a path segment (Part III, "Path segments"). - JSON member names are written in
code. "Absent" means the member is not present; OpenEik does not usenullas a stored value except where a schema says so. - Examples use the folder in
examples/one-storey-houseunless they say otherwise.
Who this is for
- Newcomers: the primer, OpenEik in 10 minutes, then Parts I and III. Terminology and references says where each term is defined.
- Implementers of readers, writers, validators, compilers and agent hosts: Parts I–V and VII are the contract, Conformance lists what each class must do, and Security and privacy considerations says what to guard against.
- Agents and people editing a model by hand: Part I (conventions) and Part III (the folder) are enough to work on files;
AGENTS.mdin every folder repeats what cannot be read off the files. - Tool builders who only read: a reader of the core needs Parts I–III and the schemas.