{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://elementic.app/spec/device-definition/1.1/schema.json",
  "title": "Elementic AI Device Definition 1.1",
  "description": "Untrusted, source-backed draft input plus separately uploaded source artwork, sanitized 1000x1000 SVG and pin geometry for importing a hardware device into Elementic.",
  "type": "object",
  "required": [
    "$schema",
    "format",
    "format_version",
    "definition_id",
    "generated_at",
    "research",
    "device",
    "microcontrollers",
    "usb_identities",
    "artwork",
    "pins",
    "sources"
  ],
  "properties": {
    "$schema": {
      "const": "https://elementic.app/spec/device-definition/1.1/schema.json"
    },
    "format": {
      "const": "elementic-device-definition"
    },
    "format_version": {
      "const": "1.1"
    },
    "definition_id": {
      "$ref": "#/$defs/key"
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "research": {
      "$ref": "#/$defs/research"
    },
    "device": {
      "$ref": "#/$defs/device"
    },
    "microcontrollers": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/microcontroller"
      }
    },
    "usb_identities": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/usbIdentity"
      }
    },
    "pins": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/pin"
      }
    },
    "build_candidate": {
      "oneOf": [
        {
          "$ref": "#/$defs/buildCandidate"
        },
        {
          "type": "null"
        }
      ]
    },
    "sources": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/source"
      }
    },
    "artwork": {
      "$ref": "#/$defs/artwork"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "key": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9._-]{0,95}$"
    },
    "sourceRefs": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "$ref": "#/$defs/key"
      }
    },
    "nullableNonNegativeInteger": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "research": {
      "type": "object",
      "required": [
        "generator",
        "status",
        "assumptions",
        "unknowns"
      ],
      "properties": {
        "generator": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "model": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 120
        },
        "status": {
          "const": "unreviewed-draft"
        },
        "assumptions": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "unknowns": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        }
      },
      "additionalProperties": false
    },
    "device": {
      "type": "object",
      "required": [
        "brand",
        "name",
        "model",
        "description",
        "device_type",
        "connectivity",
        "memory",
        "boundaries",
        "supported_output_types",
        "source_refs"
      ],
      "properties": {
        "brand": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "model": {
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "variant": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 160
        },
        "product_line": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 160
        },
        "description": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "device_type": {
          "enum": [
            "development-board",
            "controller",
            "module",
            "gateway",
            "product",
            "other"
          ]
        },
        "connectivity": {
          "$ref": "#/$defs/connectivity"
        },
        "memory": {
          "$ref": "#/$defs/deviceMemory"
        },
        "boundaries": {
          "$ref": "#/$defs/boundaries"
        },
        "supported_output_types": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "enum": [
              "ON_OFF",
              "DIMMABLE",
              "ON_OFF_EXTERN",
              "DIMMABLE_EXTERN",
              "RGB_DMX",
              "DIMMABLE_DMX"
            ]
          }
        },
        "source_refs": {
          "$ref": "#/$defs/sourceRefs"
        }
      },
      "additionalProperties": false
    },
    "connectivity": {
      "type": "object",
      "required": [
        "usb_serial",
        "wifi",
        "ethernet",
        "bluetooth",
        "mqtt",
        "poe"
      ],
      "properties": {
        "usb_serial": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "wifi": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "ethernet": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "bluetooth": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "mqtt": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "poe": {
          "type": [
            "boolean",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "deviceMemory": {
      "type": "object",
      "required": [
        "external_flash_bytes",
        "external_ram_bytes",
        "psram_bytes"
      ],
      "properties": {
        "external_flash_bytes": {
          "$ref": "#/$defs/nullableNonNegativeInteger"
        },
        "external_ram_bytes": {
          "$ref": "#/$defs/nullableNonNegativeInteger"
        },
        "psram_bytes": {
          "$ref": "#/$defs/nullableNonNegativeInteger"
        }
      },
      "additionalProperties": false
    },
    "boundaries": {
      "type": "object",
      "required": [
        "max_inputs",
        "max_outputs",
        "input_name_bytes",
        "input_topic_bytes",
        "output_name_bytes",
        "output_topic_bytes"
      ],
      "properties": {
        "max_inputs": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 254
        },
        "max_outputs": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 254
        },
        "input_name_bytes": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 63
        },
        "input_topic_bytes": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 127
        },
        "output_name_bytes": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 63
        },
        "output_topic_bytes": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 127
        }
      },
      "additionalProperties": false
    },
    "microcontroller": {
      "type": "object",
      "required": [
        "ref",
        "manufacturer",
        "name",
        "family",
        "model",
        "architecture",
        "is_primary",
        "memory",
        "gpio_count",
        "capabilities",
        "source_refs"
      ],
      "properties": {
        "ref": {
          "$ref": "#/$defs/key"
        },
        "manufacturer": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "family": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "model": {
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "architecture": {
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "is_primary": {
          "type": "boolean"
        },
        "memory": {
          "type": "object",
          "required": [
            "internal_flash_bytes",
            "internal_ram_bytes",
            "internal_eeprom_bytes"
          ],
          "properties": {
            "internal_flash_bytes": {
              "$ref": "#/$defs/nullableNonNegativeInteger"
            },
            "internal_ram_bytes": {
              "$ref": "#/$defs/nullableNonNegativeInteger"
            },
            "internal_eeprom_bytes": {
              "$ref": "#/$defs/nullableNonNegativeInteger"
            }
          },
          "additionalProperties": false
        },
        "gpio_count": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 1000
        },
        "capabilities": {
          "type": "object",
          "required": [
            "native_usb",
            "wifi_radio",
            "bluetooth_radio",
            "ethernet_mac"
          ],
          "properties": {
            "native_usb": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "wifi_radio": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "bluetooth_radio": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "ethernet_mac": {
              "type": [
                "boolean",
                "null"
              ]
            }
          },
          "additionalProperties": false
        },
        "source_refs": {
          "$ref": "#/$defs/sourceRefs"
        }
      },
      "additionalProperties": false
    },
    "usbIdentity": {
      "type": "object",
      "required": [
        "role",
        "vendor_id",
        "product_id",
        "driver",
        "binding",
        "control_lines",
        "port_index",
        "source_refs"
      ],
      "properties": {
        "role": {
          "enum": [
            "runtime",
            "bootloader",
            "programmer"
          ]
        },
        "vendor_id": {
          "type": "string",
          "pattern": "^0x[0-9A-F]{4}$"
        },
        "product_id": {
          "type": "string",
          "pattern": "^0x[0-9A-F]{4}$"
        },
        "driver": {
          "enum": [
            "cdc-acm",
            "ftdi",
            "cp210x",
            "ch34x",
            "pl2303",
            "picoboot",
            "dfu",
            "stlink"
          ]
        },
        "binding": {
          "enum": [
            "generic",
            "device-bound"
          ]
        },
        "control_lines": {
          "enum": [
            "none",
            "dtr",
            "dtr-rts",
            "best-effort"
          ]
        },
        "interface_number": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 255
        },
        "port_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 31
        },
        "notes": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 500
        },
        "source_refs": {
          "$ref": "#/$defs/sourceRefs"
        }
      },
      "additionalProperties": false
    },
    "pin": {
      "type": "object",
      "required": [
        "key",
        "label",
        "microcontroller_ref",
        "framework_pin",
        "gpio_number",
        "physical_pin",
        "role",
        "configurable",
        "capabilities",
        "alternate_functions",
        "side",
        "hitbox",
        "svg_hitbox_id",
        "mapping_status",
        "geometry_confidence",
        "mapping_confidence",
        "manual_override",
        "source_refs"
      ],
      "properties": {
        "key": {
          "$ref": "#/$defs/key"
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "microcontroller_ref": {
          "oneOf": [
            { "$ref": "#/$defs/key" },
            { "type": "null" }
          ],
          "description": "Null for board contacts such as supply rails or grounds that are not connected to one Microcontroller pin."
        },
        "framework_pin": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 80
        },
        "gpio_number": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 4095
        },
        "physical_pin": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 40
        },
        "capabilities": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "enum": [
              "ANALOG_INPUT",
              "BINARY_INPUT",
              "DIGITAL_OUTPUT",
              "BINARY_OUTPUT",
              "PWM",
              "INTERRUPT",
              "UART",
              "I2C",
              "SPI",
              "CAN",
              "USB",
              "POWER",
              "GROUND",
              "RESET",
              "DEBUG",
              "ANALOG_REFERENCE",
              "REGULATOR_CONTROL",
              "COMMUNICATION"
            ]
          }
        },
        "safe_boot_state": {
          "enum": [
            "input",
            "low",
            "high",
            "unknown"
          ]
        },
        "notes": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 500
        },
        "source_refs": {
          "$ref": "#/$defs/sourceRefs"
        },
        "role": {
          "enum": [
            "gpio",
            "power-input",
            "power-output",
            "ground",
            "analog-reference",
            "reset",
            "debug",
            "communication",
            "other"
          ]
        },
        "configurable": {
          "type": "boolean"
        },
        "alternate_functions": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          }
        },
        "side": {
          "enum": [
            "left",
            "right",
            "top",
            "bottom",
            "internal",
            "unknown"
          ]
        },
        "hitbox": {
          "$ref": "#/$defs/svgRect"
        },
        "svg_hitbox_id": {
          "type": "string",
          "pattern": "^hit-[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
        },
        "mapping_status": {
          "enum": [
            "unverified",
            "source-verified",
            "physically-verified"
          ]
        },
        "geometry_confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "mapping_confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "manual_override": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "buildCandidate": {
      "type": "object",
      "required": [
        "status",
        "platformio",
        "source_refs"
      ],
      "properties": {
        "status": {
          "const": "unverified"
        },
        "platformio": {
          "type": "object",
          "required": [
            "platform",
            "board",
            "framework",
            "upload_protocol",
            "monitor_speed",
            "build_flags",
            "lib_deps"
          ],
          "properties": {
            "platform": {
              "type": "string",
              "minLength": 1,
              "maxLength": 250
            },
            "board": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "framework": {
              "const": "arduino"
            },
            "upload_protocol": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 80
            },
            "monitor_speed": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 1200,
              "maximum": 4000000
            },
            "build_flags": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 300
              }
            },
            "lib_deps": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 300
              }
            }
          },
          "additionalProperties": false
        },
        "source_refs": {
          "$ref": "#/$defs/sourceRefs"
        }
      },
      "additionalProperties": false
    },
    "source": {
      "type": "object",
      "required": [
        "id",
        "type",
        "title",
        "url",
        "publisher",
        "retrieved_at"
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/key"
        },
        "type": {
          "enum": [
            "official-datasheet",
            "official-product-page",
            "official-documentation",
            "official-repository",
            "vendor-documentation",
            "third-party-reference"
          ]
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        },
        "url": {
          "type": "string",
          "format": "uri",
          "pattern": "^https://"
        },
        "publisher": {
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time"
        },
        "notes": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 500
        }
      },
      "additionalProperties": false
    },
    "sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "Lowercase SHA-256 digest of the separately uploaded file bytes."
    },
    "assetFileName": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$",
      "description": "Safe bundle-local basename; directory paths are forbidden."
    },
    "svgRect": {
      "type": "object",
      "required": [
        "x",
        "y",
        "width",
        "height"
      ],
      "properties": {
        "x": {
          "type": "number",
          "minimum": 0,
          "maximum": 1000
        },
        "y": {
          "type": "number",
          "minimum": 0,
          "maximum": 1000
        },
        "width": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000
        },
        "height": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000
        }
      },
      "additionalProperties": false
    },
    "sourceArtworkAsset": {
      "type": "object",
      "required": [
        "asset_id",
        "file_name",
        "kind",
        "media_type",
        "sha256",
        "size_bytes",
        "pixel_width",
        "pixel_height",
        "view",
        "rights",
        "notes"
      ],
      "properties": {
        "asset_id": {
          "$ref": "#/$defs/key"
        },
        "file_name": {
          "$ref": "#/$defs/assetFileName"
        },
        "kind": {
          "enum": [
            "user-raster",
            "official-raster",
            "official-vector"
          ]
        },
        "media_type": {
          "enum": [
            "image/jpeg",
            "image/png",
            "image/webp",
            "image/svg+xml",
            "application/pdf"
          ]
        },
        "sha256": {
          "$ref": "#/$defs/sha256"
        },
        "size_bytes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 52428800
        },
        "pixel_width": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 20000
        },
        "pixel_height": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 20000
        },
        "view": {
          "enum": [
            "top",
            "bottom",
            "unknown"
          ]
        },
        "rights": {
          "enum": [
            "user-declared-owned",
            "licensed-for-publication",
            "official-redistribution-cleared",
            "unknown"
          ]
        },
        "notes": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 1000
        },
        "source_refs": {
          "$ref": "#/$defs/sourceRefs"
        }
      },
      "additionalProperties": false
    },
    "deviceSvgAsset": {
      "type": "object",
      "required": [
        "asset_id",
        "file_name",
        "media_type",
        "sha256",
        "size_bytes",
        "derived_from_asset_id",
        "width",
        "height",
        "view_box",
        "transparent_background",
        "embedded_raster",
        "sanitization_status",
        "geometry_status"
      ],
      "properties": {
        "asset_id": {
          "$ref": "#/$defs/key"
        },
        "file_name": {
          "$ref": "#/$defs/assetFileName"
        },
        "media_type": {
          "const": "image/svg+xml"
        },
        "sha256": {
          "$ref": "#/$defs/sha256"
        },
        "size_bytes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10485760
        },
        "derived_from_asset_id": {
          "$ref": "#/$defs/key"
        },
        "width": {
          "const": "1000pt"
        },
        "height": {
          "const": "1000pt"
        },
        "view_box": {
          "type": "array",
          "prefixItems": [
            {
              "const": 0
            },
            {
              "const": 0
            },
            {
              "const": 1000
            },
            {
              "const": 1000
            }
          ],
          "minItems": 4,
          "maxItems": 4
        },
        "transparent_background": {
          "const": true
        },
        "embedded_raster": {
          "const": false
        },
        "sanitization_status": {
          "const": "pending-server-validation"
        },
        "geometry_status": {
          "enum": [
            "unverified",
            "overlay-reviewed",
            "physically-verified"
          ]
        },
        "notes": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 1000
        }
      },
      "additionalProperties": false
    },
    "pinOverlay": {
      "type": "object",
      "required": [
        "authoritative_geometry",
        "units",
        "origin",
        "svg_group_id",
        "hitboxes_embedded_in_svg"
      ],
      "properties": {
        "authoritative_geometry": {
          "const": "pins[].hitbox"
        },
        "units": {
          "const": "svg-viewbox-user-units"
        },
        "origin": {
          "const": "top-left"
        },
        "svg_group_id": {
          "const": "elementic-pin-hitboxes"
        },
        "hitboxes_embedded_in_svg": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "geometryProvenance": {
      "type": "object",
      "required": [
        "method",
        "generator",
        "generator_version",
        "source_to_svg_homography",
        "confidence",
        "manual_overrides"
      ],
      "properties": {
        "method": {
          "enum": [
            "image-trace",
            "official-vector-normalization",
            "manual-vector"
          ]
        },
        "generator": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "generator_version": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 120
        },
        "source_to_svg_homography": {
          "description": "Row-major 3x3 transform from source artwork coordinates to SVG viewBox units; null when no meaningful source coordinate system exists.",
          "oneOf": [
            {
              "type": "array",
              "items": { "type": "number" },
              "minItems": 9,
              "maxItems": 9
            },
            { "type": "null" }
          ]
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "manual_overrides": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        }
      },
      "additionalProperties": false
    },
    "artwork": {
      "type": "object",
      "required": [
        "source_artwork",
        "device_svg",
        "pin_overlay",
        "geometry_provenance"
      ],
      "properties": {
        "source_artwork": {
          "$ref": "#/$defs/sourceArtworkAsset"
        },
        "device_svg": {
          "$ref": "#/$defs/deviceSvgAsset"
        },
        "pin_overlay": {
          "$ref": "#/$defs/pinOverlay"
        },
        "geometry_provenance": {
          "$ref": "#/$defs/geometryProvenance"
        }
      },
      "additionalProperties": false
    }
  }
}
