refactor(spec): restructure v0.9 and v0.10 catalog files into dedicat…#1452
Merged
Conversation
…ed catalogs directory
Restructures the basic and minimal catalogs (and their example directories)
out of the generic json/ directory and into a modular catalogs/
hierarchy directly under the specification version roots (v0.9 and v0.10).
- Moves basic_catalog.json to catalogs/basic/catalog.json.
- Moves minimal_catalog.json to catalogs/minimal/catalog.json.
- Relocates examples to /catalogs/{catalog}/examples/.
- Refactors cross-schema references in catalogs to use absolute canonical URIs (e.g., https://a2ui.org/.../common_types.json) to decouple schemas from local filesystem paths.
- Ports modular catalog example datasets and minimal catalogs from v0.9 to v0.10.
- Simplifies validate.py to natively support canonical URI resolution during schema validation.
- Updates assemble_catalog.py, copy-spec.js packaging utility, and docs copying workflows to support the new modular layout.
- Updates repository-wide documentation referencing basic_catalog.json.
Fixes google#865
… canonical URIs - Updates BASIC_CATALOG_PATHS for version 0.9 in constants.py to catalogs/basic/catalog.json. - Updates common types pruning logic in catalog.py to match canonical URIs containing 'common_types.json#/$defs/' rather than hardcoding relative paths.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
…m Git - Adds src/v0_10/schemas/ to .gitignore inside renderers/web_core. - Removes/untracks all generated v0_10 schema build assets from Git.
…hecks in copy-spec.js - Replaces double call to readdirSync on srcJsonDir with existsSync. - Imports existsSync from node:fs.
Replaces catch (e) with catch (optional catch binding) to prevent unused variable warning.
…s structure Updates CATALOG_PATH and basic_catalog.json references in solvers.py, tasks.py, and test_scorers.py to use the new modular catalogs/basic/catalog.json location and canonical URIs.
…sic catalog reorganization Updates Lit, Angular, and React renderers, adapters, tests, and examples loaders to reference the new catalogs/basic/catalog.json catalog ID and example paths.
… and tests - Updates sync-gallery.mjs examples path to v0.9 catalogs sibling directory. - Updates v09Viewer.tsx and a2ui-prompt-v09.ts to point basic catalog references to catalogs/basic/catalog.json. - Adds @testing-library/dom to devDependencies in package.json.
…heck in copy-spec.js Avoids swallowing legitimate write/permission errors during schema packaging by explicitly verifying directory existence.
…0.9 and above in copy-spec.js Requires catalogs directory to be copied cleanly and throw ENOENT if missing for v0.9 and v0.10, while keeping it optional for v0.8.
…pec.js Directly skips catalogs copy operations for v0.8 to ensure zero possibility of illegal/accidental v0.8 catalogs packaging. Keeps catalogs mandatory for v0.9 and v0.10.
…ncies Regenerates pnpm-lock.yaml with the added @testing-library/dom devDependency to prevent outdated-lockfile blockages on CI pipelines.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
josemontespg
approved these changes
May 19, 2026
Collaborator
josemontespg
left a comment
josemontespg
left a comment
There was a problem hiding this comment.
Nice improvement, thank you!
4 tasks
valentinbeggi
added a commit
to valentinbeggi/A2UI
that referenced
this pull request
May 25, 2026
PR google#1452 moved the basic catalog from specification/v{ver}/json/basic_catalog.json to specification/v{ver}/catalogs/basic/catalog.json and updated the canonical $id accordingly. The lit renderer's basicCatalog was updated, but all downstream consumers (sample examples, eval prompts, test fixtures, run_tests.py scripts) still referenced the old URL, causing an "A2uiStateError: Catalog not found" at runtime when the LLM generates createSurface messages with the outdated catalogId. Changes: - Update all agent/client sample example JSONs (restaurant, custom- components, rizzcharts, MCP, React mock) to use the new catalogId - Update eval generation_flow.ts prompts for v0.9 and v0.10 - Update spec test case fixtures for v0.9 and v0.10 - Fix run_tests.py for both versions to load from the new path - Update agent SDK tests to use the new ID
suyangw-g
pushed a commit
to suyangw-g/A2UI
that referenced
this pull request
May 26, 2026
google#1452) # Restructure v0.9 and v0.10 catalogs into dedicated modular directories This change restructures the basic and minimal component and function catalogs for both v0.9 and v0.10 specifications, moving them out of `/json/` and into a dedicated `/catalogs/` folder under each version root. Cross-schema references are transitioned to absolute canonical URIs to prevent repository directory structure leakage into the public specification. ## Proposed directory reorganization ``` specification/ ├── v0_10/ │ ├── catalogs/ │ │ ├── basic/ │ │ │ ├── catalog.json # (formerly basic_catalog.json) │ │ │ ├── rules.txt # (formerly basic_catalog_rules.txt) │ │ │ └── examples/ # basic catalog JSON examples │ │ └── minimal/ │ │ ├── catalog.json # (formerly minimal_catalog.json) │ │ └── examples/ # minimal catalog JSON examples │ └── json/ # Core protocol schemas ``` ## Key design decisions * **Canonical absolute URIs:** Relative paths (like `../../json/common_types.json`) were replaced with canonical absolute URIs (e.g., `https://a2ui.org/specification/v0_10/common_types.json`) to completely decouple the schemas from the repository directory layout. * **Interface binding:** Kept relative `"catalog.json"` references inside core schemas, allowing Ajv to bind references natively in memory against whichever catalog is registered. ## PR breakdown * **Specification & Tooling:** Modularized v0.9 & v0.10 basic/minimal catalogs and examples, updated `specification/scripts/validate.py` to validate v0.10 natively, and updated `assemble_catalog.py` basic catalog URLs. * **Renderers & Packaging:** * Updated `copy-spec.js` to copy the modular `catalogs/` directory during package builds for versions >= v0.9, while completely skipping it for v0.8. * Ignored generated `src/v0_10/schemas/` build products in `.gitignore` and untracked them from Git. * Updated Lit, Angular, and React adapters, demo catalogs, and test suites to match the new catalog IDs and directories. * **Python SDK & Evals:** Updated constants paths, revised the common types pruning utility in `catalog.py` to handle absolute canonical URIs, and refactored prompt/scorer tasks under `eval/` to resolve new paths. * **Composer Tool:** Fixed the examples syncing script to look in the sibling directories, resolved missing test dependencies by adding `@testing-library/dom`, and updated `pnpm-lock.yaml`. ## Testing and verification All packages, tests, and build pipelines are passing: * `python3 specification/scripts/validate.py` (All 36 schema examples validated) * `test_assemble_catalog.py` (All 18 unit tests passed) * `uv run pytest` in `agent_sdks/python` (All 245 tests passed) * `uv run python3 -m pytest` in `eval/` (All 21 evaluation tests passed) * `npm run test` in `renderers/react` (All 446 tests passed) * `pnpm test` in `tools/composer` (All 32 tests passed) * Successfully compiled `@a2ui/web_core` and successfully built MkDocs site. Fixes google#865
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restructure v0.9 and v0.10 catalogs into dedicated modular directories
This change restructures the basic and minimal component and function catalogs for both v0.9 and v0.10 specifications, moving them out of
/json/and into a dedicated/catalogs/folder under each version root. Cross-schema references are transitioned to absolute canonical URIs to prevent repository directory structure leakage into the public specification.Proposed directory reorganization
Key design decisions
../../json/common_types.json) were replaced with canonical absolute URIs (e.g.,https://a2ui.org/specification/v0_10/common_types.json) to completely decouple the schemas from the repository directory layout."catalog.json"references inside core schemas, allowing Ajv to bind references natively in memory against whichever catalog is registered.PR breakdown
specification/scripts/validate.pyto validate v0.10 natively, and updatedassemble_catalog.pybasic catalog URLs.copy-spec.jsto copy the modularcatalogs/directory during package builds for versions >= v0.9, while completely skipping it for v0.8.src/v0_10/schemas/build products in.gitignoreand untracked them from Git.catalog.pyto handle absolute canonical URIs, and refactored prompt/scorer tasks undereval/to resolve new paths.@testing-library/dom, and updatedpnpm-lock.yaml.Testing and verification
All packages, tests, and build pipelines are passing:
python3 specification/scripts/validate.py(All 36 schema examples validated)test_assemble_catalog.py(All 18 unit tests passed)uv run pytestinagent_sdks/python(All 245 tests passed)uv run python3 -m pytestineval/(All 21 evaluation tests passed)npm run testinrenderers/react(All 446 tests passed)pnpm testintools/composer(All 32 tests passed)@a2ui/web_coreand successfully built MkDocs site.Fixes #865