What Is a Software Catalog and What Should It Contain?

Updated

A software catalog is a centralized, structured inventory of the software your organization builds and runs — services, components, APIs, websites, and the teams that own them — described with consistent metadata and kept current through declarative configuration files and automated discovery. It is worth building when people regularly struggle to answer "who owns this?", "what depends on it?", or "where are the docs?" across more than a handful of systems. In Backstage, the open source developer portal framework, the software catalog is the core data model that other features (templates, TechDocs, plugins) build on.

What a software catalog is used for

A catalog turns scattered tribal knowledge into a queryable inventory. The core use cases:

  • Ownership lookup — find the responsible team for any service, API, or component without asking in chat.
  • Dependency visibility — see what a service depends on and what depends on it, so change impact is visible before a deploy.
  • Onboarding — new engineers browse the catalog to learn the system landscape instead of reading stale wikis.
  • Change impact — before modifying or retiring something, check downstream consumers.
  • Consistency — every entry carries the same fields, so tooling and dashboards can rely on them.

Essential metadata for each entry

A useful catalog entry is small but complete. The fields below mirror the entity model Backstage uses (kind, metadata, spec):

Field Purpose Example
name Unique, stable identifier payments-api
owner Team or group accountable for it team-payments
type What kind of thing it is service, website, library
lifecycle Maturity stage production, experimental, deprecated
system The larger system it belongs to checkout
dependsOn / providesApis Relationships to other entries dependsOn: [user-db]
links / docs Where to find docs, dashboards, runbooks TechDocs URL, Grafana link

Start with name, owner, type, and lifecycle. Those four answer most ownership and triage questions. Add relationships and doc links as adoption grows.

Catalog vs. developer portal vs. internal developer platform

These are related but distinct layers:

  • Software catalog — the inventory and its metadata. The data layer.
  • Developer portal — the user-facing interface (search, pages, templates, docs) that surfaces the catalog and other tools. Backstage is a developer portal framework whose software catalog is its foundation.
  • Internal developer platform (IDP) — the broader set of self-service capabilities (provisioning, CI/CD, environments) that a portal often front-ends.

In short: the catalog is the data, the portal is the interface, and the platform is the capability set. You can have a catalog without a portal (a YAML repo), but a portal without a catalog has little to organize around.

How catalogs stay current

A catalog rots if it is maintained by hand in a spreadsheet. Two mechanisms keep it accurate:

  1. Declarative config files — each team commits a small descriptor file (for example, a catalog-info.yaml) alongside its code, declaring name, owner, type, and links. The catalog ingests these, so ownership lives next to the thing owned and changes in the same pull request.
  2. Automated discovery — the catalog scans source repositories or cloud accounts to find entities and flag ones that are missing or stale, rather than waiting for teams to register manually.

The declarative approach is the stronger default: it makes the catalog a byproduct of normal development rather than a separate chore.

First steps for adoption

  1. Start small. Catalog your ten most critical services, not everything. Prove the ownership lookup works before scaling.
  2. Enforce ownership. Every entry must have a real team, not "unknown." An ownerless entry is a future outage with no one to call.
  3. Use a fixed schema. Agree on the fields and allowed values (types, lifecycle stages) up front so entries stay comparable.
  4. Put descriptors in the repos. Adopt catalog-info.yaml-style files so updates happen with code changes.
  5. Add discovery later. Once manual registration is habitual, automate detection of unregistered services.
  6. Wire in docs and links. Connect TechDocs or existing doc sites so the catalog becomes the entry point, not just a list.

A catalog pays off when it answers real questions faster than asking a colleague. If your team is small enough that everyone already knows every service and owner, defer it; once that stops being true, start with ownership and lifecycle and grow from there.