feat(spec): add core A2UI templates specification, version 0.1 schema, and examples by jacobsimionato · Pull Request #2380 · a2ui-project/a2ui

jacobsimionato · 2026-08-25T03:44:55Z

Summary

This PR introduces the authoritative A2UI Templates Specification, formal JSON Schema, and multi-document YAML test fixtures under specification/proposals/templates/.

Templates provide a declarative, human-readable mechanism for authoring reusable UI subtrees in nested YAML. At generation time, an LLM emits compact, high-level template signatures (such as UserProfile("u1", "Alice")), which the backend expands into canonical Basic Catalog primitives in a single synchronous pass before emitting standard A2UI protocol messages (createSurface, updateComponents) to the client.

Architectural Highlights

Zero Client Overhead: Client renderers (@a2ui/react, @a2ui/lit, @a2ui/angular, @a2ui/flutter) require no custom widget code or dynamic plugins. They continue rendering 100% standard Basic Catalog primitives.
Context & Token Efficiency: Agents output concise function-like signatures rather than deeply nested component trees.
Deterministic Synthetic ID Generation: Implements canonical ID synthesis ({parent}_{slot}_{index}_{type}) guaranteeing zero ID collisions when multiple template instances are placed on a single surface.
Loop Expansion Boundaries: Differentiates server-side synchronous unrolling (for literal parameter arrays) from client-side reactive loops bound to the client DataModel.
Two-Way DataModel Interoperability: Preserves dynamic data binding paths ({path: "/user/name"}) and path prefix plumbing.
Strict Template Versioning (0.1): Enforces top-level version: "0.1" across all template definitions to support smooth schema evolution across future protocol releases.
Safety & Recursion Guards: Formal call-stack tracking algorithm (TemplateCycleError) and MAX_EXPANSION_DEPTH = 32 recursion limits.

Files Added

