Validation Rules

Comprehensive validation checks for OpenAPI 3.0, 3.1, and 3.2 specifications

error

Critical Errors

30+

Must be fixed

warning

Warnings

20+

Should be addressed

lightbulb

Best Practices

25+

Recommendations

error

Critical Errors

File & Structure

  • • YAML/JSON parsing
  • • OpenAPI version check
  • • Required root fields
  • • Info section validation

Schema Validations

  • • Schema type validation
  • • Circular reference detection
  • • Reference resolution
  • • ReadOnly/WriteOnly conflicts

Example Validations

  • • Example vs schema matching
  • • Format checking (int32/int64)
  • • Parameter examples
  • • Request/Response examples

Parameters & Operations

  • • Parameter structure
  • • Path parameter matching
  • • Unique operation IDs
  • • HTTP method consistency

Security

  • • Security scheme existence
  • • OAuth2 scope validation
  • • Security requirement types

Version Consistency

  • • Version mismatch detection
  • • 3.1 features in 3.0/3.2
  • • 3.0 features in 3.1+
warning

Warnings

Documentation Quality

  • • Missing operation IDs
  • • Missing descriptions
  • • Missing tags
  • • Undefined tags
  • • Missing contact info

Response Standards

  • • Missing examples
  • • Missing default responses
  • • Non-standard status codes
lightbulb

Best Practices

(Private APIs only)

Security

  • • String maxLength constraints
  • • Array maxItems constraints
  • • Number min/max values
  • • Rate limiting headers

Design

  • • Consistent naming conventions
  • • Singular vs plural paths
  • • POST returns 201
  • • Date/Email/UUID formats

Developer Experience

  • • Schema descriptions
  • • Parameter descriptions
  • • License information
  • • Terms of service
  • • API versioning

Request/Response

  • • Timestamps (createdAt/updatedAt)
  • • Idempotency keys
  • • Field selection
  • • Bulk operations
  • • Pagination support
history

Version-Specific Validations

OpenAPI 3.0

  • • nullable property
  • • Boolean exclusiveMinimum/Maximum
  • • No webhooks support

OpenAPI 3.1

  • • JSON Schema 2020-12
  • • webhooks support
  • • const keyword
  • • type arrays
  • • Numeric exclusiveMinimum/Maximum

OpenAPI 3.2

  • • QUERY HTTP method
  • • OAuth2 Device Flow
  • • Hierarchical tags
  • • Optional response descriptions