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 IDDefault SeverityDescription
validate-documenterrorDocument must have a paths or webhooks object.
path-not-include-queryerrorPath must not include query string.
duplicate-operation-iderrorOperation 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-parameterserrorValidate parameters are unique and have a non-empty name property when converted to field names.
operation-operationIdwarnEvery operation must contain an operationId.
validate-anyofwarnanyOf should only contain types that are compatible with each other.
operation-tag-definedwarnOperation tags must be defined in global tags.
validate-enumserrorValidate enums are valid for type generation.
duplicate-tagerrorTag names must be unique when converted to class, field, or file names.
oas3-operation-security-definederrorsecurity values must match a scheme defined in components.securitySchemes.
typed-enumwarnEnum values must respect the specified type.
no-script-tags-in-markdownerrorMarkdown descriptions must not have <script> tags.
validate-pathserrorValidate paths conform to RFC 3986.
validate-extensionserrorValidate x-speakeasy-globals extension use.
validate-deprecationerrorEnsure correct use of x-speakeasy-deprecation-replacement.
no-eval-in-markdownerrorMarkdown descriptions must not have eval() statements.
operation-success-responsewarnOperation must have at least one 2xx or 3xx response.
oas3-unused-componentwarnCheck for unused components and bad references.
duplicate-propertieserrorProperty names must be unique and not empty within a operation when converted to field names.
path-paramserrorPath parameters must be defined and valid.
duplicated-entry-in-enumwarnEnum values must not have duplicate entry.
validate-json-schemaerrorValidate OpenAPI document against JSON schema.
validate-requestserrorValidate request content types are valid mime types.
path-declarations-must-existerrorPath parameter declarations must not be empty (eg. /api/{} is invalid).
oas3-host-not-example.comwarnServer URL should not point at
validate-schemaserrorValidate schemas are correct for type generation.
validate-serverserrorValidate servers, variables, and x-speakeasy-server-id extension.
validate-securityerrorValidate security schemes are correct.
operation-operationId-uniqueerrorEvery operation must have unique operationId.
duplicate-schema-nameerrorSchema names must be unique when converted to class names.
validate-responseserrorValidate response content types are valid mime types.