feat: refine the predefined rulesets (#2366)

Author: tatomyr

.changeset/calm-olives-kiss.md

@@ -0,0 +1,7 @@
+---
+"@redocly/openapi-core": minor
+"@redocly/cli": minor
+---
+
+Added the `no-invalid-schema-examples` and `no-invalid-parameter-examples` to the `recommended` ruleset.
+Added the `no-duplicated-tag-names` to the `spec` ruleset.

CONTRIBUTING.md

@@ -175,10 +175,17 @@ It only checks links within the local docs (it can't check links to other docs s
 ## Built-in rules changes
 
 After adding a new rule, make sure it is added to the `minimal`, `recommended`, `recommended-strict` (the same as the previous but with warnings turned into error), `spec`, and `all` rulesets with appropriate severity levels.
-The defaults are `off` for `minimal` and `recommended` and `error` for `all`.
+The defaults are `off` or `warn` for `minimal` and `recommended` and `error` for `all`.
 Also add the rule to the built-in rules list in [the config types tree](./packages/core/src/types/redocly-yaml.ts).
 
+If the rule reflects a specification requirement, prefix it with `spec-` and add it to the [spec ruleset](./packages/core/src/rules/oas3/spec-ruleset.ts).
+
 Separately, open a merge request with the corresponding documentation changes.
+To make changes to documentation:
+
+1. Create a new page for the rule in the `docs/@v2` folder.
+2. Add the link to the rule page to the [built-in rules list](docs/@v2/rules/built-in-rules.md) and the [sidebar](docs/@v2/sidebars.yaml).
+3. Update the rulesets pages and [ruleset templates](docs/@v2/rules/ruleset-templates.md).
 
 ## Arguments usage
 

__tests__/lint/oas3.1/openapi.yaml

@@ -34,7 +34,7 @@ paths:
               schema:
                 type: array
                 prefixItems:
-                  - type: 'string'
+                  - type: string
                 items: false
         400:
           description: An error response
@@ -109,10 +109,10 @@ paths:
   /unevaluated-properties:
     get:
       operationId: getUnevaluatedProperties
-      summary: Checks if unevaluetedProperties work
+      summary: Checks if unevaluatedProperties work
       responses:
         200:
-          description: 'OK'
+          description: OK
           content:
             application/json:
               schema:
@@ -177,11 +177,11 @@ components:
   pathItems: {}
   schemas:
     Problem:
-      id: 'https://tools.ietf.org/rfc/rfc7807.txt'
+      id: https://tools.ietf.org/rfc/rfc7807.txt
       $schema: 'http://json-schema.org/draft-06/schema#'
-      description: 'schema for a rfc7807'
+      description: schema for a rfc7807
       definitions: {}
-      type: 'object'
+      type: object
       properties:
         type:
           description: A URI reference [RFC3986] that identifies the problem type.

__tests__/lint/oas3.1/snapshot.txt

@@ -1,12 +1,33 @@
-[1] openapi.yaml:179:5 at #/components/schemas/Problem
+[1] openapi.yaml:180:7 at #/components/schemas/Problem/schema
+
+Example validation errored: NOT SUPPORTED: keyword "id", use "$id" for schema ID.
+
+178 | schemas:
+179 |   Problem:
+180 |     id: https://tools.ietf.org/rfc/rfc7807.txt
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+181 |     $schema: 'http://json-schema.org/draft-06/schema#'
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  … |     < 32 more lines >
+214 |   Pet:
+    |   ^
+215 |     required:
+216 |       - id
+
+referenced from openapi.yaml:180:7 at #/components/schemas/Problem 
+
+Warning was generated by the no-invalid-schema-examples rule.
+
+
+[2] openapi.yaml:179:5 at #/components/schemas/Problem
 
 Component: "Problem" is never used.
 
 177 | pathItems: {}
 178 | schemas:
 179 |   Problem:
     |   ^^^^^^^
-180 |     id: 'https://tools.ietf.org/rfc/rfc7807.txt'
+180 |     id: https://tools.ietf.org/rfc/rfc7807.txt
 181 |     $schema: 'http://json-schema.org/draft-06/schema#'
 
 Warning was generated by the no-unused-components rule.
@@ -17,5 +38,5 @@ validating openapi.yaml using lint rules for api 'main'...
 openapi.yaml: validated in <test>ms
 
 Woohoo! Your API description is valid. 🎉
-You have 1 warning.
+You have 2 warnings.
 

docs/@v2/rules/minimal.md

@@ -11,8 +11,8 @@ Errors:
 - [no-server-trailing-slash](./oas/no-server-trailing-slash.md)
 - [no-server-variables-empty-enum](./oas/no-server-variables-empty-enum.md)
 - [no-unresolved-refs](./common/no-unresolved-refs.md)
-- [struct](./common/struct.md)
 - [stepId-unique](./arazzo/stepId-unique.md)
+- [struct](./common/struct.md)
 - [workflowId-unique](./arazzo/workflowId-unique.md)
 
 Warnings:
@@ -21,27 +21,29 @@ Warnings:
 - [no-ambiguous-paths](./oas/no-ambiguous-paths.md)
 - [no-empty-servers](./oas/no-empty-servers.md)
 - [no-enum-type-mismatch](./common/no-enum-type-mismatch.md)
-- [no-required-schema-properties-undefined](./common/no-required-schema-properties-undefined.md)
-- [no-schema-type-mismatch](./common/no-schema-type-mismatch.md)
 - [no-example-value-and-externalValue](./oas/no-example-value-and-externalValue.md)
 - [no-identical-paths](./oas/no-identical-paths.md)
 - [no-invalid-media-type-examples](./oas/no-invalid-media-type-examples.md)
 - [no-path-trailing-slash](./oas/no-path-trailing-slash.md)
+- [no-required-schema-properties-undefined](./common/no-required-schema-properties-undefined.md)
+- [no-schema-type-mismatch](./common/no-schema-type-mismatch.md)
 - [no-server-example.com](./oas/no-server-example-com.md)
 - [no-undefined-server-variable](./oas/no-undefined-server-variable.md)
 - [no-unused-components](./oas/no-unused-components.md)
 - [nullable-type-sibling](./oas/nullable-type-sibling.md)
 - [operation-2xx-response](./oas/operation-2xx-response.md)
+- [operation-operationId](./oas/operation-operationId.md)
 - [operation-operationId-unique](./oas/operation-operationId-unique.md)
 - [operation-operationId-url-safe](./oas/operation-operationId-url-safe.md)
-- [operation-operationId](./oas/operation-operationId.md)
 - [operation-parameters-unique](./oas/operation-parameters-unique.md)
 - [operation-summary](./oas/operation-summary.md)
 - [path-declaration-must-exist](./oas/path-declaration-must-exist.md)
-- [path-not-include-query](./oas/path-not-include-query.md)d
+- [path-not-include-query](./oas/path-not-include-query.md)
 - [path-parameters-defined](./oas/path-parameters-defined.md)
 - [security-defined](./oas/security-defined.md)
 - [spec-components-invalid-map-name](./oas/spec-components-invalid-map-name.md)
+- [spec-no-invalid-encoding-combinations](./oas/spec-no-invalid-encoding-combinations.md)
+- [spec-no-invalid-tag-parents](./oas/spec-no-invalid-tag-parents.md)
 - [tag-description](./oas/tag-description.md)
 
 A copy-pastable version of this ruleset is available as a [ruleset template](./ruleset-templates.md).

docs/@v2/rules/recommended.md

@@ -10,10 +10,10 @@ Errors:
 
 - [no-empty-servers](./oas/no-empty-servers.md)
 - [no-enum-type-mismatch](./common/no-enum-type-mismatch.md)
-- [no-schema-type-mismatch](./common/no-schema-type-mismatch.md)
 - [no-example-value-and-externalValue](./oas/no-example-value-and-externalValue.md)
 - [no-identical-paths](./oas/no-identical-paths.md)
 - [no-path-trailing-slash](./oas/no-path-trailing-slash.md)
+- [no-schema-type-mismatch](./common/no-schema-type-mismatch.md)
 - [no-server-trailing-slash](./oas/no-server-trailing-slash.md)
 - [no-server-variables-empty-enum](./oas/no-server-variables-empty-enum.md)
 - [no-undefined-server-variable](./oas/no-undefined-server-variable.md)
@@ -23,36 +23,45 @@ Errors:
 - [operation-operationId-url-safe](./oas/operation-operationId-url-safe.md)
 - [operation-parameters-unique](./oas/operation-parameters-unique.md)
 - [operation-summary](./oas/operation-summary.md)
+- [parameters-unique](./arazzo/parameters-unique.md)
 - [path-declaration-must-exist](./oas/path-declaration-must-exist.md)
 - [path-not-include-query](./oas/path-not-include-query.md)
 - [path-parameters-defined](./oas/path-parameters-defined.md)
 - [security-defined](./oas/security-defined.md)
-- [spec-components-invalid-map-name](./oas/spec-components-invalid-map-name.md)
-- [struct](./common/struct.md)
-- [parameters-unique](./arazzo/parameters-unique.md)
-- [sourceDescription-type](./arazzo/sourceDescriptions-type.md)
 - [sourceDescription-name-unique](./arazzo/sourceDescriptions-name-unique.md)
+- [sourceDescription-type](./arazzo/sourceDescriptions-type.md)
+- [sourceDescriptions-not-empty](./arazzo/sourceDescriptions-not-empty.md)
+- [spec-components-invalid-map-name](./oas/spec-components-invalid-map-name.md)
+- [spec-example-values](./oas/spec-example-values.md)
+- [spec-no-invalid-encoding-combinations](./oas/spec-no-invalid-encoding-combinations.md)
+- [spec-no-invalid-tag-parents](./oas/spec-no-invalid-tag-parents.md)
 - [stepId-unique](./arazzo/stepId-unique.md)
+- [struct](./common/struct.md)
 - [workflow-dependsOn](./arazzo/workflow-dependsOn.md)
 - [workflowId-unique](./arazzo/workflowId-unique.md)
 
 Warnings:
 
 - [configurable rules](./configurable-rules.md)
+- [criteria-unique](./arazzo/criteria-unique.md)
 - [info-license](./oas/info-license.md)
 - [info-license-strict](./oas/info-license-strict.md)
 - [no-ambiguous-paths](./oas/no-ambiguous-paths.md)
+- [no-duplicated-tag-names](./oas/no-duplicated-tag-names.md)
 - [no-invalid-media-type-examples](./oas/no-invalid-media-type-examples.md)
+- [no-invalid-parameter-examples](./oas/no-invalid-parameter-examples.md)
+- [no-invalid-schema-examples](./oas/no-invalid-schema-examples.md)
 - [no-required-schema-properties-undefined](./common/no-required-schema-properties-undefined.md)
 - [no-server-example.com](./oas/no-server-example-com.md)
 - [no-unused-components](./oas/no-unused-components.md)
 - [operation-2xx-response](./oas/operation-2xx-response.md)
 - [operation-4xx-response](./oas/operation-4xx-response.md)
 - [operation-operationId](./oas/operation-operationId.md)
-- [tag-description](./oas/tag-description.md)
 - [requestBody-replacements-unique](./arazzo/requestBody-replacements-unique.md)
+- [spec-discriminator-defaultMapping](./oas/spec-discriminator-defaultMapping.md)
 - [step-onFailure-unique](./arazzo/step-onFailure-unique.md)
 - [step-onSuccess-unique](./arazzo/step-onSuccess-unique.md)
+- [tag-description](./oas/tag-description.md)
 
 ## Recommended strict ruleset