a2ui-project / a2ui-project/a2ui
Simplify and Flatten Catalog Schemas & Tighten client_capabilities Catalog Schema in v0.10
- Ngôn ngữ chính
- TypeScript
- Star
- 16.4k
- Fork
- 1.3k
- Merge trung bình
- 3 ngày 15 giờ
- Pull request đã merge (30 ngày)
- 134
Mô tả
### Description
In A2UI v0.10, the catalog schemas (`catalogs/basic/catalog.json` and `catalogs/minimal/catalog.json`) have a structural inconsistency: some schemas are declared under root properties (such as `components` and `functions`), while standard schema helpers (`CatalogComponentCommon`, `theme`, `anyComponent`, `anyFunction`) are nested under `$defs`. This nesting adds unnecessary complexity and results in asymmetric, deep pointers.
This issue will simplify all catalog schemas in `v0.10` by standardizing on direct top-level declarations (removing `$defs` entirely). It will also update any reference files in `v0.10` pointing to these elements.
Furthermore, we will tighten the `Catalog` schema inside `specification/v0_10/json/client_capabilities.json` so that it accurately describes a compliant catalog structure (requiring `anyComponent`, `anyFunction`, and `theme` schemas at the root level, but leaving `catalogComponentCommon` optional).
### Scope of Work
1. **Flatten Basic and Minimal Catalogs:**
- In `specification/v0_10/catalogs/basic/catalog.json` and `specification/v0_10/catalogs/minimal/catalog.json`, remove `$defs` completely.
- Move `theme`, `anyComponent`, `anyFunction` directly into the catalog's root.
- Rename `CatalogComponentCommon` to `catalogComponentCommon` (camelCase) and move it directly to the root as an optional helper.
- Update all local references within these catalogs (e.g., pointing `{"$ref": "#/$defs/CatalogComponentCommon"}` to `{"$ref": "#/catalogComponentCommon"}`).
2. **Update Protocol Schemas for New Pointers:**
- In `specification/v0_10/json/common_types.json`, change function call union pointer from `catalog.json#/$defs/anyFunction` to `catalog.json#/anyFunction`.
- In `specification/v0_10/json/server_to_client.json`, update `theme` to `catalog.json#/theme` and `anyComponent` to `catalog.json#/anyComponent`.
3. **Tighten client_capabilities.json:**
- Standardize `Catalog` properties to be direct properties.
- Ensure `functions` is typed as an object of standard JSON Schemas rather than an array of descriptions.
- Enforce required root properties: `catalogId`, `components`, `functions`, `theme`, `anyComponent`, and `anyFunction`.
- Keep `catalogComponentCommon` as an optional property schema at the root.
4. **Verify the change:**
- Ensure the repository schemas remain valid and pass any local testing suites (e.g., `specification/v0_10/test`).
Hướng dẫn đóng góp
Hướng nghiên cứu
Công việc nằm trong thư mục `specification/v0_10/`. Bắt đầu bằng cách xem xét `catalogs/basic/catalog.json` và `catalogs/minimal/catalog.json` để hiểu cấu trúc `$defs` hiện tại. Sau đó, làm phẳng các schemas như đã mô tả, cập nhật các tham chiếu. Cũng cập nhật `json/common_types.json` và `json/server_to_client.json`. Cuối cùng, sửa `json/client_capabilities.json` để bắt buộc các properties được yêu cầu. Chạy các tests trong `specification/v0_10/test/` để xác minh các thay đổi.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- json, typescript
- Lĩnh vực
- backend-api-design
- Loại issue
- Tái cấu trúc
- Độ khó
- 3/5
- Thời gian dự kiến
- 1-2 ngày
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 55/100