Trigger.dev API Rules

extends: spectral:oas
rules:

  # All operations must have operationId
  trigger-dev-operation-id-required:
    description: All operations must have a camelCase operationId
    message: "Operation is missing operationId"
    severity: error
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: operationId
      function: truthy

  # operationIds must use camelCase
  trigger-dev-operation-id-camel-case:
    description: Operation IDs must use camelCase
    message: "operationId '{{value}}' must use camelCase"
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  # All operations must have tags
  trigger-dev-operation-tags-required:
    description: All operations must have at least one tag
    message: "Operation '{{operationId}}' must have at least one tag"
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  # Run IDs must be in path params and use run_ prefix pattern
  trigger-dev-run-id-format:
    description: Run ID parameters should document the run_ prefix format
    message: "runId parameter should document the run_ prefix in description"
    severity: hint
    given: "$.paths[*][*].parameters[?(@.name == 'runId')]"
    then:
      field: description
      function: truthy

  # All path parameters must be required
  trigger-dev-path-params-required:
    description: Path parameters must be marked as required
    message: "Path parameter must have required: true"
    severity: error
    given: "$.paths[*][*].parameters[?(@.in == 'path')]"
    then:
      field: required
      function: truthy

  # POST endpoints that create resources must define request body
  trigger-dev-post-request-body:
    description: POST operations that create resources should have a request body
    message: "POST operation '{{operationId}}' should define a requestBody"
    severity: warn
    given: "$.paths[*].post"
    then:
      field: requestBody
      function: truthy

  # Responses must include 200 status code
  trigger-dev-response-200-required:
    description: All operations must define a 200 response
    message: "Operation is missing a 200 success response"
    severity: error
    given: "$.paths[*][get,post,put,delete,patch].responses"
    then:
      field: "200"
      function: truthy

  # Responses should include 401 status code
  trigger-dev-response-401-required:
    description: Operations should document 401 unauthorized response
    message: "Operation should document 401 response for auth failures"
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch].responses"
    then:
      field: "401"
      function: truthy

  # API paths must use versioned prefix
  trigger-dev-versioned-path:
    description: All API paths must be versioned
    message: "Path '{{value}}' must start with /api/v1/ or /api/v3/"
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^/api/v[13]/"

  # Bearer auth scheme must be used
  trigger-dev-bearer-auth:
    description: Security scheme must use bearer authentication
    message: "Security scheme must use type: http with scheme: bearer"
    severity: error
    given: "$.components.securitySchemes[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            type:
              const: http
            scheme:
              const: bearer

  # RunStatus enum must be defined consistently
  trigger-dev-run-status-enum:
    description: RunStatus must reference the canonical enum
    message: "Status properties should reference RunStatus schema or define the full enum"
    severity: hint
    given: "$.components.schemas.Run.properties.status"
    then:
      function: truthy