United Airlines API Rules

extends: spectral:oas
rules:

  # Require operationId on every operation
  operation-operationId:
    description: Every operation must have a unique operationId.
    severity: error
    given: "$.paths.*[get,post,put,patch,delete,options,head]"
    then:
      field: operationId
      function: truthy

  # Require operation summary in Title Case
  operation-summary-title-case:
    description: Operation summaries must use Title Case.
    message: "Summary '{{value}}' should be in Title Case."
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]*$"

  # Require tags on every operation
  operation-tags:
    description: Every operation must include at least one tag.
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  # Require description on every operation
  operation-description:
    description: Every operation must have a description.
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  # Paths must use kebab-case
  path-kebab-case:
    description: Path segments must use kebab-case (lowercase with hyphens).
    message: "Path '{{value}}' must use kebab-case."
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}-]+)+$"

  # Paths must not have a trailing slash
  path-no-trailing-slash:
    description: Paths must not end with a trailing slash.
    severity: error
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        notMatch: ".+/$"

  # All response codes must have descriptions
  response-descriptions:
    description: All response status codes must include a description.
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete].responses.*"
    then:
      field: description
      function: truthy

  # Require security on every operation
  operation-security-defined:
    description: Every operation must define a security requirement.
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete]"
    then:
      field: security
      function: truthy

  # POST/PUT/PATCH must have a requestBody
  operation-request-body-required:
    description: POST, PUT, and PATCH operations should have a requestBody.
    severity: warn
    given: "$.paths.*[post,put,patch]"
    then:
      field: requestBody
      function: truthy

  # API must have contact information
  info-contact:
    description: API info must include contact information.
    severity: warn
    given: "$.info"
    then:
      field: contact
      function: truthy

  # All schemas must have a description
  schema-description:
    description: All named schemas should have a description.
    severity: info
    given: "$.components.schemas.*"
    then:
      field: description
      function: truthy

  # Require 2xx success response for all operations
  operation-success-response:
    description: Operations must define at least one 2xx success response.
    severity: error
    given: "$.paths.*[get,post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          minProperties: 1

  # Parameters must have descriptions
  parameter-description:
    description: All parameters must have a description.
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete].parameters.*"
    then:
      field: description
      function: truthy

  # United Airlines: Flight-domain-specific rule — flight numbers must follow UA format
  ua-flight-number-format:
    description: Flight number examples should follow United Airlines UA format (e.g., UA123).
    message: "Flight number example '{{value}}' should follow UA### format."
    severity: info
    given: "$.components.schemas.FlightSegment.properties.flightNumber.example"
    then:
      function: pattern
      functionOptions:
        match: "^UA\\d+$"

  # Servers must be defined
  servers-defined:
    description: API must define at least one server.
    severity: error
    given: "$"
    then:
      field: servers
      function: truthy