Backstage Software Catalog Format

Backstage’s Software Catalog format is a YAML-based specification, defined by the Backstage project originally open-sourced by Spotify, for describing the software that an organization builds and runs. Each catalog-info.yaml entity file declares a component, API, resource, system, or group along with its metadata, ownership, and relationships. It is the data model that turns Backstage from an empty portal into a live map of an engineering estate.

• Entity kinds - Standard kinds like Component, API, System, Resource, and Group give every asset a consistent shape.
• Ownership and lifecycle - Fields such as owner and lifecycle record who is responsible for a service and where it is in its life.
• Relationships - Entities reference each other (dependsOn, providesApis, partOf), building a graph of how software connects.
• YAML descriptor files - Definitions live in-repo as catalog-info.yaml, so the catalog stays close to the code it documents.

In real API operations, the catalog format is where an API definition — often an OpenAPI document — gets registered as a first-class API entity with an owner, a system, and consumers attached. That makes it a working piece of API governance and discovery: teams find, document, and hold ownership over services from one portal, and the same structured, machine-readable inventory is increasingly what agents read to understand an organization’s software landscape.