YAML Schema Reference

Every Tetrapus deployment is configured through a set of composable YAML files. The entry point is config.yaml, which includes the others. This page is the definitive reference for every file type.

config.yaml — Entry Point

A manifest that lists the files to merge into a single configuration.

YAML

includes:
  - data_schema.yaml
  - command_schema.yaml
  - assets.yaml
  - groups.yaml
  - policies.yaml
  - rules.yaml
  - layout.yaml

data_schema.yaml — Telemetry Fields

Declares every telemetry field emitted by the source, plus fleet-level aggregates. Field order must match the SDK binary layout.

Key	Type	Required	Description
id	String	yes	Schema name (e.g. "hvac_v1")
schema_id	String	yes	Hex wire identifier (e.g. "0xAC000001")
fields[]	FieldSpec[]	yes	Ordered list of per-entity fields
aggregates[]	AggregateSpec[]	no	Fleet-level derived values

FieldSpec keys:

Key	Type	Description
name	String	Field identifier (referenced in rules, widgets, commands)
type	String	u8, u16, u32, u64, i16, f32, f64, or enum
unit	String?	Display unit (e.g. "°C", "kts", "%")
range	[min, max]?	Expected value range for UI scaling
variants	Map?	Enum variant mapping: {"0": "Off", "1": "On"}

YAML

data_schema:
  id: hvac_v1
  schema_id: "0xAC000001"
  fields:
    - name: zone_temp
      type: f32
      unit: "°C"
      range: [10.0, 45.0]
    - name: mode
      type: enum
      variants:
        "0": "Off"
        "1": "Cool"
        "2": "Heat"
  aggregates:
    - name: avg_zone_temp
      description: "Average temperature across all zones"

command_schema.yaml — Commandable Fields

Declares fields the control bus can write to devices. Presence of this file enables the CommandRouter.

Key	Type	Description
name	String	Command field identifier
value_type	String	float, enum, or bool
range	[min, max]?	Valid value range (used for UI slider clamps)
variants	Map?	Enum variant labels (for enum type)

assets.yaml — Spatial Inventory

Defines the physical/spatial asset layout — zones, regions, exchanges. The schema is domain-specific. Three common patterns:

YAML Zone grid (HVAC, facility)

assets:
  - id: caravan_park
    zones:
      - zone_id: 1
        name: "Zone A - Reception"
        lat: -33.8688
        lon: 151.2093
        spread_m: 50.0
        grid_cols: 4
        units: ["room-1", "room-2", "room-3", "room-4"]

YAML Regional grouping (Aviation)

assets:
  - id: global_regions
    regions:
      - region_id: 1
        name: "North America"
        short: "NAM"
        color: "#3b82f6"
        airport_count: 150
        major_hubs: ["KJFK", "KLAX", "KORD"]

groups.yaml — Entity Groups

Named entity groupings for targeted commands and policy assignment.

Key	Type	Description
id	String	Unique group ID (referenced in bus_command targets)
name	String	Display name
zone_ids	u32[]?	Zones whose entities are members
entity_ids	String[]?	Explicit entity ID list
filter.field	String?	Dynamic membership: field to match
filter.value	number?	Dynamic membership: entities where field == value
policy_id	String?	Policy to enforce on this group

policies.yaml — Automation Rules

Continuously-evaluated rules that constrain or override entity fields. See Policy Engine for runtime details.

Condition types (tagged union on type):

type	Extra keys	Fires when
field_above	field, threshold	field > threshold
field_below	field, threshold	field < threshold
field_equals	field, value	field == value
time_window	start_min, end_min	Current time in [start, end] minutes since midnight
and	conditions[]	All sub-conditions true
or	conditions[]	Any sub-condition true
not	condition	Sub-condition false

Action types:

type	Extra keys	Effect
set_field	field, value	Force field to value every tick
clamp_field	field, min, max	Constrain field to [min, max]
enforce_range	field, min, max	Veto commands pushing field outside range

rules.yaml — Visual Mapping

Controls entity appearance in Scene3D. See Visual Mapper for full details. Supports defaults, rules (gradient mappings), conditional_rules (overrides), and geofences.

layout.yaml — Pane Arrangement

Declares the complete pane layout with per-pane configuration.

YAML

layout:
  panes:
    - pane_type: Scene3D
      title: "Global View"
      position: center
      active: true
      state:
        camera:
          target: [151.2093, -33.8688, 0.0]
          distance: 250000.0

    - pane_type: Table
      title: "Fleet Status"
      position: right
      state:
        data_source: fleet_tracker
        per_page: 50
        columns:
          - field: callsign
            header: "Callsign"
          - field: altitude_ft
            header: "Altitude"
            format: "{:.0} ft"

    - pane_type: Control
      title: "HVAC Controls"
      position: left
      state:
        columns: 4
        data_source: hvac_sdk
        tabs:
          - label: "Zone A"
            widgets:
              - id: temp-slider
                widget_type: slider
                label: "Setpoint"
                min: 16.0
                max: 30.0
                unit: "°C"
                bus_command:
                  target: { group: zone_a }
                  fields:
                    - field: setpoint_temp
                      use_widget_value: true
                  label: "Adjust setpoint"

Questions?

Reach out for help with integration, deployment, or custom domain codecs.

Get Started Request a Demo