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.
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 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. 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.