> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ploterr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Building model

> The typed JSON document that holds your building.

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.

```mermaid theme={null}
flowchart TD
  M[Building model] --> B[Building]
  B --> S[Storey]
  S --> W[Walls]
  W --> O[Doors, windows, voids]
  S --> P[Slabs and roofs]
  S --> C[Columns]
  S --> T[Stairs and railings]
  S --> R[Spaces]
```

| 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](/floorkit/guides/model-a-mass).

## A small model

```typescript theme={null}
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.

```typescript theme={null}
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;
}
```

<Tip>
  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.
</Tip>

## 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](/floorkit/guides/save-and-reopen), next to the model.
* Undo history. It belongs to the session.

## Agent proposals

Use the [agent building workflow](/floorkit/agents/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](/floorkit/agents/index) explains the documentation and application boundaries.

## Next

<CardGroup cols={2}>
  <Card title="Coordinates and units" icon="ruler-combined" href="/floorkit/concepts/coordinates-and-units">
    Learn where each number is measured from.
  </Card>

  <Card title="Model types" icon="code" href="/floorkit/api/architecture/validate-building-model#types">
    See each field of the document.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.