Skip to content

remove freestanding catalogs requirement in v1.0 #2019

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wrenj wants to merge 1 commit into
base: main
Choose a base branch
from
+3 −1
Open

remove freestanding catalogs requirement in v1.0 #2019

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion specification/v1_0/docs/a2ui_protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -484,7 +484,7 @@ To ensure catalog schemas can be translated reliably into alternative, LLM-frien
- All helper properties (such as common properties factored out of catalog items) MUST be inlined directly inside the properties block of each supporting component schema rather than referenced from a shared helper.
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:

@gemini-code-assist gemini-code-assist Bot Jul 16, 2026

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

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.

Suggested change
- 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:

- `ComponentId`
- `ChildList`
- `DynamicString`
Expand Down
2 changes: 2 additions & 0 deletions specification/v1_0/docs/evolution_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Version 1.0 differs from 0.9 in the following ways:
- 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.

@gemini-code-assist gemini-code-assist Bot Jul 16, 2026

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

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
  1. PR descriptions should include the Pre-Review Checklist from the PR template, with all of the steps completed. (link)


## 2. Changes

Expand All @@ -25,6 +26,7 @@ Version 1.0 differs from 0.9 in the following ways:
- Added an optional `instructions` field to the `Catalog` schema to embed design guidelines and component usage rules directly in the catalog, replacing the external `rules.txt` file.
- Supported standard JSON Schema metadata fields (`$schema`, `$id`, `title`, and `description`) in the Catalog object definition. Since the Catalog schema restricts properties with `additionalProperties: false`, this ensures inline catalogs containing standard schema metadata do not fail schema validation.
- Enforced Unicode Standard Annex #31 (UAX #31) identifier naming constraints (`XID_Start`, `XID_Continue`) across component names, function names, and argument keys.
- 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.

### 2.2. Standard catalogs (basic)

Expand Down
Loading