OpenAPI linter rules
The linter reads OpenAPI 3.0, 3.1 and 3.2 documents.
Rulesets
Rules
| Rule | What it checks | Since |
|---|---|---|
audience-defined | 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 | This rule checks that info.contact is present, with a name and a url or an email. | 0.0.1 |
id-defined | 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 | This rule checks that info has a non-empty summary, description and version. | 0.0.1 |
json-api/content-type | 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 | 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 | 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 | 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 | 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 | This rule checks that no 204 response declares content. | 0.0.1 |
openapi-json-schema-validation | 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 | This rule checks that every operation has a description of at least 10 characters. | 0.0.1 |
operation-document-not-primitive | 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 | 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 | 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 | 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 | This rule checks that every operation has security requirements, its own or the document's. | 0.0.1 |
operation-success-response | 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 | This rule checks that every tag an operation uses is declared in the document's tags. | 0.12.0 |
operation-tags-defined | This rule checks that every operation has at least one tag. | 0.0.1 |
parameter-description-defined | This rule checks that every parameter has a description of at least 10 characters that is not a placeholder. | 0.0.1 |
parameter-naming | 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 | 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 | This rule checks that PATCH request bodies do not require properties. | 0.9.0 |
path-parameters-defined | 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 | 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 | This rule checks that a document declares at most 8 paths, or the number configured. | 0.0.1 |
paths-max-depth | 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 | This rule checks that the paths of a document are in alphabetical order. | 0.0.1 |
paths-unique | 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 | 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 | 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 | 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 | 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 | This rule checks that no description contains a <script> tag or an eval() call. | 0.0.1 |
schema-conditional-effective | This rule checks that if, then and else in schemas have an effect. | 0.9.0 |
schema-constraints | 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 | 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 | This rule checks that every schema with oneOf has a discriminator. | 0.0.1 |
schema-enum-naming | 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 | This rule checks that no value appears twice in an enum. | 0.0.1 |
schema-enum-types | This rule checks that the values of enum and const have the type the schema declares. | 0.0.1 |
schema-example-defined | 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 | 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 | 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 | 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 | 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 | 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 | This rule checks that every object schema has additionalProperties: false. | 0.0.1 |
schema-no-contradictions | 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 | This rule disallows schema properties that are both optional and nullable. | 0.0.1 |
schema-oneof-no-overlap | This rule reports oneOf branches that a single value can match. | 0.9.0 |
schema-property-naming | 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 | This rule checks that every name listed in required is defined in properties. | 0.9.0 |
server-urls | 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 | This rule checks that no URL in the document's top-level servers, other than /, ends with a slash. | 0.12.0 |
servers-defined | This rule checks that the document has at least one server. | 0.0.1 |
spell-check | This rule checks the spelling of the texts written for humans: titles, summaries and descriptions. | 0.0.1 |
standard-media-types | 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 | 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 | 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 | This rule checks that every tag has a description of at least 10 characters that is not a placeholder. | 0.0.1 |
tags-sorted | This rule checks that the tags of the document are in alphabetical order of their names. | 0.0.1 |
tags-unique | This rule checks that no two tags have the same name, compared without regard to case. | 0.0.1 |
unambiguous-response-codes | 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 | This rule checks that GET, HEAD and TRACE operations have no request body. | 0.0.1 |
unused-shared-component | This rule checks that every component of the document is reachable from its paths, webhooks, security requirements or tags. | 0.0.1 |
Was this helpful?