Mixedbread API Rules

extends:
  - spectral:oas
overrides: []
rules:
  # Servers
  mxbai-server-required:
    description: Every Mixedbread spec must declare https://api.mixedbread.com as the production server.
    severity: error
    given: $.servers
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1
          contains:
            type: object
            properties:
              url:
                const: https://api.mixedbread.com

  # Paths
  mxbai-paths-must-be-versioned:
    description: All operational paths must live under /v1.
    severity: error
    given: $.paths[?(@property != "/")]~
    then:
      function: pattern
      functionOptions:
        match: ^/v1(/|$)

  # snake_case path segments (matches mxbai style: /question-answering, /list-chunks,
  # /metadata-facets, /data_sources)
  mxbai-paths-lowercase:
    description: Path segments must be lowercase. Word separators may be hyphens or underscores.
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: ^[a-z0-9/_{}\-]+$

  # Operation summaries must be present and Title Case
  mxbai-operation-summary-required:
    description: Every operation must have a summary.
    severity: error
    given: $.paths[*][get,post,put,patch,delete].summary
    then:
      function: truthy

  mxbai-operation-id-required:
    description: Every operation must have an operationId.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  # Authentication
  mxbai-bearer-auth-defined:
    description: A bearer-token security scheme should be declared (Mixedbread uses Bearer API keys).
    severity: warn
    given: $.components.securitySchemes
    then:
      function: truthy