Validate catalog entities

Overview

Roadie provides an API endpoint that validates catalog entities against the entity schema before they are registered in the catalog. This is useful when your scaffolder template generates catalog entity descriptor files and you want to ensure they are valid before proceeding with further steps like committing them to a repository or registering them.

The endpoint accepts a full catalog entity as JSON and returns validation results, letting you catch schema errors early.

Actions used

http:backstage:request

You can check the available actions if you visit /create/actions.

The request body is the full catalog entity you want to validate. It supports all standard entity kinds (Component, API, Resource, System, etc.) and any custom kinds configured in your Roadie instance.

Using the endpoint in a scaffolder template

You can call the validation endpoint from a scaffolder template using the http:backstage:request action. This lets you validate an entity that the template is about to create.

Minimal example

yaml

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: create-and-validate-component
  title: Create and validate a Component
  description: Creates a new Component entity and validates it before registering
spec:
  owner: group:default/engineering
  type: service

  parameters:
    - title: Component details
      required:
        - name
        - owner
        - lifecycle
      properties:
        name:
          title: Name
          type: string
        description:
          title: Description
          type: string
        owner:
          title: Owner
          type: string
          ui:field: OwnerPicker
        lifecycle:
          title: Lifecycle
          type: string
          enum:
            - experimental
            - production
            - deprecated

  steps:
    - id: validate-entity
      name: Validate catalog entity
      action: http:backstage:request
      input:
        method: POST
        path: /catalog/validate-entity
        headers:
          content-type: 'application/json'
        body:
          apiVersion: backstage.io/v1alpha1
          kind: Component
          metadata:
            name: ${{ parameters.name }}
            description: ${{ parameters.description }}
            annotations:
              github.com/project-slug: my-org/${{ parameters.name }}
          spec:
            type: service
            lifecycle: ${{ parameters.lifecycle }}
            owner: ${{ parameters.owner }}

    - id: log-validation-result
      name: Log validation result
      action: debug:log
      input:
        message: 'Validation result: ${{ steps["validate-entity"].output.body | dump }}'

Breakdown

The key step is the http:backstage:request call to the validation endpoint:

yaml

- id: validate-entity
  name: Validate catalog entity
  action: http:backstage:request
  input:
    method: POST
    path: /api/catalog/validate-entity
    headers:
      content-type: 'application/json'
    body:
      apiVersion: backstage.io/v1alpha1
      kind: Component
      metadata:
        name: ${{ parameters.name }}
        description: ${{ parameters.description }}
      spec:
        type: service
        lifecycle: ${{ parameters.lifecycle }}
        owner: ${{ parameters.owner }}

input.method: Must be POST.
input.path: The validation endpoint path /catalog/validate-entity.
input.headers: Set the content type to application/json.
input.body: The full catalog entity to validate. You can use scaffolder parameter values with ${{ parameters.* }} to build the entity dynamically.

The endpoint always returns a 200 status code. The response body contains a valid boolean and, when validation fails, an errors array with details about the validation errors:

json

{
  "valid": false,
  "errors": [
    "<root> must have required property 'kind' - missingProperty: kind"
  ]
}

You can access the result via ${{ steps["validate-entity"].output.body }}.

Request body

The request body is a standard Backstage catalog entity. At minimum it must include:

Field	Description
`apiVersion`	The entity API version, typically `backstage.io/v1alpha1`
`kind`	The entity kind (not required in the request, but recommended)
`metadata.name`	The entity name
`spec`	The entity spec, varies by kind