# harvested from https://github.com/XeroAPI/Xero-OpenAPI/blob/fd9d44b04bf4934a7509b8e7ece51a9e0e462e4f/.spectral.yaml on 2026-10-09 — a Spectral ruleset published in the provider's own GitHub repository (XeroAPI/Xero-OpenAPI); found by GitHub code search, fetched verbatim
x-method: harvested
x-stamped: 2026-10-09
x-source-url: https://github.com/XeroAPI/Xero-OpenAPI/blob/fd9d44b04bf4934a7509b8e7ece51a9e0e462e4f/.spectral.yaml
extends:
  - "spectral:oas"                      # Base OpenAPI validation
  - "@stoplight/spectral-owasp-ruleset" # OWASP API security ruleset

rules:
  # Custom rules specific to Xero APIs
  xero-info-required-fields:
    description: "Ensure required info fields are present"
    given: "$.info"
    severity: error
    then:
      - field: "title"
        function: truthy
      - field: "version"
        function: truthy
      - field: "termsOfService"
        function: truthy
      - field: "contact"
        function: truthy

  xero-contact-required-fields:
    description: "Ensure contact has required fields"
    given: "$.info.contact"
    severity: error
    then:
      - field: "name"
        function: truthy
      - field: "email"
        function: truthy
      - field: "url"
        function: truthy

  xero-servers-required:
    description: "Ensure servers are defined"
    given: "$"
    severity: error
    then:
      field: "servers"
      function: truthy

  xero-server-description:
    description: "Each server should have a description"
    given: "$.servers[*]"
    severity: warn
    then:
      field: "description"
      function: truthy

  xero-operation-summary:
    description: "Operations should have summaries"
    given: "$.paths[*][get,post,put,patch,delete,head,options,trace]"
    severity: warn
    then:
      field: "summary"
      function: truthy

  xero-operation-id:
    description: "Operations must have operationId"
    given: "$.paths[*][get,post,put,patch,delete,head,options,trace]"
    severity: error
    then:
      field: "operationId"
      function: truthy

  xero-operation-tags:
    description: "Operations should have tags"
    given: "$.paths[*][get,post,put,patch,delete,head,options,trace]"
    severity: warn
    then:
      field: "tags"
      function: truthy

  xero-operation-security:
    description: "Operations should have security defined"
    given: "$.paths[*][get,post,put,patch,delete,head,options,trace]"
    severity: info
    then:
      field: "security"
      function: truthy

  xero-response-200-description:
    description: "200 responses should have descriptions"
    given: "$.paths[*][get,post,put,patch,delete,head,options,trace].responses.200"
    severity: warn
    then:
      field: "description"
      function: truthy

  xero-schema-properties-description:
    description: "Schema properties should have descriptions for better documentation"
    given: "$.components.schemas[*].properties[*]"
    severity: off
    then:
      field: "description"
      function: truthy

  xero-openapi-version:
    description: "Should use OpenAPI 3.0.0 or higher"
    given: "$.openapi"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^3\\.[0-9]+\\.[0-9]+$"

  xero-path-parameters:
    description: "Path parameters should be properly defined"
    given: "$.paths[*][get,post,put,patch,delete,head,options,trace].parameters[?(@.in === 'path')]"
    severity: error
    then:
      - field: "name"
        function: truthy
      - field: "required"
        function: truthy
      - field: "schema"
        function: truthy

  xero-consistent-error-responses:
    description: "Should have consistent error response structure"
    given: "$.paths[*][get,post,put,patch,delete,head,options,trace].responses[?(@property >= '400')]"
    severity: info
    then:
      field: "description"
      function: truthy
  operation-description: off          # Disable operation description rule for now
  operation-tags: off                 # Disable operation tags rule for now
  oas3-schema: warn                  # Re-enable schema validation with reduced severity
  info-contact:
    severity: warn                    # Re-enabled with reduced severity
    given: $.info.contact             # Scope: info.contact field
    then:
      function: truthy               # Ensure the field is truthy
  info-license:
    severity: warn                    # Re-enabled with reduced severity
    given: $.info.license             # Scope: info.license field
    then:
      function: truthy               # Ensure the field is truthy


  # OWASP Rules
  owasp:api2:2023-no-http-basic: off  # Disable HTTP Basic authentication rule
  owasp:api4:2023-string-limit: off   # Disable string length limit checks
  owasp:api4:2023-array-limit: off    # Disable array size limit checks
  owasp:api4:2023-integer-limit-legacy: off # Disable integer limit checks
  owasp:api4:2023-rate-limit: off     # Disable rate limiting headers check
  owasp:api2:2023-jwt-best-practices: off # Disable JWT best practices check
  owasp:api8:2023-define-error-responses-401: off  # Disable missing 401 response rule
  owasp:api8:2023-define-error-responses-500: off  # Disable missing 500 response rule
  owasp:api4:2023-rate-limit-responses-429: off  # Disable missing 429 rate limit response rule
  oas3-valid-media-example: off                 # Disable media example validation
  owasp:api4:2023-integer-format: off           # Disable integer format validation
  no-$ref-siblings: off                        # Disable $ref sibling validation
  oas3-valid-schema-example: off               # Disable schema example validation
  owasp:api9:2023-inventory-access: off          # Disable server audience declaration rule
  owasp:api9:2023-inventory-environment: off   # Disable server environment declaration rule
  owasp:api2:2023-short-lived-access-tokens: off # Disable short-lived access tokens rule
  owasp:api8:2023-define-error-validation: off  # Disable missing error response validation rule
  operation-tag-defined: off  # Disable operation tags defined in global tags rule
  owasp:api4:2023-string-restricted: off  # Disable string restricted rule to address warnings
  path-params: off  # Disable path parameter validation to address mapping key issues
  owasp:api8:2023-define-cors-origin: off  # Disable CORS origin header requirement
  oas3-operation-security-defined: error # Ensure all scopes are listed in schema