feat: add a rule to validate OAS3.2 tag parents

Author: tatomyr

.changeset/long-moons-sin.md

@@ -0,0 +1,6 @@
+---
+"@redocly/openapi-core": minor
+"@redocly/cli": minor
+---
+
+Added a `tag-parents` rule for validating the OpenAPI 3.2 specification.

__tests__/lint/oas3.2/snapshot.txt

@@ -26,7 +26,49 @@ Property `wrong` is not expected here.
 Error was generated by the struct rule.
 
 
-[3] openapi.yaml:51:7 at #/paths/~1products/query/wrong
+[3] openapi.yaml:16:13 at #/tags/0/parent
+
+Tag parent 'products' is not defined in the API description.
+
+14 | summary: Books & Literature
+15 | description: Book catalog and recommendations
+16 | parent: products
+   |         ^^^^^^^^
+17 | kind: nav
+18 | wrong: Should catch wrong fields in tags!
+
+Error was generated by the tag-parents rule.
+
+
+[4] openapi.yaml:23:13 at #/tags/1/parent
+
+Tag parent 'products' is not defined in the API description.
+
+21 | summary: Music CDs
+22 | description: Music CD catalog and reviews
+23 | parent: products
+   |         ^^^^^^^^
+24 | kind: nav
+25 |
+
+Error was generated by the tag-parents rule.
+
+
+[5] openapi.yaml:29:13 at #/tags/2/parent
+
+Tag parent 'products' is not defined in the API description.
+
+27 | summary: Gift Cards
+28 | description: Digital and physical gift cards
+29 | parent: products
+   |         ^^^^^^^^
+30 | kind: nav
+31 |
+
+Error was generated by the tag-parents rule.
+
+
+[6] openapi.yaml:51:7 at #/paths/~1products/query/wrong
 
 Property `wrong` is not expected here.
 
@@ -40,7 +82,7 @@ Property `wrong` is not expected here.
 Error was generated by the struct rule.
 
 
-[4] openapi.yaml:48:9 at #/paths/~1products/additionalOperations/test/wrong
+[7] openapi.yaml:48:9 at #/paths/~1products/additionalOperations/test/wrong
 
 Property `wrong` is not expected here.
 
@@ -54,7 +96,7 @@ Property `wrong` is not expected here.
 Error was generated by the struct rule.
 
 
-[5] openapi.yaml:156:9 at #/components/schemas/MyResponseType/discriminator/wrong
+[8] openapi.yaml:156:9 at #/components/schemas/MyResponseType/discriminator/wrong
 
 Property `wrong` is not expected here.
 
@@ -68,7 +110,7 @@ Property `wrong` is not expected here.
 Error was generated by the struct rule.
 
 
-[6] openapi.yaml:132:11 at #/components/securitySchemes/petstore_auth/flows/implicit/wrong
+[9] openapi.yaml:132:11 at #/components/securitySchemes/petstore_auth/flows/implicit/wrong
 
 Property `wrong` is not expected here.
 
@@ -82,7 +124,7 @@ Property `wrong` is not expected here.
 Error was generated by the struct rule.
 
 
-[7] openapi.yaml:144:9 at #/components/securitySchemes/device_auth/flows/deviceAuthorization
+[10] openapi.yaml:144:9 at #/components/securitySchemes/device_auth/flows/deviceAuthorization
 
 The field `scopes` must be present on this level.
 
@@ -96,7 +138,7 @@ The field `scopes` must be present on this level.
 Error was generated by the struct rule.
 
 
-[8] openapi.yaml:2:1 at #/info
+[11] openapi.yaml:2:1 at #/info
 
 Info object should contain `license` field.
 
@@ -109,7 +151,7 @@ Info object should contain `license` field.
 Warning was generated by the info-license rule.
 
 
-[9] openapi.yaml:9:10 at #/servers/0/url
+[12] openapi.yaml:9:10 at #/servers/0/url
 
 Server `url` should not point to example.com or localhost.
 
@@ -123,7 +165,7 @@ Server `url` should not point to example.com or localhost.
 Warning was generated by the no-server-example.com rule.
 
 
-[10] openapi.yaml:39:5 at #/paths/~1giftcards/get/operationId
+[13] openapi.yaml:39:5 at #/paths/~1giftcards/get/operationId
 
 Operation object should contain `operationId` field.
 
@@ -137,7 +179,7 @@ Operation object should contain `operationId` field.
 Warning was generated by the operation-operationId rule.
 
 
-[11] openapi.yaml:49:5 at #/paths/~1products/query/operationId
+[14] openapi.yaml:49:5 at #/paths/~1products/query/operationId
 
 Operation object should contain `operationId` field.
 
@@ -151,7 +193,7 @@ Operation object should contain `operationId` field.
 Warning was generated by the operation-operationId rule.
 
 
-[12] openapi.yaml:65:7 at #/paths/~1products/query/responses
+[15] openapi.yaml:65:7 at #/paths/~1products/query/responses
 
 Operation must have at least one `4XX` response.
 
@@ -165,7 +207,7 @@ Operation must have at least one `4XX` response.
 Warning was generated by the operation-4xx-response rule.
 
 
-[13] openapi.yaml:46:7 at #/paths/~1products/additionalOperations/test/operationId
+[16] openapi.yaml:46:7 at #/paths/~1products/additionalOperations/test/operationId
 
 Operation object should contain `operationId` field.
 
@@ -179,7 +221,7 @@ Operation object should contain `operationId` field.
 Warning was generated by the operation-operationId rule.
 
 