specification/proposals/templates/README.md: Complete, authoritative specification with pipeline diagrams, grammar rules, and multi-language conformance checklist.
specification/proposals/templates/schema/template_definition.json: Canonical JSON Schema (Draft 2020-12) enforcing required version: "0.1", templateId, parameters, and nested layout.
specification/proposals/templates/examples/*.yaml: 11 multi-document YAML template fixtures and test suites (basic_cards, nested_lists, slot_composition, user_profile, salary_card, team_roster, etc.).

Stack Context

PR 1 of 4: Core Specification, Schema & Test Fixtures (This PR)
PR 2 of 4: Python Agent SDK Template Engine Implementation
PR 3 of 4: Community Templates Sample App & Interactive Studio
PR 4 of 4: Future Proposals (Client-Expanded Templates & Python Fluent Builders)

gemini-code-assist

Code Review

This pull request introduces the A2UI Templates Specification, including a comprehensive markdown specification, a JSON schema for template definitions, and multiple YAML examples demonstrating template usage. The review feedback highlights several critical issues: the JSON schema needs to enforce that either template or item is provided in LoopDefinition, and it lacks a mechanism to declare required parameters. Additionally, there are duplicate templateId registrations across example files, type mismatches in section_card.yaml and two_column_layout.yaml, and the term normalized_type in the ID synthesis specification requires explicit definition in the README.

jacobsimionato · 2026-08-25T04:05:46Z

Thank you for the detailed feedback! All comments have been addressed in the latest commit:

LoopDefinition: Added anyOf: [{"required": ["template"]}, {"required": ["item"]}] to ensure loops explicitly specify what component layout to instantiate. Also constrained children in NestedTemplateNode to prevent generic object matching.
Required Parameters: Added top-level requiredParameters array and supported required boolean in ParameterDefinition to declare required parameters.
headerAction Type: Changed headerAction from type: action to type: child in section_card.yaml to match its usage in container children.
Disambiguated Template IDs: Renamed template IDs in multi-doc bundles (BasicUserProfile, BasicMetricCard, CompositeSectionCard, TwoColumnLayoutWithHeader, NestedTeamRoster, NestedTeamCard) to ensure zero naming collisions across all example files.
headerChild Sample Data: Updated two_column_layout.yaml sampleData from "" to a valid component node {"component": "Text", "text": "Header Title"}.
normalized_type Clarification: Explicitly clarified in README.md Section 7 that normalized_type refers to lowercase component/template names.

…, and examples

gspencergoog · 2026-08-26T01:03:56Z

Would it make sense for this to be a YAML schema instead of a JSON schema?

I mean, given that the format is in YAML, that makes sense to me.

e.g. https://yaml-schema.net/

I'm not sure it actually matters much, and I think the end result is the same, so maybe it makes sense to keep all the schema in one form. It was just a thought.

I read that people normally use JSON schema to represent schemas for YAML files, so I just stuck with that. I don't feel strongly though - we can change this at any time.

From search:
"The most widely used method to validate YAML files (such as GitHub Actions, Kubernetes manifests, or custom configs) is to write a standard JSON Schema but format it as a YAML file"

gspencergoog · 2026-08-26T01:05:45Z

+The template engine operates entirely server-side within the A2UI Agent SDK:
+
+```
+-------------------------------------------------------------------------------+


This could easily be a Mermaid diagram and be a lot nicer.

Updated the execution pipeline ASCII box diagram to a clean Mermaid flowchart diagram!

gspencergoog · 2026-08-26T01:07:01Z

@@ -0,0 +1,582 @@
+# A2UI Templates Specification


Nit: Should it maybe be "A2UI Template Specification" (singular)?

Updated the title to singular: # A2UI Template Specification.

gspencergoog · 2026-08-26T01:07:40Z

+
+## Abstract
+
+This document defines the authoritative specification for the **A2UI Templates System**. 


Is it a System or a Specification?

Clarified phrasing to: "This document defines the authoritative specification for A2UI Templates."

gspencergoog · 2026-08-26T01:09:14Z

+
+This document defines the authoritative specification for the **A2UI Templates System**. 
+
+Templates provide a declarative, human-readable mechanism for authoring reusable UI subtrees in nested YAML or via native programmatic render functions. At generation time, an agent or Large Language Model (LLM) outputs compact, high-level template invocations (such as `UserProfile("u1", "Alice")` or `PayrollSummary("Eng", true)`). The backend SDK expands these invocations into standard, flat A2UI Basic Catalog components in a single synchronous pass before emitting standard A2UI protocol messages (`updateComponents`) to the client.


The examples are all "programmatic render functions", so maybe we don't need the "nested YAML" case in the first sentence? Besides, seems weird to next YAML inside of A2UI (or maybe that's not what that means)?

I'm actually a little confused about this reading the doc: it seems like the "nested YAML" part is the template definitions, while the "programmatic render functions" is the instantiations. This description makes it sound like they are interchangable.

Re whether we need YAML at all, I think the main use case is to provide a smooth workflow from composer app to code, which people seem to like. E.g. you get the composer to create some YAML, then any SDK can use it. If we only allow the programmatic option, then the composer needs to output code, which is more of a pain, and ideally it should also be able to import code (to preview / modify existing layouts) which is probably too painful for us to pursue.

Let's discuss whether YAML is worthwhile tomorrow. I think @yjbanov maybe agrees with you that we should focus on programmatic.

Re nesting YAML inside A2UI. We're not doing that - the template process parses the YAML and then outputs pure JSON. The reason to use nested YAML here is because it's a better authoring experience for humans. Most of the time people author A2UI content and have a bad time, they should actually be authoring templates. Now we are designing templates, let's make it a human-friendly format (whether data or programmatic API).

gspencergoog · 2026-08-26T01:14:28Z

+
+## 2. Template Taxonomy
+
+A2UI defines three template modalities:


Modalities feels like the wrong word. To me that implies doing the same thing in different ways. This seems like they are three different parts that serve different purposes.

Changed "modalities" to "authoring styles" (Static YAML Templates, Dynamic Data-Binding Templates, and Dynamic Programmatic Render Functions).

gspencergoog · 2026-08-26T01:17:42Z

+3. The synthetic catalog is passed to `PromptGenerator` (Express, Elemental, Atom, Direct JSON), which automatically writes the syntax rules and documentation into the system prompt.
+
+### Surface Isolation Boundary
+```


This could be a Mermaid diagram too.

Replaced the isolation boundary ASCII art with a clean Mermaid flowchart diagram!

gspencergoog · 2026-08-26T01:20:01Z

+### Rule 2: Embedded String Interpolation
+If a parameter token appears alongside other characters (e.g. `"Hello, ${userName}!"` or `"${dept} - ${code}"`):
+- All tokens are replaced by their string representations.
+- Evaluates to a native string.


Hmm. But what about the reactive UI client side of things? What if I want to use the formatString function to put a data model item into the string and have it be reactive if the data model item changes? Can I escape the string interpolation so that is possible?

That is a great observation and highlights an inherent tension: in A2UI catalogs, the client runtime already uses ${/path} for reactive data model interpolation inside formatString(...). Using ${param} for server-side template expansion means any client-side expressions in template layouts would either need escaping (\${/path}) or risk colliding.

We plan to transition template substitution to standard double curly braces {{ param }} (like Jinja/Mustache/Helm). That cleanly separates the two scopes without requiring escaping:

{{ param }} is evaluated server-side at template expansion time.

${/path} is untouched by the template engine and passes through for client-side reactive evaluation (e.g. formatString("Hello ${/user/name}, dept: {{ dept }}")).

For now, \${...} escapes any literal ${...} so it passes through to the client intact.

Update: We have gone ahead and implemented this across the specification and all template examples! Double-curly Mustache syntax ({{ param }}) is now the canonical format for template parameter substitutions (with optional whitespace, e.g. {{ param }} or {{param}}).

This cleanly disambiguates compile-time template substitutions from client-side reactive expressions (${/data/path} and catalog functions like formatString(...)), ensuring client expressions pass through untouched without requiring any escaping.

gspencergoog · 2026-08-26T01:23:28Z

+## 9. Error Handling, Cycle Guards & Safety
+
+### Recursion & Circular Reference Detection
+Templates can invoke other templates. However, circular references (`A` invokes `B`, which invokes `A`) must be caught immediately to prevent stack overflow.


What about nesting? If I have a "Card" with a "Carousel" inside of it, containing other "Card"s, I would think that should be allowed, since they're different instances of the Card template.

Clarified this in Section 11! The cycle guard specifically prevents definition-level circular references (where a template's own layout unconditionally references itself in a cycle, causing infinite expansion).

In contrast, instance nesting—where a caller passes a Card instance into a slot of another Card instance (e.g. Card(child=Carousel(items=[Card(...)])))—is fully supported and encouraged, as each instance has a unique synthetic ID and is bounded by caller input.

gspencergoog · 2026-08-26T01:24:06Z

+
+- **Call Stack Tracking**: The `TemplateProcessor` maintains an active `_call_stack: Set[str]` throughout expansion.
+- **Cycle Guard**: Before expanding any template, if `template_id in _call_stack`, expansion terminates immediately with `TemplateCycleError: Circular template reference detected: A -> B -> A`.
+- **Maximum Depth Guard**: An absolute limit (`MAX_EXPANSION_DEPTH = 32`) enforces termination even in non-identical runaway recursion.


We should standardize on the max depth defaults. I think in other cases, we're using 50.

Updated MAX_EXPANSION_DEPTH default from 32 to 50 to standardize across A2UI!

…definition specification

…cursion, and max depth

jacobsimionato · 2026-08-26T03:53:47Z

I have addressed the feedback. Please take another look.

… substitutions

nan-yu · 2026-08-26T16:30:48Z

+              },
+              "additionalProperties": false
+            },
+            {"type": "array"},


Should we limit this to be an array of NestedTemplateNode, rather than arbitrary array?

nan-yu · 2026-08-26T16:46:14Z

+Templates decouple their local invocation name from their optional global identity:
+
+- **`name`** (Required): Component tag name used in layout trees and LLM prompts (`^[A-Za-z][A-Za-z0-9_]*$`). `templateId` is accepted as a backwards-compatible alias.
+- **`id`** (Optional): Globally unique URI or URN string (e.g. `https://company.org/templates/card/v1.json`) for package distribution and version pinning.


How do we enforce or validate the global uniqueness of template IDs? Is there a plan for a centralized template registry for discovery and resolution?

nan-yu · 2026-08-26T16:47:50Z

+
+- **`name`** (Required): Component tag name used in layout trees and LLM prompts (`^[A-Za-z][A-Za-z0-9_]*$`). `templateId` is accepted as a backwards-compatible alias.
+- **`id`** (Optional): Globally unique URI or URN string (e.g. `https://company.org/templates/card/v1.json`) for package distribution and version pinning.
+- **`imports`** (Optional): List of global template IDs, or dictionary mapping local aliases to global template IDs (`imports: { VendorCard: "https://vendor.com/card.json" }`).


Do we allow remote network fetching at runtime, or must all imported template IDs be pre-loaded into a local registry ahead of time?

github-project-automation Bot added this to A2UI Aug 25, 2026

github-project-automation Bot moved this to Todo in A2UI Aug 25, 2026

gemini-code-assist Bot reviewed Aug 25, 2026

View reviewed changes

jacobsimionato force-pushed the feat/templates-spec branch from ecc0b9d to 636f817 Compare August 25, 2026 04:05

feat(spec): add core A2UI templates specification, version 0.1 schema…

9393bf7

…, and examples

jacobsimionato force-pushed the feat/templates-spec branch from 636f817 to 9393bf7 Compare August 25, 2026 04:08

jacobsimionato requested review from gspencergoog and yjbanov August 25, 2026 04:19

gspencergoog reviewed Aug 26, 2026

View reviewed changes

jacobsimionato added 2 commits August 26, 2026 10:57

style(templates): add license headers and format specification files

5950f4c

feat(templates): specify name, id, catalogs, and imports in template …

4c04267

…definition specification

jacobsimionato mentioned this pull request Aug 26, 2026

Reinstate template examples #2402

Open

jacobsimionato force-pushed the feat/templates-spec branch from 2ea9b6b to 4c04267 Compare August 26, 2026 03:35

docs(templates): address review comments on diagrams, terminology, re…

65145a0

…cursion, and max depth

feat(spec): adopt double-curly Mustache syntax for template parameter…

650a511

… substitutions

nan-yu reviewed Aug 26, 2026

View reviewed changes


		## Abstract

		This document defines the authoritative specification for the A2UI Templates System.


		## 2. Template Taxonomy

		A2UI defines three template modalities:

Uh oh!

Conversation

jacobsimionato commented Aug 25, 2026

Summary

Architectural Highlights

Files Added

Stack Context

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jacobsimionato commented Aug 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacobsimionato commented Aug 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants