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.
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/).
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.
| 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.
{ "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).
- Unzip. Not a zip: error
not-a-zip. manifest.jsonmissing, unparsable, orformatnotextrudo: errornot-extrudo. No integerformatVersion: errordamaged.document.jsonmissing or not JSON: errordamaged.- Load
document.jsonthrough the pipeline of section 3 (may fail withnot-a-document,too-new,invalid). The file counts as newer when the manifest's or the document'sformatVersionis newer than the reader's. - 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. - When the project's
idis already in the reader's store, the app imports the file as a copy with a new ID rather than overwriting.
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 (
uniton expression inputs,bodies[..].opacity,visible,ghost, a sketch'sprojections, a reference'sfingerprintwere all added this way, and so were the components of P6-05:components,bodies[..].componentandfeatures[..].component, section 4.7, and itsjoints, section 4.8, and theannotationsandannotationCounterof P6-23, section 4.10, and thesheetsof P6-24, section 4.11), new feature types (Feature.typeis 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
kindthe reader doesn't know is left out the same way and listed by its path (sheets.0.items.2); an item with nokindis damage. Writers of other tools must not add private keys to the document all the same: a reader drops them, and there is noextensionsbag in format 2. - Reading a document (
loadDocument):- The value must be an object with
format === "extrudo"and an integerformatVersion, elsenot-a-document. formatVersiongreater 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 istoo-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.- 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. - The result is validated against the current schema (section 4 onwards),
leaving out unknown keys as above (
LoadResult.droppedlists their paths, likefeatures.0.inputs.distance.tolerance); any other failure isinvalid("the document is damaged") with the list of issues.
- The value must be an object with
- 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,disabledinstead ofsuppressed, 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,maxandstepwere 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",30on an angle →"30 deg", plain on a unitless parameter), so a design in inches still reads them as millimetres.customizer.groupmoved to the parameter's owngroup(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 ittoo-new. A third-party writer should write version 2.
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):
timelineMarkermust not exceedfeatures.length.- Feature
ids are unique; parameterids are unique; parameternames are unique; viewids are unique; groupids are unique; configurationids are unique and configurationnames are unique trimmed and case-insensitively ("Small box" and " small box " are the same name); componentids are unique and componentnames are unique case-insensitively ("Lid" and "lid" are the same name); jointids are unique and jointnames are unique case-insensitively too. Every other name is compared exactly, case sensitively. - Every
componenta body (4.2) or a feature (6) names must be a component ofcomponents, and a component'sghostcomes only withvisible: 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 annotationnumbers are unique; everynumberis at mostannotationCounter; asketchanchor names a feature of typesketchinfeatures(section 4.10). - Sheet
ids are unique and sheetnames are unique case-insensitively; viewids and itemids are unique in the whole design; viewnames are unique case-insensitively in their sheet; a projected view'sparentis another view of the same sheet, with no cycle; an item'sviewis a view of its sheet and its anchors fit its kind; a balloon'slistis 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
textentity whosefontisattachment:<id>needs thatidinattachments(section 7.1), and an input of kindfile(section 6.1) needs itsidthere too, of a media type that feature reads (6.28 for animport, 6.29 for acanvas): 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
inputsis additionally checked per featuretype(section 6); the document schema alone only knows the generic input shapes.
| 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. |
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.
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.
| 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. |
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.
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.
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.
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.
| 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.
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"
}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. |
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": 3A 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. |
| 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. |
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. |
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.
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}"]] }
]
}
]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.
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.
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.
- Atoms: a number with an optional unit (
10 mm,2.5in,1e-3 m); a name (a parameter); a callname(args); a parenthesised expression. - Operators, loosest to tightest:
+ -(binary),* /, unary+ -,^(right-associative, so-2^2 = -4and2^3^2 = 512). There is no implicit multiplication (2 widthis 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/intwith no spaces (3/8 in) or a mixed number1 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/2andwidth/2stay arithmetic. - Constant:
pi. Functions:sin cos tan asin acos atan sqrt abs min max round floor ceil.minandmaxtake one or more arguments, the rest one. - Dimensions: length and angle are separate dimensions, so
10 mm + 5 degis 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.
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.
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
expressionof 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);removeParametertakes 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.
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.
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.
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.
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".
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 |
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 |
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.
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.
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.
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.
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).
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).
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.
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.
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.
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.
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.
| 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) |
| 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 |
| 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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).
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).
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.
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.
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.
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;
refinputs, a sketch's projections, a fingerprint'sadj), every plain ID (a run of[A-Za-z0-9_.~-]) that is one of the copy's feature IDs gets the same prefix; - each
exprinput (and each sketch dimension) is the value the copy gave it, in mm, degrees or a plain number, without aparamName; - 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.
{ "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).
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 ` |
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.
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.
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. |
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.
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). |
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).
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).