One API spec, three audiences: stop maintaining three copies

You publish public, partner and internal references from three copies of the same OpenAPI file. Someone fixes a response schema in the public copy. The partner SDK still uses the old shape, and the internal copy now has a different description of the same field.

Keep shared definitions in one base document and record the changes for each audience as transformations. The OpenAPI Overlay specification defines a format for those changes.

Keep the base contract authoritative

Maintain shared operation shapes, component schemas and authentication descriptions in the base contract. Put audience-specific changes into separately reviewed overlays: different explanations, a reduced visible operation surface, or environment-specific server descriptions where appropriate.

Record the base revision and overlay revision together. Publishing an overlay against whichever base file happens to be current makes troubleshooting unnecessarily difficult.

Overlays describe transformations; they do not create separate server implementations. If a partner API has a different wire contract, document those differences in the derived description.

Understand how targets select nodes

Overlay action targets use JSONPath, not JSON Pointer. These are different selection languages. JSONPath can select multiple matching nodes, so review the result set before applying an update or removal to a large document.

Keep transformations narrow enough to explain. A broad selector that removes every operation with a certain attribute may work initially and select new operations unexpectedly after a contract change. Validate both expected matches and important non-matches.

The specification permits a target to match nothing without making that action fail. If a removal is required for the public view, a no-match result can leave an internal operation in the output. Add your own assertions for required edits: for example, confirm that a known internal operation is absent from the public output.

Validate the derived artifacts

Run the overlay through an implementation supporting the version and features you use. Then validate the resulting OpenAPI description. A valid overlay does not automatically guarantee that every resulting document remains a usable API contract.

Check dangling references, empty path items, security declarations, server URLs and examples. Generate or inspect the downstream documentation and clients that consume the derived view. Removing an operation can affect more than its navigation entry.

Add audience-specific invariants to CI. The public view must not include an internal path prefix. The partner view must retain its required authentication scheme. Every view must preserve the response schema of operations it shares with the base, except for explicitly documented differences.

Documentation visibility is not authorization

Hiding an endpoint from a public description does not prevent a caller from sending an HTTP request to it. Enforce authorization and tenant isolation in the API itself. The overlay controls what a document says; the server controls what a caller may do.

Likewise, inspect examples and descriptions for information that should not leave an internal audience. Removing paths alone does not remove sensitive identifiers embedded in prose or shared components.

Record the build inputs

Retain the base commit, overlay commit and transformation-tool version with each generated view. Review changes to those inputs together and inspect a semantic diff of the resulting operation surface.