Skip to content

refactor(spec): restructure v0.9 and v0.10 catalog files into dedicat…#1452

Open
gspencergoog wants to merge 13 commits into
google:mainfrom
gspencergoog:spec_file_restructure
Open

refactor(spec): restructure v0.9 and v0.10 catalog files into dedicat…#1452
gspencergoog wants to merge 13 commits into
google:mainfrom
gspencergoog:spec_file_restructure

Conversation

@gspencergoog
Copy link
Copy Markdown
Collaborator

@gspencergoog gspencergoog commented May 19, 2026

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 #865

…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]

This comment was marked as resolved.

…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.
gemini-code-assist[bot]

This comment was marked as resolved.

@google google deleted a comment from gemini-code-assist Bot May 19, 2026
@gspencergoog gspencergoog requested a review from josemontespg May 19, 2026 02:24
Copy link
Copy Markdown
Collaborator

@josemontespg josemontespg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice improvement, thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

Restructure v0.9 and v0.10 catalog files into dedicated catalog directories

2 participants