Skip to content

Latest commit

 

History

History
2344 lines (1992 loc) · 163 KB

file-format.md

File metadata and controls

2344 lines (1992 loc) · 163 KB

The .extrudo file format

Specification of format version 2, for people who write tools that read or write Extrudo projects, and for us. It is derived from the zod schema in packages/core/src/ (the schema is normative; if this text and the schema disagree, the schema wins and this text has a bug) and from the archive code in packages/storage/src/archive.ts. packages/storage/src/file-format-doc.test.ts keeps it honest: it validates the example in section 9 against the real schema and fails when a document key, feature type, feature input, sketch entity, constraint or dimension type, reference kind or unit is missing from this text.

License: this specification is under the MIT license (the text is in file-format.LICENSE, the same as for packages/io), so anyone may implement readers and writers of Extrudo files, in any license. The rest of Extrudo is GPL-3.0-or-later.

Conventions: "must" and "may" are meant in the RFC sense. Numbers are JSON numbers (IEEE doubles). Lengths are millimetres and angles degrees wherever a plain number is stored (only sketch coordinates and radii; every other number is an expression string). An "ID" is a non-empty string.

Contents: 1 Overview, 2 The container, 3 Versioning and migrations, 4 The document, 5 Expressions and parameters, 6 Features, 7 Sketch data, 8 References, 9 Example, 10 IDs, determinism and what is derived.


1. Overview

An Extrudo project is a parametric history, not a shape. The file stores what the user did (sketches, feature inputs, expressions, parameters, the order of features) as JSON. Solids, meshes, sketch profiles, faces and their names are derived by the geometry kernel every time the document is opened or edited; they are never stored (section 10). STEP, STL and 3MF are exports; a tool that wants the editable model reads this format.

Two layers:

  • the document (document.json, section 4 onwards): the model, as JSON;
  • the container (.extrudo, section 2): a zip that holds the document plus a manifest, a thumbnail, saved versions and the files the document names (attachments/).

2. The container

A .extrudo file is a standard zip archive (PKZIP, no encryption, no multi-disk, no zip64 needed for realistic sizes). Entry names use /, are case sensitive and have no leading /. JSON entries are UTF-8, without a byte order mark. The writer (fflate zipSync) pretty-prints JSON with two-space indentation and a trailing newline and deflates entries at the default level; readers must accept any valid JSON formatting and any zip compression method that common zip libraries support (stored or deflate).

Entry Required Content
manifest.json yes A small JSON object identifying the file (section 2.1).
document.json yes The document (section 4).
thumbnail.png no A PNG preview; the app writes 256 x 256. Stored uncompressed (already compressed).
versions/index.json no { "versions": [ VersionSummary… ] } (section 2.2). Written only when there is at least one version.
versions/<n>.json one per index entry The complete document as it was when version n was saved. Same schema as document.json.
attachments/<sha256> one per file the document or a version names The bytes of an attachment (section 4.5), named by their SHA-256. Stored uncompressed (fonts are already compressed). Written only when the design has attachments.

Gzipped files. The app also opens an .extrudo that was gzipped whole (<name>.extrudo.gz, RFC 1952), the way a design comes as a GitHub issue attachment: bytes that start with gzip's magic number 1f 8b are unpacked (at most 256 MB) and then read as the zip above. Extrudo never writes one; on the desktop such a file opens as a copy that isn't linked to its path.

Reserved for later, not written or read by format version 2: cache/ (kernel-derived data that a reader may drop). A reader must ignore any entry it does not know, including that one; a writer that copies a file it edited should keep unknown entries when it can.

Attachments (P4-03b, ADR-0061) are content-addressed: the entry's name is the lower case hex SHA-256 of its bytes, and one file is written once however many attachments or versions refer to it. A reader must check that name against the bytes and leave out an entry that doesn't match (a hand-edited or truncated file); a document that names a file the zip lacks still opens, with its texts shown without letters. An importer writes the bytes into its own store before the document that names them.

2.1 manifest.json

Field Type Meaning
format "extrudo" Required. The file is refused ("not an Extrudo project") unless this is exactly the string extrudo.
formatVersion integer Required. The format version the writer used (currently 2). A file without an integer here is refused as damaged. A reader migrates by document.json's own formatVersion, but treats the file as newer when either number is above what it knows (section 3).
appVersion string Version of the app that wrote the file (copy of meta.appVersion).
created ISO 8601 string Copy of meta.created.
units mm, cm, m or in Copy of settings.units.

The manifest lets a file browser show a project without parsing the document. format and formatVersion are checked when reading; unknown manifest fields are ignored.

2.2 versions/index.json

{ "versions": [ … ], "next": 4 }, versions oldest first. next (optional integer, since P3-13) is the number the next version gets: versions can be deleted, and numbers are never given out twice. Without it (older files) the next number is one past the highest listed. Each element:

Field Type Meaning
number integer, at least 1 1, 2, 3, ... in the order saved ("V3"); gaps where versions were deleted. Names the entry versions/<number>.json.
description string What the person saving it wrote; may be empty.
created ISO 8601 string When the version was saved.
name string The project's name then.

A reader drops index elements that are not well formed and sorts the rest by number. The index itself being unreadable, or a listed versions/<n>.json missing or not valid JSON, makes the file damaged. Each version document goes through the same loading pipeline as document.json (section 3), so an old file's versions are migrated too. A version keeps the project's id (restoring it does not change the ID; opening it as a copy gives it a new one).

2.3 Import rules (the reference reader)

  1. Unzip. Not a zip: error not-a-zip.
  2. manifest.json missing, unparsable, or format not extrudo: error not-extrudo. No integer formatVersion: error damaged.
  3. document.json missing or not JSON: error damaged.
  4. Load document.json through the pipeline of section 3 (may fail with not-a-document, too-new, invalid). The file counts as newer when the manifest's or the document's formatVersion is newer than the reader's.
  5. Read the thumbnail, the versions and the attachments/ entries if present. An attachment entry whose bytes don't hash to its name is left out, and the project opens with what is there (the app tells the user which fonts are missing). Store the bytes before saving the document that names them.
  6. When the project's id is already in the reader's store, the app imports the file as a copy with a new ID rather than overwriting.

3. Versioning and migrations

document.json carries format (always "extrudo") and formatVersion (an integer; the current one is 2). The rules:

  • Breaking changes bump formatVersion. A breaking change is anything but adding an optional field: removing or renaming a field, changing a type or meaning, making an optional field required, tightening a constraint.
  • Additive changes do not bump it: new optional fields (unit on expression inputs, bodies[..].opacity, visible, ghost, a sketch's projections, a reference's fingerprint were all added this way, and so were the components of P6-05: components, bodies[..].component and features[..].component, section 4.7, and its joints, section 4.8, and the annotations and annotationCounter of P6-23, section 4.10, and the sheets of P6-24, section 4.11), new feature types (Feature.type is an open string), and new kinds of sheet item (section 4.11.3).
  • Objects are strict, reading is lenient. Every object in the schema names the keys it doesn't know, and the reader leaves them out and tells the user (since P3-13; before, a file with an optional field added after the reader was built was refused like a typo). So an older reader opens a newer file of the same version, losing only what it doesn't know. The same holds for a feature's input names: the recompute ignores an input its feature type doesn't define and marks the feature with a warning ("This version of Extrudo doesn't know the input…"). A sheet item whose kind the reader doesn't know is left out the same way and listed by its path (sheets.0.items.2); an item with no kind is damage. Writers of other tools must not add private keys to the document all the same: a reader drops them, and there is no extensions bag in format 2.
  • Reading a document (loadDocument):
    1. The value must be an object with format === "extrudo" and an integer formatVersion, else not-a-document.
    2. formatVersion greater than the reader's known version: the reader tries to read it as its own version, leaving out unknown keys. If that validates, the document opens and the user is told it came from a newer Extrudo and what was left out (loadNotice); if anything else fails (a changed type or shape), the error is too-new ("saved by a newer Extrudo… Update Extrudo to open it"), with the issues. Opening an imported file this way never changes the file (the project is a copy); a stored project opened this way is written back in the reader's version when it is saved, which the notice says. The app keeps no read-only mode.
    3. Otherwise the raw JSON is copied and migrated one step at a time (from → from + 1) until it is at the current version. Migrations work on raw JSON and never on the current types, are pure, and get their IDs and timestamps from the caller so they can be tested.
    4. The result is validated against the current schema (section 4 onwards), leaving out unknown keys as above (LoadResult.dropped lists their paths, like features.0.inputs.distance.tolerance); any other failure is invalid ("the document is damaged") with the list of issues.
  • Writing always writes the current version; a file read at an older version is saved back at the current one.
  • Version 0 is a draft shape from before the v1 schema (top-level units, parameters without IDs, disabled instead of suppressed, sketch lists as arrays). No release ever wrote it; it exists so the migration chain has a first step and a fixture (packages/core/fixtures/v0-bracket.json).
  • Version 1 → 2 (ADR-0086): a parameter's customizer.min, max and step were numbers in the base unit and became expressions (section 5.1.1); the migration writes each with its base unit spelled out (25.4 → "25.4 mm", 30 on an angle → "30 deg", plain on a unitless parameter), so a design in inches still reads them as millimetres. customizer.group moved to the parameter's own group (section 5.1). An older reader opens a version 2 file as its own version (above) unless a range is there: a string where it expects a number makes it too-new. A third-party writer should write version 2.

4. The document

document.json is one JSON object. Every object below is strict: the schema names unknown keys, and a reader leaves them out (section 3). "Required" means the key must be present.

Key Type Required Meaning and constraints
format "extrudo" yes Literal.
formatVersion 2 yes Literal 2 in this specification.
id ID yes The project's identity (a UUID v4 from crypto.randomUUID() in practice; any non-empty string is accepted). Names the project in storage.
name string yes Non-empty. Shown in the app bar and the home screen.
settings object yes Section 4.1.
parameters array of Parameter yes User parameters (section 5.1). May be empty.
features array of Feature yes The timeline, in order (section 6). May be empty.
timelineMarker integer yes At least 0 and at most features.length. The number of active features: the feature at index i >= timelineMarker is rolled back (not evaluated). features.length means everything is active.
groups array of Group no Folds of the timeline (section 4.6). Absent means the design has none.
components array of Component no Named sets of bodies, in browser order (section 4.7). Absent means the design has none.
joints array of Joint no As-built joints between components, in browser order (section 4.8). Absent means the design has none.
annotations array of Annotation no Numbered notes on geometry, points and sketches (section 4.10). Absent means the design has none.
annotationCounter integer no At least 1: the highest annotation number ever given (section 4.10). Absent until the first annotation; stays when every annotation is deleted.
sheets array of Sheet no Drawing sheets made from the model, in page order (section 4.11). Absent means the design has none.
bodies object yes Record from body ID to BodyMeta (section 4.2). May be empty. Keys are IDs the kernel makes (section 10).
views array of NamedView yes Saved camera views (section 4.3). May be empty.
render object no Render Picture settings (section 4.9). Absent until the first render.
configurations array of Configuration no Named value sets for the customizer (section 5.4). Absent means the design has none.
attachments object no Record from attachment ID to Attachment (section 4.5). Absent in designs with no files of their own.
meta object yes Section 4.4.

Whole-document rules (checked after the per-field rules):

  • timelineMarker must not exceed features.length.
  • Feature ids are unique; parameter ids are unique; parameter names are unique; view ids are unique; group ids are unique; configuration ids are unique and configuration names are unique trimmed and case-insensitively ("Small box" and " small box " are the same name); component ids are unique and component names are unique case-insensitively ("Lid" and "lid" are the same name); joint ids are unique and joint names are unique case-insensitively too. Every other name is compared exactly, case sensitively.
  • Every component a body (4.2) or a feature (6) names must be a component of components, and a component's ghost comes only with visible: false (section 4.7).
  • A joint's two sides name components of components, and different ones; its limits come only with a revolute or a slider, in the unit the type takes; and each frame's reference is a kind the type reads (section 4.8).
  • Annotation ids are unique and annotation numbers are unique; every number is at most annotationCounter; a sketch anchor names a feature of type sketch in features (section 4.10).
  • Sheet ids are unique and sheet names are unique case-insensitively; view ids and item ids are unique in the whole design; view names are unique case-insensitively in their sheet; a projected view's parent is another view of the same sheet, with no cycle; an item's view is a view of its sheet and its anchors fit its kind; a balloon's list is a parts list of its sheet; a table's rows have one cell per column (section 4.11).
  • Each group (section 4.6) must name features that exist, run forwards along the timeline, and not share a feature with another group.
  • A text entity whose font is attachment:<id> needs that id in attachments (section 7.1), and an input of kind file (section 6.1) needs its id there too, of a media type that feature reads (6.28 for an import, 6.29 for a canvas): the file is written before the document that names it, so nothing names a file the design doesn't carry. A missing attachment record makes the document damaged (section 3); a document whose attachment bytes are missing from the container is not damaged (section 2).
  • Each feature's inputs is additionally checked per feature type (section 6); the document schema alone only knows the generic input shapes.

4.1 settings

Field Type Required Meaning
units "mm", "cm", "m", "in" yes The document's length unit: what a plain number in a length field means, and what the app displays. Stored lengths in sketches are always mm regardless. When the app changes it (the browser's Document settings, ADR-0113 §1), it writes the previous unit onto every plain length number first (10 → 10 mm), so the model keeps its size.
precision integer 0 to 8 yes Decimal places shown for lengths and angles. A new document uses 2.
fractions boolean no Show inch lengths as the nearest binary fraction (1 1/2 in, 3/8 in, 0 in) instead of decimals (ADR-0113 §3). Absent = false; only meaningful with units: "in"; the denominator follows precision (2^(precision + 2), capped at 64). Areas, volumes and angles stay decimal.

4.2 bodies[<bodyId>] (BodyMeta)

Name, appearance and visibility of a body. The geometry is derived; this record only holds what the user chose. A body appears here after the first recompute that produces it.

