Skip to content

The Open Standard for Generative UI

22.7 KB
Raw Blame

The OpenUI Prompt and LibrarySpec

1.0

This document defines what is sent to the model: the LibrarySpec, the system prompt generated from it, and the conversation the model sees. It also defines the marker lines a host stores messages with. MUST, MUST NOT, SHOULD, and MAY are used as in RFC 2119.

For the language, see language.md. For the big picture, see overview.md.

1. Overview

The model learns your UI system from two places:

  1. The system prompt. Generated from the LibrarySpec and a set of options (section 4). It teaches the language, the component list, and only the features the client supports.
  2. The conversation. User messages, the model's earlier OpenUI Lang responses, and context the host adds (error reports, form values, click data, the current program in edit mode).

Nothing else is sent. The prompt MUST NOT teach features the target client does not support.

2. The LibrarySpec

A LibrarySpec is one JSON document.

field meaning
id Optional. The library name, for example support. toSpec() emits it when the library has one. A library made with extend does not inherit it.
version Optional. The library version, for example 1.2.0. toSpec() does not emit it. A host that versions its library adds it.
root Optional. The root component name, for example Card.
schema The validation schema (JSON Schema). Top-level properties names the components, $defs has one entry per component and per action a prop refers to, and functions and actions hold the params of the custom functions and actions (section 2.3).
components Per component: signature and description, derived from schema.
componentGroups Optional. Named groups that split the component list into titled parts.
functions Custom functions: signature and description.
actions Custom actions: signature and description (section 2.5).

Example:

{
  "id": "support",
  "root": "Card",
  "schema": {
    "properties": {
      "Card": { "$ref": "#/$defs/Card" },
      "Button": { "$ref": "#/$defs/Button" }
    },
    "$defs": {
      "Card": {
        "type": "object",
        "description": "A container",
        "properties": {
          "children": { "type": "array", "items": { "$ref": "#/$defs/Button" } }
        },
        "required": ["children"]
      },
      "Button": {
        "type": "object",
        "description": "A clickable button",
        "properties": {
          "label": { "type": "string" },
          "action": { "$ref": "#/$defs/ActionExpression" },
          "variant": { "type": "string", "enum": ["primary", "secondary"] }
        },
        "required": ["label"]
      },
      "ActionExpression": {
        "anyOf": [
          { "type": "object", "properties": { "type": { "const": "open_url" }, "url": { "type": "string" } }, "required": ["type", "url"] },
          { "type": "object", "properties": { "type": { "const": "continue_conversation" }, "context": { "type": "string" } }, "required": ["type"] },
          { "type": "object", "properties": { "type": { "type": "string" }, "params": { "type": "object" } }, "required": ["type"] }
        ]
      }
    },
    "functions": {
      "Percent": {
        "description": "Format part / total as a percentage",
        "params": {
          "type": "object",
          "properties": {
            "part": { "type": "number" },
            "total": { "type": "number" }
          },
          "required": ["part", "total"]
        },
        "returns": { "type": "string" }
      }
    },
    "actions": {
      "CopyToClipboard": {
        "description": "Copy text to the clipboard",
        "params": {
          "type": "object",
          "properties": { "text": { "type": "string" } },
          "required": ["text"]
        }
      }
    }
  },
  "components": {
    "Card": {
      "signature": "Card(children: Button[])",
      "description": "A container"
    },
    "Button": {
      "signature": "Button(label: string, action?: ActionExpression, variant?: \"primary\" | \"secondary\")",
      "description": "A clickable button"
    }
  },
  "functions": {
    "Percent": {
      "signature": "Percent(part: number, total: number) → string",
      "description": "Format part / total as a percentage"
    }
  },
  "actions": {
    "CopyToClipboard": {
      "signature": "CopyToClipboard(text: string)",
      "description": "Copy text to the clipboard"
    }
  }
}

2.1 id and version

id and version are metadata. A host uses them in the library= attribute of a stored message (section 7) and to name a prompt version. They do not change how a program is parsed.

2.2 root

root names the library's root component, used in the entry rule (language.md, section 2.2). When present, it MUST name a component in components. Without root, only a statement named root is an entry.

2.3 The validation schema

