AI Reporting Specification Draft 1.1

Declare the report.
Trust the host.

AIRspec is a portable JSON format for AI-generated dashboards and reports. A model writes the document; your application validates and renders it with trusted code. Nothing the model produces is ever executed.

Try the live demo → Read the specification View examples JSON Schema
report.airspec.jsonwritten by the model
your applicationtrusted renderer

Sales Overview

Year to date ▾
Revenue
$1.28M
▲ 12.4%
Orders
4,213
▲ 6.1%
Revenue by region
West
East
North
South
OrderStatusTotal
ORD-8841Open$12,400
ORD-8836Delivered$8,150

The left side is the entire artifact the AI produces — declarative JSON, validated against a published schema. The right side is yours: trusted components, your data broker, your authorization. Charts use AIRMark, the spec's built-in mark-and-encoding grammar.

The one rule

The AI produces configuration. Your app owns all execution.

An AIRspec document cannot call an API, reference a URL, embed a credential, run a formula, or inject HTML. Those capabilities are structurally absent from the format — not merely discouraged. Every document passes five validation layers before a single pixel renders.

01 / DEFINE

A document, not a program.

Any model can describe the report using the published schema and your Source Catalog. Its output remains inert JSON.

02

Prove it safe.

Five ordered validation layers reject unknown structure, invalid references, unauthorized fields, and unsafe AIRMark.

03

Resolve data privately.

The broker executes stored logical requests with the viewer's authorization and credentials that never reach the document.

04

Draw with trusted parts.

Your component registry renders the validated layout. Failures stay isolated to the component that caused them.

Anatomy of a document

Six top-level parts describe any report.

Every element is declarative, allowlisted, and independently validated.

report.airspec.json { root object }
Definition
meta

identity — title, description, and discovery tags.

parameters

inputs — typed controls whose values are validated at runtime.

datasets

requests — logical sources and fields, never endpoints or query strings.

Experience
layout

composition — a responsive tree of trusted components and AIRMark charts.

theme

preference — palette, density, and locale beneath Host accessibility rules.

interactions

behavior — fixed drilldown, navigation, parameter, refresh, and export actions.

Conformance classes

Adopt it in three steps.

Each class is a superset of the last, so a Class A host can grow into AVI without breaking a single stored document.

A

Core

Layout, text, metrics, tables, filters, and datasets. A complete working reporting system with no charting at all.

The foundation
AV

Visualization

Everything in Core plus the AIRMark chart grammar — bars, lines, areas, arcs, layers, facets, and tooltips.

Adds charts
AVI

Interactive

Everything in Visualization plus cross-component interactions: chart-to-filter drilldowns, record navigation, exports.

Adds interactions
Security by construction

The model gets the blueprint. Your data stays in your application.

In the standard AIRspec flow, the model receives a schema and a catalog of safe, logical names — not business rows, credentials, database access, or internal endpoints. It returns inert report structure. Only after validation does your trusted server fetch authorized data and render it.

The model receives Schema + logical catalog

Enough context to describe the report: approved sources, field names, capabilities, and limits.

Your application keeps Rows + credentials + execution

The Data Broker retrieves authorized rows server-side and passes them directly to trusted renderers.

Not available in the AIRspec document language
eval() data.url <script> credentials fetch() SELECT * ${expression} href="https://…" dangerouslySetInnerHTML