From a19b6f6beb41167aceeb1cb0c13e4131ad3c3f44 Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 09:48:50 +0000 Subject: [PATCH 1/4] docs(#4223): RHIDP-15302 migration design document Create the RHIDP-15302 migration design document at workspaces/boost/specifications/ai-asset-upstream-migration-design.md covering all seven AI-asset categories per Decision 1. The document maps current RHDH entity kinds and spec.type values to their upstream Backstage targets with confidence levels, provides field-level transformation rules per category, identifies consumer-facing changes (catalog UI filters, entity refs, API queries), and defines a backward compatibility strategy (keep rhdh.io/ai-asset-category annotation for one major version). Key decisions reflected: - MCP server: kind already aligned (API), no rename to McpServer - Model server: conditional on backstage#34476 (Resource to API) - Skills/rules: AiResource shipped upstream, casing alignment - Agent/AI model/skill-bundle: low confidence, track upstream - vector-store/ai-tool: explicitly out of scope - Sign-off section present but unsigned (human follow-up) Cross-links added from migration-readiness/spec.md and tasks.md group 8 (8.1-8.4 marked complete). Cites #4211 (model-server downstream) and #4164 (AiResource agent schema). Closes #4223 --- .../specs/migration-readiness/spec.md | 2 + .../changes/ai-catalog-entity-model/tasks.md | 10 +- .../ai-asset-upstream-migration-design.md | 349 ++++++++++++++++++ 3 files changed, 357 insertions(+), 4 deletions(-) create mode 100644 workspaces/boost/specifications/ai-asset-upstream-migration-design.md diff --git a/workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md b/workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md index ac5f8c1a97c..035de7beb61 100644 --- a/workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md +++ b/workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md @@ -1,6 +1,8 @@ # Migration Readiness for Upstream Entity Kinds > **Status: Draft** — Pre-implementation specification. Subject to change during implementation. +> +> **Design document:** [ai-asset-upstream-migration-design.md](../../../../specifications/ai-asset-upstream-migration-design.md) — implements RHIDP-15302 tasks 8.1-8.4 from this specification. Design document mapping custom annotations and entity kinds to upstream Backstage entity kind targets, identifying consumer-facing changes, and obtaining upstream sign-off. Current-state source of truth: [ai-catalog-entity-model/design.md Decision 1](../../design.md). MCP server kind is already aligned with upstream (`McpServerApiEntity`, [backstage#34016](https://github.com/backstage/backstage/pull/34016)); RFC [#32062](https://github.com/backstage/backstage/issues/32062) is MCP-only and does **not** define an `AIAgent` kind. diff --git a/workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md b/workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md index d492b4f704b..20f86f6c0c4 100644 --- a/workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md +++ b/workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md @@ -84,10 +84,12 @@ ## 8. Migration Readiness Design (P2) — _RHIDP-15258_ -- [ ] 8.1 Create migration design document with mapping table: current kind/spec.type/annotation → target upstream kind (RHIDP-15302) -- [ ] 8.2 Document transformation rules for each AI asset category (RHIDP-15302) -- [ ] 8.3 Identify consumer-facing changes: catalog UI filters, entity refs, API queries (RHIDP-15302) -- [ ] 8.4 Document backward compatibility strategy (e.g., keep annotation for one major version) (RHIDP-15302) +> Tasks 8.1-8.4 implemented in [ai-asset-upstream-migration-design.md](../../specifications/ai-asset-upstream-migration-design.md) via [#4223](https://github.com/redhat-developer/rhdh-plugins/issues/4223). + +- [x] 8.1 Create migration design document with mapping table: current kind/spec.type/annotation → target upstream kind (RHIDP-15302) +- [x] 8.2 Document transformation rules for each AI asset category (RHIDP-15302) +- [x] 8.3 Identify consumer-facing changes: catalog UI filters, entity refs, API queries (RHIDP-15302) +- [x] 8.4 Document backward compatibility strategy (e.g., keep annotation for one major version) (RHIDP-15302) - [ ] 8.5 Obtain upstream Backstage maintainer or RHDH architect sign-off on migration document (RHIDP-15302) - [ ] 8.6 Document sign-off in spec: reviewer name, role, date, approval status (RHIDP-15302) diff --git a/workspaces/boost/specifications/ai-asset-upstream-migration-design.md b/workspaces/boost/specifications/ai-asset-upstream-migration-design.md new file mode 100644 index 00000000000..179ea211cec --- /dev/null +++ b/workspaces/boost/specifications/ai-asset-upstream-migration-design.md @@ -0,0 +1,349 @@ +# AI Asset Upstream Migration Design + +> **Status: Draft** — Readiness design only. Actual migration is future work +> pending upstream RFC finalization. +> +> **Last updated:** 2026-08-10 +> +> **Story:** RHIDP-15302 (tasks 8.1-8.4) +> **Feature:** RHDHPLAN-1507 — Epic RHIDP-15258 +> **Parent issue:** +> [#4042](https://github.com/redhat-developer/rhdh-plugins/issues/4042) + +## 1. Purpose + +This document maps every current RHDH AI-asset entity representation to +its upstream Backstage target, documents field-level transformation +rules, identifies consumer-facing impact, and defines a backward +compatibility strategy. It is a **readiness design** — the actual +catalog migration is explicit future work. + +Platform engineers can use this document to understand what will change +when upstream entity kinds stabilize, and how RHDH will transition +without breaking existing catalog consumers. + +### Scope + +- All **seven** AI-asset categories per + [ai-catalog-entity-model/design.md Decision 1][decision-1]. +- Field-level transformation rules per category. +- Consumer-facing changes (catalog UI filters, entity refs, API + queries). +- Backward compatibility strategy. + +### Out of scope + +- **`vector-store` / `ai-tool`** categories — not yet confirmed as + AI-asset mapping rows. See + [catalog-entities spec][catalog-entities-spec] for tracking. +- Dry-run migration-readiness CLI — covered by + [#4220](https://github.com/redhat-developer/rhdh-plugins/issues/4220) + (RHIDP-15347). +- Annotation specification document (RHIDP-15346) — covered by + [#4220](https://github.com/redhat-developer/rhdh-plugins/issues/4220). +- Executing the actual catalog migration or implementing a catalog + processor. +- Re-writing mapping tables already reconciled in + [#4189](https://github.com/redhat-developer/rhdh-plugins/pull/4189). + +## 2. Current-State Source of Truth + +The authoritative current-state entity mapping is +[ai-catalog-entity-model/design.md Decision 1][decision-1]. It defines +seven `rhdh.io/ai-asset-category` values and their entity kind + +`spec.type` pairings: + +| Category | Backstage Kind | `spec.type` | Notes | +| -------------- | -------------- | ----------------- | -------------------------------------- | +| `agent` | Component | `ai-agent` | Pending RHDHPLAN-1113 agent kind def | +| `skill` | AIResource | `skill` | AIResource per RHDHPLAN-1113 | +| `rule` | AIResource | `rule` | AIResource per RHDHPLAN-1113 | +| `skill-bundle` | AIResource | `ai-skill-bundle` | Curated skill collections | +| `mcp-server` | API | `mcp-server` | Ships in RHDH 2.1 via RHDHPLAN-1510 | +| `ai-model` | Resource | `ai-model` | Pending RHDHPLAN-404 upstream work | +| `model-server` | Resource | `ai-model-server` | Pending RHDHPLAN-404 upstream work | + +All entities carry `rhdh.io/ai-asset-category` as the domain +classifier, independent of the Backstage structural kind. + +## 3. Mapping Table: Current to Upstream Target + +The mapping below was reconciled in +[#4188](https://github.com/redhat-developer/rhdh-plugins/issues/4188) / +[#4189](https://github.com/redhat-developer/rhdh-plugins/pull/4189) and +reflects the post-reconciliation OpenSpec state. Confidence levels +follow +[upstream-schema-alignment/design.md Decision 2][usa-design-d2]. + +| AI Asset | Current Kind | Current `spec.type` | `rhdh.io/ai-asset-category` | Upstream Target | Confidence | Notes | +| --- | --- | --- | --- | --- | --- | --- | +| MCP Server | `API` | `mcp-server` | `mcp-server` | Same — `McpServerApiEntity` ([backstage#34016][bs-34016], merged). **No kind rename.** | High | Kind already aligned. Remaining work is field/module gaps (see section 4). | +| Model Server | `Resource` | `ai-model-server` | `model-server` | Candidate `kind: API`, `spec.type: ai-model-server` ([backstage#34476][bs-34476], open PR; downstream [#4211][rhdh-4211]). **Not** a new kind. | Medium/Low | `Resource` to `API` kind change + field mapping. Hedge on open PR status. | +| AI Model | `Resource` | `ai-model` | `ai-model` | No solid upstream kind yet. | Low | Continue current mapping. Track future upstream proposals. | +| Skill | `AIResource` | `skill` | `skill` | `AiResource` (shipped upstream; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | +| Rule | `AIResource` | `rule` | `rule` | `AiResource` (shipped upstream; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | +| Skill Bundle | `AIResource` | `ai-skill-bundle` | `skill-bundle` | No upstream kind yet. | Low | Stay on current mapping; track future RFCs. | +| Agent | `Component` | `ai-agent` | `agent` | No upstream kind via RFC [#32062][bs-32062] (that RFC is MCP-only). Track RHIDP-15865 / [#4164][rhdh-4164] (`AiResource` + `spec.type: agent`). | Low | Do **not** attribute agent kind to RFC #32062. Agent-kind ownership tracked under RHDHPLAN-1113. | + +### Confidence level definitions + +| Level | Meaning | +| --- | --- | +| **High** | Upstream kind shipped and stable; RHDH kind already aligned. | +| **Medium-High** | Upstream kind shipped; field/name alignment work remains. | +| **Medium/Low** | Upstream target proposed in an open PR; hedge accordingly. | +| **Low** | No solid upstream kind yet, or mapping is speculative. | + +## 4. Transformation Rules + +Per-category field-level transformation rules. Each subsection covers +what changes beyond the kind and `spec.type`. + +### 4.1 MCP Server (High confidence) + +**Kind change:** None. `kind: API` stays `kind: API`. + +**Field transformations:** + +| Field | Current | Target | Action | +| --- | --- | --- | --- | +| `spec.type` | `mcp-server` | `mcp-server` | No change. | +| `spec.definition` | Free-form API definition string | `spec.remotes` (structured MCP server remotes) | Migrate `spec.definition` content to structured `spec.remotes` per `McpServerApiEntity` schema. | +| catalog-model module | Not opted in | `@backstage/plugin-catalog-backend-module-ai-model` | Opt in to the upstream AI catalog-model module for entity validation. | + +**Additional considerations:** + +- Flag any fallback `Resource`-kind entities that represent MCP servers. + These must be migrated to `kind: API` with `spec.type: mcp-server` + before upstream field alignment. +- The `rhdh.io/ai-asset-category: mcp-server` annotation remains for + backward compatibility during transition. + +### 4.2 Model Server (Medium/Low confidence) + +**Kind change:** `Resource` to `API` (if +[backstage#34476][bs-34476] merges). + +**Field transformations (conditional on PR merge):** + +| Field | Current | Target | Action | +| --- | --- | --- | --- | +| `kind` | `Resource` | `API` | Kind change from Resource to API. | +| `spec.type` | `ai-model-server` | `ai-model-server` | No change to type value. | +| `spec.owner` | Standard | Standard | No change (both kinds use `spec.owner`). | +| `spec.serverType` | Not present | Required (`serverType`) | Add `spec.serverType` per upstream schema. | +| `spec.serverUrl` | Not present | Required (`spec.serverUrl`) | Add `spec.serverUrl` per upstream schema. | +| `spec.models` | Not present | Optional (`spec.models`) | Add discoverable/available/default model lists if applicable. | + +**Hedge:** This mapping is conditional on +[backstage#34476][bs-34476] merging. If the PR is declined or the +schema changes, the transformation rules will need to be updated. +Downstream implementation: +[#4211](https://github.com/redhat-developer/rhdh-plugins/pull/4211). + +### 4.3 AI Model (Low confidence) + +**Kind change:** Unknown — no solid upstream kind proposed. + +**Field transformations:** None defined. Continue using `kind: Resource`, +`spec.type: ai-model` until upstream stabilizes. + +**Recommendation:** Track future upstream proposals. When an upstream +kind is proposed, revisit this section with concrete field-level +transformation rules. + +### 4.4 Skill (Medium-High confidence) + +**Kind change:** `AIResource` to `AiResource` (casing alignment). + +**Field transformations:** + +| Field | Current | Target | Action | +| --- | --- | --- | --- | +| `kind` | `AIResource` | `AiResource` | Casing change. Backstage lowercases kind in entity refs, so `airesource:default/my-skill` stays the same. | +| `spec.type` | `skill` | `skill` | No change. | +| `spec.*` fields | RHDH-defined fields | Upstream `AiResource` schema fields | Align field names and types per upstream `AiResource` schema ([#33575][bs-33575] lineage). | + +**Note:** The `AIResource` to `AiResource` casing change does not +affect entity ref strings because Backstage lowercases the kind prefix +(`airesource:default/...` in both cases). + +### 4.5 Rule (Medium-High confidence) + +**Kind change:** `AIResource` to `AiResource` (casing alignment). + +**Field transformations:** Same as Skill (section 4.4). Rules use the +same `AiResource` upstream kind with `spec.type: rule` to distinguish +them from skills. + +### 4.6 Skill Bundle (Low confidence) + +**Kind change:** Unknown — no upstream kind proposed. + +**Field transformations:** None defined. Continue using +`kind: AIResource`, `spec.type: ai-skill-bundle`. + +**Recommendation:** Stay on current mapping. Track future upstream RFCs +that may define a bundle or collection kind. + +### 4.7 Agent (Low confidence) + +**Kind change:** Unknown — no upstream kind via RFC +[#32062][bs-32062] (that RFC is MCP-only, not agent). + +**Field transformations:** None defined. Continue using +`kind: Component`, `spec.type: ai-agent`. + +**Current work in progress:** + +- RHIDP-15865 / + [#4164](https://github.com/redhat-developer/rhdh-plugins/pull/4164) + is adding `AiResource` + `spec.type: agent` schema support + downstream. This represents a potential migration path from + `Component` to `AiResource` for agents, but the upstream agent-kind + ownership is still tracked under RHDHPLAN-1113. + +**Recommendation:** Do not attribute agent kind to RFC #32062. Track +agent-kind ownership under RHDHPLAN-1113 and RHIDP-15865. + +## 5. Consumer-Facing Changes + +Migration to upstream entity kinds will affect three consumer-facing +areas: catalog UI filters, entity references, and API queries. + +### 5.1 Catalog UI Filters + +| Category | Current filter | Post-migration filter | Impact | +| --- | --- | --- | --- | +| MCP Server | `kind: API` + `rhdh.io/ai-asset-category: mcp-server` | No change (kind already aligned). | **None.** | +| Model Server | `kind: Resource` + `rhdh.io/ai-asset-category: model-server` | `kind: API`, `spec.type: ai-model-server` (if [#34476][bs-34476] merges). | **Kind filter changes** from `Resource` to `API`. | +| AI Model | `kind: Resource` + `rhdh.io/ai-asset-category: ai-model` | No change (no upstream kind yet). | **None** until upstream kind proposed. | +| Skill | `kind: AIResource` + `rhdh.io/ai-asset-category: skill` | `kind: AiResource` (casing change). Annotation filter still useful for category distinction. | **Minimal** — casing change only. | +| Rule | `kind: AIResource` + `rhdh.io/ai-asset-category: rule` | `kind: AiResource` (casing change). | **Minimal** — same as Skill. | +| Skill Bundle | `kind: AIResource` + `rhdh.io/ai-asset-category: skill-bundle` | No change (no upstream kind yet). | **None** until upstream kind proposed. | +| Agent | `kind: Component` + `rhdh.io/ai-asset-category: agent` | No change (no upstream kind yet). | **None** until upstream kind proposed. | + +### 5.2 Entity References + +| Category | Current entity ref | Post-migration entity ref | Impact | +| --- | --- | --- | --- | +| MCP Server | `api:default/my-mcp-server` | `api:default/my-mcp-server` | **No change.** | +| Model Server | `resource:default/my-server` | `api:default/my-server` (if [#34476][bs-34476] merges). | **Breaking** — entity ref kind prefix changes from `resource:` to `api:`. All entity links, relationship references, and stored entity refs must be updated. | +| AI Model | `resource:default/my-model` | No change. | **No change.** | +| Skill | `airesource:default/my-skill` | `airesource:default/my-skill` | **No change.** Backstage lowercases kind prefixes; `AIResource` and `AiResource` both produce `airesource:`. | +| Rule | `airesource:default/my-rule` | `airesource:default/my-rule` | **No change** (same as Skill). | +| Skill Bundle | `airesource:default/my-bundle` | No change. | **No change.** | +| Agent | `component:default/my-agent` | No change. | **No change.** | + +### 5.3 API Queries + +| Category | Current query | Post-migration query | Impact | +| --- | --- | --- | --- | +| MCP Server | `?filter=kind=API,spec.type=mcp-server` | No change. | **None.** | +| Model Server | `?filter=kind=Resource,rhdh.io/ai-asset-category=model-server` | `?filter=kind=API,spec.type=ai-model-server` (if [#34476][bs-34476] merges). | **Breaking** — both kind and filter field change. | +| AI Model | `?filter=kind=Resource,rhdh.io/ai-asset-category=ai-model` | No change. | **None.** | +| Skill | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill` | `?filter=kind=AiResource,rhdh.io/ai-asset-category=skill` | **Minimal** — casing change in kind filter value. | +| Rule | `?filter=kind=AIResource,rhdh.io/ai-asset-category=rule` | `?filter=kind=AiResource,rhdh.io/ai-asset-category=rule` | **Minimal** — same as Skill. | +| Skill Bundle | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill-bundle` | No change. | **None.** | +| Agent | `?filter=kind=Component,rhdh.io/ai-asset-category=agent` | No change. | **None.** | + +## 6. Backward Compatibility + +### Strategy + +Keep the `rhdh.io/ai-asset-category` annotation on migrated entities +for **one major RHDH version** after migration. This allows consumers +to query using both old and new filter patterns during the transition +period. + +### Deprecation approach + +1. **Announcement:** Include migration guidance in the RHDH release + notes for the version that introduces upstream kind alignment. +2. **Dual-filter period:** For one major version, both old and new + query patterns return results. The `rhdh.io/ai-asset-category` + annotation remains on all entities regardless of the new kind. +3. **Deprecation notice:** Mark the old query patterns as deprecated + in the API documentation and catalog UI. +4. **Removal:** In the following major version, remove support for + the deprecated query patterns. The annotation itself may persist + as a useful domain classifier even after kind alignment. + +### Per-category compatibility notes + +| Category | Compatibility impact | Notes | +| --- | --- | --- | +| MCP Server | **No breaking change** | Kind already aligned. Only field/module changes. | +| Model Server | **Breaking** (conditional) | Kind changes from `Resource` to `API`. Entity refs change. Requires dual-filter support during transition. Conditional on [#34476][bs-34476]. | +| AI Model | **No change** | No upstream kind yet. | +| Skill / Rule | **Minimal** | Casing change only (`AIResource` to `AiResource`). Entity refs unchanged. | +| Skill Bundle | **No change** | No upstream kind yet. | +| Agent | **No change** | No upstream kind yet. | + +## 7. Out of Scope + +The following items are explicitly **not** covered by this design +document: + +- **`vector-store` / `ai-tool` categories** — These are Augment + leftovers not yet confirmed as AI-asset mapping rows. See + [catalog-entities spec][catalog-entities-spec] for tracking. +- **Dry-run migration-readiness CLI** (RHIDP-15347) — Covered by + [#4220](https://github.com/redhat-developer/rhdh-plugins/issues/4220). +- **Annotation specification document** (RHIDP-15346) — Covered by + [#4220](https://github.com/redhat-developer/rhdh-plugins/issues/4220). +- **Live catalog migration** — Executing the actual entity migration + (re-mapping entities to finalized upstream kinds) is future work + dependent on RFC finalization. +- **Catalog processor for automated migration** — Future work once + upstream targets are stable and migration is approved. +- **Entity kind transition plan** — Detailed rollout plan for + production migration is future work. + +## 8. Sign-Off + +> This section is a placeholder for reviewer sign-off per +> [#4042](https://github.com/redhat-developer/rhdh-plugins/issues/4042) +> tasks 8.5-8.6. It will be filled in by a human reviewer after this +> document is merged. + +| Field | Value | +| --- | --- | +| Reviewer | _(to be filled)_ | +| Role | RHDH Architect | +| Date | _(to be filled)_ | +| Status | _(pending review)_ | + +--- + +## References + +- [ai-catalog-entity-model/design.md Decision 1][decision-1] — + Current-state source of truth for entity kinds and categories +- [upstream-schema-alignment/proposal.md][usa-proposal] — + Upstream schema alignment proposal +- [upstream-schema-alignment/design.md][usa-design] — + Upstream schema alignment design +- [annotation-specification/spec.md][annotation-spec] — + Annotation specification (RHIDP-15346) +- [migration-readiness/spec.md][migration-spec] — + Migration readiness specification (RHIDP-15302) +- [#4189](https://github.com/redhat-developer/rhdh-plugins/pull/4189) + — Mapping table reconciliation PR +- [#4042 gate comment][gate-comment] — Pre-implementation gate + decisions + +[decision-1]: ../openspec/changes/ai-catalog-entity-model/design.md +[usa-proposal]: ../openspec/changes/upstream-schema-alignment/proposal.md +[usa-design]: ../openspec/changes/upstream-schema-alignment/design.md +[usa-design-d2]: ../openspec/changes/upstream-schema-alignment/design.md#decision-2-mapping-table-structure-with-confidence-levels +[annotation-spec]: ../openspec/changes/upstream-schema-alignment/specs/annotation-specification/spec.md +[migration-spec]: ../openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md +[catalog-entities-spec]: ../openspec/changes/agent-creation-discovery/specs/catalog-entities/spec.md +[gate-comment]: https://github.com/redhat-developer/rhdh-plugins/issues/4042#issuecomment-5204217995 +[bs-34016]: https://github.com/backstage/backstage/pull/34016 +[bs-34476]: https://github.com/backstage/backstage/pull/34476 +[bs-33575]: https://github.com/backstage/backstage/issues/33575 +[bs-32062]: https://github.com/backstage/backstage/issues/32062 +[rhdh-4211]: https://github.com/redhat-developer/rhdh-plugins/pull/4211 +[rhdh-4164]: https://github.com/redhat-developer/rhdh-plugins/pull/4164 From 5c81e97c6648356393f67131fb17f13a5691310e Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 10:08:25 +0000 Subject: [PATCH 2/4] fix(#4223): apply prettier formatting to migration design doc Reformat markdown tables in ai-asset-upstream-migration-design.md to satisfy prettier CI checks. Addresses review feedback on #4225 --- .../ai-asset-upstream-migration-design.md | 166 +++++++++--------- 1 file changed, 83 insertions(+), 83 deletions(-) diff --git a/workspaces/boost/specifications/ai-asset-upstream-migration-design.md b/workspaces/boost/specifications/ai-asset-upstream-migration-design.md index 179ea211cec..9156d23c30c 100644 --- a/workspaces/boost/specifications/ai-asset-upstream-migration-design.md +++ b/workspaces/boost/specifications/ai-asset-upstream-migration-design.md @@ -50,18 +50,18 @@ without breaking existing catalog consumers. The authoritative current-state entity mapping is [ai-catalog-entity-model/design.md Decision 1][decision-1]. It defines -seven `rhdh.io/ai-asset-category` values and their entity kind + +seven `rhdh.io/ai-asset-category` values and their entity kind + `spec.type` pairings: -| Category | Backstage Kind | `spec.type` | Notes | -| -------------- | -------------- | ----------------- | -------------------------------------- | -| `agent` | Component | `ai-agent` | Pending RHDHPLAN-1113 agent kind def | -| `skill` | AIResource | `skill` | AIResource per RHDHPLAN-1113 | -| `rule` | AIResource | `rule` | AIResource per RHDHPLAN-1113 | -| `skill-bundle` | AIResource | `ai-skill-bundle` | Curated skill collections | -| `mcp-server` | API | `mcp-server` | Ships in RHDH 2.1 via RHDHPLAN-1510 | -| `ai-model` | Resource | `ai-model` | Pending RHDHPLAN-404 upstream work | -| `model-server` | Resource | `ai-model-server` | Pending RHDHPLAN-404 upstream work | +| Category | Backstage Kind | `spec.type` | Notes | +| -------------- | -------------- | ----------------- | ------------------------------------ | +| `agent` | Component | `ai-agent` | Pending RHDHPLAN-1113 agent kind def | +| `skill` | AIResource | `skill` | AIResource per RHDHPLAN-1113 | +| `rule` | AIResource | `rule` | AIResource per RHDHPLAN-1113 | +| `skill-bundle` | AIResource | `ai-skill-bundle` | Curated skill collections | +| `mcp-server` | API | `mcp-server` | Ships in RHDH 2.1 via RHDHPLAN-1510 | +| `ai-model` | Resource | `ai-model` | Pending RHDHPLAN-404 upstream work | +| `model-server` | Resource | `ai-model-server` | Pending RHDHPLAN-404 upstream work | All entities carry `rhdh.io/ai-asset-category` as the domain classifier, independent of the Backstage structural kind. @@ -75,24 +75,24 @@ reflects the post-reconciliation OpenSpec state. Confidence levels follow [upstream-schema-alignment/design.md Decision 2][usa-design-d2]. -| AI Asset | Current Kind | Current `spec.type` | `rhdh.io/ai-asset-category` | Upstream Target | Confidence | Notes | -| --- | --- | --- | --- | --- | --- | --- | -| MCP Server | `API` | `mcp-server` | `mcp-server` | Same — `McpServerApiEntity` ([backstage#34016][bs-34016], merged). **No kind rename.** | High | Kind already aligned. Remaining work is field/module gaps (see section 4). | -| Model Server | `Resource` | `ai-model-server` | `model-server` | Candidate `kind: API`, `spec.type: ai-model-server` ([backstage#34476][bs-34476], open PR; downstream [#4211][rhdh-4211]). **Not** a new kind. | Medium/Low | `Resource` to `API` kind change + field mapping. Hedge on open PR status. | -| AI Model | `Resource` | `ai-model` | `ai-model` | No solid upstream kind yet. | Low | Continue current mapping. Track future upstream proposals. | -| Skill | `AIResource` | `skill` | `skill` | `AiResource` (shipped upstream; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | -| Rule | `AIResource` | `rule` | `rule` | `AiResource` (shipped upstream; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | -| Skill Bundle | `AIResource` | `ai-skill-bundle` | `skill-bundle` | No upstream kind yet. | Low | Stay on current mapping; track future RFCs. | -| Agent | `Component` | `ai-agent` | `agent` | No upstream kind via RFC [#32062][bs-32062] (that RFC is MCP-only). Track RHIDP-15865 / [#4164][rhdh-4164] (`AiResource` + `spec.type: agent`). | Low | Do **not** attribute agent kind to RFC #32062. Agent-kind ownership tracked under RHDHPLAN-1113. | +| AI Asset | Current Kind | Current `spec.type` | `rhdh.io/ai-asset-category` | Upstream Target | Confidence | Notes | +| ------------ | ------------ | ------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------ | +| MCP Server | `API` | `mcp-server` | `mcp-server` | Same — `McpServerApiEntity` ([backstage#34016][bs-34016], merged). **No kind rename.** | High | Kind already aligned. Remaining work is field/module gaps (see section 4). | +| Model Server | `Resource` | `ai-model-server` | `model-server` | Candidate `kind: API`, `spec.type: ai-model-server` ([backstage#34476][bs-34476], open PR; downstream [#4211][rhdh-4211]). **Not** a new kind. | Medium/Low | `Resource` to `API` kind change + field mapping. Hedge on open PR status. | +| AI Model | `Resource` | `ai-model` | `ai-model` | No solid upstream kind yet. | Low | Continue current mapping. Track future upstream proposals. | +| Skill | `AIResource` | `skill` | `skill` | `AiResource` (shipped upstream; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | +| Rule | `AIResource` | `rule` | `rule` | `AiResource` (shipped upstream; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | +| Skill Bundle | `AIResource` | `ai-skill-bundle` | `skill-bundle` | No upstream kind yet. | Low | Stay on current mapping; track future RFCs. | +| Agent | `Component` | `ai-agent` | `agent` | No upstream kind via RFC [#32062][bs-32062] (that RFC is MCP-only). Track RHIDP-15865 / [#4164][rhdh-4164] (`AiResource` + `spec.type: agent`). | Low | Do **not** attribute agent kind to RFC #32062. Agent-kind ownership tracked under RHDHPLAN-1113. | ### Confidence level definitions -| Level | Meaning | -| --- | --- | -| **High** | Upstream kind shipped and stable; RHDH kind already aligned. | -| **Medium-High** | Upstream kind shipped; field/name alignment work remains. | -| **Medium/Low** | Upstream target proposed in an open PR; hedge accordingly. | -| **Low** | No solid upstream kind yet, or mapping is speculative. | +| Level | Meaning | +| --------------- | ------------------------------------------------------------ | +| **High** | Upstream kind shipped and stable; RHDH kind already aligned. | +| **Medium-High** | Upstream kind shipped; field/name alignment work remains. | +| **Medium/Low** | Upstream target proposed in an open PR; hedge accordingly. | +| **Low** | No solid upstream kind yet, or mapping is speculative. | ## 4. Transformation Rules @@ -105,11 +105,11 @@ what changes beyond the kind and `spec.type`. **Field transformations:** -| Field | Current | Target | Action | -| --- | --- | --- | --- | -| `spec.type` | `mcp-server` | `mcp-server` | No change. | -| `spec.definition` | Free-form API definition string | `spec.remotes` (structured MCP server remotes) | Migrate `spec.definition` content to structured `spec.remotes` per `McpServerApiEntity` schema. | -| catalog-model module | Not opted in | `@backstage/plugin-catalog-backend-module-ai-model` | Opt in to the upstream AI catalog-model module for entity validation. | +| Field | Current | Target | Action | +| -------------------- | ------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| `spec.type` | `mcp-server` | `mcp-server` | No change. | +| `spec.definition` | Free-form API definition string | `spec.remotes` (structured MCP server remotes) | Migrate `spec.definition` content to structured `spec.remotes` per `McpServerApiEntity` schema. | +| catalog-model module | Not opted in | `@backstage/plugin-catalog-backend-module-ai-model` | Opt in to the upstream AI catalog-model module for entity validation. | **Additional considerations:** @@ -126,14 +126,14 @@ what changes beyond the kind and `spec.type`. **Field transformations (conditional on PR merge):** -| Field | Current | Target | Action | -| --- | --- | --- | --- | -| `kind` | `Resource` | `API` | Kind change from Resource to API. | -| `spec.type` | `ai-model-server` | `ai-model-server` | No change to type value. | -| `spec.owner` | Standard | Standard | No change (both kinds use `spec.owner`). | -| `spec.serverType` | Not present | Required (`serverType`) | Add `spec.serverType` per upstream schema. | -| `spec.serverUrl` | Not present | Required (`spec.serverUrl`) | Add `spec.serverUrl` per upstream schema. | -| `spec.models` | Not present | Optional (`spec.models`) | Add discoverable/available/default model lists if applicable. | +| Field | Current | Target | Action | +| ----------------- | ----------------- | --------------------------- | ------------------------------------------------------------- | +| `kind` | `Resource` | `API` | Kind change from Resource to API. | +| `spec.type` | `ai-model-server` | `ai-model-server` | No change to type value. | +| `spec.owner` | Standard | Standard | No change (both kinds use `spec.owner`). | +| `spec.serverType` | Not present | Required (`serverType`) | Add `spec.serverType` per upstream schema. | +| `spec.serverUrl` | Not present | Required (`spec.serverUrl`) | Add `spec.serverUrl` per upstream schema. | +| `spec.models` | Not present | Optional (`spec.models`) | Add discoverable/available/default model lists if applicable. | **Hedge:** This mapping is conditional on [backstage#34476][bs-34476] merging. If the PR is declined or the @@ -158,11 +158,11 @@ transformation rules. **Field transformations:** -| Field | Current | Target | Action | -| --- | --- | --- | --- | -| `kind` | `AIResource` | `AiResource` | Casing change. Backstage lowercases kind in entity refs, so `airesource:default/my-skill` stays the same. | -| `spec.type` | `skill` | `skill` | No change. | -| `spec.*` fields | RHDH-defined fields | Upstream `AiResource` schema fields | Align field names and types per upstream `AiResource` schema ([#33575][bs-33575] lineage). | +| Field | Current | Target | Action | +| --------------- | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `kind` | `AIResource` | `AiResource` | Casing change. Backstage lowercases kind in entity refs, so `airesource:default/my-skill` stays the same. | +| `spec.type` | `skill` | `skill` | No change. | +| `spec.*` fields | RHDH-defined fields | Upstream `AiResource` schema fields | Align field names and types per upstream `AiResource` schema ([#33575][bs-33575] lineage). | **Note:** The `AIResource` to `AiResource` casing change does not affect entity ref strings because Backstage lowercases the kind prefix @@ -213,39 +213,39 @@ areas: catalog UI filters, entity references, and API queries. ### 5.1 Catalog UI Filters -| Category | Current filter | Post-migration filter | Impact | -| --- | --- | --- | --- | -| MCP Server | `kind: API` + `rhdh.io/ai-asset-category: mcp-server` | No change (kind already aligned). | **None.** | -| Model Server | `kind: Resource` + `rhdh.io/ai-asset-category: model-server` | `kind: API`, `spec.type: ai-model-server` (if [#34476][bs-34476] merges). | **Kind filter changes** from `Resource` to `API`. | -| AI Model | `kind: Resource` + `rhdh.io/ai-asset-category: ai-model` | No change (no upstream kind yet). | **None** until upstream kind proposed. | -| Skill | `kind: AIResource` + `rhdh.io/ai-asset-category: skill` | `kind: AiResource` (casing change). Annotation filter still useful for category distinction. | **Minimal** — casing change only. | -| Rule | `kind: AIResource` + `rhdh.io/ai-asset-category: rule` | `kind: AiResource` (casing change). | **Minimal** — same as Skill. | -| Skill Bundle | `kind: AIResource` + `rhdh.io/ai-asset-category: skill-bundle` | No change (no upstream kind yet). | **None** until upstream kind proposed. | -| Agent | `kind: Component` + `rhdh.io/ai-asset-category: agent` | No change (no upstream kind yet). | **None** until upstream kind proposed. | +| Category | Current filter | Post-migration filter | Impact | +| ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------- | +| MCP Server | `kind: API` + `rhdh.io/ai-asset-category: mcp-server` | No change (kind already aligned). | **None.** | +| Model Server | `kind: Resource` + `rhdh.io/ai-asset-category: model-server` | `kind: API`, `spec.type: ai-model-server` (if [#34476][bs-34476] merges). | **Kind filter changes** from `Resource` to `API`. | +| AI Model | `kind: Resource` + `rhdh.io/ai-asset-category: ai-model` | No change (no upstream kind yet). | **None** until upstream kind proposed. | +| Skill | `kind: AIResource` + `rhdh.io/ai-asset-category: skill` | `kind: AiResource` (casing change). Annotation filter still useful for category distinction. | **Minimal** — casing change only. | +| Rule | `kind: AIResource` + `rhdh.io/ai-asset-category: rule` | `kind: AiResource` (casing change). | **Minimal** — same as Skill. | +| Skill Bundle | `kind: AIResource` + `rhdh.io/ai-asset-category: skill-bundle` | No change (no upstream kind yet). | **None** until upstream kind proposed. | +| Agent | `kind: Component` + `rhdh.io/ai-asset-category: agent` | No change (no upstream kind yet). | **None** until upstream kind proposed. | ### 5.2 Entity References -| Category | Current entity ref | Post-migration entity ref | Impact | -| --- | --- | --- | --- | -| MCP Server | `api:default/my-mcp-server` | `api:default/my-mcp-server` | **No change.** | -| Model Server | `resource:default/my-server` | `api:default/my-server` (if [#34476][bs-34476] merges). | **Breaking** — entity ref kind prefix changes from `resource:` to `api:`. All entity links, relationship references, and stored entity refs must be updated. | -| AI Model | `resource:default/my-model` | No change. | **No change.** | -| Skill | `airesource:default/my-skill` | `airesource:default/my-skill` | **No change.** Backstage lowercases kind prefixes; `AIResource` and `AiResource` both produce `airesource:`. | -| Rule | `airesource:default/my-rule` | `airesource:default/my-rule` | **No change** (same as Skill). | -| Skill Bundle | `airesource:default/my-bundle` | No change. | **No change.** | -| Agent | `component:default/my-agent` | No change. | **No change.** | +| Category | Current entity ref | Post-migration entity ref | Impact | +| ------------ | ------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| MCP Server | `api:default/my-mcp-server` | `api:default/my-mcp-server` | **No change.** | +| Model Server | `resource:default/my-server` | `api:default/my-server` (if [#34476][bs-34476] merges). | **Breaking** — entity ref kind prefix changes from `resource:` to `api:`. All entity links, relationship references, and stored entity refs must be updated. | +| AI Model | `resource:default/my-model` | No change. | **No change.** | +| Skill | `airesource:default/my-skill` | `airesource:default/my-skill` | **No change.** Backstage lowercases kind prefixes; `AIResource` and `AiResource` both produce `airesource:`. | +| Rule | `airesource:default/my-rule` | `airesource:default/my-rule` | **No change** (same as Skill). | +| Skill Bundle | `airesource:default/my-bundle` | No change. | **No change.** | +| Agent | `component:default/my-agent` | No change. | **No change.** | ### 5.3 API Queries -| Category | Current query | Post-migration query | Impact | -| --- | --- | --- | --- | -| MCP Server | `?filter=kind=API,spec.type=mcp-server` | No change. | **None.** | -| Model Server | `?filter=kind=Resource,rhdh.io/ai-asset-category=model-server` | `?filter=kind=API,spec.type=ai-model-server` (if [#34476][bs-34476] merges). | **Breaking** — both kind and filter field change. | -| AI Model | `?filter=kind=Resource,rhdh.io/ai-asset-category=ai-model` | No change. | **None.** | -| Skill | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill` | `?filter=kind=AiResource,rhdh.io/ai-asset-category=skill` | **Minimal** — casing change in kind filter value. | -| Rule | `?filter=kind=AIResource,rhdh.io/ai-asset-category=rule` | `?filter=kind=AiResource,rhdh.io/ai-asset-category=rule` | **Minimal** — same as Skill. | -| Skill Bundle | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill-bundle` | No change. | **None.** | -| Agent | `?filter=kind=Component,rhdh.io/ai-asset-category=agent` | No change. | **None.** | +| Category | Current query | Post-migration query | Impact | +| ------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------- | +| MCP Server | `?filter=kind=API,spec.type=mcp-server` | No change. | **None.** | +| Model Server | `?filter=kind=Resource,rhdh.io/ai-asset-category=model-server` | `?filter=kind=API,spec.type=ai-model-server` (if [#34476][bs-34476] merges). | **Breaking** — both kind and filter field change. | +| AI Model | `?filter=kind=Resource,rhdh.io/ai-asset-category=ai-model` | No change. | **None.** | +| Skill | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill` | `?filter=kind=AiResource,rhdh.io/ai-asset-category=skill` | **Minimal** — casing change in kind filter value. | +| Rule | `?filter=kind=AIResource,rhdh.io/ai-asset-category=rule` | `?filter=kind=AiResource,rhdh.io/ai-asset-category=rule` | **Minimal** — same as Skill. | +| Skill Bundle | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill-bundle` | No change. | **None.** | +| Agent | `?filter=kind=Component,rhdh.io/ai-asset-category=agent` | No change. | **None.** | ## 6. Backward Compatibility @@ -271,14 +271,14 @@ period. ### Per-category compatibility notes -| Category | Compatibility impact | Notes | -| --- | --- | --- | -| MCP Server | **No breaking change** | Kind already aligned. Only field/module changes. | +| Category | Compatibility impact | Notes | +| ------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| MCP Server | **No breaking change** | Kind already aligned. Only field/module changes. | | Model Server | **Breaking** (conditional) | Kind changes from `Resource` to `API`. Entity refs change. Requires dual-filter support during transition. Conditional on [#34476][bs-34476]. | -| AI Model | **No change** | No upstream kind yet. | -| Skill / Rule | **Minimal** | Casing change only (`AIResource` to `AiResource`). Entity refs unchanged. | -| Skill Bundle | **No change** | No upstream kind yet. | -| Agent | **No change** | No upstream kind yet. | +| AI Model | **No change** | No upstream kind yet. | +| Skill / Rule | **Minimal** | Casing change only (`AIResource` to `AiResource`). Entity refs unchanged. | +| Skill Bundle | **No change** | No upstream kind yet. | +| Agent | **No change** | No upstream kind yet. | ## 7. Out of Scope @@ -307,12 +307,12 @@ document: > tasks 8.5-8.6. It will be filled in by a human reviewer after this > document is merged. -| Field | Value | -| --- | --- | -| Reviewer | _(to be filled)_ | -| Role | RHDH Architect | -| Date | _(to be filled)_ | -| Status | _(pending review)_ | +| Field | Value | +| -------- | ------------------ | +| Reviewer | _(to be filled)_ | +| Role | RHDH Architect | +| Date | _(to be filled)_ | +| Status | _(pending review)_ | --- From 4bf0a0db646f715f018c6b0e20db992d4f750435 Mon Sep 17 00:00:00 2001 From: Marek Libra Date: Mon, 10 Aug 2026 13:35:04 +0200 Subject: [PATCH 3/4] fix(#4223): address review findings on migration design doc Correct broken cross-links to the design doc, complete model-server field mapping for backstage#34476, and clarify MCP remotes, AiResource citations, and heading style. Signed-off-by: Marek Libra --- .../specs/migration-readiness/spec.md | 2 +- .../changes/ai-catalog-entity-model/tasks.md | 2 +- .../ai-asset-upstream-migration-design.md | 90 +++++++++++-------- 3 files changed, 55 insertions(+), 39 deletions(-) diff --git a/workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md b/workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md index 035de7beb61..707d03e7945 100644 --- a/workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md +++ b/workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md @@ -2,7 +2,7 @@ > **Status: Draft** — Pre-implementation specification. Subject to change during implementation. > -> **Design document:** [ai-asset-upstream-migration-design.md](../../../../specifications/ai-asset-upstream-migration-design.md) — implements RHIDP-15302 tasks 8.1-8.4 from this specification. +> **Design document:** [ai-asset-upstream-migration-design.md](../../../../../specifications/ai-asset-upstream-migration-design.md) — implements RHIDP-15302 tasks 8.1-8.4 from this specification. Design document mapping custom annotations and entity kinds to upstream Backstage entity kind targets, identifying consumer-facing changes, and obtaining upstream sign-off. Current-state source of truth: [ai-catalog-entity-model/design.md Decision 1](../../design.md). MCP server kind is already aligned with upstream (`McpServerApiEntity`, [backstage#34016](https://github.com/backstage/backstage/pull/34016)); RFC [#32062](https://github.com/backstage/backstage/issues/32062) is MCP-only and does **not** define an `AIAgent` kind. diff --git a/workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md b/workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md index 20f86f6c0c4..a3d62a52657 100644 --- a/workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md +++ b/workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md @@ -84,7 +84,7 @@ ## 8. Migration Readiness Design (P2) — _RHIDP-15258_ -> Tasks 8.1-8.4 implemented in [ai-asset-upstream-migration-design.md](../../specifications/ai-asset-upstream-migration-design.md) via [#4223](https://github.com/redhat-developer/rhdh-plugins/issues/4223). +> Tasks 8.1-8.4 implemented in [ai-asset-upstream-migration-design.md](../../../specifications/ai-asset-upstream-migration-design.md) via [#4223](https://github.com/redhat-developer/rhdh-plugins/issues/4223). - [x] 8.1 Create migration design document with mapping table: current kind/spec.type/annotation → target upstream kind (RHIDP-15302) - [x] 8.2 Document transformation rules for each AI asset category (RHIDP-15302) diff --git a/workspaces/boost/specifications/ai-asset-upstream-migration-design.md b/workspaces/boost/specifications/ai-asset-upstream-migration-design.md index 9156d23c30c..37a16fba3df 100644 --- a/workspaces/boost/specifications/ai-asset-upstream-migration-design.md +++ b/workspaces/boost/specifications/ai-asset-upstream-migration-design.md @@ -10,7 +10,7 @@ > **Parent issue:** > [#4042](https://github.com/redhat-developer/rhdh-plugins/issues/4042) -## 1. Purpose +## Purpose This document maps every current RHDH AI-asset entity representation to its upstream Backstage target, documents field-level transformation @@ -46,7 +46,7 @@ without breaking existing catalog consumers. - Re-writing mapping tables already reconciled in [#4189](https://github.com/redhat-developer/rhdh-plugins/pull/4189). -## 2. Current-State Source of Truth +## Current-State Source of Truth The authoritative current-state entity mapping is [ai-catalog-entity-model/design.md Decision 1][decision-1]. It defines @@ -66,7 +66,13 @@ seven `rhdh.io/ai-asset-category` values and their entity kind + All entities carry `rhdh.io/ai-asset-category` as the domain classifier, independent of the Backstage structural kind. -## 3. Mapping Table: Current to Upstream Target +> **Note:** Decision 1 still lists `AIResource` as the current kind for +> skills/rules/skill-bundles. In-tree Boost fixtures and plugin tests +> already emit `kind: AiResource`, so casing alignment may already be +> done locally. Decision 1 remains the source of truth for this +> document; any Decision 1 wording update is separate follow-up work. + +## Mapping Table: Current to Upstream Target The mapping below was reconciled in [#4188](https://github.com/redhat-developer/rhdh-plugins/issues/4188) / @@ -77,11 +83,11 @@ follow | AI Asset | Current Kind | Current `spec.type` | `rhdh.io/ai-asset-category` | Upstream Target | Confidence | Notes | | ------------ | ------------ | ------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------ | -| MCP Server | `API` | `mcp-server` | `mcp-server` | Same — `McpServerApiEntity` ([backstage#34016][bs-34016], merged). **No kind rename.** | High | Kind already aligned. Remaining work is field/module gaps (see section 4). | +| MCP Server | `API` | `mcp-server` | `mcp-server` | Same — `McpServerApiEntity` ([backstage#34016][bs-34016], merged). **No kind rename.** | High | Kind already aligned. Remaining work is field/module gaps (see Transformation Rules). | | Model Server | `Resource` | `ai-model-server` | `model-server` | Candidate `kind: API`, `spec.type: ai-model-server` ([backstage#34476][bs-34476], open PR; downstream [#4211][rhdh-4211]). **Not** a new kind. | Medium/Low | `Resource` to `API` kind change + field mapping. Hedge on open PR status. | | AI Model | `Resource` | `ai-model` | `ai-model` | No solid upstream kind yet. | Low | Continue current mapping. Track future upstream proposals. | -| Skill | `AIResource` | `skill` | `skill` | `AiResource` (shipped upstream; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | -| Rule | `AIResource` | `rule` | `rule` | `AiResource` (shipped upstream; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | +| Skill | `AIResource` | `skill` | `skill` | `AiResource` (shipped upstream; see [Backstage 1.51][bs-1-51] / [#34876][bs-34876]; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | +| Rule | `AIResource` | `rule` | `rule` | `AiResource` (shipped upstream; see [Backstage 1.51][bs-1-51] / [#34876][bs-34876]; [#33575][bs-33575] lineage). | Medium-High | Kind/name casing alignment (`AIResource` to `AiResource`). Field alignment needed. | | Skill Bundle | `AIResource` | `ai-skill-bundle` | `skill-bundle` | No upstream kind yet. | Low | Stay on current mapping; track future RFCs. | | Agent | `Component` | `ai-agent` | `agent` | No upstream kind via RFC [#32062][bs-32062] (that RFC is MCP-only). Track RHIDP-15865 / [#4164][rhdh-4164] (`AiResource` + `spec.type: agent`). | Low | Do **not** attribute agent kind to RFC #32062. Agent-kind ownership tracked under RHDHPLAN-1113. | @@ -94,12 +100,12 @@ follow | **Medium/Low** | Upstream target proposed in an open PR; hedge accordingly. | | **Low** | No solid upstream kind yet, or mapping is speculative. | -## 4. Transformation Rules +## Transformation Rules Per-category field-level transformation rules. Each subsection covers what changes beyond the kind and `spec.type`. -### 4.1 MCP Server (High confidence) +### MCP Server (High confidence) **Kind change:** None. `kind: API` stays `kind: API`. @@ -108,7 +114,7 @@ what changes beyond the kind and `spec.type`. | Field | Current | Target | Action | | -------------------- | ------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `spec.type` | `mcp-server` | `mcp-server` | No change. | -| `spec.definition` | Free-form API definition string | `spec.remotes` (structured MCP server remotes) | Migrate `spec.definition` content to structured `spec.remotes` per `McpServerApiEntity` schema. | +| `spec.definition` | Free-form API definition string | `spec.remotes` (`{ type, url }[]`) | Migrate `spec.definition` content to structured `spec.remotes` per `McpServerApiEntity` schema. | | catalog-model module | Not opted in | `@backstage/plugin-catalog-backend-module-ai-model` | Opt in to the upstream AI catalog-model module for entity validation. | **Additional considerations:** @@ -119,21 +125,23 @@ what changes beyond the kind and `spec.type`. - The `rhdh.io/ai-asset-category: mcp-server` annotation remains for backward compatibility during transition. -### 4.2 Model Server (Medium/Low confidence) +### Model Server (Medium/Low confidence) **Kind change:** `Resource` to `API` (if [backstage#34476][bs-34476] merges). **Field transformations (conditional on PR merge):** -| Field | Current | Target | Action | -| ----------------- | ----------------- | --------------------------- | ------------------------------------------------------------- | -| `kind` | `Resource` | `API` | Kind change from Resource to API. | -| `spec.type` | `ai-model-server` | `ai-model-server` | No change to type value. | -| `spec.owner` | Standard | Standard | No change (both kinds use `spec.owner`). | -| `spec.serverType` | Not present | Required (`serverType`) | Add `spec.serverType` per upstream schema. | -| `spec.serverUrl` | Not present | Required (`spec.serverUrl`) | Add `spec.serverUrl` per upstream schema. | -| `spec.models` | Not present | Optional (`spec.models`) | Add discoverable/available/default model lists if applicable. | +| Field | Current | Target | Action | +| --------------------- | ----------------- | -------------------------------- | ------------------------------------------------------------- | +| `kind` | `Resource` | `API` | Kind change from Resource to API. | +| `spec.type` | `ai-model-server` | `ai-model-server` | No change to type value. | +| `spec.owner` | Standard | Standard | No change (both kinds use `spec.owner`). | +| `spec.serverType` | Not present | Required (`spec.serverType`) | Add `spec.serverType` per upstream schema. | +| `spec.serverUrl` | Not present | Required (`spec.serverUrl`) | Add `spec.serverUrl` per upstream schema. | +| `spec.models` | Not present | Optional (`spec.models`) | Add discoverable/available/default model lists if applicable. | +| `spec.requiresApiKey` | Not present | Optional (`spec.requiresApiKey`) | Add when the server requires an API key. | +| `spec.apiEntityRef` | Not present | Optional (`spec.apiEntityRef`) | Add entity ref to a related API credential/entity if used. | **Hedge:** This mapping is conditional on [backstage#34476][bs-34476] merging. If the PR is declined or the @@ -141,7 +149,7 @@ schema changes, the transformation rules will need to be updated. Downstream implementation: [#4211](https://github.com/redhat-developer/rhdh-plugins/pull/4211). -### 4.3 AI Model (Low confidence) +### AI Model (Low confidence) **Kind change:** Unknown — no solid upstream kind proposed. @@ -152,31 +160,33 @@ Downstream implementation: kind is proposed, revisit this section with concrete field-level transformation rules. -### 4.4 Skill (Medium-High confidence) +### Skill (Medium-High confidence) **Kind change:** `AIResource` to `AiResource` (casing alignment). **Field transformations:** -| Field | Current | Target | Action | -| --------------- | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `kind` | `AIResource` | `AiResource` | Casing change. Backstage lowercases kind in entity refs, so `airesource:default/my-skill` stays the same. | -| `spec.type` | `skill` | `skill` | No change. | -| `spec.*` fields | RHDH-defined fields | Upstream `AiResource` schema fields | Align field names and types per upstream `AiResource` schema ([#33575][bs-33575] lineage). | +| Field | Current | Target | Action | +| --------------- | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `kind` | `AIResource` | `AiResource` | Casing change. Backstage lowercases kind in entity refs, so `airesource:default/my-skill` stays the same. | +| `spec.type` | `skill` | `skill` | No change. | +| `spec.*` fields | RHDH-defined fields | Upstream `AiResource` schema fields | Align field names and types per upstream `AiResource` schema ([#33575][bs-33575] lineage; see also [Backstage 1.51][bs-1-51] / [#34876][bs-34876]). | **Note:** The `AIResource` to `AiResource` casing change does not affect entity ref strings because Backstage lowercases the kind prefix -(`airesource:default/...` in both cases). +(`airesource:default/...` in both cases). In-tree Boost fixtures and +tests already use `kind: AiResource`; see the footnote under +Current-State Source of Truth. -### 4.5 Rule (Medium-High confidence) +### Rule (Medium-High confidence) **Kind change:** `AIResource` to `AiResource` (casing alignment). -**Field transformations:** Same as Skill (section 4.4). Rules use the +**Field transformations:** Same as Skill. Rules use the same `AiResource` upstream kind with `spec.type: rule` to distinguish them from skills. -### 4.6 Skill Bundle (Low confidence) +### Skill Bundle (Low confidence) **Kind change:** Unknown — no upstream kind proposed. @@ -186,7 +196,7 @@ them from skills. **Recommendation:** Stay on current mapping. Track future upstream RFCs that may define a bundle or collection kind. -### 4.7 Agent (Low confidence) +### Agent (Low confidence) **Kind change:** Unknown — no upstream kind via RFC [#32062][bs-32062] (that RFC is MCP-only, not agent). @@ -206,12 +216,12 @@ that may define a bundle or collection kind. **Recommendation:** Do not attribute agent kind to RFC #32062. Track agent-kind ownership under RHDHPLAN-1113 and RHIDP-15865. -## 5. Consumer-Facing Changes +## Consumer-Facing Changes Migration to upstream entity kinds will affect three consumer-facing areas: catalog UI filters, entity references, and API queries. -### 5.1 Catalog UI Filters +### Catalog UI Filters | Category | Current filter | Post-migration filter | Impact | | ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------- | @@ -223,7 +233,7 @@ areas: catalog UI filters, entity references, and API queries. | Skill Bundle | `kind: AIResource` + `rhdh.io/ai-asset-category: skill-bundle` | No change (no upstream kind yet). | **None** until upstream kind proposed. | | Agent | `kind: Component` + `rhdh.io/ai-asset-category: agent` | No change (no upstream kind yet). | **None** until upstream kind proposed. | -### 5.2 Entity References +### Entity References | Category | Current entity ref | Post-migration entity ref | Impact | | ------------ | ------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -235,7 +245,7 @@ areas: catalog UI filters, entity references, and API queries. | Skill Bundle | `airesource:default/my-bundle` | No change. | **No change.** | | Agent | `component:default/my-agent` | No change. | **No change.** | -### 5.3 API Queries +### API Queries | Category | Current query | Post-migration query | Impact | | ------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------- | @@ -247,7 +257,7 @@ areas: catalog UI filters, entity references, and API queries. | Skill Bundle | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill-bundle` | No change. | **None.** | | Agent | `?filter=kind=Component,rhdh.io/ai-asset-category=agent` | No change. | **None.** | -## 6. Backward Compatibility +## Backward Compatibility ### Strategy @@ -280,7 +290,7 @@ period. | Skill Bundle | **No change** | No upstream kind yet. | | Agent | **No change** | No upstream kind yet. | -## 7. Out of Scope +## Out of Scope The following items are explicitly **not** covered by this design document: @@ -300,7 +310,7 @@ document: - **Entity kind transition plan** — Detailed rollout plan for production migration is future work. -## 8. Sign-Off +## Sign-Off > This section is a placeholder for reviewer sign-off per > [#4042](https://github.com/redhat-developer/rhdh-plugins/issues/4042) @@ -332,6 +342,10 @@ document: — Mapping table reconciliation PR - [#4042 gate comment][gate-comment] — Pre-implementation gate decisions +- [Backstage 1.51 release notes][bs-1-51] — shipped `AiResource` kind + in catalog-model +- [#34876][bs-34876] — follow-on `AiResource` spec extension proposal +- [#33575][bs-33575] — AIContext RFC (related AI catalog kind lineage) [decision-1]: ../openspec/changes/ai-catalog-entity-model/design.md [usa-proposal]: ../openspec/changes/upstream-schema-alignment/proposal.md @@ -345,5 +359,7 @@ document: [bs-34476]: https://github.com/backstage/backstage/pull/34476 [bs-33575]: https://github.com/backstage/backstage/issues/33575 [bs-32062]: https://github.com/backstage/backstage/issues/32062 +[bs-34876]: https://github.com/backstage/backstage/issues/34876 +[bs-1-51]: https://github.com/backstage/backstage/blob/master/docs/releases/v1.51.0-changelog.md [rhdh-4211]: https://github.com/redhat-developer/rhdh-plugins/pull/4211 [rhdh-4164]: https://github.com/redhat-developer/rhdh-plugins/pull/4164 From cd1043cda27e3548b4342f33abc69ffb57921a8a Mon Sep 17 00:00:00 2001 From: Marek Libra Date: Mon, 10 Aug 2026 13:54:48 +0200 Subject: [PATCH 4/4] docs(#4223): tighten migration design field rules and API filters Use catalog annotation filter paths, spell out Skill/Rule and spec.models transformations, and dedupe Out of scope. --- .../ai-asset-upstream-migration-design.md | 107 +++++++++--------- 1 file changed, 56 insertions(+), 51 deletions(-) diff --git a/workspaces/boost/specifications/ai-asset-upstream-migration-design.md b/workspaces/boost/specifications/ai-asset-upstream-migration-design.md index 37a16fba3df..93008b25b50 100644 --- a/workspaces/boost/specifications/ai-asset-upstream-migration-design.md +++ b/workspaces/boost/specifications/ai-asset-upstream-migration-design.md @@ -41,8 +41,11 @@ without breaking existing catalog consumers. (RHIDP-15347). - Annotation specification document (RHIDP-15346) — covered by [#4220](https://github.com/redhat-developer/rhdh-plugins/issues/4220). -- Executing the actual catalog migration or implementing a catalog - processor. +- Live catalog migration (re-mapping entities to finalized upstream + kinds) and any catalog processor for automated migration — future + work after RFC finalization and sign-off. +- Detailed production entity-kind transition / rollout plan — future + work. - Re-writing mapping tables already reconciled in [#4189](https://github.com/redhat-developer/rhdh-plugins/pull/4189). @@ -132,16 +135,16 @@ what changes beyond the kind and `spec.type`. **Field transformations (conditional on PR merge):** -| Field | Current | Target | Action | -| --------------------- | ----------------- | -------------------------------- | ------------------------------------------------------------- | -| `kind` | `Resource` | `API` | Kind change from Resource to API. | -| `spec.type` | `ai-model-server` | `ai-model-server` | No change to type value. | -| `spec.owner` | Standard | Standard | No change (both kinds use `spec.owner`). | -| `spec.serverType` | Not present | Required (`spec.serverType`) | Add `spec.serverType` per upstream schema. | -| `spec.serverUrl` | Not present | Required (`spec.serverUrl`) | Add `spec.serverUrl` per upstream schema. | -| `spec.models` | Not present | Optional (`spec.models`) | Add discoverable/available/default model lists if applicable. | -| `spec.requiresApiKey` | Not present | Optional (`spec.requiresApiKey`) | Add when the server requires an API key. | -| `spec.apiEntityRef` | Not present | Optional (`spec.apiEntityRef`) | Add entity ref to a related API credential/entity if used. | +| Field | Current | Target | Action | +| --------------------- | ----------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------- | +| `kind` | `Resource` | `API` | Kind change from Resource to API. | +| `spec.type` | `ai-model-server` | `ai-model-server` | No change to type value. | +| `spec.owner` | Standard | Standard | No change (both kinds use `spec.owner`). | +| `spec.serverType` | Not present | Required (`spec.serverType`) | Add `spec.serverType` per upstream schema. | +| `spec.serverUrl` | Not present | Required (`spec.serverUrl`) | Add `spec.serverUrl` per upstream schema. | +| `spec.models` | Not present | Optional `{ discoverable?: boolean, available?: string[], default?: string }` | Add model discovery metadata when applicable. | +| `spec.requiresApiKey` | Not present | Optional (`spec.requiresApiKey`) | Add when the server requires an API key. | +| `spec.apiEntityRef` | Not present | Optional (`spec.apiEntityRef`) | Add entity ref to a related API credential/entity if used. | **Hedge:** This mapping is conditional on [backstage#34476][bs-34476] merging. If the PR is declined or the @@ -164,13 +167,21 @@ transformation rules. **Kind change:** `AIResource` to `AiResource` (casing alignment). -**Field transformations:** - -| Field | Current | Target | Action | -| --------------- | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `kind` | `AIResource` | `AiResource` | Casing change. Backstage lowercases kind in entity refs, so `airesource:default/my-skill` stays the same. | -| `spec.type` | `skill` | `skill` | No change. | -| `spec.*` fields | RHDH-defined fields | Upstream `AiResource` schema fields | Align field names and types per upstream `AiResource` schema ([#33575][bs-33575] lineage; see also [Backstage 1.51][bs-1-51] / [#34876][bs-34876]). | +**Field transformations** (upstream `AiResource` skill subtype; see +[Backstage 1.51][bs-1-51] / [#33575][bs-33575] lineage): + +| Field | Current | Target | Action | +| ------------------------------- | --------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `kind` | `AIResource` | `AiResource` | Casing change. Backstage lowercases kind in entity refs, so `airesource:default/my-skill` stays the same. | +| `spec.type` | `skill` | `skill` | No change. | +| `spec.lifecycle` / `spec.owner` | Required base fields | Required base fields | No change. | +| `spec.system` | Optional | Optional | No change when present. | +| `spec.disciplines` | Optional string array (RHDH / local fixtures) | Optional `string[]` | Keep; aligns with upstream skill schema. | +| `spec.categories` | Optional string array | Optional `string[]` | Keep; aligns with upstream skill schema. | +| `spec.agents` | Optional refs / identifiers | Optional `string[]` | Keep as catalog-friendly agent identifiers per upstream schema. | +| `spec.dependsOn` | Often absent | Optional entity-ref `string[]` | Add when the skill depends on other `AiResource` entities (`defaultKind: AiResource`). | +| `spec.location` (RHDH-local) | Sometimes present (`type` + `target`) | Not part of upstream skill schema | Remove from `spec`; point content via `metadata.annotations['backstage.io/source-location']` instead. | +| Skill **content** | Embedded or custom location fields | Not stored in entity `spec` | Providers must set `backstage.io/source-location` to the `SKILL.md` (or equivalent) source file. | **Note:** The `AIResource` to `AiResource` casing change does not affect entity ref strings because Backstage lowercases the kind prefix @@ -182,9 +193,19 @@ Current-State Source of Truth. **Kind change:** `AIResource` to `AiResource` (casing alignment). -**Field transformations:** Same as Skill. Rules use the -same `AiResource` upstream kind with `spec.type: rule` to distinguish -them from skills. +**Field transformations** (upstream `AiResource` rule subtype): + +| Field | Current | Target | Action | +| ------------------------------- | ------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `kind` | `AIResource` | `AiResource` | Casing change (same entity-ref behavior as Skill). | +| `spec.type` | `rule` | `rule` | No change — distinguishes rules from skills on the same kind. | +| `spec.lifecycle` / `spec.owner` | Required base fields | Required base fields | No change. | +| `spec.system` | Optional | Optional | No change when present. | +| `spec.disciplines` | Optional string array | Optional `string[]` | Keep when used; supported on upstream rule subtype. | +| `spec.category` | Present in RHDH fixtures | **Required** string | Ensure every rule entity sets `spec.category` (upstream required). | +| `spec.rationale` | Present in RHDH fixtures | **Required** string | Ensure every rule entity sets `spec.rationale` (upstream required). | +| `spec.location` (RHDH-local) | Sometimes present (`type` + `target`) | Not part of upstream rule schema | Remove from `spec`; use `metadata.annotations['backstage.io/source-location']` for the rule source file. | +| Rule **content** | Embedded or custom location fields | Not stored in entity `spec` | Same as Skill — content lives at `backstage.io/source-location`, not in `spec`. | ### Skill Bundle (Low confidence) @@ -247,15 +268,19 @@ areas: catalog UI filters, entity references, and API queries. ### API Queries -| Category | Current query | Post-migration query | Impact | -| ------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------- | -| MCP Server | `?filter=kind=API,spec.type=mcp-server` | No change. | **None.** | -| Model Server | `?filter=kind=Resource,rhdh.io/ai-asset-category=model-server` | `?filter=kind=API,spec.type=ai-model-server` (if [#34476][bs-34476] merges). | **Breaking** — both kind and filter field change. | -| AI Model | `?filter=kind=Resource,rhdh.io/ai-asset-category=ai-model` | No change. | **None.** | -| Skill | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill` | `?filter=kind=AiResource,rhdh.io/ai-asset-category=skill` | **Minimal** — casing change in kind filter value. | -| Rule | `?filter=kind=AIResource,rhdh.io/ai-asset-category=rule` | `?filter=kind=AiResource,rhdh.io/ai-asset-category=rule` | **Minimal** — same as Skill. | -| Skill Bundle | `?filter=kind=AIResource,rhdh.io/ai-asset-category=skill-bundle` | No change. | **None.** | -| Agent | `?filter=kind=Component,rhdh.io/ai-asset-category=agent` | No change. | **None.** | +Catalog annotation filters use the +`metadata.annotations.=` path form (see +[Backstage catalog API filtering](https://backstage.io/docs/features/software-catalog/software-catalog-api#filtering)). + +| Category | Current query | Post-migration query | Impact | +| ------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------- | +| MCP Server | `?filter=kind=API,spec.type=mcp-server` | No change. | **None.** | +| Model Server | `?filter=kind=Resource,metadata.annotations.rhdh.io/ai-asset-category=model-server` | `?filter=kind=API,spec.type=ai-model-server` (if [#34476][bs-34476] merges). | **Breaking** — both kind and filter field change. | +| AI Model | `?filter=kind=Resource,metadata.annotations.rhdh.io/ai-asset-category=ai-model` | No change. | **None.** | +| Skill | `?filter=kind=AIResource,metadata.annotations.rhdh.io/ai-asset-category=skill` | `?filter=kind=AiResource,metadata.annotations.rhdh.io/ai-asset-category=skill` | **Minimal** — casing change in kind filter value. | +| Rule | `?filter=kind=AIResource,metadata.annotations.rhdh.io/ai-asset-category=rule` | `?filter=kind=AiResource,metadata.annotations.rhdh.io/ai-asset-category=rule` | **Minimal** — same as Skill. | +| Skill Bundle | `?filter=kind=AIResource,metadata.annotations.rhdh.io/ai-asset-category=skill-bundle` | No change. | **None.** | +| Agent | `?filter=kind=Component,metadata.annotations.rhdh.io/ai-asset-category=agent` | No change. | **None.** | ## Backward Compatibility @@ -290,26 +315,6 @@ period. | Skill Bundle | **No change** | No upstream kind yet. | | Agent | **No change** | No upstream kind yet. | -## Out of Scope - -The following items are explicitly **not** covered by this design -document: - -- **`vector-store` / `ai-tool` categories** — These are Augment - leftovers not yet confirmed as AI-asset mapping rows. See - [catalog-entities spec][catalog-entities-spec] for tracking. -- **Dry-run migration-readiness CLI** (RHIDP-15347) — Covered by - [#4220](https://github.com/redhat-developer/rhdh-plugins/issues/4220). -- **Annotation specification document** (RHIDP-15346) — Covered by - [#4220](https://github.com/redhat-developer/rhdh-plugins/issues/4220). -- **Live catalog migration** — Executing the actual entity migration - (re-mapping entities to finalized upstream kinds) is future work - dependent on RFC finalization. -- **Catalog processor for automated migration** — Future work once - upstream targets are stable and migration is approved. -- **Entity kind transition plan** — Detailed rollout plan for - production migration is future work. - ## Sign-Off > This section is a placeholder for reviewer sign-off per