OpenAPI document linting

The Speakeasy Linter validates OpenAPI 3.x documents for correctness, style, and SDK generation readiness. It is built on top of the open-source speakeasy-api/openapi linter framework, which provides a fast, index-based validation engine. By default, the linter runs using the speakeasy-recommended ruleset, which can be extended with any of the available rulesets.

The Speakeasy Linter offers:

• Linting and validation of OpenAPI 3.x documents
• 90+ built-in rules across six categories: SDK generation, spec correctness, best practices, security, schema validation, and Speakeasy-specific checks
• Five built-in rulesets: speakeasy-recommended, speakeasy-generation, speakeasy-openapi, openapi-standard, and owasp
• Full configuration of rules and rulesets via lint.yaml
• Custom rules written in TypeScript or JavaScript using @speakeasy-api/openapi-linter-types

Rules are organized into categories by naming prefix:

Prefix	Category	Purpose
generator-*	SDK Generation	Collision detection, type validation, SDK-specific checks
semantic-*	Spec Correctness	Path params, ambiguous paths, operation IDs, security refs
style-*	Best Practices	Descriptions, tags, kebab-case paths, trailing slashes
owasp-*	Security	OWASP API security best practices
oas-/oas3-	Schema Validation	OAS-version-specific schema and example checks
speakeasy-*	Speakeasy	Speakeasy-specific checks (e.g., document validation)

Usage

Two options are available for running linting:

1. Run manually via the Speakeasy CLI:

speakeasy lint openapi -s openapi.yaml

2. Integrate into a Speakeasy workflow:

workflowVersion: "1.0.0"
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml

Running speakeasy run lints the document as part of the workflow and generates an HTML report accessible from a link in the command output.

By default, these options use the speakeasy-recommended ruleset to ensure OpenAPI documents meet the Speakeasy quality bar.

Configuration

OpenAPI spec linting is fully configurable. Create custom rulesets by selecting from predefined sets or writing new rules. These custom linting rules work throughout the workflow.

Immediately before SDK generation, the speakeasy-generation ruleset is always applied to ensure compatibility with the code generator. This cannot be overridden.

Configure linting in a lint.yaml file in the .speakeasy folder. The .speakeasy folder can be located in the same directory as the OpenAPI document or in the working directory for running the speakeasy lint or speakeasy run commands.

Basic structure

lintVersion: 2.0.0
defaultRuleset: myRuleset
rulesets:
  myRuleset:
    rulesets:
      - speakeasy-recommended  # Extend a built-in ruleset
    rules:
      - id: generator-validate-enums
        severity: warn          # Downgrade severity
      - id: generator-missing-examples
        disabled: true          # Disable a rule
