Simpaisa API Spectral Ruleset¶

This document describes the Spectral linting rules enforced across all Simpaisa OpenAPI specifications. The machine-readable ruleset is defined in .spectral.yaml in this directory.

Overview¶

The ruleset extends the default spectral:oas rules and adds ten custom rules specific to Simpaisa's API governance requirements. All OpenAPI 3.1 specifications must pass these rules before merge.

Rules¶

1. idempotency-key-required¶

Severity: Error

All POST operations must include an Idempotency-Key header parameter. This ensures that payment operations can be safely retried without creating duplicate transactions — a critical requirement for a payment gateway processing 270M+ transactions.

2. trace-id-in-response¶

Severity: Warning

All responses must include an X-Trace-Id header. This enables end-to-end request tracing across Simpaisa's microservices architecture and is essential for incident investigation and debugging.

3. standard-error-schema¶

Severity: Error (two rules: standard-error-schema-4xx and standard-error-schema-5xx)

All 4xx and 5xx responses must reference the ErrorResponse schema. This ensures a consistent error format across Pay-Ins, Pay-Outs, Remittances and Cards APIs, simplifying SDK generation and merchant integration.

The ErrorResponse schema must include: - error.code — machine-readable error code - error.message — human-readable description - error.details[] — optional field-level validation errors - traceId — request trace identifier

4. pagination-params¶

Severity: Warning

GET endpoints that return lists must include cursor and limit query parameters. Simpaisa uses cursor-based pagination (not offset-based) for consistent performance across large datasets.

5. rate-limit-headers¶

Severity: Warning

All success responses (2xx) must include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. These headers allow merchants to implement client-side rate management and avoid throttling.

6. version-prefix¶

Severity: Error

All API paths must start with a version prefix in the format /vN/ (e.g. /v3/). This enforces explicit API versioning and supports parallel operation of multiple API versions during migration periods.

7. kebab-case-paths¶

Severity: Warning

Path segments (excluding path parameters) must use kebab-case — lowercase letters and hyphens only. Path parameters in curly braces are exempt and may use camelCase. This ensures URL consistency and readability.

Examples: - /v3/payin/{merchantId}/transactions/initiate (correct) - /v3/payIn/{merchantId}/Transactions/Initiate (incorrect)

8. no-internal-schemas¶

Severity: Error

Schema names in components.schemas must not contain the words "Internal" or "Private". This prevents accidental exposure of internal data models in public-facing API specifications.

9. merchant-id-in-path¶

Severity: Error

All API paths must include {merchantId} as a path segment. Simpaisa's multi-tenant architecture requires merchant scoping at the URL level for access control, audit logging and rate limiting.

10. timestamp-header-required¶

Severity: Error

All operations (GET, POST, PUT, PATCH, DELETE) must include an X-Timestamp header parameter. The timestamp is a mandatory component of the RSA-SHA256 request signature, preventing replay attacks.

Usage¶

Running locally¶

# Install Spectral CLI
npm install -g @stoplight/spectral-cli

# Lint a single spec
spectral lint Standards/OpenAPI/payin-api.yaml --ruleset Standards/.spectral.yaml

# Lint all specs
spectral lint Standards/OpenAPI/*.yaml --ruleset Standards/.spectral.yaml

CI/CD integration¶

The Spectral ruleset should be executed as a quality gate in the CI pipeline. Any rule with severity error must block the merge. Rules with severity warn should be reported but not block.

# Example Bitbucket Pipeline step
- step:
    name: Lint OpenAPI Specs
    script:
      - npm install -g @stoplight/spectral-cli
      - spectral lint Standards/OpenAPI/*.yaml --ruleset Standards/.spectral.yaml --fail-severity error

Extending the ruleset¶

To add new rules, edit .spectral.yaml and add a corresponding section to this document. All rules must include: - A clear description - A human-readable message template - An appropriate severity (error for must-fix, warn for should-fix) - A given JSONPath targeting the relevant part of the OpenAPI spec - A then assertion using Spectral's built-in functions