Chapter 05 of 10
Reuse Beats Inspection
Why a shared definition removes a class of violation instead of reporting it, what belongs in an organisation-wide library, and how to distribute a change without breaking twelve services.
A rule that checks ten copies of the same shape is work created by the copies. Removing them removes the rule, and the category of mistake it was there to catch.
A shared definition removes the violation, not the report
This is the difference worth internalising. A check tells you that three teams wrote incompatible error bodies, and a shared component means there was only ever one error body to write.
Nobody can be inconsistent about a shape they reference. The inconsistency requires a copy, and the copy is the thing a library takes away. That is why reuse is the cheapest governance mechanism available, and why it is usually the one an organisation reaches for last.
The effect compounds in the places consumers touch most. Every client that talks to your APIs writes error handling once instead of per service, and that is visible to them long before any style guide is.
What belongs in a library across teams
The line runs between the shapes every API has and the shapes that belong to one domain.
Four things are almost always worth sharing. The error body is the first, since every API has one and no API benefits from its own. The pagination envelope is the second, because the alternative is consumers writing the loop once per service. Authentication schemes are the third, and the small value types such as money, addresses, identifiers and timestamps are the fourth.
Domain objects are the counter-example. A shared Customer schema sounds like consistency and behaves like coupling, because two services that had no reason to move together now do. If a team has to negotiate a release with another team to add a field, the library has become a distributed monolith with a friendly name.
The components chapter of the OpenAPI guide covers where the same line sits inside a single document, and consistency across an API covers when to extract at all.
The distribution problem
Sharing a definition across twelve services creates a question that sharing inside one document never raises, which is what happens when it changes.
A library that pushes a change to every consumer at once is a deployment nobody scheduled. The first time it breaks a service, the team that owns that service starts copying definitions instead of linking them, and the library quietly stops being used.
The arrangement that survives is the opposite. Each consumer records the version it linked and moves when it chooses, so a change to the library is an offer rather than an event. The cost is that several versions coexist for a while, and that cost is small next to a library nobody is willing to depend on.
Adopting a library into APIs that already exist
Starting a library on an empty page produces definitions that match nothing you have.
The cheaper route is to promote what already works. Find the error schema in the API your team knows best, lift that one into the library, and link it back. The definition is then proven rather than theoretical, and the first consumer is already using it.
Finding the duplicates is the other half. Teams rarely copy a schema by name, they write their own version of the same idea, so a PostalAddress and an Address and a ShippingAddress describe one thing. Grouping schemas by structure rather than by name is what surfaces those, and each group is a candidate with a ready-made consumer list.
Where reuse ends
A library cannot carry the decisions that are not shapes.
It will not make anybody name a resource well, choose the right status code, or decide that an operation should not exist. It covers the parts of consistency that can be factored out, and the rest stays with the rules and the review. A library plus a check is the working pair, and neither one on its own gets you there.
In Routebase
The shared library holds organisation-wide schemas and responses, and linking one into a specification copies it in while keeping the connection.
Every shared component carries a version, and the editor shows the pending bump while you type. Specifications keep the version they linked, so a library change never rewrites a consuming specification behind somebody's back. When a newer version exists the component shows an update indicator with both version numbers, and accepting the update is a single action on that specification.
Components can go the other way as well, so a schema or response that proved itself in one specification can be promoted into the library rather than rewritten. A project-level overview groups the structurally identical schemas across every specification in the project, which is how you find the three teams that each wrote their own address type. One of them can then be promoted into the library. Linked components carry a badge showing whether they came from the organisation or the project library, and unlinking keeps the content and drops only the connection.
Linking follows ordinary specification write access, while creating and changing library components needs the governance permission. The shared library is available on every plan. The Shared Library guide covers versioning, promotion and the update flow.
Frequently asked questions
How do you keep API schemas consistent across teams?
Share the definition rather than check the copies. When every API references one error schema, no rule has to compare ten error bodies, because there is one body. Inspection scales with the number of copies while reuse removes them, which is why a shared library usually buys more consistency than the rules people write to compensate for not having one.
What should go in a shared API component library?
The shapes every API has and none of them should be inventing. That is the error body, the pagination envelope, the authentication schemes, and the small value types such as money, addresses and timestamps that appear everywhere. Domain objects belong to the team that owns them, and putting one in a shared library couples two services that had no reason to be coupled.
How do you update a shared schema without breaking consumers?
Pin each consumer to the version it linked and let it move on its own schedule. A library that pushes changes to everybody at once is a deployment nobody scheduled, and the second time it breaks a service, teams stop linking anything. Versions coexisting for a while is the price of a library people are willing to depend on.
Last reviewed by The Routebase Team.