Upstream Schema Alignment — Annotation Spec, Migration Design & Tooling (issue 4 of 29)

[gabemontero]

Labels: ready-to-code
Dependencies: None
RHIDP Stories: RHIDP-15346, RHIDP-15347, RHIDP-15302
Feature: RHDHPLAN-1513 — Epic RHIDP-15334 + RHDHPLAN-1507 — Epic RHIDP-15258

Document the annotation specification mapping rhdh.io/ai-asset-* annotations to upstream Backstage RFCs (#32062 McpServer, #33060 ai-model/ai-model-server), with confidence levels and transformation rules. Create the @red-hat-developer-hub/backstage-plugin-boost-migration-readiness CLI scaffold for dry-run migration assessments. Create the migration design document with mapping tables and backward compatibility strategy. This is readiness assessment — actual migration is future work.

Deferral note: This issue bundles RHDHPLAN-1507 work (RHIDP-15302 — migration design doc) with RHDHPLAN-1513 work (RHIDP-15346/15347 — annotation spec mapping and migration CLI). If RHDHPLAN-1513 is deferred from 2.1, this issue must be split: RHIDP-15302 stays (it is RHDHPLAN-1507 scope), RHIDP-15346 and RHIDP-15347 defer with RHDHPLAN-1513.

Tasks

From openspec/changes/upstream-schema-alignment/tasks.md group 1 (RHIDP-15346):

• 1.1 Document all rhdh.io/ai-asset-category values
• 1.2 Document rhdh.io/ai-asset-version annotation format and normalization rules
• 1.3 Document rhdh.io/ai-asset-source annotation format
• 1.4 Document entity kind + spec.type mapping table
• 1.5 Map each entity type to RFC #32062 (McpServer) target
• 1.6 Map each entity type to RFC #33060 (ai-model/ai-model-server) targets
• 1.7 Assign confidence levels to each mapping
• 1.8 Document fields requiring transformation per entity type
• 1.9 Add explicit "Future Work" section
• 1.10 Add header with draft status and last-updated date
• 1.11 Cross-reference agent-creation-discovery/catalog-entities spec
• 1.12 Publish spec in workspaces/boost/specifications/ directory

From openspec/changes/upstream-schema-alignment/tasks.md group 2 (RHIDP-15347):

• 2.1 Create @red-hat-developer-hub/backstage-plugin-boost-migration-readiness CLI package structure
• 2.2 Set up TypeScript configuration and build pipeline
• 2.3 Implement catalog API client for entity enumeration
• 2.4 Filter entities by rhdh.io/ai-asset-category annotation presence
• 2.5 Implement per-entity mapping logic using annotation spec rules
• 2.6 Generate per-entity report (current → target, transformations, confidence)
• 2.7 Implement JSON output formatter
• 2.8 Implement human-readable output formatter
• 2.9 Handle entities with missing annotation (exclude gracefully)
• 2.10 Handle entities with partial annotations (include with warning)
• 2.11 CLI argument parsing (--catalog-url, --output-format, --filter)
• 2.12 Add footer message: "This is a migration-readiness assessment"

From openspec/changes/upstream-schema-alignment/tasks.md groups 3–5:

• 3.1–3.10 Testing (mapping logic, confidence, transformations, mock catalog, edge cases)
• 4.1–4.8 Documentation (README, usage, output interpretation, confidence levels, future work)
• 5.1–5.5 Cross-references (RHDHPLAN-1507, RFCs, RHIDP-15302/15303)

From openspec/changes/ai-catalog-entity-model/tasks.md group 8 (RHIDP-15302):

• 8.1 Create migration design document with mapping table: current → target upstream kind
• 8.2 Document transformation rules for each AI asset category
• 8.3 Identify consumer-facing changes: catalog UI filters, entity refs, API queries
• 8.4 Document backward compatibility strategy
• 8.5 Obtain upstream Backstage maintainer or RHDH architect sign-off
• 8.6 Document sign-off in spec

Specifications

• openspec/changes/upstream-schema-alignment/specs/annotation-specification/spec.md
• openspec/changes/upstream-schema-alignment/specs/migration-readiness-tooling/spec.md
• openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 7:59 PM UTC · Completed 8:03 PM UTC
Commit: e03b281 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Category: Feature — Annotation specification, migration design, and CLI tooling for upstream schema alignment readiness.

Severity: Medium — This is readiness assessment work that enables future migration planning but does not block current functionality.

Problem

The boost workspace uses custom rhdh.io/ai-asset-* annotations, but upstream Backstage is introducing new entity kinds via RFCs. No documented mapping, migration design, or assessment tooling exists yet to prepare for eventual alignment.

Upstream RFC Status (verified 2026-07-30)

• RFC: Modeling of MCP Servers in the Catalog backstage/backstage#32062 (McpServer): Closed — available as a stable mapping target.
• RFC: Modeling/Importing of AI Models/ModelServers in the Catalog backstage/backstage#33060 (ai-model/ai-model-server): Still open — mappings to this RFC should carry appropriately hedged confidence levels reflecting its draft status.

Neither RFC blocks this work, since the issue is explicitly scoped as readiness assessment with confidence levels.

Recommended Approach

Three deliverables, following the detailed task groups in the issue body:

1. Annotation specification — Document all rhdh.io/ai-asset-* values, map each entity type to both RFC targets, assign confidence levels, and publish to workspaces/boost/specifications/.
2. @red-hat-developer-hub/backstage-plugin-boost-migration-readiness CLI — TypeScript package with catalog API client, per-entity mapping logic, JSON and human-readable output formatters, and graceful handling of missing/partial annotations.
3. Migration design document — Mapping tables, transformation rules, consumer-facing change analysis, and backward compatibility strategy.

Deferral Consideration

As noted in the issue, if RHDHPLAN-1513 is deferred from 2.1, this issue should be split: RHIDP-15302 (migration design doc) stays as RHDHPLAN-1507 scope, while RHIDP-15346 and RHIDP-15347 defer with RHDHPLAN-1513.

Proposed Test Case

Test the migration-readiness CLI against a mock catalog:
- Entities with full annotations → correct mapping, high confidence
- Entities with partial annotations → included with warnings
- Entities with no ai-asset annotations → gracefully excluded
- Both RFC targets → correct assignment and confidence levels
- Unrecognized ai-asset-category values → handled with low confidence/warning
- Validate JSON and human-readable output formats
- Verify footer: "This is a migration-readiness assessment"

This issue has a comprehensive task breakdown and is ready for implementation.

Previous run

Triage Summary

Category: Feature — Annotation specification, migration design, and CLI tooling for upstream schema alignment readiness.

Severity: Medium — This is readiness assessment work that enables future migration planning but does not block current functionality.

Problem

The boost workspace uses custom rhdh.io/ai-asset-* annotations, but upstream Backstage is introducing new entity kinds via RFCs (McpServer, ai-model/ai-model-server). No documented mapping, migration design, or assessment tooling exists yet.

Upstream RFC Status

• RFC: Modeling of MCP Servers in the Catalog backstage/backstage#32062 (McpServer): Closed/completed — available as a stable mapping target.
• RFC: Modeling/Importing of AI Models/ModelServers in the Catalog backstage/backstage#33060 (ai-model/ai-model-server): Still open — mappings to this RFC should carry appropriate confidence levels reflecting its draft status.

Recommended Approach

Three deliverables, following the detailed task groups in the issue body:

1. Annotation specification — Document all rhdh.io/ai-asset-* values, map each entity type to both RFC targets, assign confidence levels, and publish to workspaces/boost/specifications/.
2. @boost/migration-readiness CLI — TypeScript package with catalog API client, per-entity mapping logic, JSON and human-readable output formatters, and graceful handling of missing/partial annotations.
3. Migration design document — Mapping tables, transformation rules, consumer-facing change analysis, and backward compatibility strategy.

Proposed Test Case

Test the migration-readiness CLI against a mock catalog:
- Entities with full annotations → correct mapping, high confidence
- Entities with partial annotations → included with warnings
- Entities with no ai-asset annotations → gracefully excluded
- Both RFC targets → correct assignment and confidence levels
- Validate JSON and human-readable output formats
- Verify footer: "This is a migration-readiness assessment"

This issue has a comprehensive task breakdown and is ready for implementation.

[fullsend-ai-triage]

🤖 Triage · ⚠️ Cancelled · Started 7:32 PM UTC · Ended 7:33 PM UTC
Commit: 1b270c9 · View workflow run →

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 7:34 PM UTC · Completed 7:38 PM UTC
Commit: 1b270c9 · View workflow run →