---
sidebar:
  hidden: true
title: roboto.experimental.boards.definition
---
## Module Contents

### BoardCalendar

```python
class roboto.experimental.boards.definition.BoardCalendar(/, **data: Any)
```

`from roboto.experimental.boards import BoardCalendar`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L352-L373)

Bases: `_DefinitionPart`

The time zone a board reads its times in, and the day its weeks start on.

The Roboto web app shows every time on the board in this zone, and divides time into days, weeks and other calendar periods in it, with weeks beginning on [`week_start`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardCalendar.week_start): for a chart's time units and weekly groups, for the rows a click on one of those periods selects, and for the periods of a metric aggregate. The bounds of a custom `time_range`, each a date (`"2026-09-06"`) or a date and time written without a zone or offset (`"2026-09-06T14:00"`), are read in this zone too.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardCalendar.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- **BoardCalendar.time_zone** (`str`) = `'UTC'`: The zone's name in the IANA time zone database, in the database's letter case, such as `"America/Los_Angeles"`. This model does not check the name. The web app reports the definition as invalid when the name is not in the database, is an offset such as `"+05:30"`, is written in another letter case such as `"america/los_angeles"`, or is `CET`, `EET`, `MET` or `WET`, which Roboto reads as fixed offsets without daylight saving time when it aggregates metrics; name such a zone by area and location instead, such as `"Europe/Paris"` for `CET`.
- **BoardCalendar.week_start** (`roboto.domain.metrics.record.DayOfWeek`): The day the board's weeks start on.

### BoardColumnControlDomain

```python
class roboto.experimental.boards.definition.BoardColumnControlDomain(/, **data: Any)
```

`from roboto.experimental.boards import BoardColumnControlDomain`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L96-L104)

Bases: `_DefinitionPart`

A value control's choices taken from the distinct values of a column in the result of the one stage the control reads.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardColumnControlDomain.column** (`str`) = `None`: The column of the input stage's result whose distinct values the control lists.
- **BoardColumnControlDomain.kind** (`Literal['column']`): Marks the choices as a column's values.

### BoardControlFilterBody

```python
class roboto.experimental.boards.definition.BoardControlFilterBody(/, **data: Any)
```

`from roboto.experimental.boards import BoardControlFilterBody`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L215-L231)

Bases: `_DefinitionPart`

Keeps the rows of the stage's first input that match the values chosen in the value control it reads second.

The stage's [`inputs`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardStage.inputs) name the data stage and then the value control. A control that is not required and has no value filters nothing.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardControlFilterBody.column** (`str`) = `None`: The column of the data stage's result that the filter compares with the chosen values.
- **BoardControlFilterBody.columnHolds** (`Literal['value', 'entity-id'] | None`) = `None`: What the column holds: `value`, a value of the control's type, which matches when it is a chosen value; or `entity-id`, the id of an entity of the control's `entity-field` domain, which matches when that entity's field holds a chosen value. `value` when absent.
- **BoardControlFilterBody.kind** (`Literal['control-filter']`): Marks the stage as a control-filter.

### BoardControlOption

```python
class roboto.experimental.boards.definition.BoardControlOption(/, **data: Any)
```

`from roboto.experimental.boards import BoardControlOption`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L76-L83)

Bases: `_DefinitionPart`

One choice a value control lists, and the label the control shows for it.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardControlOption.label** (`str`): The text the control shows for the choice.
- **BoardControlOption.value** (`dict[str, Any]`): The value as a tagged JSON object, for example `{"type": "string", "value": "north"}`.

### BoardDefinition

```python
class roboto.experimental.boards.definition.BoardDefinition(/, **data: Any)
```

`from roboto.experimental.boards import BoardDefinition`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L376-L493)

Bases: `_DefinitionPart`

A board definition whose outline is checked as the model is built.

The platform refuses a definition whose top level this model refuses, with the entries of `panels` and `stages` set aside, and stores the panels and stages in it as given; the web app decides what a definition means when it opens the board. This model checks a definition's outline:

- the top-level keys, the calendar's members, and the keys every panel, stage, section and selection carries;
- the members of a control or control-filter stage, and how many inputs it names;
- that no two stages share an id;
- that each stage a panel or another stage names is declared;
- that a control-filter reads a data stage (a stage that is not a control), then a value control.

It does not check what lies deeper, such as a stage's query or a chart's specification, nor whether the calendar's time zone is one the web app accepts, so the web app can still report a definition this model accepts, or a panel or stage in it, as invalid.