Field Type Required Meaning
name string yes Non-empty. Defaults are Body1, Body2, ... and are never reused.
color string #rrggbb no Six hex digits (either case): a swatch or any custom colour (the app writes lower case). Absent: the theme's default body colour.
opacity number 0.1 to 1 no Absent: opaque.
visible boolean yes Whether the body is drawn.
ghost boolean no true only, and only with visible: false (ADR-0030's amendment, 2026-10-09): the body is drawn as a grey see-through shape that takes no part in anything. Older readers leave the unknown key out and show the body hidden.
component ID no The id of the component (4.7) the body belongs to (P6-05, ADR-0081 §2). Absent: the body is loose, in no component. Must name a component of components.

Entries whose body no longer exists are harmless; a body without an entry gets one at the next recompute.

4.3 views[] (NamedView)

A view the user saved from the nav bar's Named views menu or the browser's Named views folder (added 2026-10-10; ADR-0008's amendment). Nothing refers to a view, so deleting one is always allowed.

Field Type Required Meaning
id ID yes Unique among views.
name string yes Non-empty. Defaults are View1, View2, ... the lowest number no view uses; a name taken by another view is saved as the next free "<name> 2".
camera object yes projection ("perspective" or "orthographic"), position, target, up: each of the last three is a [x, y, z] array of three numbers, in world millimetres. The world is Z up. position is the camera's own point; up the camera's up direction. An optional size (number, positive) holds the visible height through the target in mm — orthographic views only: their camera sits far back at a distance that depends on the zoom, so position, target and up alone don't fix the view's size. A perspective view needs no size: its position's distance from the target already fixes it.
section object no The section shown when the view was saved (ADR-0045's amendment of 2026-11-06). Absent: the view has no section, and restoring it leaves the section on screen alone. Shape below.

The section object has a kind:

Field Type Required Meaning
kind string yes "planes" or "box".
planes array planes only 1 to 3 section planes. Each has plane (a reference as in section 8: an origin plane origin:xy/origin:yz/origin:xz, a construction plane feature's ID, or a flat face), offset (an expression in the document's length unit, along the plane's normal), flip (boolean: the removed side is the one the normal points away from, unless flipped) and on (boolean: clipped, or kept but switched off).
center array of 3 expressions box only The box's centre [x, y, z], each an expression in the document's length unit, world axes (Z up).
half array of 3 expressions box only The box's half-sizes along x, y and z, expressions in the document's length unit.
on boolean box only The box clips, or is switched off.

A parameter rename rewrites the expressions here; deleting a parameter a section uses is not refused. A plane reference that no longer resolves is not an error: the view restores it as a lost plane.

4.4 meta

Field Type Required Meaning
created ISO 8601 datetime string yes When the project was created. Must satisfy zod's z.iso.datetime() (UTC Z suffix, e.g. 2026-09-29T10:00:00.000Z).
modified ISO 8601 datetime string yes Set by storage when it saves, not by editing commands (so undo does not touch it).
appVersion string yes The writer's version, for diagnostics.

4.5 attachments[<attachmentId>] (Attachment)

A file that travels with the design (P4-03b, ADR-0061; P4-06, ADR-0066 §0). The record says what the file is; its bytes live beside the document, never in it — in the container as attachments/<sha256> (section 2) and in the app's project store as projects/<id>/attachments/<sha256>. Three kinds of file exist so far: a font (a sketch text entity's attachment:<id>), a model an import feature reads (6.28), and a canvas image (6.29).

Field Type Required Meaning
name string yes 1 to 200 characters. What the user sees, e.g. Comic Neue Bold.
fileName string yes 1 to 255 characters. The name of the file it was added from, so an export can offer it back.
mediaType one of font/ttf, font/otf, font/woff, model/step, model/stl, model/3mf, model/obj, application/x-openscad, image/png, image/jpeg, image/webp, application/x-extrudo-plugin yes How the bytes are to be read. WOFF2 is not accepted: the font shaper can't read it, so such a file is refused. A reader must take the type from the file name's extension, never from the browser's File.type (empty for most of these): .ttf, .otf, .woff, .step/.stp, .stl, .3mf, .obj, .scad, .png, .jpg/.jpeg, .webp, .extrudo-plugin (case apart). application/x-openscad (P5-04, ADR-0071) is an OpenSCAD source file, UTF-8 text. application/x-extrudo-plugin (P6-03, ADR-0077) is a plugin file, a zip of its manifest and module, carried by a design whose plugin features use it (section 6.32).
sha256 string yes Exactly 64 lower case hex digits: the SHA-256 of the bytes, which is the name of the file in the container and in storage.
size integer yes At least 1. The file's size in bytes, used for the storage limits (one file at most 25 MB, all of a design at most 100 MB; raised in P4-06 for imported models, ADR-0066 §0).

Content-addressed. Two attachments (or an attachment and a version) with the same sha256 are the same file and are stored once. A record whose bytes are missing, or an entry whose bytes don't match its name, is harmless: the design opens, the texts that need a missing font show without letters and the feature that names a missing file fails with "The file is missing from this design." An attachment record nothing refers to any more is dropped by the writer of the document (the app's commands refuse to drop one a text uses); the bytes are collected when the project saves a version.

4.6 groups[] (Group)

A fold of the timeline (P4-09, ADR-0065 §1, FR-TL-06): a run of neighbouring features the app draws under one name, folded into one chip or open with its members on a band. The group is a range, not a list of members, which is what keeps it contiguous: its members are exactly the features between first and last, inclusive, in timeline order. Nothing else in the file depends on groups: the engine, the naming and the recompute ignore them, so folding a timeline never changes the geometry it computes.

Field Type Required Meaning
id ID yes Unique among groups, permanent (section 10).
name string yes 1 to 100 characters. Defaults are Group1, Group2, ...; the app numbers them above every group the design still has.
first ID yes A feature ID: the feature the group starts at. Must be in features.
last ID yes A feature ID: the feature the group ends at. Must be in features, at or after first in the timeline.
collapsed boolean yes Whether the timeline draws the group folded into one chip. Stored, so reopening a design shows it as it was folded.

A group is a range, so what it holds follows from the timeline around it: a feature that ends up between first and last is in the group, an end that is moved away moves that end to the next member inside (an end whose ends swap places makes the group run from the earlier to the later one), and a group whose members are all gone is dropped, groups key and all. Groups never nest and never overlap; a group that would share a feature with a group before it in groups is dropped. The app's commands apply these rules after every change that reorders or removes features, so a document written by the app is always in this state. A document that is not (hand-edited, or written by something else) is read as it is and the app repairs it with the next change.

Two groups may sit next to each other (first of the second is the feature after last of the first); a group of a single feature is legal.

4.7 components[] (Component)

A component (P6-05, ADR-0081): a named, user-made set of bodies that shows, hides, exports and is placed as a unit (a box and its lid are two components). The array is in browser order. A design without components is a design of loose bodies, as before components existed.

Field Type Required Meaning
id ID yes Unique among components, permanent (section 10).
name string yes 1 to 100 characters, unique case-insensitively. Defaults are Component1, Component2, ... (the lowest free number); a copy is <name> (2), (3), ...
visible boolean yes Whether the component's bodies are drawn. A hidden component hides every body in it; showing it again restores each body's own state.
ghost boolean no true only, and only with visible: false, the same pair rule as a body's (4.2): the component's bodies are drawn as ghosts, apart from a body that is itself hidden.

Membership lives on the body: a body is in a component when its metadata's component (4.2) names it, so a body is in at most one, and there is no member list here. A body that has no metadata yet belongs where this rule puts it (componentOfBody in @extrudo/core): the component of the body it was broken off (a cut or Split Body that made it a piece of another body), else the component of the feature that made it (6; a Script's generated feature takes the Script's), else none. The app stores the answer when it first names the body; from then on the stored metadata is the truth. A body that disappears keeps its metadata, membership included, and a component whose bodies are all gone stays until it is deleted. Deleting a component clears every body's and feature's component that names it; its bodies stay, loose.

No transform: placement is the timeline's. A component stores no position. Its bodies are where the timeline put them, and moving a component is a move feature (6.12) over its bodies. Nothing in the recompute reads components or either component key, so an older reader that leaves them out (section 3) opens the same geometry, as loose bodies.

4.8 joints[] (Joint)

An as-built joint between two components (P6-05, ADR-0081 §4): a frame picked on each of two components where the parts already are, so making it moves nothing. Side a moves, side b stays: the axis or direction is read from b's frame, and a's must agree with it as built (a revolute's two axes collinear within 0.05 mm and 0.5°, a slider's directions parallel within 0.5°; a frame that disagrees is the joint's warning). A joint moves nothing stored: posing it is a look in the view and its clearance check a query, so nothing in the recompute reads joints and an older reader that leaves them out (section 3) opens the same geometry. The array is in browser order.

Field Type Required Meaning
id ID yes Unique among joints, permanent (section 10).
name string yes 1 to 100 characters, unique case-insensitively. Defaults are Joint1, Joint2, ... (the lowest free number).
type string yes rigid (the two components move as one: a revolute or slider joint that moves one carries the other), revolute (side a turns about an axis) or slider (side a moves along a direction).
a JointFrame yes The side that moves (4.8.1).
b JointFrame yes The side that stays (4.8.1); its component differs from a's.
min expr input no The lower limit: an angle (unit: "angle") for a revolute, a length for a slider; never on a rigid joint. 0 is the as-built position.
max expr input no The upper limit, in the same unit. A revolute without both limits turns a whole turn; a slider needs both to be posed or checked.
flip boolean no true only: reverses the positive direction (a revolute's turn is right-handed about the axis otherwise).
suppressed boolean no true only: the joint is kept but not resolved, posed or checked.

The limits are expression inputs (section 6.1) whose expressions may use parameters; they never carry a paramName of their own, and a parameter they use can't be deleted.

4.8.1 JointFrame

Field Type Required Meaning
component ID yes The component (4.7) the frame is on. Must name a component of components.
ref reference yes The picked geometry (section 6.1), by its persistent name with a fingerprint like any feature's reference.

The kinds a frame's ref may be, per type: a revolute takes a face (a cylindrical or conical one: its axis), an edge (a circular one: its centre and normal; a straight one: its line), an axis (origin or construction) or a sketchEntity (a sketch line); a slider the same kinds, a face being a flat one (its normal through its centre); a rigid joint any face, edge or vertex, or a body. Frames are references by persistent name; components beside them are metadata: the reference never names a component, and the app warns when a frame's body is no longer in the frame's component. The kernel resolves both frames after every recompute at the timeline marker, like a feature appended there: a lost frame is the joint's error (Fix References repairs it), and a frame on a rolled-back feature makes the joint inactive.

4.9 render (RenderSettings)

What the Render Picture dialog last used (ADR-0101; added 2026-10-23, engine added 2026-10-24 with ADR-0101 §6). The dialog writes it when a render starts, so the next render of the design starts from the same choices. The picture itself is never stored: it is derived, and the user saves or copies it from the dialog.

Field Type Required Meaning
preset string yes The scene: studio (a white sweep), table (a wooden table top), workbench (a cutting mat with a 10 mm grid) or outdoor (the ground under a sunny sky).
finishes object no Record from body ID (section 4.2) to a finish: matte, glossy, translucent, resin, metal or wood. Only bodies whose finish isn't matte (the default) are listed; an entry for a body that no longer exists is ignored.
camera object (RenderCamera) yes Which camera the picture uses, by kind: auto (the renderer frames the model itself), current (the viewport's camera when the render starts) or view with the id of a saved view (section 4.3).
width integer yes Picture width in pixels, 256 to 8192.
height integer yes Picture height in pixels, 256 to 8192.
quality string yes draft, standard or high: how long the renderer takes.
engine string no Who renders: app (the app itself, in the browser or the desktop app) or blender (Blender on a desktop, when it is installed). Absent means app. A design that says blender renders in the app where Blender isn't there, and keeps the value.
"render": {
  "preset": "table",
  "finishes": { "extrude-1:0": "glossy" },
  "camera": { "kind": "auto" },
  "width": 1920,
  "height": 1080,
  "quality": "standard",
  "engine": "blender"
}

4.10 annotations[] (Annotation)

A numbered note (P6-23, ADR-0126): "#3: make this hole M4". People pin them in the app and agents read and write them over the MCP server. Each has a number that is unique in the design and never given again: annotationCounter holds the highest number ever given, a new annotation gets annotationCounter + 1 and the counter moves with it, and deleting an annotation keeps the counter. Nothing in the recompute reads annotations: the kernel only resolves model anchors at the timeline marker after a recompute, to draw them, so an older reader that leaves both keys out (section 3) opens the same geometry. The array is in the order the annotations were made.

Field Type Required Meaning
id ID yes Unique among annotations, permanent (section 10).
number integer yes At least 1, unique, at most annotationCounter: the #n people and agents call it by.
text string yes 1 to 2000 characters, plain text; may contain newlines.
anchor AnnotationAnchor yes Where it is (4.10.1).
offset [number, number] no The callout's offset from the anchor in screen pixels (x right, y down). Absent means [28, -28].
hidden boolean no true only: the annotation is not drawn.
done boolean no true only: ticked off; drawn muted and listed last.

4.10.1 AnnotationAnchor

An object whose kind says which of three it is:

kind Fields Meaning
model ref (reference), at ([x, y, z]) On geometry: ref is a reference (section 6.1) of kind face, edge, vertex, body, plane, axis, point or sketchEntity (the model-mode <sketch>/<entity>), by its persistent name, never an index: one; the app always stores its fingerprint. at is where it touches the geometry, world mm.
free at ([x, y, z]) A point in space, world mm.
sketch sketch (ID), at ([x, y]), entity (ID, optional) In a sketch: sketch names a sketch feature; at is in that sketch's own mm. With entity (a sketch point, curve or text of that sketch), at is the offset from the entity's reference point: a point's position, a line's midpoint, a circle's, arc's or ellipse's centre, a spline's mean point, a text's anchor.

A model annotation follows its geometry: the kernel resolves ref like a feature's reference (exact name, related name, fingerprint) and draws the annotation at at moved by as much as the reference's own point moved since the fingerprint was taken (the vertex or point itself for a vertex or point). One whose reference resolves to nothing, or to a feature past the timeline marker, is detached and drawn at at. Deleting a sketch feature deletes its sketch annotations; deleting a sketch entity clears entity and turns at into the sketch position it was drawn at.

"annotations": [
  {
    "id": "6f1c…",
    "number": 1,
    "text": "Make this hole M4",
    "anchor": {
      "kind": "model",
      "ref": {
        "kind": "face",
        "id": "extrude:extrude-1:cap:end",
        "fingerprint": { "type": "plane", "at": [20, 10, 5], "dir": [0, 0, 1], "size": 800 }
      },
      "at": [10, 5, 5]
    }
  },
  { "id": "9a0e…", "number": 3, "text": "Logo here", "anchor": { "kind": "free", "at": [0, -12, 2.5] }, "done": true }
],
"annotationCounter": 3

4.11 sheets[] (Sheet)

A drawing sheet (P6-24, ADR-0143): one page with views of the model and items placed on it, exported as PDF or SVG. Nothing derived is stored: a view says what to draw (a direction, a scale, a style, which bodies), never the lines, so opening the file computes the views again. Every layout number is stored as a number: positions and sizes in mm on the sheet, measured from its top-left corner with y down. Nothing in the recompute reads sheets, so an older reader that leaves the key out (section 3) opens the same geometry. The array is in page order.

Field Type Required Meaning
id ID yes Unique among sheets, permanent (section 10).
name string yes 1 to 100 characters; unique among the sheets, compared case-insensitively.
size string or [number, number] yes A named paper, A4, A3, A2, A1, A0 (ISO 216), letter (215.9 × 279.4 mm), legal (215.9 × 355.6) or tabloid (279.4 × 431.8), or a custom paper's two sides in mm, each 10 to 10000.
orientation string yes landscape (the paper's long side across) or portrait, for a named and a custom size alike.
scale [number, number] yes Both positive: sheet length to model length, [1, 2] is 1:2. The views' scale unless a view has its own.
projection string yes first or third: the projection angle that places projected views.
decimals integer yes 0 to 4: the decimals dimensions show.
border object no A border round the sheet; absent means none. Its one field, zones (true only), adds zone letters and numbers along it.
titleBlock object no A title block; absent means none. template is simple or full; fields is a record from a field name (a letter, then up to 39 letters and digits, like title or drawnBy) to what was typed, at most 2000 characters; a field not in the record is empty.
views array of SheetView yes The views (4.11.1), drawn in order. May be empty.
items array of SheetItem yes Texts and other items (4.11.3), drawn in order after the views. May be empty.

4.11.1 SheetView

Field Type Required Meaning
id ID yes Unique among every sheet's views, permanent.
name string yes 1 to 100 characters, like "Front"; unique in its sheet, compared case-insensitively.
at [number, number] yes The view's origin on the sheet, mm from the top-left corner, y down.
from object yes Which way it looks (4.11.2).
scale [number, number] no The view's own scale, like the sheet's scale; absent means the sheet's. Never on a projected view.
style string no visible (visible edges only), hidden (visible edges and hidden ones dashed), shaded or shaded-edges. Absent means hidden. Never on a projected view.
bodies array of IDs no The bodies drawn, each once, at least one; absent means every shown body. An ID the design has no body for is skipped when the view is drawn, so deleting a feature or a body never changes a sheet.
tangentEdges boolean no false only: tangent edges are left out.
centreLines boolean no false only: centre lines are left out.
label boolean no true only: the view's name and scale are drawn under it.

4.11.2 from

An object whose kind says which of two it is:

kind Fields Meaning
base direction ([x, y, z]), up ([x, y, z]) A base view: looks along direction with up pointing up the sheet, both world vectors, not zero, not parallel, of any length.
projected parent (ID), side (string) A projected view: made from parent, another view of the same sheet (itself base or projected, with no cycle), it stays aligned with it and takes its scale and style. side is where it sits from the parent: left, right, above, below, or one of the isometric corners iso-above-left, iso-above-right, iso-below-left, iso-below-right; the sheet's projection turns it into a direction.

4.11.3 SheetItem

An object whose kind says what it is. Every item has an id, unique among every sheet's items. This version knows nine kinds; later versions may add more, and a reader leaves out an item of a kind it doesn't know (section 3). An item that belongs to a view names it in view, a view of the same sheet, and its positions are in the view's own mm (model size, x right, y up, the world origin at 0, 0), so it moves and scales with the view; removing the view removes it. An item on the sheet itself (a text, a sticky note) has its positions in sheet mm from the top-left, y down.

kind Fields Meaning
text at ([x, y]), text (string), size (number, optional), width (number, optional) A text placed on the sheet. at is its top-left corner, mm. text is plain, up to 2000 characters and not blank; it may contain newlines. size is the letter height in mm, absent means 3.5. width, when present, is the width it wraps at, in mm.
dimension view (ID), type (string), direction (string, optional), anchors (array of SheetAnchor, 4.11.4), at ([x, y]), decimals (integer, optional), before (string, optional), after (string, optional), reference (boolean, optional) A dimension in a view, measured from the model and never driving it; its value is not stored, it is measured each time the sheet is drawn. view is a view of the same sheet (removing the view removes the dimension). type is linear (a distance), radius or diameter (a circle) or angle (between two lines). direction, for a linear one only: horizontal, vertical or aligned; absent means it follows where the dimension is placed. anchors are one or two, fitting the type: linear takes one whole edge or outline (its length) or two anchors that are points or lines; radius one circle (a whole circular edge or a cylinder's face); diameter one circle or two outlines (a cylinder seen from the side); angle two lines (whole edges or outlines). Whether a whole edge is a line or a circle is the model's to say when the sheet is drawn. at is where its text is, in the view's own mm (model size, x right, y up, the world origin at 0, 0), so it moves and scales with the view; when the anchors' geometry moves (a parameter changes), the text moves as far as their fingerprint points moved. decimals is 0 to 4, absent means the sheet's. before and after are written around the value (and before R or Ø), up to 100 characters each. reference (true only) writes it in brackets.
leader view (ID), anchor (SheetAnchor, 4.11.4), at ([x, y]), text (string) A leader note: text with a line and an arrowhead to the model. anchor is any one anchor: a vertex or an edge's point (the arrow ends on it), a whole edge (on the edge's nearest point to the text, on a circle's rim towards it), a whole face (a dot on it), an outline, or a free point. at is where the leader line ends and the text starts, in the view's own mm; it follows the anchor as a dimension's text does. text is plain, up to 2000 characters and not blank; it may contain newlines.
sticky at ([x, y]), size ([number, number]), text (string), color (string, optional), print (boolean, optional) A coloured note on the sheet. at is its top-left corner and size its width and height, mm, 5 to 1000 each. text is plain, up to 2000 characters and not blank, wrapped inside the note. color is yellow, orange, pink, blue or green; absent means yellow. print (true only) puts it in exports; absent, it is shown on screen only.
centreMark view (ID), anchors (array of SheetAnchor) A cross on a circle's centre. anchors is one: a whole edge that is a circle, or a cylinder's face.
centreLine view (ID), anchors (array of SheetAnchor) A dash-dot centre line. anchors are two lines (whole edges or outlines) that are parallel in the view, the line running midway between them, or one cylinder's or cone's face, the line along its axis.
partsList view (ID), at ([x, y]), columns (array of strings, optional), rows (object, optional) A table filled from the bodies of view (its base view's bodies, else every shown body) each time the sheet is drawn: its rows are not stored. Identical bodies share a row with a quantity: equal volume and bounding box, and the same component name or the same name stem (the name without a trailing number, so "Shelf 1" and "Shelf 2"). at is its top-left corner in sheet mm. columns are the columns shown, in that order, each once, from item, qty, name, material, size (the bounding box's three sides, longest first, in the design's unit) and mass (from the app's filament density, which is not in the file); absent means all six. rows holds only what was typed over a row: an object from the ID of the row's first body to { name?, material? }, each up to 200 characters; material is free text. An entry for a body the list no longer shows is kept and ignored.
balloon view (ID), anchor (SheetAnchor), at ([x, y]), list (ID) A numbered circle with a leader to a body. anchor is on geometry (a vertex, an edge or one of its points, a face, an outline), never a free point; the number is the item of that body's row in list, a partsList of the same sheet, and is not stored. at is the circle's centre in the view's own mm; it follows the anchor as a leader note's text does. Deleting the parts list deletes its balloons.
table at ([x, y]), columns (array of numbers), rows (array of arrays of strings) A free table on the sheet. at is its top-left corner, mm. columns are the columns' widths in mm, 1 to 1000 each, 1 to 50 columns. rows are 1 to 500 rows, top to bottom, each with exactly one cell per column: plain text up to 2000 characters, which may be empty or contain newlines; a row is as tall as its text.

The view's centreLines (false) leaves its centre marks and centre lines out. Nothing is added to a view by itself: every centre mark and line is an item someone placed.

Text fields. The text of a text and a leader item, a table's cells and the title block's fields may hold fields in braces, filled in each time the sheet is drawn and stored as typed: {name} (the design's name), {sheet} and {sheets} (this sheet's page number and the number of sheets), {scale} (the sheet's, like 1:2), {date} (the day it is drawn), {version} (the newest saved version's name) and {= expr}, an expression over the design's parameters (section 5.2) written with its unit at the sheet's decimals ({= clearance} gives 0.20 mm). Renaming a parameter rewrites the names in {= …} too. A field that has no value, one this version doesn't know and an expression that doesn't evaluate are drawn as typed.

4.11.4 SheetAnchor

What a dimension measures from, or a leader note, a centre mark, a centre line or a balloon is drawn on: one of three shapes, told apart by their keys.

Shape Fields Meaning
On geometry ref (GeomRef), at (string, optional) ref names a vertex, an edge or a face by its persistent name (section 10) and must carry its fingerprint; an index: reference is refused. at takes one point of an edge: start, end, middle or centre (a circle's or an ellipse's); absent means the whole edge, the vertex, or the face (a cylinder's circle for a radius, a diameter or a centre mark, its axis for a centre line, a point on it for a leader note). A vertex and a face never have at.
On an outline ref (GeomRef), silhouette (1 or -1) The outline of a cylinder or cone face as the item's view sees it: 1 is the one on the side the face's axis (with its canonical sign: first non-zero component positive) crossed with the view's direction points to, -1 the other.
Free free ([x, y]) A point in the view's own mm, tied to nothing.

An anchor whose geometry is gone is not an error: the file still loads and the item is drawn as detached (the reference resolves as a feature's does, section 10: by its name, a related name or its fingerprint). An anchor on geometry of a feature the design no longer has, or one that is suppressed, is detached without that search: a close match there would be another edge.

"sheets": [
  {
    "id": "0b7e…",
    "name": "Bracket",
    "size": "A3",
    "orientation": "landscape",
    "scale": [1, 2],
    "projection": "first",
    "decimals": 1,
    "titleBlock": { "template": "simple", "fields": { "title": "Bracket" } },
    "views": [
      { "id": "41c2…", "name": "Front", "at": [120, 150], "from": { "kind": "base", "direction": [0, 1, 0], "up": [0, 0, 1] } },
      { "id": "7d90…", "name": "Right", "at": [260, 150], "from": { "kind": "projected", "parent": "41c2…", "side": "right" } }
    ],
    "items": [
      { "kind": "text", "id": "c3a1…", "at": [20, 20], "text": "All edges 0.5 mm" },
      {
        "kind": "dimension", "id": "9e04…", "view": "41c2…", "type": "linear", "at": [0, -12],
        "anchors": [{ "ref": { "kind": "edge", "id": "e[box:…:side:front|box:…:cap:start]", "fingerprint": { "type": "line", "at": [0, -20, 0], "dir": [1, 0, 0], "size": 60 } } }]
      },
      { "kind": "sticky", "id": "5f1d…", "at": [300, 30], "size": [50, 30], "text": "Check the fit after the first print." },
      { "kind": "partsList", "id": "a8e2…", "view": "41c2…", "at": [250, 220], "columns": ["item", "qty", "name", "material", "size"], "rows": { "Pad1:0": { "material": "PETG" } } },
      {
        "kind": "balloon", "id": "b310…", "view": "41c2…", "at": [-40, 25], "list": "a8e2…",
        "anchor": { "ref": { "kind": "face", "id": "f[pad:Pad1:side:0]", "fingerprint": { "type": "plane", "at": [-30, 0, 10] } } }
      },
      { "kind": "table", "id": "d6c4…", "at": [20, 230], "columns": [30, 60], "rows": [["Clearance", "{= clearance}"], ["Sheet", "{sheet} of {sheets}"]] }
    ]
  }
]

5. Expressions and parameters

Every number a user can edit is an expression string (never a raw number in a feature input). Sketch coordinates and radii are the only stored plain numbers, and they are the solved values.

5.1 parameters[] (Parameter)

User parameters, the named values of the parameters table.

Field Type Required Meaning
id ID yes Unique among parameters.
name string yes Must match ^[A-Za-z_][A-Za-z0-9_]*$ and be unique. See the extra rules below.
expression string yes An expression (section 5.2), for example 2 mm or width / 2.
unit "length", "angle" or "unitless" yes The kind the expression must evaluate to.
comment string no Free text.
group string no 1 to 40 characters: the group the parameter sits in, a section of the Parameters dialog and a heading in the customizer panel (ADR-0086 §1). Absent means no group.
customizer object no The parameter is shown in the customizer panel. Section 5.1.1.

Rules that the evaluator enforces but the schema does not: a name must not be a reserved word (a unit mm cm m in ft deg rad, a function name, or pi); a user parameter's name must not equal a model parameter's paramName (below). Parameters may refer to each other in any order (the list order is not evaluation order); a cycle is an error reported on every parameter in it. All parameters and model parameters share one namespace. The list order is the order the Parameters dialog and the customizer panel show (ADR-0086 §3); it never changes a value.

5.1.1 customizer

Present = the parameter is exposed for changing in the customizer panel (ADR-0059 §1). Only user parameters can be; model parameters (section 5.3) are not exposed.

Field Type Required Meaning
min string no The slider's range, low end: an expression (section 5.2) in the parameter's unit, like its own ("20 mm", "wall * 5"). Absent means no slider.
max string no The slider's range, high end, an expression in the same unit.
step string no The slider's step, an expression that must evaluate above 0. Absent means the panel's own step.

The panel groups exposed parameters by the parameter's group (section 5.1): parameters without one come first, then the groups in order of first appearance.

A range expression may use other parameters, and it is evaluated whenever the panel shows it, so it follows them. It must not use the parameter itself or a parameter that depends on it (the range would move while the slider is dragged): an app refuses to store one and shows no slider for an end that has come to depend on it since. Neither does a range whose min evaluates above its max get a slider; the schema can't check that, since only evaluating can tell.

The range is a slider range, not a constraint: an expression may evaluate outside [min, max] (the panel shows that with a warning). A parameter whose expression is a plain value (one number with an optional unit) gets a slider when it has both ends; a formula shows its computed value read-only with the formula as a hint.

5.2 Expression language (summary of ADR-0004)

  • Atoms: a number with an optional unit (10 mm, 2.5in, 1e-3 m); a name (a parameter); a call name(args); a parenthesised expression.
  • Operators, loosest to tightest: + - (binary), * /, unary + -, ^ (right-associative, so -2^2 = -4 and 2^3^2 = 512). There is no implicit multiplication (2 width is an error).
  • Units: mm cm m in ft deg rad. A unit may only follow a number literal. Values are held in millimetres and degrees.
  • Fractions, feet and inches (ADR-0113 §3): a length may be a fraction int/int with no spaces (3/8 in) or a mixed number 1 1/2/1-1/2 (1 1/2 in), always with a length unit right after it. The inch and foot marks are units too: 6" is 6 in, 5' is 5 ft. A feet number directly followed by an inches number is their sum (5' 6", 5 ft 6 1/2 in). With no length unit, 10 / 2, 10/2 and width/2 stay arithmetic.
  • Constant: pi. Functions: sin cos tan asin acos atan sqrt abs min max round floor ceil. min and max take one or more arguments, the rest one.
  • Dimensions: length and angle are separate dimensions, so 10 mm + 5 deg is an error. Intermediate results may be areas or volumes; the final result must be what the field needs.
  • Plain numbers take the context unit. A bare literal (or arithmetic on literals only) in a length field means the document's length unit (settings.units), in an angle field degrees. A unitless parameter in a length field is an error; multiply by a unit.
  • Trigonometry takes an angle; a bare number counts as degrees, a non-bare unitless value as radians.
  • Whitespace is insignificant. Names are case sensitive.

Expression fields are stored verbatim as the user typed them (formatting included), so a tool that only reads geometry values should evaluate them, not parse them ad hoc.

5.3 Model parameters

A feature input or sketch dimension may expose its value as a model parameter: its paramName (d1, d2, ...). It then takes part in the same namespace as user parameters, so other expressions can use it. The schema requires only that a paramName match the name regex; uniqueness and non-collision with user parameters and reserved words are the evaluator's job.

5.4 configurations[] (Configuration)

Named value sets to switch between (ADR-0059 §2): the presets of a customizer. Optional; a design without any may leave the key out.

Field Type Required Meaning
id ID yes Unique among configurations, permanent (section 10).
name string yes 1 to 60 characters. Unique trimmed and case-insensitively (section 4).
values object yes Record from parameter ID to the expression this configuration sets for that parameter. Keys are parameter IDs; a value is an expression string (section 5.2).
  • Applying a configuration sets the expression of every parameter it lists. Parameters it doesn't list keep their values. A value for a parameter that no longer exists is ignored (the panel shows it as missing); removeParameter takes such an entry out with the parameter, so a document written by the app has none.
  • No "active" configuration is stored. One would go stale after any edit, undo or slider drag. A tool shows a configuration as current when every value it lists that still exists equals the parameter's expression, compared after trimming (whitespace is insignificant in an expression); undo or a manual edit then simply leaves no configuration current.
  • Writing a configuration (saving a new one, or updating one with the current expressions) captures the expressions verbatim, formatting included.

6. Features

features[] is the timeline. Each element (Feature):

Field Type Required Meaning
id ID yes Unique among features, permanent.
type string yes Non-empty. One of the types below; the schema accepts any string, so a document with an unknown type loads and the app reports that feature as an error. A tool should preserve features it does not understand.
name string yes Non-empty; the user's name ("Extrude1").
suppressed boolean yes true: the feature is skipped, as if not there (its dependants report errors).
visible boolean no false hides the feature's own geometry (a sketch's curves) in the view. Absent: shown.
inputs object yes Record from input name to an Input (below). Which names are allowed depends on type.
component ID no The component (4.7) the feature's new bodies join (P6-05, ADR-0081 §2): the app stamps the active component when it inserts the feature, and editing the feature never changes it. Must name a component of components. The recompute does not read it.

Order matters. A feature can only use things made by features before it. A feature depends on those whose IDs appear in its stored references (profiles, bodies, face/edge names), and the app refuses to move a feature before something it uses. Expressions do not order features.

6.1 Inputs

inputs[<name>] is an object with a kind discriminator:

kind Other fields Meaning
expr expr (string, required); paramName (string matching the name regex, optional); unit (length, angle or unitless, optional, default length) A number as an expression. paramName makes it a model parameter (section 5.3). unit says what it must evaluate to. An angle input must say "unit": "angle": the feature schemas reject an expr whose unit (default length) is not the one the input takes.
enum value (string) One choice from a fixed list; the allowed values depend on the feature and input.
bool value (boolean) A flag.
ref refs (array of GeomRef, required, may be empty) Persistent references to geometry (section 8).
sketchData sketch (SketchData, required) A sketch's 2D content (section 7). Only the sketch feature uses it.
file id (attachment ID string, required) A file of the design itself (P4-06, ADR-0066 §0): the id of an attachments entry (4.5) whose bytes the kernel reads. A document that names an id it doesn't carry, or one of a media type the feature doesn't read, is damaged (section 3), like a text font the design doesn't carry.
labels labels (array of strings, required, may be empty) Names of a design's own making, with nothing to refer to (P4-12): the instances a pattern leaves out, as position labels matching m?\d+(xm?\d+)? (6.16). Only the pattern features use it.
code value (string, required) Source code (P5-02, ADR-0070 §1): a Script's program, as the text the user wrote, at most 100,000 characters. Only the script feature uses it (6.30).
design design (EmbeddedDesign, required) Another design, copied in (P6-26, ADR-0140 §2): its name, unit, parameters and features, below. Only the insertDesign feature uses it (6.37).

Feature-specific rules below are enforced by the per-type inputs schema (each inputs object is strict too: the recompute ignores unknown input names with a warning, section 3). "Optional" inputs may be absent; the default is what a reader must assume.

6.2 sketch

A sketch on a plane or a flat face (label "Sketch", category sketch).

Input Kind Required Rule
plane ref yes Exactly one reference, of kind plane (an origin plane origin:xy, origin:xz, origin:yz, or a construction plane's feature ID, 6.10) or face.
sketch sketchData yes The sketch content (section 7).

A sketch's 2D frame (origin, X, Y, normal) is derived: for an origin plane it is fixed (below); for a face it is computed from the face's plane and reported by the kernel.

Plane X Y Normal
origin:xy (1, 0, 0) (0, 1, 0) (0, 0, 1)
origin:xz (1, 0, 0) (0, 0, 1) (0, -1, 0)
origin:yz (0, 1, 0) (0, 0, 1) (1, 0, 0)

All three have their origin at the world origin.

6.3 Shared pieces of solid features

The four body operations (operation, an enum input): new-body (default), join, cut, intersect. bodies (a ref input of kind body references, body IDs) chooses the participants of join, cut and intersect; absent or empty means every body the new solid touches (join) or overlaps (cut, intersect). A feature that yields several separate solids makes one body per solid.

Reading conventions for all solid features: inputs the chosen mode does not use are ignored but may be kept (so a dialog can switch back and forth); a length expr input must have unit absent or length; an angle one must have "unit": "angle".

6.4 extrude

Sweeps sketch profiles or flat faces straight along their plane's normal. Every input is optional in the schema; a useful extrude has profiles and distance (without profiles the feature fails in the kernel).

Input Kind Rule Default and meaning
profiles ref Refs of kind profile, face or sketchEntity, any number, all in one plane. A sketchEntity ref names a text (<sketch>/<textId>) and means all of that text's letters (section 8, ADR-0058 §5) none: the feature fails until some are picked
direction enum one-side, symmetric, two-sides one-side. Symmetric is centred on the plane and distance is the whole length; two-sides uses side 2 inputs too
extent enum distance, to-object, through-all distance (side 1)
distance expr length Side 1's length; negative goes the other way
symmetricMeasure enum whole, half How distance measures a symmetric sweep: whole (the whole length, the default) or half (the length of each side, so the body is twice distance long). Read only for symmetric, and stored only when half
toObject ref At most one ref of kind face (flat or curved), body, vertex or plane Side 1's target for to-object: the sweep ends where it first meets the face's surface (extended past the face) or the body
offset expr length Side 1's offset from toObject, default 0: the target is moved along the sweep by it, so positive ends past it and negative short of it. Read only for to-object
taper expr angle Side 1's taper, default 0. Positive widens along the sweep, negative narrows
extent2 enum as extent Side 2 of two-sides
distance2 expr length Side 2's length
toObject2 ref as toObject Side 2's target
offset2 expr length Side 2's offset from toObject2
taper2 expr angle Side 2's taper
flip bool Reverses the direction, default false
operation enum section 6.3 new-body
bodies ref body refs section 6.3

6.5 revolve

Turns profiles or flat faces about an axis in their plane. Optional inputs as for extrude; a useful revolve has profiles and axis.

Input Kind Rule Default and meaning
profiles ref refs of kind profile, face or sketchEntity. A sketchEntity ref names a text (<sketch>/<textId>) and means all of that text's letters (section 8, ADR-0058 §5) none: fails until picked
axis ref At most one ref of kind axis (origin:x, origin:y, origin:z), sketchEntity (<sketch>/<line>) or edge (a straight edge) none: fails until picked. Must lie in the profiles' plane
direction enum one-side, symmetric, two-sides one-side
extent enum angle, to-object angle. to-object turns one side (direction must be one-side) until it first meets toObject; the angles are ignored
toObject ref At most one ref of kind face (flat or curved), body or plane The target for to-object
angle expr angle Side 1 (the whole angle when symmetric); default a full turn, 360 deg (no end faces). Right-handed about the axis. Negative turns the other way
symmetricMeasure enum whole, half How angle measures a symmetric revolve: whole (the whole angle, the default) or half (the angle of each side, so it turns twice as far in all). Read only for symmetric, and stored only when half
angle2 expr angle Side 2 of two-sides, the other way round; default 0
flip bool Turns side 1 the other way, default false
operation enum section 6.3 new-body
bodies ref body refs section 6.3

6.6 Primitives: box, cylinder, sphere, torus

Four feature types with one input set for placement and one for size. Every input is optional; the minimal feature has "inputs": {} (a 20 mm cube, new body, on the XY plane at the origin).

Placement (all four):

Input Kind Rule Default and meaning
plane ref At most one ref of kind plane or face The XY plane (origin:xy)
x expr length 0. The primitive's centre along the plane frame's X
y expr length 0. Along the frame's Y
offset expr length 0. Lifts the base (a sphere's or torus's centre) off the plane along its normal
operation enum section 6.3 new-body
bodies ref body refs section 6.3

Sizes:

Type Input Default Meaning
box length 20 mm Along the frame's X (turned by rotation); must be greater than 0
box width 20 mm Along the frame's Y; greater than 0
box height 20 mm Along the normal from the base; negative goes below the plane
box rotation (expr angle) 0 deg Turns the box about the normal through its centre, right-handed, from the frame's X
cylinder diameter 20 mm Base centred on the point; greater than 0
cylinder height 20 mm As the box's height
sphere diameter 20 mm Centred on the point; greater than 0
torus diameter 40 mm Through the tube's centre line; greater than 0
torus tube 10 mm The tube's own diameter, smaller than diameter
torus axis (enum) normal Where the ring's axis points, in the plane's frame: normal (along the plane's normal, the ring flat in the plane), or x, y (along the frame's X or Y, the ring on edge)
torus seat (enum) centre centre puts the ring's centre on the point; plane rests the torus on the plane, lifted along the normal so its lowest point touches it (tube / 2 with axis normal, diameter / 2 + tube / 2 with the axis in the plane), and offset still adds on top

The size sign rules ("greater than 0") are checked by the kernel when the value is known, not by the schema, since values are expressions.

6.7 remove

Takes bodies out of the model without touching the features that made them.

Input Kind Required Rule
bodies ref yes One or more refs, all of kind body (body IDs).

Rolling the timeline back past it, suppressing it or deleting it brings the bodies back.

6.8 fillet

Rounds edges of a body, with a constant radius per edge set (P3-01) or one that tapers along the set's chain (P4-10). A fillet has up to 32 edge sets (8 until P4-12): set 1 is edges + radius, set n is edges<n> + radius<n> (edges2, radius2, ..., edges32, radius32), and a set with an end radius also takes radiusEnd<n> + swap<n> (radiusEnd, radiusEnd2, ... and swap, swap2, ...). Every input is optional, so a file written with fewer sets reads unchanged.

Input Kind Rule
edges, edges2 ... edges32 ref Refs of kind edge (persistent edge names, section 8); a set with no edges is ignored
radius, radius2 ... radius32 expr Length; greater than 0 when the kernel evaluates it (not checked by the schema); a set with edges needs its radius
radiusEnd, radiusEnd2 ... radiusEnd32 expr Length, greater than 0; the radius at the chain's other end. A set with one is variable
swap, swap2 ... swap32 bool Puts the end radius at the other end of the chain (which end that is depends on the topology)
skipLostEdges bool With true, the fillet is built from the edges the kernel finds and warns how many it left out (they stay listed for Fix References) instead of failing; with none found it fails. Stored only as true; absent, one lost edge fails the fillet (2026-10-11)

The kernel rounds the whole chain of tangent-continuous edges around each edge you name, so edges of one chain must share their radii (two sets that reach one chain with different radii fail). A variable set's radius runs from radius to radiusEnd along its chain. Edges of different bodies are rounded body by body. The faces it makes are named fillet:<feature id>:from:(<edge name>). No new keys: a fillet is a feature with ref, expr and bool inputs like the others.

6.9 chamfer

Bevels edges of a body (P3-02). Like a fillet it has up to 32 edge sets (8 until P4-12), and each set has its own type and values. The names of set 1 are plain, set n appends its number: edges, mode, distance, distanceB, angle, flip, face, then edges2, mode2, distance2, distanceB2, angle2, flip2, face2, ..., up to edges32 ... face32. Every input is optional.

Input Kind Rule
edges, edges2 ... edges32 ref Refs of kind edge (persistent edge names, section 8); a set with no edges is ignored
mode, mode2 ... enum equal (default), two-distances or distance-angle
distance, distance2 ... expr Length, greater than 0 when the kernel evaluates it (not checked by the schema); needed by every type
distanceB, distanceB2 ... expr Length: the second distance of two-distances
angle, angle2 ... expr Angle, between 0 and 90 deg (exclusive) when evaluated: the angle of distance-angle
flip, flip2 ... bool Swaps which of the edge's two faces takes distance, for two-distances and distance-angle (default false)
face, face2 ... face32 ref One ref of kind face (a persistent face name, section 8): the face distance is measured on, for two-distances and distance-angle (P4-12). It must touch every edge of the set; while it is there, flip is ignored. equal sets ignore it
skipLostEdges bool As the fillet's: lost edges are left out with a warning instead of failing; a set none of whose edges is found is left out whole, its face too (2026-10-11)

equal puts the chamfer distance from the edge on both faces. two-distances puts distance on the set's first face and distanceB on the other; the first face is the one face names (P4-12), else the lower-numbered of the two faces around the edge in the kernel's face order (flip taking the other; the first edge of a chain of tangent edges decides for the chain). distance-angle puts distance on the first face, with the chamfer at angle to that face (45 deg is the equal chamfer). As in a fillet, the kernel bevels the whole chain of tangent-continuous edges around each edge you name, with one setting, so edges of one chain must share their set's type and values. Edges of different bodies are bevelled body by body. The faces it makes are named chamfer:<feature id>:from:(<edge name>). No new keys: a chamfer is a feature with ref, enum, expr and bool inputs like the others.

6.10 Construction features

Thirteen feature types (category construct) make no body: each makes a plane, an axis or a point that later features refer to (section 8: a reference of kind plane, axis or point whose id is the feature's ID). Every input is optional in the schema (a missing pick is an error the kernel reports), and every reference input takes at most the count shown. The nine original types are here; P4-12's four (pointOnPath, planeAlongPath, pointAtIntersection and midplaneAngled) and the tangentPlane point are in 6.31.

Type Makes Inputs
offsetPlane plane plane (ref, one of kind plane or face); distance (expr length, default 0): along the plane's normal (a face's outward one)
planeAtAngle plane axis (ref, one of kind axis, edge or sketchEntity: the line the plane turns about); plane (ref, one plane or face: where the angle counts from; without it 0 deg is the plane through the line whose normal is as vertical as possible); angle (expr angle, default 0, right-handed about the line)
midplane plane planes (ref, two of kind plane or face, parallel): the plane halfway between
planeThroughPoints plane points (ref, three of kind point or vertex, not on one line); the normal follows their order (right-handed)
tangentPlane plane face (ref, one face: cylindrical, conical or spherical); plane (ref, one plane or face: says where round the face it touches, by its normal); angle (expr angle, default 0: turns the touching point about the face's axis); point (ref, one point or vertex: touch the face nearest it — a torus, a cone or a free-form face, 6.31)
axisThroughPoints axis points (ref, two different points of kind point or vertex): from the first to the second
axisThroughCylinder axis face (ref, one face: cylindrical, conical, toroidal or of revolution): the face's own axis
axisAlongEdge axis edge (ref, one of kind edge or sketchEntity): a straight edge or sketch line, or a circular edge's axis through its centre
constructionPoint point at (ref, one of kind point, vertex, edge or face: a circular edge gives its centre, another edge its middle, a face its centre; without it the origin); x, y, z (expr length, default 0): moves it along the world axes

A plane's 2D frame is derived from the plane alone, by the rule of a sketch on a flat face (6.2), so a sketch or primitive on a construction plane follows it. The kernel computes and reports everything; nothing but the inputs is stored. A feature that uses a construction feature must come after it in the timeline, and deleting one that is used is refused (section 8).

6.11 combine

Joins, cuts or intersects a target body with tool bodies (P3-06).

Input Kind Required Rule
target ref yes At most one ref, of kind body (a body ID). Empty: the kernel reports "Pick the target body."
tools ref yes Refs of kind body. Empty: an error until some are picked
operation enum no join (default), cut or intersect
keepTools bool no Default false: the tool bodies are used up

The result keeps the target's body ID, name and colour; the tools leave the body set unless keepTools. join needs every tool to touch the target (or a tool that does); cut and intersect fail with a message when nothing would change or nothing would be left. A result of several separate solids becomes one body per solid (<feature id>:<n>). Faces keep the names of the target and of the tools' faces that end up in the result (section 8).

6.12 move

Moves or turns bodies, optionally as copies (P3-06). Every input but bodies is optional and defaults to "no move".

Input Kind Rule
bodies ref Refs of kind body. Empty: an error until some are picked
mode enum free (default), rotate or point-to-point
dx, dy, dz expr Length. free: the move along the world axes, after the turns
rx, ry, rz expr Angle. free: turns about the world X, Y and Z axes through the centre of the bodies' bounding box, in that order
axis ref At most one ref of kind axis, edge or sketchEntity. rotate: the axis to turn about
angle expr Angle. rotate: right-handed about the axis
from, to ref At most one ref each, of kind vertex or point. point-to-point: the bodies move by the vector from from to to
copy bool Default false. true: the bodies stay and moved copies are new bodies <feature id>:<n>, in the order of bodies

A move keeps the body IDs, so references to the moved bodies and to their faces still resolve. A copy's faces are named move:<feature id>:from:(<the original face's name>), so a reference means one body. Fields of the other modes are not stored.

6.13 mirror

Mirrors bodies, or features, about a plane (P3-06, features in P3-07).

Input Kind Required Rule
objects enum no bodies (default) or features: what is mirrored
bodies ref with bodies Refs of kind body. Empty or missing: an error until some are picked
features ref with features Refs of kind feature: the features whose tools are mirrored (6.16)
plane ref yes At most one ref, of kind plane (an origin or construction plane) or a flat face
copy bool no Bodies only. Default true: the originals stay and the mirrored copies are new bodies <feature id>:<n>. false: the bodies themselves are mirrored and keep their IDs
join bool no Bodies only; default false; only with copy. Fuses each copy into its original (which keeps its ID); a copy that doesn't touch it stays a body of its own

A copy's faces are named mirror:<feature id>:from:(<the original face's name>). With features, the tool of each listed feature is reflected in the plane and joined or cut like the feature did (6.16 says which features qualify); bodies, copy and join are ignored.

6.14 shell

Hollows bodies with walls of a given thickness (P3-03).

Input Kind Required Rule
faces ref no Refs of kind face (persistent face names, section 8): the faces to remove, the openings. May lie on several bodies
bodies ref no Refs of kind body (body IDs): bodies to hollow closed, with no opening. Bodies of the picked faces are shelled anyway
thickness expr yes Length, greater than 0 when the kernel evaluates it (not checked by the schema)
direction enum no inside (default) or outside
wallFaces, wallFaces2, wallFaces3, wallFaces4, wallFaces5, wallFaces6, wallFaces7, wallFaces8 ref no Refs of kind face: wall set n, faces of the shelled bodies whose walls get the set's own thickness (P4-12). A set with no faces does nothing
wallThickness, wallThickness2, wallThickness3, wallThickness4, wallThickness5, wallThickness6, wallThickness7, wallThickness8 expr (length) no Wall set n's thickness, greater than 0; needed once the set has faces

At least one face or body is needed (the kernel reports it otherwise). Each body with faces picked is shelled with those faces removed; a body without any becomes a closed solid with a sealed void. inside keeps the body's outer surface where it is and cuts the cavity into it; outside keeps the surface as the cavity and grows the walls outwards, so the part gets bigger. The outer skin keeps the faces' names in both directions; the faces the shell makes are named shell:<feature id>:inner:(<face name>) (the cavity), shell:<feature id>:rim:(<removed face name>) (around an opening) and shell:<feature id>:round:(<edge or vertex name>) (a rounded join). A removed face that runs smoothly into a neighbour (next to a fillet) is opened as a plug when it is flat, its other edges meet their neighbours square and it shares no edge with another removed face (P4-12), and refused otherwise. Wall sets (P4-12): a face of a wall set gets that set's thickness instead of thickness, and so do the faces that run smoothly into it (a fillet's round and the faces beyond it); a face in two sets, a removed face in a set and a face of a body the shell doesn't hollow are errors, and so are two sets that reach one smooth chain with different thicknesses. A shell with wall sets joins its walls sharp (no rounded joins), so outside its corners stay square; one without them computes as before. No new keys: a shell is a feature with ref, expr and enum inputs like the others, and a document without wall sets is unchanged.

6.15 placeOnBed

Turns the body a flat face belongs to so that face lies on the build plate (P3-10); with several faces, each body lies on its own face (P3-17). The rotation and the move are computed on every recompute, not stored.

Input Kind Required Rule
face ref yes Refs of kind face, flat faces, at most one per body (two faces of one body are an error). Empty: an error until one is picked. Before P3-17 at most one
spin expr (angle) no A turn about the vertical (+Z) through the face's centre, after the face lies on the bed. Absent: no turn
carry ref no Refs of kind body (P6-05 S5, ADR-0081 §3): bodies that take the same turn and drop as the face's body, so a component is placed as one. Only with exactly one face; a carried body that is also the face's body is an error. Empty: no carried bodies

Each body is the one its face is in. It turns by the smallest rotation that makes the face's outward normal point along -Z (about the horizontal axis normal x -Z through the face's centre; a face that faces up turns half a turn about X), then moves along Z so the face lies at z = 0, then turns by spin (counter-clockwise seen from above) about the vertical through the face's centre. The X and Y of the face's centre stay where they were. Every body keeps its ID and every face keeps its name, so references to the body and its faces still resolve. The feature warns when every face is already on the bed (and there is no spin), and when part of a body ends up below z = 0. Each carry body takes the face body's own rotation and move, keeps its ID and names, and is warned about on the same rule.

6.16 Patterns: rectangularPattern, circularPattern, pathPattern

Copies of bodies, or repeats of features, in a layout (P3-07, ADR-0047). The original counts as the first instance: a count of 3 makes two new ones. Three feature types share these inputs:

Input Kind Required Rule
objects enum no bodies (default) or features
bodies ref with bodies Refs of kind body, each once. Empty or missing: an error until some are picked
features ref with features Refs of kind feature ({"kind": "feature", "id": "<feature id>"}): the features to repeat, in the order they are applied. Each must come earlier in the timeline, be a solid feature that joins or cuts (extrude, revolve, a primitive, a hole, which always cuts) and not be suppressed; the pattern depends on it like on any feature it refers to
join bool no Bodies only; default false: the copies are new bodies <feature id>:<n>. true: they are fused into the original body, and a copy that doesn't touch it becomes a body of its own with a warning
skip labels no The instances left out, as their position labels ("2", "m1", "1x3"; P4-12). Missing or empty: every instance is made. The original ("0", "0x0") can't be listed (an error), and a label no instance has (the count went down) is ignored and kept, so the skip comes back if the count grows. Because a label names a position and not a face, nothing in it can go stale

Counts are expr inputs of unit unitless that must evaluate to a whole number from 1 up; a pattern makes at most 1000 instances. Distances are expr inputs of unit length, angles of unit angle.

With features, the tool the feature made (the solid it extruded, revolved or built) is copied to every instance, and one boolean joins it to, or cuts it from, the bodies it touches. Instances that overlap each other are fused first.

Names: every face of an instance is named pattern:<feature id>:<label>:from:(<the original face's name>), where the label is the instance's position in the layout (1, 2, m1 for -1, 1x2 for a grid position), so a reference to a face of one instance keeps resolving when the counts change. A copy's body ID is <feature id>:<n> with n derived from the same position, so it stays too.

rectangularPattern

Input Kind Required Rule
direction1 ref yes One ref of kind axis (origin or construction), sketchEntity (a sketch line) or edge (a straight edge). Missing: an error until picked
count1 expr no Unitless. Default 2
distance1 expr no Length. Default 20 mm
measure1 enum no spacing (default: the distance is between neighbours) or extent (from the first instance to the last)
symmetric1 bool no Default false. true: the original sits in the middle of the row (for an even count, one place before the middle)
direction2 ref no A second direction, as direction1, makes a grid; it must not be parallel to the first
count2, distance2, measure2, symmetric2 as count1… no The second direction's series (used only with direction2)

circularPattern

Input Kind Required Rule
axis ref yes One ref of kind axis, sketchEntity or edge, as a direction above
count expr no Unitless. Default 3
angle expr no Angle. Default 360 deg. Right-handed about the axis
measure enum no total (default: the angle is the whole spread; a whole turn or more is divided into count equal parts, less into count - 1) or step (the angle between neighbours)
symmetric bool no Default false. The original in the middle of the series

pathPattern

Input Kind Required Rule
path ref yes Refs of kind sketchEntity (<sketch>/<curve>) and edge, chained end to end (the kernel reorders and reverses pieces as they meet); the first is walked in its own direction
count expr no Unitless. Default 3
distance expr no Length. Default 20 mm
measure enum no spacing (default) or extent, as above
aligned bool no Default false: instances keep the original's orientation. true: each turns with the path's direction, about the path's start
flip bool no Default false. true: walk the path from its other end

The first instance is taken to sit at the start of the path and the others move by the way the path went from there. A path shorter than the pattern needs is an error.

Skipping instances (P4-12)

skip leaves single instances out of any of the three types, before the boolean: the named placements are dropped, and the dialog draws each one as a faint ghost of what it would have been. A pattern whose every instance is skipped makes nothing new and says so as a warning. The other instances are untouched: their body IDs, their face names and their geometry are exactly what they would have been with the skip off, because a label names a position.

6.17 hole

Drills holes into the bodies below a plane or a flat face (P3-04, ADR-0049). It makes no body of its own: it always cuts, like a cut operation, and a pattern or mirror can repeat it as a feature (6.16). Every input is optional; a minimal hole is {}: a 5 mm blind hole, 10 mm deep, in the XY plane at the origin.

Input Kind Required Rule
plane ref no At most one ref, of kind plane (an origin or construction plane) or face (a flat face). Where the holes start. Missing or empty: the XY plane
points ref no Refs of kind sketchEntity naming sketch points (<sketch feature id>/<point id>, section 8): one hole at each, the point dropped along the plane's normal onto the plane, so a sketch on the face or on a parallel plane both work. Empty or missing: one hole at x, y
x, y expr no Length, default 0. The one hole's place in the plane's sketch frame, the frame a sketch on that plane gets (for a face: the world origin projected onto it, X along world X on faces within 40 degrees of horizontal, else Y up the face, 6.2). Not used with points
type enum no simple (default), counterbore (a wider flat-bottomed step at the top) or countersink (a cone at the top)
extent enum no blind (default) or through (runs past every body along its way)
diameter expr no Length, default 5 mm; greater than 0
depth expr no Length, default 10 mm. Blind only: from the plane to the end of the full diameter
tipAngle expr no Angle, default 118 deg. Blind only: the drill point's full angle, a cone beyond depth; 0 deg makes a flat bottom; must be under 180 deg
cbDiameter, cbDepth expr no Length, defaults 10 mm and 4 mm. Counterbore only: the step's diameter (larger than diameter) and its depth from the plane (less than depth when blind)
csDiameter, csAngle expr no Length default 10 mm, angle default 90 deg. Countersink only: the cone's diameter at the plane (larger than diameter) and its full opening angle (between 0 and 180 deg)
flip bool no Default false. The holes go against the plane's normal: into a face (whose normal points out of the body), down from an origin plane. true reverses that

Holes are solids of revolution about their axis, cut from every body they touch. The kernel warns when some of several holes cut nothing and reports an error when none does (no body there, or the wrong flip), when a size doesn't fit (a counterbore wider than the body's hole, a countersink or counterbore deeper than a blind hole) and when a sketch point is gone. At most 200 holes per feature; two points in one place make one hole.

Names: the faces a hole makes are hole:<feature id>:side:<part>, where the part is wall (the cylinder), tip (the drill point's cone) or floor (a flat bottom), cbwall and cbfloor (the counterbore's wall and floor) or cone (the countersink). With points, each part is prefixed with the point's ID (<point id>.wall), so a face keeps its name when other points are added or removed. The hole dialog's presets (M2 to M8 clearance, heat-set inserts) only fill these inputs in the app; nothing about a preset is stored. In a document with a print-tolerance parameter (a user parameter named tolerance, P4-08, ADR-0062) a preset writes each diameter as <nominal> mm + 2 * tolerance, which is an ordinary expression like any other.

6.18 offsetFace

Moves faces of bodies along their normals by a distance (P3-08, ADR-0051); the faces next to them are extended or trimmed to follow. No new keys: a feature with ref, expr and bool inputs like the others.

Input Kind Required Rule
faces ref yes Refs of kind face (persistent face names, section 8): the faces to move. May lie on several bodies, each of which is offset on its own. Empty: an error until one is picked
distance expr yes Length. Positive moves a face along its outward normal: the body grows there (a pad grows, a hole's wall closes in). Negative moves it in. 0 is an error when the kernel evaluates it (not checked by the schema)
keepRounds bool no true: a fillet's round (a face a fillet made, or a pattern's or mirror's copy of one, on a cylinder or torus) next to a moved face that isn't listed keeps its radius: it is made again between the moved face and its other neighbour, which stays (ADR-0051's amendments, 2026-10-14). Absent or false: such rounds move with the face like any smooth neighbour and their radius changes by the distance, as before the flag existed. The app writes true for a new offset

Faces that run smoothly into a picked face (their normals at the shared edge within 4 degrees: the fillets round a pad) move with it by the same distance, whether or not they are listed, except the rounds keepRounds keeps; the app's dialog lists them (with keepRounds, a face's chain up to its rounds). A planar face moves like a pad growing or sinking, a cylinder's wall changes its radius, a cone keeps its angle. Every face keeps its name, so later features that refer to a moved face keep finding it, and the distance can be edited freely; a face the offset swallows is gone, and a face OCCT splits gets #n. A solid with a sealed void inside (a body shelled closed), a body whose rounded edges meet at a sharp corner (two fillets with no blend between them, which OCCT's offset can't do safely), a distance that makes the body vanish or cross itself, and faces OCCT can't offset are reported as errors, with the largest distance that works where one does. Press Pull is not a feature: it opens an Offset Face, a Fillet or an Extrude in the app.

6.19 splitBody

Cuts bodies in two along a plane (P3-08, ADR-0053). No new keys.

Input Kind Required Rule
bodies ref yes Refs of kind body (body IDs): the bodies to cut. Empty: an error until some are picked
plane ref yes One ref of kind plane (an origin or construction plane) or face (a flat face, taken as its whole plane, past its edges). Empty: an error until one is picked
keep enum no both (default), above (the side the plane's normal points to: +Z for the XY plane, outside the body for a face) or below

Each side becomes a body of its own, and a side that falls apart into several solids becomes several bodies. The largest piece keeps the body's ID (and so its name and colour); the others get the feature's IDs <feature>:<n> (ADR-0030). A face the plane cuts in two keeps its name with #1 and #2 (one piece in each body, so names stay unique); the new faces on the plane are split:<feature>:cut:above and split:<feature>:cut:below. A body the plane doesn't cut stays whole with a warning (an error if none is cut), and keeping a side that has nothing of a body in it is an error.

6.20 scale

Makes bodies larger or smaller about a point (P3-08, ADR-0053). No new keys.

Input Kind Required Rule
bodies ref yes Refs of kind body: the bodies to scale. Empty: an error until some are picked
point ref no At most one ref of kind vertex or point (a construction point): the point that stays where it is. Absent or empty: the centre of the box that holds the bodies
mode enum no uniform (default) or non-uniform
factor expr no uniform: plain number (unitless), default 1
x, y, z expr no non-uniform: plain numbers, the factors along the world X, Y and Z axes, default 1 each
copy bool no Keep the bodies and add scaled copies (<feature>:<n>). Default false

Every factor must be greater than 0 (an error otherwise; a mirror is mirror); all factors 1 is a warning. Faces keep their names (a copy's faces are scale:<feature>:from:(<name>), as for move). A uniform scale keeps every surface's type; a non-uniform one turns curved faces into B-spline surfaces (a cylinder scaled across its axis has an elliptic section), while flat faces stay planes and the straight edges between them lines.

6.21 draft

Tilts faces by an angle about a neutral plane (P3-08, ADR-0053). No new keys.

Input Kind Required Rule
faces ref yes Refs of kind face: the faces to tilt, on one or several bodies. Empty: an error until one is picked
plane ref yes One ref of kind plane or face (a flat face): the neutral plane. The faces turn about the line where each meets it; its normal is the pull direction
angle expr yes Angle. Positive narrows the body along the pull (matter goes on the pull side of the plane and comes on the other); negative widens it. 0, and 90° or more, are errors when the kernel evaluates it
flip bool no Pull against the plane's normal. Default false

Only flat, cylindrical and conical faces tilt (a cylinder becomes a cone); faces that run smoothly into a picked face tilt with it. Every face keeps its name. A face parallel to the neutral plane, a face of another kind, faces whose rounded or chamfered neighbours can't follow, and an angle that makes faces cross are reported as errors, with the largest angle that works where one does.

6.22 sweep

Moves sketch profiles or flat faces along a path (P4-01, ADR-0055), then makes new bodies or joins, cuts or intersects (section 6.3). No new keys. A useful sweep has profiles and path.

Input Kind Rule Default and meaning
profiles ref Refs of kind profile or face (flat), all in one plane; a profile may have holes none: fails until picked
path ref Refs of kind sketchEntity (<sketch>/<curve>: a line, arc, circle, ellipse or spline, construction ones too) or edge, in any order and direction, that join end to end (within 1 µm) into one chain without branches none: fails until picked
orientation enum follow, fixed follow: the profile keeps its angle to the path. fixed: it doesn't turn, staying parallel to where it starts
twist expr angle follow only, along a path without sharp corners 0. The profile turns about the path by this much from start to end, evenly by length
scale expr unitless greater than 0; not on a closed path 1. The profile's size at the end as a factor of its size at the start, changing evenly along the path
operation enum section 6.3 new-body
bodies ref body refs section 6.3

The profile stays where it is: it need not touch the path, and travels with the path's frame from the path's end nearer to the profile's centre (the chain is walked the other way when its far end is nearer). Sharp corners of the path are mitred. Faces are named sweep:<feature>:cap:start (the profile's own place), sweep:<feature>:cap:end and sweep:<feature>:side:<source> per profile edge (a sketch curve's ID, or (<edge name>) for a body's face), as for extrude, numbered #1, #2 … along a path of several pieces (a face per piece). A sweep that would run into itself (a profile too large for a bend, a path coming back near itself) is an error.

6.23 loft

A solid through sections in order (P4-01, ADR-0055), then new bodies or a join, cut or intersection (section 6.3). No new keys.

Input Kind Rule Default and meaning
sections ref In loft order, at least two (three when closed): refs of kind profile or face (flat, one outline without holes), or as the first or last section a point: point (a construction point), vertex or sketchEntity (<sketch>/<point>) none: fails until picked
ruled bool false: smooth through all sections. true: straight (ruled) between neighbours
closed bool no points false. true joins the last section back to the first: a ring with no end faces
operation enum section 6.3 new-body
bodies ref body refs section 6.3

Sections may have different numbers of edges (a square to a circle); the kernel lines their starts up so the loft doesn't twist. Neighbouring sections in one plane, a section with a hole, a point in the middle and a loft that runs into itself are errors. Faces are named loft:<feature>:cap:start (the first section), loft:<feature>:cap:end (the last) and loft:<feature>:side:<source> after the edge of the earliest section that bounds the face. Rails and a centre line are not part of the format yet.

6.24 coil

A spring (P4-01, ADR-0055): a section swept along a helix, placed like a primitive (section 6.6), then new bodies or a join, cut or intersection. No new keys. Every input is optional; "inputs": {} is 5 turns, 20 mm high, of a 2 mm round wire on a 20 mm diameter, standing on the XY plane at the origin.

Input Kind Rule Default and meaning
plane ref At most one ref of kind plane or face The XY plane. The coil's axis is the plane's normal through (x, y)
x, y expr length 0. The axis's place in the plane's frame
offset expr length 0. Lifts the start off the plane
type enum revolutions-height, revolutions-pitch, height-pitch revolutions-height: which two of revolutions, height and pitch set the length; the third follows, and its input is ignored
diameter expr length greater than 0 20 mm. The helix's diameter at the start, measured through the section's centre when position is on
revolutions expr unitless greater than 0, at most 1000 turns in all 5. Fractions allowed
height expr length greater than 0 20 mm. Along the axis from start to end
pitch expr length greater than 0 and than the section's height along the axis 4 mm. Rise per turn
taper expr angle between -89° and 89° 0. Half-angle of the cone the helix winds on; positive widens with height
direction enum counter-clockwise, clockwise counter-clockwise seen from above (along the normal): a right-hand spring
section enum circle, square, triangle-out, triangle-in circle. A triangle is equilateral, pointing away from the axis (triangle-out) or towards it (triangle-in)
size expr length greater than 0 2 mm. The circle's diameter, the square's side, the triangle's side along the axis
position enum inside, on, outside on: the section is centred on the diameter; inside and outside put its outer or inner side on it
operation enum section 6.3 new-body
bodies ref body refs section 6.3

The helix starts on the plane frame's X side of the axis, and the section is centred on that start height (half of it lies below the start). A section that would reach the axis, or turns that would touch, are errors. Faces are named coil:<feature>:cap:start, coil:<feature>:cap:end and coil:<feature>:side:<role>: surface (circle), inner, outer, top, bottom (square), and for triangles the base (inner or outer) and the top and bottom sides; each has a face per turn, numbered #1, #2 … up the coil.

6.25 thread

A modeled screw thread cut into round faces (P4-02, ADR-0056): real geometry that prints, external on a shaft's face, internal on a hole's wall (the kernel tells which from the face). Sections 6.22 to 6.24 are P4-01's (sweep, loft, coil). It makes no body of its own: it always cuts, and a pattern or mirror can repeat it as a feature (6.16). No new keys.

Input Kind Required Rule
faces ref yes 1 to 16 refs of kind face: whole cylindrical faces (all the way round), one thread on each. A flat or curved face of another kind, or part of a cylinder, is an error
diameter expr no Length: the nominal (major) diameter of the ISO 68-1 basic profile (60°, which the Unified inch threads share)
pitch expr no Length: crest to crest along the axis. With neither diameter nor pitch the kernel picks the thread that fits each face (M2 to M64 for iso, the print sizes for print45: on a shaft the largest whose diameter isn't more than 0.1 mm over the shaft's; in a hole the largest whose minor diameter is at most the hole's + 0.1 mm and whose diameter is larger, so a tap-drill hole finds its thread; and a hole drawn at a size's own diameter — within 0.01 mm of it — is that size). With one of them, the other takes its default (6 mm, 1 mm)
extent enum no full (default: from offset to the face's far end) or length
length expr no Length, default 10 mm; with extent: length. At least one pitch
offset expr no Length, default 0: from the face's end to where the thread starts
flip bool no Default false: offset and length run from the face's lower end along its axis (the axis taken with its first non-zero component positive: a vertical shaft's bottom end); true from the other end
hand enum no right (default) or left
profile enum no iso (default: ISO 68-1, 60°), trapezoidal (ISO 2901 / DIN 103 Tr), buttress (DIN 513 S), bottle (the PCO-1881 finish, a rounded trapezoid), print45 (made for printing: 45° flanks, flat crest and root) or whitworth (55°, BS 84: the form of the BSP G pipe threads)
loadFlank enum no Buttress only: start or end (default), the end the steep 3° load flank faces
starts expr no Unitless, 1 (default, never stored) to 8: helices round the face, lead = starts × pitch (6.33)
tolerance expr no Length, default 0.1 mm, not negative: the print clearance. The whole profile moves this far radially into the part's material, so an external thread's diameters shrink by twice it and an internal one's grow by twice it
chamfer bool no Default true: a 45° lead-in where the thread runs out of an open end of the face (a shaft's end, a hole's mouth; not a shoulder or a hole's floor)

The profile is the tooth's shape, from the table threadProfile in core (iso, the default, is what older files get). The ISO 68-1 basic profile puts a crest flat P/8 wide at the major diameter and a root flat P/4 wide at the minor (D − 1.0825 P), in a hole the reverse; trapezoidal is a 30° trapezoid 0.5 P deep with equal 0.366 P flats; buttress is a 3° load flank and a 30° trailing flank at a 0.75 P load-bearing depth; bottle is a rounded 20° trapezoid 0.45 P deep with arcs on its crest and root; print45 is the printing profile: 45° flanks, a flat crest and root each 0.2 P, 0.3 P deep, so the tooth tiles one pitch and the flats are the same inside and out — a screw and a nut are exact complements, and it mates only with itself; whitworth is BS 84's 55° triangle cut by a sixth of its height at the crest and the root, 0.640 P deep with flats P/6 wide, the same inside and out (the standard rounds crest and root; the flats stand in for the arcs). All are moved by tolerance. A shaft thicker than the thread is turned down to it (a warning when much thicker); a hole wider than the thread's minor diameter (as a bore drawn at a size's own diameter is, one at or past the thread's root included) is filled in to it along the thread before the cut, and a shaft thinner than its major is built up to it, so the tooth is whole (a warning notes it when the diameter was off by more than the thread's depth; a hole Remove Faces can't close is cut as drawn, with a warning that only the outer part of the tooth is cut, unless the hole is at or past the root, where nothing would be cut: an error); a shaft at or under the thread's root, a thread longer than the face, an offset as long as the face and more than 150 turns are errors. With profile: iso or print45 and no size the kernel picks the thread that fits (autoThread): the ISO coarse one, or a print size; another profile with no size is refused ("Enter a diameter and pitch"). A shaft's thread and a hole's that start at the same plane mesh (the hole's tooth sits half a pitch on). Names: thread:<feature id>:side:f<k>.<part>, where k is the face's place in faces (0, 1 …) and the part is crest, flank0, flank1 (one face per turn, #n along the helix), root, end0 / end1 (the flat steps where a thread stops inside a face), lead0 / lead1 (the lead-in cones) or, where a face was filled in or built up, fillEnd0 / fillEnd1 (the fill's flat ends, where a thread stops inside the face) and fill / fillWall (its cylinders, which the cut and the join take away); a rounded crest or root is still one crest/root face. The dialog's sizes (ISO metric coarse and fine, UNC, UNF, the Tr series, the print sizes and PCO-1881) only fill diameter, pitch and profile; nothing about a preset is stored. For a new thread the dialog writes the document's print-tolerance parameter (tolerance, P4-08, ADR-0062) here when it has one, which is an ordinary expression like any other.

6.26 emboss

Puts sketch profiles or text onto a face of a body and joins them on (emboss) or cuts them in (deboss) (P4-04, ADR-0060): the same thing as sketching on the face and extruding out or in, done in one step from a sketch anywhere in a parallel plane. It makes no body of its own: the body that owns the picked faces is the only body it touches, and a pattern or mirror can repeat it as a feature (6.16). The one key added since P4-04 is tangent: an older Extrudo ignores it with its unknown-input warning and computes the emboss without folding the profiles, so it may refuse the sketch. Since P4-12 face may hold several faces; an older Extrudo, whose schema allowed one, marks such an emboss "Invalid inputs".

Input Kind Required Rule
profiles ref yes Refs of kind profile (<sketch>/<region>) and sketchEntity (a whole text, <sketch>/<text>: every ink region of it, so editing the string keeps the feature). All in one plane, parallel to the face's. Missing or empty: an error until some are picked
face ref yes Refs of kind face, all of one body: the faces to emboss on (a flat face; a cylinder or a cone needs the sketch parallel to its axis; any other face takes the profiles projected along the sketch's normal, P4-12). One face works as before, unclipped; with several (P4-12, ADR-0060 B3) each face takes the part of the letters that lands on it, clipped to the face. Missing: an error until picked
depth expr no Length, greater than 0; default 1 mm. How far the letters stand out (emboss) or go in (deboss)
mode enum no emboss (default: joins material outwards) or deboss (cuts inwards)
tangent bool no Default false. Lay the profiles on the face first, as if sketched on its tangent plane straight in front of them: any sketch angle, the letters read the right way round from outside (P4-12, ADR-0060 B2)

The profiles are moved onto the face's plane (a translation along the face's outward normal) and swept depth along it (emboss) or against it (deboss), then joined to or cut from the face's body. So a sketch below the face or above it, at any offset, works the same; the profiles must lie in a parallel plane, or the feature says so. Profiles that miss the face entirely, a depth of 0 or less and a sketch that isn't parallel to a flat face are errors. Since P4-12 (ADR-0060's amendment) the kernel also wraps the profiles round a cone like a cylinder, and projects them onto any other face (a sphere, a torus, a free-form face) along the sketch's normal, refusing profiles that reach past the face's edge or outline as seen from the sketch; a wrap may run up to a whole turn. With tangent the profiles are first laid on the face as if sketched on its tangent plane straight in front of them (the line through their area centroid along the sketch's normal, the nearest hit, then a fold onto the face's outward normal there), and the face's method runs on the laid profiles. The method is chosen from the face, not stored.

With several faces (ADR-0060's second amendment B3) each face takes the part of the letters that lands on it by its own method, clipped to that face, and the pieces fuse into one tool. When any face takes a projection, every face that isn't a flat face parallel to the profiles is projected too (a flat face that isn't parallel, refused alone, is projected in a set). A face no letter reaches gives the warning "No letters land on face k."; when none is reached the feature fails. Faces of two bodies are an error.

Names: the prism's own names under emboss:<feature id> — …:cap:start (on the face's plane) and …:cap:end, and …:side:<source> for each sketch curve the profile is bounded by, #n where names repeat — like an extrude's. With several faces, the walls where the letters stop at a picked face's edge are …:clip:<k>, k the face's place in the face list (from 1), and names split across the faces' pieces take #n.

6.27 rib

A thin wall (a gusset, a web) that fills the space between one sketch line and the bodies beside it (P4-10, ADR-0064 §1): in an L-bracket a diagonal on the bracket's middle plane becomes a stiffening triangle that meets both legs. It makes no body of its own: the piece is joined to the bodies it reaches, and a pattern or mirror can repeat it as a feature (6.16). Only straight lines, in any sketch plane; no new keys.

Input Kind Required Rule
curve ref yes One ref of kind sketchEntity naming a sketch line (<sketch>/<line>; construction lines too). Missing: an error until one is picked
thickness expr no Length, greater than 0; default 2 mm. How thick the wall is
side enum no both (default: centred on the sketch plane), one (from it along its normal) or other (against it)
flip bool no Default false: grow to the other side of the line

The line is extended by the bodies' box diagonal at both ends and swept that far to one side of it — the side the material is on, read from where the bodies' mass is, which flip reverses — and prisms that along the sketch plane's normal by the thickness. Every body is then cut out of the slab, and the piece that holds the line's midpoint (moved a hair into the material side, at mid-thickness) is the rib; it is joined to the bodies it touches. The material stops where it meets the body, so the line's ends should reach it: a line that lies inside a body says so, and a piece that would run past the body instead of closing on it is an error, as is a thickness of 0 or less.

Names: the prism's own names under rib:<feature id> — …:cap:start and …:cap:end (the wall's two faces across the sketch plane), and …:side:<sketch line> for the face the wall stands on, …:side:(<sketch line>:end0) and …:side:(<sketch line>:end1) for the extension's ends, #n where names repeat — like an extrude's.

6.28 import

A file of the design as a body (P4-06, ADR-0066 §2 and §3): a STEP file is read as solid bodies, and each solid becomes one body of the design (the largest keeps the feature's first body ID <feature>:0, the others <feature>:1, <feature>:2…, in creation order as everywhere). A mesh file (STL, 3MF, OBJ) is read as mesh bodies: one per object of the file, split into its connected pieces, numbered the same way. A mesh that isn't closed, or has more than 1,000,000 triangles, is an error (the message names the file).

Input Kind Required Rule
file file yes The attachment ID of the file (section 4.5). Its media type must be model/step, model/stl, model/3mf, model/obj or application/x-openscad.
units enum no What unit the file's numbers are in: auto (default; a 3MF's own unit, STL, OBJ and OpenSCAD as millimetres), mm, cm, m or in. Meshes and OpenSCAD files only — a STEP file converts its own units, so the value has no effect there.
up enum no The file's up axis: z (default) or y. y turns the file +90° about X, so a Y-up file stands up in a Z-up design.
position enum no Where the bodies land, after the up turn: file (default: the file's coordinates) or centre (all of the file's bodies moved together, so the box around them has its centre over the origin and its bottom on the XY plane; ADR-0066's amendment of 2026-11-04). The app's Import dialog stores centre unless the user picks the file's coordinates.
scadName, scadName2 ... scadName32 enum no OpenSCAD files only (P5-04, ADR-0071 §5): override n's variable, the name of a top-level variable of the file (^\$?[A-Za-z_][A-Za-z0-9_]*$, so $fn too). The value is free text, not one of a list.
scadValue, scadValue2 ... scadValue32 expr no OpenSCAD files only: override n's value, an expression of any unit (unit says which: a length reaches OpenSCAD in millimetres, an angle in degrees, a plain number as it is). unit is required here, unlike every other expr input (where a missing one means a length, section 6.1): a reader refuses a scadValue<n> without one, since a plain 24 read as a length in an inch document would reach OpenSCAD as 609.6. A writer stores unitless for a plain value and the unit of the expression otherwise (the app's dialog stores what the expression evaluates to; the API a parameter's own unit).

Apart from position there are no placement inputs: Move or Place on Bed puts the bodies elsewhere. An import is not patternable, but its bodies are, through Pattern › Bodies.

OpenSCAD files (P5-04, ADR-0071): the file is compiled by OpenSCAD (its Manifold backend) with every override as a -D name=value definition, and the mesh it makes is read like a mesh file's. A pair with only one of its two inputs, or the same variable twice, is an error; a variable the file never assigns is a warning. The overrides are numbered like a fillet's sets (section 6.8): scadName + scadValue is the first, scadName<n> + scadValue<n> the nth, and an absent pair is skipped. OpenSCAD's own errors (a syntax error, a failed assert, a 2D or empty result, a file it includes that the design lacks) are the feature's error, its echoes and warnings the feature's warnings.

Names: a STEP file's face n (1-based, in the order the file's faces are listed before the bodies are split) is import:<feature id>:face:<n>, with its edges and vertices derived from those faces. A mesh body has the one face of all its triangles, named mesh:<feature id> (mesh:<feature id>#2, #3… for the bodies after the first). The file never changes, so the order is stable and a recompute names the same face the same way. Nothing here is built from other geometry, so there is no history.

6.29 canvas

A reference picture on a plane (P4-06, ADR-0066 §5): it makes no geometry at all — not a face, not a body — so a reader of this file computes nothing from it. It is drawn by the view, as one quad on the frame of its plane, and it is never picked: clicks pass through to the model or to whatever is picking planes. Its image bytes are read on the UI thread (createImageBitmap from the attachment's bytes, so no URL is loaded); they never reach the geometry kernel.

Input Kind Required Rule
plane ref no The plane the picture lies on: a plane reference (an origin plane, or a construction feature's ID) or a flat face. Absent: the XY plane.
image file yes The attachment ID of the picture (section 4.5). Its media type must be image/*: image/png, image/jpeg or image/webp.
x, y expr (length) no The picture's centre in the plane's own sketch frame, default 0.
width expr (length) no How wide the picture is; its height follows the picture's aspect. Default 100 mm; the app writes the picked picture's own pixel width × 0.1 mm (100 dpi) when the feature is made.
rotation expr (angle) no Turns the picture about the plane's normal, right-handed, from the frame's X. Default 0°.
opacity expr (unitless) no How strongly the picture is drawn, 0.05 to 1 (outside that the feature is an error). Default 0.5.
flip bool no Mirrors the picture left–right. Default false.

Every number is an expression, as everywhere: x, y, width and opacity may be parameters of the design, and changing one brings the picture with it (only the plane comes from the kernel, through a report of its own).

Calibration is not stored: the dialog writes a new width when the user marks two points of a known real distance on the picture (width × real / measured, to 0.01 mm, as a plain value).

6.30 script

Code that adds features (P5-02, ADR-0070, FR-PRG-02). The program runs in a sandbox (QuickJS compiled to WebAssembly, in the kernel worker or in Node) against the document as it is before the script — the features before it in the timeline and every parameter — and builds features through the document API (@extrudo/api, ADR-0068): design.extrude(…), design.sketch(…). It may only add features; removing, moving, renaming or suppressing one, adding or changing a parameter, and adding another script are refused.

Input Kind Required Rule
code code yes The program: TypeScript or JavaScript, at most 100,000 characters.
language enum no ts (the types are stripped before it runs, and nothing is type-checked) or js. Default ts.

The features it adds are not stored. A reader that computes the design runs the program on every recompute and evaluates what it made right after the script, in order, as if those features stood in the timeline there; the code is the source, so they can't go stale. The same program over the same document and parameter values makes the same features: their IDs are the script's own ID, a . and the API's counter (<script>.f1, <script>.f2…; sketch entities, constraints and dimensions inside them are numbered by the same counter without the prefix), and the counter does not depend on anything else in the document. Their names are the script's, ›, and the type's label counted within the script ("Script1 › Extrude1").

References into a script's geometry are ordinary references: a later feature stores extrude:<script>.f1:cap:end for a face, <script>.f1:0 for a body, <script>.f2/<region> for a profile of a sketch the script made. Such a reference is a dependency on the script itself (the script's ID is the part before the last .), so the timeline refuses to move that feature before the script, and the script can't be deleted while it is used.

What the program may read and do is the sandbox's (ADR-0070 §2): design (add only), params (every parameter's value by name, in mm, degrees or plain units, frozen), console.log, a Math.random seeded from the script's ID and a Date frozen at 0; two seconds, 64 MB and 1,000 features per run. A program that fails, or exceeds a limit, makes nothing: the feature is in error, with the line of the source when there is one, and the bodies before it are unchanged.

6.31 pointOnPath, planeAlongPath, pointAtIntersection, midplaneAngled

More construction geometry (P4-12, ADR-0040's amendment). Like the nine in 6.10, each makes a plane or a point that later features refer to by its own ID; they make no body and are computed in the kernel from what the references name.

pointOnPath and planeAlongPath place a point, or a plane square to the path, at a place along a path of sketch curves and edges (chained end to end like a pathPattern's, 6.16). The plane's frame follows a sketch-on-face one, so a sketch drawn on it (a sweep's section) lies in it.

Type Makes Inputs
pointOnPath point path (ref, any number of kind sketchEntity or edge, chained end to end); by (enum, position (default) or length: how the place is measured); position (expr unitless, default 0.5: a fraction of the path); distance (expr length, only with by = length: a length from the path's start); flip (bool, default false: measure from the other end)
planeAlongPath plane the same path, by, position, distance and flip; the plane is square to the path's tangent at that place

pointAtIntersection takes entities (ref, up to three of kind edge, plane or face) and reads what they are: two edges, an edge and a plane, flat face or curved face, or three planes or flat faces. Two edges meet within 1 µm (their closest points through the kernel); an edge crosses the plane of a plane or flat face; an edge and a curved face meet where their closest points are within 1 µm (the midpoint of the two), and an edge that crosses the face twice gives whichever crossing the kernel reports first; three planes are solved for their one common point. Any other mix, or references that don't meet, is an error.

midplaneAngled takes planes (ref, two of kind plane or face) and flip (bool, default false). The two planes must not be parallel (that is what midplane is for); the result is the plane through their intersection line that bisects them, flip taking the other bisector.

tangentPlane's point (6.10) is where a tangent plane touches a face surfaceGeometry can't place analytically: a torus (the tube's nearest point), a cone (the foot of the point on the nearest generatrix, the apex for a point past it; a point on the axis has no nearest generatrix, so the angle rule decides with a warning; like a cylinder's, the surface is the infinite one, so a point beyond the rim touches past the face) or a free-form face (the nearest triangle of a fine mesh of the face, 0.01 mm deflection, whose outward normal the plane takes), the plane square to the surface there.

6.32 plugin

A plugin's custom feature (P6-03, ADR-0077). A plugin is a .extrudo-plugin file — a zip of plugin.json (its manifest: ID, name, version, the commands and custom features it offers and each feature's inputs), its module (main.ts or main.js) and optionally README.md and LICENSE — and a design that uses one of its features carries the file as an attachment of media type application/x-extrudo-plugin (section 4.5; its record's name is the plugin's name and version, "Name plate 1.0.0", its fileName <plugin id>.extrudo-plugin), so the design opens where the plugin isn't installed. Like a script (6.30) it makes features: the reader runs the module's handler for this feature in the script sandbox against the document as it is before the feature, and evaluates what it added right after it.

Input Kind Required Rule
plugin file yes The plugin file: an attachment of this design whose media type is application/x-extrudo-plugin.
handler enum yes Which of the plugin's custom features this is: a type its manifest lists under features (lower case letters, digits and dashes, name-plate). Its values come from the manifest, so the schema checks only the form.
in:<name> expr, bool, enum or ref per manifest The plugin's own inputs, one per input of the manifest's feature, under its name (an identifier) prefixed in: (in:width), in the stored form of the manifest's kind. An expr carries the manifest's unit (length; angle; none is stored as unitless), so parameters and dimensions drive it as they drive an extrude; a ref is a reference with its fingerprint (section 8) of a kind the manifest's accepts lists, one unless the input is multiple; an enum value is one of its options. An input the feature lacks takes the manifest's default.

A key that neither is plugin or handler nor starts with in: is an unknown input (the recompute leaves it out with a warning, section 6), and an in: key of any other stored kind (file, labels, code, sketchData) is that feature's error, "in:x has a kind this plugin can't take"; the document still opens. What the manifest says is checked when the feature is computed, not when the file is read: a handler the manifest doesn't list, an input of the wrong kind or unit, a missing required reference or an input the manifest lacks makes the feature an error that names it, and so does a plugin file that isn't in the design or can't be read.

The features it adds are not stored, exactly as a script's (6.30): their IDs are the feature's own ID, a . and the API's counter (<feature>.f1…), their names the feature's name, › and the type's label counted within the run ("Name plate1 › Extrude1"), and a reference into them is a dependency on the plugin feature. The handler gets the sandbox a script gets (add only, the same limits) plus its inputs as plain values (an expr as its number in mm, degrees or plain units; a ref as { kind, id, fingerprint? } with a face, edge or vertex resolved to the name it has before this feature; a multiple one as a list).

6.33 thread's starts

A multi-start thread (P4-12, ADR-0056's second amendment): starts helices round the face, a lead of starts × pitch, the way a soda-bottle finish or a fast lead screw is cut. One new optional input of thread (6.25); no other key changes.

Input Kind Required Rule
starts expr no Unitless, a whole number from 1 to 8 (default 1; the kernel refuses anything else). Stored only when it isn't 1, so a single-start thread's file is what it was. The tooth profile keeps pitch (crest to crest along the axis); the lead is starts × pitch, so starts: 2 at M20 × 2.5 advances 5 mm a turn. The 150-turn limit counts the turns of one helix

With more than one start each start's tooth faces carry s<j>. in their role: thread:<id>:side:f0.s1.crest (the lead-in and end faces are unchanged; with one start the names are exactly as before).

6.34 removeFaces

Takes faces out of a solid and extends or trims the faces around them until they meet (ADR-0099, defeaturing), so a hole closes up and a round becomes a sharp edge again; it works on imported bodies too. No new keys: a feature with one ref input.

Input Kind Required Rule
faces ref yes Refs of kind face (persistent face names, section 8): the faces to remove, at least one. May lie on several bodies, each of which is changed on its own. A round or a hole needs all its faces

All or nothing: when the gap one picked face leaves can't be closed, the feature fails and changes no body; the message says how many faces of the round or hole to add. A pick of every face of a body is an error (use remove, 6.7). The removed faces' names are gone; a face that was extended or trimmed keeps its name, so later features that refer to it keep finding it. The app's pick takes a hole's or a round's faces together; the feature stores the faces it got.

6.35 meshToSolid

Turns an imported mesh body into a B-rep solid with real faces (P4-13, ADR-0097). No new keys.

Input Kind Required Rule
body ref yes One ref of kind body: the mesh body to convert. Empty: an error until one is picked. A body that is already a solid is refused
method enum no prismatic (default) recognises planes, cylinders, cones, spheres and tori within tolerance and rebuilds analytic faces (exact where the whole mesh fits, otherwise a hybrid that keeps the unfit parts as flat facets); faceted keeps every flat facet as a face and refuses a result of more than 5,000 faces
tolerance expr no Length in millimetres, greater than 0; absent: Auto (the kernel picks from 0.01, 0.02, 0.05 and 0.1 mm the first that fits all but 2 % of the surface); only prismatic reads it

The result replaces the mesh body under its own body ID, so the body keeps its name, colour and place in the browser; suppressing the feature gives the mesh back. The result's faces are named toSolid:<feature>:face:<n>, n the face's position in the result shape, with edges and vertices derived; there is no history into the mesh, so a reference to such a face survives a recompute until the mesh, the method or the tolerance changes. faceted refuses a result of more than 5,000 faces and prismatic more than 500 recognised surfaces, or any region that fits no plane, cylinder, cone, sphere or torus. The feature's report of kind meshToSolid carries method, faces, planes, cylinders, cones, spheres, tori, unfit (regions, triangles, fraction) and, when a region fits nothing, a suggestedTolerance.

6.36 simplifyForPrint

Finds the small rounds, chamfers and holes of the chosen bodies and removes them with Remove Faces' defeaturing (6.34; ADR-0141). It stores no faces: the kernel finds them on every recompute from the limits, so a changed limit or an upstream edit finds them again. No new keys.

Input Kind Required Rule
bodies ref yes Refs of kind body: the solid bodies to simplify. Empty: an error until one is picked. A mesh body is refused
rounds bool no false keeps the rounds whatever maxRoundRadius says. Absent: rounds are removed while maxRoundRadius is given
maxRoundRadius expr no Length in millimetres, greater than 0: the largest round radius removed (a torus by its tube radius). Absent: rounds stay
chamfers bool no false keeps the chamfers whatever maxChamferSize says. Absent: chamfers are removed while maxChamferSize is given
maxChamferSize expr no Length in millimetres, greater than 0: the largest chamfer removed, by its longer leg (how far it cuts back into either face). Absent: chamfers stay
holes bool no false keeps the holes whatever maxHoleDiameter says. Absent: holes are removed while maxHoleDiameter is given
maxHoleDiameter expr no Length in millimetres, greater than 0: the largest hole diameter removed (a counterbored hole by its widest wall, a tapered one by its wider end). Absent: holes stay

A kind is removed while its limit is given and its toggle isn't false; none removed is an error. The app's dialog writes no toggles: a kind it keeps has no limit. Each round, chamfer or hole is all or nothing; one that can't be removed stays and the rest still go (a warning). Removed faces' names are gone; a face that was extended or trimmed keeps its name, as with removeFaces. The feature's report of kind simplifyForPrint carries groups (each round, chamfer or hole found: kind, body, size in mm, faces as a count, removed) and sizes (round, chamfer, hole: the sizes found on the bodies, for the dialog's sliders). Reports are derived, never stored.

6.37 insertDesign

Another design, copied into this one as one feature (P6-26, ADR-0140, label "Insert Design", category create): the design's features are evaluated right after the insert, like a Script's (6.30), and their bodies make one component (4.7). No link to the file it came from is kept.

Input Kind Required Rule
design design yes The copied design (EmbeddedDesign, below).

The feature's component (6) is the component its bodies join; the app makes a new one, named after the file, with each insert. There are no placement inputs: the bodies land at the coordinates the source design gave them, and Move or Place on Bed puts them elsewhere.

EmbeddedDesign (strict, like everything here):

Field Type Required Meaning
name string yes Non-empty: the source design's name when it was inserted.
units mm, cm, m or in yes The source design's length unit (4.1): what its plain numbers are in.
parameters array of Parameter yes The source design's parameters (5.1). Their ids and names are unique within the copy, not across the document: they are a namespace of their own.
features array of EmbeddedFeature yes The source design's features before its timeline marker, in order. Their ids are unique within the copy.

An EmbeddedFeature is a Feature (6) without component, whose inputs may be of every kind but design: an inserted design holds no inserted design. Its file inputs and its texts' attachment:<id> fonts name attachments of this document (4.5), checked like the document's own.

How a reader computes it. Evaluate the copy's parameters and expressions on their own (5.2, with the copy's units as the length unit; never this document's parameters), then walk the copy's features right after the insert, in order, as if they stood in the timeline there, with these changes:

  • each feature's ID is the insert's ID, . and its own (<insert>.<id>), and its name <insert name> › <name>;
  • in its references (section 8; ref inputs, a sketch's projections, a fingerprint's adj), every plain ID (a run of [A-Za-z0-9_.~-]) that is one of the copy's feature IDs gets the same prefix;
  • each expr input (and each sketch dimension) is the value the copy gave it, in mm, degrees or a plain number, without a paramName;
  • each feature sees only the bodies whose IDs start with <insert>., and its result replaces only those: a join or cut of the copy never touches the document's other bodies.

A body of the insert is therefore <insert>.<feature>:<n> and a face extrude:<insert>.<feature>:cap:end; a later feature that refers to one depends on the insert, as on a Script. A copy that holds a script, plugin or insertDesign feature is refused by the app; a reader that meets one reports it as an error of that feature. An expression of the copy that has an error makes the insert an error that names it.


7. Sketch data (sketchData)

{ "kind": "sketchData", "sketch": SketchData }, where SketchData is:

Field Type Required Meaning
entities record: sketch entity ID to Entity yes Points and curves (7.1).
constraints record: constraint ID to Constraint yes Geometric constraints (7.2).
dimensions record: dimension ID to Dimension yes Dimensions (7.3).
projections record: projection ID to Projection no Model geometry projected into the sketch (7.4). Absent: none.

Records keyed by ID, not arrays, so that one deletion is one small patch. JSON object key order carries no meaning. All four records share one ID space per sketch: an ID appears in at most one of them. IDs are unique within the sketch only.

Coordinates are millimetres in the sketch plane's own 2D frame (6.2). The values stored are the solved ones, so a sketch draws immediately and the solver starts from the last solution. A sketch's profiles (closed regions) are derived, never stored.

Reference checks (run when loading; an inconsistent sketch is damaged): every entity a record points at must exist and be of an allowed kind (the tables below give the kinds); a record must not refer to the same entity twice where that is meaningless; each point belongs to at most one curve (two lines that meet share no point; a coincident constraint joins their endpoints).

7.1 Entities (type)

All curves have a construction flag (required): true makes it construction geometry (dashed, helps constrain, never forms profiles).

type Fields Meaning
point x, y (numbers) A point.
line start, end (point IDs, distinct); construction A segment. Direction is start to end.
circle center (point ID); radius (number greater than 0); construction A circle.
arc center, start, end (point IDs, all distinct); construction Counter-clockwise from start to end about center; the radius is the distance from center to start.
ellipse center, major, minor (point IDs, distinct); construction From three points: the centre, the end of the major axis, the end of the minor axis. The minor point is on the ellipse square to the major axis (the solver keeps it so); radii and rotation are the points' distances and angle, nothing else is stored.
spline points (array of at least 2 point IDs, distinct); mode (fit, control or conic, optional — absent means fit); rho (number greater than 0 and less than 1; only with mode: "conic"); knots (array of numbers, optional; only with mode: "control" and not with closed); closed (boolean, optional; not with mode: "conic"); tangents (object with optional start and end, each [x, y] numbers, not both zero; only on an open fit spline); degree (integer 1 to 5, optional; only with mode: "control" and not with closed, and at most points.length − 1); construction A spline (P4-05, ADR-0063). fit (the default): a smooth curve through the points in order. control: the points are the poles of a clamped cubic B-spline with uniform interior knots, so the curve starts at the first point, ends at the last and is tangent to the control polygon at both. conic: exactly three points (start, shoulder, end) and a rho (0.5 = a parabola) that says how full the conic is. The B-spline is derived from the points, so the solver sees only the points; a conic's own curve is rational and is drawn as a cubic within 1e-5 mm. knots (P4-12, ADR-0063's amendment): a control spline's own full clamped knot vector — points.length + 4 values, non-decreasing, the first four 0 and the last four 1, each inner one strictly between and repeated at most three times — which makes the curve a cubic over those knots instead of uniform ones; a trimmed or broken spline is written this way. With a degree the counts follow it: points.length + degree + 1 values, the first and last degree + 1 0 and 1, an inner one repeated at most degree times. closed: true (P4-12): the curve runs back round to its first point (at least 3 points): a closed fit spline is the periodic cubic through its points, a closed control spline the periodic uniform cubic of its poles, both C2 everywhere. Absent means open, as before. tangents (P4-12, ADR-0063's third amendment): an open fit spline's end derivatives, in mm per unit of the curve's parameter (0 to 1) — direction and length of the curve as it leaves its first point (start) and arrives at its last (end); either may be absent (that end is free). degree (same amendment): a control spline's degree, 1 (the control polygon itself) to 5; absent means 3, or points.length − 1 below four points.
text anchor, top (point IDs, distinct); text (string of 1 to 1000 characters, \n separating lines); font (font ID); align (left, center or right); construction A text entity (P4-03, ADR-0058): anchor sits on the first line's baseline, top one text height above it ("up" for the text), so height is `

7.2 Constraints (type)

Field values are entity IDs. "Kind" says what entity types are allowed.

type Fields Allowed kinds and rules
coincident a, b Two distinct points.
pointOnCurve point, curve point a point; curve a line, circle, arc or ellipse.
collinear a, b Two distinct lines.
concentric a, b Two distinct circles or arcs.
midpoint point, of point a point; of a line or an arc.
midpointOnLine a, b Two distinct lines: a's middle lies on b, taken as endless (ADR-0129).
fix entity Any entity (point, line, circle, arc, ellipse, spline — not text). Splines take only fix.
parallel a, b Two distinct lines.
perpendicular a, b Two distinct lines.
horizontal a; b (optional) Either a a line and no b, or a and b two distinct points.
vertical a; b (optional) As horizontal.
tangent a, b; reversed (boolean, optional) Two distinct curves (line, circle or arc), not two lines.
smooth a, b; reversed (boolean, optional) As tangent. Meant as G2 continuity for splines; between lines and arcs the solver treats it as tangency today.
equal a, b Two distinct lines, or two circles/arcs.
symmetric a, b, axis a and b distinct and of the same kind (point, line, or circle/arc); axis a line, distinct from both.

reversed (tangent, smooth) records whether the two curves' directions at the joint point opposite ways (lines run start to end, circles and arcs counter-clockwise); the solver keeps the joint on that side. Absent: the solver picks the side from the current geometry.

7.3 Dimensions (type)

Every dimension has these common fields, in addition to its own:

Field Type Required Meaning
expr string yes The value as an expression (section 5). A length for distance, radius, diameter; an angle for angle.
paramName string matching the name regex no Makes the dimension a model parameter (d1, ...).
driven boolean yes true: a reference dimension that measures the geometry instead of driving it.
label object { "x": number, "y": number } no Where the label sits: an offset in sketch mm from the dimension's anchor. Absent: a default spot.
type Own fields Meaning and rules
distance orientation (aligned, horizontal or vertical, required); a (required); b (optional); sideA, sideB (near or far, optional) A line's length (a a line, no b), or the distance between two points, a point and a line, or two parallel lines; since ADR-0112 also between a circle's or an arc's edge and a point, a line or another circle's or arc's edge. a and b are points, lines, circles or arcs and distinct; a a point, circle or arc needs b; a line with a point or a line must be aligned. A circle's or arc's edge point lies on its whole circle: aligned, on the line from its center toward the other entity (a point, the center's foot on a line, the other center); horizontal or vertical, the quadrant point on that side. sideA (only when a is a circle or an arc) and sideB (likewise for b) say which edge: near (the default when absent), the one facing the other entity, or far, the opposite one. To a line, a horizontal or vertical distance runs along that direction to where it meets the line.
radius curve A circle or arc.
diameter curve A circle or arc.
angle a, b (distinct lines); supplement (boolean, optional) The angle between the lines' directions (start to end), 0 to 180 degrees; with supplement, 180 degrees minus that.

A driving dimension's value comes from expr; the solver moves the geometry to satisfy it. A dimension whose expr cannot be satisfied together with the constraints is reported by the app; the file still loads.

7.4 Projections (projections[<id>])

Model geometry projected into the sketch (P2-09), kept associative. The projected curves are ordinary entities that the solver holds fixed; the kernel reports where they should be on each recompute and the app moves them. Since P4-12 a projection may also be an intersection (mode), and a vertex or a body may be projected. Since ADR-0093 an origin or construction axis or point may be projected too: the dimension and constraint tools add one when the origin or an axis is picked. Since ADR-0125 a curve, a point or a whole sketch of an earlier sketch may be projected.

Field Type Required Meaning
ref GeomRef yes What is projected: kind edge, face, vertex or body, kind axis or point (an origin axis origin:x/origin:y/origin:z, the origin point origin:point, or a construction axis or point feature's ID), kind sketchEntity (<sketchFeatureId>/<entityId>: one curve or point of a sketch, ADR-0125), or kind feature whose id is a sketch feature (the whole sketch, ADR-0125); with mode: "intersect" kind face or body (other kinds are refused), with mode: "center" kind face. A body is referred to by its ID.
curves record: string to entity ID or null yes Each key is what a curve comes from (the source edge's persistent name, sil:<n> for a silhouette of a projected face, sil:<face>:<n> for a silhouette of a projected body's face, edge for a projected edge itself, vertex for a projected vertex, cut:<n> for an intersection curve, axis for a projected axis (a construction line 100 mm long, centred on the axis's origin), point for a projected point, a sketch point, or an axis along the sketch's normal, faceCenter for a face's centre, curve or curve:<n> for a projected sketch curve in pieces, the source entity IDs and <id>:<n> for a whole projected sketch); its value the entity ID of the curve in the sketch, or null once the user deleted it (so it does not come back). A non-null value must be an existing curve (not a point, except for a vertex's vertex, an axis's, a point's or a sketch point's point, and a centre's faceCenter), and no curve is used by two projections. Silhouettes, intersection curves and projected sketch splines and conics that are neither lines nor conics are control-point splines (mode: "control"). A projected construction curve stays construction.
mode "project", "intersect" or "center" no intersect: the curves where the face or body meets the sketch plane, instead of its projection along the sketch's normal. center (issue #140, ADR-0074's amendment): the area centre of a face (ref of kind face only) seen along the sketch's normal, one point keyed faceCenter, where a sketch tool snapped to the middle of a flat face. Absent: project.
linked false no An include ("Keep linked" off) waiting for the kernel's report: the app turns the reported curves into plain entities and removes the record, in the step that added it. Absent: linked. A file normally has none; one left in a file is finished on the next recompute.

8. References

A GeomRef points at geometry made by earlier features. It is stored in ref inputs (refs arrays) and in a projection's ref.

Field Type Required Meaning
kind one of plane, axis, point, face, edge, vertex, profile, body, sketchEntity, feature yes What kind of thing.
id string yes Non-empty. The persistent name (below), never an index into a mesh or a shape.
fingerprint GeomFingerprint no For face, edge and vertex: what the target looked like when picked; used when id no longer resolves.

id by kind:

kind id Made by
plane origin:xy, origin:xz, origin:yz; or a construction plane feature's ID (<featureId>, 6.10) fixed, or a construction feature
axis origin:x, origin:y, origin:z; or a construction axis feature's ID fixed, or a construction feature
profile <sketchFeatureId>/<regionId>: the sketch feature and the region within it. A region's ID is a hash of the curves around its outer loop and the direction each runs in, so it survives moving and resizing derived from the sketch
sketchEntity <sketchFeatureId>/<entityId> (a curve or point picked outside its sketch). In a profile field (extrude, revolve), an entityId of a text means all of that text's letters — every ink region of the text, so the reference survives editing the string, the font or the size (ADR-0058 §5) sketch
body a body ID, <featureId>:<n>: the first body a feature makes is <featureId>:0 kernel
face a face name, op:feature:role[:source] with optional #n split suffixes kernel
edge `e[face face…]with optional@n`
vertex `v[face face…]with optional@n`
point a construction point feature's ID (<featureId>, 6.10) construction feature
feature a feature's ID (<featureId>): the feature itself, for a pattern or mirror that repeats it (6.16) the timeline

Topological names (ADR-0005) describe why a face exists, not where it is, so they stay valid when upstream features change. Grammar:

face     = created split*
created  = op ":" feature ":" role (":" source)?
source   = token | "(" name ")"        nested names in parentheses
split    = "#" n                       n at least 1
edge     = "e[" face ("|" face)* "]" ("@" n)?
vertex   = "v[" face ("|" face)* "]" ("@" n)?

Tokens are plain IDs ([A-Za-z0-9_.~-]+); names never contain /. Examples: extrude:E:cap:end (the end cap of extrude E), extrude:E:side:l8 (the side swept from sketch line l8), box:B:side:front, e[extrude:E:cap:end|extrude:E:side:l8] (the edge between them), v[extrude:E:cap:end|extrude:E:side:l11|extrude:E:side:l8]. Third-party writers can create references to origin planes, axes and sketch profiles and entities; face, edge and vertex names must come from the kernel's naming tables (packages/kernel/src/naming/), which is why a tool that needs them has to run a kernel.

8.1 fingerprint

Recorded when a face, edge or vertex is picked, matched against the current geometry only if id does not resolve (the app then warns that it guessed).

Field Type Required Meaning
type string yes Non-empty. Surface type of a face (plane, cylinder, ...), curve type of an edge (line, circle, ...), point for a vertex.
at [x, y, z] yes Area centroid of a face, midpoint of an edge, position of a vertex (mm).
dir [x, y, z] no A plane's outward normal, an axis, or a line's direction.
size number, at least 0 no Area (mm squared) of a face, length (mm) of an edge.
adj array of strings no Persistent names of the faces around it (for a face: the faces next to it).

9. Example

A complete valid document.json: two parameters (one of them exposed in the customizer), a 40 by 20 mm rectangle sketch on the XY plane (four lines, each with its own two points; joined by coincident constraints; two dimensions, one of them a model parameter), an extrude of its profile that is wall * 5 long, a box on the extrude's end face that joins the body, the body's record, two configurations and one saved view. The sketch has no projections. (A test parses this block against the real schema, so it stays valid.)

{
  "format": "extrudo",
  "formatVersion": 2,
  "id": "5b0b3ad0-2a52-4c6f-9c5e-0f2d3f9e0a11",
  "name": "Example bracket",
  "settings": { "units": "mm", "precision": 2 },
  "parameters": [
    {
      "id": "param-width",
      "name": "width",
      "expression": "40 mm",
      "unit": "length",
      "comment": "Overall width",
      "group": "Size",
      "customizer": { "min": "20 * wall", "max": "80 mm", "step": "5 mm" }
    },
    { "id": "param-wall", "name": "wall", "expression": "2 mm", "unit": "length" }
  ],
  "features": [
    {
      "id": "sketch-1",
      "type": "sketch",
      "name": "Sketch1",
      "suppressed": false,
      "inputs": {
        "plane": { "kind": "ref", "refs": [{ "kind": "plane", "id": "origin:xy" }] },
        "sketch": {
          "kind": "sketchData",
          "sketch": {
            "entities": {
              "p1s": { "type": "point", "x": 0, "y": 0 },
              "p1e": { "type": "point", "x": 40, "y": 0 },
              "p2s": { "type": "point", "x": 40, "y": 0 },
              "p2e": { "type": "point", "x": 40, "y": 20 },
              "p3s": { "type": "point", "x": 40, "y": 20 },
              "p3e": { "type": "point", "x": 0, "y": 20 },
              "p4s": { "type": "point", "x": 0, "y": 20 },
              "p4e": { "type": "point", "x": 0, "y": 0 },
              "l1": { "type": "line", "start": "p1s", "end": "p1e", "construction": false },
              "l2": { "type": "line", "start": "p2s", "end": "p2e", "construction": false },
              "l3": { "type": "line", "start": "p3s", "end": "p3e", "construction": false },
              "l4": { "type": "line", "start": "p4s", "end": "p4e", "construction": false }
            },
            "constraints": {
              "c1": { "type": "coincident", "a": "p1e", "b": "p2s" },
              "c2": { "type": "coincident", "a": "p2e", "b": "p3s" },
              "c3": { "type": "coincident", "a": "p3e", "b": "p4s" },
              "c4": { "type": "coincident", "a": "p4e", "b": "p1s" },
              "c5": { "type": "horizontal", "a": "l1" },
              "c6": { "type": "horizontal", "a": "l3" },
              "c7": { "type": "vertical", "a": "l2" },
              "c8": { "type": "vertical", "a": "l4" },
              "c9": { "type": "fix", "entity": "p1s" }
            },
            "dimensions": {
              "dim1": { "type": "distance", "orientation": "aligned", "a": "l1", "expr": "width", "paramName": "d1", "driven": false },
              "dim2": { "type": "distance", "orientation": "aligned", "a": "l2", "expr": "20 mm", "driven": false, "label": { "x": 3, "y": 0 } }
            }
          }
        }
      }
    },
    {
      "id": "extrude-1",
      "type": "extrude",
      "name": "Extrude1",
      "suppressed": false,
      "inputs": {
        "profiles": { "kind": "ref", "refs": [{ "kind": "profile", "id": "sketch-1/1ihvgl0iouc" }] },
        "distance": { "kind": "expr", "expr": "wall * 5", "unit": "length", "paramName": "d2" },
        "operation": { "kind": "enum", "value": "new-body" }
      }
    },
    {
      "id": "box-1",
      "type": "box",
      "name": "Box1",
      "suppressed": false,
      "inputs": {
        "plane": {
          "kind": "ref",
          "refs": [
            {
              "kind": "face",
              "id": "extrude:extrude-1:cap:end",
              "fingerprint": { "type": "plane", "at": [20, 10, 10], "dir": [0, 0, 1], "size": 800 }
            }
          ]
        },
        "x": { "kind": "expr", "expr": "10 mm", "unit": "length" },
        "length": { "kind": "expr", "expr": "10 mm", "unit": "length" },
        "width": { "kind": "expr", "expr": "10 mm", "unit": "length" },
        "height": { "kind": "expr", "expr": "5 mm", "unit": "length" },
        "rotation": { "kind": "expr", "expr": "15 deg", "unit": "angle" },
        "operation": { "kind": "enum", "value": "join" },
        "bodies": { "kind": "ref", "refs": [{ "kind": "body", "id": "extrude-1:0" }] }
      }
    }
  ],
  "timelineMarker": 3,
  "bodies": {
    "extrude-1:0": { "name": "Body1", "color": "#3b82f6", "opacity": 1, "visible": true }
  },
  "configurations": [
    { "id": "configuration-1", "name": "Narrow", "values": { "param-width": "25 mm" } },
    { "id": "configuration-2", "name": "Wide", "values": { "param-width": "60 mm" } }
  ],
  "views": [
    {
      "id": "view-1",
      "name": "Front",
      "camera": {
        "projection": "orthographic",
        "position": [0, -200, 0],
        "target": [0, 0, 0],
        "up": [0, 0, 1],
        "size": 100
      }
    },
    {
      "id": "view-2",
      "name": "Cut at 10",
      "camera": {
        "projection": "perspective",
        "position": [120, -120, 120],
        "target": [0, 0, 0],
        "up": [0, 0, 1]
      },
      "section": {
        "kind": "planes",
        "planes": [
          { "plane": { "kind": "plane", "id": "origin:xy" }, "offset": "10 mm", "flip": false, "on": true }
        ]
      }
    }
  ],
  "meta": {
    "created": "2026-09-29T10:00:00.000Z",
    "modified": "2026-09-29T10:30:00.000Z",
    "appVersion": "0.1.0"
  }
}

Its container, with one saved version, holds manifest.json ({"format":"extrudo","formatVersion":2,"appVersion":"0.1.0","created":"2026-09-29T10:00:00.000Z","units":"mm"}), document.json (the above), thumbnail.png (optional), versions/index.json ({"versions":[{"number":1,"description":"First cut","created":"2026-09-29T10:15:00.000Z","name":"Example bracket"}]}) and versions/1.json (a document of the same shape).


10. IDs, determinism and what is derived

IDs. Every entity that has an ID (document, feature, parameter, view, configuration, group, component (ComponentId, 4.7), joint (JointId, 4.8), sketch entity, constraint, dimension, projection) gets a random UUID (v4, from crypto.randomUUID()) when it is created and keeps it for life; IDs are never reused. The schema only requires a non-empty string, and readers must accept any. IDs of features are used as tokens inside references and persistent names, so a hand-written feature ID should use only [A-Za-z0-9_.~-] and no / or :. A feature a script makes has the ID <script>.<n> (6.30), which is never stored, and so has a feature of an inserted design, <insert>.<id> (6.37). Sketch entity, constraint, dimension and projection IDs share one space per sketch (section 7). Body IDs are made by the kernel (<feature>:<n>) and profile region IDs by the sketch profile detector; a third-party writer that creates them must follow the rules in section 8.

Determinism. Editing is a sequence of deterministic commands over this JSON (undoable, replayable): a command makes the same change from the same document and payload, and IDs and timestamps are created by the caller, never inside a command. As a file format this means: the same document, evaluated by the same kernel, gives the same geometry, and a writer must not put randomness or time into anything but IDs and meta.

Derived, never stored. The following are computed from the document by the kernel (OCCT compiled to WebAssembly, in a worker) and are not part of any .extrudo file: solids and their meshes; a sketch's profiles and faces; the frame of a sketch on a face; persistent names of faces, edges and vertices (only references to them are stored); measurements; the values of expressions and parameters; constraint status (free, fixed, conflict) of a sketch; body IDs' existence (only their metadata is stored). A tool that wants shapes must run a kernel over the feature list in order, honouring suppressed and timelineMarker, or use the app's STEP, STL and 3MF exports.

Unstored user state. Selection, the open sketch, camera (other than saved views), panel layout, undo history and the display settings are not part of the file.

Known gaps in format 2 (things a tool author might expect that are not there yet): no hole, pattern, move or combine features; no imported bodies and no attachment kinds other than fonts; no cache/; no extension mechanism for third-party keys. Each will arrive as new feature types or optional fields, or as a formatVersion bump with a migration (section 3).