Comeet API Rules

extends:
  - spectral:oas

# Spectral linting rules for the Comeet (Spark Hire Recruit) Careers API.
# Tuned to comeet.co careers-api conventions: tokenized GETs over HTTPS,
# company UID path parameters, and embeddable widget data shapes.
rules:
  comeet-info-contact:
    description: API info must include a contact block.
    severity: error
    given: "$.info"
    then:
      field: contact
      function: truthy

  comeet-server-https:
    description: Server URLs must use HTTPS.
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  comeet-server-host:
    description: Public server URL should point to comeet.co.
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "comeet.co"

  comeet-careers-base-path:
    description: Careers API server URL should include /careers-api/2.0.
    severity: info
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "/careers-api/"

  comeet-operation-id:
    description: Every operation must declare a unique operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  comeet-operation-tags:
    description: Operations must declare at least one tag.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  comeet-token-query-param:
    description: Read endpoints must accept the public company `token` query parameter.
    severity: warn
    given: "$.paths[*].get.parameters"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          contains:
            type: object
            properties:
              name:
                const: token
              in:
                const: query

  comeet-company-uid-path:
    description: Company-scoped endpoints must use a {company_uid} path parameter.
    severity: warn
    given: "$.paths[?(@property.indexOf('company') > -1)]"
    then:
      function: pattern
      functionOptions:
        match: "{company_uid}"