Skip to content
Last updated

spec-no-invalid-tag-parents

Validates that tag parent references are properly defined and don't create circular dependencies.

OASCompatibility
2.0❌
3.0❌
3.1❌
3.2✅
tags:
  - name: string
    parent: string
    description: string
    externalDocs: object
tags:
  - name: products
    description: All products
  - name: books
    parent: products
    description: Books category

The default setting for this rule (in the built-in recommended configuration) is error.

API design principles

OpenAPI 3.2 introduced the ability to organize tags in a hierarchical structure using the parent field. This rule ensures that:

  1. Parent tags exist: Any tag referenced as a parent must be defined in the tags array.
  2. No circular references: Tag parent relationships must not create circular dependencies.

Proper tag hierarchy helps organize your API documentation and makes it easier for users to navigate related endpoints.

Configuration

To configure the rule, add it to the rules object in your configuration file. Set the desired severity for the rule.

rules:
  spec-no-invalid-tag-parents: error
OptionTypeDescription
severitystringPossible values: off, warn, error. Default error (in recommended configuration).

An example configuration:

rules:
  spec-no-invalid-tag-parents: error

Examples

Given this configuration:

rules:
  spec-no-invalid-tag-parents: error

Example of incorrect tags (undefined parent):

tags:
  - name: books
    parent: products

Example of incorrect tags (circular reference):

tags:
  - name: comics
    parent: books
  - name: books
    parent: comics

Example of correct tags:

tags:
  - name: products
  - name: books
    parent: products

Resources

 
Next page