Learn Backstage - Software Catalog Basics

#Introduction

In episode 3, you successfully ran your first Backstage with yarn dev. Now it's time to dive into the most central primitive: the Software Catalog. Episode 4 covers its fundamentals — what an entity is, the eight kinds Backstage recognizes, how the catalog-info.yaml file describes an entity, and how relations between entities form.

The Software Catalog is one of the pages you'll open most often when using Backstage. It's not just a list — it's a knowledge graph that represents your entire organization's software. Every entry can be clicked to see its details, owner, dependencies, and documentation. Understanding the data model behind it is the foundation for every later episode, because the scaffolder, TechDocs, and search all work on top of the catalog.

#The Entity Concept

#What Is an Entity

In the Software Catalog, everything is represented as an entity. A service, website, API, team, even a business domain can be an entity. Each entity is described by a YAML file and read by the catalog to become an entry that can be searched, explored, and related. This entity is what answers the discoverability problem you learned about in episode 1.

#Entity Kind

Every entity has a kind — a type that determines its meaning and the fields available to it. Backstage recognizes eight core kinds:

Kind	Role
`Component`	A service, website, library, or dataset that can be run
`System`	A collection of components working as one unit
`API`	An interface exposed by a component
`Domain`	A collection of systems representing one business area
`Resource`	Supporting infrastructure such as databases or clusters
`Group`	A team or organizational unit that owns entities
`User`	An individual user
`Location`	A source where entities are read — a repo, URL, or file

Component is the kind used most often — every service in your repository is usually described as a Component. The other kinds exist to group and connect entities.

#catalog-info.yaml

The way to describe an entity is through a catalog-info.yaml file stored inside each repository. For example:

Contoh catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: Layanan pemrosesan pesanan
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  owner: team-checkout
  system: e-commerce
  providesApis:
    - order-api

This file has three main blocks: apiVersion, metadata, and spec.

#Metadata

The metadata block holds general entity information: name as the unique identity, description for an explanation, and annotations. Annotations are a space for additional metadata that plugins can read. Some annotations use the special backstage.io/* namespace — for example backstage.io/techdocs-ref, which points to the location of that entity's TechDocs documentation. Annotations like these act as a contract between an entity and the plugins that consume it.

#Spec

The spec block contains details specific to each kind. For a Component, the type field determines whether the entity is a service, website, or library; the owner field points to who is responsible; the system field groups the component into a system; and providesApis lists the APIs it provides. The contents of spec depend heavily on the kind — different kinds have different spec fields.

Note

apiVersion and kind are a required pair in every catalog-info.yaml. Together they mark that this file is a valid Backstage entity description, similar to the header in a Kubernetes configuration file.

#Relations Between Entities

Entities don't stand alone — they connect to each other through relations. The three most common ones are:

Relation	Direction	Meaning
`ownedBy`	entity points to its owner	Indicates the Group or User responsible
`partOf`	entity points to its container	Marks it as part of a System, Domain, or Group
`providesApi`	entity points to an API	Indicates the API an entity provides

These relations usually aren't written explicitly as a list — they're inferred from the contents of spec. When you write owner: team-checkout, the catalog reads it as an ownedBy relation to the Group team-checkout. When you write system: e-commerce, a partOf relation to that System forms. This way, the relationship graph of all services can be drawn automatically — and you can see who owns what just by exploring the catalog.

#Connecting Entities into a Single Graph

For relations to form, the referenced entities must also exist in the catalog. Notice the System and Group referenced by the catalog-info.yaml above:

System dan Group yang dirujuk oleh spec

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: e-commerce
spec:
  owner: group:commerce-platform
---
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: team-checkout
spec:
  type: team
  children: []

The --- separator in the example above splits two entities within one file — Backstage allows more than one entity per file. With the System e-commerce and Group team-checkout present, all relations referenced by the Component order-service can connect: partOf to the System, ownedBy to the Group, and providesApi to the registered API.

Tip

Incomplete references don't make the catalog fail entirely — the entity still enters, but its relations dangle. When you see an entity without an owner or a clear parent in the UI, the target entity most likely hasn't been registered in the catalog yet.

#Conclusion

In this episode 4, you understood the basics of the Software Catalog: the entity concept, the eight kinds Backstage recognizes, the structure of catalog-info.yaml with its metadata and spec, backstage.io/* annotations, and relations between entities such as ownedBy, partOf, and providesApi.

The key takeaways:

An entity is the basic unit of the catalog — services, teams, and APIs are all entities.
Kind determines an entity's shape — the eight core kinds cover almost every need.
catalog-info.yaml is the source of description — stored inside each repository.
Relations are inferred from spec — owner, system, and providesApi form an automatic network.

In the next episode, episode 5, we discuss how the catalog gets all those entities: catalog ingestion and processing — from static locations, URL and file locations, to entity providers, along with the processing pipeline from provider to ready-to-use entity.