a2ui-project / a2ui-project/a2ui

fix(docs): Catalog composition examples in catalogs.md use invalid allOf under components

Open
#2,219 0 comments 0 reactions 0 assignees View on GitHub
component: specification P2 status: first-line-handled type: documentation
Dominant language
TypeScript
Stars
16.4k
Forks
1.3k
Avg merge
2d 13h
Merged PRs (30d)
134

Description

## Problem Page(s)

- `docs/public/concepts/catalogs.md` (Sections: "#### Example: Extending the Basic Catalog" and "#### Example: Cherry-picking Components")

## Describe the Issue

In `docs/public/concepts/catalogs.md`, the documentation examples for catalog composition and imports show an `"allOf"` key with an array value placed directly under the `"components"` map:

```json
{
"$id": "https://github.com/.../hello_world_with_all_basic/v1/catalog.json",
"catalogId": "https://github.com/.../hello_world_with_all_basic/v1/catalog.json",
"components": {
"allOf": [
{"$ref": "basic_catalog_definition.json#/components"},
{
"SuggestionChips": {
"type": "object",
...
}
}
]
}
}
```

In the A2UI Catalog Schema definition (`specification/v1_0/json/catalog_definition.json` and protocol specs), `components` is defined as an object where each property name is a component type and its value must be a valid JSON Schema:

```json
"components": {
"type": "object",
"description": "Definitions for UI components supported by this catalog.",
"additionalProperties": {
"$ref": "https://json-schema.org/draft/2020-12/schema"
}
}
```

Placing `"allOf": [...]` inside `components` fails JSON Schema validation against the Catalog meta-schema because:
1. `"allOf"` is treated as a component name rather than a JSON Schema composition keyword.
2. The value is an array, which is not a valid JSON Schema object.

## Proposed Changes

Update the catalog composition examples in `docs/public/concepts/catalogs.md` to reflect valid schema syntax (e.g. structuring composition at the root catalog schema level, or demonstrating valid multi-catalog linking patterns).

## Additional Context

Flagged during review of #2184.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.