At the top level and in the calendar, a key the models do not declare is refused, as the web app refuses it. Elsewhere below the top level, such a key is kept as given. An optional key left as `None` is omitted when the model is serialized.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardDefinition.calendar** (`BoardCalendar | None`) = `None`: The time zone the board reads its times in, and the day its weeks start on. Without one, the board reads its times in UTC and its weeks start on Monday.
- **BoardDefinition.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- **BoardDefinition.panels** (`list[BoardPanel]`): The panels on the canvas. May be empty.
- **BoardDefinition.schema_version** (`Literal[1]`) = `1`: Version of the definition's schema.
- **BoardDefinition.sections** (`list[BoardSection] | None`) = `None`: Titled regions of the canvas.
- **BoardDefinition.selections** (`list[BoardSelection] | None`) = `None`: Named selections that panels publish to and filter by.
- **BoardDefinition.stages** (`list[BoardStage] | None`) = `None`: The stages that provide the panels' data, and the controls above the canvas.
- **BoardDefinition.time_range** (`str | dict[str, Any]`): The time range the board opens with: a preset such as `"90d"`, or a JSON object describing a custom or relative range.
- **BoardDefinition.title** (`str | None`) = `None`: The board's title. The platform keeps a board's name equal to a title that is a non-empty string.

#### BoardDefinition.validate_stage_ids_and_references()

```python
def validate_stage_ids_and_references() -> BoardDefinition
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L427-L493)

Reject a reused stage id, a reference to an undeclared stage, and a control-filter reading the wrong stages.

A control-filter reads a data stage, then a value control. A control-filter input that names no stage, or an id several stages share, is reported only as an undeclared or a reused stage id.

**Returns**

- `BoardDefinition`

### BoardEntityFieldControlDomain

```python
class roboto.experimental.boards.definition.BoardEntityFieldControlDomain(
    /,
    **data: Any,
)
```

`from roboto.experimental.boards import BoardEntityFieldControlDomain`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L107-L117)

Bases: `_DefinitionPart`

A value control's choices taken from the values a field holds on one kind of entity.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardEntityFieldControlDomain.field** (`str`) = `None`: The field, for example `name`, or `custom.<field_name>` for a custom field.
- **BoardEntityFieldControlDomain.kind** (`Literal['entity-field']`): Marks the choices as an entity field's values.
- **BoardEntityFieldControlDomain.target** (`str`) = `None`: The kind of entity, for example `sessions` or `devices`.

### BoardFieldControlBody

```python
class roboto.experimental.boards.definition.BoardFieldControlBody(/, **data: Any)
```

`from roboto.experimental.boards import BoardFieldControlBody`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L181-L212)

Bases: `_DefinitionPart`

A control above the canvas in which a viewer chooses which field a chart or query reads.

The fields it offers belong to exactly one kind of entity ([`target`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardFieldControlBody.target)) or one topic ([`topic`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardFieldControlBody.topic)). The stage reads no input.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardFieldControlBody.default** (`str | None`) = `None`: The field the control holds when the board opens and the board's URL has no `control.<name>` key for the control, and after the control is reset to its default from the control bar.
- **BoardFieldControlBody.kind** (`Literal['field-control']`): Marks the stage as a field control.
- **BoardFieldControlBody.label** (`str | None`) = `None`: The control's caption.
- **BoardFieldControlBody.options** (`list[BoardFieldControlOption] | None`) = `None`: The fields the control lists, when it lists fewer than its entity or topic has.
- **BoardFieldControlBody.target** (`str | None`) = `None`: The kind of entity whose fields the control offers, for example `sessions`.
- **BoardFieldControlBody.topic** (`str | None`) = `None`: The name of the topic whose fields the control offers.

#### BoardFieldControlBody.validate_target_or_topic()

```python
def validate_target_or_topic() -> BoardFieldControlBody
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L208-L212)

Reject a field control that declares both or neither of a target and a topic.

**Returns**

- `BoardFieldControlBody`

### BoardFieldControlOption

```python
class roboto.experimental.boards.definition.BoardFieldControlOption(/, **data: Any)
```

`from roboto.experimental.boards import BoardFieldControlOption`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L171-L178)

Bases: `_DefinitionPart`

One field a field control lists, and the label the control shows for it.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardFieldControlOption.label** (`str`): The text the control shows for the field.
- **BoardFieldControlOption.value** (`str`) = `None`: The field, for example `name`, `custom.<field_name>` or a dotted topic field path.

### BoardPanel

```python
class roboto.experimental.boards.definition.BoardPanel(/, **data: Any)
```

`from roboto.experimental.boards import BoardPanel`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L47-L61)

Bases: `_DefinitionPart`

A panel on the board's canvas: a chart, a table, or a map.