customRules:                    # Optional: load custom TypeScript rules
  paths:
    - ./rules/*.ts
  timeout: 30s                  # Per-rule execution timeout (default: 30s)

Configuration fields

Field	Type	Description
lintVersion	string	Configuration format version. Use 2.0.0.
defaultRuleset	string	Name of the ruleset to use by default.
rulesets	map	Map of ruleset names to ruleset definitions.
customRules	object	Optional. Paths and timeout for custom TypeScript/JS rules.

Ruleset definition

Each ruleset can extend built-in rulesets and override individual rules:

rulesets:
  myRuleset:
    rulesets:            # Built-in or other rulesets to extend
      - speakeasy-recommended
      - owasp
    rules:               # Per-rule overrides
      - id: owasp-string-limit
        severity: warn   # Downgrade from error to warning
      - id: owasp-no-numeric-ids
        disabled: true   # Disable the rule

Rule override options

Field	Type	Description
id	string	The rule ID to configure.
severity	string	Override severity: error, warn, or hint.
disabled	bool	Set to true to disable the rule.
match	string	Regex pattern. When set, the override only applies to errors whose message matches the pattern.

Severity levels

Level	Behavior
error	Fails validation. Blocks SDK generation.
warn	Warning only. Does not block.
hint	Informational. Does not block.

Match filters

Match filters allow severity overrides to apply only to errors that match a regex pattern. This is useful for selectively downgrading specific error messages without affecting all errors from a rule.

rules:
  - id: validation-required-field
    match: ".*info\\.title is required.*"
    severity: warn  # Only downgrade this specific message to warning

Using rulesets

Use rulesets in these ways:

1. Set the defaultRuleset in lint.yaml to use by default. This ruleset applies when no ruleset is specified using the lint command or workflow.yaml file.
2. Pass a ruleset name to the lint command with the -r argument, for example, speakeasy lint openapi -r myRuleset -s openapi.yaml.
3. Define the ruleset for a particular source in the workflow.yaml file:

workflowVersion: "1.0.0"
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml
    ruleset: myRuleset

Real-world example

lintVersion: 2.0.0
defaultRuleset: reviewRuleset
rulesets:
  reviewRuleset:
    rulesets:
      - speakeasy-recommended
    rules:
      - id: generator-missing-error-response
        disabled: true
      - id: generator-missing-examples
        disabled: true

Custom rules

Custom linting rules can be written in TypeScript or JavaScript and loaded alongside built-in rules. Custom rules use the @speakeasy-api/openapi-linter-types package.

Getting started

Step 1. Install the types package in your rules directory:

npm install @speakeasy-api/openapi-linter-types

Step 2. Create a rule file (e.g., rules/require-description.ts):

import {
  Rule,
  registerRule,
  createValidationError,
} from '@speakeasy-api/openapi-linter-types';
import type {
  Context,
  DocumentInfo,
  RuleConfig,
  ValidationError,
} from '@speakeasy-api/openapi-linter-types';

class RequireOperationDescription extends Rule {
  id(): string {
    return 'custom-require-operation-description';
  }

  category(): string {
    return 'style';
  }

  description(): string {
    return 'All operations must have a description field for documentation.';
  }

  summary(): string {
    return 'Operations must have a description';
  }

  run(_ctx: Context, docInfo: DocumentInfo, config: RuleConfig): ValidationError[] {
    const errors: ValidationError[] = [];

    if (!docInfo.index || !docInfo.index.operations) {
      return errors;
    }

    for (const opNode of docInfo.index.operations) {
      const op = opNode.node;
      const description = op.getDescription ? op.getDescription() : '';

      if (!description || description === '') {
        const opId = op.getOperationID ? op.getOperationID() : 'unnamed';
        errors.push(createValidationError(
          config.getSeverity(this.defaultSeverity()),
          this.id(),
          `Operation "${opId}" is missing a description`,
          op.getRootNode ? op.getRootNode() : null
        ));
      }
    }

    return errors;
  }
}

registerRule(new RequireOperationDescription());

Step 3. Configure the linter (.speakeasy/lint.yaml):

lintVersion: 2.0.0
defaultRuleset: myRuleset
rulesets:
  myRuleset:
    rulesets:
      - speakeasy-recommended
    rules:
      - id: custom-require-operation-description
        severity: error  # Optionally override severity
customRules:
  paths:
    - ./rules/*.ts

Rule implementation API

Extend the Rule base class and implement the required methods:

Method	Required	Description
id()	Yes	Unique identifier. Prefix with custom- to avoid collisions.
category()	Yes	Category for grouping: style, security, semantic, etc.
description()	Yes	Full description of what the rule checks.
summary()	Yes	Short summary for display in reports.
run(ctx, docInfo, config)	Yes	Main logic. Returns an array of ValidationError.
link()	No	URL to documentation for this rule.
defaultSeverity()	No	Default: 'warn'. Options: 'error', 'warn', 'hint'.
versions()	No	OpenAPI versions this rule applies to (e.g., ['3.0', '3.1']).

Accessing document data

The DocumentInfo object provides access to the parsed OpenAPI document and pre-computed indices for efficient iteration:

run(ctx: Context, docInfo: DocumentInfo, config: RuleConfig): ValidationError[] {
  // Access the document root
  const doc = docInfo.document;
  const info = doc.getInfo();

  // Access file location
  const location = docInfo.location;

  // Use the pre-computed index for efficient iteration
  const index = docInfo.index;

  // All operations in the document
  for (const opNode of index.operations) {
    const operation = opNode.node;
    const path = opNode.locations.path;
    const method = opNode.locations.method;
  }

  // All component schemas
  for (const schemaNode of index.componentSchemas) {
    const schema = schemaNode.node;
    const name = schemaNode.locations.name;
  }

  // Also available: index.inlineSchemas, index.parameters,
  // index.requestBodies, index.responses, index.headers,
  // index.securitySchemes, and more
}

Creating validation errors

Use createValidationError() to create properly formatted errors:

errors.push(createValidationError(
  config.getSeverity(this.defaultSeverity()),  // Respects user severity overrides
  this.id(),                                    // Rule ID
  'Description of the issue',                   // Error message
  node.getRootNode()                            // YAML/JSON node for line/column info
));

Configuring custom rules

Custom rules support all standard configuration options in lint.yaml:

rules:
  # Override severity
  - id: custom-require-operation-description
    severity: error

  # Disable a custom rule
  - id: custom-require-operation-description
    disabled: true

  # Filter by message pattern
  - id: custom-require-operation-description
    match: ".*unnamed.*"
    severity: hint

Available rules

The rules available to the Speakeasy Linter are listed below and can be used in custom rulesets or to match and modify default rules in the lint.yaml file.

Rule ID

generator-duplicate-errors

Default Severity

hint

Description

Detect duplicate error schemas that would produce multiple SDK error types with colliding names.

generator-duplicate-inline-schemas

Default Severity

hint

Description

Detect duplicate inline schemas that would produce multiple generated SDK types with colliding names.

generator-duplicate-model-namespace

Default Severity

warn

Description

Model namespace values (x-speakeasy-model-namespace) must be unique when converted to folder or package names. Different namespace values that only differ by casing can collide when sanitized for a target language.

generator-duplicate-operation-name

Default Severity

error

Description

Duplicate operation names can cause SDK method name collisions after naming rules are applied (group + method name).

generator-duplicate-path-params

Default Severity

warn

Description

Path parameters must be unique within the path template.

generator-duplicate-properties

Default Severity

error

Description

Property names must be unique and not empty within a schema when converted to field names, accounting for language-specific sanitization rules.

generator-duplicate-schema-name

Default Severity

warn

Description

Schema names must be unique when converted to class names.

generator-duplicate-tag

Default Severity

error

Description

Tag names must be unique when converted to class, field, or file names.

generator-missing-error-response

Default Severity

hint

Description

Error responses should be defined for all operations to document failure cases.

generator-missing-examples

Default Severity

hint

Description

Examples should be provided where possible to improve API documentation and SDK usability.

generator-pagination

Default Severity

hint

Description

Detect operations that appear to support pagination based on request and response patterns.

generator-path-params

Default Severity

error

Description

Path parameters must be defined on the operation and used in the path template.

generator-retries

Default Severity

hint

Description

Retries should be configured for operations that are safe to retry.

generator-validate-composite-schemas

Default Severity

error

Description

Ensure anyOf/allOf/oneOf don't contain duplicate references or identical inline schemas.

generator-validate-consts-defaults

Default Severity

warn

Description

Validate const and default values match their declared schema type.

generator-validate-content-type

Default Severity

error

Description

Ensure multipart/form-data request schemas are objects as required by OpenAPI.

generator-validate-deprecation

Default Severity

error

Description

Ensure correct usage of x-speakeasy-deprecation-replacement and x-speakeasy-deprecation-message extensions.

generator-validate-enums

Default Severity

error

Description

Validate enums for type generation by checking value types, uniqueness, and x-speakeasy-enums definitions.

generator-validate-extensions

Default Severity

error

Description

Validate x-speakeasy-globals extension usage by enforcing unique parameter names and avoiding collisions with server variables.

generator-validate-parameters

Default Severity

error

Description

Validate parameters are unique once converted to field names and have a non-empty name.

generator-validate-paths

Default Severity

error

Description

Validate paths conform to RFC 3986 and use valid URI template syntax.

generator-validate-requests

Default Severity

error

Description

Validate request body content types are valid MIME types.

generator-validate-responses

Default Severity

error

Description

Validate response status codes and content types are syntactically valid.

generator-validate-security

Default Severity

error

Description

Validate security schemes have supported types, flows, and required fields.

generator-validate-servers

Default Severity

hint

Description

Validate servers, their variables, and the x-speakeasy-server-id extension.

generator-validate-types

Default Severity

error

Description

Ensure schema data types and formats are supported for generation.

oas-schema-check

Default Severity

error

Description

Schemas must use type-appropriate constraints and have valid constraint values.

oas3-example-missing

Default Severity

hint

Description

Schemas, parameters, headers, and media types should include example values.

oas3-no-nullable

Default Severity

warn

Description

The nullable keyword is not supported in OpenAPI 3.1+ and should be replaced with a type array that includes null.

owasp-additional-properties-constrained

Default Severity

hint

Description

Schemas with additionalProperties should define maxProperties to limit object size.

owasp-array-limit

Default Severity

error

Description

Array schemas must specify maxItems to prevent resource exhaustion attacks.

owasp-auth-insecure-schemes

Default Severity

error

Description

Authentication schemes using outdated or insecure methods must be avoided.

owasp-define-error-responses-401

Default Severity

warn

Description

Operations should define a 401 Unauthorized response to handle authentication failures.

owasp-define-error-responses-429

Default Severity

warn

Description

Operations should define a 429 Too Many Requests response to indicate rate limiting.

owasp-define-error-responses-500

Default Severity

warn

Description

Operations should define a 500 Internal Server Error response to handle unexpected failures.

owasp-define-error-validation

Default Severity

warn

Description

Operations should define validation error responses (400, 422, or 4XX).

owasp-integer-format

Default Severity

error

Description

Integer schemas must specify a format of int32 or int64.

owasp-integer-limit

Default Severity

error

Description

Integer schemas must specify minimum and maximum values to prevent unbounded inputs.

owasp-jwt-best-practices

Default Severity

error

Description

Security schemes using OAuth2 or JWT must declare support for RFC8725.

owasp-no-additional-properties

Default Severity

error

Description

Object schemas must not allow arbitrary additional properties.

owasp-no-api-keys-in-url

Default Severity

error

Description

API keys must not be passed via URL parameters as they are logged and cached.

owasp-no-credentials-in-url

Default Severity

error

Description

URL parameters must not contain credentials like API keys, passwords, or secrets.

owasp-no-http-basic

Default Severity

error

Description

Security schemes must not use HTTP Basic authentication without additional security layers.

owasp-no-numeric-ids

Default Severity

error

Description

Resource identifiers must use random values like UUIDs instead of sequential numeric IDs.

owasp-protection-global-safe

Default Severity

hint

Description

Safe operations (GET, HEAD) should be protected by security schemes or explicitly marked as public.

owasp-protection-global-unsafe

Default Severity

error

Description

Unsafe operations (POST, PUT, PATCH, DELETE) must be protected by security schemes.

owasp-protection-global-unsafe-strict

Default Severity

hint

Description

Unsafe operations must be protected by non-empty security schemes without explicit opt-outs.

owasp-rate-limit

Default Severity

error

Description

2XX and 4XX responses must define rate limiting headers.

owasp-rate-limit-retry-after

Default Severity

error

Description

429 Too Many Requests responses must include a Retry-After header.

owasp-security-hosts-https-oas3

Default Severity

error

Description

Server URLs must begin with https://.

owasp-string-limit

Default Severity

error

Description

String schemas must specify maxLength, const, or enum to prevent unbounded data.

owasp-string-restricted

Default Severity

error

Description

String schemas must specify format, const, enum, or pattern to restrict content.

semantic-duplicated-enum

Default Severity

warn

Description

Enum arrays should not contain duplicate values.

semantic-link-operation

Default Severity

error

Description

Link operationId must reference an existing operation in the API specification.

semantic-no-ambiguous-paths

Default Severity

error

Description

Path definitions must be unambiguous and distinguishable from each other.

semantic-no-eval-in-markdown

Default Severity

error

Description

Markdown descriptions must not contain eval() statements.

semantic-no-script-tags-in-markdown

Default Severity

error

Description

Markdown descriptions must not contain tags.

semantic-operation-id-valid-in-url

Default Severity

error

Description

Operation IDs must use URL-friendly characters.

semantic-operation-operation-id

Default Severity

warn

Description

Operations should define an operationId for consistent referencing.

semantic-path-declarations

Default Severity

error

Description

Path parameter declarations must not be empty.

semantic-path-params

Default Severity

error

Description

Path template variables must have corresponding parameter definitions.

semantic-path-query

Default Severity

error

Description

Paths must not include query strings. Query parameters should be defined in the parameters array.

semantic-typed-enum

Default Severity

warn

Description

Enum values must match the specified type.

semantic-unused-component

Default Severity

warn

Description

Components that are declared but never referenced should be removed.

speakeasy-validate-document

Default Severity

error

Description

Document must have a paths or webhooks object with at least one entry.

style-component-description

Default Severity

hint

Description

Reusable components should include descriptions.

style-contact-properties

Default Severity

warn

Description

The contact object should include name, url, and email properties.

style-description-duplication

Default Severity

warn

Description

Description and summary fields should not contain identical text.

style-info-contact

Default Severity

warn

Description

The info section should include a contact object.

style-info-description

Default Severity

warn

Description

The info section should include a description field.

style-info-license

Default Severity

hint

Description

The info section should include a license object.

style-license-url

Default Severity

hint

Description

The license object should include a URL pointing to the full license text.

style-no-ref-siblings

Default Severity

warn

Description

In OpenAPI 3.0.x, a $ref field should not have sibling properties alongside it.

style-no-verbs-in-path

Default Severity

warn

Description

Path segments should not contain HTTP verbs.

style-oas3-api-servers

Default Severity

warn

Description

OpenAPI 3.x specifications should define at least one server with a valid URL.

style-oas3-host-not-example

Default Severity

warn

Description

Server URLs should not point to example.com domains.

style-oas3-host-trailing-slash

Default Severity

warn

Description

Server URLs should not end with a trailing slash.

style-oas3-parameter-description

Default Severity

warn

Description

Parameters should include descriptions that explain their purpose.

style-openapi-tags

Default Severity

warn

Description

The specification should define a non-empty tags array at the root level.

style-operation-description

Default Severity

warn

Description

Operations should include either a description or summary field.

style-operation-error-response

Default Severity

warn

Description

Operations should define at least one 4xx error response.

style-operation-singular-tag

Default Severity

warn

Description

Operations should be associated with only a single tag.

style-operation-success-response

Default Severity

warn

Description

Operations should define at least one 2xx or 3xx response code.

style-operation-tag-defined

Default Severity

warn

Description

Operation tags should be declared in the global tags array.

style-operation-tags

Default Severity

warn

Description

Operations should have at least one tag.

style-path-trailing-slash

Default Severity

warn

Description

Path definitions should not end with a trailing slash.

style-paths-kebab-case

Default Severity

warn

Description

Path segments should use kebab-case for consistency.

style-tag-description

Default Severity

hint

Description

Tags should include descriptions.

style-tags-alphabetical

Default Severity

warn

Description

Tags should be listed in alphabetical order.

Rule ID	Default Severity	Description
generator-duplicate-errors	hint	Detect duplicate error schemas that would produce multiple SDK error types with colliding names.
generator-duplicate-inline-schemas	hint	Detect duplicate inline schemas that would produce multiple generated SDK types with colliding names.
generator-duplicate-model-namespace	warn	Model namespace values (x-speakeasy-model-namespace) must be unique when converted to folder or package names. Different namespace values that only differ by casing can collide when sanitized for a target language.
generator-duplicate-operation-name	error	Duplicate operation names can cause SDK method name collisions after naming rules are applied (group + method name).
generator-duplicate-path-params	warn	Path parameters must be unique within the path template.
generator-duplicate-properties	error	Property names must be unique and not empty within a schema when converted to field names, accounting for language-specific sanitization rules.
generator-duplicate-schema-name	warn	Schema names must be unique when converted to class names.
generator-duplicate-tag	error	Tag names must be unique when converted to class, field, or file names.
generator-missing-error-response	hint	Error responses should be defined for all operations to document failure cases.
generator-missing-examples	hint	Examples should be provided where possible to improve API documentation and SDK usability.
generator-pagination	hint	Detect operations that appear to support pagination based on request and response patterns.
generator-path-params	error	Path parameters must be defined on the operation and used in the path template.
generator-retries	hint	Retries should be configured for operations that are safe to retry.
generator-validate-composite-schemas	error	Ensure anyOf/allOf/oneOf don't contain duplicate references or identical inline schemas.
generator-validate-consts-defaults	warn	Validate const and default values match their declared schema type.
generator-validate-content-type	error	Ensure multipart/form-data request schemas are objects as required by OpenAPI.
generator-validate-deprecation	error	Ensure correct usage of x-speakeasy-deprecation-replacement and x-speakeasy-deprecation-message extensions.
generator-validate-enums	error	Validate enums for type generation by checking value types, uniqueness, and x-speakeasy-enums definitions.
generator-validate-extensions	error	Validate x-speakeasy-globals extension usage by enforcing unique parameter names and avoiding collisions with server variables.
generator-validate-parameters	error	Validate parameters are unique once converted to field names and have a non-empty name.
generator-validate-paths	error	Validate paths conform to RFC 3986 and use valid URI template syntax.
generator-validate-requests	error	Validate request body content types are valid MIME types.
generator-validate-responses	error	Validate response status codes and content types are syntactically valid.
generator-validate-security	error	Validate security schemes have supported types, flows, and required fields.
generator-validate-servers	hint	Validate servers, their variables, and the x-speakeasy-server-id extension.
generator-validate-types	error	Ensure schema data types and formats are supported for generation.
oas-schema-check	error	Schemas must use type-appropriate constraints and have valid constraint values.
oas3-example-missing	hint	Schemas, parameters, headers, and media types should include example values.
oas3-no-nullable	warn	The nullable keyword is not supported in OpenAPI 3.1+ and should be replaced with a type array that includes null.
owasp-additional-properties-constrained	hint	Schemas with additionalProperties should define maxProperties to limit object size.
owasp-array-limit	error	Array schemas must specify maxItems to prevent resource exhaustion attacks.
owasp-auth-insecure-schemes	error	Authentication schemes using outdated or insecure methods must be avoided.
owasp-define-error-responses-401	warn	Operations should define a 401 Unauthorized response to handle authentication failures.
owasp-define-error-responses-429	warn	Operations should define a 429 Too Many Requests response to indicate rate limiting.
owasp-define-error-responses-500	warn	Operations should define a 500 Internal Server Error response to handle unexpected failures.
owasp-define-error-validation	warn	Operations should define validation error responses (400, 422, or 4XX).
owasp-integer-format	error	Integer schemas must specify a format of int32 or int64.
owasp-integer-limit	error	Integer schemas must specify minimum and maximum values to prevent unbounded inputs.
owasp-jwt-best-practices	error	Security schemes using OAuth2 or JWT must declare support for RFC8725.
owasp-no-additional-properties	error	Object schemas must not allow arbitrary additional properties.
owasp-no-api-keys-in-url	error	API keys must not be passed via URL parameters as they are logged and cached.
owasp-no-credentials-in-url	error	URL parameters must not contain credentials like API keys, passwords, or secrets.
owasp-no-http-basic	error	Security schemes must not use HTTP Basic authentication without additional security layers.
owasp-no-numeric-ids	error	Resource identifiers must use random values like UUIDs instead of sequential numeric IDs.
owasp-protection-global-safe	hint	Safe operations (GET, HEAD) should be protected by security schemes or explicitly marked as public.
owasp-protection-global-unsafe	error	Unsafe operations (POST, PUT, PATCH, DELETE) must be protected by security schemes.
owasp-protection-global-unsafe-strict	hint	Unsafe operations must be protected by non-empty security schemes without explicit opt-outs.
owasp-rate-limit	error	2XX and 4XX responses must define rate limiting headers.
owasp-rate-limit-retry-after	error	429 Too Many Requests responses must include a Retry-After header.
owasp-security-hosts-https-oas3	error	Server URLs must begin with https://.
owasp-string-limit	error	String schemas must specify maxLength, const, or enum to prevent unbounded data.
owasp-string-restricted	error	String schemas must specify format, const, enum, or pattern to restrict content.
semantic-duplicated-enum	warn	Enum arrays should not contain duplicate values.
semantic-link-operation	error	Link operationId must reference an existing operation in the API specification.
semantic-no-ambiguous-paths	error	Path definitions must be unambiguous and distinguishable from each other.
semantic-no-eval-in-markdown	error	Markdown descriptions must not contain eval() statements.
semantic-no-script-tags-in-markdown	error	Markdown descriptions must not contain tags.
semantic-operation-id-valid-in-url	error	Operation IDs must use URL-friendly characters.
semantic-operation-operation-id	warn	Operations should define an operationId for consistent referencing.
semantic-path-declarations	error	Path parameter declarations must not be empty.
semantic-path-params	error	Path template variables must have corresponding parameter definitions.
semantic-path-query	error	Paths must not include query strings. Query parameters should be defined in the parameters array.
semantic-typed-enum	warn	Enum values must match the specified type.
semantic-unused-component	warn	Components that are declared but never referenced should be removed.
speakeasy-validate-document	error	Document must have a paths or webhooks object with at least one entry.
style-component-description	hint	Reusable components should include descriptions.
style-contact-properties	warn	The contact object should include name, url, and email properties.
style-description-duplication	warn	Description and summary fields should not contain identical text.
style-info-contact	warn	The info section should include a contact object.
style-info-description	warn	The info section should include a description field.
style-info-license	hint	The info section should include a license object.
style-license-url	hint	The license object should include a URL pointing to the full license text.
style-no-ref-siblings	warn	In OpenAPI 3.0.x, a $ref field should not have sibling properties alongside it.
style-no-verbs-in-path	warn	Path segments should not contain HTTP verbs.
style-oas3-api-servers	warn	OpenAPI 3.x specifications should define at least one server with a valid URL.
style-oas3-host-not-example	warn	Server URLs should not point to example.com domains.
style-oas3-host-trailing-slash	warn	Server URLs should not end with a trailing slash.
style-oas3-parameter-description	warn	Parameters should include descriptions that explain their purpose.
style-openapi-tags	warn	The specification should define a non-empty tags array at the root level.
style-operation-description	warn	Operations should include either a description or summary field.
style-operation-error-response	warn	Operations should define at least one 4xx error response.
style-operation-singular-tag	warn	Operations should be associated with only a single tag.
style-operation-success-response	warn	Operations should define at least one 2xx or 3xx response code.
style-operation-tag-defined	warn	Operation tags should be declared in the global tags array.
style-operation-tags	warn	Operations should have at least one tag.
style-path-trailing-slash	warn	Path definitions should not end with a trailing slash.
style-paths-kebab-case	warn	Path segments should use kebab-case for consistency.
style-tag-description	hint	Tags should include descriptions.
style-tags-alphabetical	warn	Tags should be listed in alphabetical order.

Validation errors

In addition to linting rules, the following validation errors may be reported when parsing the OpenAPI document:

Rule ID

validation-required-field

Default Severity

error

Description

Required fields must be present in the document.

validation-type-mismatch

Default Severity

error

Description

Values must match the schema types defined in the specification.

validation-duplicate-key

Default Severity

error

Description

Duplicate keys are not allowed in objects.

validation-invalid-format

Default Severity

error

Description

Values must match the specified format.

validation-empty-value

Default Severity

error

Description

Values must not be empty when the field requires content.

validation-invalid-reference

Default Severity

error

Description

References must resolve to existing components or locations.

validation-invalid-syntax

Default Severity

error

Description

Documents must be valid YAML or JSON.

validation-invalid-schema

Default Severity

error

Description

Schemas must be valid according to the OpenAPI/JSON Schema rules.

validation-invalid-target

Default Severity

error

Description

Validation targets must exist and be valid for the context.

validation-allowed-values

Default Severity

error

Description

Values must be one of the allowed values.

validation-mutually-exclusive-fields

Default Severity

error

Description

Mutually exclusive fields cannot be used together.

validation-operation-not-found

Default Severity

error

Description

Referenced operations must exist in the specification.

validation-operation-id-unique

Default Severity

error

Description

Operation IDs must be unique across the specification.

validation-operation-parameters

Default Severity

error

Description

Operation parameters must be valid and correctly defined.

validation-scheme-not-found

Default Severity

error

Description

Referenced security schemes must be defined.

validation-tag-not-found

Default Severity

error

Description

Operation tags should be defined in the top-level tags array.

validation-supported-version

Default Severity

error

Description

The document must use a supported OpenAPI version.

validation-circular-reference

Default Severity

error

Description

Schemas must not contain circular references that cannot be resolved.

Rule ID	Default Severity	Description
validation-required-field	error	Required fields must be present in the document.
validation-type-mismatch	error	Values must match the schema types defined in the specification.
validation-duplicate-key	error	Duplicate keys are not allowed in objects.
validation-invalid-format	error	Values must match the specified format.
validation-empty-value	error	Values must not be empty when the field requires content.
validation-invalid-reference	error	References must resolve to existing components or locations.
validation-invalid-syntax	error	Documents must be valid YAML or JSON.
validation-invalid-schema	error	Schemas must be valid according to the OpenAPI/JSON Schema rules.
validation-invalid-target	error	Validation targets must exist and be valid for the context.
validation-allowed-values	error	Values must be one of the allowed values.
validation-mutually-exclusive-fields	error	Mutually exclusive fields cannot be used together.
validation-operation-not-found	error	Referenced operations must exist in the specification.
validation-operation-id-unique	error	Operation IDs must be unique across the specification.
validation-operation-parameters	error	Operation parameters must be valid and correctly defined.
validation-scheme-not-found	error	Referenced security schemes must be defined.
validation-tag-not-found	error	Operation tags should be defined in the top-level tags array.
validation-supported-version	error	The document must use a supported OpenAPI version.
validation-circular-reference	error	Schemas must not contain circular references that cannot be resolved.

Available rulesets

The built-in rulesets available to the Speakeasy Linter are listed below and can be composed in custom rulesets.

speakeasy-recommended

The default ruleset. Includes all SDK generation rules, OpenAPI compliance rules, and select style and quality rules. Recommended for ensuring OpenAPI documents meet the Speakeasy quality bar.

Rule ID

generator-duplicate-schema-name

Severity

warn

generator-duplicate-operation-name

Severity

error

generator-duplicate-properties

Severity

error

generator-duplicate-path-params

Severity

warn

generator-duplicate-tag

Severity

error

generator-duplicate-errors

Severity

hint

generator-duplicate-inline-schemas

Severity

hint

generator-duplicate-model-namespace

Severity

warn

generator-validate-types

Severity

error

generator-validate-composite-schemas

Severity

error

generator-validate-consts-defaults

Severity

warn

generator-validate-content-type

Severity

error

generator-validate-enums

Severity

error

generator-validate-extensions

Severity

error

generator-validate-parameters

Severity

error

generator-validate-paths

Severity

error

generator-validate-requests

Severity

error

generator-validate-responses

Severity

error

generator-validate-security

Severity

error

generator-validate-servers

Severity

hint

generator-validate-deprecation

Severity

error

generator-path-params

Severity

error

generator-missing-error-response

Severity

hint

generator-missing-examples

Severity

hint

generator-pagination

Severity

hint

generator-retries

Severity

hint

speakeasy-validate-document

Severity

error

semantic-path-declarations

Severity

error

semantic-path-query

Severity

error

semantic-typed-enum

Severity

warn

semantic-no-eval-in-markdown

Severity

error

semantic-no-script-tags-in-markdown

Severity

error

semantic-unused-component

Severity

warn

semantic-operation-operation-id

Severity

warn

semantic-duplicated-enum

Severity

warn

style-operation-success-response

Severity

warn

style-oas3-host-not-example

Severity

warn

style-operation-tag-defined

Severity

warn

Rule ID	Severity
generator-duplicate-schema-name	warn
generator-duplicate-operation-name	error
generator-duplicate-properties	error
generator-duplicate-path-params	warn
generator-duplicate-tag	error
generator-duplicate-errors	hint
generator-duplicate-inline-schemas	hint
generator-duplicate-model-namespace	warn
generator-validate-types	error
generator-validate-composite-schemas	error
generator-validate-consts-defaults	warn
generator-validate-content-type	error
generator-validate-enums	error
generator-validate-extensions	error
generator-validate-parameters	error
generator-validate-paths	error
generator-validate-requests	error
generator-validate-responses	error
generator-validate-security	error
generator-validate-servers	hint
generator-validate-deprecation	error
generator-path-params	error
generator-missing-error-response	hint
generator-missing-examples	hint
generator-pagination	hint
generator-retries	hint
speakeasy-validate-document	error
semantic-path-declarations	error
semantic-path-query	error
semantic-typed-enum	warn
semantic-no-eval-in-markdown	error
semantic-no-script-tags-in-markdown	error
semantic-unused-component	warn
semantic-operation-operation-id	warn
semantic-duplicated-enum	warn
style-operation-success-response	warn
style-oas3-host-not-example	warn
style-operation-tag-defined	warn

speakeasy-generation

The minimum set of rules required for successful SDK generation. This ruleset is always applied before generation and cannot be overridden or reconfigured when using the generator.

Use this as a base when you want a lean ruleset that only enforces what’s strictly necessary for generation.

Rule ID

generator-duplicate-schema-name

Severity

warn

generator-duplicate-operation-name

Severity

error

generator-duplicate-properties

Severity

error

generator-duplicate-path-params

Severity

warn

generator-duplicate-tag

Severity

error

generator-duplicate-errors

Severity

hint

generator-duplicate-inline-schemas

Severity

hint

generator-duplicate-model-namespace

Severity

warn

generator-validate-types

Severity

error

generator-validate-composite-schemas

Severity

error

generator-validate-consts-defaults

Severity

warn

generator-validate-content-type

Severity

error

generator-validate-enums

Severity

error

generator-validate-extensions

Severity

error

generator-validate-parameters

Severity

error

generator-validate-paths

Severity

error

generator-validate-requests

Severity

error

generator-validate-responses

Severity

error

generator-validate-security

Severity

error

generator-validate-servers

Severity

hint

generator-validate-deprecation

Severity

error

generator-path-params

Severity

error

generator-missing-error-response

Severity

hint

generator-pagination

Severity

hint

generator-retries

Severity

hint

speakeasy-validate-document

Severity

error

semantic-path-declarations

Severity

error

semantic-path-query

Severity

error

semantic-typed-enum

Severity

warn

semantic-no-eval-in-markdown

Severity

error

semantic-no-script-tags-in-markdown

Severity

error

style-operation-success-response

Severity

warn

Rule ID	Severity
generator-duplicate-schema-name	warn
generator-duplicate-operation-name	error
generator-duplicate-properties	error
generator-duplicate-path-params	warn
generator-duplicate-tag	error
generator-duplicate-errors	hint
generator-duplicate-inline-schemas	hint
generator-duplicate-model-namespace	warn
generator-validate-types	error
generator-validate-composite-schemas	error
generator-validate-consts-defaults	warn
generator-validate-content-type	error
generator-validate-enums	error
generator-validate-extensions	error
generator-validate-parameters	error
generator-validate-paths	error
generator-validate-requests	error
generator-validate-responses	error
generator-validate-security	error
generator-validate-servers	hint
generator-validate-deprecation	error
generator-path-params	error
generator-missing-error-response	hint
generator-pagination	hint
generator-retries	hint
speakeasy-validate-document	error
semantic-path-declarations	error
semantic-path-query	error
semantic-typed-enum	warn
semantic-no-eval-in-markdown	error
semantic-no-script-tags-in-markdown	error
style-operation-success-response	warn

speakeasy-openapi

A broader set of rules for general OpenAPI compliance. Builds on speakeasy-generation with additional quality rules like unused component detection, example validation, and link operation validation. Note that Speakeasy-specific rules like generator-validate-enums and generator-validate-extensions are not included in this ruleset.

Rule ID

generator-duplicate-schema-name

Severity

warn

generator-duplicate-operation-name

Severity

error

generator-duplicate-properties

Severity

error

generator-duplicate-path-params

Severity

warn

generator-duplicate-tag

Severity

error

generator-duplicate-errors

Severity

hint

generator-duplicate-inline-schemas

Severity

hint

generator-duplicate-model-namespace

Severity

warn

generator-validate-types

Severity

error

generator-validate-composite-schemas

Severity

error

generator-validate-consts-defaults

Severity

warn

generator-validate-content-type

Severity

error

generator-validate-parameters

Severity

error

generator-validate-paths

Severity

error

generator-validate-requests

Severity

error

generator-validate-responses

Severity

error

generator-validate-security

Severity

error

generator-validate-servers

Severity

hint

generator-validate-deprecation

Severity

error

generator-path-params

Severity

error

generator-missing-error-response

Severity

hint

generator-missing-examples

Severity

hint

generator-pagination

Severity

hint

generator-retries

Severity

hint

speakeasy-validate-document

Severity

error

semantic-path-declarations

Severity

error

semantic-path-query

Severity

error

semantic-typed-enum

Severity

warn

semantic-no-eval-in-markdown

Severity

error

semantic-no-script-tags-in-markdown

Severity

error

semantic-unused-component

Severity

warn

semantic-operation-operation-id

Severity

warn

semantic-duplicated-enum

Severity

warn

semantic-link-operation

Severity

error

style-operation-success-response

Severity

warn

style-oas3-host-not-example

Severity

warn

style-operation-tag-defined

Severity

warn

oas3-example-missing

Severity

hint

Rule ID	Severity
generator-duplicate-schema-name	warn
generator-duplicate-operation-name	error
generator-duplicate-properties	error
generator-duplicate-path-params	warn
generator-duplicate-tag	error
generator-duplicate-errors	hint
generator-duplicate-inline-schemas	hint
generator-duplicate-model-namespace	warn
generator-validate-types	error
generator-validate-composite-schemas	error
generator-validate-consts-defaults	warn
generator-validate-content-type	error
generator-validate-parameters	error
generator-validate-paths	error
generator-validate-requests	error
generator-validate-responses	error
generator-validate-security	error
generator-validate-servers	hint
generator-validate-deprecation	error
generator-path-params	error
generator-missing-error-response	hint
generator-missing-examples	hint
generator-pagination	hint
generator-retries	hint
speakeasy-validate-document	error
semantic-path-declarations	error
semantic-path-query	error
semantic-typed-enum	warn
semantic-no-eval-in-markdown	error
semantic-no-script-tags-in-markdown	error
semantic-unused-component	warn
semantic-operation-operation-id	warn
semantic-duplicated-enum	warn
semantic-link-operation	error
style-operation-success-response	warn
style-oas3-host-not-example	warn
style-operation-tag-defined	warn
oas3-example-missing	hint

openapi-standard

The most comprehensive ruleset. Includes most generator rules plus every built-in rule from the linter library: full semantic, style, and OAS-version-specific rules. Speakeasy-specific rules like generator-validate-enums and generator-validate-extensions are not included. Use this when you want maximum validation coverage.

Rule ID

generator-duplicate-schema-name

Severity

warn

generator-duplicate-operation-name

Severity

error

generator-duplicate-properties

Severity

error

generator-duplicate-path-params

Severity

warn

generator-duplicate-tag

Severity

error

generator-duplicate-errors

Severity

hint

generator-duplicate-inline-schemas

Severity

hint

generator-duplicate-model-namespace

Severity

warn

generator-validate-types

Severity

error

generator-validate-composite-schemas

Severity

error

generator-validate-consts-defaults

Severity

warn

generator-validate-content-type

Severity

error

generator-validate-parameters

Severity

error

generator-validate-paths

Severity

error

generator-validate-requests

Severity

error

generator-validate-responses

Severity

error

generator-validate-security

Severity

error

generator-validate-servers

Severity

hint

generator-validate-deprecation

Severity

error

generator-path-params

Severity

error

generator-missing-error-response

Severity

hint

generator-missing-examples

Severity

hint

generator-pagination

Severity

hint

generator-retries

Severity

hint

speakeasy-validate-document

Severity

error

semantic-duplicated-enum

Severity

warn

semantic-typed-enum

Severity

warn

semantic-unused-component

Severity

warn

semantic-no-ambiguous-paths

Severity

error

semantic-path-declarations

Severity

error

semantic-path-params

Severity

error

semantic-path-query

Severity

error

semantic-link-operation

Severity

error

semantic-operation-id-valid-in-url

Severity

error

semantic-operation-operation-id

Severity

warn

semantic-no-eval-in-markdown

Severity

error

semantic-no-script-tags-in-markdown

Severity

error

oas-schema-check

Severity

error

oas3-example-missing

Severity

hint

oas3-no-nullable

Severity

warn

style-component-description

Severity

hint

style-no-ref-siblings

Severity

warn

style-contact-properties

Severity

warn

style-description-duplication

Severity

warn

style-info-contact

Severity

warn

style-info-description

Severity

warn

style-info-license

Severity

hint

style-license-url

Severity

hint

style-no-verbs-in-path

Severity

warn

style-path-trailing-slash

Severity

warn

style-paths-kebab-case

Severity

warn

style-operation-description

Severity

warn

style-operation-error-response

Severity

warn

style-operation-singular-tag

Severity

warn

style-operation-success-response

Severity

warn

style-operation-tag-defined

Severity

warn

style-operation-tags

Severity

warn

style-openapi-tags

Severity

warn

style-tag-description

Severity

hint

style-tags-alphabetical

Severity

warn

style-oas3-api-servers

Severity

warn

style-oas3-host-not-example

Severity

warn

style-oas3-host-trailing-slash

Severity

warn

style-oas3-parameter-description

Severity

warn

Rule ID	Severity
generator-duplicate-schema-name	warn
generator-duplicate-operation-name	error
generator-duplicate-properties	error
generator-duplicate-path-params	warn
generator-duplicate-tag	error
generator-duplicate-errors	hint
generator-duplicate-inline-schemas	hint
generator-duplicate-model-namespace	warn
generator-validate-types	error
generator-validate-composite-schemas	error
generator-validate-consts-defaults	warn
generator-validate-content-type	error
generator-validate-parameters	error
generator-validate-paths	error
generator-validate-requests	error
generator-validate-responses	error
generator-validate-security	error
generator-validate-servers	hint
generator-validate-deprecation	error
generator-path-params	error
generator-missing-error-response	hint
generator-missing-examples	hint
generator-pagination	hint
generator-retries	hint
speakeasy-validate-document	error
semantic-duplicated-enum	warn
semantic-typed-enum	warn
semantic-unused-component	warn
semantic-no-ambiguous-paths	error
semantic-path-declarations	error
semantic-path-params	error
semantic-path-query	error
semantic-link-operation	error
semantic-operation-id-valid-in-url	error
semantic-operation-operation-id	warn
semantic-no-eval-in-markdown	error
semantic-no-script-tags-in-markdown	error
oas-schema-check	error
oas3-example-missing	hint
oas3-no-nullable	warn
style-component-description	hint
style-no-ref-siblings	warn
style-contact-properties	warn
style-description-duplication	warn
style-info-contact	warn
style-info-description	warn
style-info-license	hint
style-license-url	hint
style-no-verbs-in-path	warn
style-path-trailing-slash	warn
style-paths-kebab-case	warn
style-operation-description	warn
style-operation-error-response	warn
style-operation-singular-tag	warn
style-operation-success-response	warn
style-operation-tag-defined	warn
style-operation-tags	warn
style-openapi-tags	warn
style-tag-description	hint
style-tags-alphabetical	warn
style-oas3-api-servers	warn
style-oas3-host-not-example	warn
style-oas3-host-trailing-slash	warn
style-oas3-parameter-description	warn

owasp

OWASP API Security rules. Covers authentication, rate limiting, input validation, and data exposure. Can be combined with other rulesets:

rulesets:
  secureRuleset:
    rulesets:
      - speakeasy-recommended
      - owasp

Rule ID

owasp-no-numeric-ids

Severity

error

owasp-no-http-basic

Severity

error

owasp-no-api-keys-in-url

Severity

error

owasp-no-credentials-in-url

Severity

error

owasp-auth-insecure-schemes

Severity

error

owasp-jwt-best-practices

Severity

error

owasp-protection-global-unsafe

Severity

error

owasp-protection-global-unsafe-strict

Severity

hint

owasp-protection-global-safe

Severity

hint

owasp-define-error-validation

Severity

warn

owasp-define-error-responses-401

Severity

warn

owasp-define-error-responses-500

Severity

warn

owasp-define-error-responses-429

Severity

warn

owasp-rate-limit

Severity

error

owasp-rate-limit-retry-after

Severity

error

owasp-array-limit

Severity

error

owasp-string-limit

Severity

error

owasp-string-restricted

Severity

error

owasp-integer-format

Severity

error

owasp-integer-limit

Severity

error

owasp-no-additional-properties

Severity

error

owasp-additional-properties-constrained

Severity

hint

owasp-security-hosts-https-oas3

Severity

error

Rule ID	Severity
owasp-no-numeric-ids	error
owasp-no-http-basic	error
owasp-no-api-keys-in-url	error
owasp-no-credentials-in-url	error
owasp-auth-insecure-schemes	error
owasp-jwt-best-practices	error
owasp-protection-global-unsafe	error
owasp-protection-global-unsafe-strict	hint
owasp-protection-global-safe	hint
owasp-define-error-validation	warn
owasp-define-error-responses-401	warn
owasp-define-error-responses-500	warn
owasp-define-error-responses-429	warn
owasp-rate-limit	error
owasp-rate-limit-retry-after	error
owasp-array-limit	error
owasp-string-limit	error
owasp-string-restricted	error
owasp-integer-format	error
owasp-integer-limit	error
owasp-no-additional-properties	error
owasp-additional-properties-constrained	hint
owasp-security-hosts-https-oas3	error

openapi CLI

The openapi CLI is a standalone, open-source tool for working with OpenAPI specifications. It shares the same core linting engine as the Speakeasy Linter but does not include the Speakeasy-specific generation rules (generator-*). It is a good option for teams that want OpenAPI linting without the full Speakeasy generation pipeline.

	Speakeasy CLI	openapi CLI
Generation gating	speakeasy-generation ruleset enforced before SDK generation	No generation gating
Built-in rulesets	speakeasy-recommended, speakeasy-generation, speakeasy-openapi, openapi-standard, owasp	all, recommended, security
Config format	.speakeasy/lint.yaml with lintVersion/rulesets/customRules	lint.yaml with extends/custom_rules

Installation

Homebrew (macOS/Linux):

brew install openapi

Go Install:

go install github.com/speakeasy-api/openapi/cmd/openapi@latest

Script Installation (Linux/macOS):

curl -fsSL https://go.speakeasy.com/openapi.sh | bash

Script Installation (Windows/PowerShell):

iwr -useb https://go.speakeasy.com/openapi.ps1 | iex

Linting usage

# Lint an OpenAPI specification
openapi spec lint api.yaml

# Lint with a specific config file
openapi spec lint --config lint.yaml api.yaml

# Output as JSON
openapi spec lint --format json api.yaml

# Disable specific rules
openapi spec lint --disable semantic-path-params api.yaml

Built-in rulesets

The openapi CLI has its own built-in rulesets:

Ruleset	Description
all	All available rules (default)
recommended	Balanced set: semantic rules + essential style + basic security
security	Comprehensive OWASP security rules

Configuration uses its own format (extends and custom_rules rather than the Speakeasy lintVersion/rulesets/customRules format):

extends: recommended

rules:
  - id: semantic-path-params
    severity: error

custom_rules:
  paths:
    - ./rules/*.ts

By default, the CLI loads config from ~/.openapi/lint.yaml unless --config is provided.

Beyond linting

The openapi CLI also provides additional tools:

• openapi spec validate - Validate against the OpenAPI specification
• openapi spec bundle - Bundle external references into components
• openapi spec inline - Inline all references
• openapi spec upgrade - Upgrade to the latest OpenAPI version
• openapi spec explore - Interactively explore a spec in the terminal
• openapi spec clean - Remove unused components
• openapi spec optimize - Deduplicate inline schemas
• openapi swagger upgrade - Upgrade Swagger 2.0 to OpenAPI 3.0