fairvisor validate

fairvisor validate parses and validates a policy bundle file, reporting every structural error found. It does not start the edge or contact the SaaS API.

Synopsis

fairvisor validate <file|->

Pass - to read from stdin.

What is validated

The validator checks the complete bundle schema:

1. Top-level structure — bundle_version present and > 0, policies array non-empty, optional issued_at/expires_at are valid ISO 8601
2. Each policy — id non-empty, spec present, selector valid, mode is enforce or shadow
3. Each selector — at least one of pathExact or pathPrefix present, both start with /, methods are valid HTTP verbs, optional hosts is a non-empty string array
4. Each rule — name non-empty, limit_keys non-empty array of valid descriptor keys, algorithm is a known value, algorithm_config matches the algorithm schema
5. Token bucket config — one of tokens_per_second / rps present, burst >= tokens_per_second
6. Cost-based config — budget > 0, period is 5m/1h/1d/7d, staged_actions non-empty, strictly ascending thresholds, a reject action at 100%
7. Kill switches — scope_key matches (jwt|header|query|ip|ua):[A-Za-z0-9_-]+, scope_value non-empty
8. Runtime overrides — optional global_shadow and kill_switch_override blocks must be valid objects; when enabled=true, reason and future expires_at are required
9. Loop detection — window_seconds positive integer, threshold >= 2
10. Circuit breaker — spend_rate_threshold_per_minute positive

Errors are reported as path: message:

policies[0].spec.rules[0].algorithm_config: burst must be >= tokens_per_second
policies[1].spec.selector: at least one of pathExact or pathPrefix is required

Examples

# Validate a file
fairvisor validate policy.json

# Validate from stdin (e.g. piped from another command)
cat policy.json | fairvisor validate -

# Use in CI — non-zero exit on error
fairvisor validate policy.json && echo "Policy OK" || exit 1

Successful output

Valid: 2 policies, 5 rules

Failed output

Error: invalid bundle
  policies[0].spec.rules[0].algorithm_config: burst (5) must be >= tokens_per_second (10)
  policies[1].id: must be a non-empty string

Exit codes

CI integration

# GitHub Actions example
- name: Validate policy
  run: fairvisor validate policy.json

Standalone CI (no SaaS)

If you run Fairvisor in standalone mode (local policy.json, no SaaS control plane), make policy validation a required CI step before deploy.

GitHub Actions

name: Validate Fairvisor Policy
on: [push, pull_request]

jobs:
  validate-policy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Fairvisor CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/fairvisor/edge/main/install.sh | sh
      - name: Validate policy
        run: fairvisor validate policy.json

GitLab CI

stages:
  - validate

validate_policy:
  stage: validate
  image: alpine:3.20
  script:
    - apk add --no-cache curl
    - curl -fsSL https://raw.githubusercontent.com/fairvisor/edge/main/install.sh | sh
    - fairvisor validate policy.json

Failing validation must block merge/release for standalone deployments.