Link an explanation to the exact API contract
A guide can point to a resource, operation, request or response without hard-coding a generated URL. Publication resolves the semantic target against the reference the application actually emits.
Example — Go from an explanation to its operation
A guide introduces creating a record, then takes the reader directly to that action’s contract. The guide remains about the task while the reference carries the exact payload.
For engineers
This illustrative resource target uses the public target contract from @wildo-ai/saas-specifications/technical-documentation:
const target = {
section: TechnicalDocumentationApiReferenceSection.API_REFERENCE,
kind: TechnicalDocumentationApiReferenceTargetKind.RESOURCE,
resourceRef: 'technical-documentation:resource/company',
} satisfies TechnicalDocumentationApiReferenceTargetV1;
The application must actually publish that resource identity. A response target instead needs the operation-variant identity and status; a category target needs its category ID. The discriminated target schema requires the fields appropriate to each kind and carries no URL.
Resolve against the emitted reference
The OpenAPI link index records the published target inventory and its public fragments. The documentation link model carries the target to the renderer, which resolves it before emitting the guide. Missing, duplicate or ambiguous targets stop the relevant publication rather than silently choosing a similarly named endpoint.
Keep the explanatory link text in the guide and the contract identity in its target data. Do not derive fragments from translated labels or copy a current browser URL as a substitute for this join. Regenerate the reference before resolving guides whose targets changed.