Sound Transit API Rules

extends: spectral:oas
rules:
  # Sound Transit OneBusAway API always requires API key query parameter
  sound-transit-api-key-required:
    description: All Sound Transit API operations require the 'key' query parameter
    severity: error
    given: "$.paths[*][get].parameters[?(@.name == 'key')]"
    then:
      field: required
      function: truthy

  # All paths use .json suffix - enforce this pattern
  sound-transit-json-suffix:
    description: Sound Transit OneBusAway API paths use .json suffix
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: ".*\\.json$"

  # All operations must have summaries in Title Case
  sound-transit-operation-summary-title-case:
    description: Operation summaries must use Title Case
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*([ ][A-Z][a-zA-Z0-9]*)*$"

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

  # operationId must use camelCase
  sound-transit-operation-id-camel-case:
    description: OperationId must use camelCase convention
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  # All operations must have tags
  sound-transit-operation-has-tags:
    description: All operations must have at least one tag
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  # 401 response for missing API key
  sound-transit-401-response:
    description: Operations must document 401 Unauthorized for invalid API key
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: "401"
      function: defined

  # Response schemas must be defined
  sound-transit-response-schema-defined:
    description: Successful responses must have a schema
    severity: warn
    given: "$.paths[*][get].responses['200'].content['application/json']"
    then:
      field: schema
      function: defined

  # All tags must be Title Case
  sound-transit-tags-title-case:
    description: All tags in the spec must use Title Case
    severity: warn
    given: "$.tags[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*([ ][A-Z][a-zA-Z0-9]*)*$"

  # BaseResponse structure - all responses inherit from BaseResponse
  sound-transit-base-response-structure:
    description: All response schemas should reference BaseResponse or include code and currentTime fields
    severity: info
    given: "$.components.schemas.BaseResponse"
    then:
      field: properties
      function: truthy