roboto.experimental.boards.definition
Module Contents
BoardCalendar
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: 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 AnyAttributes
BoardCalendar.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
BoardCalendar.time_zone
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
The day the board’s weeks start on.
BoardColumnControlDomain
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 AnyBoardControlFilterBody
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 name the data stage and then the value control. A control that is not required and has no value filters nothing.
Parameters
data AnyAttributes
BoardControlFilterBody.column
The column of the data stage’s result that the filter compares with the chosen values.
BoardControlFilterBody.columnHolds
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.
BoardControlOption
Bases: _DefinitionPart
One choice a value control lists, and the label the control shows for it.
Parameters
data AnyBoardDefinition
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 AnyAttributes
BoardDefinition.calendar
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
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
BoardDefinition.selections
Named selections that panels publish to and filter by.
BoardDefinition.stages
The stages that provide the panels’ data, and the controls above the canvas.
BoardDefinition.time_range
The time range the board opens with: a preset such as "90d", or a JSON object describing a custom or relative range.
BoardDefinition.title
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()
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.
Return type
BoardEntityFieldControlDomain
Bases: _DefinitionPart
A value control’s choices taken from the values a field holds on one kind of entity.
Parameters
data AnyAttributes
BoardEntityFieldControlDomain.field
The field, for example name, or custom.<field_name> for a custom field.
BoardEntityFieldControlDomain.kind
Marks the choices as an entity field’s values.
BoardEntityFieldControlDomain.target
The kind of entity, for example sessions or devices.
BoardFieldControlBody
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) or one topic (topic). The stage reads no input.
Parameters
data AnyAttributes
BoardFieldControlBody.default
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.options
The fields the control lists, when it lists fewer than its entity or topic has.
BoardFieldControlBody.target
The kind of entity whose fields the control offers, for example sessions.
BoardFieldControlBody.topic
The name of the topic whose fields the control offers.
BoardFieldControlBody.validate_target_or_topic()
Reject a field control that declares both or neither of a target and a topic.
Return type
BoardFieldControlOption
Bases: _DefinitionPart
One field a field control lists, and the label the control shows for it.
Parameters
data AnyBoardPanel
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 AnyAttributes
BoardPanel.bindings
The stage results the panel draws. A panel has at least one.
BoardPanelBinding
Bases: _DefinitionPart
One stage’s result, under the name a panel draws it by.
Parameters
data AnyBoardSection
Bases: _DefinitionPart
A titled region of the canvas. A panel joins a section by naming the section in its own placement.
Parameters
data AnyAttributes
BoardSelection
Bases: _DefinitionPart
A named selection that panels publish to and filter by.
Parameters
data AnyBoardStage
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 AnyAttributes
BoardStage.body
What the stage does.
BoardStage.id
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.name
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()
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 AnyReturn type
BoardStage.validate_control_name_and_inputs()
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.
Return type
BoardStageBody
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, BoardFieldControlBody or BoardControlFilterBody instead.
Parameters
data AnyAttributes
BoardStaticControlDomain
Bases: _DefinitionPart
A value control’s choices listed in the definition.
Parameters
data AnyAttributes
BoardStaticControlDomain.options
The choices the control lists, in order.
BoardValueControlBody
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. The stage reads no input, except the one stage whose column a BoardColumnControlDomain lists.
Parameters
data AnyAttributes
BoardValueControlBody.default
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 is true.
BoardValueControlBody.domain
Where the control’s choices come from. Absent, the viewer types the value.
BoardValueControlBody.label
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.
BoardValueControlBody.multi
Whether the viewer may choose several values. False when absent.
BoardValueControlBody.required
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.validate_default_matches_multi()
Reject a default that is a list when the control holds one value, or one value when it holds several.
Return type
Attributes
BoardValueControlBody.valueType
The type of the values the control holds, as a JSON object with a type, for example {"type": "string"}.
BoardValueControlDomain
Where a value control’s choices come from.
check_definition_top_level()
Refuse a board definition whose top level BoardDefinition refuses.
The definition is checked as 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.ValidationErrorBoardDefinition refuses the definition’s top level.
Return type