Object Type Schema

Every Switchboard object — the SDK singleton, audio engines, audio graphs, audio graph nodes, and extensions — publishes a static type descriptor. The descriptor describes what the object is, what construction parameters it accepts, what runtime properties it exposes, what actions can be invoked on it, and what events it emits.

This page defines the shape of those descriptors as a JSON Schema. You can use it to validate hand-written descriptors, to generate UIs from object metadata, or to drive code generation for client SDKs.

At a glance

A descriptor is an object with up to nine fields:

Field	Required	Purpose
type	yes	Kind of object (switchboard, engine, graph, node, extension).
subtype	yes	Specific variant within the kind (e.g. Switchboard.Gain).
description	yes	Human-readable description.
displayName	no	Display label for UIs.
categories	no	Tags for grouping in UIs.
configuration	no	Construction-time parameters, keyed by name.
properties	no	Runtime properties, keyed by name.
actions	no	Invocable actions, keyed by name.
events	no	Emitted events, keyed by name.

Top-level fields

type

The kind of Switchboard object. Must be one of:

• switchboard — the SDK singleton
• engine — an audio engine (e.g. realtime, offline, manual, websocket)
• graph — an audio graph
• node — an audio graph node
• extension — an extension package

subtype

A string that identifies the specific variant within the type. For nodes this is the fully-qualified node type name (e.g. Switchboard.Gain, Superpowered.Reverb); for extensions it is the extension name; for engines it is the engine type name.

description

A human-readable description of what this object does. Required.

displayName

An optional UI-friendly label. Consumers should fall back to subtype when this is omitted.

categories

An optional array of strings that group related objects in UIs. The SDK ships these common values, but extensions are free to add their own:

Audio Processing, Mixing, Music, Voice, Generation, Analysis, Effects, Utility, AI, RTC.

Configuration schema

configuration is a map keyed by parameter name. Each entry describes one construction-time parameter.

Field	Required	Notes
name	no	Name of the parameter. Inferred from the key in the configuration map.
description	yes	Human-readable description.
type	yes	One of boolean, float, int, string, array, object.
default	yes	Default value used when the caller omits this parameter. Must match type.
min	no	Inclusive minimum for numeric types.
max	no	Inclusive maximum for numeric types.
options	no	An array of allowed values; each entry must match type.

Property schema

properties is a map keyed by property name. Each entry describes one runtime property exposed via getValue / setValue.

Field	Required	Notes
name	no	Name of the property. Inferred from the key in the properties map.
description	yes	Human-readable description.
type	yes	One of boolean, float, int, string, array, object.
readOnly	yes	true for derived/observed values, false for caller-settable values.
default	no	Initial value before the caller sets one. Only meaningful when readOnly is false.
min	no	Inclusive minimum for numeric types.
max	no	Inclusive maximum for numeric types.
options	no	An array of allowed values; each entry must match type.
unit	no	A unit hint for UIs: ms, dB, %, Hz, semitones, BPM, samples, frames, channels, bytes, bits.

Action schema

actions is a map keyed by action name. Each entry describes one invocable action.

Field	Required	Notes
name	no	Name of the action. Inferred from the key in the actions map.
description	yes	Human-readable description.
parameters	no	A map of parameter-name → parameter schema (see below).

Action parameter schema

Field	Required	Notes
name	no	Name of the parameter. Inferred from the key in the parameters map.
description	yes	Human-readable description.
type	yes	One of boolean, float, int, string, array, object.
isOptional	no	true if the caller may omit the parameter. Defaults to false.

Event schema

events is a map keyed by event name. Each entry describes one emitted event.

Field	Required	Notes
name	no	Name of the event. Inferred from the key in the events map.
description	yes	Human-readable description.
data	no	A map of data-field-name → data-field schema (see below).

Event data field schema

Field	Required	Notes
name	no	Name of the data field. Inferred from the key in the data map.
description	yes	Human-readable description.
type	yes	One of boolean, float, int, string, array, object.

Example

{
  "type": "node",
  "subtype": "Switchboard.Gain",
  "displayName": "Gain",
  "description": "Applies a gain factor to the audio signal.",
  "categories": ["Audio Processing"],
  "properties": {
    "gain": {
      "type": "float",
      "readOnly": false,
      "description": "The gain of the audio signal. The range is [0, 1].",
      "min": 0.0,
      "max": 1.0
    }
  }
}

Full JSON Schema

Download object-type.json