Document specification

A document dashboard shows a document written as data, not code: pages of rows, rows of columns, and columns of blocks such as text, key figures, tables, charts, live values, controls, tiles and inputs. Formulas in the formula language compute values from inputs, parameters, stored history, device operations and price lists. Nothing is built or run as code.

The Document template (document) renders configuration.document. A dashboard without a document shows an empty one. A code dashboard may keep a document under the document key of its configuration and render it with DocumentView from @overvis/hmi-workspace-ui. Another catalog template’s dashboard takes one only when its config.schema.json declares a document key.

The format’s schema is documentType in @overvis/hmi-shared/document, and validateDocument(document, context) checks a document there without network access. The server checks every save; see Checks.

Create a document

• Ask the assistant, for example “make a page that shows the last day’s energy cost, with the price per kWh as an input”. It creates a dashboard with the Document template and opens it. When you ask for changes, it edits the same dashboard.
• In Setup, create a dashboard with the Document template; see Create and publish dashboards. Open Dashboard actions → Edit settings and write the document under the document key of Configuration (JSON).
• In a pulled workspace, run pnpm hmi pull, edit the dashboard’s configuration in setup.db with pnpm hmi sql, run pnpm hmi check, and publish with pnpm hmi push; see Pull a workspace.

Copy, revert, pull and history keep the document with the dashboard’s configuration.

Document

Key	Type	Default	Meaning
format	1	required	The version of this format
refreshSeconds	integer 1–60	2	Seconds between live readings of the visible page
density	comfortable, compact	comfortable	Spacing of tile grids
rotateSeconds	integer 10–600	off	Seconds each page shows before the next one, for wall displays
variables	object of variables	none	Values set by inputs or computed by formulas; see Variables
sources	object of sources	none	Values read from equipment and the HMI API; see Sources
pages	1–12 pages	required	The document’s pages

Pages, rows and columns

A page has an id, an optional name, and up to 60 rows. The first page opens at the dashboard’s own address and every page at /pages/<id>. An id is 1–64 letters, digits, _ and -, and starts with a letter or digit. With more than one page, tabs show each page’s name, or “Page 2” without one.

A row has either columns (1–6) or content, which is one full-width column. A row with a title is a section: the title is its heading. report: true on a titled row adds a Report button for a quick report of its numeric tiles, up to 20 parameters.

A column has content, up to 60 items, and an optional span of 1–12 out of twelve. Columns without a span share what the others leave. Spans add up to 12 at most. From a width of 48 rem (a tablet) up, columns sit side by side; on phones they stack in order.

An item is a block, or a row with kind: "row" whose columns hold blocks only.

{
  "id": "summary",
  "rows": [
    { "content": [{ "kind": "lead", "title": "The retrofit pays back in {payback} years" }] },
    {
      "title": "Costs",
      "columns": [
        { "span": 8, "content": [{ "kind": "markdown", "text": "…" }] },
        {
          "content": [
            { "kind": "metric", "label": "Total", "value": "formatCurrency(total, \"EUR\")" }
          ]
        }
      ]
    }
  ]
}

Texts

Every text is a string, or an object with one string per language, such as { "en": "Costs", "de": "Kosten" }. The document shows the viewer’s language, then English, then the first language in alphabetical order. Labels and titles have 1–200 characters; Markdown up to 20,000.

{name} in a text shows the value of the variable or source value name, formatted for the viewer: numbers with up to two decimals, instants in the workspace’s time zone, ”—” while a value is not known. Use a formula variable with formatCurrency() or formatNumber() for other formats.

Markdown supports paragraphs, emphasis, links, lists, quotes, code, headings (shown below the document’s own headings), rules and GFM tables. Raw HTML is shown as text. Links open in a new tab.

Blocks

Every block has a kind. Keys not listed are refused.

kind	Keys	Shows
lead	title, context?, text? (Markdown)	The conclusion at the top, with context above and text below
heading	text, level? (2 or 3, default 2)	A heading
markdown	text	Text
callout	tone (info, ok, warning, critical), title?, text	A note in the tone’s color
metric	label, value (formula), detail? (Markdown)	A key figure
table	see Tables	A table
chart	see Charts	Bars or lines
image	file, alt, caption? (Markdown)	An image from the workspace’s files, such as photos/pump.jpg
value	parameterId, label?, unit?, decimals? (0–6)	A parameter’s current value with its stale marker
control	control; see Controls	A command or setpoint button
alarms	sourceIds?, parameterIds?	Active alarms, optionally of some alarm rules and automations, or of rules that read some parameters
divider	none	A rule
number	variable, label, description?, min?, max?, step?, unit?	A number field
slider	variable, label, description?, min, max, step?, unit?	A slider with its value
select	variable, label, description?, options (1–50)	{ "value", "label" } options: buttons for up to 7 of up to 20 characters each, a list otherwise
toggle	variable, label, description?	A switch
tiles	tiles (up to 60)	Tiles in the board grid; see Tiles

