Skip to content

docs(spec): fix two v1.0 evolution guide inaccuracies (functionResponse, Icon.name)#1925

Open
dongai-z wants to merge 1 commit into
a2ui-project:mainfrom
AGenUI:feat/fix_evolution_issue
Open

docs(spec): fix two v1.0 evolution guide inaccuracies (functionResponse, Icon.name)#1925
dongai-z wants to merge 1 commit into
a2ui-project:mainfrom
AGenUI:feat/fix_evolution_issue

Conversation

@dongai-z

@dongai-z dongai-z commented Jul 6, 2026

Copy link
Copy Markdown

Description

Two documentation-only corrections to specification/v1_0/docs/evolution_guide.md.
Both align the guide with the existing v1.0 schema; no schema or code behavior changes, so no tracking issue was filed first.

1. functionResponse description (§ Client-to-server events)

The functionResponse entry is inaccurate in two ways:

  • It references a type name FunctionResponseMessage that does not exist. client_to_server.json has no $defs; its messages are inlined as top-level properties (action / functionResponse / error), so there is no FunctionResponseMessage identifier.
    grep -c "FunctionResponseMessage" specification/v1_0/json/client_to_server.json0
  • It says functionResponse returns "(value or error)", but the schema is required: [functionCallId, call, value] with unevaluatedProperties: false — it carries only a value, never an error. Function execution failures are reported via the separate error message (which carries a functionCallId), as already documented in the very next bullet of the same section.

Fixed: drop the non-existent name, state that functionResponse returns the successful value, and point to the separate error message for failures.

2. Icon.name DataBinding removal (§ Standard catalogs + Migration guide)

v1.0 renamed the custom-SVG field svgPath to path. As a side effect, the custom-SVG object {path} became structurally identical to a DataBinding {path}, making the Icon.name oneOf ambiguous. v1.0 therefore removed the DataBinding branch from Icon.name:

  • v0.9.1 Icon.name = oneOf[ enum, {svgPath}, DataBinding ] (3 branches)
  • v1.0 Icon.name = oneOf[ enum, {path} ] (2 branches; DataBinding removed)
  • grep -c "DataBinding" specification/v1_0/catalogs/basic/catalog.json0

This is a breaking capability change: in v0.9.1 Icon.name could be data-bound; in v1.0 it cannot. The guide previously recorded only the svgPathpath rename and never mentioned the DataBinding removal or the resulting loss of data-binding — an undocumented breaking change.

Fixed: add one entry under the basic-catalog changes and one note in the migration guide. The schema already reflects the removal; this only documents it.

Pre-launch Checklist

One time:

For this PR:

  • I have added updates to the CHANGELOG.
  • I updated/added relevant documentation.
  • My code changes (if any) have tests.
  • If my branch is on fork, I have verified that scripts/e2e_test.sh passes.

If you need help, consider asking for advice on the discussion board.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the evolution_guide.md documentation to reflect the removal of the DataBinding option from the Icon component's name property, clarify that functionResponse only returns successful results, and add corresponding migration steps. The review feedback suggests improving the clarity of the JSON structures by replacing {path} with {"path": "..."} and correcting the terminology regarding component updates via updateComponents to refer to updating the component tree.

- Added a `steps` property to the `Slider` component schema to snap values to discrete intervals.
- Added an optional `instructions` field to the `Catalog` schema (`catalogs/basic/catalog.json`) to embed Markdown guidelines/rules directly, replacing the external `rules.txt` file.
- Renamed `svgPath` to `path` in the custom SVG icon definition object schema.
- Removed the `DataBinding` option from the `Icon` component's `name` property. Because `svgPath` was renamed to `path`, the custom-SVG object `{path}` became structurally identical to a `DataBinding` `{path}`, making the `name` `oneOf` ambiguous. As a result, `Icon.name` can no longer be data-bound; it must be a literal enum icon name or an inline custom SVG `{path}`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using {path} without quotes can be slightly confusing since it looks like a placeholder rather than a JSON object structure. Wrapping it in backticks and showing it as a JSON-like object (e.g., {"path": "..."}) makes it much clearer that it refers to a specific JSON structure.

Suggested change
- Removed the `DataBinding` option from the `Icon` component's `name` property. Because `svgPath` was renamed to `path`, the custom-SVG object `{path}` became structurally identical to a `DataBinding` `{path}`, making the `name` `oneOf` ambiguous. As a result, `Icon.name` can no longer be data-bound; it must be a literal enum icon name or an inline custom SVG `{path}`.
- Removed the `DataBinding` option from the `Icon` component's `name` property. Because `svgPath` was renamed to `path`, the custom-SVG object `{"path": "..."}` became structurally identical to a `DataBinding` `{"path": "..."}`, making the `name` `oneOf` ambiguous. As a result, `Icon.name` can no longer be data-bound; it must be a literal enum icon name or an inline custom SVG `{"path": "..."}`.

- Ensure all generated catalog entity names conform to UAX #31 identifier rules.
- Do not include `callableFrom` or `returnType` properties in wire-level `FunctionCall` payloads. Set static `callableFrom` and `returnType` metadata in catalog function definitions where needed.
- Update custom SVG icon definitions in `Icon` components to rename `svgPath` to `path`. Update `Video`, `TextField`, and `Slider` components to support optional `posterUrl`, `placeholder`, and `steps` properties.
- Stop data-binding the `Icon` component's `name` property; data binding on `name` is no longer supported. Use a literal enum icon name or an inline custom SVG `{path}`, and change an icon dynamically by resending the `Icon` component via `updateComponents`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Saying "resending the Icon component" might be slightly misleading because updateComponents requires the full component list (or at least a list containing the root component), so you cannot send just the Icon component by itself. Updating the phrasing to "updating the component tree" is more technically accurate. Additionally, using {"path": "..."} instead of {path} clarifies the JSON structure.

Suggested change
- Stop data-binding the `Icon` component's `name` property; data binding on `name` is no longer supported. Use a literal enum icon name or an inline custom SVG `{path}`, and change an icon dynamically by resending the `Icon` component via `updateComponents`.
- Stop data-binding the `Icon` component's `name` property; data binding on `name` is no longer supported. Use a literal enum icon name or an inline custom SVG `{"path": "..."}`, and change an icon dynamically by updating the component tree via `updateComponents` with the new icon definition.

@github-actions github-actions Bot added the status: needs-triage auto-managed: https://github.com/a2ui-project/a2ui/blob/main/scripts/triage.mjs label Jul 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: needs-triage auto-managed: https://github.com/a2ui-project/a2ui/blob/main/scripts/triage.mjs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant