docs(spec): fix two v1.0 evolution guide inaccuracies (functionResponse, Icon.name)#1925
docs(spec): fix two v1.0 evolution guide inaccuracies (functionResponse, Icon.name)#1925dongai-z wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
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}`. |
There was a problem hiding this comment.
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.
| - 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`. |
There was a problem hiding this comment.
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.
| - 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. |
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.
functionResponsedescription (§ Client-to-server events)The
functionResponseentry is inaccurate in two ways:FunctionResponseMessagethat does not exist.client_to_server.jsonhas no$defs; its messages are inlined as top-level properties (action/functionResponse/error), so there is noFunctionResponseMessageidentifier.grep -c "FunctionResponseMessage" specification/v1_0/json/client_to_server.json→0functionResponsereturns "(valueorerror)", but the schema isrequired: [functionCallId, call, value]withunevaluatedProperties: false— it carries only avalue, never anerror. Function execution failures are reported via the separateerrormessage (which carries afunctionCallId), as already documented in the very next bullet of the same section.Fixed: drop the non-existent name, state that
functionResponsereturns the successfulvalue, and point to the separateerrormessage for failures.2.
Icon.nameDataBinding removal (§ Standard catalogs + Migration guide)v1.0 renamed the custom-SVG field
svgPathtopath. As a side effect, the custom-SVG object{path}became structurally identical to aDataBinding{path}, making theIcon.nameoneOfambiguous. v1.0 therefore removed theDataBindingbranch fromIcon.name:Icon.name=oneOf[ enum, {svgPath}, DataBinding ](3 branches)Icon.name=oneOf[ enum, {path} ](2 branches;DataBindingremoved)grep -c "DataBinding" specification/v1_0/catalogs/basic/catalog.json→0This is a breaking capability change: in v0.9.1
Icon.namecould be data-bound; in v1.0 it cannot. The guide previously recorded only thesvgPath→pathrename and never mentioned theDataBindingremoval 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:
If you need help, consider asking for advice on the discussion board.