GistUI Protocol v1

An open, model-agnostic format for user interfaces that a language model writes and any app can render while it streams. What it specifies, and its status.

GistUI Protocol v1 is the open specification behind GistUI: a text format for interfaces that a language model writes and a program renders while the text is still arriving. Its formal name is GistUI Format 1.0.

It is a content format, like HTML or Markdown. It says what a program means, not how it travels. It is independent of the GistUI library: anyone can write a generator, a parser or a renderer for it, in any language, and test it against a public conformance suite.

The problem it addresses

Every generative-UI system has to answer the same four questions. Today each answers them privately.

Question	Without a shared format
What does the model write?	A vendor’s JSON shape or DSL, taught by a vendor’s prompt
What happens when the model gets it slightly wrong?	Undefined. Each parser recovers, or fails, in its own way
What may the generated UI do?	Whatever the renderer allows. Safety is an implementation detail
How does the app hear about a click?	A vendor’s callback shape

So an answer generated for one renderer cannot be shown by another, a saved conversation is tied to one library version, and nobody can check a parser against anything but itself.

What v1 specifies

Part	What it defines	Page
Syntax	Statements, components, tables, expressions: a complete grammar	The format
Recovery	Numbered rules for every common model slip, so two processors build the same tree from the same imperfect text	The format
The tree	The abstract result of processing, with stable node ids and a JSON form	The format
Catalogs	How a set of components is described, as a manifest any tool can read	The format
Runtime	State, expressions, built-in functions, queries, mutations, actions	The format
Limits	Fixed bounds on nesting, nodes, loops, timers and tool calls	The format
Diagnostics	A registry of codes, with severity and required order	Diagnostics
Security	A threat model and the policies a renderer must apply	The format
Envelopes	The action a renderer reports, and the capabilities a host declares	The format
Conformance	Five classes, three profiles, 149 test cases	Conformance
Bindings	How a program travels over HTTP, MCP and AG-UI, and how it maps to A2UI	Bindings

Design principles

Text, line by line. A statement is complete when its line ends. A renderer can show each one as it arrives; a model can write the layout first and fill it in.
Directed by a catalog. Meaning never depends on text that has not arrived. A bare word is an enum, a flag or a reference according to the component it is in.
Mistakes are part of the format. Models make the same small slips again and again. The format says how each is read, and requires every processor to do the same.
The program is untrusted. It is model output, possibly steered by content the model read. It cannot run code, and every rule with a security consequence is normative.
Bounded. No input may make a processor fail, hang or grow without limit.
Not a transport. How a program travels is left to bindings, so it fits into HTTP streams, MCP and AG-UI as they are.

Roles

 generator  ──writes──►  program text  ──►  processor  ──►  tree + diagnostics
 (a model)                                     ▲                    │
                                            catalog            runtime (state, tools)
                                                                    │
                                                              renderer (draws)
                                                                    │
                                                         action envelope ──► host

A generator writes programs. Usually a model with a system prompt.
A processor turns text and a catalog into a tree and a list of diagnostics.
A runtime evaluates expressions, holds state and calls tools.
A renderer draws the tree and reports interaction.
A catalog says which components exist and what they take.

Read on

Why a standard

What a shared format gives model providers, app developers and tool builders.

Comparison

Against OpenUI Lang, A2UI, json-render, MCP Apps and AG-UI, with measurements.

The format

A readable tour of the specification, section by section.

Conformance

Classes, profiles and how to run the 149 cases against your implementation.

Bindings

HTTP and SSE, MCP, AG-UI and the mapping to A2UI.

Implement it

What to build, in what order, to write a processor in another language.

The full specification text is in the repository: spec/gistui-format.md.