AIRspec

SQL gave databases a safe language for questions. AIRspec gives AI a safe language for reports: dashboards from a sentence, emitted as declarative JSON. No code, no expressions and a closed vocabulary

Comment

Inspiration

Everyone I know right now has the same pain point. Someone in sales or operations needs a report, so they file a ticket, and a developer stops real work to write a dashboard that will be obsolete in a month. AI should fix this, but the current answer is to let a model write executable chart code against production data, which is a security nightmare. I wanted the opposite trade: give users total freedom to ask for any report in plain English, while the data itself stays behind locks that only developers control. The insight was that the AI never needs to touch data at all. It only needs to describe a report.

What it does

AIRspec is an open specification that lets an AI generate complete interactive dashboards as declarative JSON documents. A document says what to show, how to chart it, what filters and interactions exist. It contains no code and no expressions, only a closed vocabulary defined by a JSON schema. The host application validates every document in layers: schema validation, semantic checks like dangling references, and authorization against a catalog of datasets where developers declare exactly which data, fields, and operations are allowed. A data broker executes only catalog approved queries. A deterministic rendering engine draws the same pixels from the same document every time.

The payoff is the security model. Users run any report they can describe, instantly, with no developer in the loop. Developers authorize datasets once and sleep fine, because a generated document physically cannot reach anything outside the catalog, and anything invalid is rejected with precise errors before it renders.

How I built it

I wrote the specification first and let it drive everything else. The spec covers documents, datasets, filters, parameters, a charting grammar called AIRMark, theming, interactions, and a structured math system for derived fields that allows arithmetic like quantity times price as a JSON tree with a fixed operation vocabulary, so there is still nothing to inject and nothing to eval.

Around the spec I built the published JSON Schema, a conformance suite of valid and invalid fixture documents, a browser validator that runs entirely client side, and a reference rendering engine released on npm as a set of packages with a golden fixture test suite. Our demo app runs on Supabase edge functions with a validate and retry loop, so when the model produces an invalid document, the errors go straight back to it as machine readable JSON pointers and it corrects itself before the user ever sees a failure.

For all AI generation I used OpenAI 5.6, and I leaned on it heavily across the whole project: drafting and stress testing the spec, writing fixtures, implementing and debugging the engine, and handling npm and site deployments. The model was effectively a team member with a very good memory for JSON Schema.

Challenges I ran into

The population pyramid nearly broke me. One chart went through every failure mode the architecture can have: the generator invented column names it remembered from a famous UN dataset instead of using our catalog, the spec turned out to be silent on how aggregate outputs are named so three implementations disagreed, and the data broker quietly appended a rollup total row that survived every filter the model threw at it, including an explicit whitelist of all 21 valid age groups, because rollup rows are created after filtering runs. The chart rendered perfectly except for one mystery bar labeled undefined.

Each failure forced a systemic fix rather than a patch. Catalog field lists now get injected into the generation prompt. Metric aliases became required in the spec so output naming can never be ambiguous. The engine now refuses partial rows with an error that names the missing field and lists the keys it actually received. The hardest lesson was cultural: every layer must either honor a feature or loudly refuse it. Silent fallbacks cost me more debugging hours than actual bugs did.

Accomplishments that I'm proud of

The security model works and it is not theoretical. Reports run against real authorized data with the AI locked out of the data path entirely. The whole ecosystem is live: the spec and schema at airspec.dev, the conformance suite, the validator page, and the engine on npm with every chart type backed by golden tests. I proved the spec is model independent by swapping generators and getting conformant documents from a different vendor on the first try. And I shipped real features through a disciplined amendment process, including mirrored axes for population pyramids and the derived fields math system, each with spec text, schema changes, and fixtures landing together.

What I learned

Constraints make AI more capable, not less. A closed vocabulary with a validator in the loop produces better dashboards than freeform code generation, because every error is precise and the model can fix its own work. I learned that specifications fail in silence, so anything two implementations could interpret differently must be written down normatively. And I learned to route every bug to its layer: generator, spec, validator, broker, engine, or renderer. Once the taxonomy existed, a single screenshot was usually enough to know exactly who was guilty.

What's next for AIRspec

Catalog field statistics, so generators know value ranges and units instead of guessing them. Named color schemes and continuous color scales with normatively pinned ramps. A samples gallery generated from the conformance fixtures so any app can offer a chart type picker. Streaming generation for progressive rendering of large documents. And I want other implementations: the spec, schema, and conformance suite are open precisely so that anyone can build a renderer or broker and prove it correct against the same fixtures I use.

Built With

Share this project:

Updates