remove freestanding catalogs requirement in v1.0#2019
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation in a2ui_protocol.md and evolution_guide.md to reflect that catalogs can now use $ref to reference other catalogs, removing the requirement for them to be freestanding. The reviewer suggested improving the clarity of the wording in the protocol documentation and noted that the PR description should include the required Pre-Review Checklist as per the repository style guide.
| 3. **Restricted `$ref` Targets:** | ||
| - Local `$ref` targets are restricted to referencing the catalog's top-level components or functions (e.g., `#/components/Text`, `#/functions/required`). | ||
| - External `$ref` targets MUST reference the standard types inside `common_types.json` (`https://a2ui.org/specification/v1_0/common_types.json#/$defs/...`), limited to the following allowed schemas: | ||
| - External `$ref` targets may reference other catalogs. When referencing `common_types.json` (`https://a2ui.org/specification/v1_0/common_types.json#/$defs/...`), targets are limited to the following allowed schemas: |
There was a problem hiding this comment.
The current wording is a bit dense and could be misinterpreted. To improve clarity, consider separating the two cases for external $ref targets more explicitly. This will make it easier for readers to understand that referencing other catalogs is a new general capability, while referencing common_types.json is a specific case with its own constraints.
| - External `$ref` targets may reference other catalogs. When referencing `common_types.json` (`https://a2ui.org/specification/v1_0/common_types.json#/$defs/...`), targets are limited to the following allowed schemas: | |
| - External `$ref` targets may reference other catalogs. Additionally, when referencing `common_types.json` (`https://a2ui.org/specification/v1_0/common_types.json#/$defs/...`), targets are limited to the following allowed schemas: |
| - Standard JSON Schema metadata fields (`$schema`, `$id`, `title`, and `description`) are supported in catalogs, preventing validation failures on inline catalogs with strict property checks. | ||
| - Identifier naming rules across all catalog entities (component names, function names, and argument keys) must conform to Unicode Standard Annex #31 (UAX #31). | ||
| - The `@index` built-in function dynamically retrieves iteration indices during list template rendering. The `@` prefix is reserved for core system context evaluations. | ||
| - Catalogs may now use `$ref` to reference other catalogs. This removes the requirement that catalogs be freestanding / have no external references except to core libraries. |
There was a problem hiding this comment.
The pull request description is currently empty. Per the repository's style guide (lines 18-20), it should include the Pre-Review Checklist from the pull request template. Please update the description accordingly.
References
- PR descriptions should include the Pre-Review Checklist from the PR template, with all of the steps completed. (link)
1 participant
For v1.0 - Catalogs may now use
$refto reference other catalogs. This removes the requirement that catalogs be freestanding / have no external references except to core libraries.