What is the Backstage service catalog and how does it model ownership?
The software catalog is Backstage's central registry of entities: typed records describing what exists in your system and how the pieces relate. Each entity has a kind. These seven matter for ownership mapping:
| Kind | Represents | Typical ownership question |
|---|---|---|
| Component | A deployable unit: service, library, website | Who gets paged when it breaks? |
| API | An interface a Component provides or consumes | Who approves a breaking change? |
| Resource | Infrastructure a Component needs: database, bucket, queue | Who handles migrations and capacity? |
| System | A set of Components, APIs, and Resources forming one product capability | Who owns the end-to-end behavior? |
| Domain | A business area grouping Systems | Which part of the org is accountable? |
| Group | A team or org unit | Who is on it, and where does it sit? |
| User | A person | Which teams is this person a member of? |
Ownership is a relation, not a label. spec.owner is an entity reference that resolves to another catalog entity, which should be a Group. It can point at a User, but people change teams and leave, while a team persists. Because the owner is a resolvable reference, the catalog can answer graph queries such as "everything Payments owns, including through child teams." A free-text annotation cannot answer that.
Domain: commerce
└─ System: checkout ──ownedBy──> Group: checkout-team
├─ Component: order-service ──ownedBy──> Group: orders
├─ API: orders-api ──ownedBy──> Group: orders
└─ Resource: orders-db ──ownedBy──> Group: platform-data
Group: engineering
├─ parentOf ─> Group: checkout-team
│ └─ parentOf ─> Group: orders
└─ parentOf ─> Group: platform-data
The catalog only maps ownership reliably when three conditions hold. Ownership must be modeled as relationships. The metadata must live next to the code it describes. The references must be validated continuously. A one-time inventory import satisfies none of these, and the result decays into a stale directory.
SOFTWARE ENTITIES ORG ENTITIES (Groups)
+--------------------+ +----------------------+
| Domain: commerce | | Group: engineering |
+---------+----------+ +---+--------------+---+
| hasPart | parentOf | parentOf
+---------v----------+ ownedBy +---v----------+ |
| System: checkout |----------------->| checkout-team| |
+--+-----------------+ +---+----------+ |
| hasPart | parentOf |
| +-----------------+ ownedBy +---v----------+ |
+-->| Component: |------------->| orders | |
| | order-service | +--->| | |
| +-----------------+ | +--------------+ |
| +-----------------+ | |
+-->| API: orders-api |---------+ ownedBy |
| +-----------------+ +---v-----------+
| +-----------------+ ownedBy | platform-data |
+-->| Resource: |---------------------------->| |
| orders-db | +---------------+
+-----------------+
Software entities form a Domain-to-System-to-Component/API/Resource hierarchy, and each entity's spec.owner resolves to a Group in the org tree, so ownership can be traced through parent and child teams.
How does catalog-info.yaml work for a microservice?
A catalog-info.yaml file is a single entity descriptor committed at the root of the service's repository. For a microservice, apiVersion is backstage.io/v1alpha1 and kind is Component. The table shows what each field gives you in the developer portal.
| Field | What it enables |
|---|---|
metadata.name, description |
Unique identity, search, and the summary shown on the entity page |
metadata.labels |
Filtering and grouping by key/value |
metadata.annotations |
Plugin wiring, such as source location, CI, or docs |
spec.type, lifecycle |
Catalog filters, for example service + production vs. deprecated |
spec.owner |
The ownership relation, and the team page listing what a team owns |
spec.system |
Grouping of the service into a larger product boundary |
providesApis, consumesApis, dependsOn |
Dependency graph and impact analysis |
Every relational field takes an entity reference in the form [kind:][namespace/]name. If you omit the kind or namespace, the field's default applies. The namespace default is default, and for owner the kind defaults to Group. So payments-team and group:default/payments-team point to the same entity. Write the full form anyway, because it removes ambiguity once you add namespaces later.
References are not validated at ingestion. A misspelled owner is stored as written and produces a relation to an entity that doesn't exist. The page still shows the owner, but nothing links to it, and the team's ownership view leaves the service out. To catch these, run a CI check that resolves each spec.owner against the catalog API and fails when the lookup returns nothing.
Resist modeling everything up front. Start with owner, lifecycle, and system. Add API and dependency edges only when someone will actually query them, because every edge you add is another reference that can go stale.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payments-api # unique within kind + namespace
description: Authorizes and captures card payments for checkout
labels:
tier: critical # free-form key/value, used for filtering
annotations:
# Plugin wiring: GitHub-based plugins read this to find the repo
github.com/project-slug: example-org/payments-api
# TechDocs builds docs from the mkdocs.yml in this directory
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
# Start with these three fields. Use full references so they stay
# unambiguous once more namespaces exist.
owner: group:default/payments-team
system: system:default/checkout
# Add the edges below only after owner, lifecycle, and system are
# accurate across the catalog.
providesApis:
- api:default/payments-rest-api
consumesApis:
- api:default/fraud-scoring-api
dependsOn:
# dependsOn has no default kind, so the kind is required
- resource:default/payments-db
A minimal Component descriptor for a microservice that uses fully qualified entity references for owner, system, and its API and dependency edges.
Worked example: modeling an order service, a payment service, and a shared database
The example below uses seven entities. The commerce Domain is owned by group:commerce-leads. The checkout System sets spec.domain: commerce and spec.owner: group:checkout-team. Two Components, order-service and payment-service, both set spec.system: checkout, but each has a different owner: group:checkout-team and group:payments-team. That split is intentional. It records that one team is accountable for the checkout capability while another team is on the hook for the payment code inside it.
Each Component publishes an API entity: order-api and payment-api. payment-service lists payment-api under providesApis. order-service provides order-api and lists payment-api under consumesApis. The shared Postgres instance is a Resource named checkout-db with spec.type: database, owned by group:checkout-team. Both Components reference it in dependsOn as resource:checkout-db.
Why the hierarchy matters
Without Systems and Domains, a search for "checkout" returns a flat list of components and APIs. Someone then has to read every owner field and guess who actually decides things. With the hierarchy, the question "who owns checkout?" has one answer: the System's owner. The Components under it tell you who to page for a specific failure, and the Domain tells you where to escalate.
Treat declared edges as claims
dependsOn and consumesApis are only as accurate as whoever last edited the file. Engineers routinely forget transitive calls, queues, and shared caches. Before anyone uses these edges for blast-radius or impact analysis, compare them against runtime data such as tracing, service-mesh telemetry, or database connection logs.
apiVersion: backstage.io/v1alpha1
kind: Domain # escalation point above the System
metadata: {name: commerce}
spec: {owner: group:commerce-leads}
---
apiVersion: backstage.io/v1alpha1
kind: System # answers 'who owns checkout?'
metadata: {name: checkout}
spec: {owner: group:checkout-team, domain: commerce}
---
apiVersion: backstage.io/v1alpha1
kind: Component # order code is owned by the System's team
metadata: {name: order-service}
spec: {type: service, lifecycle: production, owner: group:checkout-team, system: checkout,
providesApis: [order-api], consumesApis: [payment-api],
dependsOn: [resource:checkout-db]} # declared by hand: verify against tracing
---
apiVersion: backstage.io/v1alpha1
kind: Component # same System, different owner: page payments-team for this code
metadata: {name: payment-service}
spec: {type: service, lifecycle: production, owner: group:payments-team, system: checkout,
providesApis: [payment-api],
dependsOn: [resource:checkout-db]} # shared DB: check connection logs for other users
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata: {name: order-api}
spec: {type: openapi, lifecycle: production, owner: group:checkout-team, system: checkout, definition: {$text: ./order-openapi.yaml}}
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata: {name: payment-api}
spec: {type: openapi, lifecycle: production, owner: group:payments-team, system: checkout, definition: {$text: ./payment-openapi.yaml}}
---
apiVersion: backstage.io/v1alpha1
kind: Resource # shared Postgres instance used by both Components
metadata: {name: checkout-db}
spec: {type: database, owner: group:checkout-team, system: checkout}
A catalog-info.yaml containing seven entities: a commerce Domain, a checkout System, two Components with different owning Groups, their API entities, and a shared database Resource, linked through providesApis, consumesApis and dependsOn.
How should Group and User entities be imported from your organization?
Groups and Users are the anchor for every spec.owner reference in the catalog, so they should come from the system that already knows who works where. If teams are hand-written YAML in a repository, they drift the moment someone changes teams, leaves, or a reorg renames a department. Nobody files a pull request for that. An identity provider or an HR-backed directory already tracks these changes as part of onboarding and offboarding.
Backstage supports this through entity providers, which periodically read an external source and emit Group and User entities. Modules exist for common directories such as LDAP and Microsoft Graph. A custom provider against an internal HR API is a reasonable amount of work if neither fits. Keep the provider's output read-only in the catalog, and fix errors at the source.
Hierarchy drives rollups
Each Group can declare a parent and children, and Users list the groups they belong to in memberOf. Backstage uses these relations to answer "what does this department own?" by aggregating ownership from descendant teams. This only works if the hierarchy mirrors real reporting lines. A flat import, or one that uses cost centers as teams, produces rollups that are technically correct and practically useless.
Group ownership versus accountability
Owning by Group survives individual departures, which is why it should be the default. The risk is a group like "backend-engineering" with eighty members. Every service has an owner on paper, and no one feels responsible for any of them. Assign ownership to the smallest group that actually runs the service on call. Treat any owner group above a size threshold you choose as a smell worth reviewing.
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
name: payments
spec:
type: department
profile:
displayName: Payments
parent: engineering # mirrors real reporting lines
children: [payments-oncall] # rollups aggregate ownership from here down
---
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
name: payments-oncall
spec:
type: team # smallest group that is on call for the services
parent: payments
children: []
---
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
name: jdoe
spec:
profile:
displayName: Jane Doe
email: jdoe@example.com
memberOf: [payments-oncall]
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: refund-service
spec:
type: service
lifecycle: production
owner: group:default/payments-oncall
Group and User entities as an entity provider would emit them, with parent, children and memberOf relations that let ownership of refund-service roll up from payments-oncall to payments and engineering.
How do catalog-info.yaml files get into the catalog?
There are three ways to get entities in. Manual registration uses the portal's "register existing component" flow, where someone pastes the URL of a catalog-info.yaml. It works for a pilot, but nothing tells you when a new repository never got registered. Static locations are declared in app-config.yaml under catalog.locations. Each entry has a type such as url or file, a target pointing at a YAML file, and optional rules that restrict which entity kinds that location may define. A common pattern is one location for an org-wide all.yaml that lists other files. Repository discovery uses an integration-specific provider that scans your source host for files matching a path, so new services appear without anyone filing a request.
Where the files live matters more than how they are read.
| Approach | Strength | Weakness |
|---|---|---|
| File in each service repo | Metadata changes ship in the same pull request as code | A team rename means editing spec.owner in dozens of repos |
| Central catalog repo | One pull request updates every affected entity | Descriptions drift because no one touches the file when the code changes |
Use the central repo for things you cannot easily modify, such as vendored services, legacy systems with frozen repositories, and managed databases. Keep everything else in the service repo. To make renames survivable, point spec.owner at a stable group identifier rather than a display name, so a reorganization changes one Group entity instead of every component.
How does the catalog work internally?
Knowing the pipeline behind the portal explains why a fix to a YAML file does not show up instantly and where ownership errors come from. The catalog backend processes entities in three stages.
-
Ingestion. Entity providers push raw entities into the catalog. This covers the providers that read registered and static locations, the repository discovery providers, and the org providers that emit Groups and Users. A provider owns the entities it emits. When it stops emitting one, for example because a repository was deleted, that entity can be removed or marked as orphaned, depending on the provider and configuration.
-
Processing. Each unprocessed entity goes through a chain of processors. Processors read the referenced files, validate the entity's shape against its kind's schema, and emit relations derived from the spec. For example,
spec.ownerbecomes anownedByrelation on the component and a matchingownerOfrelation on the target. Processing failures are recorded as errors on the entity. They do not crash ingestion. Processing re-runs on a refresh loop, so source changes are picked up on the next pass and not on commit. -
Stitching. The catalog combines the processed entity with all relations that point to or from it, including relations emitted by other entities. The result is the final entity, stored in the catalog database and served through the catalog API. The frontend, search, and plugins all read from that API.
This design has two practical consequences for ownership mapping. First, a relation is just a pair of references. Stitching does not check that the target entity exists, which is why a misspelled owner produces a dangling relation and not an error. Second, rollups such as "everything the payments department owns" are computed by walking stored parentOf/childOf and ownerOf relations at query time. They are only as good as the Group hierarchy the org provider emits.
How do you keep service ownership metadata accurate over time?
Even with stable identifiers, ownership metadata decays. Teams merge, Group entities get deleted, and the engineer listed as owner leaves. The YAML still parses, so nothing breaks loudly. The catalog simply starts pointing at owners who no longer exist.
Validate in CI
Run a check on every change to catalog-info.yaml that parses the file and fails the build when spec.owner or spec.lifecycle is missing or empty. The illustrative check below does exactly that. It is a cheap schema gate that stops the most common decay at the source. A stronger version also confirms the owner resolves to a Group that exists in the catalog. That catches references to teams that a reorg has already dissolved.
Require review from the owner
Configure your code host's code-owners rules so changes to catalog-info.yaml need approval from the owning team. This prevents a drive-by edit from silently reassigning a service.
Route processing errors back to owners
When ingestion fails, for example because of a bad reference or invalid YAML, the catalog records a processing error on the entity. These errors appear in the portal, but service teams rarely look there, so the failures stay invisible to them. Platform teams should collect these errors on a schedule and send each one to the owning team's normal channel or issue queue.
Review orphans after reorgs
After each reorganization, list entities flagged as orphaned (backstage.io/orphan) and entities whose owner no longer resolves. Then assign each one to a named team. Do this explicitly, rather than leaving the entity until someone needs it during an incident.
When is a Backstage service catalog worth it, and what are the alternatives?
When should it be used?
A Backstage service catalog pays off when "who owns this?" is asked often and answered slowly. That usually means dozens of services spread across many teams, plus a platform team that wants the developer portal to be the default entry point instead of one more bookmark.
The savings come from operational lookups. During an incident you can route a page to the owning team's on-call rotation without asking around. Before a deprecation or migration you can list every component that depends on the retiring API or database. Annotations take you straight to the repository, CI pipeline, and dashboards, so nobody has to search for them.
It is a good fit when these conditions hold:
- Services are split across enough repositories and teams that no single person can name every owner from memory.
- Reorganizations happen often enough that ownership has to roll up through a team hierarchy, not live in a flat list.
- You have an identity provider or HR directory that can feed Group and User entities automatically.
- Teams are willing to keep a
catalog-info.yamlin their repositories and accept a CI gate on it. - Someone will act on the catalog's output: incident routing, deprecation planning, or ownership audits.
When should it be avoided?
Skip it if you run a handful of services and everyone already knows the owners, or if no team has capacity to run the portal. Backstage is a framework you assemble. Plugins, framework upgrades, authentication, and ingestion configuration all need ongoing work, so budget for a portal owner as you would for any internal service.
It is also a poor fit in these situations:
- There is no reliable source of org data. If teams exist only informally, every
spec.ownerpoints at hand-maintained Groups that will drift, and the catalog inherits that drift. - You need only repository-level review routing. CODEOWNERS already enforces approval on pull requests. A catalog adds little if no one asks cross-repo or dependency questions.
- You expect accurate dependency graphs for free. Declared
dependsOnandconsumesApisedges are hand-maintained claims. If your main goal is runtime topology, tracing or service-mesh data answers that question directly. - Adoption cannot be enforced. A catalog where some teams register services and others don't gives incomplete answers, and incomplete ownership data can mislead during an incident worse than no data.
Illustrative estimate: Assume 40 ownership lookups per week, 15 minutes each without a catalog and 2 minutes with one. That works out to (15 − 2) × 40 = 520 minutes, or about 8.7 hours per week. If running the portal costs more engineering time than that, a lighter option is the better choice.
| Option | Strengths | Weaknesses |
|---|---|---|
| CODEOWNERS files | Lives with the code and is enforced in review | Scoped to one repo, with no dependency or runtime model |
| Spreadsheet or wiki | No setup | Drifts quickly and has no validation |
| Homegrown registry | Fits your exact model | You build and maintain all of it |
| Commercial developer portal | Less assembly and upkeep | Licensing cost and less control over the data model |
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to backstage service catalog, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.