Building model

A building model is one JSON document. It describes the building with numbers and ids, not with meshes. Your app, your server and an AI agent can all read it and write it.

Structure

A model contains buildings. A building contains storeys. A storey contains the elements.

List in a storey	What it holds
`walls`	Walls. Each wall holds its `openings`.
`slabs`	Floor plates, floors and ceilings
`roofs`	Flat, gable, hip and shed roofs
`columns`	Columns and piers
`stairs`, `railings`	Stairs and their railings
`spaces`	Rooms with a name and an area
`instances`	Furniture and equipment from your own assets
`unhostedOpenings`	Doors and windows that are not in a wall
`modelObjects`	Basic shapes: lines, arcs, polygons and boxes

A building can also have a mass. A mass is the building as a simple volume, for the early stage of a design. See Model a mass.

A small model

import type { BuildingModel } from '@opengeometry/floorkit';

export const model: BuildingModel = {
  schema: 'floorkit.building-model',
  version: 3,
  units: 'meters',
  upAxis: 'y',
  id: 'small-house',
  buildings: [
    {
      id: 'building',
      storeys: [
        {
          id: 'ground',
          elevation: 0,
          height: 3,
          walls: [
            {
              id: 'south-wall',
              points: [
                [0, 0],
                [6, 0],
              ],
              thickness: 0.2,
              openings: [{ id: 'entry-door', kind: 'door', offset: 2, width: 0.9, height: 2.1 }],
            },
          ],
        },
      ],
    },
  ],
};

The header fields

Field	Value	Meaning
`schema`	`'floorkit.building-model'`	Tells Floorkit what the document is
`version`	`3`	Use `3` for a new model
`units`	`'meters'`	All lengths are in metres
`upAxis`	`'y'`	The Y axis points up
`id`	Your text	The id of the model

Rules that keep a model valid

Each id is unique. You choose the ids and Floorkit keeps them.
A wall is a line of [x, z] points. For a closed room, set closed: true. Do not repeat the first point.
A door or a window is an entry in the openings of its wall. Its offset is the distance from the first wall point, along the wall.
The elevation of a storey is its height in the world. The elements of the storey use offsets from that height.

Check a model

validateBuildingModel reads a document and returns each problem with a path, a code and a message. It does not need the geometry kernel, so you can also run it on a server.

import { validateBuildingModel } from '@opengeometry/floorkit';

export function check(input: unknown): boolean {
  const result = validateBuildingModel(input);
  for (const issue of result.errors) console.error(issue.path, issue.code, issue.message);
  return result.ok;
}

This check makes the model a good target for an AI agent. The agent writes the document. If the check finds a problem, give the path and the message back to the agent and let it correct the document.

What is not in the model

Meshes and other geometry. Floorkit builds them from the model.
Views and sheets. They are in the project file, next to the model.
Undo history. It belongs to the session.

Agent proposals

Use the agent building workflow to turn unknown JSON into an editable project. Preserve IDs and return validation issues to the agent. A valid document can still fail during geometry construction; keep the existing project until its replacement builds. The TypeScript contract is not a downloadable JSON Schema or an LLM tool definition. Your app supplies its AI provider and tool inputs. Build with agents explains the documentation and application boundaries.

Coordinates and units

Learn where each number is measured from.

Model types

See each field of the document.

Documentation

Structure

A small model

The header fields

Rules that keep a model valid

Check a model

What is not in the model

Agent proposals

Next

Coordinates and units

Model types

​Structure

​A small model

​The header fields

​Rules that keep a model valid

​Check a model

​What is not in the model

​Agent proposals

​Next

Coordinates and units

Model types

Structure

A small model

The header fields

Rules that keep a model valid

Check a model

What is not in the model

Agent proposals

Next