Only the keys every panel carries are checked. Everything else a panel holds, such as its `title`, its `placement` on the canvas and a chart's `spec`, is kept as given and is not checked.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardPanel.bindings** (`list[BoardPanelBinding]`) = `None`: The stage results the panel draws. A panel has at least one.
- **BoardPanel.id** (`str`) = `None`: Identifies the panel within the board.
- **BoardPanel.kind** (`str`) = `None`: What the panel draws, for example `chart`, `table` or `map`.

### BoardPanelBinding

```python
class roboto.experimental.boards.definition.BoardPanelBinding(/, **data: Any)
```

`from roboto.experimental.boards import BoardPanelBinding`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L37-L44)

Bases: `_DefinitionPart`

One stage's result, under the name a panel draws it by.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardPanelBinding.name** (`str`) = `None`: The name the panel knows the result by. A chart's specification refers to the result by this name.
- **BoardPanelBinding.stage** (`str`) = `None`: The [`id`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardStage.id) of the stage whose result the panel draws.

### BoardSection

```python
class roboto.experimental.boards.definition.BoardSection(/, **data: Any)
```

`from roboto.experimental.boards import BoardSection`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L320-L339)

Bases: `_DefinitionPart`

A titled region of the canvas. A panel joins a section by naming the section in its own placement.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardSection.height** (`_Number`): Height of the region, in canvas units.
- **BoardSection.id** (`str`) = `None`: Identifies the section within the board.
- **BoardSection.title** (`str`) = `None`: The title shown on the region.
- **BoardSection.width** (`_Number`): Width of the region, in canvas units.
- **BoardSection.x** (`_Number`): Horizontal position of the region's left edge, in canvas units.
- **BoardSection.y** (`_Number`): Vertical position of the region's top edge, in canvas units.

### BoardSelection

```python
class roboto.experimental.boards.definition.BoardSelection(/, **data: Any)
```

`from roboto.experimental.boards import BoardSelection`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L342-L349)

Bases: `_DefinitionPart`

A named selection that panels publish to and filter by.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardSelection.keys** (`list[dict[str, Any]]`): The values a selection carries, each a JSON object with a `key` and a `valueType`. May be empty.
- **BoardSelection.name** (`str`) = `None`: The name panels refer to the selection by.

### BoardStage

```python
class roboto.experimental.boards.definition.BoardStage(/, **data: Any)
```

`from roboto.experimental.boards import BoardStage`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L244-L317)

Bases: `_DefinitionPart`

One stage of the board's data: a query of the platform, a transformation of other stages' results, a control above the canvas whose result is the value a viewer chooses, or a filter of a stage's rows by such a control.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardStage.body** (`BoardValueControlBody | BoardFieldControlBody | BoardControlFilterBody | BoardStageBody`): What the stage does.
- **BoardStage.id** (`str`) = `None`: Identifies the stage within the board, so no two stages of a board share an id. Panels and other stages refer to the stage by it. Starts with a letter or digit, and holds only letters, digits, underscores and hyphens.
- **BoardStage.inputs** (`list[str] | None`) = `None`: The [`id`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardStage.id) of each stage this stage reads.
- **BoardStage.name** (`str`) = `None`: The name the stage's result goes by, for example as a table in another stage's SQL. Starts with a letter or digit, and holds only letters, digits, underscores and hyphens. A control's name is also what a `$name` reference names, so it starts with a letter and holds only letters, digits and underscores.

#### BoardStage.read_body_as_its_kind()

```python
@classmethod
def read_body_as_its_kind(body: Any) -> Any
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L265-L271)

Read a body as the model of its kind, so a mistake in it is reported at the key it was made in.

**Parameters**

- **body** (`Any`)

**Returns**

- `Any`

#### BoardStage.validate_control_name_and_inputs()

```python
def validate_control_name_and_inputs() -> BoardStage
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L274-L317)

Reject a control name a `$name` reference cannot hold, and a control or control-filter with wrong inputs.

A control reads no input, except a value control whose choices are a column's values, which reads the one stage holding the column. A control-filter reads a data stage and then a value control.

**Returns**

- `BoardStage`

### BoardStageBody

```python
class roboto.experimental.boards.definition.BoardStageBody(/, **data: Any)
```

`from roboto.experimental.boards import BoardStageBody`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L64-L73)

Bases: `_DefinitionPart`

What a stage does, for a kind of stage this module has no model of.

Each kind of stage has its own keys, which are kept as given and are not checked. A control or a control-filter is read as [`BoardValueControlBody`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardValueControlBody), [`BoardFieldControlBody`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardFieldControlBody) or [`BoardControlFilterBody`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardControlFilterBody) instead.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardStageBody.kind** (`str`) = `None`: The kind of stage, for example `entity.query` or `sql`.

