ruleset.yaml

# Centralized Spectral ruleset for Elastic OpenAPI specs.
# Consumers do not author rules; changes land here via PR (elastic/docs-eng-team#639).
#
# extends `spectral:oas` fully OFF, then re-enables specific rules by name.
# This is deliberate: it means new rules that Spectral's built-in ruleset adds
# in a future release never silently start applying to consumers.
#
# Two tiers:
#   - error: parses, $refs resolve, conforms to the OAS schema for its version.
#     (invalid-ref and parser failures are resolver-level and always error,
#     regardless of what's enabled below.)
#   - warn: authoring conventions. Kept at warn so existing specs pass
#     as-is; flip a consumer's `fail-on-warn` input to `true` to enforce.
extends: [["spectral:oas", off]]

rules:
  # ---- Core tier (error) ----
  oas2-schema: error
  oas3-schema: error # covers both 3.0.x and 3.1.0; Spectral dispatches on detected version

  # ---- Convention tier (warn) — built-in spectral:oas rules, re-enabled ----
  operation-operationId: warn
  info-description: warn
  oas3-api-servers: warn # 3.x only; Swagger 2.0 has no `servers` equivalent
  operation-description: warn
  operation-tags: warn
  operation-tag-defined: warn

  # ---- Convention tier (warn) — custom Elastic rules ----
  #
  # None enabled yet. The rules below are examples sketched from the
  # conventions analysis in elastic/docs-eng-team#639, but those conventions
  # (operationId casing, security scheme naming, the x-state shape) aren't
  # agreed yet across consumer teams. Uncomment and land via PR once a
  # convention is actually adopted — don't enforce contested decisions here
  # ahead of agreement.
  #
  # elastic-info-version-non-empty:
  #   description: 'info.version must be set'
  #   given: '$.info.version'
  #   severity: warn
  #   then:
  #     function: truthy
  #
  # elastic-operation-summary:
  #   description: 'Every operation should have a summary'
  #   given: '$.paths[*][get,put,post,delete,options,head,patch,trace]'
  #   severity: warn
  #   then:
  #     field: summary
  #     function: truthy
  #
  # elastic-operation-id-camel-case:
  #   description: 'operationId should be camelCase'
  #   given: '$.paths[*][get,put,post,delete,options,head,patch,trace].operationId'
  #   severity: warn
  #   then:
  #     function: casing
  #     functionOptions:
  #       type: camel
  #
  # elastic-security-scheme-names:
  #   description: 'Security scheme keys should be apiKeyAuth, basicAuth, or bearerAuth'
  #   given:
  #     - '$.securityDefinitions[*]~'
  #     - '$.components.securitySchemes[*]~'
  #   severity: warn
  #   then:
  #     function: enumeration
  #     functionOptions:
  #       values:
  #         - apiKeyAuth
  #         - basicAuth
  #         - bearerAuth
  #
  # elastic-x-state-shape:
  #   description: 'x-state should be a structured lifecycle object, not a free-form string'
  #   given: '$..x-state'
  #   severity: warn
  #   then:
  #     function: schema
  #     functionOptions:
  #       schema:
  #         type: object
  #         required: [lifecycle]
  #         properties:
  #           lifecycle:
  #             enum: [ga, beta, experimental, technical-preview]
  #           since:
  #             type: string
  #         additionalProperties: false