> ## Documentation Index > Fetch the complete documentation index at: https://docs.loft.build/llms.txt > Use this file to discover all available pages before exploring further. # The loft ontology **Status:** hand-authored around generated splice regions (the `errors.ts` / `CATEGORIES.md` lifecycle, v0.3 session 1): §3 generates from the value-type enum in `/packages/lang/src/schema/valuetypes.ts` and §6 from the keyword registries in `/packages/lang/src/parser/keywords.ts` — edit the code and run `pnpm gen:taxonomy`; CI pins each marked region to its renderer. Per-category *datum* inventories stay in [the category catalog](/categories/) — this file owns the axes; that file owns the per-category instances. (Folding CATEGORIES.md in was considered and kept separate, 2026-08-12: different readers — reference card while writing loft vs. constitution while writing the spec — and different ownership. The splice machinery now exists, so merging CATEGORIES as one more generated section is cheap and the question stays open as pure taste.) This file answers one question wherever it arises: **what kinds of things exist in loft, and along which axes is each thing classified?** When a spec section, error message, or design conversation needs a word for one of these, it uses this file's word. *** ## 1. The identity ladder Every placeable thing in a model resolves through the same four layers: | Layer | loft | What it is | Revit | | ------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | **Category** | `door`, `wall`, `grid`… | The *interface*: a closed, spec-owned keyword set. Owns the required parameter core and the required datum projection. | Category | | **Component** | (v0.4-era grammar) | The *implementation*: geometry recipes + internal logic behind an export membrane. System components (walls, floors, roofs) are compiler-built; authored components ship as `.loft` source — including the generic library. | Family (loadable ≈ authored; system ≈ system) | | **Type** | `doortype 3070 …` | The *partial application*: a named parameter set that fixes some of the component's parameters and delegates the rest. | Type | | **Instance** | `door 3070 D1 in wall.W1 at 4'` | The *call*: a placement supplying whatever the type delegated. | Instance | * component = function · type = partial application · instance = the call. * Every v0.3 type is a type of the built-in generic component (scaffolding with a designed retirement — SPEC-v0.3 §7 P2). * Declaration order is category → type → \[id] → placement (decision 38); each category requires at least one of the two leading name slots. **Beside the ladder, not on it:** * **Declared datums** (`grid`, `level`, future `refplane`): pure reference geometry — carriers with no recipe. Id required (being referenced is their entire job); type slot absent today, arrivable additively. * **`opening`**: the type-less, filler-less cutter. Id optional (an element, not a datum); no type, ever — a product-shaped hole is a component's cutter, which is a recipe role, never an element. * **Projected datums** (`wall.W1.end`, `door.D1.jamb`): not declared things at all — the datum surface every element exports, per the category's projection rule. Inventory: [the category catalog](/categories/). * **Placement** is a how-to, not ontology: [Placing elements](/placement/) walks the methods — a plane, a line, a point, a wall host, a loop — with the slots each one takes. ## 2. Parameter axes Every parameter is classified along five independent axes. The first two exist in v0.3; the rest are settled direction with reserved arrival points. | Axis | Values (v0.3 in bold) | Notes | | -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Vocabulary** | **spec** (bare: `width`) · **user** (`u-` prefix) | The prefix is provenance, visible in every schedule and diff. | | **Binding** | **type-fixed** · **instance-authored** (delegated via `instance`) | The category requires; the type chooses; the instance is checked. | | Value source | **authored text** · model-derived (future) | Model-derived = Revit reporting parameters (host wall thickness, height from base/top levels). `boundAt` records the source. | | Visibility | *(all public in v0.3)* · exported · internal (component era) | Exported = API, breaking-change-tracked; internal = implementation, renameable. | | Mutability | **authored** · computed (component era) | Computed exports (formwork area, concrete volume) are read-only query targets. | Requiredness is a per-parameter fact governed by **the requiredness ratchet** (decision 45): authority descends category → component → type → placement, and each rung may tighten *optional → required* for what it governs, never loosen. The category holds the core (every door has `width`, `height`); a type may demand a delegated `u-` parameter of every placement (`u-hardware instance text required` — omission is D0515); the future `param` statement (project-profile rung) demands at project scope; components join with their own vocabulary — including the category's *optional* words (a door's sill, a part number), which stay spec-typed even when unenforced — in their era. ## 3. Value types **The closed set is the type system.** Fixed parameters infer their value type from the literal; the unification rule ("one name, one value type, per component" — SPEC-v0.3 §6.3, rendered per category while types apply the built-in generics) makes that inference safe. Both facts require the literal grammar to be a closed, enumerated list: an unenumerated value type is undefined behavior, so this table is normative — and generated from the enum the parser enforces (`/packages/lang/src/schema/valuetypes.ts`). ### v0.3 ships | Type | Literal | Example | In the dimensional algebra? | | ----------- | -------------------------- | --------------- | --------------------------- | | **length** | imperial literal, unquoted | `3'-0"`, `3/4"` | Yes (decision 20) | | **boolean** | `true` / `false`, unquoted | `true` | No | | **text** | quoted, always | `"BHMA set 3"` | No | ### The lexical law (why length never confuses with text) 1. **Text is always quoted.** No exceptions, no bare words. 2. **Unquoted values must lex as exactly one non-text literal form** (length, number, boolean). `3'-6"` is a length; `"3'-6in"` is text that mentions one — strings have no escape sequences (the tokenizer ends text at the next `"`), so a length inside text uses the word-suffix spelling (`in`/`ft`), which is already first-class. 3. **Nothing ever falls back to text.** An unquoted token matching no literal form is an error with a did-you-mean — never a guessed string. (The YAML cautionary tale: unquoted-scalar guessing turns `no` into `false`. loft never guesses.) 4. **Delegated declarations state the type by name** (`instance text`) because there is no literal to infer from; the stated name must be a row in this table. ### The growth law The set grows by *versioned addition*, and a new value type may only claim literal spellings that were previously **errors** — never reinterpret a spelling that already means something. (Adding `45deg` is legal: it lexes as nothing today. Making bare words mean text is illegal forever: it would reinterpret every typo.) ### Reserved roadmap (each with its motivating case) | Type | Motivating case | Arrival | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | **area** | computed formwork sqft; algebra product length × length | falls out of the dimensional algebra with computed params | | **volume** | computed concrete CY; area × length | same | | **angle** | future non-orthogonal work, sketch grammar | curves/profiles era | | **number** | counts and durations, each with its unit (`90 min`, `2 hr`); struck 2026-09-17 because no literal may spell a bare number | the `duration` / count era | | **datum reference** | column `base`/`top` (a level, a plane) | component era | | **material reference** | a layertype's material slot; the material vocabulary is closed and keyed by MasterFormat number (PARKINGLOT wall-assembly entry, 2026-08-17) | layers/registry era | | **component reference** | sub-components (hardware sets) | registry era | Reference-valued parameters store the *reference* plus the resolved target (principle 3), and ride the shared resolution chain. ## 4. The governance ladders Two ladders, often conflated because both get called "the ladder." They answer different questions. ### 4a. The declaration ladder — *where does a definition live?* (3 rungs) Every nameable definition (profile, type, eventually component) climbs the same three rungs, each migration a mechanical "extract and name": 1. **Inline** — sketched anonymously in the using declaration (a rectangular profile implied by `width 3' height 7'`). Local, zero ceremony. 2. **Project-declared** — named at project scope (`doortype 3070 …`, `profile ARCH-TOP …`, the walltype pattern). Reusable, diffable, one source per model. 3. **Registry** — imported from a package (`import { DBL-9070 } from "@registry/…"`), version-pinned, vendor-owned. Rung 1 → 2 is the *extract-named-thing* refactoring; rung 2 → 3 is publishing. Nothing about a definition's meaning changes as it climbs — the rung is distribution, not semantics. ### 4b. The vocabulary governance ladder — *who owns which words?* For parameters and datums alike (one ladder, two columns), authority descends, and each level may only **add**, never redefine: 1. **Spec / category core** — the format's own law: every door has `width`, `height`, projects `centerline · head · jamb`. Closed, guaranteed, tools may assume it blind. 2. **Project profile** — additive-only project law ("every door on this job needs `u-fire-rating`"); the future `param` declaration statement. Liskov-governed: a profile may demand more, never less or different. 3. **Component/type** — author-added vocabulary (`u-` parameters, custom datums), binding level chosen here (fix vs delegate), exported-vs-internal chosen here (component era). 4. **Instance** — supplies values for whatever was delegated; declares nothing. The `u-` prefix marks vocabulary owned below the spec rung, and its typing scope follows its owner: unification runs at the declaring component's scope ("one name, one value type, per category" in v0.3, where every type applies the built-in category component) — which keeps rung-3 freedom type-safe without rung-2 ceremony. Rung 2 (`param`) is what grants a name one identity *across* categories: the shared-parameter tier, where a BIM manager pins the type and requiredness once and the cross-category schedule column becomes legitimate. ## 5. Datum kinds and selectors (pointer) Datums classify by **kind** (plane, line, level — the decision-20 kind algebra, orientation-worded) and resolve through **selectors** in two families: *geometric* (resolved from the referencing statement's own frame: bare `jamb`) and *operational* (resolved from the referent's declaration: `jamb.near`, `hinge`). Per-category inventories, the required cores, and the projection rule live in [the category catalog](/categories/) and SPEC-v0.2 §6.3 — this file only fixes the axis names. ## 6. The keyword registry Generated from `/packages/lang/src/parser/keywords.ts` and the category catalog — the registries the parser enforces. A statement keyword is **claimed** (real grammar) or **reserved** (errors with a teaching message naming its future, never a generic syntax error). Reserved *value* words are contextual: legal only in the slots that define them, the reserved-word error everywhere else. Reserved *parameter* words are the catalog's rows with an era (`schema/categories/`): clause words a statement refuses with a teaching message naming their future (D0274), at the rung the row names. **Claimed statement keywords:** `project` · `units` · `level` · `grid` · `walltype` · `doortype` · `windowtype` · `wall` · `door` · `window` · `opening` · `room` · `roomline` · `viewtype` · `view` ### Reserved statement keywords | Word | Reserved for | | -------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `import` | imports and the package registry | | `export` | exports | | `const` | declared constants | | `component` | component definitions — the family layer, where doors, windows, and furniture are authored as source and every type applies one | | `refplane` | reference planes | | `section` | section views — a view kind: view section S1 at grid.B to grid.A | | `elevation` | elevation views — a view kind: view elevation E1 at grid.1 - 10' to grid.3 | | `detail` | detail views | | `sheet` | sheet generation | | `schedule` | schedules | | `floortype` | floor types | | `rooftype` | roof types | | `hatchtype` | hatch pattern types | | `materialtype` | material types | | `layertype` | assembly layer types | | `floor` | floor elements | | `roof` | roof elements | | `ceiling` | ceiling elements | | `stair` | stair elements | | `ramp` | ramp elements | | `railing` | railing elements | | `curtainwall` | curtain walls | | `mullion` | curtain-wall mullions | | `shaft` | shaft openings | | `column` | structural columns | | `beam` | structural framing | | `brace` | structural bracing | | `foundation` | foundations | | `slab` | structural slabs | | `truss` | trusses | | `duct` | ductwork | | `pipe` | piping | | `conduit` | electrical conduit | | `cabletray` | cable trays | | `sprinkler` | fire protection | | `fixture` | fixtures | | `equipment` | equipment placement | | `furniture` | furniture placement | | `casework` | casework | | `site` | site elements | | `topo` | topography | | `parking` | parking elements | | `planting` | planting elements | | `area` | area schemes | | `arealine` | area boundary lines | | `zone` | zones | | `space` | space elements | | `mass` | massing studies | | `group` | element groups | | `assembly` | assemblies | | `part` | parts | | `tag` | tags | | `dimension` | dimensions | | `annotation` | annotations | ### Reserved value words | Word | Meaning | | ---------- | ------------------------------------------------------------------------------------------- | | `instance` | the delegation word in type declarations — the value comes from each placement | | `required` | the requiredness marker on delegated type parameters — every placement must supply the pair | ### Reserved parameter words | Word | On | Meaning | Waits for | | ------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `stack` | level | which sequence of levels this one belongs to — `above` then defaults within it | a real interleaved-sequence model (a garage's 8' levels beside the podium's 10' ones) | | `label` | level, wall, opening, door, window | what the tag prints when it is not the id | a bubble or tag printing text other than the id — the grid's bubble is the one that ships | | `function` | wall | what the wall does in the building (Revit's Function) | the wall worksheet's second pass — decided at decision 65(e), not yet a clause | | `structural-usage` | wall | whether the wall bears, shears, or neither (Revit's Structural Usage) | the structure era | | `room-bounding` | wall | whether the wall bounds rooms — today every wall does | the furred or decorative wall that must not bound a room; bounding is per story since decision 74 | | `phase` | wall, opening, door, window, room, roomline | the phase this element is created in | the phasing era — phases are an ordered list declared in their own file, and a view looks at the model as of one | | `demolished` | wall, opening, door, window, room, roomline | the phase this element is demolished in | the phasing era — phases are an ordered list declared in their own file, and a view looks at the model as of one | | `fire-rating` | doortype, windowtype | the assembly's fire rating — drawn, not just scheduled (NCS ships nine fire-rating linetypes) | the `duration` value type (`90 min`, `2 hr`) — every parameter value carries units; until then the corpus spells it as text, `u-fire-rating "90"` | | `hardware-set` | doortype, windowtype | the hardware set the leaf carries | the door worksheet — `u-` today, a built-in candidate then | | `kind` | doortype, windowtype | which kind of leaf the type is — the category's declaration lists them | a second kind of leaf — the door's and the window's declarations list what is coming (D0242) | | `level` | room | the per-room level override — the walls' `base` analog, for the room that differs from its file | a room that differs from its file's level | | `department` | room | identity data (Revit's Department) | `roomtype`, or `u-` on categories | | `occupancy` | room | identity data (Revit's Occupancy) | `roomtype`, or `u-` on categories | | `units` | viewtype | how derived quantities display on this sheet — units are presentation, never a fact about the model | the metric / areas era — a tier on the view ?? viewtype ?? project cascade | | `phase` | view | the phase the query looks at the model as of | the phasing era — the phase filter, discipline's twin (a filter on the query, never a kind) | | `discipline` | view | the discipline the view reads the model as (structural, mechanical…) — a filter on the query, and the graphic standard's cell beside scale | the views/filters era — phase's twin (a filter on the query, never a kind); object styles stay one standard, the view's discipline picks the resolver cell the way its scale does | *** *Change protocol: hand-authored sections ride spec PRs; generated sections are edited only through their source modules and `pnpm gen:taxonomy` — same law as [the category catalog](/categories/). Never let this file and the code disagree silently.*