circuit-json
v0.0.559
Published
Definitions for the tscircuit intermediary JSON format
Readme
Circuit JSON Specification circuit-json
Circuit JSON a low-level JSON-array circuit representation. It contains all the information needed to visually represent a schematic, PCB, produce Gerber files, produce bill of materials, run SPICE simulations, view warnings and more. It is designed to easily interoperate with a SQL database.
tscircuit · discord · online circuit json viewer · example.json · Introduction to Circuit JSON Video
You can think of Circuit JSON as a big JSON array of "Circuit Elements", each
element can have references to other elements, for example a source_component
has a corresponding pcb_component representation, which has a corresponding
set of pcb_ports and is connected via pcb_traces.
If you generated Circuit JSON, you can use a wide range of utilities and libraries provided by tscircuit. For example, if you want to autoroute a PCB, you could use Circuit JSON as an input to the tscircuit dsn-converter to generate a DSN file for freerouting, you could then read the DSN file back to Circuit JSON.
This module has the zod definitions and conversion functions for using circuit json, and is the primary way that Circuit JSON is defined and maintained.
https://github.com/user-attachments/assets/2f28b7ba-689e-4d80-85b2-5bdef84b41f8
To quickly generate Circuit JSON with tscircuit, use tscircuit/eval
Things You Can Do With Circuit JSON
- Generate Gerber files
- Generate and read Specctra DSN Autorouting files
- Generate Pick'n'Place Files
- Generate PCB and Schematic SVGs
- Generate Bill of Materials
- Generate SPICE netlists and simulations
- Display PCBs on the web
- Display Schematics on the web
- Display 3d models of electronics on the web
- Render Circuit JSON to a GLTF
Table of Contents
- Circuit JSON Specification
circuit-json- SourceAmbiguousPortReference
- SourceBoard
- SourceBus
- SourceComponentAvailabilityWarning
- SourceComponentBase
- SourceComponentInternalConnection
- SourceComponentMisconfiguredError
- SourceComponentPinsUnderspecifiedWarning
- SourceConfusingNetNameWarning
- SourceDatasheet
- SourceFailedToCreateComponentError
- SourceGroup
- SourceI2cMisconfiguredError
- SourceInterconnect
- SourceInvalidComponentPropertyError
- SourceManuallyPlacedVia
- SourceMissingManufacturerPartNumberWarning
- SourceMissingPropertyError
- SourceMotor
- SourceNet
- SourceNoGroundPinDefinedWarning
- SourceNoPowerPinDefinedWarning
- SourcePartNotFoundWarning
- SourcePcbGroundPlane
- SourcePinAttributes
- SourcePinMissingTraceWarning
- SourcePinMustBeConnectedError
- SourcePort
- SourcePrintedPart
- SourceProjectMetadata
- SourcePropertyIgnoredWarning
- SourceRefdesConventionWarning
- SourceRuntimeError
- SourceSimpleAmmeter
- SourceSimpleBattery
- SourceSimpleCapacitor
- SourceSimpleChip
- SourceSimpleConnector
- SourceSimpleCrystal
- SourceSimpleCurrentSource
- SourceSimpleDiode
- SourceSimpleFiducial
- SourceSimpleFuse
- SourceSimpleGround
- SourceSimpleInductor
- SourceSimpleLed
- SourceSimpleMosfet
- SourceSimpleOpAmp
- SourceSimplePinHeader
- SourceSimplePinout
- SourceSimplePotentiometer
- SourceSimplePowerSource
- SourceSimplePushButton
- SourceSimpleResistor
- SourceSimpleResonator
- SourceSimpleSwitch
- SourceSimpleTestPoint
- SourceSimpleTransistor
- SourceSimpleVoltageProbe
- SourceSimpleVoltageSource
- SourceSubassembly
- SourceTrace
- SourceTraceNotConnectedError
- SourceUnnamedTraceWarning
- UnknownErrorFindingPart
- PcbAutoroutingError
- PcbBend
- PcbBoard
- PcbBreakoutPoint
- PcbBusLengthSkewError
- PcbBusRoutingConstraintError
- PcbBusRoutingConstraintWarning
- PcbComponent
- PcbComponentInvalidLayerError
- PcbComponentMissingCourtyardWarning
- PcbComponentNotOnBoardEdgeError
- PcbComponentOutsideBoardError
- PcbConnectorNotInAccessibleOrientationWarning
- PcbCopperPour
- PcbCopperText
- PcbCourtyardCircle
- PcbCourtyardOutline
- PcbCourtyardOverlapError
- PcbCourtyardPill
- PcbCourtyardPolygon
- PcbCourtyardRect
- PcbCutout
- PcbDebugObject
- PcbFabricationNoteDimension
- PcbFabricationNotePath
- PcbFabricationNoteRect
- PcbFabricationNoteText
- PcbFabricatorExtraChargeWarning
- PcbFootprintOverlapError
- PcbGroundPlane
- PcbGroundPlaneRegion
- PcbGroup
- PcbHole
- PcbKeepout
- PcbKeepoutOverlapWarning
- PcbManualEditConflictWarning
- PcbMissingFootprintError
- PcbNet
- PcbNoteDimension
- PcbNoteLine
- PcbNotePath
- PcbNoteRect
- PcbNoteText
- PcbPackingError
- PcbPadPadClearanceError
- PcbPadTraceClearanceError
- PcbPanel
- PcbPanelizationPlacementError
- PcbPin1Location
- PcbPlacementError
- PcbPlatedHole
- PcbPort
- PcbPortNotConnectedError
- PcbPortNotMatchedError
- PcbPreflightRoutingError
- PcbQuoteEstimate
- PcbRouteHints
- PcbSilkscreenCircle
- PcbSilkscreenGraphic
- PcbSilkscreenLine
- PcbSilkscreenOval
- PcbSilkscreenPath
- PcbSilkscreenPill
- PcbSilkscreenRect
- PcbSilkscreenText
- PcbSoldermaskOpening
- PcbSolderPaste
- PcbStackup
- PcbStiffener
- PcbText
- PcbThermalSpoke
- PcbTrace
- PcbTraceError
- PcbTraceHint
- PcbTraceMissingError
- PcbTraceStyleWarning
- PcbTraceTooLongError
- PcbTraceTooLongWarning
- PcbTraceTooManyViasWarning
- PcbTraceWarning
- PcbVia
- PcbViaClearanceError
- PcbViaTraceClearanceError
- SchematicArc
- SchematicBox
- SchematicCircle
- SchematicComponent
- SchematicComponentOverlapWarning
- SchematicComponentStylingWarning
- SchematicDebugObject
- SchematicElementOutsideSheetWarning
- SchematicError
- SchematicGraphic
- SchematicGroup
- SchematicLayoutError
- SchematicLine
- SchematicManualEditConflictWarning
- SchematicMissingSheetWarning
- SchematicNetLabel
- SchematicPath
- SchematicPort
- SchematicRect
- SchematicSheet
- SchematicSheetStylingWarning
- SchematicSymbol
- SchematicTable
- SchematicTableCell
- SchematicText
- SchematicTextPart
- SchematicTrace
- SchematicVoltageProbe
- SimulationAcSweepCurrentGraph
- SimulationAcSweepVoltageGraph
- SimulationAnalysisResult
- SimulationComplexSample
- SimulationCurrentProbe
- SimulationCurrentSource
- SimulationDcOperatingPointCurrent
- SimulationDcOperatingPointVoltage
- SimulationDcSweepCurrentGraph
- SimulationDcSweepVoltageGraph
- SimulationExperiment
- SimulationEyeDiagram
- SimulationOpAmp
- SimulationOscilloscopeTrace
- SimulationParameterSweep
- SimulationParameterSweepCoordinate
- SimulationPcbDriverReceiverChannel
- SimulationPcbReturnCurrentField
- SimulationPcbReturnCurrentHeatmap
- SimulationPcbReturnCurrentMarker
- SimulationPcbReturnCurrentResult
- SimulationPcbTransientChannelResult
- SimulationPcbTransientChannelSimulation
- SimulationReturnCurrentContact
- SimulationReturnCurrentExcitation
- SimulationReturnCurrentGridJson
- SimulationSignalWaveformResult
- SimulationSpiceSubcircuit
- SimulationSwitch
- SimulationTerminalPort
- SimulationTransientCurrentGraph
- SimulationTransientVoltageGraph
- SimulationUnknownExperimentError
- SimulationVoltageProbe
- SimulationVoltageSource
Typescript Usage
import { any_circuit_element, simple_source_resistor } from "circuit-json"
import type { SourceSimpleResistor } from "circuit-json"
const resistor: SourceSimpleResistor = simple_source_resistor.parse({
type: "source_component",
ftype: "simple_resistor",
source_component_id: "source_component_1",
name: "R1",
resistane: "1k",
})
console.log(resistor.resistance) // 1000
// This is the common way to parse/transform any element
any_circuit_element.parse({/* ... */})Base Units
When there is not a string unit provided, tscircuit assumes the a "base unit" is used.
You can specify circuit json with string units to avoid ambiguity around
units, for example by specifying { max_trace_length: "100mm" } avoids needing to know
the base unit. However if a number is specified, it should be in the base units in the
table below. In this case { max_trace_length: 100 } is equivalent.
The default units when reading a number are defined as follows:
| Measurement Type | Base Unit | Description | | ---------------- | --------- | ------------------ | | Length | mm | Millimeters | | Duration | ms | Milliseconds | | Timestamp | string | ISO 8601 Timestamp | | Mass | g | Grams | | Angle | deg | Degrees | | Frequency | Hz | Hertz | | Volume | ml | Milliliters | | Voltage | V | Volts | | Current | A | Amperes | | Resistance | Ω | Ohms | | Capacitance | F | Farads | | Inductance | H | Henries |
Element Prefixes
Element prefixes are used to separate data that's used in different contexts. This allows developers who use Circuit JSON to develop partial implementations with smaller targets in mind. It can also help simplify JSON elements because schematic and pcb information is not contained in the same object.
A single <resistor /> (in tscircuit) will have a corresponding source_component, schematic_component and pcb_component, as well as other elements that may be necessary
to represent it.
There are 3 main element prefixes:
source_- e.g.source_componentAn element that contains information from whatever originally defined the entity. You can think of this as a non-target representations.- For example, you might have
supplier_part_numbersas a property here, since that is not strictly related to thepcbor theschematic. - This category sometimes contains information that is relevant to both the
pcband theschematic - This is a somewhat a "Miscellaneous" category, because it contains things from the source definition that we wouldn't want to lose.
- For example, you might have
pcb_- e.g.pcb_component,pcb_port. Anything required to render the PCBschematic_- e.g.schematic_component. Anything required to render the Schematic
The system_block_ prefix describes resolved system block diagrams,
including page bounds, block/group geometry, and routed logical connections.
Source Components
SourceAmbiguousPortReference
/** Error emitted when a port hint matches multiple non-overlapping pads,
* making the port reference ambiguous (e.g. multiple pads all named "SH" */
interface SourceAmbiguousPortReference extends BaseCircuitJsonError {
type: "source_ambiguous_port_reference"
source_ambiguous_port_reference_id: string
error_type: "source_ambiguous_port_reference"
source_port_id?: string
source_component_id?: string
}SourceBoard
Defines a board in the source domain
/** Defines a board in the source domain */
interface SourceBoard {
type: "source_board"
source_board_id: string
source_group_id: string
title?: string
}SourceBus
A group of resolved source traces with a maximum routed-length difference.
/** A group of resolved source traces with a maximum routed-length difference. */
interface SourceBus {
type: "source_bus"
source_bus_id: string
name?: string
source_trace_ids: string[]
/** Maximum difference between the longest and shortest member, in millimeters. */
max_length_skew?: number
/** Intended single-ended characteristic impedance, in ohms. */
target_impedance?: number
/** Intended differential characteristic impedance, in ohms. */
target_differential_impedance?: number
/** Ordered polarity for a resolved point-to-point differential pair. */
differential_pair?: {
positive_source_trace_id: string
negative_source_trace_id: string
trace_gap?: number
max_uncoupled_length?: number
}
/** Additional traces for length comparison, without changing electrical membership. */
length_match_source_trace_ids?: string[]
min_length?: SourceBusRouteLength
max_length?: SourceBusRouteLength
target_length?: SourceBusRouteLength
length_tolerance?: number
/** Within this bus, excluding declared differential partners. */
pcb_trace_spacing?: SourceBusTraceSpacing
/** To all signals outside this bus or pair. */
pcb_spacing_to_other_signals?: SourceBusTraceSpacing
target_impedance_min?: number
target_impedance_max?: number
target_differential_impedance_min?: number
target_differential_impedance_max?: number
subcircuit_id?: string
}
/** A routed length in mm, or an offset from the longest endpoint Manhattan distance.
* Explicit references are resolved source traces; omitted references use the bus
* members and length_match_source_trace_ids. */ type SourceBusRouteLength =
| number
| {
reference: "longest_manhattan"
source_trace_ids?: string[]
offset?: number
}
/** Centerline separation in mm or a multiple of the larger local trace width. */ type SourceBusTraceSpacing =
number | { width_multiplier: number }SourceComponentAvailabilityWarning
Warning emitted when no supplier alternative can be confirmed in stock.
/** Warning emitted when no supplier alternative can be confirmed in stock. */
interface SourceComponentAvailabilityWarning {
type: "source_component_availability_warning"
source_component_availability_warning_id: string
warning_type: "source_component_availability_warning"
message: string
source_component_id: string
subcircuit_id?: string
supplier_name: SupplierName
supplier_part_numbers: [string, ...string[]]
}SourceComponentBase
interface SourceComponentBase {
type: "source_component"
ftype?: string
source_component_id: string
name: string
manufacturer_part_number?: string
supplier_part_numbers?: Partial<Record<SupplierName, string[]>>
display_value?: string
display_name?: string
are_pins_interchangeable?: boolean
internally_connected_source_port_ids?: string[][]
source_group_id?: string
subcircuit_id?: string
}SourceComponentInternalConnection
interface SourceComponentInternalConnection {
type: "source_component_internal_connection"
source_component_internal_connection_id: string
source_component_id: string
source_port_ids: string[]
subcircuit_id?: string
}SourceComponentMisconfiguredError
Error emitted when one or more source components have an invalid or conflicting configuration
/** Error emitted when one or more source components have an invalid or conflicting configuration */
interface SourceComponentMisconfiguredError extends BaseCircuitJsonError {
type: "source_component_misconfigured_error"
source_component_misconfigured_error_id: string
error_type: "source_component_misconfigured_error"
source_component_ids: string[]
source_port_ids?: string[]
}SourceComponentPinsUnderspecifiedWarning
Warning emitted when all ports on a source component are underspecified
/** Warning emitted when all ports on a source component are underspecified */
interface SourceComponentPinsUnderspecifiedWarning {
type: "source_component_pins_underspecified_warning"
source_component_pins_underspecified_warning_id: string
warning_type: "source_component_pins_underspecified_warning"
message: string
source_component_id: string
source_port_ids: string[]
subcircuit_id?: string
}SourceConfusingNetNameWarning
Warning emitted when electrically disconnected source nets share a name
/** Warning emitted when electrically disconnected source nets share a name */
interface SourceConfusingNetNameWarning {
type: "source_confusing_net_name_warning"
source_confusing_net_name_warning_id: string
warning_type: "source_confusing_net_name_warning"
message: string
source_net_ids: string[]
net_name: string
subcircuit_id?: string
}SourceDatasheet
Datasheet information for a manufacturer part number, supplied with Circuit JSON.
/** Datasheet information for a manufacturer part number, supplied with Circuit JSON. */
interface SourceDatasheet {
type: "source_datasheet"
source_datasheet_id: string
manufacturer_part_number: string
datasheet_pdf_urls: string[]
description?: string
}SourceFailedToCreateComponentError
/** Error emitted when a component fails to be constructed.
* Contains details about the failure and prevents the component from being rendered. */
interface SourceFailedToCreateComponentError extends BaseCircuitJsonError {
type: "source_failed_to_create_component_error"
source_failed_to_create_component_error_id: string
error_type: "source_failed_to_create_component_error"
component_name?: string
subcircuit_id?: string
parent_source_component_id?: string
pcb_center?: {
x?: number
y?: number
}
schematic_center?: {
x?: number
y?: number
}
}SourceGroup
interface SourceGroup {
type: "source_group"
source_group_id: string
subcircuit_id?: string
parent_subcircuit_id?: string
parent_source_group_id?: string
is_subcircuit?: boolean
show_as_schematic_box?: boolean
name?: string
was_automatically_named?: boolean
}SourceI2cMisconfiguredError
Error emitted when incompatible I2C pins (e.g. SDA and SCL) are connected to the same net
/** Error emitted when incompatible I2C pins (e.g. SDA and SCL) are connected to the same net */
interface SourceI2cMisconfiguredError extends BaseCircuitJsonError {
type: "source_i2c_misconfigured_error"
source_i2c_misconfigured_error_id: string
error_type: "source_i2c_misconfigured_error"
source_port_ids: string[]
}SourceInterconnect
Defines a generic interconnect component
/** Defines a generic interconnect component */
interface SourceInterconnect extends SourceComponentBase {
ftype: "interconnect"
}SourceInvalidComponentPropertyError
The source component property is invalid
/** The source component property is invalid */
interface SourceInvalidComponentPropertyError extends BaseCircuitJsonError {
type: "source_invalid_component_property_error"
source_invalid_component_property_error_id: string
source_component_id: string
property_name: string
property_value?: unknown
expected_format?: string
subcircuit_id?: string
error_type: "source_invalid_component_property_error"
}SourceManuallyPlacedVia
Defines a via that is manually placed in the source domain
/** Defines a via that is manually placed in the source domain */
interface SourceManuallyPlacedVia {
type: "source_manually_placed_via"
source_manually_placed_via_id: string
source_group_id: string
source_net_id?: string
subcircuit_id?: string
source_trace_id?: string
}SourceMissingManufacturerPartNumberWarning
Warning emitted when a source component is missing its manufacturer part number
/** Warning emitted when a source component is missing its manufacturer part number */
interface SourceMissingManufacturerPartNumberWarning {
type: "source_missing_manufacturer_part_number_warning"
source_missing_manufacturer_part_number_warning_id: string
warning_type: "source_missing_manufacturer_part_number_warning"
message: string
source_component_id: string
standard?: string
subcircuit_id?: string
}SourceMissingPropertyError
The source code is missing a property
/** The source code is missing a property */
interface SourceMissingPropertyError extends BaseCircuitJsonError {
type: "source_missing_property_error"
source_missing_property_error_id: string
source_component_id: string
property_name: string
subcircuit_id?: string
error_type: "source_missing_property_error"
}SourceMotor
Defines a motor component.
/** Defines a motor component. */
interface SourceMotor extends SourceComponentBase {
ftype: "motor"
}SourceNet
interface SourceNet {
type: "source_net"
source_net_id: string
name: string
member_source_group_ids: string[]
is_power?: boolean
is_ground?: boolean
is_digital_signal?: boolean
is_analog_signal?: boolean
is_positive_voltage_source?: boolean
trace_width?: number
/** Minimum edge-to-edge clearance in mm from a trace to a different net's
* trace, pad, or via copper on a shared layer. Use the largest applicable
* existing minimum or requirement from either net. */
min_trace_clearance?: number
subcircuit_id?: string
subcircuit_connectivity_map_key?: string
}SourceNoGroundPinDefinedWarning
Warning emitted when a chip has no source ports marked as ground pins
/** Warning emitted when a chip has no source ports marked as ground pins */
interface SourceNoGroundPinDefinedWarning {
type: "source_no_ground_pin_defined_warning"
source_no_ground_pin_defined_warning_id: string
warning_type: "source_no_ground_pin_defined_warning"
message: string
source_component_id: string
source_port_ids: string[]
subcircuit_id?: string
}SourceNoPowerPinDefinedWarning
Warning emitted when a chip has no source ports with requires_power=true
/** Warning emitted when a chip has no source ports with requires_power=true */
interface SourceNoPowerPinDefinedWarning {
type: "source_no_power_pin_defined_warning"
source_no_power_pin_defined_warning_id: string
warning_type: "source_no_power_pin_defined_warning"
message: string
source_component_id: string
source_port_ids: string[]
subcircuit_id?: string
}SourcePartNotFoundWarning
Warning emitted when a requested part can not be found
/** Warning emitted when a requested part can not be found */
interface SourcePartNotFoundWarning {
type: "source_part_not_found_warning"
source_part_not_found_warning_id: string
warning_type: "source_part_not_found_warning"
message: string
source_component_id?: string
subcircuit_id?: string
supplier_name?: SupplierName
manufacturer_part_number?: string
supplier_part_number?: string
part_name?: string
}SourcePcbGroundPlane
Defines a ground plane in the source domain
/** Defines a ground plane in the source domain */
interface SourcePcbGroundPlane {
type: "source_pcb_ground_plane"
source_pcb_ground_plane_id: string
source_group_id: string
source_net_id: string
subcircuit_id?: string
}SourcePinAttributes
Allowed relative deviation from requires_voltage, e.g. 0.05 for ±5%.
interface SourcePinAttributes {
is_input?: boolean
is_output?: boolean
is_bidirectional?: boolean
is_passive?: boolean
can_use_tri_state?: boolean
is_using_tri_state?: boolean
can_use_open_collector?: boolean
is_using_open_collector?: boolean
can_use_open_emitter?: boolean
is_using_open_emitter?: boolean
is_gpio?: boolean
highlight_color?: string
must_be_connected?: boolean
provides_power?: boolean
requires_power?: boolean
provides_ground?: boolean
requires_ground?: boolean
provides_voltage?: number
requires_voltage?: number
/** Allowed relative deviation from requires_voltage, e.g. 0.05 for ±5%. */
required_voltage_tolerance?: number
do_not_connect?: boolean
include_in_board_pinout?: boolean
can_use_internal_pullup?: boolean
is_using_internal_pullup?: boolean
needs_external_pullup?: boolean
can_use_internal_pulldown?: boolean
is_using_internal_pulldown?: boolean
needs_external_pulldown?: boolean
can_use_open_drain?: boolean
is_using_open_drain?: boolean
can_use_push_pull?: boolean
is_using_push_pull?: boolean
should_have_decoupling_capacitor?: boolean
recommended_decoupling_capacitor_capacitance?: string | number
is_configured_for_i2c_sda?: boolean
is_configured_for_i2c_scl?: boolean
is_configured_for_spi_mosi?: boolean
is_configured_for_spi_miso?: boolean
is_configured_for_spi_sck?: boolean
is_configured_for_spi_cs?: boolean
is_configured_for_uart_tx?: boolean
is_configured_for_uart_rx?: boolean
supports_i2c_sda?: boolean
supports_i2c_scl?: boolean
supports_spi_mosi?: boolean
supports_spi_miso?: boolean
supports_spi_sck?: boolean
supports_spi_cs?: boolean
supports_uart_tx?: boolean
supports_uart_rx?: boolean
}SourcePinMissingTraceWarning
Warning emitted when a source component pin is missing a trace connection
/** Warning emitted when a source component pin is missing a trace connection */
interface SourcePinMissingTraceWarning {
type: "source_pin_missing_trace_warning"
source_pin_missing_trace_warning_id: string
warning_type: "source_pin_missing_trace_warning"
message: string
source_component_id: string
source_port_id: string
subcircuit_id?: string
}SourcePinMustBeConnectedError
Error emitted when a pin with mustBeConnected attribute is not connected to any trace
/** Error emitted when a pin with mustBeConnected attribute is not connected to any trace */
interface SourcePinMustBeConnectedError extends BaseCircuitJsonError {
type: "source_pin_must_be_connected_error"
source_pin_must_be_connected_error_id: string
error_type: "source_pin_must_be_connected_error"
source_component_id: string
source_port_id: string
subcircuit_id?: string
}SourcePort
Defines a source port that can be connected to other components
/** Defines a source port that can be connected to other components */
interface SourcePort extends SourcePinAttributes {
type: "source_port"
pin_number?: number
port_hints?: string[]
name: string
source_port_id: string
source_component_id?: string
source_group_id?: string
most_frequently_referenced_by_name?: string
subcircuit_id?: string
subcircuit_connectivity_map_key?: string
}SourcePrintedPart
Defines a 3D-printed part in an assembly.
/** Defines a 3D-printed part in an assembly. */
interface SourcePrintedPart extends SourceComponentBase {
ftype: "printedpart"
/** Printable material, when specified by the author. */
material?: "pla" | "petg" | "nylon"
/** Author-specified print color; also carried on the CAD geometry. */
color?: string
}SourceProjectMetadata
interface SourceProjectMetadata {
type: "source_project_metadata"
name?: string
software_used_string?: string
project_url?: string
source_filesystem_md5_hash?: string
created_at?: string // ISO8601 timestamp
}SourcePropertyIgnoredWarning
The source property was ignored
/** The source property was ignored */
interface SourcePropertyIgnoredWarning {
type: "source_property_ignored_warning"
source_property_ignored_warning_id: string
source_component_id: string
property_name: string
subcircuit_id?: string
error_type: "source_property_ignored_warning"
message: string
}SourceRefdesConventionWarning
Warning emitted when a source component reference designator does not match the component type convention
/** Warning emitted when a source component reference designator does not match the component type convention */
interface SourceRefdesConventionWarning {
type: "source_refdes_convention_warning"
source_refdes_convention_warning_id: string
warning_type: "source_refdes_convention_warning"
message: string
source_component_id: string
refdes: string
source_component_ftype: string
expected_prefixes: string[]
actual_prefix?: string
subcircuit_id?: string
}SourceRuntimeError
interface SourceRuntimeError extends Pick<
BaseCircuitJsonError,
"message" | "error_type"
> {
type: "source_runtime_error"
source_runtime_error_id: string
error_type: "source_runtime_error"
phase_name?: string
}SourceSimpleAmmeter
Defines a simple ammeter component for simulation and measurement
/** Defines a simple ammeter component for simulation and measurement */
interface SourceSimpleAmmeter extends SourceComponentBase {
ftype: "simple_ammeter"
}SourceSimpleBattery
Defines a simple battery component
/** Defines a simple battery component */
interface SourceSimpleBattery extends SourceComponentBase {
ftype: "simple_battery"
capacity: number
}SourceSimpleCapacitor
Defines a simple capacitor component
/** Defines a simple capacitor component */
interface SourceSimpleCapacitor extends SourceComponentBase {
ftype: "simple_capacitor"
capacitance: number
max_voltage_rating?: number
display_capacitance?: string
max_decoupling_trace_length?: number
}SourceSimpleChip
Defines a simple integrated circuit component
/** Defines a simple integrated circuit component */
interface SourceSimpleChip extends SourceComponentBase {
ftype: "simple_chip"
}SourceSimpleConnector
Defines a simple connector component
/** Defines a simple connector component */
interface SourceSimpleConnector extends SourceComponentBase {
ftype: "simple_connector"
/** Connector interface or product family, such as usb_c, m2, or jst_ph */
standard?: SourceSimpleConnectorStandard
/** Number of electrical circuits in the connector */
pin_count?: number
}
type SourceSimpleConnectorStandard =
(typeof source_simple_connector_standards)[number]SourceSimpleCrystal
Defines a simple crystal oscillator component
/** Defines a simple crystal oscillator component */
interface SourceSimpleCrystal extends SourceComponentBase {
ftype: "simple_crystal"
frequency: number
display_frequency?: string
load_capacitance?: number
display_load_capacitance?: string
pin_variant?: "two_pin" | "four_pin"
}SourceSimpleCurrentSource
Defines a simple current source component
/** Defines a simple current source component */
interface SourceSimpleCurrentSource extends SourceComponentBase {
ftype: "simple_current_source"
current: number
frequency?: number
peak_to_peak_current?: number
wave_shape: "sine" | "square" | "triangle" | "sawtooth" | "dc"
phase?: number
duty_cycle?: number
}SourceSimpleDiode
Defines a simple diode component
/** Defines a simple diode component */
interface SourceSimpleDiode extends SourceComponentBase {
ftype: "simple_diode"
}SourceSimpleFiducial
Defines a simple fiducial component
/** Defines a simple fiducial component */
interface SourceSimpleFiducial extends SourceComponentBase {
ftype: "simple_fiducial"
}SourceSimpleFuse
interface SourceSimpleFuse extends SourceComponentBase {
ftype: "simple_fuse"
current_rating_amps: number
voltage_rating_volts: number
}SourceSimpleGround
Defines a simple ground component
/** Defines a simple ground component */
interface SourceSimpleGround extends SourceComponentBase {
ftype: "simple_ground"
}SourceSimpleInductor
Defines a simple inductor component
/** Defines a simple inductor component */
interface SourceSimpleInductor extends SourceComponentBase {
ftype: "simple_inductor"
inductance: number
display_inductance?: string
max_current_rating?: number
}SourceSimpleLed
Defines a simple led component
/** Defines a simple led component */
interface SourceSimpleLed extends Omit<SourceSimpleDiode, "ftype"> {
ftype: "simple_led"
color?: string
wavelength?: string
}SourceSimpleMosfet
/** Defines a simple mosfet component
* This is a three-pin semiconductor device (source, gate, drain)
* Pin configuration is handled by the schematic port system */
interface SourceSimpleMosfet extends SourceComponentBase {
ftype: "simple_mosfet"
channel_type: "n" | "p"
mosfet_mode: "enhancement" | "depletion"
}SourceSimpleOpAmp
Defines a simple op-amp component
/** Defines a simple op-amp component */
interface SourceSimpleOpAmp extends SourceComponentBase {
ftype: "simple_op_amp"
}SourceSimplePinHeader
interface SourceSimplePinHeader extends SourceComponentBase {
ftype: "simple_pin_header"
pin_count: number
gender: "male" | "female"
}SourceSimplePinout
Defines a simple pinout component
/** Defines a simple pinout component */
interface SourceSimplePinout extends SourceComponentBase {
ftype: "simple_pinout"
}SourceSimplePotentiometer
interface SourceSimplePotentiometer extends SourceComponentBase {
ftype: "simple_potentiometer"
max_resistance: number
display_max_resistance?: string
}SourceSimplePowerSource
Defines a simple power source component
/** Defines a simple power source component */
interface SourceSimplePowerSource extends SourceComponentBase {
ftype: "simple_power_source"
voltage: number
}SourceSimplePushButton
Defines a simple push button component
/** Defines a simple push button component */
interface SourceSimplePushButton extends SourceComponentBase {
ftype: "simple_push_button"
}SourceSimpleResistor
Defines a simple resistor component
/** Defines a simple resistor component */
interface SourceSimpleResistor extends SourceComponentBase {
ftype: "simple_resistor"
resistance: number
display_resistance?: string
}SourceSimpleResonator
Defines a simple resonator component
/** Defines a simple resonator component */
interface SourceSimpleResonator extends SourceComponentBase {
ftype: "simple_resonator"
load_capacitance: number
equivalent_series_resistance?: number
frequency: number
}SourceSimpleSwitch
Defines a simple switch component
/** Defines a simple switch component */
interface SourceSimpleSwitch extends SourceComponentBase {
ftype: "simple_switch"
}SourceSimpleTestPoint
/** Defines a simple test point component
* Can be surface-mount or through-hole.
* Pad shape and dimensions configurable for different use cases. */
interface SourceSimpleTestPoint extends SourceComponentBase {
ftype: "simple_test_point"
footprint_variant?: "pad" | "through_hole"
pad_shape?: "rect" | "circle"
pad_diameter?: number | string
hole_diameter?: number | string
width?: number | string
height?: number | string
}SourceSimpleTransistor
/** Defines a simple transistor component
* This is a three-pin semiconductor device (emitter, base, collector)
* Pin configuration is handled by the schematic port system */
interface SourceSimpleTransistor extends SourceComponentBase {
ftype: "simple_transistor"
transistor_type: "npn" | "pnp"
}SourceSimpleVoltageProbe
Defines a simple voltage probe component for simulation and measurement
/** Defines a simple voltage probe component for simulation and measurement */
interface SourceSimpleVoltageProbe extends SourceComponentBase {
ftype: "simple_voltage_probe"
}SourceSimpleVoltageSource
Defines a simple voltage source component
/** Defines a simple voltage source component */
interface SourceSimpleVoltageSource extends SourceComponentBase {
ftype: "simple_voltage_source"
voltage: number
frequency?: number
peak_to_peak_voltage?: number
wave_shape?: "sinewave" | "square" | "triangle" | "sawtooth"
phase?: number
duty_cycle?: number
pulse_delay?: number // ms
rise_time?: number // ms
fall_time?: number // ms
pulse_width?: number // ms
period?: number // ms
}SourceSubassembly
Defines a subassembly component.
/** Defines a subassembly component. */
interface SourceSubassembly extends SourceComponentBase {
ftype: "subassembly"
}SourceTrace
interface SourceTrace {
type: "source_trace"
source_trace_id: string
connected_source_port_ids: string[]
connected_source_net_ids: string[]
subcircuit_id?: string
subcircuit_connectivity_map_key?: string
max_length?: number
max_via_count?: number
name?: string
display_name?: string
min_trace_thickness?: number
}SourceTraceNotConnectedError
Occurs when a source trace selector does not match any ports
/** Occurs when a source trace selector does not match any ports */
interface SourceTraceNotConnectedError extends BaseCircuitJsonError {
type: "source_trace_not_connected_error"
source_trace_not_connected_error_id: string
error_type: "source_trace_not_connected_error"
subcircuit_id?: string
source_group_id?: string
source_trace_id?: string
connected_source_port_ids?: string[]
selectors_not_found?: string[]
}SourceUnnamedTraceWarning
Warning emitted when a source trace is missing a name
/** Warning emitted when a source trace is missing a name */
interface SourceUnnamedTraceWarning {
type: "source_unnamed_trace_warning"
source_unnamed_trace_warning_id: string
warning_type: "source_unnamed_trace_warning"
message: string
source_trace_id: string
subcircuit_id?: string
}UnknownErrorFindingPart
/** Error emitted when an unexpected error occurs while finding a part.
* This includes cases where the API returns HTML instead of JSON,
* network failures, or other unexpected responses. */
interface UnknownErrorFindingPart extends BaseCircuitJsonError {
type: "unknown_error_finding_part"
unknown_error_finding_part_id: string
error_type: "unknown_error_finding_part"
source_component_id?: string
subcircuit_id?: string
}CAD Components
CadAssemblyBomItem
A bill-of-materials entry for a physical assembly.
/** A bill-of-materials entry for a physical assembly. */
interface CadAssemblyBomItem {
type: "cad_assembly_bom_item"
cad_assembly_bom_item_id: string
/** Human-readable item or subassembly name. */
name: string
/** Individual item count per parent assembly, or per root build when unparented. */
quantity: number
/** Parent BOM entry for nesting; independent of electrical group membership. */
parent_cad_assembly_bom_item_id?: string
/** Optional link to the authored component. BOM-only materials may omit it. */
source_component_id?: string
/** Optional associated geometry; its count does not determine the quantity. */
cad_component_ids?: string[]
/** Existing supplier identifiers for parts-engine lookup. */
supplier_part_numbers?: Partial<Record<SupplierName, string[]>>
/** Optional product listings, including stores outside the parts engine. */
purchase_urls?: string[]
}CadCable
/** Resolved cable geometry in circuit-world XYZ, mm, +Z up. Path samples are
* points; first and last are wire exits. Optional pin 1 positions are absolute
* points at the connector mating faces, resolved by the circuit producer.
* Their transverse offsets from the endpoint centerlines fix connector roll.
* Omitted positions preserve legacy parallel-transport orientation.
* Rendering consumes this path without rerouting or adding sag. */
interface CadCable {
type: "cad_cable"
cad_cable_id: string
name: string
from_source_component_id: string
to_source_component_id: string
from_connector_pin1_position?: Point3
to_connector_pin1_position?: Point3
cableprinter_string: string
path: Point3[]
}CadCollisionError
Union silhouette of solid intersection, projected along face normal (mm²
interface CadCollisionError extends BaseCircuitJsonError {
type: "cad_collision_error"
cad_collision_error_id: string
error_type: "cad_collision_error"
cad_component_ids: string[]
pcb_component_ids?: string[]
source_component_ids: string[]
/** Union silhouette of solid intersection, projected along face normal (mm² */
intersection_area_mm2: number
threshold_area_mm2: number
}CadComponent
CAD geometry, optionally associated with a PCB component.
/** CAD geometry, optionally associated with a PCB component. */
interface CadComponent {
type: "cad_component"
cad_component_id: string
/** Omit for CAD geometry that has no corresponding PCB component. */
pcb_component_id?: string
source_component_id: string
position: Point3
rotation?: Point3
/** True for assembled folded position/rotation; false or omitted for flat.
* PCB records stay flat. pcb_component_id identifies the mount/owning board. */
is_on_folded_board?: boolean
size?: Point3
layer?: LayerRef
subcircuit_id?: string
footprinter_string?: string
model_obj_url?: string
model_stl_url?: string
model_3mf_url?: string
model_gltf_url?: string
model_glb_url?: string
model_step_url?: string
model_wrl_url?: string
model_asset?: Asset
model_unit_to_mm_scale_factor?: number
model_board_normal_direction?: CadModelAxisDirection
model_origin_position?: Point3
model_origin_alignment?:
| "unknown"
| "center"
| "center_of_component_on_board_surface"
| "bottom_center_of_component"
model_object_fit: "contain_within_bounds" | "fill_bounds"
model_jscad?: any
/** Explicit CAD color override; omission preserves authored model materials. */
color?: string
show_as_translucent_model?: boolean
show_as_bounding_box?: boolean
show_hidden_edges?: boolean
anchor_alignment: CadComponentAnchorAlignment
}CadExplosionMove
interface CadExplosionMove {
type: "cad_explosion_move"
cad_explosion_move_id: string
cad_explosion_stage_id: string
order: number
targets: CadExplosionTarget[]
translation: Point3
}
type CadExplosionTarget =
| { type: "cad_reference_surface"; cad_reference_surface_id: string }
| { type: "cad_component"; cad_component_id: string }
| { type: "cad_explosion_stage"; cad_explosion_stage_id: string }CadExplosionStage
interface CadExplosionStage {
type: "cad_explosion_stage"
cad_explosion_stage_id: string
name: string
order: number
cad_component_ids: string[]
cad_reference_surface_ids?: string[]
}CadReferenceSurface
/** Resolved reference frame in right-handed circuit world: +X right, +Y top,
* +Z above. Center and extents are mm; normal and x_axis are dimensionless,
* perpendicular unit directions, within 1e-6 numerical tolerance. The frame's
* Y direction is normal cross x_axis. Names are unique within source_component_id.
* Width and height are both present or both omitted; omission adds no default.
* This record describes mounting reference geometry for optional visualization. */
interface CadReferenceSurface {
type: "cad_reference_surface"
cad_reference_surface_id: string
source_component_id: string
name: string
shape: "rect"
center: Point3
normal: Point3
x_axis: Point3
width?: number
height?: number
subcircuit_id?: string
}PCB Elements
PcbAutoroutingError
interface PcbAutoroutingErrorInterface extends BaseCircuitJsonError {
type: "pcb_autorouting_error"
pcb_error_id: string
error_type: "pcb_autorouting_error"
subcircuit_id?: string
}PcbBend
Defines a bend without changing the flat PCB layout or stored CAD poses.
/** Defines a bend without changing the flat PCB layout or stored CAD poses. */
interface PcbBend {
type: "pcb_bend"
pcb_bend_id: string
pcb_board_id: string
/** Ownership only; group transforms are already resolved into board coordinates. */
pcb_group_id?: string
subcircuit_id?: string
name?: string
/** Bend-zone centerline endpoints, relative to the flat board center, in mm. */
start: Point
end: Point
/** Target angle in signed degrees; positive folds the moving side toward local top. Zero is flat. */
bend_angle: Rotation
/** Positive radius at the neutral surface, in mm. Zone width is radius times absolute angle in radians. */
bend_radius: Length
/** Moving side looking from start toward end in the flat top view. */
bend_side: "left" | "right"
}PcbBoard
Defines the board outline of the PCB
/** Defines the board outline of the PCB */
interface PcbBoard extends ManufacturingDrcProperties {
type: "pcb_board"
pcb_board_id: string
pcb_panel_id?: string
carrier_pcb_board_id?: string
is_subcircuit?: boolean
subcircuit_id?: string
is_mounted_to_carrier_board?: boolean
is_via_in_pad_allowed?: boolean
default_via_tented_on_top?: boolean
default_via_tented_on_bottom?: boolean
default_via_plugged?: boolean
/** Preferred trace width in mm for connections without an explicit width. */
default_nominal_trace_width?: Length
width?: Length
height?: Length
display_offset_x?: string
display_offset_y?: string
thickness: Length
num_layers: number
/** Whether autorouters may generate blind and buried vias. */
allow_blind_and_buried_vias?: boolean
center: Point
outline?: Point[]
shape?: "rect" | "polygon"
material: "fr4" | "fr1" | "flex"
solder_mask_color?: string
silkscreen_color?: string
anchor_position?: Point
anchor_alignment?: NinePointAnchor
position_mode?: "relative_to_panel_anchor" | "none"
}PcbBreakoutPoint
Defines a routing target within a pcb_group for a source_trace or source_net
/** Defines a routing target within a pcb_group for a source_trace or source_net */
interface PcbBreakoutPoint {
type: "pcb_breakout_point"
pcb_breakout_point_id: string
pcb_group_id: string
subcircuit_id?: string
source_trace_id?: string
source_port_id?: string
source_net_id?: string
layer?: LayerRef
x: Distance
y: Distance
}PcbBusLengthSkewError
The routed lengths of a bus's members exceed its allowed skew.
/** The routed lengths of a bus's members exceed its allowed skew. */
interface PcbBusLengthSkewError extends BaseCircuitJsonError {
type: "pcb_bus_length_skew_error"
pcb_bus_length_skew_error_id: string
error_type: "pcb_bus_length_skew_error"
source_bus_id: string
source_trace_ids: string[]
pcb_trace_ids: string[]
actual_length_skew: number
maximum_length_skew: number
subcircuit_id?: string
}PcbBusRoutingConstraintError
type PcbBusRoutingConstraintError =
WithErrorContext<PcbBusRoutingConstraintViolation>
/** Rule-specific routing measurements. Lengths and centreline spacing are mm; impedance is ohms. */ type PcbBusRoutingConstraintViolation =
| {
routing_rule: "length_skew"
actual_length_skew: number
maximum_length_skew: number
}
| {
routing_rule: "min_length"
actual_trace_length: number
minimum_trace_length: number
}
| {
routing_rule: "max_length"
actual_trace_length: number
maximum_trace_length: number
}
| {
routing_rule: "target_length"
actual_trace_length: number
target_trace_length: number
length_tolerance: number
}
| {
routing_rule: "pcb_trace_spacing"
other_pcb_trace_id: string
other_source_trace_id?: string
actual_centerline_spacing: number
minimum_centerline_spacing: number
}
| {
routing_rule: "pcb_spacing_to_other_signals"
other_pcb_trace_id: string
other_source_trace_id?: string
actual_centerline_spacing: number
minimum_centerline_spacing: number
}
| {
routing_rule: "impedance_target"
target_impedance: number
minimum_impedance?: number
maximum_impedance?: number
}PcbBusRoutingConstraintWarning
type PcbBusRoutingConstraintWarning = WithWarningContext<WarningRule>PcbComponent
interface PcbComponentMetadata {
kicad_footprint?: KicadFootprintMetadata
}
type SupplierPin1LocationMap = Partial<Record<SupplierName, PcbPin1Location>>PcbComponentInvalidLayerError
Error emitted when a component is placed on an invalid layer (components can only be on 'top' or 'bottom' layers)
/** Error emitted when a component is placed on an invalid layer (components can only be on 'top' or 'bottom' layers) */
interface PcbComponentInvalidLayerError extends BaseCircuitJsonError {
type: "pcb_component_invalid_layer_error"
pcb_component_invalid_layer_error_id: string
error_type: "pcb_component_invalid_layer_error"
pcb_component_id?: string
source_component_id: string
layer: LayerRef
subcircuit_id?: string
}PcbComponentMissingCourtyardWarning
Warning emitted when a PCB component has no courtyard geometry