### BoardStaticControlDomain

```python
class roboto.experimental.boards.definition.BoardStaticControlDomain(/, **data: Any)
```

`from roboto.experimental.boards import BoardStaticControlDomain`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L86-L93)

Bases: `_DefinitionPart`

A value control's choices listed in the definition.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardStaticControlDomain.kind** (`Literal['static']`): Marks the choices as listed here.
- **BoardStaticControlDomain.options** (`list[BoardControlOption]`): The choices the control lists, in order.

### BoardValueControlBody

```python
class roboto.experimental.boards.definition.BoardValueControlBody(/, **data: Any)
```

`from roboto.experimental.boards import BoardValueControlBody`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L127-L168)

Bases: `_DefinitionPart`

A control above the canvas in which a viewer chooses one or several values of a type.

The stage's result is the chosen values. A `control-filter` stage that reads it keeps the rows of its data stage that match the choice, and SQL text, stage expressions, chart specifications and panel titles read the choice as `$name`, where `name` is the stage's [`name`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardStage.name). The stage reads no input, except the one stage whose column a [`BoardColumnControlDomain`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardColumnControlDomain) lists.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BoardValueControlBody.default** (`dict[str, Any] | list[dict[str, Any]] | None`) = `None`: The value the control holds when the board opens and the board's URL has no `control.<name>` key for the control, and after the control is reset to its default from the control bar or by the `reset` operation of a `control` interaction: one tagged JSON object, or a list of them when [`multi`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardValueControlBody.multi) is true.
- **BoardValueControlBody.domain** (`BoardValueControlDomain | None`) = `None`: Where the control's choices come from. Absent, the viewer types the value.
- **BoardValueControlBody.kind** (`Literal['value-control']`): Marks the stage as a value control.
- **BoardValueControlBody.label** (`str | None`) = `None`: The control's caption. Absent or blank, the caption is the display name of the entity field the control takes its choices from (a custom field's display name, a catalog field's display name such as "Device ID" for `device_id`, or a metadata path as written), or else the stage's [`name`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardStage.name).
- **BoardValueControlBody.multi** (`bool | None`) = `None`: Whether the viewer may choose several values. False when absent.
- **BoardValueControlBody.required** (`bool | None`) = `None`: Whether the stages and panels that read the control wait for a value. False when absent, and a control that is not required and has no value filters nothing.
- **BoardValueControlBody.valueType** (`dict[str, Any]`): The type of the values the control holds, as a JSON object with a `type`, for example `{"type": "string"}`.

#### BoardValueControlBody.validate_default_matches_multi()

```python
def validate_default_matches_multi() -> BoardValueControlBody
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L164-L168)

Reject a default that is a list when the control holds one value, or one value when it holds several.

**Returns**

- `BoardValueControlBody`

### BoardValueControlDomain

```python
roboto.experimental.boards.definition.BoardValueControlDomain
```

`from roboto.experimental.boards import BoardValueControlDomain`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L120-L123)

Where a value control's choices come from.

### check_definition_top_level()

```python
def roboto.experimental.boards.definition.check_definition_top_level(
    definition: dict[str, Any],
) -> None
```

`from roboto.experimental.boards.definition import check_definition_top_level`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/boards/definition.py#L496-L517)

Refuse a board definition whose top level [`BoardDefinition`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardDefinition) refuses.

The definition is checked as [`BoardDefinition`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardDefinition) checks it, except for the entries of `panels` and `stages`, which are not checked. It is refused for an unknown top-level key, a missing `time_range` or `panels`, a `panels` that is not a list, a `stages`, `sections` or `selections` that is neither a list nor null, a `title` that is neither a string nor null, a `time_range` that is neither a string nor an object, a `schema_version` other than 1, a `calendar` that is neither an object nor null or has a member other than `time_zone` and `week_start`, a `week_start` that is not a day's name, or a malformed section or selection. The web app reads each panel and stage on its own: it shows a panel or stage that fails beside the rest of the board and saves it as written, so a person can repair a board one panel or stage at a time. A mistake at the top level leaves the web app nothing to show.

**Parameters**

- **definition** (`dict[str, Any]`): The board definition as a JSON object.

**Raises**

- `pydantic.ValidationError`: [`BoardDefinition`](/docs/reference/python-sdk/roboto/experimental/boards/definition#roboto.experimental.boards.definition.BoardDefinition) refuses the definition's top level.

**Returns**

- `None`