# OpenEik

> 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. Version 0.4.0. Status: Tagged `v0.4.0` on 1 November 2026, privately until the public launch. OpenEik 0.3 is kept at the tag `v0.3.0`, 0.2 at the tag `v0.2.0` and its patch versions to `v0.2.3`, and 0.1 at `v0.1.0` and `v0.1.1`; a reader of 0.4 reads each of them (Part I, 9.6, rule 3).

To start, read Part I (foundations) and Part III (code base): they are enough to work on a model's files, and every model folder has an `AGENTS.md` with the conventions that cannot be read off its files. A reader of the core needs Parts I to III and the schemas; Conformance lists what each class of implementation must do. The samples below are complete model folders to try it on.

## Specification

- [OpenEik 0.2: the specification](https://openeik.org/spec/0.4/index.md): the version, status and licences, the contents, and the conventions of the text
- [Part I. Foundations](https://openeik.org/spec/0.4/foundations.md): Scope, conformance language, units and axes, level semantics, ids, references, versions, errata and deprecation, unknown members, extensions
- [Part II. Language](https://openeik.org/spec/0.4/language.md): 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
- [Part III. Code base](https://openeik.org/spec/0.4/code-base.md): The folder: layout, folders that follow owners, file kinds, the stored form, hashes, kept files, reading and writing, the single-file form, its file extension and media type
- [Part IV. Compiler](https://openeik.org/spec/0.4/compiler.md): What is derived and never stored; the geometric rules it fixes, doors' and windows' frames, stairs, timber framing, trusses and joists, and rooms among them; the structural subset; reference behaviour; declared geometry and railing lines
- [Part V. Commands](https://openeik.org/spec/0.4/commands.md): Typed writes: the command set, preconditions, validation, batches, dry runs, answers, determinism
- [Part VI. History](https://openeik.org/spec/0.4/history.md): Objects, trees, versions and refs; diff; three-way merge by record and field; remotes, push and pull; applications' results and proposals
- [Part VII. Agent interface](https://openeik.org/spec/0.4/agent-interface.md): The contract for agents: tree, tiered reads, the filter, budgets, honesty fields, the write loop, the guide, the headless host
- [Part VIII. Bridges](https://openeik.org/spec/0.4/bridges.md): IFC and other exports; reading IFC once to start a project
- [Conformance](https://openeik.org/spec/0.4/conformance.md): The conformance classes and what each must do
- [Open questions and changes from the plan](https://openeik.org/spec/0.4/open-questions.md): Where the implementation and the plan differ, and what is still open
- [Security and privacy considerations](https://openeik.org/spec/0.4/security-and-privacy.md): 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](https://openeik.org/spec/0.4/terminology-and-references.md): The terms the text defines and where each is defined; the normative and informative references
- [Part XIII. Electrical installations](https://openeik.org/spec/0.4/electrical.md): Devices and boards, circuits, feed chains, control, cable carriers and modelled cables
- [Part XIV. Drawings](https://openeik.org/spec/0.4/drawings.md): 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
- [Part XV. Assets](https://openeik.org/spec/0.4/assets.md): 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
- [Part XVI. Ownership](https://openeik.org/spec/0.4/ownership.md): 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
- [Part XVII. Commands with an envelope](https://openeik.org/spec/0.4/envelope.md): 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
- [Part XVIII. Review and issue](https://openeik.org/spec/0.4/review.md): 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
- [Errata of OpenEik 0.4](https://openeik.org/errata/0.4.md): the corrections accepted to 0.4 as published (none yet), each with the date it was accepted, the passage as it was, the correction and the patch version that applies it; as a page at https://openeik.org/errata/0.4

## Schemas

- [All schemas](https://openeik.org/schemas/0.4/): every schema of 0.4, by group, each served at its `$id`
- [openeik-schemas-0.4.zip](https://openeik.org/schemas/openeik-schemas-0.4.zip): the same 197 schemas in one download, each at the path of its `$id` under a folder `openeik-schemas-0.4/`, with index.json, source.json and LICENSE (CC0-1.0); 227 kB
- [index.json](https://openeik.org/schemas/0.4/index.json): maps each kind of file in a folder to its schema, and names the categories, the disciplines and the references
- [Single-file model](https://openeik.org/schemas/0.4/model.schema.json): A whole model as one JSON object: the single-file form of Part III. Lists hold their records in order; views hold their detail items inline; `extras` holds the folder's kept files, text by path. From 0.2 it names its format and units at its top, as eik.json does for a folder (Part III, 11).
- [Element](https://openeik.org/schemas/0.4/elements/element.schema.json): An element record. The category-specific schemas in this folder add the rules of each category.
- [Type](https://openeik.org/schemas/0.4/types/type.schema.json): A type record. The category-specific schemas in this folder add the rules of each category.
- [Command](https://openeik.org/schemas/0.4/commands/index.json): A command of the core record operations (Part V, 2.1), view.upsert of the documentation profile (Part V, 2.2), or of the kinds a part adds (Part XIII, 9), checked against the schema of its kind. x-eik-commands lists the kinds, their schemas and their preconditions (the member, and whether it is required, optional, required when the record exists, or none).
- [Result manifest](https://openeik.org/schemas/0.4/applications/result-manifest.schema.json): What a result set was computed from: <application>/<model>/results/<run>/manifest.json, a kept file (spec Part VI, 8.2 to 8.5). Written by hand from the text, not generated. A reader also reads the earlier id openeik-result/0.1-proposal as this format.
- [Proposal](https://openeik.org/schemas/0.4/applications/proposal.schema.json): A change an application offers to a model's records, as commands of Part V: <application>/<model>/proposals/<id>.json, a kept file (spec Part VI, 8.7). Written by hand from the text, not generated. A reader also reads the earlier id openeik-proposal/0.1-proposal as this format.

## Guides

- [OpenEik in 10 minutes](https://openeik.org/guides/primer.md): A developer who has never seen OpenEik: what a model is, a tour of a small folder, the rules that matter most, how to check a folder, and where to read next.
- [Implementing OpenEik as an app's native format](https://openeik.org/guides/implementing-openeik.md): Developers and AI agents building an app or tool whose own model is an OpenEik folder: reading and writing records, ids, commands, versions and merges, where to store a model, and conformance
- [Working across disciplines](https://openeik.org/guides/disciplines.md): Teams in which architects, structural engineers and building services engineers work on one building: where each discipline's records are, what they name of each other's, the datums every discipline shares, merging separate lines of work, and what a discipline can take out without breaking the others, with `openeik datums`, `diff`, `merge` and `clash`
- [Reading and saving an OpenEik model](https://openeik.org/guides/reading-and-saving.md): Developers of apps that work beside a model's author, such as an analysis, a quantity take-off or a supplier's tool: reading a folder or a version in a store, what an app may change, its own folder, results that name what they were computed from, proposed changes, and remotes, push and pull
- [examples/openeik-store.mjs](https://openeik.org/guides/examples/openeik-store.mjs): A short script with no dependencies: an OpenEik folder as content-addressed objects, pushed to a store that speaks the store API v0, and read back.

## Samples

- [one-storey-house.zip](https://openeik.org/samples/one-storey-house.zip): A synthetic house built with typed commands only (`examples/one-storey-house.commands.json`), written with `ek export` as a folder of 0.1 and migrated to 0.2 in one write. 34 files, 10 elements.
- [l-house.zip](https://openeik.org/samples/l-house.zip): The reference implementation's synthetic L-house test model, put into English with commands, written with `ek export` as a folder of 0.1 and migrated to 0.2 in one write. 193 files, 130 elements.
- [Samples](https://openeik.org/samples/): the samples with their sizes and contents

## Extension registry

- [extensions.json](https://openeik.org/registry/extensions.json): the prefixes applications register for the members and files they add to a model (2 so far), and the 19 names OpenEik reserves (Part I, 11); its schema is [extensions.schema.json](https://openeik.org/schemas/0.4/registry/extensions.schema.json)
- [README.md](https://openeik.org/registry/README.md): what a prefix looks like, how to register one, and the rules

## Conformance

- [openeik-conformance-0.4.zip](https://openeik.org/conformance/openeik-conformance-0.4.zip): the conformance suite, 1080 cases for readers, validators, command processors and drawing validators in a folder `openeik-conformance-0.4/`: each a small model, the rule it tests and what a validator and a reader must do with it. Its README.md says how to run them; 6.2 MB
- [Conformance](https://openeik.org/conformance): the classes, how a claim is checked, and where the implementations stand

## Tools

- [openeik-tools-0.4.tgz](https://openeik.org/tools/openeik-tools-0.4.tgz): `@openeik/tools`, a library with no dependencies that reads, checks, hashes, diffs and stores OpenEik models, and its `openeik` command, as npm installs it: `npm install https://openeik.org/tools/openeik-tools-0.4.tgz`, then `npx @openeik/tools check <folder>` in the same folder. It is on npm as `@openeik/tools` only from the public release; until then it installs from openeik.org.
- [index.js](https://openeik.org/tools/0.4/index.js): the same library as ES modules under /tools/0.4/, for a browser: `import { readFolder, checkFolder } from "https://openeik.org/tools/0.4/index.js"`
- [README.md](https://openeik.org/tools/0.4/README.md): the library's README: the API, with its functions and every diagnostic code
- [Developers](https://openeik.org/developers): a quick start with the library and its command
- [Validator](https://openeik.org/validate): the online check of an OpenEik model

## Earlier versions

- [OpenEik 0.1](https://openeik.org/spec/0.1/index.md): the specification of 0.1.0-draft as text, kept as it was at the tag `v0.1.1`, each Part beside it; as pages at https://openeik.org/spec/0.1/
- [Errata of OpenEik 0.1](https://openeik.org/errata/0.1.md): the corrections accepted to 0.1 as published (0.1-E1), each with the date it was accepted, the passage as it was, the correction and the patch version that applies it; as a page at https://openeik.org/errata/0.1
- [Schemas 0.1](https://openeik.org/schemas/0.1/): every schema of 0.1, each served at its `$id`; all of them in one download: [openeik-schemas-0.1.zip](https://openeik.org/schemas/openeik-schemas-0.1.zip), 239 kB
- [openeik-conformance-0.1.zip](https://openeik.org/conformance/openeik-conformance-0.1.zip), 6.2 MB: the conformance suite of 0.1
- [openeik-tools-0.1.tgz](https://openeik.org/tools/openeik-tools-0.1.tgz), 1.3 MB: `@openeik/tools` 0.1.0-draft, as npm installs it; its modules are under /tools/0.1/
- [OpenEik 0.2](https://openeik.org/spec/0.2/index.md): the specification of 0.2.0-draft as text, kept as it was at the tag `v0.2.3`, each Part beside it; as pages at https://openeik.org/spec/0.2/
- [Errata of OpenEik 0.2](https://openeik.org/errata/0.2.md): the corrections accepted to 0.2 as published (0.2-E1, 0.2-E2, 0.2-E3, 0.2-E4 and 0.2-E5), each with the date it was accepted, the passage as it was, the correction and the patch version that applies it; as a page at https://openeik.org/errata/0.2
- [Schemas 0.2](https://openeik.org/schemas/0.2/): every schema of 0.2, each served at its `$id`; all of them in one download: [openeik-schemas-0.2.zip](https://openeik.org/schemas/openeik-schemas-0.2.zip), 221 kB
- [openeik-conformance-0.2.zip](https://openeik.org/conformance/openeik-conformance-0.2.zip), 5.9 MB: the conformance suite of 0.2
- [openeik-tools-0.2.tgz](https://openeik.org/tools/openeik-tools-0.2.tgz), 1.4 MB: `@openeik/tools` 0.2.0-draft, as npm installs it; its modules are under /tools/0.2/
- [OpenEik 0.3](https://openeik.org/spec/0.3/index.md): the specification of 0.3.0 as text, kept as it was at the tag `v0.3.0`, each Part beside it; as pages at https://openeik.org/spec/0.3/
- [Errata of OpenEik 0.3](https://openeik.org/errata/0.3.md): the corrections accepted to 0.3 as published (none yet), each with the date it was accepted, the passage as it was, the correction and the patch version that applies it; as a page at https://openeik.org/errata/0.3
- [Schemas 0.3](https://openeik.org/schemas/0.3/): every schema of 0.3, each served at its `$id`; all of them in one download: [openeik-schemas-0.3.zip](https://openeik.org/schemas/openeik-schemas-0.3.zip), 225 kB
- [openeik-conformance-0.3.zip](https://openeik.org/conformance/openeik-conformance-0.3.zip), 6.1 MB: the conformance suite of 0.3
- [openeik-tools-0.3.tgz](https://openeik.org/tools/openeik-tools-0.3.tgz), 1.5 MB: `@openeik/tools` 0.3.0, as npm installs it; its modules are under /tools/0.3/

## Optional

- [Full text](https://openeik.org/llms-full.txt): the specification of 0.4 (its README first, then every Part in order), its errata and the guides, in one file