Introduction

UI Schema is a JSON format for declaring interfaces, their behavior, data flow, and validation handling. This documentation covers the core structure and semantics of the language, independent of any implementation or rendering engine.

At a Glance

A UI schema document is a root element (type plus props) carrying its identity and dialect. This example uses a field binding, an action, a translation, and a conditional together:

{
  "$id": "https://example.com/forms/signup/1",
  "$schema": "https://example.com/ui-schema/app",
  "type": "form",
  "props": {
    "onSubmit": { "$action": "submit", "$args": [{ "$data": "" }] },
    "children": [
      {
        "type": "input",
        "props": {
          "label": { "$t": "signup.email" },
          "value": { "$field": "/email" }
        }
      },
      {
        "type": "checkbox",
        "props": {
          "label": { "$t": "signup.terms" },
          "value": { "$field": "/acceptedTerms" }
        }
      },
      {
        "$if": [{ "$data": "/acceptedTerms" }, { "const": true }],
        "$then": {
          "type": "button",
          "props": { "label": { "$t": "signup.submit" } }
        }
      }
    ]
  }
}

Scope

This specification defines the UI Schema language. Rendering UIs with UI Schema involves several components:

• Language: The keywords, composition rules, and semantics defined in this specification.

• Dialect: Element definitions composed into a JSON Schema meta-schema conforming to this specification. A dialect defines element types, their props, and maps them to component renderers. The generated meta-schema is the normative grammar: each construct in this document corresponds to a definition in it ($defs/expression, $defs/action, $defs/field, $defs/children).

• UI Schema: A document created using the language and a specific dialect that describes the UI to render.

• Engine: Interprets a UI schema and data context using the dialect to render the actual UI. Manages component creation, event binding, state, and validation.

Conformance

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this documentation are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals, as shown here.

A document conforms to a dialect when it validates against that dialect's meta-schema. The requirement keywords in this documentation state the constraints the meta-schema encodes and the behavior required of engines.

Concepts

UI Schema describes interfaces through elements and props:

• Elements: Components to render, identified by a type. Elements form a tree and can contain other elements through props.

• Props: Attributes that configure elements, carried under an element's props. Which props are available, and what values they accept, depends on the dialect's element definitions.

Prop values are specified using the following constructs:

• Expressions: Constructs that resolve to a value: literals, data references, translation references, and scoped arguments.

• Fields: A two-way binding between a prop and a data field, carrying value and form state (focus, validation).

• Actions: Commands dispatched when a callback prop fires.

• Conditionals: Control flow that selects a value based on a condition.

• Maps: Iteration that transforms each item of an array.