a2ui-project / a2ui-project/a2ui
refactor(spec): Standardize on absolute URIs for schema and catalog references
- Ngôn ngữ chính
- TypeScript
- Star
- 16.4k
- Fork
- 1.3k
- Merge trung bình
- 2 ngày 13 giờ
- Pull request đã merge (30 ngày)
- 134
Mô tả
### Description of the Inconsistency
There is an inconsistency in how schemas and catalogs are referenced across the A2UI repository.
Currently, the specification and examples mix **long/absolute URIs** (which tie identifiers to the repository's schema domains) and **short/relative URIs**.
#### 1. Long URIs used in Spec and Schema Files:
* In the official basic catalog [catalog.json](https://github.com/google/A2UI/blob/main/specification/v0_9/catalogs/basic/catalog.json), the `$id` and `catalogId` are set to `https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json`.
* References to common types in [catalog.json](https://github.com/google/A2UI/blob/main/specification/v0_9/catalogs/basic/catalog.json) use the full URI: `https://a2ui.org/specification/v0_9/common_types.json#/$defs/ComponentCommon`.
* The protocol documentation [a2ui_protocol.md](https://github.com/google/A2UI/blob/main/specification/v0_9/docs/a2ui_protocol.md#L198) and examples use `https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json` as the `catalogId`.
#### 2. Short/Relative URIs used in Code and Conformance Tests:
* Conformance test data such as [simplified_catalog_v09.json](https://github.com/google/A2UI/blob/main/agent_sdks/conformance/test_data/simplified_catalog_v09.json#L8) references common types using the short/relative filename: `"common_types.json#/$defs/ComponentCommon"`.
* The Web Core's `MessageProcessor` [message-processor.ts](https://github.com/google/A2UI/blob/main/renderers/web_core/src/v0_9/processing/message-processor.ts#L101) dynamically generates inline catalogs using the relative reference `"common_types.json#/$defs/ComponentCommon"`.
This inconsistency makes writing offline parser/validator registries fragile. A validator registry must map both long and short URIs to prevent validation failures, which goes against the design goal of catalog-agnostic validation.
### Proposed Solution
We should standardize on the **long/absolute version** of the catalog ID and schema URIs across all specifications, documents, and implementations.
1. **Standardize on Long URIs**:
* All `$ref` links inside catalogs, example messages, and generated schemas should use the full absolute URL representation (e.g. `https://a2ui.org/specification/v0_9/common_types.json#/$defs/...`) rather than relative filenames.
2. **Registry Mapping**:
* Platform-specific validator registries (such as in Java, Kotlin, or Web Core) should define standard base URL mappings so that these absolute URIs can be resolved locally offline without network access.
Hướng dẫn đóng góp
Hướng nghiên cứu
The issue identifies specific files: specification/v0_9/catalogs/basic/catalog.json, agent_sdks/conformance/test_data/simplified_catalog_v09.json, and renderers/web_core/src/v0_9/processing/message-processor.ts. Start by examining these files to understand the URI patterns. The task is to update all schema and catalog references to use absolute URIs (https://a2ui.org/...). Run existing conformance tests to ensure changes don't break validation. 'Done' means all references in the repository are consistent and tests pass.
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
- tooling
- 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
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 65/100