ProtoPart Schema
Complete field-level reference for ProtoPart JSON definitions, the schema that powers every part in Protoboard.
A ProtoPart definition is a single JSON file that describes everything Protoboard needs to know about a hardware component: its electrical pins, mechanical dimensions, communication protocols, fluid connections, purchase links, and more. The validation engine reads these definitions to check compatibility, allocate resources, and run Design Rule Checks (DRC).
Top-Level Structure
Every ProtoPart file has three top-level keys:
id
Yes (generated)
Unique identifier assigned automatically when the part is imported.
definition
Yes
The full part definition object containing metadata, domains, and all optional fields.
purchaseInfo
No
One object or an array of objects with vendor and pricing data.
{
"id": "KlggTcbDH4jaRhmCIU0c",
"definition": {
"metadata": { ... },
"domains": [ ... ],
"design_rules": [ ... ],
"usage_notes": "...",
"warnings": [ ... ],
"purchaseInfo": { ... }
},
"purchaseInfo": { ... }
}Metadata
The metadata object identifies the part and controls how it appears in search, the library, and version tracking.
id
string
Yes
Unique kebab-case identifier. Pattern: ^[a-z0-9-]+$. Example: arduino-nano
name
string
Yes
Human-readable display name. Example: Arduino Nano
type
string
Yes
Primary category. Examples: microcontroller, sensor, actuator, custom
taxonomy
string[]
No
Dot-notation paths from the category taxonomy. Example: ["sensor.environmental", "expansion.breakout"]
categories
string[]
No
Legacy; use taxonomy instead.
description
string
No
Marketing-style description of the part's purpose and capabilities.
manufacturer
string
No
Manufacturer name.
part_number
string
No
Official manufacturer part number.
datasheet_url
string (URI)
No
Link to the datasheet.
tags
string[]
No
Searchable tags for discovery.
schema_version
string
No
Schema version this definition targets. Default: "1.4.0"
version
string
No
Part definition version in MAJOR.MINOR format. New parts start at 1.0. Legacy MAJOR.MINOR.PATCH values are accepted.
Domains
The domains array is required and must contain at least one domain object. Each domain scopes the part's capabilities to a single engineering discipline. Every domain object has three required keys:
domain
Yes
One of the six domain type strings (see below).
resources
Yes
Array of resource objects within this domain.
interfaces
Yes
Array of interface objects within this domain.
Domain string: "electrical"
The most common domain. Models pins, power rails, signals, and communication buses.
Additional domain-level fields:
power_domains
powerDomain[]
Named voltage rails with ranges, isolation, and ground references.
supply_voltage_V
[min, max]
Overall supply voltage range.
power_consumption_mW
number
Typical power draw.
pin_count
number
Total electrical pins.
metadata
object
Flags like supports_hot_plug, supports_usb, package_type, emc_compliance, etc.
Domain string: "mechanical"
Models physical form factor, mounting, and structural connections.
Additional domain-level fields:
package_type
string
E.g., "PCB Module", "DIP".
dimensions_mm
{length, width, height}
Physical dimensions.
weight_g
number
Weight in grams.
mount_holes
object[]
Array with location and diam_mm.
metadata
object
mounting_method, enclosure_type, assembly_time_min, field_serviceable, etc.
Domain string: "thermal"
Models heat generation and dissipation.
Additional domain-level fields:
operating_temperature_C
[min, max]
Operating temperature range in Celsius.
metadata
object
thermal_design_power_W, requires_thermal_management, cooling_method, etc.
Domain string: "pneumatic"
Models compressed-air systems, valves, and actuators.
Additional domain-level fields:
metadata
object
standard_pressure_bar, working_medium, air_quality_class, compressor_required, etc.
Uses fluidResource and fluidInterface definitions (shared with hydraulic).
Domain string: "hydraulic"
Models hydraulic systems, pumps, and cylinders.
Additional domain-level fields:
metadata
object
hydraulic_fluid_type, system_pressure_bar, reservoir_capacity_l, pump_type, etc.
Uses fluidResource and fluidInterface definitions (shared with pneumatic).
Domain string: "network"
Models high-level networking: Ethernet switches, WiFi access points, Bluetooth devices.
Additional domain-level fields:
metadata
object
network_protocols, max_bandwidth_mbps, network_topology, supports_poe, wireless_standards, security_protocols, etc.
Resource Groups
A resource group logically clusters related resources that share constraints. For example, all GPIO pins in a microcontroller bank may form a resource group with a shared current budget or a rule that only one pin in the group can be assigned to hardware I2C at a time.
Group-level rules apply collectively: if the group has a 200mA total current limit, the DRC evaluates the sum of all allocations in the group rather than checking each pin individually. Resource groups are optional; resources without a group are validated independently.
Resources
A resource represents one physical endpoint that can be independently allocated (a single pin, port, shaft, or mounting hole). Each resource belongs to exactly one domain.
Electrical Resource Fields
id
string
Yes
Unique identifier within the domain.
functions
function[]
Yes
What this resource can do (see Functions below).
name
string
No
Human-readable name.
description
string
No
What this resource is.
power_domain_id
string
No
Which power domain this resource belongs to.
connector_type
string
No
Physical connector type.
current_rating
object
No
Source/sink current limits with continuous, peak, and leakage values.
logic_levels
object
No
v_ih_min_V, v_il_max_V, v_oh_min_V, v_ol_max_V.
has_internal_pullup
boolean
No
Whether the pin has an internal pull-up.
has_internal_pulldown
boolean
No
Whether the pin has an internal pull-down.
recommended_pullup_res_kΩ
number
No
Recommended external pull-up value.
esd_protection_kV
number
No
ESD protection rating.
custom_fields
customPropertyDef[]
No
User-defined fields for part instances.
Mechanical Resource Fields
id
string
Yes
Unique identifier.
functions
function[]
Yes
E.g., mounting_hole, mechanical_drive.
connector_type
string
Yes
through_hole, surface_mount, threaded_hole, clip_connection, adhesive, custom.
Fluid Resource Fields (Pneumatic / Hydraulic)
id
string
Yes
Unique identifier.
functions
function[]
Yes
E.g., pressure_port, return_port, exhaust_port.
connector_type
string
Yes
threaded_port, quick_connect, flange, hose_barb, compression, custom.
working_pressure_bar
number
No
Normal working pressure.
max_pressure_bar
number
No
Maximum pressure rating.
flow_rate_l_per_min
number
No
Flow rate.
compatible_fluids
string[]
No
List of compatible fluid types.
port_size
string
No
E.g., "1/4", "M5", "6mm".
seal_type
string
No
E.g., "O-ring", "PTFE".
Network Resource Fields
id
string
Yes
Unique identifier.
functions
function[]
Yes
E.g., ethernet_port, wifi_antenna.
resource_type
string
Yes
physical_port, logical_port, ip_address, bandwidth_allocation, etc.
port_specifications
object
No
port_type, port_count, connector_type, speed_mbps, duplex_modes.
addressing
object
No
IPv4/IPv6 support, DHCP, VLAN.
qos_capabilities
object
No
Traffic shaping, priority queues.
Functions
Functions are the atomic capabilities a resource provides. They are how the allocation engine matches interface requirements to physical resources.
name
string
Yes
Canonical function name. Must match the protocol spec allowlist. Examples: power_input, ground, i2c_sda, spi_mosi, digital_io, pwm_output, mounting_hole, pressure_port.
description
string
No
What this function provides.
direction
string
No
"source", "sink", or "bidirectional".
shareable_with
string[]
No
Other function names within the same resource that can be allocated simultaneously. Empty array (default) means exclusive access.
priority
number
No
Higher = more important during allocation conflicts.
signal_class
string
No
Semantic classification: power, ground, clock, data, sense, mechanical_drive, fluid.
When to Use Multiple Functions on One Resource
Multiple functions on a single resource are valid only when they are mutually exclusive alternatives for the same physical pin:
Pin D3 can serve as a digital I/O or a PWM output or an interrupt input, but only one at a time. The allocation engine ensures only one interface claims the resource.
The shareable_with Field
shareable_with appears in two contexts with related but distinct meanings:
On resource functions
Controls which functions within the same resource can be allocated at the same time.
Both functions live on one physical RJ45 jack and can be active simultaneously (PoE).
On interface requires entries
Controls which interface functions can be mapped to the same physical resource.
Use "all" as shorthand to allow sharing with every other function in the interface.
Interfaces
An interface is a template for a single connection between two parts. It declares which protocol it speaks, what role it plays, and which resource functions it needs.
Common Interface Fields (All Domains)
id
string
Yes
Unique identifier within the domain.
protocol
object
Yes
Contains type and role (see below).
requires
array
Yes
Functions needed and their counts.
name
string
No
Display name.
description
string
No
What this interface does.
max_instances
number
No
Hard cap on how many instances the device supports. Only use when the hardware itself limits this beyond what resources allow.
constraints
object
No
Electrical: max_connections, requires_matching_voltage_domain, max_cable_length_m, etc.
custom_fields
customPropertyDef[]
No
Instance-level custom fields.
The Protocol Object
The protocol object is what drives compatibility matching between two parts.
type
string
The protocol name. Must match a type from the protocol spec allowlist.
role
string or string[]
Role in the protocol. Can be a single role or an array of allowed roles.
Two interfaces can connect when they share the same type and their role values form a compatible pair (e.g., master + slave, output + input). See Interfaces and Harnesses for the full compatibility table.
The Requires Array
Each entry declares a function the interface needs and how many instances:
The allocation engine searches for separate unallocated resources providing each required function. If count is greater than 1, it needs that many distinct resources with that function.
Electrical Interface Extras
power_delivery
object
max_voltage_V, max_current_mA, efficiency_percent, regulation_tolerance_percent, ripple_voltage_mV.
constraints.max_connections
number
How many other parts can connect to a single instance. E.g., I2C bus: 8.
constraints.requires_matching_voltage_domain
boolean
Whether connected parts must share a compatible voltage rail.
constraints.requires_impedance_matching
boolean
For high-speed links (USB, Ethernet).
Fluid Interface Extras
system_pressure_bar
number
Operating pressure.
system_flow_rate_l_per_min
number
Flow rate.
fluid_type
string
compressed_air, hydraulic_oil, water, custom.
control_method
string
manual, solenoid, pilot, proportional.
cv_flow_coefficient
number
Cv value for sizing.
Network Interface Extras
protocol.version
string
E.g., "IPv4", "HTTP/2", "MQTT 5.0".
connection_parameters
object
max_connections, connection_timeout_s, mtu_bytes, etc.
bandwidth_requirements
object
min_bandwidth_mbps, max_bandwidth_mbps.
security_requirements
object
encryption_required, authentication_required, etc.
Power Domains
Power domains are unique to the electrical domain and model distinct voltage rails. Think of them as named nets on a PCB.
id
string
Yes
Unique identifier.
name
string
Yes
Human-readable name.
nominal_voltage_V
number
Yes
Target voltage.
max_current_mA
number
Yes
Maximum current the rail can supply.
voltage_range_V
[min, max]
No
Acceptable voltage range.
isolation_type
string
No
isolated, non_isolated, galvanically_isolated.
ground_reference
string
No
common, isolated, floating.
Resources reference power domains via power_domain_id so the DRC can check voltage compatibility and isolation.
Purchase Info
A single object or an array of vendor entries. Used by the app's shared sourcing system.
vendor
string
Yes
Vendor name (e.g., "amazon", "digikey", "mouser").
link
string (URI)
Yes
Product page URL.
isAffiliate
boolean
Yes
Whether the link is an affiliate link.
vendorPartId
string
No
Vendor SKU or listing ID.
currentPriceUSD
string
No
Latest known price. Pattern: ^\d+(\.\d{2})?$.
packQuantity
integer
No
Units per purchase.
minimumOrderQuantity
integer
No
MOQ.
stockQuantityAvailable
integer
No
Known stock count.
availabilityStatus
string
No
in_stock, limited_stock, out_of_stock, unknown.
priceTimestamp
string (date-time)
No
When the price was last verified.
productStatus
string
No
active, out_of_stock, discontinued, unknown.
Node Geometry
Controls how the part's node looks on the Protoboard canvas.
xScale
number
1
Scale multiplier for polyline X coordinates (0.01 to 10000).
yScale
number
1
Scale multiplier for polyline Y coordinates (0.01 to 10000).
shape
string
rounded_rectangle
Legacy shape: rectangle, circle, rounded_rectangle.
outline.preset
string
rounded_rectangle
Preferred shape selector: rectangle, rounded_rectangle, circle, rounded_triangle.
outline.polyline
object
None
Custom outline with points array, optional bulges, and corner_radius_px.
outline.content_padding_px
number or {x, y}
None
Padding between outline stroke and label text.
Optional Top-Level Fields
These fields sit inside definition alongside metadata and domains.
design_rules
string[]
Part-specific rules for DRC validation. E.g., "Maximum 40mA per I/O pin".
usage_notes
string
Practical guidance and best practices.
application_examples
string[]
Real-world use cases.
compatibility_notes
string
Notes on what other parts this works with.
warnings
string[]
Safety and usage warnings.
custom_fields
customPropertyDef[]
Instance-level custom properties (see below).
Custom Fields
Custom fields let definition authors add part-specific properties that users can set per instance on the canvas.
key
string
Yes
Identifier. Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$.
type
string
Yes
string, number, boolean, enum.
label
string
No
Display label.
description
string
No
Help text.
default
varies
No
Default value (must match type).
required
boolean
No
Whether a value is mandatory. Default: false.
options
string[]
No
Choices for enum type.
min / max
number
No
Bounds for number type.
pattern
string
No
Regex for string validation.
ui_hints
object
No
control (textbox, select, etc.), group, order, width.
Complete Examples
Blank Template
Use this as a starting point for new definitions. Remove domains you do not need.
Quick Lookup: Required vs Optional
Always required
metadata.idmetadata.namemetadata.typedomains(min 1)Per domain:
domain,resources,interfacesPer resource:
id,functionsPer interface:
id,protocol,requires
Strongly recommended
metadata.schema_versionmetadata.versionmetadata.descriptionmetadata.manufacturermetadata.datasheet_urlpower_domains(electrical domain)design_ruleswarnings
Last updated