This document describes the JSON schemas used to define hardware in the SBL ecosystem.

Overview

SBL uses two primary schemas to model hardware:

Schema	Purpose
`mainboard.schema.json`	Primary boards running an SBL application
`module.schema.json`	Attachable modules (expansion boards, ICs)

The key concept is the expose/claim model: mainboards expose resources (pins, buses) and modules claim them. This creates a traceable chain from logical pin names down to physical MCU registers.

Schema Relationships

Schema Diagrams

Mainboard Schema

Mainboard Schema Structure

Module Schema

Module Schema Structure

Supporting Schemas

Schema	Diagram
MCU Definition
Project Config
Lock File

To regenerate these diagrams:

cd tools/schema/
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python visualize_schema.py --all

Mainboard Schema

File: schema/mainboard.schema.json

A mainboard is the primary board in an SBL application. It references an MCU and defines what resources are available to modules.

Root Properties

Property	Required	Description
`schemaVersion`	Yes	Schema version (currently `"0.1"`)
`mainboard`	Yes	Core board metadata
`exposes`	No	Resources exposed to modules
`claims`	No	Resources claimed internally
`contains`	No	ICs/components on this board
`config`	No	Board configuration (clocks, etc.)

mainboard Object

{
  "mainboard": {
    "name": "my-devboard",
    "manifestVersion": "1.0.0",
    "revision": "1.0",
    "mcu": "mcu/arm/stm32h750"
  }
}

Field	Required	Description
`name`	Yes	Identifier matching directory name (`^[a-z0-9-]+$`)
`manifestVersion`	Yes	Manifest definition version (semver)
`revision`	Yes	Hardware revision (physical PCB) (`^\d+\.\d+(\.\d+)?$`)
`mcu`	Yes	MCU reference path (`^mcu/[a-z0-9_/-]+$`)

exposes Object

Defines what resources this mainboard makes available to modules.

{
  "exposes": {
    "gpio": {
      "d20": { "mcu_pin": "PC1", "functions": ["gpio", "adc"] }
    },
    "adc": {
      "adc0": { "mcu_pin": "PA0", "mcu_channel": "ADC1_IN0" }
    },
    "buses": {
      "spi1": {
        "type": "spi",
        "mcu_peripheral": "SPI1",
        "pins": { "mosi": "PB5", "miso": "PB4", "sck": "PB3" }
      }
    }
  }
}

GPIO Expose

Field	Required	Description
`mcu_pin`	Yes	Physical MCU pin name
`functions`	No	Available alternate functions

ADC Expose

Field	Required	Description
`mcu_pin`	Yes	Physical MCU pin name
`mcu_channel`	Yes	ADC channel identifier

Bus Expose

Field	Required	Description
`type`	Yes	Bus type: `spi`, `i2c`, `uart`
`mcu_peripheral`	Yes	MCU peripheral name
`pins`	No	Pin assignments for this bus

claims Object

Resources claimed internally by the mainboard (not available to modules).

{
  "claims": {
    "pins": [
      {
        "mcu_pin": "PC13",
        "function": "gpio",
        "direction": "out",
        "id": "status_led"
      }
    ],
    "buses": [
      { "mcu_peripheral": "I2C2", "id": "internal_i2c" }
    ]
  }
}

Pin Claim

Field	Required	Description
`mcu_pin`	Yes	Physical MCU pin
`function`	Yes	Pin function (gpio, adc, pwm, etc.)
`id`	Yes	Code identifier (`^[a-z][a-z0-9_]*$`)
`direction`	No	`in` or `out` (for GPIO)
`pull`	No	`up`, `down`, `none`
`active_low`	No	Inverted logic (default: false)

Bus Claim

Field	Required	Description
`mcu_peripheral`	Yes	MCU peripheral name
`id`	Yes	Code identifier

contains Object

ICs and components soldered onto this mainboard.

