The document

A design is one YAML file. It is pure data — there is no kind: custom, no inline code and nothing that executes, so a design.yaml is always safe to open and safe to share.

schema: furniture-cad/v0.1

meta: { ... }          # who and what this is
units: mm              # metric only
catalogs: { ... }      # which catalogue versions to compile against
parameters: [ ... ]    # the numbers a person would change
requirements: { ... }  # design intent the validator can check
materials: [ ... ]     # the stock this piece is made from
parts: [ ... ]         # blanks, and what is cut into them
joints: [ ... ]        # what touches what, and with which hardware
assembly: { ... }      # which part is held still, and how it comes apart
outputs: { ... }       # what to draw and export

materials and parts are the only sections that are required. A document with no joints compiles — you get a pile of parts at the origin — which is occasionally what you want while you are working out blank sizes.

The order does not matter, but write it this way anyway

YAML mappings are unordered and the resolver does not care. References are resolved lazily: a parameter may reference a material, a material may reference a parameter, and a part may reference another part. There is no phase ordering to obey, and a genuine loop is reported as RES-003 naming the actual cycle.

Write the sections in the order above regardless. It is the order the pages here follow, the order the authoring pack emits, and it reads top-down: the numbers, then the stock, then the parts, then what holds them together.

schema:

schema: furniture-cad/v0.1

Required, and the first line. It is how a file written against an older version of this reference is recognised as such rather than mis-parsed.

meta:

meta:
  id: walnut-platform-bed-queen
  title: Walnut slatted platform bed — Queen
  description: >
    A knock-down platform bed in solid walnut with a panelled headboard. Rails
    bolt to the posts so the whole thing comes apart to get up a staircase.
  author: claude-cad
  tags: [bed, knock-down, slatted, walnut]

Key
id	required	Stable identifier. Keep it across repairs — it is how the app recognises a re-emitted file as the same design rather than a new one.
title	required	What a person calls the piece.
description		Prose. Reaches the drawing’s title block.
author		Free text.
created		ISO date.
tags		Free-text list, for the design library.

units:

units: mm

Optional, and mm is the only accepted value. It exists so that a file written in inches is rejected with a clear message rather than compiled into a piece of furniture forty times too large. Every number in the document is millimetres, except angles, which are degrees.

See Units and precision.

catalogs:

catalogs:
  materials: std/lumber@1
  fixtures: std/fixtures@1
  standards: std/standards@1

Pins which catalogue the ids in this document resolve against. This is the closest thing the format has to an import: nothing is copied into your file, and the catalogue is not something you author — you name a version of it and then reference entries from materials, joints and parameters.

All three keys are optional and default to the bundled std/…@1. Unless you have a reason, leave them at the defaults or omit the section.

What each family contains, and how a reference resolves, is How the catalogue works.

The rest

Each of the remaining sections has its own page:

• Parameters and expressions — the numbers, and the only computation in the format
• Requirements — intent the validator can check
• Materials — narrowing a catalogue family to a real board
• Parts — blanks, grain and instances
• Features — what is cut into a blank
• Anchors — the placement model, and the concept to read first
• Joints — what touches what
• Arrays — slats, shelves, pickets
• Assembly and outputs — the ground part, groups, exports

A complete, minimal document

Two parts, one screw, nothing derived:

schema: furniture-cad/v0.1

meta:
  id: shelf-and-cleat
  title: One shelf on one cleat

units: mm

materials:
  - id: pine
    from: lumber.softwood.s4s
    species: pine
    thickness: 25
    width: 195

parts:
  - id: shelf
    material: pine
    grain: length
    blank: { length: 800, width: 195, thickness: 25 }

  - id: cleat
    material: pine
    grain: length
    blank: { length: 800, width: 40, thickness: 25 }

joints:
  - id: shelf_to_cleat
    kind: screwed
    fixture: fixtures.wood_screw.4x50
    through: shelf
    mate:
      a: shelf:face.bottom
      b: cleat:face.top
      align: { contact: true }
    fasteners:
      pattern: { along: length, count: 4, spacing: auto, margin: 60 }

assembly:
  ground: cleat

That compiles, and the validator has something to say about it — which is the point.