diff --git a/specification/v0_9/docs/a2ui_protocol.md b/specification/v0_9/docs/a2ui_protocol.md index 84405f1b..8b88ddc9 100644 --- a/specification/v0_9/docs/a2ui_protocol.md +++ b/specification/v0_9/docs/a2ui_protocol.md @@ -605,6 +605,7 @@ The [`standard_catalog.json`] provides the baseline set of components and functi | **length** | Checks string length constraints. | | **numeric** | Checks numeric range constraints. | | **email** | Checks that the value is a valid email address. | +| **formatString** | Does string interpolation of data model values and registered functions. | | **string_format** | Does string interpolation of data model values and registered functions. | | **openUrl** | Opens a URL in a browser. | @@ -624,9 +625,9 @@ The `iconUrl` and `agentDisplayName` fields are used to provide attribution to t In multi-agent systems or orchestrators, the orchestrator is responsible for setting or validating these fields. This ensures that the identity displayed to the user matches the actual agent server being contacted, preventing malicious agents from impersonating trusted services. For example, an orchestrator might overwrite these fields with the verified identity of the sub-agent before forwarding the `createSurface` message to the client. -### The `string_format` function +### The `formatString` function -The `string_format` function supports embedding dynamic expressions directly within string properties. This allows for mixing static text with data model values and function results. +The `formatString` function supports embedding dynamic expressions directly within string properties. This allows for mixing static text with data model values and function results. #### `string_format` Syntax @@ -646,7 +647,7 @@ Values from the data model can be interpolated using their JSON Pointer path. "id": "user_welcome", "component": "Text", "text": { - "call": "string_format", + "call": "formatString", "args": [ "Hello, ${/user/firstName}! Welcome back to ${/appName}." ] diff --git a/specification/v0_9/docs/evolution_guide.md b/specification/v0_9/docs/evolution_guide.md index b9b6e526..45047df6 100644 --- a/specification/v0_9/docs/evolution_guide.md +++ b/specification/v0_9/docs/evolution_guide.md @@ -226,7 +226,7 @@ Specifying an unknown surfaceId will cause an error. It is recommended that clie **v0.9:** -- **String Formatting**: Introduced the `string_format` function, which supports `${expression}` syntax for interpolation. +- **String Formatting**: Introduced the `formatString` function, which supports `${expression}` syntax for interpolation. - **Unified Expression Language**: Allows embedding JSON Pointer paths (absolute and relative) and client-side function calls directly within the format string. - **Nesting**: Supports recursive nesting of expressions (e.g., `${formatDate(${/timestamp}, 'yyyy-MM-dd')}`). - **Restriction**: String interpolation `${...}` is **ONLY** supported within the `string_format` function. It is not supported in general for string properties, in order to strictly separate data binding definitions from static content. diff --git a/specification/v0_9/json/standard_catalog.json b/specification/v0_9/json/standard_catalog.json index 2ca74c15..25ce7fdb 100644 --- a/specification/v0_9/json/standard_catalog.json +++ b/specification/v0_9/json/standard_catalog.json @@ -740,7 +740,7 @@ } }, { - "name": "string_format", + "name": "formatString", "description": "Performs string interpolation of data model values and other functions in the catalog functions list and returns the resulting string. The value string can contain interpolated expressions in the `${expression}` format. Supported expression types include: JSON Pointer paths to the data model (e.g., `${/absolute/path}` or `${relative/path}`), and client-side function calls (e.g., `${now()}`). Function arguments must be literals (quoted strings, numbers, booleans) or nested expressions (e.g., `${formatDate(${/currentDate}, 'MM-dd')}`). To include a literal `${` sequence, escape it as `\\${`.", "returnType": "string", "parameters": { @@ -751,6 +751,114 @@ } }, { + "name": "formatNumber", + "description": "Formats a number with the specified grouping and decimal precision.", + "returnType": "string", + "parameters": { + "type": "array", + "items": [ + { + "$ref": "common_types.json#/$defs/DynamicNumber", + "description": "The number to format." + }, + { + "$ref": "common_types.json#/$defs/DynamicNumber", + "description": "Optional. The number of decimal places to show. Defaults to 0 or 2 depending on locale." + }, + { + "$ref": "common_types.json#/$defs/DynamicBoolean", + "description": "Optional. If true, uses locale-specific grouping separators (e.g. '1,000'). If false, returns raw digits (e.g. '1000'). Defaults to true." + } + ], + "minItems": 1 + } + }, + { + "name": "formatCurrency", + "description": "Formats a number as a currency string.", + "returnType": "string", + "parameters": { + "type": "array", + "items": [ + { + "$ref": "common_types.json#/$defs/DynamicNumber", + "description": "The monetary amount." + }, + { + "$ref": "common_types.json#/$defs/DynamicString", + "description": "The ISO 4217 currency code (e.g., 'USD', 'EUR')." + } + ], + "minItems": 2 + } + }, + { + "name": "formatDate", + "description": "Formats a timestamp into a string using a pattern.", + "returnType": "string", + "parameters": { + "type": "array", + "items": [ + { + "$ref": "common_types.json#/$defs/DynamicValue", + "description": "The date to format." + }, + { + "$ref": "common_types.json#/$defs/DynamicString", + "description": "A Unicode TR35 date pattern string.\n\nToken Reference:\n- Year: 'yy' (26), 'yyyy' (2026)\n- Month: 'M' (1), 'MM' (01), 'MMM' (Jan), 'MMMM' (January)\n- Day: 'd' (1), 'dd' (01), 'E' (Tue), 'EEEE' (Tuesday)\n- Hour (12h): 'h' (1-12), 'hh' (01-12) - requires 'a' for AM/PM\n- Hour (24h): 'H' (0-23), 'HH' (00-23) - Military Time\n- Minute: 'mm' (00-59)\n- Second: 'ss' (00-59)\n- Period: 'a' (AM/PM)\n\nExamples:\n- 'MMM dd, yyyy' -> 'Jan 16, 2026'\n- 'HH:mm' -> '14:30' (Military)\n- 'h:mm a' -> '2:30 PM'\n- 'EEEE, d MMMM' -> 'Friday, 16 January'" + } + ], + "minItems": 2 + } + }, + { + "name": "pluralize", + "description": "Returns a localized string based on the Common Locale Data Repository (CLDR) plural category of the count (zero, one, two, few, many, other). Requires an 'other' fallback. For English, just use 'one' and 'other'.", + "returnType": "string", + "parameters": { + "type": "array", + "items": [ + { + "$ref": "common_types.json#/$defs/DynamicNumber", + "description": "The numeric value used to determine the plural category." + }, + { + "type": "object", + "description": "A map of CLDR plural categories to their corresponding strings.", + "properties": { + "zero": { + "$ref": "common_types.json#/$defs/DynamicString", + "description": "String for the 'zero' category (e.g., 0 items)." + }, + "one": { + "$ref": "common_types.json#/$defs/DynamicString", + "description": "String for the 'one' category (e.g., 1 item)." + }, + "two": { + "$ref": "common_types.json#/$defs/DynamicString", + "description": "String for the 'two' category (used in Arabic, Welsh, etc.)." + }, + "few": { + "$ref": "common_types.json#/$defs/DynamicString", + "description": "String for the 'few' category (e.g., small groups in Slavic languages)." + }, + "many": { + "$ref": "common_types.json#/$defs/DynamicString", + "description": "String for the 'many' category (e.g., large groups in various languages)." + }, + "other": { + "$ref": "common_types.json#/$defs/DynamicString", + "description": "The default/fallback string (used for general plural cases)." + } + }, + "required": [ + "other" + ], + "additionalProperties": false + } + ], + "minItems": 2, + "maxItems": 2 "name": "openUrl", "description": "Opens the specified URL in a browser or handler. This function has no return value.", "returnType": "void",