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
Table of Contents
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)
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:
| 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_component An 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_numbers as a property here, since that is
not strictly related to the pcb or the schematic.
- This category sometimes contains information that is relevant to both the
pcb and the schematic
- This is a somewhat a "Miscellaneous" category, because it contains things from the source
definition that we wouldn't want to lose.
pcb_ - e.g. pcb_component, pcb_port. Anything required to render the PCB
schematic_ - e.g. schematic_component. Anything required to render the Schematic
Source Components
SourceBoard
Source
Defines a board in the source domain
interface SourceBoard {
type: "source_board"
source_board_id: string
source_group_id: string
title?: string
}
SourceComponentBase
Source
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
are_pins_interchangeable?: boolean
internally_connected_source_port_ids?: string[][]
source_group_id?: string
subcircuit_id?: string
}
SourceComponentInternalConnection
Source
interface SourceComponentInternalConnection {
type: "source_component_internal_connection"
source_component_internal_connection_id: string
source_component_id: string
source_port_ids: string[]
subcircuit_id?: string
}
SourceFailedToCreateComponentError
Source
interface SourceFailedToCreateComponentError {
type: "source_failed_to_create_component_error"
source_failed_to_create_component_error_id: string
error_type: "source_failed_to_create_component_error"
message: string
component_name?: string
subcircuit_id?: string
parent_source_component_id?: string
pcb_center?: {
x?: number
y?: number
}
schematic_center?: {
x?: number
y?: number
}
}
SourceGroup
Source
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
}
SourceInterconnect
Source
Defines a generic interconnect component
interface SourceInterconnect extends SourceComponentBase {
ftype: "interconnect"
}
SourceManuallyPlacedVia
Source
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
}
SourceMissingPropertyError
Source
The source code is missing a property
interface SourceMissingPropertyError {
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"
message: string
}
SourceNet
Source
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
subcircuit_id?: string
subcircuit_connectivity_map_key?: string
}
SourcePcbGroundPlane
Source
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
}
SourcePinMissingTraceWarning
Source
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
Source
Error emitted when a pin with mustBeConnected attribute is not connected to any trace
interface SourcePinMustBeConnectedError {
type: "source_pin_must_be_connected_error"
source_pin_must_be_connected_error_id: string
error_type: "source_pin_must_be_connected_error"
message: string
source_component_id: string
source_port_id: string
subcircuit_id?: string
}
SourcePort
Source
Defines a source port that can be connected to other components
interface SourcePort {
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
must_be_connected?: boolean
provides_power?: boolean
requires_power?: boolean
provides_ground?: boolean
requires_ground?: boolean
provides_voltage?: string | number
requires_voltage?: string | 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
}
SourceProjectMetadata
Source
interface SourceProjectMetadata {
type: "source_project_metadata"
name?: string
software_used_string?: string
project_url?: string
created_at?: string
}
SourcePropertyIgnoredWarning
Source
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
}
SourceSimpleBattery
Source
Defines a simple battery component
interface SourceSimpleBattery extends SourceComponentBase {
ftype: "simple_battery"
capacity: number
}
SourceSimpleCapacitor
Source
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
Source
Defines a simple integrated circuit component
interface SourceSimpleChip extends SourceComponentBase {
ftype: "simple_chip"
}
SourceSimpleCrystal
Source
Defines a simple crystal oscillator component
interface SourceSimpleCrystal extends SourceComponentBase {
ftype: "simple_crystal"
frequency: number
load_capacitance?: number
}
SourceSimpleDiode
Source
Defines a simple diode component
interface SourceSimpleDiode extends SourceComponentBase {
ftype: "simple_diode"
}
SourceSimpleFiducial
Source
Defines a simple fiducial component
interface SourceSimpleFiducial extends SourceComponentBase {
ftype: "simple_fiducial"
}
SourceSimpleFuse
Source
interface SourceSimpleFuse extends SourceComponentBase {
ftype: "simple_fuse"
current_rating_amps: number
voltage_rating_volts: number
}
SourceSimpleGround
Source
Defines a simple ground component
interface SourceSimpleGround extends SourceComponentBase {
ftype: "simple_ground"
}
SourceSimpleInductor
Source
Defines a simple inductor component
interface SourceSimpleInductor extends SourceComponentBase {
ftype: "simple_inductor"
inductance: number
display_inductance?: string
max_current_rating?: number
}
SourceSimpleLed
Source
Defines a simple led component
interface SourceSimpleLed extends Omit<SourceSimpleDiode, "ftype"> {
ftype: "simple_led"
color?: string
wavelength?: string
}
SourceSimpleMosfet
Source
interface SourceSimpleMosfet extends SourceComponentBase {
ftype: "simple_mosfet"
channel_type: "n" | "p"
mosfet_mode: "enhancement" | "depletion"
}
Source
interface SourceSimplePinHeader extends SourceComponentBase {
ftype: "simple_pin_header"
pin_count: number
gender: "male" | "female"
}
SourceSimplePinout
Source
Defines a simple pinout component
interface SourceSimplePinout extends SourceComponentBase {
ftype: "simple_pinout"
}
SourceSimplePotentiometer
Source
interface SourceSimplePotentiometer extends SourceComponentBase {
ftype: "simple_potentiometer"
max_resistance: number
}
SourceSimplePowerSource
Source
Defines a simple power source component
interface SourceSimplePowerSource extends SourceComponentBase {
ftype: "simple_power_source"
voltage: number
}
SourceSimplePushButton
Source
Defines a simple push button component
interface SourceSimplePushButton extends SourceComponentBase {
ftype: "simple_push_button"
}
SourceSimpleResistor
Source
Defines a simple resistor component
interface SourceSimpleResistor extends SourceComponentBase {
ftype: "simple_resistor"
resistance: number
display_resistance?: string
}
SourceSimpleResonator
Source
Defines a simple resonator component
interface SourceSimpleResonator extends SourceComponentBase {
ftype: "simple_resonator"
load_capacitance: number
equivalent_series_resistance?: number
frequency: number
}
SourceSimpleSwitch
Source
Defines a simple switch component
interface SourceSimpleSwitch extends SourceComponentBase {
ftype: "simple_switch"
}
SourceSimpleTestPoint
Source
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
Source
interface SourceSimpleTransistor extends SourceComponentBase {
ftype: "simple_transistor"
transistor_type: "npn" | "pnp"
}
SourceSimpleVoltageProbe
Source
Defines a simple voltage probe component for simulation and measurement
interface SourceSimpleVoltageProbe extends SourceComponentBase {
ftype: "simple_voltage_probe"
}
SourceTrace
Source
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
display_name?: string
min_trace_thickness?: number
}
SourceTraceNotConnectedError
Source
Occurs when a source trace selector does not match any ports
interface SourceTraceNotConnectedError {
type: "source_trace_not_connected_error"
source_trace_not_connected_error_id: string
error_type: "source_trace_not_connected_error"
message: string
subcircuit_id?: string
source_group_id?: string
source_trace_id?: string
connected_source_port_ids?: string[]
selectors_not_found?: string[]
}
UnknownErrorFindingPart
Source
interface UnknownErrorFindingPart {
type: "unknown_error_finding_part"
unknown_error_finding_part_id: string
error_type: "unknown_error_finding_part"
message: string
source_component_id?: string
subcircuit_id?: string
}
CAD Components
CadComponent
Source
interface CadComponent {
type: "cad_component"
cad_component_id: string
pcb_component_id: string
source_component_id: string
position: Point3
rotation?: Point3
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_unit_to_mm_scale_factor?: number
model_jscad?: any
show_as_translucent_model?: boolean
}
PCB Elements
PcbAutoroutingError
Source
interface PcbAutoroutingErrorInterface {
type: "pcb_autorouting_error"
pcb_error_id: string
error_type: "pcb_autorouting_error"
message: string
subcircuit_id?: string
}
PcbBoard
Source
Defines the board outline of the PCB
interface PcbBoard {
type: "pcb_board"
pcb_board_id: string
pcb_panel_id?: string
is_subcircuit?: boolean
subcircuit_id?: string
width?: Length
height?: Length
display_offset_x?: string
display_offset_y?: string
thickness: Length
num_layers: number
center: Point
outline?: Point[]
shape?: "rect" | "polygon"
material: "fr4" | "fr1"
anchor_position?: Point
anchor_alignment: NinePointAnchor
position_mode?: "relative_to_panel_anchor" | "none"
}
PcbBreakoutPoint
Source
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
x: Distance
y: Distance
}
PcbComponent
Source
Defines a component on the PCB
interface PcbComponent {
type: "pcb_component"
pcb_component_id: string
source_component_id: string
subcircuit_id?: string
center: Point
layer: LayerRef
rotation: Rotation
display_offset_x?: string
display_offset_y?: string
width: Length
height: Length
do_not_place?: boolean
pcb_group_id?: string
position_mode?:
| "packed"
| "relative_to_group_anchor"
| "relative_to_another_component"
| "none"
anchor_position?: Point
anchor_alignment?: NinePointAnchor
positioned_relative_to_pcb_group_id?: string
positioned_relative_to_pcb_board_id?: string
obstructs_within_bounds: boolean
}
PcbComponentInvalidLayerError
Source
Error emitted when a component is placed on an invalid layer (components can only be on 'top' or 'bottom' layers)
interface PcbComponentInvalidLayerError {
type: "pcb_component_invalid_layer_error"
pcb_component_invalid_layer_error_id: string
error_type: "pcb_component_invalid_layer_error"
message: string
pcb_component_id?: string
source_component_id: string
layer: LayerRef
subcircuit_id?: string
}
PcbComponentOutsideBoardError
Source
Error emitted when a PCB component is placed outside the board boundaries
interface PcbComponentOutsideBoardError {
type: "pcb_component_outside_board_error"
pcb_component_outside_board_error_id: string
error_type: "pcb_component_outside_board_error"
message: string
pcb_component_id: string
pcb_board_id: string
component_center: Point
component_bounds: {
min_x: number
max_x: number
min_y: number
max_y: number
}
subcircuit_id?: string
source_component_id?: string
}
PcbCopperPour
Source
Defines a rectangular copper pour on the PCB.
interface PcbCopperPourRect {
type: "pcb_copper_pour"
pcb_copper_pour_id: string
covered_with_solder_mask: boolean
pcb_group_id?: string
subcircuit_id?: string
layer: LayerRef
source_net_id?: string
shape: "rect"
center: Point
width: Length
height: Length
rotation?: Rotation
}
PcbCopperText
Source
Defines copper text on the PCB
interface PcbCopperText {
type: "pcb_copper_text"
pcb_copper_text_id: string
pcb_group_id?: string
subcircuit_id?: string
font: "tscircuit2024"
font_size: Length
pcb_component_id: string
text: string
is_knockout?: boolean
knockout_padding?: {
left: Length
top: Length
bottom: Length
right: Length
}
ccw_rotation?: number
layer: LayerRef
is_mirrored?: boolean
anchor_position: Point
anchor_alignment: NinePointAnchor
}
PcbCourtyardOutline
Source
Defines a courtyard outline on the PCB
interface PcbCourtyardOutline {
type: "pcb_courtyard_outline"
pcb_courtyard_outline_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
layer: VisibleLayer
outline: Point[]
stroke_width: Length
is_closed?: boolean
is_stroke_dashed?: boolean
color?: string
}
PcbCourtyardPolygon
Source
Defines a courtyard polygon on the PCB
interface PcbCourtyardPolygon {
type: "pcb_courtyard_polygon"
pcb_courtyard_polygon_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
layer: VisibleLayer
points: Point[]
color?: string
}
PcbCourtyardRect
Source
Defines a courtyard rectangle on the PCB
interface PcbCourtyardRect {
type: "pcb_courtyard_rect"
pcb_courtyard_rect_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
center: Point
width: Length
height: Length
layer: VisibleLayer
color?: string
}
PcbCutout
Source
Defines a rectangular cutout on the PCB.
interface PcbCutoutRect {
type: "pcb_cutout"
pcb_cutout_id: string
pcb_group_id?: string
subcircuit_id?: string
pcb_board_id?: string
pcb_panel_id?: string
shape: "rect"
center: Point
width: Length
height: Length
rotation?: Rotation
corner_radius?: Length
}
PcbFabricationNoteDimension
Source
Defines a measurement annotation within PCB fabrication notes
interface PcbFabricationNoteDimension {
type: "pcb_fabrication_note_dimension"
pcb_fabrication_note_dimension_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
layer: VisibleLayer
from: Point
to: Point
text?: string
text_ccw_rotation?: number
offset?: Length
offset_distance?: Length
offset_direction?: {
x: number
y: number
}
font: "tscircuit2024"
font_size: Length
color?: string
arrow_size: Length
}
PcbFabricationNotePath
Source
Defines a fabrication path on the PCB for fabricators or assemblers
interface PcbFabricationNotePath {
type: "pcb_fabrication_note_path"
pcb_fabrication_note_path_id: string
pcb_component_id: string
subcircuit_id?: string
layer: LayerRef
route: Point[]
stroke_width: Length
color?: string
}
PcbFabricationNoteRect
Source
Defines a fabrication note rectangle on the PCB
interface PcbFabricationNoteRect {
type: "pcb_fabrication_note_rect"
pcb_fabrication_note_rect_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
center: Point
width: Length
height: Length
layer: VisibleLayer
stroke_width: Length
corner_radius?: Length
is_filled?: boolean
has_stroke?: boolean
is_stroke_dashed?: boolean
color?: string
}
PcbFabricationNoteText
Source
Defines a fabrication note in text on the PCB, useful for leaving notes for assemblers or fabricators
interface PcbFabricationNoteText {
type: "pcb_fabrication_note_text"
pcb_fabrication_note_text_id: string
subcircuit_id?: string
pcb_group_id?: string
font: "tscircuit2024"
font_size: Length
pcb_component_id: string
text: string
layer: VisibleLayer
anchor_position: Point
anchor_alignment:
| "center"
| "top_left"
| "top_right"
| "bottom_left"
| "bottom_right"
color?: string
}
Source
Error emitted when a pcb footprint overlaps with another element
interface PcbFootprintOverlapError {
type: "pcb_footprint_overlap_error"
pcb_error_id: string
error_type: "pcb_footprint_overlap_error"
message: string
pcb_smtpad_ids?: string[]
pcb_plated_hole_ids?: string[]
pcb_hole_ids?: string[]
pcb_keepout_ids?: string[]
}
PcbGroundPlane
Source
Defines a ground plane on the PCB
interface PcbGroundPlane {
type: "pcb_ground_plane"
pcb_ground_plane_id: string
source_pcb_ground_plane_id: string
source_net_id: string
pcb_group_id?: string
subcircuit_id?: string
}
PcbGroundPlaneRegion
Source
Defines a polygon region of a ground plane
interface PcbGroundPlaneRegion {
type: "pcb_ground_plane_region"
pcb_ground_plane_region_id: string
pcb_ground_plane_id: string
pcb_group_id?: string
subcircuit_id?: string
layer: LayerRef
points: Point[]
}
PcbGroup
Source
Defines a group of components on the PCB
interface PcbGroup {
type: "pcb_group"
pcb_group_id: string
source_group_id: string
is_subcircuit?: boolean
subcircuit_id?: string
width?: Length
height?: Length
center: Point
display_offset_x?: string
display_offset_y?: string
outline?: Point[]
anchor_position?: Point
anchor_alignment: NinePointAnchor
position_mode?: "packed" | "relative_to_group_anchor" | "none"
positioned_relative_to_pcb_group_id?: string
positioned_relative_to_pcb_board_id?: string
pcb_component_ids: string[]
child_layout_mode?: "packed" | "none"
name?: string
description?: string
layout_mode?: string
autorouter_configuration?: {
trace_clearance: Length
}
autorouter_used_string?: string
}
PcbHole
Source
Defines a circular hole on the PCB
interface PcbHoleCircle {
type: "pcb_hole"
pcb_hole_id: string
pcb_group_id?: string
subcircuit_id?: string
pcb_component_id?: string
hole_shape: "circle"
hole_diameter: number
x: Distance
y: Distance
is_covered_with_solder_mask?: boolean
soldermask_margin?: number
}
PcbManualEditConflictWarning
Source
Warning emitted when a component has both manual placement (via manualEdits) and explicit pcbX/pcbY coordinates
interface PcbManualEditConflictWarning {
type: "pcb_manual_edit_conflict_warning"
pcb_manual_edit_conflict_warning_id: string
warning_type: "pcb_manual_edit_conflict_warning"
message: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
source_component_id: string
}
Source
Defines a placement error on the PCB
interface PcbMissingFootprintError {
type: "pcb_missing_footprint_error"
pcb_missing_footprint_error_id: string
pcb_group_id?: string
subcircuit_id?: string
error_type: "pcb_missing_footprint_error"
source_component_id: string
message: string
}
PcbNet
Source
Defines a net on the PCB
interface PcbNet {
type: "pcb_net"
pcb_net_id: string
source_net_id?: string
highlight_color?: string
}
PcbNoteDimension
Source
Defines a measurement annotation within PCB documentation notes
interface PcbNoteDimension {
type: "pcb_note_dimension"
pcb_note_dimension_id: string
pcb_component_id?: string
pcb_group_id?: string
subcircuit_id?: string
name?: string
from: Point
to: Point
text?: string
text_ccw_rotation?: number
offset_distance?: Length
offset_direction?: {
x: number
y: number
}
font: "tscircuit2024"
font_size: Length
color?: string
arrow_size: Length
}
PcbNoteLine
Source
Defines a straight documentation note line on the PCB
interface PcbNoteLine {
type: "pcb_note_line"
pcb_note_line_id: string
pcb_component_id?: string
pcb_group_id?: string
subcircuit_id?: string
name?: string
text?: string
x1: Distance
y1: Distance
x2: Distance
y2: Distance
stroke_width: Distance
color?: string
is_dashed?: boolean
}
PcbNotePath
Source
Defines a polyline documentation note on the PCB
interface PcbNotePath {
type: "pcb_note_path"
pcb_note_path_id: string
pcb_component_id?: string
pcb_group_id?: string
subcircuit_id?: string
name?: string
text?: string
route: Point[]
stroke_width: Length
color?: string
}
PcbNoteRect
Source
Defines a rectangular documentation note on the PCB
interface PcbNoteRect {
type: "pcb_note_rect"
pcb_note_rect_id: string
pcb_component_id?: string
pcb_group_id?: string
subcircuit_id?: string
name?: string
text?: string
center: Point
width: Length
height: Length
stroke_width: Length
corner_radius?: Length
is_filled?: boolean
has_stroke?: boolean
is_stroke_dashed?: boolean
color?: string
}
PcbNoteText
Source
Defines a documentation note in text on the PCB
interface PcbNoteText {
type: "pcb_note_text"
pcb_note_text_id: string
pcb_component_id?: string
pcb_group_id?: string
subcircuit_id?: string
name?: string
font: "tscircuit2024"
font_size: Length
text?: string
anchor_position: Point
anchor_alignment:
| "center"
| "top_left"
| "top_right"
| "bottom_left"
| "bottom_right"
layer: VisibleLayer
is_mirrored?: boolean
color?: string
}
PcbPanel
Source
Defines a PCB panel that can contain multiple boards
interface PcbPanel {
type: "pcb_panel"
pcb_panel_id: string
width: Length
height: Length
center: Point
thickness: Length
covered_with_solder_mask: boolean
}
PcbPlacementError
Source
Defines a placement error on the PCB
interface PcbPlacementError {
type: "pcb_placement_error"
pcb_placement_error_id: string
error_type: "pcb_placement_error"
message: string
subcircuit_id?: string
}
PcbPlatedHole
Source
Defines a circular plated hole on the PCB
interface PcbPlatedHoleCircle {
type: "pcb_plated_hole"
shape: "circle"
pcb_group_id?: string
subcircuit_id?: string
outer_diameter: number
hole_diameter: number
is_covered_with_solder_mask?: boolean
x: Distance
y: Distance
layers: LayerRef[]
port_hints?: string[]
pcb_component_id?: string
pcb_port_id?: string
pcb_plated_hole_id: string
soldermask_margin?: number
}
interface PcbHolePillWithRectPad {
type: "pcb_plated_hole"
shape: "pill_hole_with_rect_pad"
pcb_group_id?: string
subcircuit_id?: string
hole_shape: "pill"
pad_shape: "rect"
hole_width: number
hole_height: number
rect_pad_width: number
rect_pad_height: number
rect_border_radius?: number
hole_offset_x: Distance
hole_offset_y: Distance
is_covered_with_solder_mask?: boolean
x: Distance
y: Distance
layers: LayerRef[]
port_hints?: string[]
pcb_component_id?: string
pcb_port_id?: string
pcb_plated_hole_id: string
soldermask_margin?: number
}
interface PcbHoleRotatedPillWithRectPad {
type: "pcb_plated_hole"
shape: "rotated_pill_hole_with_rect_pad"
pcb_group_id?: string
subcircuit_id?: string
hole_shape: "rotated_pill"
pad_shape: "rect"
hole_width: number
hole_height: number
hole_ccw_rotation: Rotation
rect_pad_width: number
rect_pad_height: number
rect_border_radius?: number
rect_ccw_rotation: Rotation
hole_offset_x: Distance
hole_offset_y: Distance
is_covered_with_solder_mask?: boolean
x: Distance
y: Distance
layers: LayerRef[]
port_hints?: string[]
pcb_component_id?: string
pcb_port_id?: string
pcb_plated_hole_id: string
soldermask_margin?: number
}
interface PcbHoleCircularWithRectPad {
type: "pcb_plated_hole"
shape: "circular_hole_with_rect_pad"
pcb_group_id?: string
subcircuit_id?: string
hole_shape: "circle"
pad_shape: "rect"
hole_diameter: number
rect_pad_width: number
rect_pad_height: number
rect_border_radius?: number
hole_offset_x: Distance
hole_offset_y: Distance
is_covered_with_solder_mask?: boolean
x: Distance
y: Distance
layers: LayerRef[]
port_hints?: string[]
pcb_component_id?: string
pcb_port_id?: string
pcb_plated_hole_id: string
soldermask_margin?: number
}
interface PcbHoleWithPolygonPad {
type: "pcb_plated_hole"
shape: "hole_with_polygon_pad"
pcb_group_id?: string
subcircuit_id?: string
hole_shape: "circle" | "oval" | "pill" | "rotated_pill"
hole_diameter?: number
hole_width?: number
hole_height?: number
pad_outline: { x: Distance; y: Distance }[]
hole_offset_x: Distance
hole_offset_y: Distance
is_covered_with_solder_mask?: boolean
x: Distance
y: Distance
layers: LayerRef[]
port_hints?: string[]
pcb_component_id?: string
pcb_port_id?: string
pcb_plated_hole_id: string
soldermask_margin?: number
}
PcbPort
Source
Defines a port on the PCB
interface PcbPort {
type: "pcb_port"
pcb_port_id: string
pcb_group_id?: string
subcircuit_id?: string
source_port_id: string
pcb_component_id?: string
x: Distance
y: Distance
layers: LayerRef[]
is_board_pinout?: boolean
}
PcbPortNotConnectedError
Source
Defines an error when a pcb port is not connected to any trace
interface PcbPortNotConnectedError {
type: "pcb_port_not_connected_error"
pcb_port_not_connected_error_id: string
error_type: "pcb_port_not_connected_error"
message: string
pcb_port_ids: string[]
pcb_component_ids: string[]
subcircuit_id?: string
}
PcbPortNotMatchedError
Source
Defines a trace error on the PCB where a port is not matched
interface PcbPortNotMatchedError {
type: "pcb_port_not_matched_error"
pcb_error_id: string
error_type: "pcb_port_not_matched_error"
message: string
pcb_component_ids: string[]
subcircuit_id?: string
}
PcbRouteHints
Source
type PcbRouteHints = PcbRouteHint[]
interface PcbRouteHint {
x: number
y: number
via?: boolean
via_to_layer?: LayerRef
}
PcbSilkscreenCircle
Source
Defines a silkscreen circle on the PCB
interface PcbSilkscreenCircle {
type: "pcb_silkscreen_circle"
pcb_silkscreen_circle_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
center: Point
radius: Length
layer: VisibleLayer
stroke_width: Length
}
PcbSilkscreenLine
Source
Defines a silkscreen line on the PCB
interface PcbSilkscreenLine {
type: "pcb_silkscreen_line"
pcb_silkscreen_line_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
stroke_width: Distance
x1: Distance
y1: Distance
x2: Distance
y2: Distance
layer: VisibleLayer
}
PcbSilkscreenOval
Source
Defines a silkscreen oval on the PCB
interface PcbSilkscreenOval {
type: "pcb_silkscreen_oval"
pcb_silkscreen_oval_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
center: Point
radius_x: Distance
radius_y: Distance
layer: VisibleLayer
}
PcbSilkscreenPath
Source
Defines a silkscreen path on the PCB
interface PcbSilkscreenPath {
type: "pcb_silkscreen_path"
pcb_silkscreen_path_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
layer: VisibleLayerRef
route: Point[]
stroke_width: Length
}
PcbSilkscreenPill
Source
Defines a silkscreen pill on the PCB
interface PcbSilkscreenPill {
type: "pcb_silkscreen_pill"
pcb_silkscreen_pill_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
center: Point
width: Length
height: Length
layer: LayerRef
}
PcbSilkscreenRect
Source
Defines a silkscreen rect on the PCB
interface PcbSilkscreenRect {
type: "pcb_silkscreen_rect"
pcb_silkscreen_rect_id: string
pcb_component_id: string
pcb_group_id?: string
subcircuit_id?: string
center: Point
width: Length
height: Length
layer: LayerRef
stroke_width: Length
corner_radius?: Length
is_filled?: boolean
has_stroke?: boolean
is_stroke_dashed?: boolean
}
PcbSilkscreenText
Source
Defines silkscreen text on the PCB
interface PcbSilkscreenText {
type: "pcb_silkscreen_text"
pcb_silkscreen_text_id: string
pcb_group_id?: string
subcircuit_id?: string
font: "tscircuit2024"
font_size: Length
pcb_component_id: string
text: string
is_knockout?: boolean
knockout_padding?: {
left: Length
top: Length
bottom: Length
right: Length
}
ccw_rotation?: number
layer: LayerRef
is_mirrored_from_top_view?: boolean
anchor_position: Point
anchor_alignment: NinePointAnchor
}
PcbSolderPaste
Source
Defines solderpaste on the PCB
interface PcbSolderPasteCircle {
type: "pcb_solder_paste"
shape: "circle"
pcb_solder_paste_id: string
pcb_group_id?: string
subcircuit_id?: string
x: Distance
y: Distance
radius: number
layer: LayerRef
pcb_component_id?: string
pcb_smtpad_id?: string
}
Source
Warning emitted when a supplier part footprint does not match the expected footprint
interface SupplierFootprintMismatchWarning {
type: "supplier_footprint_mismatch_warning"
supplier_footprint_mismatch_warning_id: string
warning_type: "supplier_footprint_mismatch_warning"
message: string
source_component_id: string
pcb_component_id?: string
pcb_group_id?: string
subcircuit_id?: string
supplier_name?: SupplierName
supplier_part_number?: string
supplier_footprint_url?: string
footprint_copper_intersection_over_union: number
}
PcbText
Source
Defines text on the PCB
interface PcbText {
type: "pcb_text"
pcb_text_id: string
pcb_group_id?: string
subcircuit_id?: string
text: string
center: Point
layer: LayerRef
width: Length
height: Length
lines: number
align: "bottom-left"
}
PcbThermalSpoke
Source
Pattern for connecting a ground plane to a plated hole
interface PcbThermalSpoke {
type: "pcb_thermal_spoke"
pcb_thermal_spoke_id: string
pcb_ground_plane_id: string
shape: string
spoke_count: number
spoke_thickness: Distance
spoke_inner_diameter: Distance
spoke_outer_diameter: Distance
pcb_plated_hole_id?: string
subcircuit_id?: string
}
PcbTrace
Source
interface PcbTraceRoutePointWire {
route_type: "wire"
x: Distance
y: Distance
width: Distance
start_pcb_port_id?: string
end_pcb_port_id?: string
layer: LayerRef
}
interface PcbTraceRoutePointThroughPad {
route_type: "through_pad"
start: Point
end: Point
width: Distance
start_layer: LayerRef
end_layer: LayerRef
pcb_smtpad_id?: string
pcb_plated_hole_id?: string
}
type PcbTraceRoutePoint =
| PcbTraceRoutePointWire
| PcbTraceRoutePointVia
| PcbTraceRoutePointThroughPad
PcbTraceWarning
Source
Warning emitted when a PCB trace has a warning condition
interface PcbTraceWarning {
type: "pcb_trace_warning"
pcb_trace_warning_id: string
warning_type: "pcb_trace_warning"
message: string
center?: Point
pcb_trace_id: string
source_trace_id: string
pcb_component_ids: string[]
pcb_port_ids: string[]
subcircuit_id?: string
}
PcbTraceError
Source
Defines a trace error on the PCB
interface PcbTraceError {
type: "pcb_trace_error"
pcb_trace_error_id: string
error_type: "pcb_trace_error"
message: string
center?: Point
pcb_trace_id: string
source_trace_id: string
pcb_component_ids: string[]
pcb_port_ids: string[]
subcircuit_id?: string
}
PcbTraceHint
Source
A hint that can be used during generation of a PCB trace.
interface PcbTraceHint {
type: "pcb_trace_hint"
pcb_trace_hint_id: string
pcb_port_id: string
pcb_component_id: string
route: RouteHintPoint[]
subcircuit_id?: string
}
PcbTraceMissingError
Source
Defines an error when a source trace has no corresponding PCB trace
interface PcbTraceMissingError {
type: "pcb_trace_missing_error"
pcb_trace_missing_error_id: string
error_type: "pcb_trace_missing_error"
message: string
center?: Point
source_trace_id: string
pcb_component_ids: string[]
pcb_port_ids: string[]
subcircuit_id?: string
}
PcbVia
Source
Defines a via on the PCB
interface PcbVia {
type: "pcb_via"
pcb_via_id: string
pcb_group_id?: string
subcircuit_id?: string
subcircuit_connectivity_map_key?: string
x: Distance
y: Distance
outer_diameter: Distance
hole_diameter: Distance
from_layer?: LayerRef
to_layer?: LayerRef
layers: LayerRef[]
pcb_trace_id?: string
net_is_assignable?: boolean
net_assigned?: boolean
is_tented?: boolean
}
PcbViaClearanceError
Source
Error emitted when vias are closer than the allowed clearance
interface PcbViaClearanceError {
type: "pcb_via_clearance_error"
pcb_error_id: string
error_type: "pcb_via_clearance_error"
message: string
pcb_via_ids: string[]
minimum_clearance?: Distance
actual_clearance?: Distance
pcb_center?: {
x?: number
y?: number
}
subcircuit_id?: string
}
Schematic Elements
SchematicArc
Source
Draws a styled arc on the schematic
interface SchematicArc {
type: "schematic_arc"
schematic_arc_id: string
schematic_component_id: string
center: Point
radius: number
start_angle_degrees: number
end_angle_degrees: number
direction: "clockwise" | "counterclockwise"
stroke_width?: number | null
color: string
is_dashed: boolean
subcircuit_id?: string
}
SchematicBox
Source
interface SchematicBox {
type: "schematic_box"
schematic_component_id?: string
width: number
height: number
is_dashed: boolean
x: number
y: number
subcircuit_id?: string
}
SchematicCircle
Source
Draws a styled circle on the schematic
interface SchematicCircle {
type: "schematic_circle"
schematic_circle_id: string
schematic_component_id: string
center: Point
radius: number
stroke_width?: number | null
color: string
is_filled: boolean
fill_color?: string
is_dashed: boolean
subcircuit_id?: string
}
SchematicComponent
Source
interface SchematicComponent {
type: "schematic_component"
size: Size
center: Point
source_component_id?: string
schematic_component_id: string
pin_spacing?: number
pin_styles?: Record<
string,
{
left_margin?: number
right_margin?: number
top_margin?: number
bottom_margin?: number
}
>
box_width?: number
symbol_name?: string
port_arrangement?: SchematicPortArrangement
port_labels?: Record<string, string>
symbol_display_value?: string
subcircuit_id?: string
schematic_group_id?: string
is_schematic_group?: boolean
source_group_id?: string
is_box_with_pins: boolean
}
interface SchematicPortArrangementBySize {
left_size: number
right_size: number
top_size?: number
bottom_size?: number
}
interface SchematicPortArrangementBySides {
left_side?: { pins: number[]; direction?: "top-to-bottom" | "bottom-to-top" }
right_side?: { pins: number[]; direction?: "top-to-bottom" | "bottom-to-top" }
top_side?: { pins: number[]; direction?: "left-to-right" | "right-to-left" }
bottom_side?: {
pins: number[]
direction?: "left-to-right" | "right-to-left"
}
}
type SchematicPortArrangement =
| SchematicPortArrangementBySize
| SchematicPortArrangementBySides
SchematicDebugObject
Source
type SchematicDebugObject =
| SchematicDebugRect
| SchematicDebugLine
| SchematicDebugPoint
interface SchematicDebugRect {
type: "schematic_debug_object"
label?: string
shape: "rect"
center: Point
size: Size
subcircuit_id?: string
}
interface SchematicDebugLine {
type: "schematic_debug_object"
label?: string
shape: "line"
start: Point
end: Point
subcircuit_id?: string
}
interface SchematicDebugPoint {
type: "schematic_debug_object"
label?: string
shape: "point"
center: Point
subcircuit_id?: string
}
SchematicError
Source
interface SchematicError {
type: "schematic_error"
schematic_error_id: string
error_type: "schematic_port_not_found"
message: string
subcircuit_id?: string
}
SchematicGroup
Source
Defines a group of components on the schematic
interface SchematicGroup {
type: "schematic_group"
schematic_group_id: string
source_group_id: string
is_subcircuit?: boolean
subcircuit_id?: string
width: Length
height: Length
center: Point
schematic_component_ids: string[]
show_as_schematic_box?: boolean
name?: string
description?: string
}
SchematicLayoutError
Source
interface SchematicLayoutError {
type: "schematic_layout_error"
schematic_layout_error_id: string
error_type: "schematic_layout_error"
message: string
source_group_id: string
schematic_group_id: string
subcircuit_id?: string
}
SchematicLine
Source
Draws a styled line on the schematic
interface SchematicLine {
type: "schematic_line"
schematic_line_id: string
schematic_component_id: string
x1: number
y1: number
x2: number
y2: number
stroke_width?: number | null
color: string
is_dashed: boolean
subcircuit_id?: string
}
SchematicManualEditConflictWarning
Source
Warning emitted when a component has both manual placement (via manualEdits) and explicit schX/schY coordinates
interface SchematicManualEditConflictWarning {
type: "schematic_manual_edit_conflict_warning"
schematic_manual_edit_conflict_warning_id: string
warning_type: "schematic_manual_edit_conflict_warning"
message: string
schematic_component_id: string
schematic_group_id?: string
subcircuit_id?: string
source_component_id: string
}
SchematicNetLabel
Source
interface SchematicNetLabel {
type: "schematic_net_label"
schematic_net_label_id: string
schematic_trace_id?: string
source_trace_id?: string
source_net_id: string
center: Point
anchor_position?: Point | undefined
anchor_side: "top" | "bottom" | "left" | "right"
text: string
symbol_name?: string | undefined
is_movable?: boolean
subcircuit_id?: string
}
SchematicPath
Source
interface SchematicPath {
type: "schematic_path"
schematic_component_id: string
fill_color?: "red" | "blue"
is_filled?: boolean
points: Point[]
subcircuit_id?: string
}
SchematicPort
Source
interface SchematicPort {
type: "schematic_port"
schematic_port_id: string
source_port_id: string
schematic_component_id?: string
center: Point
facing_direction?: "up" | "down" | "left" | "right"
distance_from_component_edge?: number
side_of_component?: "top" | "bottom" | "left" | "right"
true_ccw_index?: number
pin_number?: number
display_pin_label?: string
subcircuit_id?: string
is_connected?: boolean
has_input_arrow?: boolean
has_output_arrow?: boolean
}
SchematicRect
Source
Draws a styled rectangle on the schematic
interface SchematicRect {
type: "schematic_rect"
schematic_rect_id: string
schematic_component_id: string
center: Point
width: number
height: number
rotation: number
stroke_width?: number | null
color: string
is_filled: boolean
fill_color?: string
is_dashed: boolean
subcircuit_id?: string
}
SchematicSheet
Source
Defines a schematic sheet or page that components can be placed on.
interface SchematicSheet {
type: "schematic_sheet"
schematic_sheet_id: string
name?: string
subcircuit_id?: string
}
SchematicTable
Source
Defines a table on the schematic, useful for displaying data in a structured format.
interface SchematicTable {
type: "schematic_table"
schematic_table_id: string
anchor_position: Point
column_widths: Length[]
row_heights: Length[]
cell_padding?: Length
border_width?: Length
subcircuit_id?: string
schematic_component_id?: string
anchor?: NinePointAnchor
}
SchematicTableCell
Source
Defines a cell within a schematic_table
interface SchematicTableCell {
type: "schematic_table_cell"
schematic_table_cell_id: string
schematic_table_id: string
start_row_index: number
end_row_index: number
start_column_index: number
end_column_index: number
text?: string
center: Point
width: Length
height: Length
horizontal_align?: "left" | "center" | "right"
vertical_align?: "top" | "middle" | "bottom"
font_size?: Length
subcircuit_id?: string
}
SchematicText
Source
interface SchematicText {
type: "schematic_text"
schematic_component_id?: string
schematic_text_id: string
text: string
font_size: number
position: {
x: number
y: number
}
rotation: number
anchor: NinePointAnchor | FivePointAnchor
color: string
subcircuit_id?: string
}
SchematicTrace
Source
interface SchematicTraceEdge {
from: {
x: number
y: number
}
to: {
x: number
y: number
}
is_crossing?: boolean
from_schematic_port_id?: string
to_schematic_port_id?: string
}
SchematicVoltageProbe
Source
interface SchematicVoltageProbe {
type: "schematic_voltage_probe"
schematic_voltage_probe_id: string
source_component_id?: string
name?: string
position: Point
schematic_trace_id: string
voltage?: number
subcircuit_id?: string
color?: string
label_alignment?: NinePointAnchor
}
Simulation Elements
SimulationExperiment
Source
interface SimulationExperiment {
type: "simulation_experiment"
simulation_experiment_id: string
name: string
experiment_type: ExperimentType
time_per_step?: number
start_time_ms?: number
end_time_ms?: number
}
SimulationSwitch
Source
interface SimulationSwitch {
type: "simulation_switch"
simulation_switch_id: string
source_component_id?: string
closes_at?: number
opens_at?: number
starts_closed?: boolean
switching_frequency?: number
}
SimulationTransientVoltageGraph
Source
interface SimulationTransientVoltageGraph {
type: "simulation_transient_voltage_graph"
simulation_transient_voltage_graph_id: string
simulation_experiment_id: string
timestamps_ms?: number[]
voltage_levels: number[]
source_component_id?: string
subcircuit_connectivity_map_key?: string
time_per_step: number
start_time_ms: number
end_time_ms: number
name?: string
color?: string
}
SimulationUnknownExperimentError
Source
An unknown error occurred during the simulation experiment.
interface SimulationUnknownExperimentError {
type: "simulation_unknown_experiment_error"
simulation_unknown_experiment_error_id: string
error_type: "simulation_unknown_experiment_error"
message: string
simulation_experiment_id?: string
subcircuit_id?: string
}
SimulationVoltageProbe
Source
interface SimulationVoltageProbe {
type: "simulation_voltage_probe"
simulation_voltage_probe_id: string
source_component_id?: string
name?: string
signal_input_source_port_id?: string
signal_input_source_net_id?: string
reference_input_source_port_id?: string
reference_input_source_net_id?: string
subcircuit_id?: string
color?: string
}
SimulationVoltageSource
Source
type SimulationVoltageSource =
| SimulationDcVoltageSource
| SimulationAcVoltageSource
interface SimulationDcVoltageSource {
type: "simulation_voltage_source"
simulation_voltage_source_id: string
is_dc_source: true
positive_source_port_id?: string
positive_source_net_id?: string
negative_source_port_id?: string
negative_source_net_id?: string
voltage: number
}
interface SimulationAcVoltageSource {
type: "simulation_voltage_source"
simulation_voltage_source_id: string
is_dc_source: false
terminal1_source_port_id?: string
terminal2_source_port_id?: string
terminal1_source_net_id?: string
terminal2_source_net_id?: string
voltage?: number
frequency?: number
peak_to_peak_voltage?: number
wave_shape?: WaveShape
phase?: number
duty_cycle?: number
}