Convex API Rules

extends:
  - "spectral:oas"
documentationUrl: https://docs.convex.dev/management-api
rules:
  convex-mgmt-info-title:
    description: Management API OpenAPI info.title must reference Convex Management
    severity: error
    given: "$.info.title"
    then:
      function: pattern
      functionOptions:
        match: "(?i)Convex\\s+Management"
  convex-mgmt-server-defined:
    description: At least one server URL must be defined
    severity: error
    given: "$.servers"
    then:
      function: length
      functionOptions:
        min: 1
  convex-mgmt-server-host:
    description: Management API server URL must point to api.convex.dev
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "https://api\\.convex\\.dev/v1"
  convex-mgmt-bearer-auth:
    description: Management API must declare bearer authentication
    severity: error
    given: "$.components.securitySchemes"
    then:
      function: defined
  convex-mgmt-tag-required:
    description: Tags must declare Projects, Deployments, Teams, AccessTokens, DeployKeys, CustomDomains, or EnvironmentVariables scope
    severity: warn
    given: "$.tags[*].name"
    then:
      function: enumeration
      functionOptions:
        values:
          - AccessTokens
          - CustomDomains
          - DeployKeys
          - Deployments
          - EnvironmentVariables
          - Projects
          - Teams
  convex-mgmt-operation-id-camelcase:
    description: Every operation must define an operationId in camelCase or snake_case
    severity: warn
    given: "$.paths.*[get,put,post,delete,patch].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-zA-Z][a-zA-Z0-9_]+$"
  convex-mgmt-paths-prefix:
    description: Management API paths must live under /teams, /projects, /deployments, or /token
    severity: warn
    given: "$.paths"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^/(teams|projects|deployments|token|list_personal_access_tokens|create_personal_access_token|delete_personal_access_token)"