TrueLayer API Rules

extends: spectral:oas
rules:
  truelayer-operation-summary-title-case:
    description: Operation summaries must use Title Case
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^([A-Z][a-z]* ?)+$"

  truelayer-operation-tags-required:
    description: All operations must have at least one tag
    severity: error
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy

  truelayer-v3-path-prefix:
    description: All paths must use the /v3/ prefix
    severity: error
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^/v3/"

  truelayer-idempotency-key-required:
    description: POST operations must require an Idempotency-Key header
    severity: error
    given: "$.paths[*][post].parameters[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            name:
              type: string

  truelayer-signature-header-post:
    description: POST payment operations require Tl-Signature header
    severity: error
    given: "$.paths[/v3/payments,/v3/mandates,/v3/payouts][post].parameters"
    then:
      function: truthy

  truelayer-amount-minor-units:
    description: >-
      Payment amounts must be in minor units (integer), not decimal
    severity: error
    given: "$.components.schemas.*.properties.amount_in_minor"
    then:
      field: type
      function: enumeration
      functionOptions:
        values:
          - integer

  truelayer-currency-enum:
    description: Currency fields must be restricted to supported values (GBP, EUR)
    severity: warn
    given: "$.components.schemas.*.properties.currency"
    then:
      field: enum
      function: truthy

  truelayer-uuid-format:
    description: ID fields should use UUID format
    severity: hint
    given: "$.components.schemas.*.properties.id"
    then:
      field: format
      function: enumeration
      functionOptions:
        values:
          - uuid

  truelayer-webhook-type-documented:
    description: Webhook types should be documented as enum values
    severity: hint
    given: "$.components.schemas.*.properties.type"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          minProperties: 1

  truelayer-error-trace-id:
    description: Error responses should include a trace_id for debugging
    severity: hint
    given: "$.paths[*][*].responses[4*,5*].content.application/json.schema.properties"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          minProperties: 1

  truelayer-success-2xx-defined:
    description: All operations must define a 200 success response
    severity: error
    given: "$.paths[*][get,post,delete]"
    then:
      field: responses
      function: schema
      functionOptions:
        schema:
          type: object
          minProperties: 1