Definition Format

A Playground Definition is a JSON object mapping heavily to the Workflow Definition structure, but it is explicitly designed to define customizable, interactive application layouts rather than invisible backend processes.

High-Level Structure

Every Playground Definition uses the following JSON signature:

{
  "type": "playground_definition",
  "version": "1.1.0",
  "layout": {
    // Layout block — see "Layout Types" below for the allowed shapes
  },
  "components": [
    // Array of UI Widget Objects
  ],
  "connections": [
    // Array of Interactive Connections
  ]
}

Top-Level Properties

Property	Type	Description
`type`	string	Constant identifier. Must be exactly `"playground_definition"`.
`version`	string	Schema version. Currently `"1.1.0"`. Definitions created before this version may carry `"1.0.1"` and have no `layout` block — see Layout Types.
`layout`	object	Layout type and configuration. See Layout Types below. Optional for backwards compatibility — if absent, the definition is treated as `{"type": "free_form"}`.
`components`	array	A list of distinct interactive UI instances to render (e.g., chat boxes, charts).
`connections`	array	A list of connections describing interaction pathways between widgets or external resources.

Layout Types

A Playground Definition is rendered with one of two layouts. The layout type is chosen when the playground is created and is immutable — it cannot be changed later. Attempting to upload a definition whose layout block differs from the persisted layout will fail with invalid_layout.

Free-Form Layout

The default. Widgets are positioned with absolute pixel coordinates on a 2D canvas; widget size comes from width / height ports declared per-widget. Suited to ad-hoc canvases where widgets are placed anywhere by drag-and-drop.

{
  "type": "playground_definition",
  "version": "1.1.0",
  "layout": {
    "type": "free_form",
    "zoom": 1.25
  },
  "components": [ /* ... */ ],
  "connections": []
}

The legacy shape (no layout block, version: "1.0.1") is equivalent to {"type": "free_form"} and continues to be served as-is. Newly created free-form playgrounds always carry the explicit layout block. zoom is optional on free-form layouts as well — same range and semantics as in grid (see zoom below): the value is the canvas zoom level the user last saved, and it’s the only mutable field on layout.

Grid Layout

Widgets are placed on a fixed-column grid. Widget position and size are expressed in grid units rather than pixels, and the grid configuration (columns, row_height) is set at creation time.

{
  "type": "playground_definition",
  "version": "1.1.0",
  "layout": {
    "type": "grid",
    "columns": 12,
    "row_height": 30,
    "margin": [10, 10],
    "container_padding": [10, 10],
    "vertical_sizing": "fixed_rows",
    "reference_rows": 12,
    "zoom": 1.25
  },
  "components": [ /* ... */ ],
  "connections": []
}

`layout` Properties (grid)

Property	Type	Description
`type`	string	Must be exactly `"grid"`.
`columns`	integer	Number of columns the grid is divided into. Range: 4–128. Required at creation.
`row_height`	integer	Row height in pixels. Range: 10–200. Required at creation.
`margin`	array of 2 integers	Optional. Horizontal and vertical margin between widgets, in pixels. Defaults to `[10, 10]`.
`container_padding`	array of 2 integers	Optional. Padding around the canvas, in pixels. Defaults to `[10, 10]`.
`vertical_sizing`	string	Optional. Vertical sizing strategy: `pitch` (default), `fit`, or `fixed_rows`. Mutable across uploads. See Vertical Sizing below. Absent ⇒ `pitch`.
`reference_rows`	integer	Optional. Row count used only when `vertical_sizing` is `fixed_rows` (and as the fallback for an empty `fit` grid). Range: 1–128. Defaults to `12`. Mutable across uploads.
`zoom`	number	Optional. Last user zoom setting; mutable across uploads. Range: 0.5–2. Defaults to `1` if absent. Also valid on free-form layouts.

columns, row_height, margin, and container_padding are immutable for the lifetime of the playground. zoom, vertical_sizing, and reference_rows may be updated freely across uploads.

Vertical Sizing

vertical_sizing controls how the effective row height is derived from the viewport. There are three modes:

