> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/reference/protopart-schema.md). # ProtoPart Schema Complete field-level reference for ProtoPart JSON definitions, the schema that powers every part in Protoboard. {% hint style="info" %} **Schema version covered:** `1.4.0`\ **Source file:** [`contribution/protopart-schema.json`](https://github.com/Delta-Robotics-Inc/ProtoPart/blob/main/contribution/protopart-schema.json) in the ProtoPart repository (open source). {% endhint %} 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: | Key | Required | Description | | -------------- | --------------- | ------------------------------------------------------------------------------------------ | | `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. | ```json { "id": "KlggTcbDH4jaRhmCIU0c", "definition": { "metadata": { ... }, "domains": [ ... ], "design_rules": [ ... ], "usage_notes": "...", "warnings": [ ... ], "purchaseInfo": { ... } }, "purchaseInfo": { ... } } ``` {% hint style="warning" %} The `purchaseInfo` field can appear at the top level **or** inside `definition`. Both locations are valid. When both exist, the top-level value takes precedence in the app. {% endhint %} *** ## Metadata The `metadata` object identifies the part and controls how it appears in search, the library, and version tracking. | Field | Type | Required | Description | | ---------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `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. |
Example metadata block ```json "metadata": { "id": "adafruit-bme280", "name": "BME280 Environmental Sensor Breakout", "type": "sensor", "taxonomy": ["sensor.environmental", "expansion.breakout"], "description": "Bosch BME280 sensor breakout for temperature, humidity, and barometric pressure.", "manufacturer": "Adafruit", "part_number": "2652", "datasheet_url": "https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme280-ds002.pdf", "tags": ["sensor", "environmental", "temperature", "humidity", "pressure", "I2C", "SPI"], "schema_version": "1.4.0", "version": "1.0" } ```
*** ## 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: | Key | Required | Description | | ------------ | -------- | ----------------------------------------------- | | `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. | {% tabs %} {% tab title="electrical" %} **Domain string:** `"electrical"` The most common domain. Models pins, power rails, signals, and communication buses. **Additional domain-level fields:** | Field | Type | Description | | ---------------------- | --------------- | -------------------------------------------------------------------------------------- | | `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. | | {% endtab %} | | | {% tab title="mechanical" %} **Domain string:** `"mechanical"` Models physical form factor, mounting, and structural connections. **Additional domain-level fields:** | Field | Type | Description | | --------------- | ------------------------- | ----------------------------------------------------------------------------------- | | `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. | | {% endtab %} | | | {% tab title="thermal" %} **Domain string:** `"thermal"` Models heat generation and dissipation. **Additional domain-level fields:** | Field | Type | Description | | ------------------------- | ------------ | ------------------------------------------------------------------------------- | | `operating_temperature_C` | `[min, max]` | Operating temperature range in Celsius. | | `metadata` | `object` | `thermal_design_power_W`, `requires_thermal_management`, `cooling_method`, etc. | | {% endtab %} | | | {% tab title="pneumatic" %} **Domain string:** `"pneumatic"` Models compressed-air systems, valves, and actuators. **Additional domain-level fields:** | Field | Type | Description | | ---------- | -------- | ------------------------------------------------------------------------------------------- | | `metadata` | `object` | `standard_pressure_bar`, `working_medium`, `air_quality_class`, `compressor_required`, etc. | Uses `fluidResource` and `fluidInterface` definitions (shared with hydraulic). {% endtab %} {% tab title="hydraulic" %} **Domain string:** `"hydraulic"` Models hydraulic systems, pumps, and cylinders. **Additional domain-level fields:** | Field | Type | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------- | | `metadata` | `object` | `hydraulic_fluid_type`, `system_pressure_bar`, `reservoir_capacity_l`, `pump_type`, etc. | Uses `fluidResource` and `fluidInterface` definitions (shared with pneumatic). {% endtab %} {% tab title="network" %} **Domain string:** `"network"` Models high-level networking: Ethernet switches, WiFi access points, Bluetooth devices. **Additional domain-level fields:** | Field | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `metadata` | `object` | `network_protocols`, `max_bandwidth_mbps`, `network_topology`, `supports_poe`, `wireless_standards`, `security_protocols`, etc. | | {% endtab %} | | | | {% endtabs %} | | | *** ## 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. {% hint style="danger" %} **One resource = one allocatable unit.** Do not combine multiple wires or pins into a single resource. Each function that needs separate allocation must live on its own resource. For example, I2C requires two resources: one for SDA and one for SCL. {% endhint %} ### Electrical Resource Fields | Field | Type | Required | Description | | --------------------------- | --------------------- | -------- | --------------------------------------------------------------------- | | `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 | Field | Type | Required | Description | | ---------------- | ------------ | -------- | ------------------------------------------------------------------------------------------ | | `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) | Field | Type | Required | Description | | ---------------------- | ------------ | -------- | --------------------------------------------------------------------------------- | | `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 | Field | Type | Required | Description | | --------------------- | ------------ | -------- | --------------------------------------------------------------------------- | | `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. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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: ```json { "id": "d3", "functions": [ { "name": "digital_io" }, { "name": "pwm_output" }, { "name": "interrupt" } ] } ``` 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: {% columns %} {% column %} **On resource functions** Controls which functions within the **same resource** can be allocated at the same time. ```json { "id": "rj45_port_1", "functions": [ { "name": "ethernet_port", "shareable_with": ["poe_power_source"] }, { "name": "poe_power_source", "shareable_with": ["ethernet_port"] } ] } ``` Both functions live on one physical RJ45 jack and can be active simultaneously (PoE). {% endcolumn %} {% column %} **On interface `requires` entries** Controls which interface functions can be mapped to the **same physical resource**. ```json "requires": [ { "function": "ethernet_port", "count": 1, "shareable_with": ["poe_power_source"] }, { "function": "poe_power_source", "count": 1, "shareable_with": ["ethernet_port"] } ] ``` Use `"all"` as shorthand to allow sharing with every other function in the interface. {% endcolumn %} {% endcolumns %} *** ## 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. {% hint style="info" %} **1 interface = 1 connection.** An interface goes between exactly two devices. If a connector carries multiple signals that always travel together (like an RJ45 jack), that is one interface. If pins could reasonably be separated, split them into separate interfaces. {% endhint %} ### Common Interface Fields (All Domains) | Field | Type | Required | Description | | --------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `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. ```json "protocol": { "type": "i2c", "role": "master" } ``` | Field | Type | Description | | ------ | ---------------------- | ------------------------------------------------------------------------ | | `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](/reference/interfaces-and-harnesses.md) for the full compatibility table. ### The Requires Array Each entry declares a function the interface needs and how many instances: ```json "requires": [ { "function": "i2c_sda", "count": 1 }, { "function": "i2c_scl", "count": 1 } ] ``` 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 | Field | Type | Description | | ---------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------- | | `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 | Field | Type | Description | | ---------------------------- | -------- | ----------------------------------------------------- | | `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 | Field | Type | Description | | ------------------------ | -------- | ------------------------------------------------------------ | | `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. | Field | Type | Required | Description | | ------------------- | ------------ | -------- | ---------------------------------------------------- | | `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.
Example: Arduino Nano power domains ```json "power_domains": [ { "id": "vin", "name": "VIN (Raw Input)", "nominal_voltage_V": 9, "voltage_range_V": [7, 12], "max_current_mA": 500, "regulation_type": "unregulated", "isolation_type": "non_isolated", "ground_reference": "common" }, { "id": "usb_5v", "name": "USB 5V", "nominal_voltage_V": 5, "voltage_range_V": [4.5, 5.5], "max_current_mA": 500, "regulation_type": "regulated", "isolation_type": "non_isolated", "ground_reference": "common" }, { "id": "regulated_5v", "name": "Regulated 5V", "nominal_voltage_V": 5, "voltage_range_V": [4.8, 5.2], "max_current_mA": 800, "regulation_type": "regulated", "isolation_type": "non_isolated", "ground_reference": "common", "compatible_domains": ["usb_5v"] }, { "id": "regulated_3v3", "name": "Regulated 3.3V", "nominal_voltage_V": 3.3, "voltage_range_V": [3.1, 3.5], "max_current_mA": 150, "regulation_type": "regulated", "isolation_type": "non_isolated", "ground_reference": "common", "compatible_domains": ["regulated_5v"] } ] ```
*** ## Purchase Info A single object or an array of vendor entries. Used by the app's shared sourcing system. | Field | Type | Required | Description | | ------------------------ | -------------------- | -------- | -------------------------------------------------------- | | `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. | Field | Type | Default | Description | | ---------------------------- | -------------------- | ------------------- | ----------------------------------------------------------------------------------------- | | `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`. | Field | Type | Description | | ---------------------- | --------------------- | --------------------------------------------------------------------------- | | `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. | Field | Type | Required | Description | | ------------- | ---------- | -------- | ------------------------------------------------------------- | | `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 {% tabs %} {% tab title="Simple Sensor (BME280)" %}
Full BME280 definition JSON (click to expand) ```json { "id": "KlggTcbDH4jaRhmCIU0c", "definition": { "metadata": { "id": "adafruit-bme280", "name": "BME280 Environmental Sensor Breakout", "type": "sensor", "taxonomy": ["sensor.environmental", "expansion.breakout"], "description": "Bosch BME280 sensor breakout for temperature, humidity, and barometric pressure. Supports I2C and SPI. Onboard 3.3V regulator and level shifting allow 3-5V supply and logic compatibility.", "manufacturer": "Adafruit", "part_number": "2652", "datasheet_url": "https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme280-ds002.pdf", "tags": ["sensor", "environmental", "temperature", "humidity", "pressure", "I2C", "SPI"], "schema_version": "1.4.0", "version": "1.0" }, "domains": [ { "domain": "electrical", "power_domains": [ { "id": "vin", "name": "Vin (Input)", "nominal_voltage_V": 5, "voltage_range_V": [3, 5.5], "max_current_mA": 150, "isolation_type": "non_isolated", "ground_reference": "common" }, { "id": "3v3", "name": "Regulated 3.3V", "nominal_voltage_V": 3.3, "voltage_range_V": [3.2, 3.4], "max_current_mA": 100, "isolation_type": "non_isolated", "ground_reference": "common" } ], "resources": [ { "id": "vin_pin", "functions": [{ "name": "power_input" }], "power_domain_id": "vin", "description": "Vin power input pin (3-5V)" }, { "id": "3v3_out", "functions": [{ "name": "power_output" }], "power_domain_id": "3v3", "description": "3.3V regulated output" }, { "id": "gnd", "functions": [{ "name": "ground" }], "power_domain_id": "vin" }, { "id": "sck", "functions": [ { "name": "i2c_scl" }, { "name": "spi_sck" } ], "power_domain_id": "vin", "description": "Clock pin -- I2C SCL or SPI SCK" }, { "id": "sdi", "functions": [ { "name": "i2c_sda" }, { "name": "spi_mosi" } ], "power_domain_id": "vin", "description": "Data pin -- I2C SDA or SPI MOSI" }, { "id": "sdo", "functions": [{ "name": "spi_miso" }], "power_domain_id": "vin" }, { "id": "cs", "functions": [{ "name": "spi_ss" }], "power_domain_id": "vin" } ], "interfaces": [ { "id": "power_input", "name": "Power Input", "protocol": { "type": "power", "role": "input" }, "requires": [ { "function": "power_input", "count": 1 }, { "function": "ground", "count": 1 } ], "max_instances": 1 }, { "id": "i2c_slave", "name": "I2C Slave", "protocol": { "type": "i2c", "role": "slave" }, "requires": [ { "function": "i2c_sda", "count": 1 }, { "function": "i2c_scl", "count": 1 } ], "constraints": { "requires_matching_voltage_domain": true } }, { "id": "spi_slave", "name": "SPI Slave", "protocol": { "type": "spi", "role": "slave" }, "requires": [ { "function": "spi_mosi", "count": 1 }, { "function": "spi_miso", "count": 1 }, { "function": "spi_sck", "count": 1 }, { "function": "spi_ss", "count": 1 } ], "constraints": { "requires_matching_voltage_domain": true } } ], "supply_voltage_V": [3, 5.5], "power_consumption_mW": 3, "pin_count": 8 }, { "domain": "mechanical", "resources": [ { "id": "mount_hole_1", "functions": [{ "name": "mounting_hole" }], "connector_type": "through_hole" }, { "id": "mount_hole_2", "functions": [{ "name": "mounting_hole" }], "connector_type": "through_hole" } ], "interfaces": [ { "id": "module_mount", "name": "PCB Mounting", "protocol": { "type": "threaded_connection", "role": "mounting_point" }, "requires": [{ "function": "mounting_hole", "count": 2 }] } ], "dimensions_mm": { "length": 25.2, "width": 18, "height": 4.6 }, "weight_g": 3 }, { "domain": "thermal", "resources": [], "interfaces": [], "operating_temperature_C": [-40, 85] } ], "design_rules": [ "Use either I2C or SPI at a time -- do not connect both protocols simultaneously.", "Do not exceed 5.5V on the Vin pin." ], "warnings": [ "Avoid placing the sensor near heat sources -- self-heating affects temperature readings.", "Do not draw more than 100 mA from the 3Vo pin." ] }, "purchaseInfo": { "vendor": "amazon", "link": "https://amzn.to/4qAiWpH", "isAffiliate": true, "currentPriceUSD": "14.95", "availabilityStatus": "in_stock" } } ```
{% endtab %} {% tab title="Complex MCU (Arduino Nano)" %}
Abbreviated Arduino Nano definition (click to expand) ```json { "id": "73BRJWDJoU8QYE5y5IBA", "definition": { "metadata": { "id": "arduino-nano", "name": "Arduino Nano", "type": "microcontroller", "taxonomy": ["microcontroller.arduino"], "description": "Compact ATmega328P board with USB, ideal for embedded projects.", "manufacturer": "Arduino", "part_number": "A000005", "schema_version": "1.4.0", "version": "1.0" }, "domains": [ { "domain": "electrical", "power_domains": [ { "id": "vin", "name": "VIN (Raw Input)", "nominal_voltage_V": 9, "voltage_range_V": [7, 12], "max_current_mA": 500 }, { "id": "usb_5v", "name": "USB 5V", "nominal_voltage_V": 5, "voltage_range_V": [4.5, 5.5], "max_current_mA": 500 }, { "id": "regulated_5v", "name": "Regulated 5V", "nominal_voltage_V": 5, "voltage_range_V": [4.8, 5.2], "max_current_mA": 800 }, { "id": "regulated_3v3", "name": "Regulated 3.3V", "nominal_voltage_V": 3.3, "voltage_range_V": [3.1, 3.5], "max_current_mA": 150 } ], "resources": [ { "id": "vin", "functions": [{ "name": "power_input" }], "power_domain_id": "vin" }, { "id": "5v_out", "functions": [{ "name": "power_output" }], "power_domain_id": "regulated_5v" }, { "id": "3v3_out", "functions": [{ "name": "power_output" }], "power_domain_id": "regulated_3v3" }, { "id": "gnd1", "functions": [{ "name": "ground" }], "power_domain_id": "regulated_5v" }, { "id": "gnd2", "functions": [{ "name": "ground" }], "power_domain_id": "regulated_3v3" }, { "id": "d0", "power_domain_id": "digital_io", "functions": [{ "name": "digital_io" }, { "name": "uart_rx" }], "description": "Digital pin 0 / UART RX" }, { "id": "d1", "power_domain_id": "digital_io", "functions": [{ "name": "digital_io" }, { "name": "uart_tx" }], "description": "Digital pin 1 / UART TX" }, { "id": "d3", "power_domain_id": "digital_io", "functions": [{ "name": "digital_io" }, { "name": "pwm" }, { "name": "interrupt" }], "description": "Digital pin 3 / PWM / Interrupt" }, { "id": "a4", "power_domain_id": "analog_ref", "functions": [{ "name": "analog_input" }, { "name": "digital_io" }, { "name": "i2c_sda" }], "description": "Analog A4 / I2C SDA" }, { "id": "a5", "power_domain_id": "analog_ref", "functions": [{ "name": "analog_input" }, { "name": "digital_io" }, { "name": "i2c_scl" }], "description": "Analog A5 / I2C SCL" } ], "interfaces": [ { "id": "power_input", "protocol": { "type": "power", "role": "input" }, "requires": [{ "function": "power_input", "count": 1 }, { "function": "ground", "count": 1 }] }, { "id": "power_output", "name": "Power Output", "protocol": { "type": "power", "role": "output" }, "requires": [{ "function": "power_output", "count": 1 }, { "function": "ground", "count": 1 }], "constraints": { "max_connections": 10 } }, { "id": "i2c_master", "name": "I2C Master", "protocol": { "type": "i2c", "role": "master" }, "requires": [{ "function": "i2c_sda", "count": 1 }, { "function": "i2c_scl", "count": 1 }], "constraints": { "max_connections": 8, "requires_matching_voltage_domain": true } }, { "id": "spi_master", "name": "SPI Master", "protocol": { "type": "spi", "role": "master" }, "requires": [ { "function": "spi_mosi", "count": 1 }, { "function": "spi_miso", "count": 1 }, { "function": "spi_sck", "count": 1 }, { "function": "spi_ss", "count": 1 } ], "constraints": { "max_connections": 8 } }, { "id": "digital_output", "name": "Digital Output", "protocol": { "type": "digital", "role": "transmitter" }, "requires": [{ "function": "digital_io", "count": 1 }], "constraints": { "max_connections": 1 } }, { "id": "analog_input", "name": "Analog Input", "protocol": { "type": "analog", "role": "receiver" }, "requires": [{ "function": "analog_input", "count": 1 }], "constraints": { "max_connections": 1 } } ], "supply_voltage_V": [7, 12], "power_consumption_mW": 500, "pin_count": 30 }, { "domain": "mechanical", "resources": [ { "id": "mount_hole_1", "functions": [{ "name": "mounting_hole" }], "connector_type": "through_hole" }, { "id": "mount_hole_2", "functions": [{ "name": "mounting_hole" }], "connector_type": "through_hole" }, { "id": "mount_hole_3", "functions": [{ "name": "mounting_hole" }], "connector_type": "through_hole" }, { "id": "mount_hole_4", "functions": [{ "name": "mounting_hole" }], "connector_type": "through_hole" } ], "interfaces": [ { "id": "pcb_mounting", "name": "PCB Mounting", "protocol": { "type": "threaded_connection", "role": "mounting_point" }, "requires": [{ "function": "mounting_hole", "count": 4 }] } ], "dimensions_mm": { "length": 45, "width": 18, "height": 7 }, "weight_g": 7 }, { "domain": "thermal", "resources": [], "interfaces": [], "operating_temperature_C": [-40, 85] } ], "design_rules": [ "Maximum 40mA per I/O pin", "Maximum 200mA total I/O current", "VIN must be 7-12V when using external power", "USB and VIN power sources are mutually exclusive" ], "warnings": [ "Do not exceed 40mA per I/O pin", "Do not reverse power supply polarity", "USB and external power should not be used simultaneously" ] }, "purchaseInfo": [ { "vendor": "amazon", "link": "https://amzn.to/45sjBQW", "isAffiliate": true, "currentPriceUSD": "24.99", "availabilityStatus": "in_stock" }, { "vendor": "digikey", "link": "https://www.digikey.com/en/products/detail/arduino/A000005/2638989", "isAffiliate": false, "currentPriceUSD": "25.70", "availabilityStatus": "in_stock" } ] } ```
{% endtab %} {% endtabs %} *** ## Blank Template Use this as a starting point for new definitions. Remove domains you do not need.
blank-def.json ```json { "metadata": { "id": "undefined-component", "name": "Undefined Component", "type": "custom", "schema_version": "1.4.0", "version": "1.0" }, "domains": [ { "domain": "electrical", "resources": [], "interfaces": [] }, { "domain": "mechanical", "resources": [], "interfaces": [] }, { "domain": "thermal", "resources": [], "interfaces": [] }, { "domain": "pneumatic", "resources": [], "interfaces": [] }, { "domain": "hydraulic", "resources": [], "interfaces": [] }, { "domain": "network", "resources": [], "interfaces": [] } ] } ```
*** ## Quick Lookup: Required vs Optional {% columns %} {% column %} **Always required** * `metadata.id` * `metadata.name` * `metadata.type` * `domains` (min 1) * Per domain: `domain`, `resources`, `interfaces` * Per resource: `id`, `functions` * Per interface: `id`, `protocol`, `requires` {% endcolumn %} {% column %} **Strongly recommended** * `metadata.schema_version` * `metadata.version` * `metadata.description` * `metadata.manufacturer` * `metadata.datasheet_url` * `power_domains` (electrical domain) * `design_rules` * `warnings` {% endcolumn %} {% endcolumns %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.protoboard.xyz/reference/protopart-schema.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.