The schema is the single source of truth for a component's arguments.

  • The key order of a component's properties in $defs is its positional order. Button("Save", a, "primary") maps label, action, variant in that order.
  • required lists the props that must be present. A prop's default fills a missing required argument before the component is dropped.
  • A prop that takes a component is a $ref to that component's $defs entry, { "$ref": "#/$defs/Card" }, or an anyOf of such $refs. A list of components puts this in its items.
  • An action prop is { "$ref": "#/$defs/ActionExpression" } and takes any action. The ActionExpression entry describes the legacy action objects ({ "type": ... }). A prop that takes only some actions is an anyOf of $refs to action names, for example #/$defs/CopyToClipboard and #/$defs/OpenUrl, each with its own $defs entry.
  • A reader classifies each $ref by its name. Components are the names in the schema's top-level properties. Actions are the names in actions plus the built-in names ActionExpression, OpenUrl, and ToAssistant.
  • The schema has no marker for binding props. A binding prop has only its value type in the schema, for example { "type": "string" }. Its signature prints it as $binding<string> (section 5.1), and that is where a reader learns it.

Readers MUST keep the key order of properties when they read the schema, because it is the positional order.

2.4 Derived signatures

Each entry in components has a signature and a description. The signature is derived from the schema. If they disagree, the schema wins, and a consumer SHOULD rebuild the signature from it. The one exception is $binding<type>, which only the signature carries. The format is in section 5.

2.5 Custom functions and actions

A library declares pure functions with defineFunction({ name, description, params, returns, fn }). The schema keeps its description, params (a JSON Schema object whose key order is the positional order, as for components), and returns in schema.functions. The LibrarySpec's functions keeps its signature and description. fn never serializes. It receives one object keyed by the params names. Each client implements the function itself.

A program calls a custom function like a built-in, with the @ prefix and positional arguments in the key order of params:

share = TextContent(@Percent(done, total))

The prompt lists custom functions next to the built-ins. Lookup goes to built-ins first, then custom functions. A call to a name that is not a built-in, an action, or a custom function evaluates to null, like an unresolved reference, and reports unknown-function. The statement is not dropped (language.md, sections 3.6 and 8.2).

Custom actions. A library declares its own actions with defineAction({ name, description, params }). The schema keeps their description and params in schema.actions, with no returns. The LibrarySpec's actions keeps their signatures and descriptions. A program uses one like a built-in action, @CopyToClipboard("text"), alone or inside Action([...]). The client does not run it. The host receives it in onAction (language.md, section 6.3). The prompt lists custom actions with the built-in actions.