pitch (default, and the behavior when the field is absent): row_height is used as a fixed pixel pitch. The number of visible rows depends on the viewport height, and content that extends beyond the viewport scrolls normally. This is the historical behavior.
fit: the grid scales so that all occupied rows fit exactly within the viewport height — effective row height = viewport height ÷ (bottom-most occupied row). Adding widgets proportionally shrinks all rows; the grid never scrolls. If the grid is empty, reference_rows is used as the fallback row count.
fixed_rows: a fixed number of rows (set by reference_rows) always fills the viewport height, giving each widget a stable share of the screen across different resolutions. Content placed beyond reference_rows scrolls as normal.

reference_rows is consulted only when vertical_sizing is "fixed_rows" (and as the empty-grid fallback for "fit"). It has no effect in "pitch" mode. Similarly, row_height is only meaningful in "pitch" mode — in "fit" and "fixed_rows" the effective row height is derived from the viewport.

Playground Widgets (Components)

Just like Workflow Components, Playground widgets rely on interfaces to define their behavior. However, they generally pertain to user-facing interactions. The shape of each component’s position field depends on the layout type.

Free-Form Component

{
  "id": "302e66bc-8b8b-4d49-a88d-500f8c422f8d",
  "category": "widget",
  "type": "widget.tradingview",
  "name": "TradingView Chart",
  "ports": [
    {
      "category": "data_input",
      "route": "message",
      "value": {
        "type": "component_alias",
        "alias": "ticker_viz_AAPL_1m"
      }
    },
    {
      "category": "data_input",
      "route": "width",
      "value": {
        "type": "integer",
        "integer": 700
      }
    },
    {
      "category": "data_input",
      "route": "height",
      "value": {
        "type": "integer",
        "integer": 500
      }
    }
  ],
  "position": {
    "x": -3341.5386043389353,
    "y": -1843.5798926414566
  }
}

position.x and position.y are pixel coordinates on the canvas (negative values are valid — they correspond to panning offsets). Widget size is read from the width / height ports.

Grid Component

{
  "id": "302e66bc-8b8b-4d49-a88d-500f8c422f8d",
  "category": "widget",
  "type": "widget.tradingview",
  "name": "TradingView Chart",
  "ports": [
    {
      "category": "data_input",
      "route": "message",
      "value": {
        "type": "component_alias",
        "alias": "ticker_viz_AAPL_1m"
      }
    }
  ],
  "position": {
    "x": 0,
    "y": 0,
    "width": 6,
    "height": 6,
    "min_width": 2,
    "min_height": 2
  }
}

In a grid playground, every component’s position field carries grid-unit coordinates and dimensions:

Property	Type	Description
`x`	integer	Column index of the widget’s top-left corner (0-based).
`y`	integer	Row index of the widget’s top-left corner (0-based).
`width`	integer	Widget width in grid columns. Required.
`height`	integer	Widget height in grid rows. Required.
`min_width`	integer	Optional minimum width in columns.
`max_width`	integer	Optional maximum width in columns.
`min_height`	integer	Optional minimum height in rows.
`max_height`	integer	Optional maximum height in rows.

Constraint: position.x + position.width must not exceed layout.columns. Violations are rejected with invalid_component_position. Grid components do not carry width / height ports — widget size is derived from the grid units and the playground’s row_height / column width.

Overview

Workflow

Scheduler

ONNX

Definition Format

High-Level Structure

Top-Level Properties

Layout Types

Free-Form Layout

Grid Layout

`layout` Properties (grid)

Vertical Sizing

Playground Widgets (Components)

Free-Form Component

Grid Component

​High-Level Structure

​Top-Level Properties

​Layout Types

​Free-Form Layout

​Grid Layout

​layout Properties (grid)

​Vertical Sizing

​Playground Widgets (Components)

​Free-Form Component

​Grid Component

High-Level Structure

Top-Level Properties

Layout Types

Free-Form Layout

Grid Layout

`layout` Properties (grid)

Vertical Sizing

Playground Widgets (Components)

Free-Form Component

Grid Component