refactor: Refactor FunctionCall wire schema and align protocol specification by gspencergoog · Pull Request #1518 · a2ui-project/a2ui

gspencergoog · 2026-06-02T16:08:02Z

Description

This pull request refactors the FunctionCall schema definition in the A2UI v0.10 specification to completely remove the redundant callableFrom and returnType properties from the wire-level payload. Enforcements and validations (such as execution boundaries and return type correctness) are moved entirely to client-side runtime verification against catalog registries rather than being validated on the wire.

Additionally, this pull request adds support for static callableFrom and returnType metadata inside the client capabilities catalog definition schema, aligns the official protocol documentation (a2ui_protocol.md) with all updated schemas, and comprehensively updates all test cases, JSONL streams, and basic catalog examples to remove these obsolete wire-level fields.

Detailed changes

Schemas

common_types.json:
- Removed the callableFrom and returnType properties from the core FunctionCall schema definition.
- Removed static returnType constraints from DynamicString, DynamicNumber, DynamicBoolean, and DynamicStringList schema unions so they accept any FunctionCall on the wire and rely on client-side runtime type checking.
server_to_client.json: Simplified the CallFunctionMessage payload's callFunction property, removing both callableFrom and returnType overrides and required constraints.
testing_catalog.json & catalogs/minimal/catalog.json & catalogs/basic/catalog.json: Removed the callableFrom and returnType property definitions from catalog function schemas, keeping them strictly as validators for wire payloads.
client_capabilities.json: Declared static callableFrom and returnType properties inside the $defs/FunctionDefinition catalog schema. This allows clients to statically advertise their custom functions' boundaries and return types to the server as metadata, separate from the wire payload.

Test cases and Examples

