oas3-document-relationships
A document can have the right structure and still point to something that does not exist.
What is this rule checking for?
- Link
operationIdvalues identify an operation. - Top-level tag names are unique.
- OpenAPI 3.2 tag parents exist and have no cycles.
- Server variable defaults belong to their enum in OpenAPI 3.1 and 3.2.
Link targets can be in external OpenAPI documents already loaded through references. Findings point to the file and field where the Link is defined.
OpenAPI 3.0 recommends enum membership for server variable defaults. This rule enforces it from 3.1, where it is required.
Why did this violation appear?
A Link names a missing operation, a tag is duplicated, a parent relationship is invalid, or a server default is outside its enum.
Bad example
paths:
/pets:
get:
operationId: listPets
responses:
'200':
description: Pets
links:
next:
operationId: missingOperation
How do I fix this violation?
- Point the Link at the intended operation ID.
- Merge or rename duplicate tags.
- Use an existing tag parent and remove cycles.
- Choose a server variable default from its enum.
For the example above, use operationId: listPets if that is the intended target.
This rule runs at error severity in the recommended ruleset.