Booking Holdings API Rules

# Spectral ruleset for the Booking.com Demand API (Booking Holdings)
# Generated by the API Evangelist generate-spectral-rules skill.
# Enforces the conventions observed in openapi/booking-com-demand-api.yaml:
#   - OpenAPI 3.1.0, POST-only RPC-style endpoints
#   - kebab-case path segments under a /3.1 version host
#   - snake_case schema/property and parameter naming
#   - Bearer (Affiliate ID + token) authentication
#   - Title Case tags, "Booking.com " summary prefix
extends: []
rules:

  # ── INFO / METADATA ──────────────────────────────────────────────
  info-title-required:
    description: API must declare an info.title.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy
  info-title-booking-prefix:
    description: Title should identify Booking.com.
    severity: warn
    given: $.info.title
    then:
      function: pattern
      functionOptions:
        match: "Booking.com"
  info-description-required:
    description: API must have a description (summary acceptable for 3.1).
    severity: warn
    given: $.info
    then:
      field: summary
      function: truthy
  info-version-required:
    description: API must declare a version.
    severity: error
    given: $.info
    then:
      field: version
      function: truthy

  # ── OPENAPI VERSION ──────────────────────────────────────────────
  openapi-version-3-1:
    description: Booking.com Demand API specs are OpenAPI 3.1.0.
    severity: warn
    given: $.openapi
    then:
      function: pattern
      functionOptions:
        match: "^3\\.1\\."

  # ── SERVERS ──────────────────────────────────────────────────────
  servers-defined:
    description: At least one server must be defined.
    severity: error
    given: $.servers
    then:
      function: length
      functionOptions:
        min: 1
  server-https-only:
    description: All server URLs must use HTTPS.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"
  server-description-required:
    description: Each server should describe its environment (e.g. Production, Sandbox).
    severity: warn
    given: $.servers[*]
    then:
      field: description
      function: truthy

  # ── PATHS — NAMING CONVENTIONS ───────────────────────────────────
  path-kebab-case:
    description: Path segments must be lowercase kebab-case.
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(/([a-z0-9]+(-[a-z0-9]+)*|\\{[a-zA-Z0-9_]+\\}))+$"
  path-no-trailing-slash:
    description: Paths must not end with a trailing slash.
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: ".+/$"
  path-no-query-string:
    description: Paths must not contain query strings.
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: "\\?"

  # ── OPERATIONS ───────────────────────────────────────────────────
  operation-post-only:
    description: Demand API endpoints are RPC-style POST operations; avoid GET/PUT/PATCH/DELETE.
    severity: info
    given: $.paths[*]
    then:
      field: post
      function: truthy
  operation-summary-required:
    description: Every operation must have a summary.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: summary
      function: truthy
  operation-summary-booking-prefix:
    description: Operation summaries should be prefixed with "Booking.com ".
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].summary
    then:
      function: pattern
      functionOptions:
        match: "^Booking\\.com "
  operation-operationid-required:
    description: Every operation must have an operationId.
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
  operation-operationid-camelcase:
    description: operationId must be camelCase.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].operationId
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"
  operation-tags-required:
    description: Every operation must declare at least one tag.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: length
      functionOptions:
        min: 1
  operation-microcks-extension:
    description: Operations should carry an x-microcks-operation extension for mock compatibility.
    severity: info
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: x-microcks-operation
      function: truthy

  # ── TAGS ─────────────────────────────────────────────────────────
  tag-title-case:
    description: Tag names should be Title Case (allowing a Common/Subgroup form).
    severity: info
    given: $.paths[*][get,post,put,patch,delete].tags[*]
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][A-Za-z]+(/[a-z]+)?$"

  # ── PARAMETERS ───────────────────────────────────────────────────
  parameter-description-required:
    description: Parameters must have a description.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].parameters[*]
    then:
      field: description
      function: truthy
  parameter-snake-case:
    description: Parameter names should be snake_case.
    severity: info
    given: $.paths[*][get,post,put,patch,delete].parameters[*].name
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*$"

  # ── REQUEST BODIES ───────────────────────────────────────────────
  request-body-json:
    description: Request bodies should accept application/json.
    severity: warn
    given: $.paths[*][post,put,patch].requestBody.content
    then:
      field: application/json
      function: truthy

  # ── RESPONSES ────────────────────────────────────────────────────
  response-2xx-required:
    description: Every operation must define a successful (2xx) response.
    severity: error
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            "^2[0-9][0-9]$": true
          minProperties: 1
  response-json-content:
    description: 200 responses should return application/json.
    severity: info
    given: $.paths[*][get,post,put,patch,delete].responses.200.content
    then:
      field: application/json
      function: truthy

  # ── SCHEMAS — PROPERTY NAMING ────────────────────────────────────
  schema-property-snake-case:
    description: Schema property names should be snake_case (Demand API convention).
    severity: info
    given: $..properties.*~
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*$"

  # ── SECURITY ─────────────────────────────────────────────────────
  global-security-defined:
    description: The API must declare global security.
    severity: error
    given: $
    then:
      field: security
      function: truthy
  security-scheme-bearer:
    description: A BearerAuth (HTTP bearer) security scheme must be defined.
    severity: error
    given: $.components.securitySchemes
    then:
      field: BearerAuth
      function: truthy
  security-scheme-is-bearer:
    description: BearerAuth must be an http bearer scheme.
    severity: warn
    given: $.components.securitySchemes.BearerAuth
    then:
      - field: type
        function: pattern
        functionOptions:
          match: "^http$"
      - field: scheme
        function: pattern
        functionOptions:
          match: "^bearer$"

  # ── GENERAL QUALITY ──────────────────────────────────────────────
  no-empty-descriptions:
    description: Descriptions, when present, must not be empty.
    severity: warn
    given: $..description
    then:
      function: truthy
  deprecation-documented:
    description: Deprecated operations should explain the deprecation in their description.
    severity: info
    given: $.paths[*][get,post,put,patch,delete][?(@.deprecated == true)]
    then:
      field: description
      function: truthy