0003 — Project format

Status: accepted · specification: The .falcad format

Decision

A project is a folder with a *.falcad manifest and discrete documents (*.sch.json, *.pcb.json, *.sim.json, HDL and firmware sources). An optional .falcadpack ZIP archive carries a whole project as one file.
Documents are canonical JSON. Key order is deterministic and output is byte-identical for identical models. Git diffs therefore show only real changes.
Lengths are integer nanometres, so there is no floating-point drift from repeated moves.
Every entity has a UUID v4 identity (see 0009).
Documents carry schema and version. Migrations run forward, and newer versions are refused rather than corrupted.
The zod schemas in @falcad/format are the single source of truth. JSON Schemas for other languages are generated from them and checked for drift.
Loaders treat projects as untrusted. They enforce safe relative paths (no traversal, devices or drive letters), check symlinks, cap sizes, and defend against zip-slip and zip bombs.

Binary or SQLite projects: not reviewable in Git, and lock users into tooling.
A single JSON blob: produces huge diffs and merge conflicts between disciplines.