Skip to main content
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

PropertyTypeDescription
typestringConstant identifier. Must be exactly "playground_definition".
versionstringSchema version. Currently "1.1.0". Definitions created before this version may carry "1.0.1" and have no layout block — see Layout Types.
layoutobjectLayout type and configuration. See Layout Types below. Optional for backwards compatibility — if absent, the definition is treated as {"type": "free_form"}.
componentsarrayA list of distinct interactive UI instances to render (e.g., chat boxes, charts).
connectionsarrayA 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],
    "zoom": 1.25
  },
  "components": [ /* ... */ ],
  "connections": []
}

​
layout Properties (grid)

PropertyTypeDescription
typestringMust be exactly "grid".
columnsintegerNumber of columns the grid is divided into. Range: 4–128. Required at creation.
row_heightintegerRow height in pixels. Range: 10–200. Required at creation.
marginarray of 2 integersOptional. Horizontal and vertical margin between widgets, in pixels. Defaults to [10, 10].
container_paddingarray of 2 integersOptional. Padding around the canvas, in pixels. Defaults to [10, 10].
zoomnumberOptional. Last user zoom setting; mutable across uploads. Range: 0.5–2. Defaults to 1 if absent. Also valid on free-form layouts.
All four configuration fields (columns, row_height, margin, container_padding) are immutable for the lifetime of the playground. Only zoom may be updated freely.

​
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:
PropertyTypeDescription
xintegerColumn index of the widget’s top-left corner (0-based).
yintegerRow index of the widget’s top-left corner (0-based).
widthintegerWidget width in grid columns. Required.
heightintegerWidget height in grid rows. Required.
min_widthintegerOptional minimum width in columns.
max_widthintegerOptional maximum width in columns.
min_heightintegerOptional minimum height in rows.
max_heightintegerOptional 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.