Schemas define the parameters and operations that a device exposes. They serve as the contract between the device and its consumers, driving validation, documentation generation, and the mock pipeline (gate d1).
Why schemas?
- Validation — ensure parameter values are within valid ranges
- Documentation — auto-generate device docs from schema metadata
- Mock pipeline — the test framework uses schemas to simulate device behavior
- Discovery — clients can query available parameters and operations
Parameter schema
Each parameter has a schema that defines its metadata:
from plesty.lib.schema import ParameterSchema
param_schema = ParameterSchema(
key="voltage",
unit="V",
dtype="float",
default=0.0,
min_value=0.0,
max_value=100.0,
description="Output voltage",
)Schema fields
| Field | Type | Description |
|---|---|---|
key |
str |
Unique parameter identifier |
unit |
str |
Physical unit (V, A, Hz, etc.) |
dtype |
str |
Data type (float, int, bool, str) |
default |
object |
Default value |
min_value |
float |
Minimum valid value (numeric types) |
max_value |
float |
Maximum valid value (numeric types) |
description |
str |
Human-readable description |
Operation schema
Operations are functions the device can perform:
from plesty.lib.schema import OperationSchema
op_schema = OperationSchema(
key="calibrate",
description="Run calibration routine",
parameters={
"target": {"type": "float", "description": "Target value"},
},
)Registering schemas
Schemas are registered in the device class, typically in init:
class MyDevice(BaseDeviceSyncModel):
def __init__(self, main=None):
super().__init__(main=main)
self._params = {
"voltage": ParameterSchema(
key="voltage",
unit="V",
dtype="float",
default=0.0,
min_value=0.0,
max_value=100.0,
description="Output voltage",
),
}
self._ops = {
"calibrate": OperationSchema(
key="calibrate",
description="Run calibration routine",
),
}Schema and the mock pipeline
The mock pipeline (gate d1) uses schemas to:
- Validate schema integrity — ensure JSON is well-formed
- Resolve parameter keys — every key in
get_config_list()must have a schema - Round-trip parameters — write and read back through the mock solver
- Execute operations — each operation must return a dict
Next steps
- Write the full device implementation
- Set up the TCP server
- Pass gate d1