Document format and agent API

A Wallgraph plan is a single JSON file with no derived geometry stored in it. Below: the model, the JSON Schema, and the two ways a program drives the editor.

The model

A plan is a planar graph of wall centerlines. What is stored: nodes, walls (centerlines with a thickness and an optional arc), openings parameterised along their wall, placed symbols, stairs, vides and structural elements. Nothing derived is in the file: wall faces, mitred corners, room polygons, areas and dimension labels are all recomputed when the plan is drawn.

This allows openings to be derived from their walls while keeping the file compact. A generator only needs to write the graph.

• Every coordinate and length is a whole number of millimetres. No decimals, no metres.
• y points down, matching the canvas.
• bulge is the DXF convention tan(θ/4): 0 is straight. It is required — omitting it does not mean “straight”, it means the arc maths sees NaN.
• An opening sits at t millimetres from node a, measured along the centerline.
• A stair carries its own dimensions — width, going, treads and rise — because the same kind is built to a different size in every plan. The treads themselves are not stored. A flight of n treads has n+1 risers, so the riser height, the walking rule and the tread the section plane cuts all follow from rise.

JSON Schema

The format is published as JSON Schema (draft 2020-12) at /wallgraph.schema.json. Every field is described and unknown fields are rejected. An incorrect key therefore produces a validation error instead of missing content in a loaded plan.

A complete example

One 4 × 3 metre room with a door, a side-hung window and a socket. The valid document can be loaded through the editor menu or a plan link.

{
  "version": 1,
  "unit": "mm",
  "gridMm": 100,
  "areaMode": "net",
  "floors": [
    {
      "id": "f1",
      "name": "Begane grond",
      "nodes": [
        {
          "id": "n1",
          "x": 0,
          "y": 0
        },
        {
          "id": "n2",
          "x": 4000,
          "y": 0
        },
        {
          "id": "n3",
          "x": 4000,
          "y": 3000
        },
        {
          "id": "n4",
          "x": 0,
          "y": 3000
        }
      ],
      "walls": [
        {
          "id": "w1",
          "a": "n1",
          "b": "n2",
          "thickness": 300,
          "bulge": 0,
          "openings": []
        },
        {
          "id": "w2",
          "a": "n2",
          "b": "n3",
          "thickness": 300,
          "bulge": 0,
          "openings": [
            {
              "id": "o1",
              "kind": "window",
              "t": 1500,
              "width": 1200,
              "sashes": [
                {
                  "action": "turn",
                  "hinge": "a"
                }
              ]
            }
          ]
        },
        {
          "id": "w3",
          "a": "n3",
          "b": "n4",
          "thickness": 300,
          "bulge": 0,
          "openings": [
            {
              "id": "o2",
              "kind": "door",
              "t": 2000,
              "width": 900,
              "sashes": [
                {
                  "action": "turn",
                  "hinge": "a"
                }
              ]
            }
          ]
        },
        {
          "id": "w4",
          "a": "n4",
          "b": "n1",
          "thickness": 300,
          "bulge": 0,
          "openings": []
        }
      ],
      "symbols": [
        {
          "id": "s1",
          "type": "socket",
          "x": 800,
          "y": 150,
          "rotation": 3.141592653589793,
          "wallId": "w1"
        }
      ]
    }
  ]
}

For AI agents

The editor provides two client-side automation channels. Neither requires an account or API key.

1. A plan in a link

The document JSON can be placed in a base64url string after #plan=. URL fragment values are not included in HTTP requests to the server. Anyone with the link can open the embedded plan.

https://plattegrond.crocode.nl/#plan=<base64url of the JSON document>

# optionally with the language:
https://plattegrond.crocode.nl/#plan=<…>&lang=en

Loading replaces the current plan and is recorded as an undoable document step.

2. window.wallgraph

The hosted page provides an automation interface on window. Its methods can be called through page.evaluate to load, render and read a plan.

// Load a plan into the running editor. Returns false if it is not a plan.
window.wallgraph.load(doc)

// The current plan, as a deep copy.
const doc = window.wallgraph.save()

// A shareable link to this page carrying the current plan.
window.wallgraph.link()

// Read or switch the interface language ("nl" | "en").
window.wallgraph.language("en")

// Which build is running, and where the schema for the document lives.
window.wallgraph.version
window.wallgraph.schema

3. The code itself

Wallgraph is free software (AGPL-3.0) with zero runtime dependencies. npm run build produces a self-contained dist/index.html that opens without a network. See the source and llms.txt.