Agent Testing
FAQ
Autofix

  • GitHub GitHub Repo stars
  • Discord Discord Server
  • Recommended

    oas3-document-relationships


    Formats: Severity:

    A document can have the right structure and still point to something that does not exist.

    What is this rule checking for?

    • Link operationId values 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.