Dashboard spec (v1)

The spec is a YAML document you hand to publish_dashboard. The server compiles it into HTML, validates it, runs each dataset's SQL once to seed the data island, and stores the manifest that later refreshes read.

The machine-readable schema is published at https://dashies.ai/schema/dash/v1.json. This page is that schema in prose, and a build guard fails this site when a field or a tile type exists in the schema with no entry here.

Everything on this page is the shape contract. The rules about whether the numbers are right live in Measure correctness and Designing the cube.

Top-level fields

Exactly one of tiles or look is required. Declaring look also forbids theme and layout, because in look mode the markup is yours and there is no generated chrome for either to style.

Source

self is the built-in no-PII Dashies metrics view and needs no setup. A warehouse connection is created in the Dashies web app, never through MCP, and requires a paid plan. Resolution rules and the refusals are in Shared rules.

upload is what makes new data a change to this document rather than something that happens to the dashboard on its own: without it, republishing a byte-identical spec could bind a file uploaded since and move the numbers with nothing in the spec saying so. A new file is a new upload plus a republish naming it. See Build a dashboard from a file.

timezone anchors the schedule, not the SQL. Nothing propagates it into your query. Bucket your dates in your business time zone inside the SQL, and never rely on a session time zone: see SQL dialect notes.

Datasets

A dataset is one SQL statement plus the declaration of what its output columns mean. One to eight per dashboard.

What that statement returns depends on the connection. Against a warehouse connection or the workspace's uploaded-file source, it returns one row per underlying record carrying the columns each number is worked out from, and each number is declared here rather than computed in the SQL: Dashies holds those rows and works the numbers out when a reader opens the page, so a statement that has already aggregated gets aggregated a second time, and a count comes back as the number of groups you made rather than the number of records. Against the built-in self connection, it groups by your dimension keys and selects one aggregate per measure, and those rows ship inside the file. A plain total survives the wrong grain, which is why the mistake lasts: the dashboard reads as correct until somebody adds a count. See Datasets and the four modes.

Each key of dimensions and measures must equal an output column name of the SQL. Letter-case differences are reconciled for you; two output columns that differ only by case are refused, naming both.

How mode is resolved when you omit it

The connection decides which of the two answers below you get.

On a warehouse connection or the uploaded-file source the only mode you can be given is resolved. Those rows stay with Dashies and are queried per request, and the four in-file modes are refused on such a connection rather than chosen, so the table below does not describe it. The measures do not pick a different mode there, but they can stop you reaching it: four of the twelve aggregates the schema declares cannot be worked out on a held dataset, so a dataset declaring one is refused at publish, naming the measures. Measures names which four. One exception to all of this, and it turns on the plan rather than on the connection: on a free plan a dashboard built on the shared Dashies sample data is prepared the in-file way, so the table below is its answer. See Datasets and the four modes.

On the built-in self connection the resolver only ever picks cube or lattice. Both ship aggregates. rows and hybrid ship row-level data to every viewer, so they are always an explicit opt-in and are never chosen for you.

Because the three row-level fields above are refused when mode is absent, a dataset that never declares a mode cannot become rows, hybrid or Parquet by accident.

The trade-offs between the four in-file modes are in Datasets and the four modes.

Dimensions

On a lattice or hybrid dataset every dimension must be bounded: a category dimension needs domains, a date dimension needs buckets. That declaration is what the 50,000-cell estimate is computed from, so an unbounded dimension there is refused rather than guessed at.

Measures

A measure is either an aggregate or a ratio. The two shapes are exclusive.

An aggregate measure:

A ratio measure:

A ratio is the correct way to express an average, a rate or a share. Store the numerator and the denominator as additive measures and let the runtime divide under whatever filter is on screen; a stored average cannot be re-derived once the filter changes.

The schema declares twelve aggregates, and the mode decides which are legal:

rows and resolved take the same eight, because the schema applies one rule to both. So percentile_disc, stddev, variance and mode are what a warehouse or uploaded-file dataset cannot declare at all: there is no other mode for it to be steered onto, so the publish is refused naming the measures. A ratio measure is legal in every mode.

stock: true marks a measure that is a level rather than a flow, so it is never summed across periods. Omitting it on a level is the single most expensive authoring mistake in this product: see Measure correctness.

Units

scale says how the raw number is stored. A currency measure holding whole currency units declares scale: units; a percent measure holding 0.25 declares scale: fraction.

scale "points" cannot be shown by a managed tile: the tiles have no display divisor, so every figure would render 100x its true value. Divide in SQL (avg(pct)/100.0 as share) and declare scale: fraction. (Markup you write yourself may keep it: on a cube, rows or resolved dataset, a look body reading the measure through dashies.data is handed its value with scale: 100 beside it.)

