# OpenAPI linter rules

Source: https://apigenie.pl/docs/linter/openapi
See also: [Linter rules](https://apigenie.pl/docs/linter.md), [Recommended ruleset](https://apigenie.pl/docs/linter/openapi/rulesets/recommended.md), [Strict ruleset](https://apigenie.pl/docs/linter/openapi/rulesets/strict.md), [All ruleset](https://apigenie.pl/docs/linter/openapi/rulesets/all.md), [JsonApi ruleset](https://apigenie.pl/docs/linter/openapi/rulesets/json-api.md), [Privacy ruleset](https://apigenie.pl/docs/linter/openapi/rulesets/privacy.md).

The linter reads OpenAPI 3.0, 3.1 and 3.2 documents.

## Rulesets

- [Recommended ruleset](/docs/linter/openapi/rulesets/recommended.md)
- [Strict ruleset](/docs/linter/openapi/rulesets/strict.md)
- [All ruleset](/docs/linter/openapi/rulesets/all.md)
- [JsonApi ruleset](/docs/linter/openapi/rulesets/json-api.md)
- [Privacy ruleset](/docs/linter/openapi/rulesets/privacy.md)

## Rules

| Rule | What it checks | Since |
| --- | --- | --- |
| [`audience-defined`](/docs/linter/openapi/rules/audience-defined.md) | This rule checks that `info` has an `x-audience` field, and that its value is one of `internal-team`, `internal-company`, `partner` and `public`. | 0.0.1 |
| [`contact-defined`](/docs/linter/openapi/rules/contact-defined.md) | This rule checks that `info.contact` is present, with a `name` and a `url` or an `email`. | 0.0.1 |
| [`id-defined`](/docs/linter/openapi/rules/id-defined.md) | This rule checks that `info` has an identifier field, `x-id` by default, whose value is a UUID or matches a pattern of your own. | 0.0.1 |
| [`info-defined`](/docs/linter/openapi/rules/info-defined.md) | This rule checks that `info` has a non-empty `summary`, `description` and `version`. | 0.0.1 |
| [`json-api/content-type`](/docs/linter/openapi/rules/json-api-content-type.md) | This rule checks that every request body and response of the document declares the `application/vnd.api+json` media type. | 0.0.1 |
| [`json-api/resource-type-unique`](/docs/linter/openapi/rules/json-api-resource-type-unique.md) | This rule checks that every resource object schema of the JSON:API responses declares its `type` as a `const` or a one-value `enum`, and that no two of them declare the same type. | 0.0.1 |
| [`json-api/schema-validation`](/docs/linter/openapi/rules/json-api-schema-validation.md) | This rule checks that the schemas of the JSON:API request bodies and responses describe JSON:API documents: a top-level object with `data`, `errors` or `meta`, and resource objects with `type` and `id`. | 0.0.1 |
| [`json-schema-validation`](/docs/linter/openapi/rules/json-schema-validation.md) | This rule validates the document against API Genie's own meta-schema of OpenAPI 3.0 or 3.1 and reports every violation the validator finds. | 0.5.0 |
| [`license-defined`](/docs/linter/openapi/rules/license-defined.md) | This rule checks that `info.license` is present, with a `name` and a `url` or an SPDX `identifier`. | 0.0.1 |
| [`no-content-response-defined`](/docs/linter/openapi/rules/no-content-response-defined.md) | This rule checks that no `204` response declares `content`. | 0.0.1 |
| [`openapi-json-schema-validation`](/docs/linter/openapi/rules/openapi-json-schema-validation.md) | This rule validates the document against the JSON Schema the OpenAPI Initiative publishes for its version: OpenAPI 3.0, 3.1 or 3.2. | 0.0.1 |
| [`operation-description-defined`](/docs/linter/openapi/rules/operation-description-defined.md) | This rule checks that every operation has a `description` of at least 10 characters. | 0.0.1 |
| [`operation-document-not-primitive`](/docs/linter/openapi/rules/operation-document-not-primitive.md) | This rule checks that every request body and response body is an object or an array, not a string, a number or a boolean. | 0.0.1 |
| [`operation-id-defined`](/docs/linter/openapi/rules/operation-id-defined.md) | This rule checks that every operation has a non-empty `operationId`: those of paths, webhooks and the path items under `components`, and those of callbacks. | 0.0.1 |
| [`operation-id-unique`](/docs/linter/openapi/rules/operation-id-unique.md) | This rule checks that no two operations share an `operationId`, callback operations included: the specification requires the ID to be unique among all operations of the API. Empty IDs are left to operation-id-defined. | 0.0.1 |
| [`operation-rate-limiting-defined`](/docs/linter/openapi/rules/operation-rate-limiting-defined.md) | This rule checks that the responses of every operation declare the rate-limiting headers: `RateLimit-Limit`, `X-RateLimit-Limit` or `X-Rate-Limit-Limit` on every 2xx and 4xx response, and `Retry-After` on the `429` and `503` responses. | 0.0.1 |
| [`operation-security-defined`](/docs/linter/openapi/rules/operation-security-defined.md) | This rule checks that every operation has security requirements, its own or the document's. | 0.0.1 |
| [`operation-success-response`](/docs/linter/openapi/rules/operation-success-response.md) | This rule checks that every operation declares at least one 2xx or 3xx response, as a status code or as the `2XX` or `3XX` range. | 0.0.1 |
| [`operation-tags-declared`](/docs/linter/openapi/rules/operation-tags-declared.md) | This rule checks that every tag an operation uses is declared in the document's `tags`. | 0.12.0 |
| [`operation-tags-defined`](/docs/linter/openapi/rules/operation-tags-defined.md) | This rule checks that every operation has at least one tag. | 0.0.1 |
| [`parameter-description-defined`](/docs/linter/openapi/rules/parameter-description-defined.md) | This rule checks that every parameter has a description of at least 10 characters that is not a placeholder. | 0.0.1 |
| [`parameter-naming`](/docs/linter/openapi/rules/parameter-naming.md) | This rule checks that parameter names follow one naming convention per location: `kebab-case` for query parameters, `Header-Case` for header parameters and `snake_case` for the others, unless configured otherwise. | 0.0.1 |
| [`parameters-unique`](/docs/linter/openapi/rules/parameters-unique.md) | This rule checks that no path item or operation declares two parameters with the same name and location. | 0.0.1 |
| [`patch-request-body-partial`](/docs/linter/openapi/rules/patch-request-body-partial.md) | This rule checks that `PATCH` request bodies do not require properties. | 0.9.0 |
| [`path-parameters-defined`](/docs/linter/openapi/rules/path-parameters-defined.md) | This rule checks that every `{placeholder}` of a path has a parameter with `in: path` and that name, on the path item or on each of its operations. | 0.0.1 |
| [`path-parameters-on-items`](/docs/linter/openapi/rules/path-parameters-on-items.md) | This rule checks that path parameters are declared on the path item, not repeated on each of its operations. | 0.0.1 |
| [`paths-max-count`](/docs/linter/openapi/rules/paths-max-count.md) | This rule checks that a document declares at most 8 paths, or the number configured. | 0.0.1 |
| [`paths-max-depth`](/docs/linter/openapi/rules/paths-max-depth.md) | This rule checks that no path has more than 4 segments, or the number configured. A segment is the text between two slashes; `/users/{userId}/posts` has three. | 0.0.1 |
| [`paths-sorted`](/docs/linter/openapi/rules/paths-sorted.md) | This rule checks that the paths of a document are in alphabetical order. | 0.0.1 |
| [`paths-unique`](/docs/linter/openapi/rules/paths-unique.md) | This rule checks that no two paths match the same requests. Paths that differ only in the names of their placeholders, `/users/{id}` and `/users/{userId}`, are the same path. | 0.0.1 |
| [`paths-well-formed`](/docs/linter/openapi/rules/paths-well-formed.md) | This rule checks that every path starts with one slash, ends without one, has no empty segment (`//`), no empty placeholder (`{}`) and no upper-case letter outside the placeholders. | 0.0.1 |
| [`privacy/no-credentials-in-url`](/docs/linter/openapi/rules/privacy-no-credentials-in-url.md) | This rule reports passwords, tokens, API keys and other credentials passed in path or query parameters, and API keys that a security scheme sends in the query string. | 0.11.0 |
| [`privacy/no-personal-data-in-url`](/docs/linter/openapi/rules/privacy-no-personal-data-in-url.md) | This rule reports personal data, such as e-mail addresses, names, dates of birth, phone numbers and national identification numbers, passed in path or query parameters. | 0.11.0 |
| [`ref-no-siblings`](/docs/linter/openapi/rules/ref-no-siblings.md) | This rule checks that, in an OpenAPI 3.0 document, no property other than an extension sits next to the `$ref` of a Reference Object. | 0.12.0 |
| [`safe-markdown`](/docs/linter/openapi/rules/safe-markdown.md) | This rule checks that no description contains a `<script>` tag or an `eval()` call. | 0.0.1 |
| [`schema-conditional-effective`](/docs/linter/openapi/rules/schema-conditional-effective.md) | This rule checks that `if`, `then` and `else` in schemas have an effect. | 0.9.0 |
| [`schema-constraints`](/docs/linter/openapi/rules/schema-constraints.md) | This rule checks that every schema bounds the size of its values: a minimum and a maximum for integers and numbers, a length, format, pattern or enum for strings, a maximum size for arrays, a maximum number of properties or `additionalProperties: false` for objects. | 0.0.1 |
| [`schema-datetime-suffix`](/docs/linter/openapi/rules/schema-datetime-suffix.md) | This rule checks that the name of every property with the `date`, `date-time` or `time` format ends with `_at`, or with the suffix configured. | 0.0.1 |
| [`schema-discriminator-defined`](/docs/linter/openapi/rules/schema-discriminator-defined.md) | This rule checks that every schema with `oneOf` has a `discriminator`. | 0.0.1 |
| [`schema-enum-naming`](/docs/linter/openapi/rules/schema-enum-naming.md) | This rule checks that the string values of `enum` and `const` follow one naming convention, `CONST_CASE` (`ACTIVE_USER`) unless configured otherwise. | 0.0.1 |
| [`schema-enum-no-duplicates`](/docs/linter/openapi/rules/schema-enum-no-duplicates.md) | This rule checks that no value appears twice in an `enum`. | 0.0.1 |
| [`schema-enum-types`](/docs/linter/openapi/rules/schema-enum-types.md) | This rule checks that the values of `enum` and `const` have the type the schema declares. | 0.0.1 |
| [`schema-example-defined`](/docs/linter/openapi/rules/schema-example-defined.md) | This rule checks that every schema that is not trivial, an object, an array or a string with a `pattern`, has an example. | 0.0.1 |
| [`schema-format-defined`](/docs/linter/openapi/rules/schema-format-defined.md) | This rule checks that every `integer` and `number` schema has a `format` that says its size: `int32`, `int64` or another integer format for integers, `float`, `double`, `decimal` or another number format for numbers. | 0.0.1 |
| [`schema-format-deprecated`](/docs/linter/openapi/rules/schema-format-deprecated.md) | This rule reports the formats which the OpenAPI format registry marks as deprecated, and names what replaces them. | 0.10.0 |
| [`schema-format-type-mismatch`](/docs/linter/openapi/rules/schema-format-type-mismatch.md) | This rule checks that the `format` of a schema fits its `type`: `date` on a string, `int64` on an integer. | 0.0.1 |
| [`schema-format-unknown`](/docs/linter/openapi/rules/schema-format-unknown.md) | This rule reports a `format` which is neither in the OpenAPI format registry nor declared in `openapi.custom_formats` of the configuration file. | 0.10.0 |
| [`schema-keyword-support`](/docs/linter/openapi/rules/schema-keyword-support.md) | This rule reports schema keywords that the tools consuming the document are unlikely to support, and suggests the rewrite where one exists. | 0.11.0 |
| [`schema-no-additional-properties`](/docs/linter/openapi/rules/schema-no-additional-properties.md) | This rule checks that every object schema has `additionalProperties: false`. | 0.0.1 |
| [`schema-no-contradictions`](/docs/linter/openapi/rules/schema-no-contradictions.md) | This rule reports schemas with contradicting constraints, which reject every value or some of the properties they describe. | 0.9.0 |
| [`schema-no-optional-nullable-properties`](/docs/linter/openapi/rules/schema-no-optional-nullable-properties.md) | This rule disallows schema properties that are both optional and nullable. | 0.0.1 |
| [`schema-oneof-no-overlap`](/docs/linter/openapi/rules/schema-oneof-no-overlap.md) | This rule reports `oneOf` branches that a single value can match. | 0.9.0 |
| [`schema-property-naming`](/docs/linter/openapi/rules/schema-property-naming.md) | This rule checks that the property names of schemas follow one naming convention, `snake_case` (`first_name`) unless configured otherwise. | 0.0.1 |
| [`schema-required-properties-defined`](/docs/linter/openapi/rules/schema-required-properties-defined.md) | This rule checks that every name listed in `required` is defined in `properties`. | 0.9.0 |
| [`server-urls`](/docs/linter/openapi/rules/server-urls.md) | This rule checks that every server URL is valid, has its scheme and host in lower case, and uses `https`, except on `localhost`. | 0.0.1 |
| [`server-urls-no-trailing-slash`](/docs/linter/openapi/rules/server-urls-no-trailing-slash.md) | This rule checks that no URL in the document's top-level `servers`, other than `/`, ends with a slash. | 0.12.0 |
| [`servers-defined`](/docs/linter/openapi/rules/servers-defined.md) | This rule checks that the document has at least one server. | 0.0.1 |
| [`spell-check`](/docs/linter/openapi/rules/spell-check.md) | This rule checks the spelling of the texts written for humans: titles, summaries and descriptions. | 0.0.1 |
| [`standard-media-types`](/docs/linter/openapi/rules/standard-media-types.md) | This rule checks that the media types of request bodies, responses, parameters and headers are ones the rule knows: a top-level type registered with IANA (`application`, `text`, `image`, `multipart`, ...) and one of about sixty common subtypes (`json`, `xml`, `problem+json`, `vnd.api+json`, `form-data`, `x-www-form-urlencoded`, `octet-stream`, `pdf`, `png`, ...), or `*` for either. | 0.0.1 |
| [`standard-response-codes`](/docs/linter/openapi/rules/standard-response-codes.md) | This rule checks that every response is keyed by a three-digit HTTP status code from `100` to `599`, by a range from `1XX` to `5XX`, or by `default`. | 0.0.1 |
| [`standard-response-errors`](/docs/linter/openapi/rules/standard-response-errors.md) | This rule checks that every 4xx and 5xx response has the error format of one convention, Problem Details (RFC 9457) unless configured otherwise. | 0.0.1 |
| [`tag-description-defined`](/docs/linter/openapi/rules/tag-description-defined.md) | This rule checks that every tag has a description of at least 10 characters that is not a placeholder. | 0.0.1 |
| [`tags-sorted`](/docs/linter/openapi/rules/tags-sorted.md) | This rule checks that the tags of the document are in alphabetical order of their names. | 0.0.1 |
| [`tags-unique`](/docs/linter/openapi/rules/tags-unique.md) | This rule checks that no two tags have the same name, compared without regard to case. | 0.0.1 |
| [`unambiguous-response-codes`](/docs/linter/openapi/rules/unambiguous-response-codes.md) | This rule checks that no operation declares both a range, such as `2XX`, and a code of that range, such as `204`. | 0.0.1 |
| [`unused-request-body`](/docs/linter/openapi/rules/unused-request-body.md) | This rule checks that `GET`, `HEAD` and `TRACE` operations have no request body. | 0.0.1 |
| [`unused-shared-component`](/docs/linter/openapi/rules/unused-shared-component.md) | This rule checks that every component of the document is reachable from its paths, webhooks, security requirements or tags. | 0.0.1 |
