A service catalog is a searchable inventory of every service, API, and application a company runs, showing who owns each one, what it depends on, and how healthy it currently is. It exists so that anyone at the company, a new engineer, an incident responder at 2 a.m., a security team running an audit, can answer "what is this, who runs it, and what does it touch" without having to track down the one person who happens to remember, a search that often turns up nobody at all once a service has been running quietly for a few years. Most catalogs today live inside an internal developer portal, though the catalog itself is a distinct piece of data and functionality, not the whole portal. It's the piece most engineering teams reach for first when the pain of not knowing "who owns this" becomes too frequent to keep tolerating.
The reason service catalogs exist is that ownership and dependency knowledge doesn't scale past a small team without something written down. In a five-person startup, everyone knows every service by heart. In a five-hundred-engineer company running a thousand services, that knowledge is scattered across people who have since changed teams, left the company, or simply forgotten, which means the answer to a basic ownership question sometimes doesn't exist anywhere at all anymore. Without a catalog, finding an owner during an incident turns into paging people down an org chart hoping someone recognizes the name of the failing service, a process that can eat up precious minutes while the actual problem keeps getting worse.
What distinguishes a real service catalog from a spreadsheet someone tried to maintain by hand is that it's generated from actual system state rather than manually kept up to date. Modern catalogs pull ownership metadata from a file checked into each service's repository, pull dependency information from deployment configuration or service mesh data, and pull health status from live monitoring systems, stitching all of it together into one consistent view. This means the catalog reflects reality automatically as things change, instead of drifting out of date the moment nobody remembers to update the spreadsheet, which is exactly the failure mode that made most earlier attempts at service inventories fall apart within a year or two. Companies that tried a spreadsheet-based inventory before adopting a modern catalog often describe the same pattern: an initial burst of enthusiasm, a few months of reasonably accurate data, and then a slow slide into irrelevance as new services get created faster than anyone remembers to add them, until eventually the spreadsheet gets quietly abandoned altogether.
By 2026, having some form of service catalog had become close to table stakes for any engineering organization running more than a handful of services across more than a couple of teams, largely driven by the broader adoption of internal developer portals like Backstage, which ship a catalog as their core feature. Companies that once tolerated tribal knowledge as "how things work here" found that approach breaking down as team sizes and service counts grew past what any individual could track, particularly once key engineers who held that knowledge started leaving for other roles.
This page covers what data actually lives in a catalog, how that data gets kept accurate instead of stale, how a catalog differs from adjacent ideas like a CMDB or a wiki, where a catalog earns its keep and where it's overkill, and how to build one that people actually trust and use rather than quietly ignore after the first bad experience. The durable idea underneath it is that ownership and dependency information is operational infrastructure in its own right, not an afterthought. Understanding that changes how a company decides to invest in keeping it accurate, and it makes the case for automation over manual upkeep much easier to justify to the people who fund it.
At minimum, a catalog entry has a name, an owner, and a description, the bare facts that let someone unfamiliar with a service understand what it is and who to contact, without needing to read through code or ask a colleague who might not even remember the details themselves. The owner field is usually a team rather than an individual, since individuals change roles, get promoted, or leave far more often than a team's overall area of responsibility changes, which keeps the catalog from going stale every time someone gets promoted or moves teams. A catalog tied to individuals instead of teams tends to need constant manual correction, which is exactly the kind of upkeep automation is supposed to eliminate.
Dependency information is where a catalog starts earning its keep during incidents. A well-populated catalog shows which services a given service calls, which services call it in return, and how those relationships have shifted as the system has grown, so that when something breaks, the blast radius is visible immediately instead of being reconstructed by someone tracing through logs under pressure while the outage keeps running. This dependency graph is often the single most valuable piece of data in the entire catalog during an active incident, since it turns a guessing game about what else might be affected into a concrete list an on-call engineer can work through methodically.
Health and operational data rounds out a useful entry: current deployment status, links to relevant dashboards and logs, the on-call rotation currently responsible for the service, and often a rough indicator of code quality or technical debt, sometimes called a scorecard. A scorecard in particular gives engineering leadership a quick, comparable way to see which services need attention without reading through each team's individual metrics one by one. None of this replaces the actual monitoring tools, but having links and summary status inside the catalog saves the step of hunting across five different systems to piece the same picture together, especially valuable for anyone outside the owning team who needs a quick read on whether a service is currently healthy.
Some catalogs extend further into cost data, showing what a service costs to run in cloud spend, and compliance data, flagging whether a service handles regulated data or has outstanding security findings. Neither of these extensions is essential to a first version of a catalog, but both become genuinely valuable once a company has enough services that manually tracking cost or compliance status team by team turns into its own significant burden. These extensions tend to get added once the core catalog is trusted and in daily use, layered in as specific teams (finance, security) find it a convenient place to surface their own data alongside everything else rather than maintaining a separate system nobody else looks at.
The single biggest risk to a service catalog is the same risk that kills most internal documentation: it goes stale, people notice it's wrong, and they stop trusting it entirely, at which point it stops being useful even for the data that is still accurate. A catalog with a ten percent error rate on ownership data gets treated as unreliable across the board, not just wrong ten percent of the time, because nobody knows in advance which entries fall into that broken ten percent until they've already been burned by one.
The fix that has actually worked at most companies is automation rather than policy. Instead of asking teams to log into a separate tool and manually update their service's information, the catalog pulls metadata from a small file checked into the service's own repository, something like a catalog-info.yaml in the Backstage ecosystem. Because this file lives next to the code, updating it becomes a normal part of a pull request rather than a separate chore someone has to remember, which removes the exact gap that causes most manually maintained inventories to fall out of date.
Dependency data benefits from the same approach. Rather than a team manually documenting what their service calls, the catalog can pull this information from actual deployment configuration, service mesh telemetry, or API gateway logs, so the graph reflects what's really happening in production rather than what someone wrote down when the service was first built and never updated since, which matters a great deal once a service has been through several rounds of changes nobody thought to document.
Even with automation, some human input is unavoidable, particularly around ownership and descriptions. The practical answer most companies land on is making that metadata file a required part of the service scaffolding template, so it exists by default when a new service is created, and treating a missing or clearly outdated entry as something worth flagging during code review, the same way a missing test would be, rather than something that only gets caught much later when someone actually needs the information and finds it wrong.
A configuration management database, or CMDB, is an older, related idea that also tries to track assets and their relationships, but it typically originates from IT operations and infrastructure management rather than software engineering, and it's often maintained through manual processes or agent-based discovery tools rather than through metadata living alongside application code. CMDBs also tend to focus more heavily on physical and virtual infrastructure assets, servers, network devices, licenses, rather than the application-level services a software engineering team cares most about day to day. A modern service catalog borrows the same underlying goal but fits more naturally into a developer's existing workflow, since the data comes from the same repositories and pipelines engineers already touch every day rather than a separate system run by a different department.
A wiki, by contrast, is unstructured and manually written, which is exactly where it tends to break down for this purpose. A wiki page about a service is only as current as the last person who remembered to edit it, and there's no mechanism forcing that page to reflect the service's actual state, which is why so many wiki pages describing a service quietly become historical documents rather than reliable references. A service catalog entry, generated from a file in the repository and live monitoring data, has a much shorter path between the system changing and the catalog reflecting that change.
That doesn't mean a wiki has no place. Long-form documentation, architecture decisions, and runbooks often still live in a wiki or a dedicated docs tool, and a well-built catalog links out to that content rather than trying to replace it entirely. The catalog's job is the structured facts: who, what, depends on what, currently healthy or not. The wiki's job is everything that doesn't fit neatly into structured fields, the reasoning behind a decision, the tradeoffs considered, the history of why something was built a certain way.
The practical distinction worth remembering is that a catalog answers questions a script can answer by querying structured data, while a wiki answers questions that require a human explanation. Confusing the two, trying to force free-form architectural reasoning into catalog fields, or trying to track live health status inside a wiki page, is a common reason early catalog efforts fail to stick, since neither tool ends up doing its own job well when the two purposes get blurred together.
A service catalog earns its value once a company has enough services and teams that tribal knowledge genuinely fails, which for most organizations means somewhere past a few dozen services and more than a couple of independent teams. Below that scale, a shared document or a quick Slack message usually answers the ownership question fast enough that a formal catalog is more overhead than benefit, and the engineering time spent building one is often better used elsewhere.
It's particularly valuable in any organization that runs regular incident response, since the minutes spent figuring out who owns a failing service and what it depends on are minutes added directly to the outage. A catalog that reliably shortens that lookup from ten minutes of paging around to thirty seconds of searching has a very direct, measurable payoff during exactly the moments that matter most, when every additional minute of downtime carries real cost to customers and revenue.
It's also valuable for security and compliance work, where knowing which services touch regulated data, and who is responsible for them, turns an audit from a company-wide scavenger hunt into a targeted query against existing catalog data, saving weeks of coordination across teams that would otherwise have to be tracked down individually. Companies in regulated industries often find this use case alone justifies the investment in keeping catalog data accurate, since the alternative is a manual, time-consuming survey of every team before each audit cycle.
It fits less well at a company whose services and ownership structure are still changing every few weeks, since a catalog assumes there's a reasonably stable set of things to catalog. It also fits poorly if a company isn't willing to invest in the automation that keeps it accurate, since a catalog maintained purely by manual updates tends to decay into the same stale state as the wiki it was meant to replace, just with a different interface and the same underlying trust problem.
Start with the smallest useful entry, typically just name, owner, and a description, and make populating it as close to automatic as possible by requiring a metadata file in every new service's scaffolding template. Adding this requirement to the template rather than asking teams to opt in afterward means new services arrive in the catalog correctly from day one, without anyone needing to remember an extra step. Resist the urge to design an elaborate schema with dozens of fields before a single entry exists; a catalog with three accurate fields beats one with thirty fields that are half wrong, since trust in what's there matters far more than how comprehensive the schema looks on paper.
Backfill existing services deliberately rather than hoping teams will do it on their own initiative. A short, focused effort to add every current production service to the catalog, even with just the basic fields, gets you to a state where the catalog is actually comprehensive, which is what makes people start relying on it as the default place to look instead of falling back on old habits like asking around in Slack. This backfill is usually more tedious than technically difficult, and it's tempting to skip, but a catalog that's missing a third of the company's actual services rarely earns the trust needed to become anyone's default habit.
Wire in dependency and health data next, pulling from systems that already exist, deployment tooling, service mesh data, monitoring dashboards, rather than asking teams to document these relationships by hand. This is usually the step that turns a catalog from a nice-to-have directory into something people reach for during an actual incident, since it's the layer of data that pays off most visibly when things are already going wrong.
Treat catalog accuracy as an ongoing responsibility with a named owner, not a one-time data entry project. Periodically audit for services missing an entry or an entry that's clearly gone stale, and fold catalog upkeep into the same review process used for other code quality checks, so it doesn't quietly rot the moment the initial push to build it is over, the same fate that befalls almost any internal tool nobody is explicitly accountable for.
A service catalog is a searchable inventory of every service, API, and application a company runs, showing who owns each one, what it depends on, and its current health. It exists so anyone at the company can quickly answer basic questions about a service without tracking down a specific person who happens to remember, and the best ones are generated automatically rather than kept up to date by hand.
At minimum a name, owner, and description for each service. More mature catalogs add dependency relationships (what a service calls and what calls it), health and deployment status, links to dashboards and logs, on-call information, and sometimes cost or security compliance data layered in over time. Starting small and adding fields as a real need emerges tends to work better than designing an exhaustive schema up front.
The catalog is the structured inventory of services and their metadata. The portal is the broader interface that surfaces the catalog alongside golden path templates, documentation, and other developer tooling. Most catalogs today live inside a portal, but the catalog itself is a distinct dataset and feature, not the entire portal, and a company could technically build one before ever standing up a full portal around it.
Automate as much of the data population as possible, pulling ownership from a metadata file checked into each service's repository, dependencies from deployment or service mesh data, and health from live monitoring, rather than relying on people to manually update a separate tool. Manual-only catalogs almost always drift stale over time, often within months of the initial push to populate them fading.
They serve a similar underlying goal of tracking assets and relationships, but a CMDB typically comes from IT operations tradition and is often maintained through manual entry or infrastructure discovery tools. A modern service catalog usually integrates more directly into a developer's existing workflow, pulling data from code repositories and deployment systems instead of relying on a separate IT operations process most engineers rarely interact with.
There's no fixed number, but the need usually shows up once a company has enough services and teams that no single person can reliably answer ownership questions from memory, commonly somewhere past a few dozen services spread across more than a couple of independent teams, though a company growing quickly through acquisitions or rapid hiring can hit that point sooner than headcount alone would suggest.
During an outage, knowing who owns a failing service and what depends on it directly determines how fast the right people get paged and how quickly the blast radius is understood. A catalog that turns that lookup from several minutes of asking around into a quick search has a direct, measurable effect on incident resolution time, which is often one of the easiest benefits to point to when justifying the investment to leadership.
Designing an elaborate schema with many fields before getting basic data populated and accurate. A catalog with just name, owner, and description that's actually correct for every service is far more useful, and far more trusted, than one with dozens of fields that are only half filled in or already out of date, and the smaller, accurate version is also far easier to maintain as the company keeps growing.
A platform team usually owns the catalog's infrastructure and tooling, but the accuracy of each individual entry is best enforced by making it part of the service scaffolding template and normal code review, so updating the catalog entry becomes routine rather than a separate task someone has to remember to do, and periodic audits catch the rare cases that still slip through.
