Structuring the Service Catalog in Spotify's Backstage

Spotify’s Backstage is an open-source platform that aims to streamline the software development process. One of its key features is the service catalog, a central place for managing all your services. In this blog post, we’ll explore how to structure the service catalog in Backstage.

Understanding the Service Catalog

The service catalog in Backstage is a comprehensive list of all the software components, resources, and services that your team or organization uses. It provides a single source of truth about the software you own, the status of the services, and who’s responsible for them.

How to Structure the Service Catalog

Define Your Services

The first step in structuring your service catalog is to define your services. A service in Backstage can be anything from a microservice, a library, a data pipeline, or even a team. Each service should have a clear purpose and ownership.

When defining your services, consider the following


Clearly define the purpose of each service. What problem does it solve? What functionality does it provide? Understanding the purpose of a service helps teams and stakeholders determine its value and relevance within the organization. It also aids in making informed decisions about service dependencies, resource allocation, and future enhancements.

Some examples of service types:

These are just a few examples, and the specific types of services can vary depending on your organization and the nature of your software projects.


Assign ownership to each service. This helps establish accountability and ensures that someone is responsible for maintaining and improving the service.

To ease management of ownership, Backstage supports using CODEOWNERS files to define service ownership. This allows you to specify who owns a service directly in the code repository, making it easy to keep track of service ownership and changes over time.

This means that ownership is dedfined in a single place so ensures it is maintained and up-to-date.

Catalog file

The catalog file is a YAML file that defines the services in your Backstage catalog. It’s a central place where you can define your services, their metadata, and their relationships. The catalog file is used to generate the service catalog in Backstage and is stored in the projects repository.

An example catalog-info.yaml file might look like this:

kind: Component
  name: my-service
  description: My service
  owner: my-team
  type: service
  lifecycle: production
    - my-api
    - my-dependency
  system: my-system
kind: system
  name: my-system
  description: My system
  owner: my-team
kind: API
  name: my-api
  description: My API
  owner: my-team
  system: my-system

This file defines a service called my-service that provides an API called my-api and depends on a library called my-dependency. It also defines a system called my-system that the service belongs to.

The Backstage catalog system can model complex relationships between services, systems, and APIs, allowing you to define a rich and detailed service catalog that accurately reflects your software architecture. This is show in their diageam below.

Backstage catalog system


Structuring your service catalog in Backstage can help you manage your services more effectively. By defining your services, using descriptors, organizing services by teams, using labels, and keeping your catalog up-to-date, you can create a service catalog that truly serves as a single source of truth for your software.