# apigenie lint

Source: https://apigenie.pl/docs/reference/cli/lint
Part of the reference of [apigenie](https://apigenie.pl/docs/reference/cli.md).
Its other pages: [bundle](https://apigenie.pl/docs/reference/cli/bundle.md), [changelog](https://apigenie.pl/docs/reference/cli/changelog.md), [config](https://apigenie.pl/docs/reference/cli/config.md), [convert](https://apigenie.pl/docs/reference/cli/convert.md), [credits](https://apigenie.pl/docs/reference/cli/credits.md), [diff](https://apigenie.pl/docs/reference/cli/diff.md), [evolve](https://apigenie.pl/docs/reference/cli/evolve.md), [format](https://apigenie.pl/docs/reference/cli/format.md), [i18n](https://apigenie.pl/docs/reference/cli/i18n.md), [init](https://apigenie.pl/docs/reference/cli/init.md), [license](https://apigenie.pl/docs/reference/cli/license.md), [overlay](https://apigenie.pl/docs/reference/cli/overlay.md), [test](https://apigenie.pl/docs/reference/cli/test.md).

Checks OpenAPI, Swagger 2.0 and AsyncAPI documents, Protobuf files and GraphQL schemas and
operations against the rules of a ruleset, reports every issue with its position in the file, and
fixes what its rules know how to fix. Each kind of document has a linter of its own, with its own
rules, rulesets and configuration. [Linter rules](/docs/linter) lists the rules of all five with what
each checks, since which version it exists and the rulesets that turn it on.

## Usage

```sh
apigenie lint [OPTIONS] FILES...
apigenie lint --fix [OPTIONS] FILES...
apigenie lint --watch [OPTIONS] FILES...
```

Without options, each file is checked with the `recommended` ruleset of its linter, or with the
rulesets of the project's configuration file, and the issues are printed in the `stylish` format,
which ends with their counts:

```sh
apigenie lint api/openapi.yaml
```

```text
  769:12  warning  Object schema does not define constraints restricting its size       schema-constraints
  769:12  error    Object schema does not disable additional properties                 schema-no-additional-properties
  781:8   error    Schema with integer type does not define proper format               schema-format-defined
  785:6   warning  Unused shared component                                              unused-shared-component

  224 issues (32 errors, 192 warnings)
  0 errors, 6 warnings are potentially auto-fixable
```

## What the linter checks

A file goes to the linter of its specification, which the linter tells from the root field of a JSON
or YAML document, or from the file's extension:

| File                           | Recognized by                                                                 | Rules | Configuration            |
| ------------------------------ | ----------------------------------------------------------------------------- | ----- | ------------------------ |
| OpenAPI 3.0, 3.1 or 3.2        | the `openapi` field of the root; any other JSON or YAML document is read as OpenAPI | 67 (64 before 0.12.0) | `commands.lint`          |
| Swagger 2.0                    | the `swagger` field of the root                                               | 48    | `commands.lint.swagger`  |
| AsyncAPI 3                     | the `asyncapi` field of the root                                              | 39 (34 before 0.12.0) | `commands.lint.asyncapi` |
| Protobuf (proto3)              | the `.proto` extension                                                        | 39    | `commands.lint.protobuf` |
| GraphQL schemas and operations | the `.graphql`, `.graphqls` or `.gql` extension                               | 87    | `commands.lint.graphql`  |

A file that cannot be parsed, or that is not a document of its specification, is reported as
`Errors reading OpenAPI file 'FILE':` (or `AsyncAPI`, `Swagger`, `Protobuf`, `GraphQL`) with the
position and the message of each error, and the run stops with exit status 2; the files before it
are reported.

### Rules and severities

Every rule checks one thing, such as [contact-defined](/docs/linter/openapi/rules/contact-defined)
(the `info.contact` of an OpenAPI document has a name and a way to reach it) or
[paths-max-count](/docs/linter/openapi/rules/paths-max-count) (the document has at most the given
number of paths). A rule has a severity, `error`, `warning` or `hint` (also written `info`), which
its ruleset sets and the configuration changes. All three are reported, but only errors fail the
run; hints are suggestions, and do not count as warnings either. A rule reports a hint where its
advice cannot be followed yet, such as
[schema-format-deprecated](/docs/linter/openapi/rules/schema-format-deprecated) in OpenAPI 3.0
documents. Some rules take options, listed on their pages, such as the number of paths of
`paths-max-count`.

### Rulesets

A ruleset is a named set of rules with their severities and options. Every linter has
`recommended`, `strict`, which turns on more rules, and `all`, every rule of the linter. The OpenAPI linter also has
[json-api](/docs/linter/openapi/rulesets/json-api), the conventions of JSON:API documents, and
[privacy](/docs/linter/openapi/rulesets/privacy), which keeps credentials and personal data out of
URLs and is not part of `all`; the AsyncAPI linter has
[cloudevents](/docs/linter/asyncapi/rulesets/cloudevents), the envelope of CloudEvents messages,
not part of `all` either; the GraphQL linter has [relay](/docs/linter/graphql/rulesets/relay),
the Relay Cursor Connections conventions. A configuration lists the rulesets it `extends`, in
order, and changes rules one by one under `rules`; see [Configuration](#configuration).

The OpenAPI, AsyncAPI and Swagger linters also extend Spectral ruleset files, by their path (since
0.12.0); see [Ruleset files](#ruleset-files). The OpenAPI and Swagger linters ship with
[`owasp`](#the-owasp-ruleset) (since 0.12.0), Spectral's OWASP API Security Top 10 ruleset,
and the OpenAPI linter with [`camara`](#the-camara-ruleset), the
[CAMARA project](https://camaraproject.org)'s ruleset.

### References to other files

An OpenAPI document may keep parameters, request bodies, responses and other components in other
files, or at URLs. The linter checks what the file holds. A rule about keys, such as
`paths-sorted` or `standard-response-codes`, checks a path or a response in another file too; the
other rules skip it. A rule doesn't report what another file may define: `path-parameters-defined`
accepts a path parameter that a parameter in another file may define. Lint the other files too, or
lint the document with [--bundle](#bundle) to check what the references lead to.

### AsyncAPI documents

The 39 rules of the AsyncAPI linter are those of the OpenAPI linter that make sense for AsyncAPI 3
documents (`contact-defined`, `license-defined`, `operation-tags-defined`, `unused-shared-component`
and others) and rules of its own, such as `channel-parameters-defined`, `channel-addresses-unique`
and `server-hosts`. Since 0.12.0 they include the 5 core rules of the AsyncAPI parser
(`asyncapi validate`) that the linter lacked: `operation-messages-from-channel`,
`operation-channel-in-channels`, `channel-servers-in-servers`, `channel-address-no-query` and
`latest-version`. Custom rules, JavaScript functions, `x-apigenie-lint-disable` and `--fix` work
as for OpenAPI documents. OpenAPI and AsyncAPI files can be linted in one run.

### Swagger 2.0 documents

The 48 rules of the Swagger linter are those of the OpenAPI linter that make sense for Swagger 2.0
documents (`operation-id-unique`, `parameters-unique`, `path-parameters-defined`,
`unused-shared-component` and others) and rules of its own: `host-defined`, `schemes-secure`,
`media-types-defined` and `swagger-validation`, which reports the violations of the Swagger 2.0
specification that span several objects (undefined security schemes, unresolved references,
several body parameters and so on). Custom rules (with `oas2` in their `formats`), JavaScript
functions, `x-apigenie-lint-disable` and `--fix` work as for OpenAPI documents.

### Protobuf files

The 39 rules of the Protobuf linter check proto3 files for the naming of packages, files, messages,
fields, enums and their values, oneofs, services and methods, for comments on declarations, for
imports (resolved, used, sorted, without cycles, neither `public` nor `weak`), for the directory and
version suffix of a package and the consistency of its options across files, for the request and
response names of methods and their streaming, and for spelling. Imports are looked up in the
directories of `--proto-path`, in the `import_paths` of the configuration and in the directories
above the importing file. `--fix` fixes `import-used` and `imports-sorted`.

### GraphQL documents

The 87 rules of the GraphQL linter check schemas and operations: the type system and operation
rules of the GraphQL specification, naming conventions, descriptions, deprecations, schema design
(root types, mutation inputs and payloads, unreachable types, identifiers), the Relay connection
conventions, ordering and spelling. Operations are checked against a schema, the one of
`--graphql-schema` or of the `schema` setting, or else the type system of their own document:
unknown fields, types and arguments, required arguments, deprecated fields and selection depth.
`--fix` does not change GraphQL files.

## Disabling rules in a document

A rule that a part of a document breaks on purpose, because of a legacy decision or work in
progress, is disabled in the document itself, as close to that part as possible:

- In an OpenAPI, Swagger or AsyncAPI document, the `x-apigenie-lint-disable` extension of any
  object, the root included, lists the rules disabled for that object and everything nested in it.
  Here [contact-defined](/docs/linter/openapi/rules/contact-defined) is disabled for `info`, and so
  for its `contact`:

  ```yaml
  info:
    x-apigenie-lint-disable:
      - contact-defined
  ```

- In a Protobuf file, a comment attached to a declaration (before it, or at the end of its line)
  with `apigenie-lint-disable rule-a, rule-b` disables the rules for the declaration and everything
  nested in it; without rule ids it disables every rule. On the `syntax` statement it covers the
  whole file.

- In a GraphQL document, a comment `# apigenie-lint-disable rule-a, rule-b` before a definition
  disables the rules for it and everything nested in it; without rule ids it disables every rule.
  The comments at the top of the file that a blank line separates from the first definition, and
  the comments of the `schema` definition, cover the whole file.

Custom rules honour the extension and the comments like built-in rules.

## Custom rules

A rule of the OpenAPI, Swagger or AsyncAPI linter can also be defined in the configuration, under
`rules`, with an id that is not a built-in rule's. A custom rule is data, in the format of
[Spectral](https://docs.stoplight.io/docs/spectral): it selects parts of the document with a
JSONPath expression and checks each of them with a function.

```yaml
version: "1.0"
commands:
  lint:
    extends: [recommended]
    rules:
      operation-summary:
        description: Operations must have a summary
        message: "{{property}} is missing at {{path}}"
        severity: error
        given: "$.paths[*][get,put,post,delete,patch]"
        then:
          field: summary
          function: truthy
```

A rule definition accepts these properties:

| Property      | Description |
| ------------- | ----------- |
| `given`       | JSONPath expression, or a list of them, selecting the values to check. Required. |
| `then`        | What to check: an object or a list of objects with `function`, optional `functionOptions` and optional `field`; a `message` there is ignored (since 0.12.0). Required. |
| `field`       | Narrows each selected value: a member path (`summary`, `a.b[0]`), `@key` to check member names, or a JSONPath expression relative to the value (`$.properties[*]`). |
| `message`     | Message template; see below. Defaults to `description`, then to the function's message. |
| `description` | Human-readable description of the rule. |
| `severity`    | `error`, `warn` (default), `info`, `hint` or `off`. `info` and `hint` are reported as hints. |
| `resolved`    | Whether the rule sees the document with local `$ref`s followed. Defaults to `true`. |
| `recommended` | `false` (since 0.12.0) leaves the rule off in a ruleset file extended with `recommended` (the default), until `rules` turns it on. Ignored in the configuration's own rules. |
| `formats`     | Restricts the rule to document formats: `oas2` (Swagger 2.0 documents), `oas3`, `oas3_0`, `oas3_1`, `oas3_2`, or, for AsyncAPI documents, `aas3` and `aas3_0`, `aas3_1`, ... |

Messages may use `{{error}}` (the function's message), `{{description}}`,
`{{path}}` (JSON pointer of the problem), `{{property}}` (the last path
segment; since 0.12.0, for a path that doesn't exist, the path from its last existing member in
Spectral's notation: `responses[429].content`) and `{{value}}`. Issues are reported where the
offending value is defined, even when it is reached through a `$ref`. Custom rules honour
`x-apigenie-lint-disable` like built-in ones. A custom rule can be switched off
or have its severity changed later in the configuration (`my-rule: off`), but
it cannot reuse the name of a built-in rule.

### JSONPath

`given` and `field` expressions follow
[RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) with the extensions Spectral
rulesets commonly use:

- member unions without quotes: `$.paths[*][get,put]`;
- `~` at the end selects member names: `$.paths[*]~`;
- `^` selects the parent of what the query has selected so far (since 0.12.0):
  `$.paths..parameters[?(@.name === 'id')]^` is the list that holds the parameter. A member name
  that contains `^` is written in brackets: `$['a^b']`;
- filters written as JavaScript expressions:
  `$..[?(@.type === 'object' && !@.properties)]`, with `@property`, `@parent`,
  `@parentProperty`, `@path` and `$`, and the string and array methods
  `match`, `test`, `startsWith`, `endsWith`, `includes`, `indexOf`,
  `toLowerCase`, `toUpperCase`, `trim` and `length`, and, since 0.12.0, `constructor.name`, which
  is `Array`, `Object`, `String`, `Number` or `Boolean`: `@.type.constructor.name === 'Array'`.

Script expressions such as `[(@.length-1)]` and Spectral aliases (`#Name`)
are not supported.

### Core functions

| Function | Options | Checks that the value... |
| -------- | ------- | ------------------------ |
| `truthy`, `falsy` | none | is (not) truthy in the JavaScript sense |
| `defined`, `undefined` | none | exists / does not exist |
| `enumeration` | `values` | is one of the listed values |
| `length` | `min`, `max` | has a length (string, array, object keys, number) within bounds |
| `pattern` | `match`, `notMatch` | (does not) match a JavaScript regular expression; `/re/flags` is accepted |
| `casing` | `type` (`flat`, `camel`, `pascal`, `kebab`, `cobol`, `snake`, `macro`), `disallowDigits`, `separator.char`, `separator.allowLeading` | follows a naming convention |
| `alphabetical` | `keyedBy` | lists keys or items in alphabetical order |
| `or`, `xor` | `properties` | has at least one / exactly one of the listed members |
| `schema` | `schema`, `dialect`, `allErrors` | is valid against a JSON Schema (draft 4 to 2020-12) |
| `typedEnum` | none | has `enum` values matching its `type` |
| `unreferencedReusableObject` | `reusableObjectsLocation` | has only members referenced somewhere in the document |

### JavaScript functions

When the core functions are not enough, a function can be written in JavaScript. It is listed
under `functions`; API Genie loads `<name>.js` from the `functions`
directory next to the configuration file (change it with `functionsDir`).

```yaml
commands:
  lint:
    functions: [operationIdPrefix]
    rules:
      operation-id-prefix:
        given: "$.paths[*][*].operationId"
        then:
          function: operationIdPrefix
          functionOptions: { prefix: api }
```

A function is an ES module whose default export receives the value, the
options and a context, and returns a list of problems. The contract is that of
Spectral custom functions, so a function written for Spectral works unchanged:

```js
// functions/operationIdPrefix.js
import { createRulesetFunction } from '@stoplight/spectral-core';
import { casing } from '@stoplight/spectral-functions';

export default createRulesetFunction(
  {
    input: { type: 'string' },
    options: {
      type: 'object',
      properties: { prefix: { type: 'string' } },
      required: ['prefix'],
    },
  },
  (input, options, context) => {
    if (!input.startsWith(options.prefix)) {
      return [{ message: `must start with "${options.prefix}"` }];
    }
    return casing(input, { type: 'camel' }, context);
  },
);
```

- `createRulesetFunction` validates `functionOptions` when the configuration
  is loaded and skips values that do not match `input`.
- A result may carry a `path`, an array of keys and indexes, to point at a more specific
  location than `context.path`. Since 0.12.0, as in Spectral, a segment of another type, such
  as a negative number or an array, names the member that `String(value)` names. A path to a
  member that doesn't exist is reported at the closest member that does.
- `context` provides `path`, `rule` (`name`, `severity`, `resolved`),
  `document` (`formats`, `data`) and `documentInventory`: `resolved`, `unresolved`, and, since
  0.12.0, `graph.overallOrder()`, each distinct `$ref` value of the document once, depth first.
- `console.log`, `console.info`, `console.warn`, `console.error` and `console.debug` print nothing
  (since 0.12.0); other `console` methods are not defined.
- Functions may be `async`.
- A function that throws is reported as an issue of its rule.

Functions run in a sandbox: they can import other modules from the functions
directory and the two built-in `@stoplight` modules, but have no access to the
file system, network, processes or timers. Each call must finish within 5
seconds. Custom JavaScript functions are not available in the WebAssembly
build.

### Ruleset files

The OpenAPI, AsyncAPI and Swagger linters read Spectral ruleset files (YAML or JSON) since 0.12.0.
`extends` names one by its path, relative to the configuration file, next to API Genie's rulesets:

```yaml
commands:
  lint:
    extends: [recommended, ./lint/team.spectral.yaml]
    rules:
      team-no-todo: error
```

```yaml
# lint/team.spectral.yaml
extends: ./base.spectral.yaml
functionsDir: ./functions
functions: [noTodo]
rules:
  team-path-casing:
    given: "$.paths[*]~"
    then: { function: pattern, functionOptions: { match: "^(/[a-z-]+)+$" } }
  team-no-todo:
    recommended: false
    given: "$..description"
    then: { function: noTodo }
```

- An entry of `extends` is a path when it starts with `./`, `../`, `/`, `.\`, `..\` or `\`, is an
  absolute path, or ends in `.yaml`, `.yml` or `.json`. A file's own `extends`, `functions` and `functionsDir`
  resolve against that file.
- The rulesets and the files apply in the order of `extends`, each file after what it extends,
  then the configuration's own `rules`, which can change the severity of a file's rule or switch it
  off.
- `[ruleset, mode]` chooses how a ruleset's rules apply. `recommended` (the default) leaves out
  definitions with `recommended: false`, and `all` applies them too. `off` applies none, and a rule
  it defines can still be turned on under `rules`: `team-no-todo: error`, or `true` for the
  severity of its definition. On a built-in ruleset, `off` leaves it out and `all` is the same as
  `recommended`.
- Files are local: a URL is an error, and so is a file that extends itself. In a ruleset file,
  `spectral:oas`, `spectral:asyncapi` and npm packages other than
  `@stoplight/spectral-owasp-ruleset` are skipped with a warning on the standard error. So are the
  settings of rules the linter doesn't have, and `aliases` and `overrides`.
- A file in `extends` applies to the documents of that section's linter. A file of
  [--ruleset](#ruleset-file) applies to OpenAPI, AsyncAPI and Swagger documents: give its rules
  `formats` to keep them to one standard. A top-level `formats` is ignored, as are `description`,
  `documentationUrl` and `parserOptions`; another unknown top-level key is an error.
- [--ruleset](#ruleset-file) adds a file from the command line.
- The editor and the VS Code extension read ruleset files too, by relative path, without their
  functions: [the editor's hosts](/docs/reference/editor/hosts#panels) lists what they leave out.

### The `owasp` ruleset

`owasp` (since 0.12.0) checks OpenAPI and Swagger 2.0 documents for 8 of the 10 risks of the
[OWASP API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0x11-t10/), 2023
edition: API1 to API5 and API7 to API9. Its rules cover numeric ids, authentication schemes,
additional properties, unbounded strings, arrays and integers, rate limits, admin endpoints, URL
parameters, error responses, CORS, plain HTTP and server inventories. It is Spectral's
[`@stoplight/spectral-owasp-ruleset`](https://github.com/stoplightio/spectral-owasp-ruleset) 2.0.1,
with its 32 rules and 2 JavaScript functions, and ships with API Genie:

```yaml
version: '1.0'
commands:
  lint:
    extends: [recommended, owasp]
    swagger:
      extends: [recommended, owasp]
```

With `extends: [owasp]` alone in `apigenie.yaml`, `apigenie lint openapi.yaml` reports 12 issues
on this document:

```yaml
openapi: 3.1.0
info:
  title: Pets
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /pets:
    get:
      responses:
        '200':
          description: The pets
          content:
            application/json:
              schema:
                type: string
```

```sh
apigenie lint openapi.yaml
```

```text
   6:5   error    Declare intended audience of every server by defining servers[0].x-internal as true/false.  owasp:api9:2023-inventory-access
   9:5   warning  This read operation is not protected by any security scheme.                                owasp:api2:2023-read-restricted
  10:7   warning  Operation is missing rate limiting response in responses[429].                              owasp:api4:2023-rate-limit-responses-429
  10:7   warning  Operation is missing rate limiting response in responses[429].content.                      owasp:api4:2023-rate-limit-responses-429
  10:7   warning  Operation is missing responses[401].                                                        owasp:api8:2023-define-error-responses-401
  10:7   warning  Operation is missing responses[401].content.                                                owasp:api8:2023-define-error-responses-401
  10:7   warning  Operation is missing responses[500].                                                        owasp:api8:2023-define-error-responses-500
  10:7   warning  Operation is missing responses[500].content.                                                owasp:api8:2023-define-error-responses-500
  10:7   warning  Missing error response of either 400, 422 or 4XX.                                           owasp:api8:2023-define-error-validation
  11:9   error    All 2XX and 4XX responses should define rate limiting headers.                              owasp:api4:2023-rate-limit
  15:15  error    Schema of type string must specify maxLength, enum, or const.                               owasp:api4:2023-string-limit
  15:15  warning  Schema of type string should specify a format, pattern, enum, or const.                     owasp:api4:2023-string-restricted

  12 issues (3 errors, 9 warnings)
```

- Its rules keep Spectral's ids and severities, and `rules` turns them off or changes their
  severity as for any other rule. `owasp:api7:2023-concerning-url-parameter`, `info` in Spectral,
  is reported as a hint.
- Each rule applies to the documents Spectral applies it to, also from a ruleset file: none lints
  an AsyncAPI document. The rules that read `components.securitySchemes`,
  `owasp:api2:2023-no-http-basic`, `owasp:api2:2023-jwt-best-practices` and
  `owasp:api2:2023-short-lived-access-tokens`, report nothing in a Swagger 2.0 document.
- A Spectral ruleset file that extends `@stoplight/spectral-owasp-ruleset` gets it without a change,
  as [`camara`](#the-camara-ruleset) does. In `apigenie.yaml`, write `owasp`.
- On 120 of the 121 test documents of the upstream ruleset, it reports the rules, lines and
  messages that Spectral reports. On the other, which has an `apiKey` security scheme `in: path`
  that OpenAPI doesn't allow, API Genie stops with exit status 2.
- The editor and the VS Code extension don't have it: its functions need JavaScript, which they
  don't run. There, a configuration that extends `owasp` gets an error on `extends` that begins
  `Unknown ruleset owasp`, and the documents are linted with the default rules.

| Rule | Severity | Documents |
| --- | --- | --- |
| `owasp:api1:2023-no-numeric-ids` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api2:2023-no-http-basic` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api2:2023-no-api-keys-in-url` | error | OpenAPI 3 |
| `owasp:api2:2023-no-credentials-in-url` | error | OpenAPI 3 |
| `owasp:api2:2023-auth-insecure-schemes` | error | OpenAPI 3 |
| `owasp:api2:2023-jwt-best-practices` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api2:2023-short-lived-access-tokens` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api2:2023-write-restricted` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api2:2023-read-restricted` | warning | Swagger 2.0, OpenAPI 3 |
| `owasp:api3:2023-no-additionalProperties` | warning | OpenAPI 3.0 |
| `owasp:api3:2023-constrained-additionalProperties` | warning | OpenAPI 3.0 |
| `owasp:api3:2023-no-unevaluatedProperties` | warning | OpenAPI 3.1 |
| `owasp:api3:2023-constrained-unevaluatedProperties` | warning | OpenAPI 3.1 |
| `owasp:api4:2023-rate-limit` | error | OpenAPI 3 |
| `owasp:api4:2023-rate-limit-retry-after` | error | OpenAPI 3 |
| `owasp:api4:2023-rate-limit-responses-429` | warning | Swagger 2.0, OpenAPI 3 |
| `owasp:api4:2023-array-limit` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api4:2023-string-limit` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api4:2023-string-restricted` | warning | Swagger 2.0, OpenAPI 3 |
| `owasp:api4:2023-integer-limit` | error | OpenAPI 3.1 |
| `owasp:api4:2023-integer-limit-legacy` | error | Swagger 2.0, OpenAPI 3.0 |
| `owasp:api4:2023-integer-format` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api5:2023-admin-security-unique` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api7:2023-concerning-url-parameter` | hint | Swagger 2.0, OpenAPI 3 |
| `owasp:api8:2023-define-cors-origin` | error | Swagger 2.0, OpenAPI 3 |
| `owasp:api8:2023-no-scheme-http` | error | Swagger 2.0 |
| `owasp:api8:2023-no-server-http` | error | OpenAPI 3 |
| `owasp:api8:2023-define-error-validation` | warning | Swagger 2.0, OpenAPI 3 |
| `owasp:api8:2023-define-error-responses-401` | warning | Swagger 2.0, OpenAPI 3 |
| `owasp:api8:2023-define-error-responses-500` | warning | Swagger 2.0, OpenAPI 3 |
| `owasp:api9:2023-inventory-access` | error | OpenAPI 3 |
| `owasp:api9:2023-inventory-environment` | error | OpenAPI 3 |

### The `camara` ruleset

`camara` (since 0.12.0) is the ruleset the [CAMARA project](https://camaraproject.org) lints its
APIs with, for Commonalities r4. It is the `.spectral-r4.yaml` file of
[camaraproject/tooling](https://github.com/camaraproject/tooling/tree/main/linting/config) as of 4
November 2026, with its 41 rules and 14 JavaScript functions. It ships with API Genie, so nothing
needs to be copied into the repository:

```yaml
version: '1.0'
commands:
  lint:
    extends: [camara]
```

- Its rules keep their ids (`camara-properties-descriptions`), and `rules` changes them as it changes
  any other rule. Two of them are `recommended: false`: `[camara, all]` also applies the
  deprecated `camara-discriminator-use`, and `camara-language-avoid-telco`, whose function only
  logs to the console and so reports nothing. `[camara, off]` applies none.
- Upstream, the file also extends `@stoplight/spectral-owasp-ruleset`, which is
  [`owasp`](#the-owasp-ruleset) here: its rules apply with CAMARA's settings, which turn 15 of them
  off, make 4 warnings and make `owasp:api8:2023-define-error-responses-401` an error. It extends
  `spectral:oas` too, which API Genie doesn't have: those rules don't run, and nothing is reported
  about it. The file's setting `operation-success-response: true` turns on API Genie's rule of
  that id, as a warning. Add `recommended` next to it for API Genie's other checks:
  `extends: [recommended, camara]`.
- A ruleset file can extend it too (`extends: [camara]`), which lints with it under
  `--no-config --ruleset FILE`. `--ruleset` itself always names a file.
- CAMARA's APIs reference `CAMARA_common.yaml` and its other common files: lint them with
  [`bundle: true`](#configuration) in the configuration, or [--bundle](#bundle), so that the rules
  check what the references lead to.
- The editor and the VS Code extension don't have it: its functions need JavaScript, which they
  don't run. There, a configuration that extends `camara` gets an error on `extends` that begins
  `Unknown ruleset camara`, and the documents are linted with the default rules.
- [Lint CAMARA APIs](/docs/guides/industry/lint-camara-apis) sets up a CAMARA repository, its pull
  requests included.

## Fixing

`--fix` fixes what the rules know how to fix and writes the files back under their names: the
rules marked auto-fixable on their pages, 19 of the OpenAPI linter, 18 of the Swagger linter, 11
of the AsyncAPI linter and 2 of the Protobuf linter (`import-used` and `imports-sorted`). The
YAML comments of a fixed OpenAPI, Swagger or AsyncAPI document stay with the values they belong to,
and those of a value a fix removes go with it; `--strip-comments` drops them instead. A Protobuf
file is fixed by editing its text, which keeps everything outside the edited declarations. Files
without fixes are not rewritten. The exit status counts the issues that remain after the fixes.

## Formatters

`--formatter NAME` chooses how the issues are written to standard output. The formats are those of
ESLint's formatters, with SARIF added, so that tools which read ESLint reports read these too. Every format sorts the issues by
file, then by line and column. `checkstyle`, `html`, `json`, `junit`, `sarif` and `tap` write one
document for the whole run, reported at the end; `compact`, `stylish`, `unix` and `visualstudio`
report each file as soon as it is linted.

### checkstyle

The [Checkstyle](https://checkstyle.sourceforge.io) XML format.

```xml
<?xml version="1.0" encoding="utf-8"?>
<checkstyle version="4.3">
    <file name="/apigenie/data/openapi.yaml">
        <error line="2" column="2" severity="error" message="Info summary is missing or empty" source="info-defined"/>
        <error line="12" column="4" severity="warning" message="Tag &apos;Articles&apos; has no meaningful description defined" source="tag-description-defined"/>
        <error line="13" column="4" severity="warning" message="Tag &apos;Comments&apos; has no meaningful description defined" source="tag-description-defined"/>
        <error line="14" column="4" severity="warning" message="Tag &apos;Favorites&apos; has no meaningful description defined" source="tag-description-defined"/>
        <error line="15" column="4" severity="warning" message="Tag &apos;Profile&apos; has no meaningful description defined" source="tag-description-defined"/>
    </file>
</checkstyle>
```

### compact

The default output of JSHint: one line per issue.

```
/apigenie/data/openapi.yaml: line 2, col 2, Error - Info summary is missing or empty. (info-defined)
/apigenie/data/openapi.yaml: line 12, col 4, Warning - Tag 'Articles' has no meaningful description defined. (tag-description-defined)
/apigenie/data/openapi.yaml: line 13, col 4, Warning - Tag 'Comments' has no meaningful description defined. (tag-description-defined)
/apigenie/data/openapi.yaml: line 14, col 4, Warning - Tag 'Favorites' has no meaningful description defined. (tag-description-defined)
/apigenie/data/openapi.yaml: line 15, col 4, Warning - Tag 'Profile' has no meaningful description defined. (tag-description-defined)
```

### html

One HTML file, with the counts and a table of the issues, one row each, linking to the pages of the
rules.

```html
<!DOCTYPE html>
<html>
<body>
  <section id="overview">
    <h1>API Genie Report</h1>
    <ul>
      <li>Total: 224</li>
      <li>Errors: 32</li>
      <li>Warnings: 192</li>
    </ul>
  </section>
  <section id="issues">
    <table>
      <caption>/apigenie/data/openapi.yaml</caption>
      <tr>
        <td class="pos">2:2</td>
        <td class="error">Error</td>
        <td>Info summary is missing or empty</td>
        <td>
          <a href="https://apigenie.pl/docs/linter/openapi/rules/info-defined">info-defined</a>
        </td>
      </tr>
      <tr>
        <td class="pos">12:4</td>
        <td class="warning">Warning</td>
        <td>Tag 'Articles' has no meaningful description defined</td>
        <td>
          <a href="https://apigenie.pl/docs/linter/openapi/rules/tag-description-defined">tag-description-defined</a>
        </td>
      </tr>
    </table>
</body>
</html>
```

### json

A JSON report, for scripts. `results` has one item per file with issues; `formatVersion` is the
version of the format, which changes only when a member is removed or changes meaning (see
[Compatibility](/docs/reference/cli/compatibility)). Its JSON Schema is
[`apigenie-lint-report.json`](https://apigenie.pl/schemas/apigenie-lint-report.json). API Genie 0.9
and earlier wrote the bare `results` array.

```json5
{
  "formatVersion": 1,
  "results": [
    {
      "filePath": "/apigenie/data/openapi.yaml",
      "messages": [
        {
          "column": 2,
          "line": 2,
          "message": "Info summary is missing or empty",
          "ruleId": "info-defined",
          "severity": "error"
        },
        {
          "column": 4,
          "line": 12,
          "message": "Tag 'Articles' has no meaningful description defined",
          "ruleId": "tag-description-defined",
          "severity": "warning"
        },
        ... more issues ...
      ]
    }
  ]
}
```

### junit

The format of the [JUnit Jenkins plugin](https://plugins.jenkins.io/junit/): a test suite per file,
a test case per issue.

```xml
<?xml version="1.0" encoding="utf-8"?>
<testsuites>
  <testsuite package="apigenie" time="0" tests="224" errors="224" name="/apigenie/data/openapi.yaml">
    <testcase time="0" name="apigenie.info-defined" classname="apigenie.info-defined">
      <failure message="Info summary is missing or empty"><![CDATA[line 2, col 2, Error - Info summary is missing or empty. (info-defined)]]></failure>
    </testcase>
    <testcase time="0" name="apigenie.tag-description-defined" classname="apigenie.tag-description-defined">
      <failure message="Tag &apos;Articles&apos; has no meaningful description defined"><![CDATA[line 12, col 4, Warning - Tag 'Articles' has no meaningful description defined. (tag-description-defined)]]></failure>
    </testcase>
    <testcase time="0" name="apigenie.tag-description-defined" classname="apigenie.tag-description-defined">
      <failure message="Tag &apos;Comments&apos; has no meaningful description defined"><![CDATA[line 13, col 4, Warning - Tag 'Comments' has no meaningful description defined. (tag-description-defined)]]></failure>
    </testcase>
  </testsuite>
</testsuites>
```

### sarif

[SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html), the format of
GitHub code scanning and other static analysis dashboards. Files below the current directory are
given relative to it (`%SRCROOT%`), so that code scanning finds them in the repository. A result
whose JSON pointer is known has it as a logical location and in a fingerprint, which lets code
scanning keep tracking the issue when lines move.

```json5
{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "apigenie",
          "informationUri": "https://apigenie.pl",
          "rules": [
            {
              "id": "info-defined",
              "helpUri": "https://apigenie.pl/docs/linter/openapi/rules/info-defined"
            },
            ... more rules ...
          ]
        }
      },
      "originalUriBaseIds": {
        "%SRCROOT%": { "uri": "file:///apigenie/" }
      },
      "results": [
        {
          "ruleId": "info-defined",
          "ruleIndex": 0,
          "level": "error",
          "message": { "text": "Info summary is missing or empty" },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": { "uri": "data/openapi.yaml", "uriBaseId": "%SRCROOT%" },
                "region": { "startLine": 2, "startColumn": 2 }
              },
              "logicalLocations": [
                { "fullyQualifiedName": "#/info", "kind": "member" }
              ]
            }
          ],
          "partialFingerprints": {
            "apigenieLocation/v1": "info-defined|data/openapi.yaml|#/info"
          }
        },
        ... more issues ...
      ]
    }
  ]
}
```

### stylish

The default: a table per file, with the position, the severity, the message and the rule of each
issue, coloured on a terminal, and the counts at the end.

```sh
  764:6   warning  Unused shared component                                              unused-shared-component
  769:12  warning  Object schema does not define constraints restricting its size       schema-constraints
  769:12  error    Object schema does not disable additional properties                 schema-no-additional-properties
  777:6   warning  Unused shared component                                              unused-shared-component
  781:8   error    Schema with integer type does not define proper format               schema-format-defined
  781:8   warning  Integer schema does not define constraints restricting its range     schema-constraints
  785:6   warning  Unused shared component                                              unused-shared-component
  789:8   error    Schema with integer type does not define proper format               schema-format-defined
  789:8   warning  Integer schema does not define constraints restricting its range     schema-constraints
  795:6   warning  Unused shared component                                              unused-shared-component

  224 issues (32 errors, 192 warnings)
  0 errors, 6 warnings are potentially auto-fixable
```

### tap

[Test Anything Protocol](https://testanything.org) version 14: one test per file, with the issues
as its YAML diagnostics.

```yaml
TAP version 14
1..1
not ok - /apigenie/data/openapi.yaml
  ---
  errorCount: 32
  issues:
    - column: 2
      line: 2
      message: Info summary is missing or empty
      ruleId: info-defined
      severity: error
    - column: 4
      line: 12
      message: Tag 'Articles' has no meaningful description defined
      ruleId: tag-description-defined
      severity: warning
    - column: 4
      line: 13
      message: Tag 'Comments' has no meaningful description defined
      ruleId: tag-description-defined
      severity: warning
```

### unix

One line per issue in the `file:line:column: message` form of Unix tools, for `grep` and `awk`.

```
/apigenie/data/openapi.yaml:2:2: Info summary is missing or empty. [Error/info-defined]
/apigenie/data/openapi.yaml:12:4: Tag 'Articles' has no meaningful description defined. [Warning/tag-description-defined]
/apigenie/data/openapi.yaml:13:4: Tag 'Comments' has no meaningful description defined. [Warning/tag-description-defined]
/apigenie/data/openapi.yaml:14:4: Tag 'Favorites' has no meaningful description defined. [Warning/tag-description-defined]
/apigenie/data/openapi.yaml:15:4: Tag 'Profile' has no meaningful description defined. [Warning/tag-description-defined]
/apigenie/data/openapi.yaml:16:4: Tag 'Tags' has no meaningful description defined. [Warning/tag-description-defined]
```

### visualstudio

The form the integrated terminal of Visual Studio turns into clickable errors.

```
/apigenie/data/openapi.yaml(2,2): error info-defined : Info summary is missing or empty.
/apigenie/data/openapi.yaml(12,4): warning tag-description-defined : Tag 'Articles' has no meaningful description defined.
/apigenie/data/openapi.yaml(13,4): warning tag-description-defined : Tag 'Comments' has no meaningful description defined.
/apigenie/data/openapi.yaml(14,4): warning tag-description-defined : Tag 'Favorites' has no meaningful description defined.
/apigenie/data/openapi.yaml(15,4): warning tag-description-defined : Tag 'Profile' has no meaningful description defined.
/apigenie/data/openapi.yaml(16,4): warning tag-description-defined : Tag 'Tags' has no meaningful description defined.
```

## Options

### --config FILE

The configuration file. Without it, the first of `apigenie.yaml`, `apigenie.yml`, `apigenie.json`,
`.apigenie.yaml`, `.apigenie.yml` and `.apigenie.json` found in the current directory or its
parents, up to the root of the git repository, is read. See [Configuration](#configuration).

```sh
apigenie lint --config api-style-guide.yaml api/*.yaml
```

### --no-config

Lints without looking for a configuration file: with the `recommended` ruleset of each linter, or,
for the OpenAPI, AsyncAPI and Swagger linters, with the files of `--ruleset` instead.

### --ruleset FILE

A Spectral ruleset file that OpenAPI, AsyncAPI and Swagger documents are linted with (since
0.12.0). It applies after the rulesets of the configuration's `extends` and before its `rules`,
which can re-tune the file's rules. Without a configuration file, and for a linter whose
section is missing, it replaces `recommended`. The path is relative to the current directory, and
always names a file, whatever its name: a file that doesn't end in `.json` is read as YAML. Can be
repeated; see [Ruleset files](#ruleset-files).

```sh
apigenie lint --no-config --ruleset .spectral.yaml api/openapi.yaml
```

### --fix

Fixes the issues the rules know how to fix and writes the files back; see [Fixing](#fixing). The
exit status counts the issues that remain.

```sh
apigenie lint --fix api/openapi.yaml
```

### --bundle

Bundles the local files an OpenAPI 3.x document references into it before linting, as
[bundle](/docs/reference/cli/bundle) does, so that the rules check what the references lead to. An
issue in bundled content is reported in the file it comes from, at its line. A reference to a URL
can't be bundled: the command reports it and exits with status 2. `--bundle` can't be combined with
`--fix`, which would write the bundled document to the file. Swagger and AsyncAPI files are linted as
they are. To bundle on every run except under `--fix`, set [`bundle: true`](#configuration) in the
configuration.

```sh
apigenie lint --bundle api/openapi.yaml
```

### --strip-comments

With `--fix`, drops the YAML comments of the OpenAPI, Swagger and AsyncAPI documents it rewrites
instead of keeping them.

### --watch

Keeps running, and lints again whenever an input file, the configuration file, a ruleset file, a
JavaScript function file or a GraphQL schema file changes. A ruleset file that can't be read or
parsed is watched too, so fixing it lints again. Each run is preceded by a `Changed: PATH` line for
every changed file on standard error, so that the reports on standard output stay parseable. The
command never exits because of issues.

```sh
apigenie lint --watch --formatter compact api/*.yaml
```

### --formatter NAME

The format of the report: `checkstyle`, `compact`, `html`, `json`, `junit`, `sarif`, `stylish`
(the default), `tap`, `unix` or `visualstudio`; see [Formatters](#formatters).

```sh
apigenie lint --formatter sarif api/openapi.yaml > lint.sarif
```

### --proto-path DIR

A directory in which the imports of `.proto` files are looked up, before the `import_paths` of the
configuration and the directories above the importing file. Can be repeated.

```sh
apigenie lint --proto-path proto --proto-path third_party proto/acme/**/*.proto
```

### --graphql-schema FILE

A GraphQL schema file that the operations and fragments of the linted GraphQL files are checked
against. Can be repeated for a schema split across files. When given, it replaces the files of
the [schema](#graphql) setting of the configuration; relative paths resolve against the current
directory. With `--watch`, the schema files are watched too.

```sh
apigenie lint --graphql-schema schema.graphql queries/*.graphql
```

## Exit status

| Status | When                                                                                                                                                                  |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0      | No issue of severity `error` was reported; warnings and hints do not count. With `--fix`, no error remains after the fixes.                                           |
| 1      | At least one error was reported, or remains after the fixes of `--fix`.                                                                                               |
| 2      | The configuration, a ruleset file or an input file cannot be read or parsed or is invalid, a ruleset is a URL or a ruleset file extends itself, or an input is not a document of its specification. The files before it are reported. `--fix` is combined with `--bundle`: no file is linted. |

With `--watch` the command keeps running and never exits because of issues. See the
[exit statuses](/docs/reference/cli#exit-status) shared by the commands.

## Configuration

The settings live under `commands.lint` of the [configuration file](/docs/reference/cli/configuration).
The keys of the section configure the OpenAPI linter; its `asyncapi`, `swagger`, `protobuf` and
`graphql` sections configure the other linters, each with its own rules. Without a configuration
file, and for every linter whose section is missing, the `recommended` ruleset applies, as if the
configuration were the one below. For the OpenAPI, AsyncAPI and Swagger linters, the files of
[--ruleset](#ruleset-file) replace it.

```yaml
version: "1.0"
commands:
  lint:
    extends: [recommended]
```

| Key            | Linter   | Keys                                                           |
| -------------- | -------- | -------------------------------------------------------------- |
| `extends`      | OpenAPI  | The rulesets and ruleset files to combine, in order            |
| `rules`        | OpenAPI  | The settings of single rules, and custom rules                 |
| `functions`    | OpenAPI  | The JavaScript functions of custom rules                       |
| `functionsDir` | OpenAPI  | Their directory, `functions` next to the configuration file    |
| `bundle`       | OpenAPI  | Whether to bundle the local files a document references first  |
| `asyncapi`     | AsyncAPI | `extends`, `rules`, `functions`, `functionsDir`                |
| `swagger`      | Swagger  | `extends`, `rules`, `functions`, `functionsDir`                |
| `protobuf`     | Protobuf | `extends`, `rules`, `import_paths`                             |
| `graphql`      | GraphQL  | `extends`, `rules`, `self_contained`, `schema`                 |

**Example** - The recommended rules, with one rule turned off, the severity of one changed, and the
options of two set

```yaml
version: "1.0"
commands:
  lint:
    extends:
      - recommended
    rules:
      info-defined: off
      paths-max-count:
        - error
        - 30
      schema-datetime-suffix:
        - error
        - At
      tags-unique: error
```

`bundle: true` (since 0.12.0) bundles the local files an OpenAPI 3.x document references into it
before linting, on every run, as [--bundle](#bundle) does. The default is `false`, and then
`--bundle` bundles for one run. `--fix` ignores the key: it lints and fixes each file as it is. The
editor and the VS Code extension ignore `bundle` too: they lint what each file holds.

**Example** - A [CAMARA](#the-camara-ruleset) repository, whose APIs reference its common files

```yaml
version: "1.0"
commands:
  lint:
    extends: [recommended, camara]
    bundle: true
```

The formats that the format rules accept come from the [format registry](/docs/reference/cli/formats),
which [openapi.custom_formats](/docs/reference/cli/configuration#openapicustom_formats) extends for
every linter of JSON and YAML documents.

### extends

The rulesets whose rules, severities and options make up the starting point, in the order they are
applied: when two rulesets set the same rule, the later one wins. The names are those of the
ruleset pages of the linter ([OpenAPI](/docs/linter/openapi), [AsyncAPI](/docs/linter/asyncapi),
[Swagger 2.0](/docs/linter/swagger), [Protobuf](/docs/linter/protobuf),
[GraphQL](/docs/linter/graphql)). For the OpenAPI, AsyncAPI and Swagger linters, an entry can also
be (since 0.12.0) a Spectral ruleset file, by its path relative to the configuration file, or a
`[ruleset, recommended|all|off]` pair; see [Ruleset files](#ruleset-files). For the OpenAPI and
Swagger linters, an entry can also be (since 0.12.0) [`owasp`](#the-owasp-ruleset), and for the
OpenAPI linter [`camara`](#the-camara-ruleset); both ship with API Genie.

### rules

The settings of single rules, applied over the rulesets, by rule id. A setting is one of:

- a severity: `off` disables the rule; `warning` (also `warn`), `error` (`err`) and `hint`
  (`info`) enable it with that severity
- `false`, which disables the rule, or `true`, which enables it with its current severity
- a two-element array `[severity, options]`: an active severity and the options of the rule,
  described on its page
- for an id that is not a built-in rule's, the definition of a [custom rule](#custom-rules)
  (OpenAPI, Swagger and AsyncAPI linters)

**Example** - [paths-max-count](/docs/linter/openapi/rules/paths-max-count) reports an error above
30 paths, and `info-defined` is off

```yaml
version: "1.0"
commands:
  lint:
    rules:
      info-defined: off
      paths-max-count:
        - error
        - 30
```

### asyncapi

The configuration of the AsyncAPI linter: `extends`, `rules`, `functions` and `functionsDir` as
above, with the ids of the [AsyncAPI rules](/docs/linter/asyncapi). The OpenAPI settings of
`commands.lint` do not apply to AsyncAPI documents.

```yaml
version: "1.0"
commands:
  lint:
    extends: [recommended]
    asyncapi:
      extends: [strict]
      rules:
        parameter-naming: [warning, camelCase]
        server-hosts: off
```

### swagger

The configuration of the Swagger linter: `extends`, `rules`, `functions` and `functionsDir` as
above, with the ids of the [Swagger 2.0 rules](/docs/linter/swagger). The OpenAPI settings of
`commands.lint` do not apply to Swagger documents.

```yaml
version: "1.0"
commands:
  lint:
    extends: [recommended]
    swagger:
      extends: [strict]
      rules:
        schemes-secure: [error, { upgradeInsecure: true }]
        swagger-validation: [error, { checks: [unresolved-reference, security-scheme-defined] }]
        paths-sorted: off
```

### protobuf

The configuration of the Protobuf linter: `extends` and `rules` as above, with the ids of the
[Protobuf rules](/docs/linter/protobuf), and `import_paths`, the directories searched for imported
files after those of `--proto-path`; relative paths resolve against the directory of the
configuration file.

```yaml
version: "1.0"
commands:
  lint:
    protobuf:
      extends: [strict]
      import_paths: [proto, third_party]
      rules:
        enum-zero-value-suffix: [error, _UNKNOWN]
        rpc-no-client-streaming: off
```

### graphql

The configuration of the GraphQL linter: `extends` and `rules` as above, with the ids of the
[GraphQL rules](/docs/linter/graphql), `self_contained` (whether each document holds every type
and fragment it references, so that references to missing ones are reported; `false` by default)
and `schema` (a path, or a list of paths, of the schema files operations are checked against;
relative paths resolve against the directory of the configuration file;
[--graphql-schema](#graphql-schema-file) replaces them). Without `schema`, operations are checked
against the type system of their own document.

```yaml
version: "1.0"
commands:
  lint:
    graphql:
      extends: [recommended, relay]
      schema: schema.graphql
      rules:
        field-description-defined: warning
        selection-set-depth: [error, { maxDepth: 5 }]
        no-deprecated: off
```

## See also

- [Linter rules](/docs/linter): Every rule of the five linters, and the rulesets.
- [Configuration](/docs/reference/cli/configuration): The configuration file, and where it is looked for.
- [format](/docs/reference/cli/format): Lays out the documents the linter checks.
- [GitHub Action](/docs/ci/github-action): Runs `apigenie lint` in a workflow.