An input block sets an input variable while the page is open, for the viewer only. A number, slider or toggle needs a number or boolean variable as its kind says; a select needs options of the variable’s type. The value starts from the variable’s default each time the page opens.

Use a slider for a quantity the reader tries out within a known range, such as devices or years, a number for an exact figure or an open range, such as a price, and a select for a few named choices, such as a polling interval.

An image block shows a PNG, JPEG, GIF, WebP or AVIF file uploaded to the workspace, by its path under the workspace’s files. Everyone who can open the dashboard sees the images its saved document shows; other uploads stay with editors, who also see images of documents not saved yet.

A metric shows its formula’s value formatted like a {name} placeholder. A value block shows the parameter’s name unless label is given, and its units unless unit is given; an empty unit hides them.

Tables

Key	Type	Meaning
columns	1–12 of { "header", "align"? }	Headers; align is start or end
rows	rows of cells, up to 500	Rows written out
repeat	{ "over", "cells" }	Rows repeated over a repeat, one cell per column
footer	cells	A totals row
caption	text	Shown under the table

A cell is a number, a text, or { "formula": "…" }. Each row has one cell per column. The first column aligns to the start and the others to the end, unless align says otherwise. A repeated cell’s formula and text see the row’s names. Rows written out come first, then repeated rows, at most 500 together.

Charts

Key	Type	Meaning
title	text	The chart’s accessible name; the caption when caption is absent
caption	Markdown	Shown under the chart
chart	bar, line	Bars by default; history is always lines
format	formula of value, giving a string	Formats axis and tooltip values, such as formatCurrency(value, "EUR")
data	object with a kind	The data, by kind below

data.kind	Keys	Data
static	series (1–8 { "key", "label" }), rows ({ "label", "values" })	values maps a series key to a number or null, which leaves a gap
repeat	over, label (formula), series (1–8 { "label", "value" })	One bar or point per repeated row; value gives a number
history	window (1h, 24h, 7d), parameterIds (1–4), unit?	Stored averages of numeric parameters, with live values at the end

Tiles

A tiles block draws tiles of the Value tiles board: in a grid of 2 columns on a phone, 3 on a small screen, 4 on a laptop and 6 on a wide screen. Small tiles take one cell, wide two cells, large two by two. A page holds up to 60 tiles across its tile blocks.

kind	Keys
value	size, parameterId, sparkline, editable, colors, name?, unit?, decimals?
gauge	size, parameterId, colors, name?, unit?, decimals?, min?, max?
chart	size (wide, large), parameterIds (1–4), window (1h, 24h, 7d), name?, unit?
controls	size, controls (1–4), statusParameterId?, name?

colors is { "zones": boolean, "rules": [...] } with up to 8 rules, checked in order; the first that holds sets the tile’s tone, then the parameter’s own zones apply when zones is true. A rule is { "operator", "value", "tone", "parameterId"?, "label"? }: operator is eq, ne, gt, gte, lt or lte, tone is neutral, info, ok, warning or critical, and a rule without parameterId reads the tile’s parameter. Colors, staleness and gauges behave as in the Value tiles board. A chart tile opens a quick report of its parameters; value tiles with editable: true offer Change to operators and above. Tiles and rules may carry an id UUID.

Controls

A control is a command or a setpoint, in a control block or a controls tile. Operators and above use it; view-only members see it disabled. Each asks for confirmation before it writes.

kind	Keys
command	name, category (start, stop, mode, reset, other), steps (1–20), active?
setpoint	name, parameterId, unit?

A step is { "parameterId", "value" }: the value as text, written in order. active is a condition { "parameterId", "operator", "value" } that marks the command current while it holds.

Variables

variables maps a name to a variable. A name has 1–40 letters, digits and _, and starts with a letter or _. Variables, sources and source values share one set of names. The names index, value, and, or, not, true, false, pi and e are reserved.

kind	Keys	Value
input	default: a number, a string or a boolean	Set by input blocks; the type is the default’s
formula	formula	Computed from other names; the type is the formula’s

Formula variables may read each other in any order, but not in a loop.

Sources

sources maps a name to a source. A source is read as the viewer, with the viewer’s access.

kind	Keys	Gives
live	parameterId	The current value under the source’s name, refreshed with the page
history	parameterId, window (1h, 24h, 7d, 30d), aggregate	One number from stored readings over the window that ends now
api	procedure, input?, values?, refreshSeconds? (60 or more)	Values from the answer of an HMI API procedure
deviceApi	endpointId, operation, query?, body?, values?, refreshSeconds? (15 or more)	Values from the answer of a device’s read operation

A live source’s value has the parameter’s formula type: a number for numeric parameters, a boolean, an instant for date-times, or a string. aggregate is average, min, max, first, latest, delta (latest less first) or sum, of a numeric parameter: a number, or an integer without labels. The history of an integer has only first and latest.

