Generating dashboards with AI

Complete dashboards and reviewed changes

This guide describes complete declarative dashboard layouts. For a model to propose bounded filters, sorting, chart choices or table fields in an existing workspace, use AI-assisted analysis. AnalysisPlan has its own schema and explicit review/apply lifecycle; it is not a Dashboard spec. Both require application-owned data authorization and model integration.

To compose visually without a model, use Studio. It connects real public API data and exports native React components. Its versioned editor project is a separate document from a Dashboard spec.

The schema

quartileSchema is a JSON Schema (draft 2020-12) with 28 definitions. 16 of them are components a spec can name: LineChart, AreaChart, BarChart, BarList, DonutChart, Funnel, Sparkline, Histogram, ScatterPlot, Heatmap, CalendarHeatmap, Sankey, BoxPlot, KPI, DataTable, FilterBar. The rest describe fields, measures, formats, table columns, a single spec and a Dashboard: a list of specs on a 12-column grid, linked by one selection.

It ships as the quartileSchema export and as @quartile/react/schema.json. You can also fetch the schema from this documentation site; the source is spec/schema.ts. SPEC_COMPONENTS lists the component names. Specs name datasets and fields as strings and formats with names, Intl number options or typed descriptors; callbacks remain React-only. Runtime format validation checks Intl option conflicts as well as structural rules.

Try it

Edit the spec. The status line is validateSpec's verdict; the dashboard underneath is SpecView rendering it with this site's sample orders. Load invalid to see the errors, or brush the line to see the selection link the generated views.

Prompting a model

Tell the model which datasets exist and which fields they have, and include the schema. Many model APIs can also take a JSON Schema for structured output; they support different subsets of the standard, so validate the result either way.

import schema from '@quartile/react/schema.json';

const system = [
  'Answer with one JSON object that validates against this JSON Schema.',
  'Datasets: "orders" (one row per order: id, date, region, channel, category, product, amount).',
  'Use only fields from those datasets.',
  'Order rows repeat dates. For a daily LineChart, encode y as { field: "amount", aggregate: "sum" }.',
  JSON.stringify(schema),
].join('\n\n');

Validate, then render

validateSpec reports unknown components, unknown properties, wrong types, out-of-range values and missing required fields. Each error has a JSON Pointer path and a sentence you can show a person or send back to the model.

import { SpecView, validateSpec } from '@quartile/react';

const spec = JSON.parse(modelOutput);
const result = validateSpec(spec);   // { valid, errors: [{ path: '/layout/3/curve', message }] }

// SpecView validates too: invalid items render an error card in place instead of throwing.
<SpecView spec={spec} data={{ orders, daily }} />

SpecView runs the same validation first. Invalid items, unknown components and missing datasets render an error card in their place, so one bad item does not take down the dashboard.

Sending errors back

Each error names the path and what was expected, so the list can go straight back to the model with a request for a corrected spec. Cap the attempts.

async function generateSpec(question: string, attempts = 3) {
  let messages = [{ role: 'user', content: question }];
  for (let i = 0; i < attempts; i++) {
    const text = await callYourModel(system, messages);   // your model client
    let report: string;
    try {
      const spec: unknown = JSON.parse(text);
      const { valid, errors } = validateSpec(spec);
      if (valid) return spec;
      report = errors.map((e) => `${e.path || '/'}: ${e.message}`).join('\n');
    } catch {
      report = 'Return valid JSON without a Markdown code fence.';
    }
    messages = [
      ...messages,
      { role: 'assistant', content: text },
      { role: 'user', content: `That spec is not valid:\n${report}\nReturn a corrected spec.` },
    ];
  }
  throw new Error('No valid spec');
}