Scout RFP API Rules

extends:
  - spectral:oas

rules:
  # Scout RFP API uses JSON API specification format
  scout-rfp-json-api-data-wrapper:
    description: Responses should use JSON API data wrapper pattern
    message: "Response schema should include 'data' property following JSON API spec"
    severity: warn
    given: "$.paths[*][*].responses[?(@property >= '200' && @property < '300')].content.application/json.schema"
    then:
      field: properties.data
      function: truthy

  scout-rfp-pagination-meta:
    description: List endpoints should include pagination metadata
    message: "List response schemas should include 'meta' property for pagination"
    severity: warn
    given: "$.paths[*].get.responses[200].content.application/json.schema"
    then:
      field: properties.meta
      function: truthy

  scout-rfp-api-key-auth:
    description: All operations must require API key authentication headers
    message: "Operations should require X-Api-Key security scheme"
    severity: error
    given: "$.paths[*][*]"
    then:
      field: security
      function: truthy

  scout-rfp-operation-ids:
    description: All operations must have operationId
    message: "Every operation must have a unique operationId"
    severity: error
    given: "$.paths[*][*]"
    then:
      field: operationId
      function: truthy

  scout-rfp-versioned-paths:
    description: API paths should include version prefix
    message: "API paths should start with /services/ or include version"
    severity: info
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^/(services|v[0-9]+)/"

  scout-rfp-camel-case-operation-ids:
    description: Operation IDs should use camelCase
    message: "OperationId '{{value}}' should use camelCase naming"
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  scout-rfp-tags-required:
    description: All operations must have at least one tag
    message: "Operations must be tagged for proper grouping"
    severity: warn
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy

  scout-rfp-pagination-parameters:
    description: GET list endpoints should support pagination parameters
    message: "List endpoints should support page[size] and page parameters"
    severity: info
    given: "$.paths[*].get"
    then:
      field: parameters
      function: truthy

  scout-rfp-rate-limit-documentation:
    description: Document rate limiting constraints
    message: "API info should document the 5 requests/second rate limit"
    severity: info
    given: "$.info"
    then:
      field: description
      function: truthy

  scout-rfp-resource-id-path-params:
    description: Path parameters for resources should be named 'id'
    message: "Resource path parameters should follow {id} or {resource_id} naming"
    severity: warn
    given: "$.paths[*][*].parameters[?(@.in === 'path')]"
    then:
      field: name
      function: pattern
      functionOptions:
        match: "^[a-z_]+id$|^id$"