Row-level security

Each viewer is served only the rows they were granted. The filter is applied where the data is queried rather than in the page, so it holds for every tile and for every number a page you wrote yourself asks for: two people open the same URL and see different numbers.

It is an Enterprise capability on a workspace dashboard reading a warehouse. check_readiness reports whether a space has it, in row_level_security, before a spec is written; a publish that arrives without it is refused rather than quietly unfiltered.

A dataset-level entitlement declares which column decides who may see a row:

An identity is one of exactly two forms, and the set is closed:

Both are matched as whole strings and there is no wildcard. A viewer's values are the union over every grant that names them, and an empty union is not an error: that viewer gets a designed page saying they have no access to this dashboard's data. An admin the dashboard has exempted is never in that state: they are served every row rather than the no-access page.

A second designed page covers the state where the dashboard's own record says it filters and the page being served carries no filter for any dataset. Unlike the one above, every viewer gets it: it says the dashboard is being set up to show each person their own rows, nothing is served rather than everything, and publishing the dashboard again is what clears it. A refresh does not, because a refresh does not rewrite that part of what is served.

The dashboard-level entitlement carries one field, admins, which is filtered or unfiltered. Absent means filtered: row-level security applies to everyone including workspace admins, so forgetting to write it cannot widen what anybody sees. unfiltered is honoured, and it exempts admins of the dashboard's own workspace and nobody else: a creator who is not an admin, and every ordinary member, stay filtered. The role is resolved from the workspace membership rather than from anything the page can say, and what the document declares reaches a viewer only once the dashboard has been published carrying it, because a refresh does not rewrite that part of what is served. A workspace admin can also turn the exemption on or off for one dashboard from the app, which takes effect without a publish and wins over what the document says. A dashboard-level block with no dataset-level block is refused - it opts out of a filter that does not exist.

A republish cannot stop the filtering by accident. The block is read off the document being published, so a full republish that omits it is refused at the path row_level_security_removed before anything is written. Stopping on purpose is that key, written by hand at the top level as row_level_security_removed: true; declaring it beside an entitlement block is refused too, which keeps one declaration to one removal. The same code covers the case where Dashies could not read whether the dashboard filters, in a different sentence: on that one, publish again rather than declaring a removal.

Every key value in the data has to be granted to somebody or named in hidden_values. A refresh that finds one that is neither stops: it publishes nothing, the dashboard keeps the numbers from its last successful refresh, and Dashies emails the dashboard's author and every admin of its workspace, naming the first few values plus a count of the rest, and how many rows they account for; the complete list is on the run detail. There is no override and no margin. Grant them or hide them, then refresh.

Two rules hold today and are what a publish carrying the block meets:

• An entitled dataset must declare mode: resolved. The filter is applied where the data is queried rather than in the page, so a dataset that ships its rows to the viewer cannot carry one.
• Row-level security is an Enterprise capability, so the workspace the dashboard lives in has to be on that plan. check_readiness answers whether it is available before you write the block; the refusal codes are in Errors.

Look

look replaces the generated tiles with your own markup.

Exactly one of the two. Every data-dash binding in your markup must resolve against the datasets you declared, or the publish is refused; the roles and attributes are in Runtime attributes.

Declaring look forbids tiles, theme and layout.

Assets

assets declares images the server fetches and inlines into the page, so a logo never travels through an authoring tool as bytes it has to reproduce.

assets:
  logo:
    url: https://www.example.com/brand/logo.svg

Reference an asset as src="asset:logo" in markup (a look body or a custom tile) and as url(asset:logo) in CSS (theme.css or a <style> block). Every reference is replaced by the fetched bytes when the page is built, so the published page is self-contained. A reference to a name that is not declared is refused; a declared asset nothing references is a warning.

Each asset must be an SVG, PNG, JPEG, WebP or GIF by its bytes, at most 512 KiB, and all assets together at most 2 MiB. An SVG carrying a script, a foreignObject, an event attribute or an external reference is refused. The publish report lists every asset with its content type, byte size and sha256. On a later publish the pinned bytes are kept if the URL serves different ones, or if it stops answering, and the report says so. The stored copy stands in only when it is the recorded file; a copy that is not is refused rather than used. A look: { from } republish keeps the stored page byte for byte, so an asset whose bytes would change under it is refused: send the body with look: { html } to change a logo.

Theme

css is the escape hatch for anything the four knobs above do not cover. The custom properties it should target are in Theme tokens.

Check it worked

Publish with dry_run: true. The pipeline compiles, validates and seeds exactly as a real publish would, writes nothing, and reports the resolved mode for every dataset, the compiled byte size against the publish cap, and the rows each dataset seeded.