---
title: "GistUI Protocol v1"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://gistui.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GistUI Protocol v1

**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.

> **Status: Working Draft**
>
> The specification is a Working Draft, written from the reference implementation and precise enough for a second, independent one. The media type `text/vnd.gistui` is not registered yet, and the schema URLs are identifiers, not published files. Details below.

## 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](/docs/protocol/format/) |
| **Recovery** | Numbered rules for every common model slip, so two processors build the same tree from the same imperfect text | [The format](/docs/protocol/format/#recovery) |
| **The tree** | The abstract result of processing, with stable node ids and a JSON form | [The format](/docs/protocol/format/#the-tree) |
| **Catalogs** | How a set of components is described, as a manifest any tool can read | [The format](/docs/protocol/format/#catalogs) |
| **Runtime** | State, expressions, built-in functions, queries, mutations, actions | [The format](/docs/protocol/format/#runtime) |
| **Limits** | Fixed bounds on nesting, nodes, loops, timers and tool calls | [The format](/docs/protocol/format/#limits) |
| **Diagnostics** | A registry of codes, with severity and required order | [Diagnostics](/docs/reference/diagnostics/) |
| **Security** | A threat model and the policies a renderer must apply | [The format](/docs/protocol/format/#security) |
| **Envelopes** | The action a renderer reports, and the capabilities a host declares | [The format](/docs/protocol/format/#envelopes) |
| **Conformance** | Five classes, three profiles, 149 test cases | [Conformance](/docs/protocol/conformance/) |
| **Bindings** | How a program travels over HTTP, MCP and AG-UI, and how it maps to A2UI | [Bindings](/docs/protocol/bindings/) |

## Design principles

1. **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.
2. **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.
3. **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.
4. **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.
5. **Bounded.** No input may make a processor fail, hang or grow without limit.
6. **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

```text
 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](/docs/protocol/why/) — What a shared format gives model providers, app developers and tool builders.
- [Comparison](/docs/protocol/comparison/) — Against OpenUI Lang, A2UI, json-render, MCP Apps and AG-UI, with measurements.
- [The format](/docs/protocol/format/) — A readable tour of the specification, section by section.
- [Conformance](/docs/protocol/conformance/) — Classes, profiles and how to run the 149 cases against your implementation.
- [Bindings](/docs/protocol/bindings/) — HTTP and SSE, MCP, AG-UI and the mapping to A2UI.
- [Implement it](/docs/protocol/implementing/) — 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`](https://github.com/GistUI/GistUI/blob/main/spec/gistui-format.md).

Source: https://gistui.com/docs/protocol/index.mdx