OpenEik.org

Draft OpenEik 0.1.0-draft: draft, not final. From commit c6463c72 of 30 October 2026. Errata: the errata of 0.1. Raw text: /spec/0.1/terminology-and-references.md

On this page

OpenEik 0.1 specification

Terminology and references

This page lists the terms the specification defines, or uses in a sense of its own, with where each is defined (section 1), and the documents the text refers to (section 2). Section 1 is informative: each definition sums up the text it links to, and where the two differ, the linked text wins.

1. Terms

TermMeaningDefined in
agentAn AI agent that reads and changes a model through an agent host, or by editing its files, as it works on a code base.Part VII
agent hostAn implementation that serves models to agents through the operations of Part VII, headless; one of the conformance classes.Part VII; Conformance, 1
AGENTS.mdThe text file in every folder that states the conventions an agent cannot read off the files; no reader takes model data from it, and no version's tree holds it.Part III, 8.2
alternativeA line of work for another design, whose newest version the ref alternatives/<slug> names.Part VI, 3
answerWhat a command processor returns for an accepted command or batch: at least ok, dryRun, affected, verify, sequence and each command's result.Part V, 9
application recordA record of a list that OpenEik carries but does not define (sheets, title blocks, images, reports, renders, deviations, area adjustments, linked references): a JSON object with an id, kept unchanged.Part II, 9.1
application valueA member of a defined record whose value is an application's (a type's assembly, catalogSource and handbook, the project's standards, font choices): kept unchanged, and not defined by OpenEik.Part II, 9.2
application's folderThe folder of its own, at the top of a model's folder, in which an application keeps its files, with a model folder for each model of its own.Part VI, 8.1
authoritative forThe aspects (envelope, fixings, clearances, positions, loads, parts, fabrication) for which a declaration's geometry is exact within its tolerances, listed in authoritativeFor.Part II, 12.1
automatic versionA version of kind auto, which a tool makes as work goes on; it stays local and is never pushed to a shared ref.Part VI, 6.3
axis (of a member)The centroidal line of a member's body as built, after its roll: its reference line moved by its section's centroid offset, and the line analysis uses.Part IV, 6.5
base, ours and theirsIn a three-way merge, the version both lines of work started from, and the two lines being joined.Part VI, 5
basisThe ids and hashes of the records an element's declared geometry was made against; when one of those hashes changes, the declaration is kept and reported as unconfirmed.Part II, 12.1
batchAn ordered list of commands applied as one: each sees the model as the ones before it left it, the whole model is checked after the last, and a failure changes nothing.Part V, 7
bridgeAn exporter, or an importer, between OpenEik and a delivery format such as IFC; one of the conformance classes. Reading IFC is proposed for 0.2 (Part VIII, 2).Part VIII
budgetThe size under which an agent host holds every answer it sends into an agent's conversation; an answer over it is held back, never cut off silently.Part VII, 5
canonical formA JSON value as the JSON Canonicalization Scheme of RFC 8785 writes it, with no white space and members sorted by UTF-16 code units: the text hashes are taken of.Part III, 6
categoryThe kind of thing an element or a type is, one of the thirty-one of 0.1 (wall, slab, door …, generic) or one a later version adds; a plain name of ASCII letters and digits, at most 32 characters, that starts with a lower-case letter and is no device's; a type serves only elements of its own category.Part II, 6.2
centroid offsetThe centroid of a section's area less the middle of its bounding box, by which a member's axis lies off its reference line.Part IV, 6.5
class-A, class-B and class-C rulesThe compiler's rules: closed-form rules, normative where Part IV states them (A); rules that infer from geometry with tolerances (B); product and practice engines (C), the last two reference behaviour.Part IV, 2
cloneFetching every ref of a remote, setting the local refs to their versions and recording their tracking refs.Part VI, 6.5
commandA typed JSON object, named by its kind, that changes a model only after it is checked; the way a host changes a model for a person or an agent.Part V, 1
command processorAn implementation that changes models by commands; one of the conformance classes.Conformance, 1
compare-and-swapMoving a ref only from the version the writer names as its current one, so that the move fails if the ref points elsewhere.Part VI, 3
compilerAn implementation that derives bodies and quantities from a model's records, as a compiler derives a program from its source; one of the conformance classes, whose core class implements the class-A rules.Part IV
conflictWhat a merge cannot settle by itself (both changed, changed and deleted, added twice, in the way); a conflicted record keeps our side until a person chooses.Part VI, 5
conformance classOne of the eight roles in which an implementation claims to conform (reader, validator, writer, compiler, command processor, version store, agent host, bridge), each with the requirements it meets.Conformance, 1
copy and originalA group of elements placed many times is stored as its original's elements and a copy record for each placement; the copies' elements are derived, named <copy id>/<element id>, and never stored.Part II, 10
core record operationsThe command kinds every command processor implements for the core records (create, update, delete, type.upsert and the others of Part V, 2.1).Part V, 2
current and staleA result set is current where the records its application's selection selects, and the model folder's intent files, still give the digests its manifest records, and stale otherwise.Part VI, 8.4
declared geometryA supplier's geometry on a type or an element (declaredGeometry), at a declared level, exact for what it is authoritative for and silent on the rest: source, not derived data.Part II, 12.1
derived dataWhat a compiler works out from the records (bodies, joins found from geometry, room boundaries, areas, quantities, the elements of copies, drawings), which is never stored as a record.Part II, 10; Part IV, 1
derived layerThe optional hidden folder .eik/derived/, which may hold results that are hard to derive, each naming the records it came from by hash; never part of the model.Part IV, 1.1
detail chunkA file details/<n>.json beside a view, holding up to 256 of its 2D detail items, cut by a rule on the FNV-1a hash of their ids, taken over UTF-16 code units where RFC 9923 takes octets.Part III, 10
diffThe changes between two versions by record and top-level field, found by comparing their trees; a record moved to another folder is one changed record.Part VI, 4
digestThe SHA-256 of the canonical JSON of a sorted list of pairs: a name for a set of files by their content, the same on a disk, in git and in any store.Part VI, 8.3
directed baselineA wall's profile read from its first point to its second; its type's layers run exterior first from its left.Part I, 5.1
disciplineThe top folder an element goes in by its category: architecture, structure, systems or site.Part III, 4.1
domain operationA command kind beyond the core record operations (transforms, framing, reinforcement …), defined by the records it produces.Part V, 2.3
dry runRunning a command or a batch with every check a real run makes, and changing nothing.Part V, 7
eik.jsonThe file that states a folder's format and units, {"format": "openeik/0.1-draft", "units": "mm"}, read before any record.Part III, 8.1; Part I, 9.2
elementOne placed thing of the building (a wall, a slab, a door), with its type, level, offset, size and plan profile.Part II, 6
engine filesThe two files a writer puts beside the records: eik.json and AGENTS.md.Part III, 8
expressionA string in the small arithmetic language that gives a framing family's numbers.Part II, 5.4
fast-forwardA pull that, when the local line holds the tracked remote version and has nothing of its own after it, moves the local ref, or writes the folder, to the remote version instead of recording a merge.Part VI, 6.4
fetchReading the objects of a remote ref's version that the local store lacks, then setting the tracking ref to that version.Part VI, 6.2
fidelity reportWhat a bridge publishes with every export: the schema written, its counts, and what the export leaves out or approximates.Part VIII, 1
filterThe one set of criteria (ids, categories, levels, a host, a box, a radius, a view …), combined with AND, that an agent host's reads, queries and snapshots accept.Part VII, 4
fold (of a name)The name in Normalization Form D, its case folded by the full case folding of the Unicode Standard, in Normalization Form C, each as Unicode 13.0.0 defines it; a code point that version does not assign stays as it is. Two names with one fold are one where a file system ignores case and Unicode normalisation; two paths fold to one where the first names in which they differ do.Part III, 4.3
folderA model stored as files: one record per file at a path derived from the record, with eik.json, AGENTS.md and kept files; a folder and a stored version are one format.Part III, 1
formatThe version of this specification a folder is written in, stated in eik.json as openeik/<major>.<minor> with an optional -draft.Part I, 9.2
frame (of a declaration)The coordinates a declaration's geometry is given in: on a type, a frame set by how its category is placed (at a point, in an opening, along a line); on an element, world, the project's plan coordinates, or line, along the element's line.Part II, 12.1
framing familyA type's parametric 2D family (framing), swept across its plane, whose numbers are expressions.Part II, 5.4
generic elementAn element of the category generic, for a thing no other category fits, whose only shape is its declared geometry.Part II, 6.6
given shapeAn element's shape that a reader of IFC gave as a body in the derived layer, rather than its record's members, which then place it and nothing more (shape: "given"); proposed for 0.2.Part VIII, 2.3
GlobalIdThe IFC identifier a bridge gives each product it exports, derived from the project's id and the record's id, so that it stays the same from one export to the next.Part VIII, 1
guideThe knowledge an agent host serves on demand: a core read once at the start, and a topic for each feature, read when needed.Part VII, 7
hashThe SHA-256 of the UTF-8 bytes of a record's canonical form, written as 64 lowercase hexadecimal digits.Part III, 6
headless hostAn agent host that runs without a screen or a browser (in a terminal, a CI job, a sandbox or a server), as every agent host must.Part VII, 8
hiddenSaid of a file or folder whose name starts with .: not part of the model, skipped by readers and never removed by writers.Part III, 1
honesty fieldsThe members every list answer of an agent host carries: total, returned, offset, nextOffset, truncated and the host's sequence.Part VII, 3
host (of an element)The element another element is placed on or in, named by its hostId: a wall for a door or a window, a slab or a foundation for a slab edge element or reinforcement, a beam, a column or a slab edge element for a rebar element too, a wall for a mesh element too, a stair, a slab or a shaft for a railing.Part II, 7
host (a service)A service that keeps repositories of models for people and their tools, as a git host does for code; OpenEik requires none.Part VI, 7; Part I, 1
idA record's opaque, non-empty name: unique in its list, stable for the life of the record, and without /; its path segment at most 200 bytes, and no two records' paths in a model folding to one.Part I, 6
intent filesThe kept files of a model folder outside its results/ and proposals/ folders: what the application keeps of its own, source.json included.Part VI, 8.1
interface and implementationWhat other trades meet of a supplier's part (its envelope, fixings, clearances, positions and loads, with tolerances), as against the supplier's own internal detail, which it may keep back or share.Part II, 12.1
kept fileA file at a plain relative path that is no record and no engine file (another tool's results, a README), none of whose names a file system refuses or reads otherwise, whose path folds to no other of the model's, eik.json and AGENTS.md among them, and which passes through neither of those as through a folder: kept with the model as text if it is UTF-8 without NUL, of at most 1 MiB, and otherwise left alone.Part III, 7
layerOne of the compound layers of a wall, slab, foundation, roof or ceiling type, with its function, material and thickness, listed exterior first or top first.Part II, 5.1
levelA named horizontal datum, {id, name, elevation}; every element names one, and its offset from it means what the element's category says.Part I, 4
level (of a declaration)How far a declaration goes: interface, assembly or fabrication.Part II, 12.1
library recordA type, title block, detail family, image or other record that a writer takes from its own built-in library rather than from the model.Part III, 13
line of workA chain of versions, each made on the one before, whose newest version a ref names: main, or an alternative.Part VI, 3
materialA record {id, name, color, pattern, revision} that a layer names by its name, ignoring case and surrounding white space.Part II, 4
materialised memberA framing member or truss that a command wrote as an ordinary element, carrying frameHost, and no longer derived.Part II, 10
mergeJoining two lines of work against the version both started from, by record and by member, never by text, and checking the result whole.Part VI, 5
modelA building's design intent as OpenEik records, stored as a folder of files or as the single-file form.Part III
model folderA folder <application>/<model>/ that holds one of an application's own models: its intent files, result sets and proposals.Part VI, 8.1
model-quality warningsWarnings of openeik check --quality about elements modelled under a category that does not fit them: heuristics, not requirements.Conformance, 2
named versionA version of kind named, with the name and note a person gave it; what a supplier reads (Part II, 12), and what a push makes of the local versions it squashes.Part VI, 3; Part VI, 6.3
objectA record, a kept file, a tree or a version, named by the hash of its canonical form; equal content anywhere is one object, and an object never changes.Part VI, 1
orderThe file project/order.json, which gives the order of every record list but the elements; the order of elements has no meaning. An index of the record lists, not a record: a reader need not keep a member of it that names no list.Part III, 9
pairA file's [path, hash]: its leaf's path in a version's tree and its object's hash, from which digests are made.Part VI, 8.3
patchThe members an update writes to an element, each replacing the member of that name whole, null removing one.Part V, 4
path segmentA record's id, or a level's, as one name in a path: %, the characters that common file systems refuse, a leading . or ~, a trailing . or space and a device name's first character written as % and two hexadecimal digits (wall:a as wall%3Aa, con as %63on), so that every id gives one name that every common file system takes; at most 200 bytes of UTF-8 (Part I, 6, rule 8); a reader decodes every such escape.Part III, 2
payloadA member of a type allowed only for some categories (layers, section, framing …), holding what those categories need.Part II, 5
preconditionThe state a command was based on (expectedRevision and the like); a command whose precondition does not hold is refused.Part V, 3
profile (of a domain)A group of the members and payloads of one domain (structure, timber framing, systems …), so that a reader can say which domains it understands.Part II, 8
profile (of an element)An element's list of 1 to 500 plan points, whose meaning its category gives: a wall's centreline, a slab's outline, a column's centre.Part I, 5
projectThe record project/project.json: the schema version, the project (its id, name, units and axes) and the project information.Part II, 2
proposalA change to a model's records offered as commands for a person to accept; in 0.1, a proposal file <application>/<model>/proposals/<id>.json (openeik-proposal/0.1), whose writing changes no record.Part VI, 8.7
pullFetching a remote ref, then merging its version into the local line of work with the tracked version as the base.Part VI, 6.4
pushSending a local line of work to a remote ref, moved by compare-and-swap from the tracked version; a published version is never rewritten.Part VI, 6.3
readerAn implementation that reads models; one of the conformance classes. It refuses what it cannot read, and SHOULD perform the whole-model check: one that performs it refuses a model that fails it, and one that does not reads such a model as it is.Conformance, 1; Part III, 12
recordOne JSON object of a kind Part II defines (the project, a level, a type, an element, a view …), stored at a path derived from it: one record a file, but for the levels, which share project/levels.json, and a view's detail items, which are kept in chunks beside it.Part II, 1
refA name for the newest version of a line of work (main, alternatives/<slug>), moved only by compare-and-swap.Part VI, 3
referenceA field that names another record by its id; no reference is made by position in a list.Part I, 7
reference behaviourWhat the reference implementation does where 0.1 fixes no rule (the class-B and class-C rules); a compiler that differs from it says where, as Part IV, 2 asks.Part IV, 2; Part IV, 7
reference implementationStomra's engine and its ek command: the implementation this text is written from, which shows that its rules can be met, and which none of them requires.Part I, 1
reference lineThe line through the middle of a member's section, by which its record places it and on which its roll, joins and trims are computed.Part IV, 6.5
remoteAnother store that holds a repository of the same model, given a name on the local side (origin).Part VI, 6.1
remote-tracking refFor one remote and one of its refs, the version and tree last fetched from it or pushed to it; in a folder, kept in the hidden .eik/remotes.json.Part VI, 6.1
replayApplying again the commands a processor has accepted before (opening a project from its log), with the admission rules made after them lifted.Part V, 8
reserved nameA name that starts with ~, kept for the shards of version trees; writers create none in a folder.Part III, 1
result manifestThe manifest.json of a result set (openeik-result/0.1): what the results are, the application that made them, and the digests of what they were computed from.Part VI, 8.2
result setThe files of one run folder results/<run>/ of a model folder: its manifest and the results themselves.Part VI, 8.2
revisionA record's non-negative integer, raised by one with every change: a precondition token, not a version number.Part I, 8
rootA model's root tree, whose hash names the model's state: two models with one root hash hold the same records and kept files.Part VI, 2
run idThe name of a run folder. Part VI, 8.5 recommends r- and the first 12 hexadecimal digits of the hash of the run's engine, inputs and intent files, so that the same run made again gets the same name.Part VI, 8.5
schemaThe JSON Schema (2020-12) of one kind of file in a folder; schemas/index.json maps paths to them.Part I, 9.4; Part III, 3
selectionThe records an application reads (by category, list, id or path), kept with their pairs in its model folder's source.json.Part VI, 8.4
set-out lineThe centreline of a beam's underside, from its start point at its level and offset to its end, rising by endRise.Part IV, 6.2
shardA sub-tree, named ~ and two lowercase hexadecimal digits, into which a tree of more than 4096 entries is split; it holds no shard, and is no part of any path.Part VI, 2
single-file formA model as one JSON object: the folder's content without its layout, with the kept files in extras.Part III, 11
squashMaking a line's local versions that are not on the remote into one version of kind named, whose tree is the newest local tree and whose only parent is the tracked remote version, before a push.Part VI, 6.3
storeWhere a model's versions are kept as objects and refs: an application's own store, a repository on a host, or a folder.Part VI, 6
stored formThe text form of every JSON file a writer writes (members sorted, two spaces of indent, a member a line, an array of scalars on one line), so that the same record always gives the same bytes; a reader accepts any layout.Part III, 5
supplier proposal flowHow the supplier of a building part, invited to a project, reads a named version, checks its parts and proposes changed records as commands, with a quote kept on the host and out of the model.Part II, 12
tierOne of the two levels of detail an agent host's read offers at least: the index, a row per element, and the full records.Part VII, 3
toleranceHow far, in mm, a built part may lie from what its declaration states: a default, and a value for each term where it differs.Part II, 12.1
tracking refA remote-tracking ref.Part VI, 6.1
tree (version tree)An object {"tree": [[name, kind, hash], …]} that lists one folder's entries by name; a version's trees mirror the folder's layout, with eik.json and without AGENTS.md or hidden files.Part VI, 2
typeThe shared definition its elements follow, as a class is for its instances: its category, material, size, layers and payloads.Part II, 5
unknown categoryA category an implementation does not know, such as one a later version adds; its elements and types are kept, checked against the common schemas only.Part I, 10
unknown memberA member a reader does not know (of a later version, of a profile it does not implement, of another application): kept at any depth and written back unchanged.Part I, 10
validatorAn implementation that says whether a model is valid, and why not, naming the file and the rule; one of the conformance classes.Conformance, 1
versionA commit object naming a root tree, the versions it follows, its kind, its author and its time; its id is its hash, and it is never rewritten.Part VI, 3
version storeAn implementation that keeps a model's versions, with their objects, trees and refs, diffs and merges them, and exchanges them with remotes; one of the conformance classes.Part VI; Conformance, 1
viewA record of a view's settings and 2D items, at drawings/views/<kind>/<id>/view.json; the drawing it shows is derived.Part II, 1; Part II, 10
walking sideThe side of a railing's line that people walk on: inside a slab's outline, outside a shaft's.Part IV, 11.2
whole-model checkEvery record checked against its schema and the whole model against Parts I and II: required of a validator, recommended to a reader, and made after every command and every merge.Part III, 12; Conformance, 1
writerAn implementation that writes models; one of the conformance classes.Conformance, 1
x-eik-… annotationsThe schemas' own keywords: x-eik-ref on a reference field, x-eik-closed on an object whose members they know, "x-eik-values": "national" on a field of national values, and x-eik-application on an application value.Part I, 7 and 10; Part II, 8 and 9.2

2. References

2.1 Normative references

These are needed to implement the specification. Where no edition is named, the latest applies.

2.2 Informative references

These help to understand the text; no requirement depends on them.

glTF, STEP, STL, DXF, PDF and SVG, which Part VIII, 3 names as the reference implementation's other exports, are not listed: 0.1 specifies none of them. Nor are the licences, which are the repository's terms rather than references of the text (README).