OpenEik · Guide
Issued drawings
An issued OpenEik drawing is an SVG snapshot kept in the building, whose lines name the elements that drew them.
A drawing is a build of the model
OpenEik treats a building as a code base. Drawings fit that picture as the release side of software does:
| In a code base | In an OpenEik building |
|---|---|
| Source code | The model's records at a version |
| Build recipe | The view and sheet records: cut height, area, scale |
| Compiler and its version | The drawing generator and its version |
| Source map | Every line drawn from the model names its element |
| Signed release | The issued revision, signed off by named people |
| "What does this commit invalidate?" | "Which drawings does this change make stale?" |
Views and sheets are records in the model. What issuing adds is a snapshot: the drawing written once as a file, with a record of exactly what it was drawn from. It never changes afterwards; a change makes a new revision. Drawings are issued by the authoring tool, such as Stomra, or with the OpenEik tools.
What an issued drawing is made of
An issued drawing is a few plain files in the building's folder. The current revision lives in the folder; earlier ones stay in the history, found through the register.
drawings/
profile.json the project's codes and rules
issued/A-101/
drawing.svg the sheet: the exact bytes that are signed
revision.json what it was drawn from, its status, its changes
read-set.json every record it read, by hash
signoffs/ one signed statement per sign-off
register/A-101.json every revision of A-101, never rewritten
issues/<issue>.json a release of revisions to people
reviews/<review>.json a closed review round
project/people/ the people who issue and sign, with their keys
assets/<sha256>.pdf fonts, outside drawings, signed prints
Revision record
The version of the model, the sheet and views, the generator and its fonts, the status and the change items. It names the SVG's digest.
Read set
Every record each view read, with its hash, and the elements inside each view's volume.
Register
Each drawing's revisions in order, and whether one was superseded or withdrawn.
Issued drawings are the one stated exception to OpenEik's rule that derived data is never stored. They are kept because an issue is a legal event: a permit, a contract or a site depends on exactly what was sent.
The drawing SVG
The drawing is written in OpenEik drawing SVG, a restricted SVG that any browser opens:
- Paper millimetres. One unit is one millimetre of paper, and each viewport records its scale, so a measurement on the sheet reads model millimetres.
- Safe. No scripts, no styles, no outside references: nothing in the file fetches or runs anything.
- The same bytes every time. The same model, generator and fonts give an identical file, so it can be signed and checked.
- Text stays text. Notes and tags are readable by people, by
grepand by agents. - Layers. The sheet (border, title block, revision table), then one group per viewport, then the revision clouds.
The source map
Inside each viewport, every element's lines are a group carrying data-eik-id, the element's id, and data-eik-hash, a hash of its line work snapped to a 0.01 mm grid. Lines carry their role (cut, projection, hidden, hatch and so on), and annotations carry the item they draw and whether a person, an agent or the generator made them. Because the ids are in the file, a plain search answers "which issued drawings show this window?":
$ grep -l 'data-eik-id="study-window-east"' drawings/issued/*/drawing.svg
drawings/issued/A-101/drawing.svg
drawings/issued/A-104/drawing.svg
And because each group has a hash, two revisions are compared element by element. An element whose hash is unchanged did not change; a viewport moved on the sheet changes no element's hash.
Freshness: is the drawing still true?
A revision is checked against a later version of the model, or against a proposal before it merges. This is how build systems decide what to rebuild, and it needs no drawing:
- Same model, same generator: current.
- A record it read changed or vanished: the views that read it are stale.
- Something new entered a view: stale. An element whose box now meets a view's volume was not in the read set, so absence is checked too.
- Drawn again, it looks the same: where a redrawn candidate has every group's hash unchanged, the revision is checked: current, with no new revision.
- Only the generator is newer: "would draw differently", kept apart from model changes and never clouded as a design change without a person's decision.
In the L-house example, one window moved 500 mm along its wall. Hashes alone showed that A-101 (its plan and east facade) and A-104 (its plan) were stale, and that A-102 and A-103 were not. An outside drawing, such as a consultant's PDF, is unlinked: registered and issued like any other, but never checked against the model.
Revisions, change items and clouds
A new revision records change items: short descriptions that name elements as people know them, such as "East window moved 500 mm". They go in the revision table and are kept whether or not clouds are drawn, so a viewer can always show what changed.
- Clouds are chosen per update. The project's profile gives a default for each status, and the person issuing switches clouds on or off.
- Clouds follow the visible change, not element boxes, so they stay small. A change that draws nothing different needs no cloud.
- Revised throughout. When the changes cover most of the sheet, the tool proposes a note "revised throughout" instead of a sheet full of clouds.
States and the project's own codes
OpenEik defines neutral states. The project maps its own codes onto them in its drawing profile, drawings/profile.json, so the standard carries no national list. Common schemes map like this:
| OpenEik state | ISO 19650 (UK annex) | Sweden (BEAst) | Sign-offs, usually | Clouds, usually |
|---|---|---|---|---|
| draft | S0; P01.01 | Preliminär | none | none |
| shared, for information | S2; P01 | Information | none | off |
| shared, for review | S3 (S1, S4, S6, S7); P01 | Granskning | optional | off, switchable |
| published | A, B; C01 | Godkänd with its purpose | as the project requires | on in Sweden, switchable |
| as built | CR | Relationshandling | as required | removed |
The ceremony grows with the stage. A sketch or design iteration is shared for information with no review, no signature and no clouds, yet its snapshot still records what it was drawn from, so OpenEik can say when the sketch is out of date. The profile also gives the revision series, the purposes of issue, the review states and decision codes, and the fonts.
Issues, reviews and sign-offs
- An issue (
drawings/issues/) releases revisions to recipients for a purpose. It can also release a version of the model, and name the prints sent with it by their digests. - A review round (
drawings/reviews/) is the review of one revision: reviewers, items anchored to elements, their states and decisions. Anchored items follow their element into the next revision; an item whose element is gone becomes an orphan, listed and never dropped. - A sign-off (
signoffs/) is a signed statement: "this person checked, reviewed, approved … this revision, with this status". It covers the digests of the issued files, is signed with a key of the person's record (a passkey, for example) and time-stamped. Signing never changes the drawing's bytes, and anyone verifies it offline with the folder and the time-stamp authority's certificate. - Receipts record what happened to an issue for each recipient, signed by the host that sent it.
A host coordinates these and the authoring tool saves the results into the building. On EikHub, see Drawing review on EikHub and Signed receipts on EikHub.
Prints are copies
What is issued, reviewed and signed is the revision, or the version, by its digests. A PDF or an IFC made from it is a print: a copy, like paper.
- The PDF rendition is a PDF/A-3 at exact scale, with the issued SVG and its records attached inside it, as e-invoices carry their data. A reader without OpenEik opens a normal PDF; a reader with it takes out the source-mapped SVG and checks it.
- The margin note. Each PDF says in its bottom margin which drawing, revision, building and version it is a copy of, and carries a QR code that names the revision by its digest. Scanning it tells whether the sheet is still current. The note holds no print time, so the same revision always prints to the same bytes.
- An IFC names its version. An IFC printed from a version says which version it came from and that it is a print.
- Prints are never compared. To see what changed, compare the revisions or versions they were printed from.
People and agents on a drawing
Every line and note on an issued sheet says who made it:
Derived
Lines, hatches and tags the generator draws from the model. Each names its element. Drawn again, never edited.
Person
Dimensions, notes, tags and insulation added by a person, anchored to elements so they follow the model.
Agent
The same kinds of item drawn by an AI, naming the agent and the person it acts for. Proposed until a person accepts.
The rule is simple: agents propose, people accept. No sheet is issued while it holds a proposed agent item, and an agent never signs an approval. Agents work on the records and the change lists, not on pictures, which is where they are reliable.
Working with the files
Because the drawings, their revisions and their sign-offs are files in the building's folder, any tool that reads OpenEik can work with them from the folder alone:
- say how fresh every issued drawing is against the model in the folder;
- say which issued drawings a version or a proposal makes stale;
- list the elements that changed between two revisions, viewport by viewport;
- keep the register of every drawing and its revisions;
- check the sign-offs of issued drawings;
- check the drawing files, with the rest of the model, against the standard's rules.
The full rules are in OpenEik's specification, Part XIV (Drawings) and Part XVIII (Review and issue), at openeik.org.