Fixtures: evaluation/*-function-*, errors/*-unknown-function-*, actions/*-custom-*

2.6 What the spec does not do

The LibrarySpec drives prompt generation and validation, not rendering. Each platform writes its components natively and decides how they look and behave, including which props bind to state and how inputs attach to forms.

2.7 Output from the tools

library.toSpec() returns the document above. library.toJSONSchema() returns the schema alone. The CLI command npx @openuidev/cli generate writes the system prompt and, with --out prompt.txt, a prompt.spec.json beside it. --json-schema prints the schema alone. --spec prints the full spec.

Fixtures: none. The spec shape is checked on the library, not by program fixtures.

2.8 Extending a library

library.extend({ components, functions, actions }) returns a new library and leaves the base unchanged.

  • components.add appends components. An entry { component, slots } also adds the component to those slots' $ref unions. A slot is "Parent.prop", or "Parent" when the parent has one content slot.
  • components.override replaces a component by name. Every slot that referred to the old one refers to the new one.
  • components.remove drops components from the list, from every slot union, and from componentGroups. Removing the root, or the only type a prop accepts, is an error.
  • functions.add and actions.add add custom functions and actions (section 2.5).
  • Adding a name that already exists is an error.

The result is an ordinary library. Its LibrarySpec follows this section, without the base's id.

Fixtures: none. Checked on the library.

3. Rules for libraries

3.1 Conformance

  • Component names MUST start with an uppercase letter and match the identifier rule.
  • Custom function and action names MUST start with an uppercase letter, like the built-ins (@Percent).
  • Required props MUST come before optional props in positional order. A required prop that has a default counts as optional here, so it may be added at the end.
  • A library MUST NOT define components named Query, Mutation, or Action.
  • A library MUST NOT use a built-in name for a component, a function, or an action. New built-in names are reserved when added.
  • Custom functions MUST be pure and synchronous. They read their arguments and return a value. They do not touch state, the network, or the clock.
  • root, when present, and every component in componentGroups MUST exist in components.

Fixtures: none. These are definition-time checks on the library.

3.2 Backward compatibility

Stored programs are plain text. They stay readable as long as libraries follow these rules:

  1. Only add props at the end. Never reorder props. Never remove a prop.
  2. New required props need a default. An old program cannot supply it, so the default fills it. With a default, the prop counts as optional (section 3.1), so it goes at the end, as rule 1 says.
  3. New built-in names are reserved. Library components and functions MUST NOT use them.

Position is the meaning of an argument, which is why rule 1 matters most. overview.md, section "Keeping stored UIs working", says the same in plain words.

Fixtures: none. These are authoring rules for library owners.

4. Prompt generation

4.1 Determinism

The system prompt is a function of the LibrarySpec and the options. The same inputs give byte-identical prompts on every platform.

The entry point is generateSystemPrompt({ library, promptOptions }). The flat generatePrompt(spec) form is deprecated.

Fixtures: none in spec/fixtures/1.0/.

4.2 Options

option effect
toolCalls Teaches Query, Mutation, and @Run. Defaults to true when tools is given.
bindings Teaches $variables, @Set, @Reset, and $binding<type> props. Defaults to true when toolCalls is on.
builtinFunctions Lists the built-in functions even when toolCalls and bindings are off.
editMode Teaches editing by changed statements (section 6.4).
inlineMode Teaches prose plus fenced code.
tools Tool descriptors: a name string, or { name, description?, inputSchema, outputSchema, annotations? }.
preamble, examples, toolExamples, additionalRules Extra text the host adds to the prompt.

The built-in function section appears when toolCalls or bindings is on, or when builtinFunctions is true. Custom functions are listed in the same section, which prints whenever the library has any, since they also work in plain props.

The inline mode section teaches that openui-lang goes inside fences, with prose around them, and that a question gets an answer in text only.

4.3 What the 1.0 prompt teaches

  • The entry statement root, written first.
  • Positional arguments only, with optional arguments left out from the end.
  • One action needs no wrapper. Several go in Action([...]).
  • Restricted action slots and $binding<type> props, when the library has them.

4.4 Order of the prompt

  1. The syntax rules: statement shape, positional arguments, and the entry statement root.
  2. The component list (section 5).
  3. The built-ins and the tool section, when the options turn them on, and the custom functions, when the library has any.
  4. The hoisting and streaming guidance.
  5. The edit mode and inline mode sections, when the options turn them on.

Components appear in the order they are listed in components. componentGroups split the list into titled sections. A group is { name, components, notes? }. Components in no group go under "Other".

Fixtures: none in spec/fixtures/1.0/.

5. Component signatures and descriptions

Each component is one line in the prompt: the signature, a separator, and the description.

Button(label: string, action?: ActionExpression, variant?: "primary" | "secondary")

The separator is a space, an em dash, and a space, followed here by A clickable button. The line MUST stay on one line.

5.1 Signature format

  • Primitive types print as string, number, boolean, any.
  • Enums print as quoted alternatives joined by |.
  • Arrays print as T[].
  • Inline objects print as {field: type}.
  • Unions are joined by |.
  • An optional prop has ? before the colon: variant?: "primary".
  • A prop that binds to state prints as $binding<type>.
  • A restricted action slot prints its actions with @: share?: @CopyToClipboard | @OpenUrl.
  • Names such as ActionExpression come from ids the library gives to shared schemas.

5.2 Descriptions

A description SHOULD say what the type does not: units, ranges, and when to use each enum member. It SHOULD NOT repeat the type.

5.3 Error hints

Error hint fields do not reuse the signature line. They carry a shorter form: prop names only, with required props marked by a star (language.md, section 8.3).

Fixtures: none in spec/fixtures/1.0/.

6. The conversation

6.1 History

The model's earlier responses appear in history as the OpenUI Lang text it wrote, with surrounding prose in inline mode.

The host removes every marker line (section 7) from history before the model sees it. The rules in section 3.2 keep stored programs readable across library changes.

Fixtures: none in spec/fixtures/1.0/.

6.2 Error feedback

When a response had errors, the host SHOULD send the structured error list in the next request. The wire shape is in language.md, section 8.3. Each error has a hint.

Fixtures: errors/

6.3 Action events

A user action that continues the conversation becomes the next user turn. It has three parts:

  • the message, written for people (@ToAssistant("Save order"));
  • the context, any value the program passed as the second argument: a string, number, object, or array;
  • the form state.

The host receives context unchanged in params.context. How it reaches the model is up to the host (see "Reference format" below). The host writes the context and form state in a context section (section 7). The event shape is in language.md, section 6.3.

Form state is read when the action runs, not when the click starts. A @Set earlier in the same Action([...]) is visible in the form state.

One action can stand alone in an action position:

Button("Save", @ToAssistant("Save order"))

This equals Button("Save", Action([@ToAssistant("Save order")])). It works for @ToAssistant, @OpenUrl, @Set, @Reset, @Run, and custom actions. Several actions need Action([...]). A plain list of actions is data, not an Action.

Reference format. Hosts may use their own format. The reference chat client and the reference backend use this one. The user turn is stored as:

]]>openui:content
<message text>
]]>openui:context
["User clicked: <message>", <formState object>, <context value if any>]

The model receives one user message: <message text>, a newline, then context and form values = <that JSON>. All marker lines are removed. The third element, the @ToAssistant context, is new in 1.0. Earlier assistant turns reach the model as their program text only, with markers and stored form state removed.

Fixtures: actions/

6.4 Edit mode

With editMode on, the host sends the current program with the request. The model answers with a patch, only the changed statements, and the host merges it into the current program after it finishes streaming. Without editMode, every response is a complete program.

The merge uses the same statement boundary rules as parsing (language.md, section 1.4), including ternaries that span several lines. The merge rules are in language.md, section 7.

Fixtures: editing/

7. The message protocol

A host stores a response as text, with the program wrapped in marker lines. The model never writes or sees these lines.

7.1 Marker lines

marker     = "]]>openui:" kind [ "?" attributes ] line_end ;
kind       = lowercase_letter { lowercase_letter } ;
line_end   = "\n" | "\r\n" | end of message ;

The kind ends at the first ? or line end. Example:

]]>openui:content?library=support%401.2.0

The attributes are a query string in application/x-www-form-urlencoded form, as produced by URLSearchParams. Pairs are key=value, joined by &. %40 is the encoded @, and a space is written +. Readers decode the string the same way and accept an unencoded @.

A marker counts only at the very start of a line. ]]>openui: in the middle of a line is ordinary text, with one exception: a content marker (]]>openui:content followed by ?, a line end, or the end of the message) in the middle of a line starts a new line there. A regenerated response is written right after the cut-off text of the failed one, and this keeps the last content winning.

Fixtures: none in spec/fixtures/1.0/.

7.2 Kinds and sections

kind shape body
content Opens a section. The program, or prose with fenced programs.
context Opens a section. JSON defined by the host. OpenUI requires no structure.
end One line. No body. The stream reached its last chunk.

A section body starts on the line after its marker and runs up to the next marker line, or to the end of the message. The newline just before the next marker line is not part of the body.

In a stored message, a missing end line means the stream died before it finished. A reader still renders the content.

The reference chat client stores [formState] as the context of an assistant turn, and the array in section 6.3 for a user turn. That is its own usage, not a shape OpenUI requires.

Example:

]]>openui:content?library=support%401.2.0
root = Card([title, saveBtn])
title = TextContent("Order")
saveBtn = Button("Save", @ToAssistant("Save order", {"orderId": 42}))
]]>openui:context
{"formState":{"note":"rush"},"context":{"orderId":42}}
]]>openui:end

Fixtures: none in spec/fixtures/1.0/.

7.3 Reading messages

  1. Last content wins. With more than one content section, the reader uses the last one. A context section or end line that comes before it belongs to an earlier attempt and is ignored.
  2. Text before the first marker. It is the content when the message has no content marker. Otherwise the reader ignores it.
  3. Unknown attributes are ignored.
  4. Unknown kinds. The reader strips the marker line and its text up to the next marker line.
  5. Text after end. Hosts never write it. A reader keeps it with the section the end line interrupted.
  6. Display. The reader never shows marker lines, and never shows the context section as content.

While a response streams, the last line may be incomplete. If that line starts with ]]>openui:, or is a prefix of it, the reader holds it back until its newline arrives or the stream ends. A partial content marker at the end of a line is held back the same way.

Fixtures: none in spec/fixtures/1.0/.

7.4 Writing messages

The host writes the markers. It puts a content line before the response and, when it has form state or click context, a context line before the JSON. It writes end when the stream finishes. To name the library, it writes library=<id>@<version>, with id and version from the LibrarySpec (section 2.1), encoded as in section 7.1.

The attribute tells a later reader which library wrote the message. It does not change how the program is parsed.

Fixtures: none in spec/fixtures/1.0/.

7.5 What the model sees

Nothing of this protocol. The party that builds a model request MUST strip every marker line, and every section body it does not use, before the text reaches the model. The party that shows a message MUST strip every marker line before display. The prompt never teaches the syntax.

Fixtures: none in spec/fixtures/1.0/.

7.6 Older forms

  • The attribute libraryVersion (a version with no library id) is still written by some hosts. Readers return it like any other attribute.
  • Other envelopes, such as an XML <content>/<context> wrapper or an artifact header, are host-specific. OpenUI readers do not read them; the host that writes them reads them.

Fixtures: none in spec/fixtures/1.0/.

Appendix A. Changelog

  • 2026-10-12: 1.0. The LibrarySpec is one document with id, version, root, the schema, signatures, functions, and actions. Libraries can be extended. Prompts are deterministic. Libraries follow backward-compatibility rules. The message protocol uses content, context, and end marker lines.
  • Earlier drafts: 0.9 community review (2026-07-22) and 1.0-beta (2026-08-05). See the git history for their changes.