Research · Construction

Datum — an open format for buildable plans

A JSON Schema and a working reference validator exist and pass their test suite — but nothing here has been used on a real project, and no building has been built against it. This document proposes a standard we believe should exist, and invites people who build for a living to tell us where it is wrong.

1. Abstract

A building plan is a picture. It states geometry precisely and states almost nothing else: not the order in which the thing must be built, not which regulations bind which element, and not the points at which a machine should stop and ask a human. Datum proposes an open, text-based format that carries all four, so that software agents can reason about a building rather than merely render one.

2. The problem

Drawings and BIM models describe a finished state. Construction is not a state, it is a sequence — a foundation cures before a wall stands, a wall exists before conduit runs inside it, conduit is inspected before plaster hides it. That ordering is real, safety-critical, and almost entirely absent from the artefact handed to the people doing the work. It survives instead in the heads of a site manager and a foreman.

Three consequences follow, and all three cost money on every job:

• Agents cannot plan. Given a model, a system can measure and clash-detect, but it cannot answer “what is buildable on Tuesday” because dependency is not encoded.
• Regulation is re-read by hand. Compliance lives in prose. A human interprets the same clauses on every project, and an agent cannot check the work without re-deriving that interpretation.
• There is no defined place for human judgement. Where a tolerance is exceeded or a drawing is ambiguous, the correct action is to ask the electrician. Nothing in the file says so.

3. Scope and non-goals

In scope: a serialisation for elements, their build-order dependencies, the regulatory constraints binding them, and the points requiring human consultation. A validator that can reject an unbuildable plan.

Non-goals: Datum is not a replacement for IFC, CAD or BIM, and does not attempt to describe geometry better than they do — it references them. It is not a scheduling product, not a procurement system, and not a rendering format. It expresses no opinion on which tools produce it.

4. Design principles

• Text first. Diffable, reviewable, and storable in version control. A plan change should read like a code change.
• Order is first-class. Dependency is not metadata bolted on; it is a primary relation between elements.
• Regulation as constraint, not prose. Machine-checkable where a clause permits it, and explicitly marked where it does not.
• Humans are addressable. The format names the role to consult and the condition that triggers it.
• Wrong plans should fail loudly. A cycle in the dependency graph is a bug, and a validator should say so before anyone pours concrete.

5. What Datum encodes

5.1 Elements and geometry

Each element carries an id, a type drawn from a controlled vocabulary, and a reference into an existing geometry source rather than a duplicate of it.

5.2 Chronology

Two relations, requires and blocks, form a directed acyclic graph over elements. This is the part conventional formats omit, and it is the part that makes the file useful to a planner.

5.3 Regulations as code

Elements reference the clauses that bind them — for South African work, parts of SANS 10400. Where a clause is machine-checkable it carries a predicate; where it requires professional judgement it is marked as such rather than approximated.

5.4 Human consultation points

An element may declare a consult block: a trigger condition and the role to escalate to. This is the mechanism by which an agent is required to defer to the crew rather than proceed on a guess.

6. Illustrative example

JSON is the normative wire format — it validates with existing tooling and has exactly one spelling of everything, which matters more for a format checked by machines than authoring comfort does. YAML maps onto the same structure and is shown here because it reads better on a page. Details will still change.

datum: 0.1
project: warehouse-b
units: mm

elements:
  - id: slab-01
    type: concrete.slab
    depth: 250
    geometry: { ifc_ref: "1H9d2$mBv0kPQ" }
    requires: []
    regulations:
      - clause: SANS-10400-B
        check: machine        # thickness predicate is checkable
      - clause: SANS-10400-H
        check: professional   # requires an engineer's sign-off

  - id: wall-03
    type: masonry.wall
    requires:                 # cure time is a property of the edge,
      - after: slab-01        # not of the slab and not of the wall
        wait: { cure_days: 7 }

  - id: conduit-run-01
    type: electrical.conduit
    requires: [wall-03]       # cannot precede the wall it runs in
    blocks:   [plaster-03]    # plaster must not hide uninspected conduit
    consult:
      trigger: deviation > 50mm
      role: site_electrician

7. Open questions

• What subset of SANS 10400 honestly reduces to a machine-checkable predicate? v0.1 records predicates as opaque strings rather than inventing an expression language before knowing the answer.
• If a predicate encodes a clause incorrectly and the wall fails, who is accountable — the plan author, the tool vendor, or the engineer who signed off? The format cannot decide this, but it should probably record who asserted what.
• Real trades overlap: plaster starts on one wall while another is still going up. v0.1 treats each element as atomic, which is probably its largest simplification.
• How much of SANS 10400 is honestly machine-checkable, and who is accountable when a predicate encodes a clause incorrectly?
• How do site variations — which are constant — flow back into the file without a bureaucracy nobody will use?
• Does this belong inside IFC as an extension rather than beside it as a separate format?

8. How to contribute

The most useful response to this document is someone who has managed a site telling us which part is naive. If you build, inspect, or regulate buildings for a living, we would like to hear where this breaks.

Send a critique →