Test Suites (cases/*.json, cases/*.jsonl): Performed an automated smart cleanup of positive and unrelated test payloads across all test cases (e.g., checkable_components.json, button_checks.json, call_function_message.json, function_catalog_validation.json) to strip returnType and callableFrom fields, while preserving their values in dedicated negative tests checking for schema rejection of unknown properties.
Catalog Examples (catalogs/basic/examples/*.json): Cleaned up all 36 basic catalog examples to strip the obsolete wire-level returnType field from their function call declarations.

Documentation (`a2ui_protocol.md`)

callFunction specifications: Aligned the callFunction property documentation and examples to remove wire-level returnType properties and updated the JSONL stream example.
Server-to-client envelopes: Aligned the introductory list under ## Envelope message structure to include the callFunction key. Added a new section detailing the callFunction message, its properties, and payload examples. Clarified how the client runtime extracts the callableFrom configuration from catalog definitions/annotations (defaulting to "clientOnly").
Client-to-server event messages: Restructured and expanded the documentation for client events. Fully detailed the property lists, mutual exclusion rules, and JSON examples for action events (including wantResponse and actionId), functionResponse execution results, and client error messages.
Capabilities and metadata: Promoted transport-level capability and data model exchanges to a dedicated section. Aligned the documented properties of server_capabilities.json, client_capabilities.json, and client_data_model.json to correctly describe version-wrapped objects ("v0.10") and the required "version" property. Documented that custom inline catalog function definitions support static callableFrom and returnType metadata to advertise function execution details.

Verification results

All 107 test cases in the A2UI v0.10 schema validation suite pass successfully. The automated tests validated the modified JSON schemas against the updated test files under /specification/v0_10/test/cases/.

Fixes #718

The formatting script now uses Flutter, so the workflow requires the Flutter SDK instead of just the Dart SDK. Also updated formatting in infra_test.dart to keep it consistent.

…re schema - Removes the wire-level `callableFrom` property from the `FunctionCall` definition in `common_types.json`. - Simplifies the `CallFunctionMessage` payload in `server_to_client.json` to directly reference `FunctionCall` without `callableFrom` overrides or requirements. - Removes the property from `testing_catalog.json` and all validation cases in `call_function_message.json`. - Enforces boundary validation strictly as a client-side runtime check against local catalog registry definitions.

- Formally documents the `CallFunctionMessage` payload structure and its properties in `a2ui_protocol.md`. - Outlines execution boundary check rules and security constraints for client-side runtime verification. - Provides concrete JSON communication examples for server-initiated execution, client responses, and error handling.

…col spec - Aligns `server_to_client` envelope list intro with the schema by including the new `callFunction` message type. - Restructures and fully documents the `client_to_server` event envelope messages (`action` updates, `functionResponse`, and `error`). - Provides detailed property descriptions, JSON examples, and layout rules for client events, execution responses, and mutual exclusions. - Promotes `Capabilities and metadata` to its own top-level section to distinguish transport metadata from first-class A2UI envelope streams.

…emas - Aligns the properties of `server_capabilities` and `client_capabilities` by properly nesting them under their required `"v0.10"` version wrapper objects in the protocol documentation. - Adds the required top-level `"version"` property to the documented properties of the `a2uiClientDataModel` metadata object. - Resolves the remaining discrepancies between the A2UI JSON schemas and `a2ui_protocol.md`.

…itions - Adds `callableFrom` as an optional property inside the static `FunctionDefinition` schema within `client_capabilities.json`. - Defaults the execution boundary configuration for registered catalog functions to `"clientOnly"`. - Updates the client capability documentation in `a2ui_protocol.md` to specify how inline catalogs can statically declare execution boundaries.

- Adds a parenthetical note to the `callFunction` lookup rules in `a2ui_protocol.md`. - Clarifies that the client runtime inspects `callableFrom` metadata or schema annotations from the catalog to determine execution boundaries, defaulting to `"clientOnly"`.

- Updates the ReturnType description under `callFunction` to use precise and standard terminology ("Must be one of" instead of "Snaps to one of").

…Call schema

The formatting script now uses Flutter, so the workflow requires the Flutter SDK instead of just the Dart SDK. Also updated formatting in infra_test.dart to keep it consistent.

jacobsimionato · 2026-06-03T02:04:42Z

+        },
+        "callableFrom": {
+          "type": "string",
+          "enum": ["clientOnly", "remoteOnly", "clientOrRemote"],


Can't this also be called from either server or client? Add clientOrRemote?

Can't this also be called from either server or client? Add clientOrRemote?

"clientOnly" means it can only be called on the client. "remoteOnly" means it can only be called on the server, and "clientOrRemote" means it is available on both.

I'm not sure I understand your comment, though. clientOrRemote is already available.

jacobsimionato · 2026-06-03T02:17:54Z

This declares a function definition, but looking closer, it seems like this schema is actually not validated anywhere.

The basic catalog is supposed to conform to the Catalog schema below which includes this, but it seems like we don't actually validate that anywhere, because I see returnType is required here, yet it's not declared in the basic catalog JSON document.

I think probably what we really need is for each FunctionDefinition object to include a FunctionCall schema (referenced from common_types) inside which contains the name and args, and also extra metadata like ReturnType and CallableFrom that is used by the client for validation and the LLM to understand the call signature. Then, anyFunction etc in basic_catalog needs to combine together the inner FunctionCall schemas, rather than the outer FunctionDefinitions.

Hmmm maybe we're hitting the edge of what JSON schema validation can get us...

Yes, good point. Okay, I've modified the schema so it is suitable to use for validation and added validation tests for the basic and minimal catalogs to make sure that they pass validation against Catalog.

When we implement this for the core libraries, do you think we should add automatic validation for advertised catalogs?

I think JSON validation still good enough, or at least a part of a functional solution, but you're right, we're getting close to needing more.

…ype metadata - Changed functions from an array of definitions to an object (map) of schemas inside client_capabilities.json. - Redefined FunctionDefinition to inherit from Draft 2020-12 schema, housing metadata like returnType and callableFrom at the root level of the schema. - Added returnType metadata directly to basic catalog, minimal catalog, and testing catalog function definitions. - Aligned custom functions documentation with the new structure. - Removed obsolete tmp/evaluation_v0_10_features.md file.

…tion Define a separate $defs/FunctionCallValidationSchema to explicitly validate client/server function calls on the wire, and compose it in $defs/FunctionDefinition alongside returnType/callableFrom metadata using allOf. This allows reusing validation constraints without leaking metadata parameters onto the wire protocol.

Update the Catalog definition schema in client_capabilities.json to allow standard JSON schema properties ($schema, $id, title, description, $defs). Add a new test step to run_tests.py that automatically validates the basic, minimal, and testing catalogs against this Catalog schema definition.

…ect#1464) * docs: Replace agent-and-renderer.png by a Mermaid diagram. * docs: Add Glossary menu entry under Concepts

github-project-automation Bot added this to A2UI Jun 2, 2026

github-project-automation Bot moved this to Todo in A2UI Jun 2, 2026

This comment was marked as resolved.

Sign in to view

gspencergoog force-pushed the refactor-function-call branch 3 times, most recently from b9c150b to 1e47d05 Compare June 2, 2026 22:47

gspencergoog requested a review from jacobsimionato June 2, 2026 23:05

gspencergoog enabled auto-merge (squash) June 2, 2026 23:36

gspencergoog added 12 commits June 2, 2026 17:28

Fix format script to work for Flutter packages

6eaee7f

ci: install stable Flutter SDK in enforce-formatting workflow

3e24613

The formatting script now uses Flutter, so the workflow requires the Flutter SDK instead of just the Dart SDK. Also updated formatting in infra_test.dart to keep it consistent.

docs: refine returnType description style in protocol spec

48b7ae0

- Updates the ReturnType description under `callFunction` to use precise and standard terminology ("Must be one of" instead of "Snaps to one of").

refactor: remove callableFrom and returnType from wire-level Function…

a92d8a2

…Call schema

ci: install stable Flutter SDK in enforce-formatting workflow

2fd89b9

The formatting script now uses Flutter, so the workflow requires the Flutter SDK instead of just the Dart SDK. Also updated formatting in infra_test.dart to keep it consistent.

Merge branch 'main' into refactor-function-call

c069127

gspencergoog force-pushed the refactor-function-call branch from 279a614 to c069127 Compare June 3, 2026 00:44

jacobsimionato reviewed Jun 3, 2026

View reviewed changes

gspencergoog added 4 commits June 2, 2026 19:44

Merge branch 'main' into refactor-function-call

568154c

gspencergoog force-pushed the refactor-function-call branch from 03de8a6 to 14e6d60 Compare June 3, 2026 17:46

gspencergoog and others added 2 commits June 3, 2026 13:06

Merge branch 'main' into refactor-function-call

bb431da

docs: Replace agent-and-renderer.png by a Mermaid diagram. (a2ui-proj…

fd40ada

…ect#1464) * docs: Replace agent-and-renderer.png by a Mermaid diagram. * docs: Add Glossary menu entry under Concepts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: Refactor FunctionCall wire schema and align protocol specification#1518

refactor: Refactor FunctionCall wire schema and align protocol specification#1518
gspencergoog wants to merge 18 commits into
a2ui-project:mainfrom
gspencergoog:refactor-function-call

gspencergoog commented Jun 2, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

jacobsimionato Jun 3, 2026

Uh oh!

gspencergoog Jun 3, 2026

Uh oh!

Uh oh!

jacobsimionato Jun 3, 2026

Uh oh!

gspencergoog Jun 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

gspencergoog commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Detailed changes

Schemas

Test cases and Examples

Documentation (a2ui_protocol.md)

Verification results

Uh oh!

This comment was marked as resolved.

Uh oh!

jacobsimionato Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

gspencergoog Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jacobsimionato Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

gspencergoog Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gspencergoog commented Jun 2, 2026 •

edited

Loading

Documentation (`a2ui_protocol.md`)