Troubleshoot AiResource schema validation errors

When RHDH ingests an AiResource entity, the catalog processor validates the entity against the schema. If a required field is missing or a field value is invalid, ingestion fails and the catalog reports an actionable error that identifies the field to correct.

A valid entity that contains all required fields is accepted and indexed without errors. The following table lists common validation problems and how to resolve them.

Symptom Cause Resolution

Ingestion fails with an error that names a missing field, such as spec.type or spec.owner .

A required field is missing from the catalog-info.yaml file.

Add the missing field, and then register the entity again.

Ingestion fails with an error that identifies spec.type .

The spec.type value is not one of the accepted values.

Set spec.type to skill or rule .

Ingestion fails with an error that identifies the backstage.io/source-location annotation.

The annotation is missing, or its value does not use the required url: prefix.

Set backstage.io/source-location to a source repository URL as url:_<repository_url>_ , or to an OCI image reference as url:oci:// <image_reference> .

The AiResource entity is not ingested and no AiResource kind is available.

The AiResource catalog backend plugin is not enabled.

Enable the plugin. See Install the AiResource catalog backend plugin.

Note

The exact wording of validation messages is determined by the catalog processor. Messages are human-readable and identify the specific field so that you can correct the entity without inspecting source code.