# The Specify house model standard — `specify-house-model/1` How a 3D model of a type house has to be built so that it works in Specify's configurator: a customer on a housebuilder's website chooses the size, the garage, the roof and the facade, and sees that exact house, from outside and from inside, on whatever device they are holding. **Who this is for.** First, the 3D modeller Specify commissions to build a house — you do not need to know anything about Specify, and everything you must do is in [Part A](#part-a--what-to-deliver). Second, Specify's own engineers, who build the conformance check against the numbered rules (`HM-1`, `HM-2`, …) and the reasoning in [Part B](#part-b--why-it-is-this-way). **Status: version 1, 2026-09-24.** Decided by TG (`T-260924-G7LB`). No model has been built to it yet. The numeric budgets in [§ A5](#a5-quality-tiers) are a first calibration and **will be tuned against the first commissioned delivery** — that is expected, not a sign the standard is wrong. --- ## Part A — What to deliver ### A1. The package One folder per house. `` is the house's key (see [§ A3](#a3-names)), e.g. `villa-140`. ``` villa-140/ ├── house.json the manifest — what can be configured (§ A2) ├── villa-140.high.glb three quality tiers of the same house (§ A5) ├── villa-140.standard.glb ├── villa-140.low.glb ├── plans/ │ ├── villa-140.plan.size-120.svg one floor plan per layout variant (§ A8) │ ├── villa-140.plan.size-140.svg │ └── villa-140.plan.size-160.svg └── source/ ├── villa-140.blend the editable source (§ A9) ├── textures/ └── README.txt ``` - `HM-1` The package contains `house.json`, exactly three `.glb` files named `.high.glb`, `.standard.glb` and `.low.glb`, a `plans/` folder and a `source/` folder. ### A2. The manifest — `house.json` A small file that says what a customer can configure. It is the first thing Specify reads, and the models are checked against it. The format is defined exactly by [house.schema.json](house.schema.json); an example: ```json { "standard": "specify-house-model/1", "house": "villa-140", "name": "Villa 140", "groups": [ { "key": "size", "kind": "geometry", "layout": true, "default": "140", "options": ["120", "140", "160"] }, { "key": "garage", "kind": "geometry", "default": "no", "options": ["no", "yes"], "empty": ["no"] }, { "key": "roof", "kind": "geometry", "default": "gable", "options": ["gable", "hip"] }, { "key": "facade", "kind": "material", "default": "brick", "options": ["brick", "wood", "render"] } ], "rooms": { "entrance": "Entrance", "living": "Living room", "kitchen": "Kitchen", "bedroom-1": "Bedroom 1", "bedroom-2": "Bedroom 2", "bathroom": "Bathroom" }, "views": { "front": "Front", "garden": "Garden side" } } ``` A **group** is one thing the customer chooses. There are two kinds: - **`geometry`** — the choice changes the shape of the house (size, garage, roof shape). Each option is a set of parts shown or hidden (§ A4). - **`material`** — the choice changes a surface's finish (facade, roof covering, window frames). Each option is a material variant (§ A6). - `HM-2` `house.json` validates against `house.schema.json`, and `standard` is exactly `specify-house-model/1`. - `HM-3` Every group has a `default` that is one of its `options`. - `HM-4` An option listed in `empty` is allowed to show no parts at all (e.g. `garage: no`). Every other geometry option must show at least one part in every combination (§ A4). - `HM-5` At least one geometry group is marked `"layout": true` — the groups that change the floor plan. Usually this is only `size`. - `HM-6` The number of geometry combinations — the product of the option counts of every geometry group — is at most **64**. ### A3. Names Every key — the house, a group, an option, a room, a view, a material slot — uses only **lower-case letters, digits, hyphens and underscores**, and starts with a letter or digit: `villa-140`, `size`, `140`, `bedroom-1`, `window-frame`. - `HM-7` Every key matches `^[a-z0-9][a-z0-9_-]*$`. These are the same characters Specify's configurator uses for its own row and option keys, **on purpose**: a group called `size` with an option `140` connects to a configurator row `size` with an option `140` automatically. If the housebuilder's configurator already exists, use its keys. ### A4. Scene structure and variant parts The scene is one root node named `house`, with two children, `exterior` and `interior`. Everything else goes underneath one of them. **A part that only appears for certain choices is tagged in its node name**: | Node name | Shown when | |---|---| | `var:garage=yes` | the garage is `yes` | | `var:size=160` | the size is `160` | | `var:size=160;roof=hip` | the size is `160` **and** the roof is `hip` | | *(anything without `var:`)* | always | Put the tag on a **group node** (an Empty in Blender) and place the meshes inside it; they inherit its visibility. A node inside a hidden node is hidden too. - `HM-8` The root node is named `house` and has exactly the children `exterior` and `interior`. - `HM-9` A tagged node's name is `var:` followed by one or more `group=option` conditions joined by `;`, where every group is a `geometry` group in `house.json` and every option is one of its options. A condition names each group at most once. - `HM-10` For **every** combination of geometry options (up to 64, § A2), each geometry group's chosen option shows at least one part — unless it is listed in `empty`. This is what catches the missing `var:size=160;roof=hip` roof. - `HM-11` Node names are unique, **except** that a trailing `.001`, `.002` … (which Blender adds to duplicates) is ignored — so two nodes may both be `var:garage=yes` if one is in `exterior` and one in `interior`. ### A5. Quality tiers You deliver the **same house three times, at three levels of detail**. Specify's viewer picks the one the customer's device can carry. | Tier | For | Triangles, whole house, every variant present | Largest texture | Texture images | Delivered `.glb` at most | |---|---|---|---|---|---| | **High** | desktop computers with a good graphics card | 1,500,000 | 4096 × 4096 | 64 | 250 MB | | **Standard** | ordinary laptops, recent phones | 300,000 | 2048 × 2048 | 32 | 60 MB | | **Low** | older phones, slow connections, the wireframe view | 60,000 | 1024 × 1024 | 16 | 12 MB | Counts are for the file as delivered, with **every variant part present** — the worst case, not a typical configuration. Specify compresses geometry and textures for serving, so you may deliver uncompressed. **The three tiers must have the same structure.** Detail differs; names do not. - `HM-12` Each tier is within its budget on every column above. - `HM-13` All three tiers have identical sets of `var:`, `room:` and `view:` node names, identical material slot names and identical material variant names. - `HM-14` **Low tier: clean hard edges.** The wireframe view draws the Low tier's edges, so walls, roofs and openings must read as clean architectural lines — no stray diagonals across flat faces where they would show as edges, no decimation noise. ### A6. Materials Physically based materials only, in glTF's standard metallic-roughness model. Each material is named for the surface it covers: - `HM-15` Every material is named `mat:`, e.g. `mat:facade`, `mat:roof`, `mat:window-frame`, `mat:glass`, `mat:floor`, `mat:wall-interior`. **Material choices use the glTF extension `KHR_materials_variants`**, which Blender's glTF exporter supports: the same mesh carries one material per variant. Each variant is named `group=option`, matching a `material` group in `house.json` — e.g. variants `facade=brick`, `facade=wood`, `facade=render`. - `HM-16` Every `material` group in `house.json` has one variant per option, named `group=option`, and the default option's material is also the mesh's own material. - `HM-17` Textures are PNG, JPEG or WebP, embedded in the `.glb`, with power-of-two dimensions. - `HM-18` Ambient occlusion, if baked, goes in the material's `occlusionTexture` (it may use a second UV set, `TEXCOORD_1`). Do not bake lighting into the base colour: the viewer lights the house, and baked-in light and shadow would double. ### A7. Interior layout The interior is the **layout, not the furnishing**: walls with their real thickness, floors, interior doors (the opening and the door leaf), windows (frame and glass), and stairs where there is more than one storey. No loose furniture, no appliances, no decoration. Each room is a node named `room:`, containing that room's floor. Room names shown to customers come from the `rooms` map in `house.json`. - `HM-19` Every room in `house.json` has a `room:` node under `interior`, and every `room:` node is listed in `house.json`. - `HM-20` A room's floor lies at its storey's floor level and is a single closed surface, so Specify can compute its area. - `HM-21` No furniture, appliances or decorative objects. (Built-in kitchens and bathrooms may be added as a later extension of the same model — not in this version.) ### A8. Floor plans One plan per **layout variant** — one per combination of the groups marked `"layout": true`, which is usually one per size. A roof or cladding choice does not change the plan, so it does not need its own. - `HM-22` One plan per layout combination, named `.plan.-