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

Open Beginner friendly
#2,219 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
80/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
json, typescript
Domain
documentation

Research direction

The issue points to specific sections in docs/public/concepts/catalogs.md. First, read the file to understand the current invalid examples. Then, check the referenced schema at specification/v1_0/json/catalog_definition.json to see the correct structure. The fix is to update the JSON examples in the markdown file to use valid JSON Schema syntax, ensuring 'components' contains only component-type keys with proper schema objects. Verify by reviewing the changes locally.

Written by the indexing model from the issue text.

Description

component: specification P2 status: first-line-handled type: documentation

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:

{
  "$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:

"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.

Dominant language
TypeScript
Stars
16.4k
Forks
1.3k
Avg merge
3d 5h
Merged PRs (30d)
117

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from a2ui-project/a2ui

All issues in a2ui-project/a2ui

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.