ai-integrations: retool OCI AIResource validation onto url:oci:// source-location

[johnmcollier]

Summary

Retool OCI-backed AIResource support to use the upstream backstage.io/source-location convention (url:oci://…) instead of the RHDH spec.location field.

Upstream AiResource has no spec.location. Skill/rule content is referenced via backstage.io/source-location. Keep format-only OCI validation (zero registry/network I/O). An OCI UrlReader is not in scope.

Tracks Jira: RHIDP-15739 (Epic RHIDP-13942, Feature RHDHPLAN-1113).

OpenSpec for this change was updated in #3938.

Tasks

• Remove RHDH spec.location usage from AIResource OCI/git asset location support (schema/types, processor input, docs, examples)
• Retool OCI validation to read metadata.annotations["backstage.io/source-location"] as a Backstage location-ref
• Enforce location-ref form url:oci://… (type url, target starts with oci:// and is a well-formed OCI reference)
• Reject bare oci://… (missing url: prefix) and other malformed OCI refs with actionable errors
• Keep zero outbound HTTP/registry calls during validation
• Update unit tests for valid/invalid url:oci://… annotations, bare oci://…, whitespace/malformed targets, and non-OCI source-locations
• Update examples (examples/ai-resource-*.yaml) and plugin README registration guidance for the new model
• Keep tests non-interactive (CI=true yarn test --watchAll=false style)

Acceptance Criteria

• AIResource entities no longer require or use spec.location for asset location
• Valid backstage.io/source-location: url:oci://quay.io/org/skills:latest passes ingest validation
• Malformed OCI source-location values (including bare oci://…) are rejected with actionable errors
• Processor performs zero outbound registry/network calls
• Git/HTTPS source-location entities continue to work and are not subject to OCI format rules
• Examples, README/docs, and tests match the OpenSpec contract

Specifications

All paths below are relative to workspaces/ai-integrations/.

• openspec/changes/ai-resource-catalog-entity-kind/proposal.md
• openspec/changes/ai-resource-catalog-entity-kind/design.md (esp. D2–D5, D10; RHIDP-14557 git UrlReader verification)
• openspec/changes/ai-resource-catalog-entity-kind/tasks.md (Sections 1–2 and 6)
• openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-entity-schema/spec.md
• openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-catalog-ingestion/spec.md

Out of Scope

• OCI UrlReader / registry content fetch / layer pull
• Catalog location type oci / readLocation for discovering entities from registries
• Custom AI catalog frontend beyond standard entity-page adaptations
• Changes to spec.scope (keep as RHDH extension)
• Replacing git/HTTPS registration flows (entity YAML still comes from normal url/file/git locations)

Context

Related prior work:

• ai-integrations: implement AIResourceOciProcessor for OCI ingestion #3693 / PR feat(#3693): add AIResourceOciProcessor for OCI ingestion validation #3764 — initial AIResourceOciProcessor (spec.location model)
• ai-integrations: add AIResource spec.scope schema extension #3694 / PR feat(#3694): add AIResource spec.scope validation #3742 — spec.scope validation
• ai-integrations: add AIResource OCI target validation #3695 — OCI target validation follow-ups
• ai-integrations: add AIResource catalog ingestion integration tests #3857 — integration tests (still written against spec.location; update or supersede as needed)
• ai-integrations: add AIResource examples and registration docs #3858 / PR docs(#3858): add AIResource examples and registration docs #3859 — examples/docs (still on spec.location; update as part of this work)
• docs(ai-integrations): retool AIResource OpenSpec onto url:oci:// source-location #3938 — OpenSpec retool onto url:oci://… source-location

Prefer updating the existing catalog-backend-module-catalog-backend-module-ai-resource-extensions processor(s) and tests rather than introducing a new module.

Important location-ref detail: the annotation must be url:oci://…, not bare oci://…. Bare oci://… parses as location type oci with a non-URL target and breaks future UrlReader integration.

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 8:55 PM UTC · Completed 8:59 PM UTC
Commit: 6680291 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Category: Feature / Refactoring · Severity: Medium

Problem

AIResource OCI asset location support currently uses a custom spec.location field, diverging from the upstream Backstage convention of using backstage.io/source-location annotations. The upstream AiResource kind has no spec.location — OCI references should use url:oci://... location-refs in the standard annotation.

Prerequisites — All Clear

• OpenSpec (docs(ai-integrations): retool AIResource OpenSpec onto url:oci:// source-location #3938): Merged ✅ — the design and specification for this change are finalized
• Initial OCI processor (ai-integrations: implement AIResourceOciProcessor for OCI ingestion #3693 / PR feat(#3693): add AIResourceOciProcessor for OCI ingestion validation #3764): Merged ✅ — existing code to refactor
• spec.scope validation (ai-integrations: add AIResource spec.scope schema extension #3694 / PR feat(#3694): add AIResource spec.scope validation #3742): Merged ✅ — no conflict
• Examples/docs (ai-integrations: add AIResource examples and registration docs #3858 / PR docs(#3858): add AIResource examples and registration docs #3859): Merged ✅ — to be updated as part of this work
• Integration tests (ai-integrations: add AIResource catalog ingestion integration tests #3857): Open, but explicitly scoped as "update or supersede as needed" — not a blocker
• No open PRs addressing this issue currently exist

Recommended Approach

Update the existing catalog-backend-module-ai-resource-extensions processor(s) in workspaces/ai-integrations/ to:

1. Remove spec.location from schema, types, processor logic, docs, and examples
2. Read metadata.annotations["backstage.io/source-location"] as a Backstage location-ref
3. Enforce url:oci://... format — reject bare oci://... (parses as location type oci with non-URL target)
4. Keep zero outbound registry/network calls during validation
5. Update examples and README registration guidance

Proposed Test Cases

- Valid: `url:oci://quay.io/org/skills:latest` → passes validation
- Reject: bare `oci://quay.io/org/skills:latest` (missing url: prefix) → actionable error
- Reject: `url:oci://` or `url:oci://no-tag` → malformed OCI ref error
- Handle: whitespace-padded annotation values
- Pass-through: non-OCI source-locations (e.g., url:https://...) skip OCI rules
- Handle: entities without the annotation
- Verify: zero outbound HTTP calls during validation

Run: CI=true yarn test --watchAll=false

This issue is well-specified with clear tasks, acceptance criteria, and OpenSpec references. Ready for implementation.

---

Labels: This is a feature/enhancement in the ai-integrations workspace. Adding 'enhancement' and 'ready-to-code' since it has sufficient detail for implementation.

[johnmcollier]

/fs-code

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 9:11 PM UTC · Completed 9:27 PM UTC
Commit: 6680291 · View workflow run →