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.

Bridging the Gap: Practical Application and Common Pitfalls

Let’s be honest – learning professional English, especially within a technical field like platform engineering, can feel overwhelming. You’ve mastered the concepts of Backstage and its components—you understand that a catalog-info.yaml file describes your tech docs, a scaffolder generates code for new entities, and plugins extend Backstage’s functionality. But translating this understanding into clear, concise communication in English can be tricky. Many developers, particularly those whose first language isn’t English, struggle with the nuances of phrasing that are expected when discussing technical projects, giving feedback on code, or documenting decisions.

A common pitfall is over-reliance on literal translations from your native language. For instance, a developer might instinctively say “we need to integrate this feature” when they mean “we need to build this feature into the existing platform.” While “integrate” isn’t wrong, it lacks the precision expected in Backstage discussions about extending catalogs and adding entities – terms like “extend” or “augment” are more common. Similarly, phrasing feedback as “this code is bad” can be unhelpful. Instead of delivering criticism bluntly, a constructive comment would be: “This function could benefit from clearer error handling; consider adding try...catch blocks to gracefully manage potential exceptions.” Focusing on what needs improvement and why provides more actionable guidance.

Another frequent issue is using overly complex vocabulary when simpler terms suffice. The term “entity” itself can be intimidating, but it simply refers to a distinct piece of data or functionality within your platform – a user account, a database table, or an API endpoint. Similarly, describing a change as “modifying the core infrastructure” sounds incredibly daunting; phrases like “adjusting the configuration for the authentication service” are far more approachable and easily understood by a wider audience. Remember, clarity is paramount.

Finally, pay attention to the formality of your communication. Slack messages should be conversational, but PR descriptions and code review comments require a level of precision that aligns with professional standards. A well-written PR description might start with: “This pull request introduces a new entity for managing user profiles, enhancing our platform’s ability to…”.

Here’s an example illustrating how backstage dev commands can be used in a practical scenario:

backstage dev --entity-id my-team/user-profile --scaffold create-profile-form

This command demonstrates the scaffolder’s functionality – generating a basic form for creating user profiles based on the specified entity ID. Using this command and its output effectively in a discussion requires clear communication about the generated form’s purpose, how it interacts with existing entities, and any necessary configurations.