@useoptic/standard-rulesets

Standard rulesets

Optic includes the following rulesets:

• breaking changes (enforces breaking changes)
• naming (enforces casing conventions)
• examples (requires examples to be provided and for them to match the schemas)
• spectral oas (run spectral rules with Optic lifecycles)

Run these locally using optic cli or in optic cloud which integrates with github and gitlab.

Breaking Changes Rules

Turn on breaking changes by adding the breaking-changes into your optic.dev.yml file

ruleset:
  - breaking-changes

You can also exclude certain operations in breaking changes by exempting operations with a certain extension. E.g.

ruleset:
  - breaking-changes:
      exclude_operations_with_extension: x-draft # if an operation has the extension x-draft, optic will not check for breaking changes

paths:
  /api/users:
    get:
      x-draft: true # this endpoint will not be checked for breaking changes
      ...

The rules that are enforced are:

• prevent operation removal
• prevent adding new required query, cookie or header parameters
• prevent changing query, cookie, or header parameter optional -> required
• prevent changing query, cookie, path or header parameter types
• prevent adding required request body property
• prevent changing request body property optional -> required
• prevent changing request body property types
• prevent removing a response body property
• prevent changing response body property required -> optional
• prevent changing response body property types
• prevent removing a response status code

Naming Changes

Turn on naming enforcement to ensure your OpenAPI spec is has consistent naming conventions

The configuration options are:

ruleset:
  - naming:
      required_on: always # also available are 'added' or addedOrChanged
      requestHeaders: camelCase #also available are Capital-Param-Case, param-case PascalCase and snake_case
      queryParameters: camelCase
      responseHeaders: camelCase
      cookieParameters: camelCase
      properties: camelCase
      pathComponents: camelCase

Require Examples Ruleset

Require an example to be present in your schemas, and ensure that they match the schema object

The configuration options are:

ruleset:
  - examples:
      required_on: always # also available are 'added' or addedOrChanged
      require_request_examples: true # default is false
      require_response_examples: true # default is false
      require_parameter_examples: true # default is false