OpenAPI Document Validation

You can use the Speakeasy CLI (opens in a new tab) to validate an OpenAPI document to ensure it is compatible with the Speakeasy SDK Generator and ready to use.

The Speakeasy validator will ensure the document:

Is a valid OpenAPI 3.x document.
Defines operations and schemas in a way that is compatible with the Speakeasy SDK generator.
Uses Speakeasy extensions in a valid manner.

Validation Ruleset

Rule ID	Default Severity	Description
validate-document	error	Document must have a paths or webhooks object.
path-not-include-query	error	Path must not include query string.
duplicate-operation-id	error	Operation IDs (including inferred) must be unique across all operations and tags, and overridden method names must be unique within tags when converted to method names.
validate-parameters	error	Validate parameters are unique and have a non-empty `name` property when converted to field names.
operation-operationId	warn	Every operation must contain an `operationId`.
validate-anyof	warn	`anyOf` should only contain types that are compatible with each other.
operation-tag-defined	warn	Operation tags must be defined in global tags.
validate-enums	error	Validate enums are valid for type generation.
duplicate-tag	error	Tag names must be unique when converted to class, field, or file names.
oas3-operation-security-defined	error	`security` values must match a scheme defined in `components.securitySchemes`.
typed-enum	warn	Enum values must respect the specified type.
no-script-tags-in-markdown	error	Markdown descriptions must not have `<script>` tags.
validate-paths	error	Validate paths conform to RFC 3986.
validate-extensions	error	Validate `x-speakeasy-globals` extension use.
validate-deprecation	error	Ensure correct use of `x-speakeasy-deprecation-replacement`.
no-eval-in-markdown	error	Markdown descriptions must not have `eval()` statements.
operation-success-response	warn	Operation must have at least one `2xx` or `3xx` response.
oas3-unused-component	warn	Check for unused components and bad references.
duplicate-properties	error	Property names must be unique and not empty within a operation when converted to field names.
path-params	error	Path parameters must be defined and valid.
duplicated-entry-in-enum	warn	Enum values must not have duplicate entry.
validate-json-schema	error	Validate OpenAPI document against JSON schema.
validate-requests	error	Validate request content types are valid mime types.
path-declarations-must-exist	error	Path parameter declarations must not be empty (eg. `/api/{}` is invalid).
oas3-host-not-example.com	warn	Server URL should not point at example.com.
validate-schemas	error	Validate schemas are correct for type generation.
validate-servers	error	Validate servers, variables, and `x-speakeasy-server-id` extension.
validate-security	error	Validate security schemes are correct.
operation-operationId-unique	error	Every operation must have unique `operationId`.
duplicate-schema-name	error	Schema names must be unique when converted to class names.
validate-responses	error	Validate response content types are valid mime types.