> 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. |

<details>

<summary>Example metadata block</summary>

```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"
}
```

</details>

***

## 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](https://docs.protoboard.xyz/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.

<details>

<summary>Example: Arduino Nano power domains</summary>

```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"]
  }
]
```

</details>

***

## 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)" %}

<details>

<summary>Full BME280 definition JSON (click to expand)</summary>

```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"
  }
}
```

</details>
{% endtab %}

{% tab title="Complex MCU (Arduino Nano)" %}

<details>

<summary>Abbreviated Arduino Nano definition (click to expand)</summary>

```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" }
  ]
}
```

</details>
{% endtab %}
{% endtabs %}

***

## Blank Template

Use this as a starting point for new definitions. Remove domains you do not need.

<details>

<summary>blank-def.json</summary>

```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": []
    }
  ]
}
```

</details>

***

## 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 %}
