Vessel API Rules

# Vessel API governance ruleset (Spectral)
#
# generated: '2026-08-13'
# method: derived
# source: openapi/ (20 OpenAPI 3.1.0 definitions harvested from
#         https://github.com/vesselapi/all-api-docs on 2026-08-13)
#
# These rules encode the conventions Vessel's own published contracts follow, plus the
# gaps those contracts have. Running this ruleset against openapi/ is expected to FAIL
# on the error-response and securityScheme rules — that is the finding, not a bug in the
# ruleset. See errors/vessel-error-codes.yml and conformance/vessel-conformance.yml.
extends: spectral:oas
rules:
  vessel-operation-ids-kebab-case:
    description: >-
      Operation IDs use kebab-case across every published Vessel definition
      (list-contacts, batch-read-deals, get-one-session-token).
    message: "Operation ID '{{value}}' must be kebab-case"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"

  vessel-operation-id-required:
    description: Every operation must carry an operationId so clients and agents can bind to it.
    message: Operation is missing an operationId
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  vessel-operation-summary-required:
    description: Every operation must carry a human-readable summary.
    message: Operation is missing a summary
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  vessel-error-responses-declared:
    description: >-
      Vessel documents 400, 401, 409 and a 5xx class in prose but declares none of them in any
      contract — all 375 published operations declare only a 200. A client generated from these
      specs has no error type at all.
    message: "Operation declares no 4xx or 5xx response"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: ['400']
            - required: ['401']
            - required: ['409']
            - required: ['500']

  vessel-security-scheme-defined:
    description: >-
      The v2 specs declare a top-level security requirement referencing VesselAPIToken but never
      define it under components.securitySchemes. Only the two v1 specs define the scheme.
    message: components.securitySchemes must define every scheme referenced by security[]
    severity: error
    given: "$"
    then:
      field: components.securitySchemes
      function: truthy

  vessel-operations-tagged:
    description: >-
      No published Vessel definition declares tags, so nothing can group these operations by
      resource. overlays/ adds them without mutating the original.
    message: Operation is not tagged
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  vessel-json-only:
    description: Vessel is JSON over HTTPS; no other media type is used.
    message: "Only application/json is expected on Vessel operations"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses[*].content"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - application/json

  vessel-https-servers:
    description: All requests to Vessel must be made over https.
    message: "Server URL must use https"
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"