-[14] openapi.yaml:70:5 at #/paths/~1stream/get/operationId
+[17] openapi.yaml:70:5 at #/paths/~1stream/get/operationId
 
 Operation object should contain `operationId` field.
 
@@ -193,7 +235,7 @@ Operation object should contain `operationId` field.
 Warning was generated by the operation-operationId rule.
 
 
-[15] openapi.yaml:72:7 at #/paths/~1stream/get/responses
+[18] openapi.yaml:72:7 at #/paths/~1stream/get/responses
 
 Operation must have at least one `4XX` response.
 
@@ -207,7 +249,7 @@ Operation must have at least one `4XX` response.
 Warning was generated by the operation-4xx-response rule.
 
 
-[16] openapi.yaml:83:5 at #/paths/~1thing/get/operationId
+[19] openapi.yaml:83:5 at #/paths/~1thing/get/operationId
 
 Operation object should contain `operationId` field.
 
@@ -221,7 +263,7 @@ Operation object should contain `operationId` field.
 Warning was generated by the operation-operationId rule.
 
 
-[17] openapi.yaml:85:7 at #/paths/~1thing/get/responses
+[20] openapi.yaml:85:7 at #/paths/~1thing/get/responses
 
 Operation must have at least one `4XX` response.
 
@@ -235,7 +277,7 @@ Operation must have at least one `4XX` response.
 Warning was generated by the operation-4xx-response rule.
 
 
-[18] openapi.yaml:149:5 at #/components/schemas/MyResponseType
+[21] openapi.yaml:149:5 at #/components/schemas/MyResponseType
 
 Component: "MyResponseType" is never used.
 
@@ -253,6 +295,6 @@ Warning was generated by the no-unused-components rule.
 validating openapi.yaml using lint rules for api 'main'...
 openapi.yaml: validated in <test>ms
 
-❌ Validation failed with 7 errors and 11 warnings.
+❌ Validation failed with 10 errors and 11 warnings.
 run `redocly lint --generate-ignore-file` to add all problems to the ignore file.
 

__tests__/lint/tag-parents/openapi.yaml

@@ -0,0 +1,23 @@
+openapi: 3.2.0
+info:
+  title: Test API
+  version: 1.0.0
+paths: {}
+tags:
+  - name: tag
+    parent: none
+    description: A tag with an undefined parent
+
+  - name: foo
+    parent: bar
+    description: Circular references
+  - name: bar
+    parent: foo
+    description: Circular references
+  - name: baz
+    parent: foo
+    description: Circular references
+
+  - name: self
+    parent: self
+    description: Self-referencing tag

__tests__/lint/tag-parents/redocly.yaml

@@ -0,0 +1,5 @@
+apis:
+  main:
+    root: openapi.yaml
+rules:
+  tag-parents: error

__tests__/lint/tag-parents/snapshot.txt

@@ -0,0 +1,77 @@
+[1] openapi.yaml:8:13 at #/tags/0/parent
+
+Tag parent 'none' is not defined in the API description.
+
+ 6 | tags:
+ 7 |   - name: tag
+ 8 |     parent: none
+   |             ^^^^
+ 9 |     description: A tag with an undefined parent
+10 |
+
+Error was generated by the tag-parents rule.
+
+
+[2] openapi.yaml:12:13 at #/tags/1/parent
+
+Circular reference detected in tag parent hierarchy for tag 'foo'.
+
+10 |
+11 | - name: foo
+12 |   parent: bar
+   |           ^^^
+13 |   description: Circular references
+14 | - name: bar
+
+Error was generated by the tag-parents rule.
+
+
+[3] openapi.yaml:15:13 at #/tags/2/parent
+
+Circular reference detected in tag parent hierarchy for tag 'bar'.
+
+13 |   description: Circular references
+14 | - name: bar
+15 |   parent: foo
+   |           ^^^
+16 |   description: Circular references
+17 | - name: baz
+
+Error was generated by the tag-parents rule.
+
+
+[4] openapi.yaml:18:13 at #/tags/3/parent
+
+Circular reference detected in tag parent hierarchy for tag 'baz'.
+
+16 |   description: Circular references
+17 | - name: baz
+18 |   parent: foo
+   |           ^^^
+19 |   description: Circular references
+20 |
+
+Error was generated by the tag-parents rule.
+
+
+[5] openapi.yaml:22:13 at #/tags/4/parent
+
+Circular reference detected in tag parent hierarchy for tag 'self'.
+
+20 |
+21 | - name: self
+22 |   parent: self
+   |           ^^^^
+23 |   description: Self-referencing tag
+24 |
+
+Error was generated by the tag-parents rule.
+
+
+
+validating openapi.yaml using lint rules for api 'main'...
+openapi.yaml: validated in <test>ms
+
+❌ Validation failed with 5 errors.
+run `redocly lint --generate-ignore-file` to add all problems to the ignore file.
+

docs/@v2/rules/built-in-rules.md

@@ -105,6 +105,7 @@ The rules list is split into sections.
 - [operation-singular-tag](./oas/operation-singular-tag.md): Each operation may only have one tag
 - [operation-tag-defined](./oas/operation-tag-defined.md): Tags can only be used if they are defined at the top level
 - [tag-description](./oas/tag-description.md): Tags must have descriptions
+- [tag-parents](./oas/tag-parents.md): Tag parent references must be properly defined and free of circular dependencies
 - [tags-alphabetical](./oas/tags-alphabetical.md): Tags in the top-level `tags` section must appear alphabetically
 
 ## AsyncAPI rules