{
  "contains": {
    "codec": {
      "part": "WM8731",
      "module": "modules/ic/wm8731",
      "bus": "internal_i2s"
    },
    "flash": {
      "part": "IS25LP064A",
      "interface": "qspi",
      "size_mb": 8
    }
  }
}

config Object

Board-level configuration.

{
  "config": {
    "hse_mhz": 16,
    "sysclk_mhz": 480
  }
}

Module Schema

File: schema/module.schema.json

A module is anything that attaches to a mainboard or another module: expansion boards, ICs, peripherals.

Root Properties

Property	Required	Description
`schemaVersion`	Yes	Schema version (currently `"0.1"`)
`module`	Yes	Core module metadata
`interface`	No	Bus interface (for ICs)
`secondary_mcu`	No	Secondary MCU on this module
`exposes`	No	Resources exposed to child modules
`claims`	No	Resources claimed from parent
`requires`	No	Additional required pins (for ICs)
`provides`	No	Capabilities documentation
`contains`	No	Sub-components
`protocol`	No	Communication protocol

module Object

{
  "module": {
    "name": "led-panel",
    "manifestVersion": "1.0.0",
    "revision": "1.0",
    "category": "boards",
    "attaches_to": "mainboards/my-devboard"
  }
}

Field	Required	Description
`name`	Yes	Module identifier
`manifestVersion`	Yes	Manifest definition version (semver)
`revision`	Yes	Hardware revision (physical version)
`category`	Yes	`boards` or `ic`
`attaches_to`	No	Parent reference
`manufacturer`	No	IC manufacturer
`datasheet`	No	Datasheet URL

interface Object

For ICs that connect via a bus:

{
  "interface": {
    "type": "spi",
    "role": "peripheral",
    "mode": 0,
    "max_speed_hz": 20000000
  }
}

Field	Required	Description
`type`	No	`spi`, `i2c`, `uart`
`role`	No	`peripheral` or `controller`
`address`	No	I2C address (hex string)
`mode`	No	SPI mode (0-3)
`max_speed_hz`	No	Maximum bus speed

claims Object

Resources this module claims from its parent:

{
  "claims": {
    "pins": [
      { "pin": "d20", "function": "gpio", "direction": "out", "id": "led1_red" }
    ],
    "adc": [
      { "pin": "adc0", "id": "knob1" }
    ],
    "buses": [
      { "bus": "spi1", "cs_pin": "d10", "id": "display_spi" }
    ]
  }
}

Key difference from mainboard claims: modules reference logical names from their parent's exposes, not physical MCU pins.

requires Object

For ICs that need additional pins beyond the bus:

{
  "requires": {
    "pins": [
      { "function": "gpio", "direction": "out", "id": "reset", "optional": false },
      { "function": "gpio", "direction": "out", "id": "ldac", "optional": true }
    ]
  }
}

protocol Object

For complex ICs or modules with secondary MCUs:

{
  "protocol": {
    "commands": {
      "reset": { "opcode": "0x06", "args": [] },
      "read": { "opcode": "0x03", "args": ["address", "length"] }
    },
    "registers": {
      "status": { "address": "0x00", "size": 1, "access": "r" },
      "config": { "address": "0x01", "size": 2, "access": "rw" }
    }
  }
}

Pin Resolution Flow

The power of this schema design is traceable pin resolution:

Module claims "d20" (logical name)
    ↓
Mainboard exposes "d20" → "PC1" (MCU pin)
    ↓
MCU defines "PC1" → { port: 2, pin: 1 }
    ↓
Code generation: gpio::Pin<2, 1>

This separation means:

Modules are portable across different mainboards
Pin mappings are explicit and auditable
Code generation has all information needed for type-safe HAL access

Validation

Validate your definitions against these schemas:

# Using ajv-cli
npm install -g ajv-cli
ajv validate -s schema/mainboard.schema.json -d mainboards/my-board/hardware.json
 
# Using jsonschema (Python)
pip install jsonschema
jsonschema -i mainboards/my-board/hardware.json schema/mainboard.schema.json