Speakeasy API Rules

extends: spectral:oas
rules:
  # All paths must start with /v1/
  speakeasy-path-versioned:
    description: All API paths must be prefixed with /v1/
    severity: error
    given: "$.paths.*~"
    then:
      function: pattern
      functionOptions:
        match: "^/v1/"

  # Operation IDs must be camelCase
  speakeasy-operation-id-camel-case:
    description: Operation IDs must use camelCase
    severity: warn
    given: "$.paths.*.*.operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  # All operations must have an operationId
  speakeasy-operation-id-required:
    description: All operations must define an operationId
    severity: error
    given: "$.paths.*[get,post,put,patch,delete]"
    then:
      field: operationId
      function: defined

  # All operations must have at least one tag
  speakeasy-operation-tags-required:
    description: All operations must have at least one tag for grouping
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete]"
    then:
      field: tags
      function: defined

  # All operations must have a summary
  speakeasy-operation-summary-required:
    description: All operations must have a summary in Title Case
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete]"
    then:
      field: summary
      function: defined

  # Responses must define 4XX error handling
  speakeasy-error-responses-required:
    description: Operations should define 4XX error responses
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
            - required: ["4XX"]
            - required: ["400"]
            - required: ["401"]
            - required: ["403"]
            - required: ["404"]

  # Resource IDs should use camelCase path parameters
  speakeasy-path-param-camel-case:
    description: Path parameters should use camelCase naming (e.g., workspaceId not workspace_id)
    severity: info
    given: "$.paths.*.*.parameters[?(@.in == 'path')].name"
    then:
      function: pattern
      functionOptions:
        match: "^[a-zA-Z][a-zA-Z0-9]*([A-Z][a-zA-Z0-9]*)*$"

  # Security must be defined at operation or global level
  speakeasy-security-defined:
    description: API operations should define security requirements
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete]"
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
            - required: ["security"]
            - properties:
                security:
                  type: array

  # Workspace-scoped paths should consistently reference workspace_id
  speakeasy-workspace-paths-consistent:
    description: Workspace-scoped paths should use the /workspace/{workspace_id}/ prefix
    severity: info
    given: "$.paths.*~"
    then:
      function: pattern
      functionOptions:
        match: "^/v1/(workspace/\\{workspace_id\\}|workspaces|workspace$|workspace\\?|auth|user|organization|organizations|publishing-tokens|reports|suggest|schema_store|short_urls|artifacts|oci|subscriptions|github|code_sample)"