# Merge Rules

SelfDocHub builds a merged document for each service from its current version. This page explains how names are prefixed so that identifiers from different services never collide.

Each service has its own merged document, so reading one endpoint never gets slower as you add services. The merged document is also what the interface, exports and the MCP server read. A service whose specification is invalid or unreadable is skipped and reported in the diagnostics, and other services are not affected.

## OpenAPI

Names are prefixed with the service slug. For example, for the slug `billing-api`:

| OpenAPI area | Rule |
|--------------|------|
| `paths` | Each path is prefixed with `/{slug}`: `/invoices` becomes `/billing-api/invoices`. |
| Operation `tags` | Prefixed with the slug converted to underscores: `invoice` becomes `billing_api_invoice`. |
| Top-level `tags` | Same rule as operation tags. |
| `components/*` | Every component name is prefixed: `Invoice` becomes `billing_api_Invoice`. |
| `$ref` | Local component references are rewritten to the new names. |
| `operationId` | IDs are prefixed with the slug. Duplicates get a numeric suffix. |

Page addresses use the path without the slug prefix, with `{param}` written as `:param`. See [Endpoint Pages](/documentation/endpoint-pages).

## OpenRPC

The merged document is shaped as OpenRPC (`methods` and `components`):

| OpenRPC area | Rule |
|--------------|------|
| Method `name` | Prefixed with `{slug}.`: `getInvoice` becomes `billing-api.getInvoice`. Methods sharing a name get an identifier with a token. |
| Method `tags` | Left as written. Navigation groups tags strictly per service, so they cannot collide. |
| `components/*` | Same prefixing as OpenAPI. |
| `$ref` | Same rewriting as OpenAPI. |

See [OpenRPC](/documentation/openrpc) for methods with the same name.

## Overlays and merging

Markdown overlays are applied to each service's operations or methods right after they are merged. See [Markdown Overlays](/documentation/markdown-overlays). The **Rebuild** action (`admin` only) rebuilds all merged documents and creates a snapshot for each.

## Snapshots

Every successful rebuild writes the merged document and a versioned snapshot per service. Snapshot retention uses `history_depth`, applied per service. Snapshots can be promoted through the API as a low-level rollback by `admin` or `editor`. This is separate from the version history that the interface uses. See [API Reference](/documentation/api-reference).

## Next steps

- [Versions and Branches](/documentation/versions-and-branches)
- [Publishing a Specification](/documentation/publishing-specifications)

---
Source: https://selfdochub.com/documentation/merge-rules
