Export Contract and Format Matrix
On this page
Kessetsu 1.3.0 supports external comparator/two-terminal instances through the same
nine formats. Export metadata/warnings identify
required local file/hash/entry dependencies; no external model body is embedded. Native
SPICE/LTspice file destinations must remain beside their .kess source so relative
references stay valid; when moving exports, deliberately copy matching model directories
subject to their terms. Web downloads require the same manual dependency arrangement.
Two-terminal LTspice exports use its rectangular native outline with explicit Prefix X,
not resistor semantics. Known symbol mappings are unchanged. See the
model catalog for characterized setups and simulator-compatibility losses.
Kessetsu's export layer belongs to neither Web nor CLI. Every output is produced through the kessetsu.export.v3 contract from typed Circuit IR and, where drawing geometry is required, connectivity-verified kessetsu.schematic.v3. CLI and Web call only this shared Core API.
Every artifact reports the exporter name/version, MIME type and extension, byte length, SHA-256, connectivity_verified, capability fields, warnings, and known semantic losses. Unsupported topology or symbol geometry is never approximated silently; a KES-Xxxx diagnostic stops the export.
Export formats
| Format | Purpose | Connectivity | Models | Physical parts | Verification / explicit loss |
|---|---|---|---|---|---|
| SVG | Scalable visual, documentation, and Web | Yes | No | No | Semantic text, fixed viewBox, light export style |
| PNG | Presentations, reports, and quick sharing | Visual projection | No | No | Pure-Rust canonical SVG raster; 0.25..8 scale, white or transparent background |
| Printing and vector documents | Visual projection | No | No | One page, content bounds, automatic orientation, Schematic IR margin, deterministic vector glyphs; no multi-page output | |
| Schematic IR JSON | Lossless drawing interchange | Yes | Yes | No | kessetsu.schematic.v3, deterministic pretty JSON with model provenance but no external model body |
| SPICE | Simulation and automation | Yes | Yes | No | Canonical Ngspice netlist with analyses; physical selection cannot change simulation |
KiCad .kicad_sch |
Continued editing | Yes | Metadata | Yes | Complete pin maps drive real pad numbers/footprint properties; an unmapped footprint is deliberately not attached |
LTspice .asc |
Editing and LTspice simulation | Yes | Yes | No | Real LTspice 24.1.9 -netlist smoke; assertions remain in the .kess source |
| BOM CSV | Sourcing/editable spreadsheet | No | No | Yes | Groups equal selections, excludes abstract sources, retains unresolved/EDA status and condition-qualified provided ratings |
| Handoff JSON | Dependency and readiness manifest | No | Yes | Yes | kessetsu.handoff.v2; IR identity, part assignments/ratings, footprint/pin readiness, exact external model dependencies and unresolved components |
The PDF policy is deliberately single-page because splitting an electronic schematic makes connectivity harder to follow. For a very large circuit, Core must first produce readable Schematic IR; the exporter does not invent arbitrary page breaks. The exporter uses a canonical content-sized media box rather than an A4/Letter frame, avoiding unused space and deriving orientation naturally from the content.
Raster and vector font measurement does not depend on system fonts. The repository's SIL OFL 1.1-licensed Roboto Mono is loaded identically for native and WASM rendering. Semantic SVG text remains selectable in the browser; PNG is raster output, while PDF converts glyphs to deterministic vector paths to avoid platform-dependent font-subset identifiers.
An external subcircuit remains a user-owned sidecar dependency. Schematic JSON and KiCad preserve its verified provenance, entry point, pin order, compatibility mode, redistribution policy, and content hash, but never embed the model body. SPICE and LTspice reference the validated relative file and therefore must be written beside the source .kess file; their export result includes an explicit dependency warning. Visual exports do not require or contain the model body.
Physical metadata follows a stricter EDA rule. BOM and handoff outputs record a stated footprint even when its logical-to-physical mapping is missing, marking that condition explicitly. KiCad attaches the footprint and replaces embedded-symbol pin numbers only when the map is complete. This prevents a convenient default numbering order from silently becoming a board-level claim. Manufacturer/MPN and rating fields are user-provided records, not independently verified stock, price, datasheet or safe-operating-area data. KiCad retains provided ratings, conditions and citations as hidden editable properties; BOM and handoff outputs keep the same provenance.
EDA verification
scripts/verify-eda-exports.ps1 -RequireApplications generates RC filter, gain stage, power
amplifier, external comparator/memristor, loaded filter, transistor-driver, physical-handoff and
independently parameterized reusable-block fixtures through Core/CLI. It then:
- parses each file with KiCad 10, generates a KiCad XML netlist, runs ERC, and compares the exact component set, logical/physical pin identities, mapped footprints, net connectivity, displayed values and model metadata against canonical Schematic IR plus the handoff manifest;
- opens each
.ascthrough LTspice 24.1.9's real-netlistpath and compares component sets, ordered pin connectivity, values/models/stimuli and the active analysis against canonical Schematic IR and SPICE, including a complete.endrecord. Inactive analyses remain in the schematic as comments. Generated net names may differ; merged or split nets fail the comparison.
LTspice supports one active analysis at a time. The exporter activates the first declared analysis and preserves the rest as visible comments with an explicit artifact warning; select the desired analysis in LTspice before running. This target-specific behavior follows the LTspice schematic reference.
Maintenance note: these analysis corrections are included in 1.0.1 in the
changelog. The immutable 1.0.0 CLI downloads are unchanged; for their
LTspice exports, correct/choose the dotted analysis directive in LTspice before simulation.
Source names without the target's V/I prefix receive an ASCII prefix (for example,
bias becomes V_bias) so DC sweeps reference the actual exported source.
When the applications are unavailable, normal local verification reports the check explicitly as skipped; -RequireApplications is mandatory on the release machine. Core unit tests independently verify byte determinism, signatures, schemas, hashes, and connectivity contracts for every format.
KiCad officially documents its modern s-expression schematic format and .kicad_sch extension: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/. LTspice defines .asc schematics and .net/.cir/.sp netlists as application formats: https://ltspicehelpmanual.azurewebsites.net/introduction1.htm.
Other formats
| Target | Decision | Rationale |
|---|---|---|
Qucs-S .sch |
Phase 5+ adapter candidate | Qucs-S documents schematics as project input, but this release has no round-trip evidence with an installed target application: https://qucs-s-help.readthedocs.io/en/latest/overview/understanding-file-structure.html |
| CircuitJS | Phase 5+ adapter candidate | It supports plain-text/URL circuit transfer, but its component and analog-model semantics do not map one-to-one to Kessetsu's scope. Official source: https://github.com/sharpie7/circuitjs1 |
| EasyEDA JSON | Phase 5+ adapter candidate | The format is open and documented, but its compressed primitive contract and editor-version maintenance cost are high; support is not advertised without a real import smoke test: https://docs.easyeda.com/en/DocumentFormat/EasyEDA-Document-Format/ |
| EDIF | Not implemented | Although it is a general interchange standard, there is no verified low-loss flow for a target application and analog schematic behavior |
These decisions do not exist merely to keep the format count small. They preserve the distinction between “a download button exists” and “engineering data was transferred.” A new adapter becomes a supported format only with a canonical graph-connectivity fixture and target-application smoke test.
CLI
kess render circuit.kess --output circuit.svg
kess render circuit.kess --output circuit.png --scale 3 --background transparent
kess render circuit.kess --output circuit.pdf
kess export circuit.kess --target schematic-json --output circuit.schematic.json
kess export circuit.kess --target spice --output circuit.spice
kess export circuit.kess --target kicad --output circuit.kicad_sch
kess export circuit.kess --target ltspice --output circuit.asc
kess export circuit.kess --target bom-csv --output circuit.bom.csv
kess export circuit.kess --target handoff-json --output circuit.handoff.json
Replacing an existing target requires explicit --force. Overwriting the source file is always rejected. With --format json, artifact bytes are never mixed into stdout; an agent sees only structured artifact metadata and diagnostics.