Backstage Software Catalog: English Vocabulary for Platform Teams

Backstage, the open-source developer portal from Spotify, has become a standard tool for platform engineering teams at companies of all sizes. If you work on a platform team or consume internal developer tooling, you will encounter Backstage vocabulary in meetings, Slack threads, and pull request reviews every day. This guide explains the essential English terms and phrases so you can participate confidently in those conversations.

Key Vocabulary

Software Catalog — the central registry in Backstage that tracks every service, website, library, API, and resource in your organisation. Engineers register components in the catalog so that other teams can discover them.

“Before you start building a new service, check the software catalog — there might already be a library that does what you need.”

Entity — any item registered in the Backstage catalog. An entity has a kind (such as Component, API, or Resource), a namespace, and a name. Every entity is described in a catalog-info.yaml file committed to its repository.

“The catalog currently has 340 entities — 210 components, 80 APIs, and 50 resources.”

catalog-info.yaml — the configuration file you add to a repository to register it as an entity in the software catalog. It declares the entity’s kind, owner, lifecycle stage, and relationships to other entities.

“The pipeline failed the ownership check because the catalog-info.yaml file was missing the spec.owner field.”

TechDocs — Backstage’s built-in documentation system. Teams write Markdown docs stored alongside their code, and Backstage renders them as a searchable documentation site. Engineers often say they are “writing TechDocs” or “publishing TechDocs” for their service.

“Our runbooks live in TechDocs now — engineers no longer have to hunt through Confluence to find the on-call playbook.”

Scaffolder (Software Templates) — the Backstage feature that lets platform teams create templates for new projects. When a developer wants to create a new service, they open the scaffolder, choose a template, fill in a form, and Backstage automatically creates the repository, adds the catalog-info.yaml, and registers the new entity.

“We used the scaffolder to spin up the new payments service — it took three minutes and the repository was already configured with CI, linting, and ownership metadata.”

Plugin — a self-contained extension that adds functionality to Backstage. Plugins can be frontend (adding pages and cards to the portal), backend (adding APIs), or both. The Backstage ecosystem has hundreds of open-source plugins covering Kubernetes, cost management, security scanning, and more.

“We installed the PagerDuty plugin — now engineers can see their on-call schedule and active incidents directly in the Backstage portal without switching tabs.”

Owner — the team or individual responsible for an entity, declared in catalog-info.yaml under spec.owner. Ownership is critical for incident response and for routing questions to the right team.

“The catalog shows that the checkout-api is owned by the payments team — I’ll raise the issue with them directly.”

Lifecycle — a metadata field on a component entity that indicates its maturity stage: typically experimental, production, or deprecated. Teams use lifecycle status to decide whether they can safely take a dependency on a component.

“That library is still marked as experimental in the catalog — I would not take a hard dependency on it for a production service yet.”

Useful Phrases

Here are real sentences platform engineers and developers use when working with Backstage:

• “I’ve raised a PR to add the catalog-info.yaml — once it merges, the service will appear in the catalog automatically.”
• “The scaffolder template we created has reduced new service setup from two days to about 20 minutes.”
• “Can you check if that API is documented in TechDocs? The team should have published runbooks there.”
• “We need to sort out the ownership metadata — about 30% of our catalog entities have no owner, which makes incident response painful.”
• “I installed the Lighthouse plugin last sprint so product managers can see performance scores for all our frontend components in one place.”

Common Mistakes

Confusing “entity” and “component”. In everyday speech, engineers sometimes say “component” when they mean any kind of entity. In Backstage, Component is a specific kind — it represents a deployable piece of software (a service, a website, a library). An API entity describes an interface, and a Resource entity describes infrastructure like a database or an S3 bucket. Using the terms precisely avoids confusion when you are writing catalog-info.yaml files or discussing catalog structure.

Saying “upload” instead of “register”. Non-native speakers sometimes say “I uploaded the service to the catalog.” The correct verb is register: “I registered the service in the catalog” or “I added the service to the catalog.” The catalog discovers entities by reading catalog-info.yaml files from source control — nothing is uploaded in the traditional sense.

Mispronouncing “scaffold” and “scaffolder”. The word scaffold is pronounced SKAF-old (the first syllable rhymes with staff, and the c before the a is silent). Engineers new to English sometimes pronounce the c as a hard sound. Practice saying: “We scaffolded a new service using the Backstage scaffolder.”

Backstage vocabulary is straightforward once you understand the core concepts — the catalog is your single source of truth, entities are the items in it, TechDocs keeps documentation close to the code, and the scaffolder turns your best practices into reusable templates that every team can use from day one.