A source without refreshSeconds is read once when the page opens, and again when its input changes; until the new answer arrives, its values keep the last one. A billing.estimate source is priced on the page from the price list, as the server prices it, so it follows its inputs at once. A device read reaches the device and shares the operation’s rate limit with every viewer; see Device API.

API procedures

procedure	Input
billing.prices	none
billing.estimate	the profile, months, effectiveFrom; see Estimate costs
readings.aggregate	parameters, from, to; the workspace is the dashboard’s
readings.minMax	parameters, from, to; the workspace is the dashboard’s
readings.days	parameters, from, to, timezone; the workspace is the dashboard’s

The API reference describes each input and answer.

Inputs and values

input, query and body are JSON. An object of exactly { "formula": "…" } anywhere in them is replaced by the formula’s value: a number, a string or a boolean, with instants and durations as milliseconds. While one of these formulas is not known, the source is not read.

values maps a name to { "path", "type"? }: path is a JSON pointer into the answer and type is number, string, boolean or instant, read from date-time text or milliseconds. For a procedure, the type comes from its answer’s schema, with date-time text as an instant, and type is needed only where the answer allows several or to read a date-time as string. For a device, type is required. A value that is missing or of another type is not known.

"sources": {
  "estimate": {
    "kind": "api",
    "procedure": "billing.estimate",
    "input": {
      "profile": {
        "deviceGroups": [
          { "devices": { "formula": "meters" }, "parametersPerDevice": 5, "pollSeconds": 60, "endpoints": { "formula": "meters" } }
        ]
      },
      "months": 24
    },
    "values": {
      "firstMonth": { "path": "/months/0/totalMicroEur" },
      "total": { "path": "/totalMicroEur" }
    }
  }
}

Repeats

A table’s repeat.over and a repeated chart’s over repeat rows:

kind	Keys	Rows
range	from, to (formulas)	One row per whole number from from to to; index is the number
list	source, path, fields?	One row per item of the list at path in an api or deviceApi source’s answer; index counts from 1

fields maps a name to { "path", "type"? } inside each item, like values. A row’s formulas and texts see index and its fields besides the document’s names.

Formulas

Formulas are in the formula language. They see the variables, the live and history sources by name, and the source values; repeated rows also see index and their fields, and a chart’s format sees value. The clock and calendar functions use the workspace’s time zone, and sunrise() and sunset() its location. formatNumber(), formatCurrency() and formatPercent() format in the viewer’s language.

A formula gives an unknown value while a name it reads is not known, such as before a source is read, and when it fails for the values, such as by dividing by zero. Unknown values show as ”—”.

Checks

The server checks the document each time a dashboard is saved, from Setup, the API or hmi push. It refuses a change that adds errors, such as a formula that reads a name that does not exist or a block for a parameter that is not in the workspace. Each error names the key it is at. Errors the document already had, such as a reference to a parameter deleted since, do not block other changes. Warnings, such as a variable nothing reads, never block. hmi check checks documents in a pulled workspace before you push. For the API, see Check a document.

Example

A page that prices the last 24 hours of an energy meter at a price the viewer enters, beside a chart of its power. Replace the two parameter IDs with your meter’s.

{
  "format": 1,
  "variables": {
    "price": { "kind": "input", "default": 0.25 },
    "cost": { "kind": "formula", "formula": "formatCurrency(energy * price, \"EUR\")" }
  },
  "sources": {
    "energy": {
      "kind": "history",
      "parameterId": "3f2b8c1e-5d4a-4e6b-9a7c-1b2d3e4f5a60",
      "window": "24h",
      "aggregate": "delta"
    }
  },
  "pages": [
    {
      "id": "energy",
      "rows": [
        {
          "content": [
            {
              "kind": "lead",
              "title": "The last 24 hours cost {cost}",
              "text": "{energy} kWh at the price per kWh you enter."
            }
          ]
        },
        {
          "columns": [
            {
              "span": 4,
              "content": [
                {
                  "kind": "number",
                  "variable": "price",
                  "label": "Price per kWh",
                  "min": 0,
                  "step": 0.01,
                  "unit": "EUR"
                }
              ]
            },
            {
              "span": 8,
              "content": [
                {
                  "kind": "chart",
                  "title": "Power",
                  "data": {
                    "kind": "history",
                    "window": "24h",
                    "parameterIds": ["9c4d2e7a-1b3f-4a5c-8d6e-7f8a9b0c1d2e"]
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Limits

What	Limit
Pages	12
Rows of a page	60
Columns of a row	6
Items of a column	60
Tiles of a page	60
Color rules of a tile	8
Parameters of a chart tile or history chart	4
Controls of a controls tile	4
Variables	100
Sources	30
Values of a source, fields of a list	50
Rows of a table or chart	500
Columns of a table	12
Series of a chart	8
Options of a select	50
Characters of a formula	2,000

Related

• Formula language
• Value tiles dashboard
• Document components for code dashboards, for documents written as code
• Dashboard host contract