cvt

Contract Validator Toolkit

📖 Documentation

A contract validation platform for OpenAPI v2/v3 specifications that validates API requests and responses against API contracts. Supports both consumer-side (client) and producer-side (server) validation.

Examples: For complete working examples with real-world usage patterns, see the CVT Demo Repository.

🎙️ Podcast

Listen to an AI-generated podcast of CVT, created with NotebookLM

Features

• OpenAPI v2/v3 Support - Validate against Swagger 2.0 and OpenAPI 3.0 specifications
• Consumer Validation - Validate outgoing API calls match the contract (client-side)
• Producer Validation - Validate incoming requests match the contract (server-side middleware)
• Consumer Registry - Track which consumers depend on which schemas
• Mock Server - Generate a running HTTP mock server from any OpenAPI schema with cvt mock
• Deployment Safety - can-i-deploy checks prevent breaking changes from reaching production
• High Performance - gRPC-based server with schema caching (1000 schemas, 24h TTL)
• Multiple SDKs - Node.js, Python, Go, and Java client libraries
• Security - TLS/mTLS support and API key authentication
• Observability - Prometheus metrics and Grafana dashboards built-in

Contract Testing Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                          Contract Testing with CVT                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  CONSUMER TESTING                        PRODUCER TESTING                   │
│  "Am I calling the API correctly?"       "Does my API match my spec?"       │
│                                                                             │
│  ┌─────────────┐      HTTP       ┌─────────────┐                            │
│  │ Your Service│ ──────────────► │ Upstream API│                            │
│  │ (Consumer)  │                 │ (Producer)  │                            │
│  └──────┬──────┘                 └─────────────┘                            │
│         │                                                                   │
│         │ Validate request/response                                         │
│         ▼                                                                   │
│  ┌─────────────┐                 ┌─────────────┐      HTTP       ┌────────┐ │
│  │ CVT Server  │                 │  Your API   │◄────────────────│ Client │ │
│  │ + Schema    │                 │ + Middleware│                 │        │ │
│  └─────────────┘                 └──────┬──────┘                 └────────┘ │
│                                         │                                   │
│                                         │ Validate request/response         │
│                                         ▼                                   │
│                                  ┌─────────────┐                            │
│                                  │ CVT Server  │                            │
│                                  │ + Schema    │                            │
│                                  └─────────────┘                            │
│                                                                             │
│  Use Cases:                              Use Cases:                         │
│  • Test your API integrations            • Runtime request validation       │
│  • Mock upstream APIs                    • Detect implementation drift      │
│  • Register as consumer                  • Deployment safety checks         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Quick Start

# 1. Start CVT server + PostgreSQL + Prometheus + Grafana
make up

# 2. Verify gRPC server is accepting connections
make health

# 3. Run Node.js SDK example to see validation in action
make run-example

# 4. Stop all containers
make down

Basic Usage

import { ContractValidator } from "@sahina/cvt-sdk";

const validator = new ContractValidator("localhost:9550");
await validator.registerSchema("my-api", "./openapi.json");

const result = await validator.validate(
  { method: "GET", path: "/users/123" },
  { statusCode: 200, body: { id: 123, name: "Alice" } },
);

console.log(result.valid ? "Valid" : "Invalid");

When to Use Each Approach

Key Commands

# Docker
make up                    # Start server + observability
make down                  # Stop all services
make health                # Check server health

# Testing
make test                  # Run all tests
make test-server           # Server unit tests only

# Development
make build                 # Build server and SDKs
make run-example           # Run Node.js example

Run make help for all available commands.

CLI (Local Lite Mode)

Validate schemas locally without Docker.

Install

Download a pre-built binary from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/sahina/cvt/releases/latest/download/cvt-darwin-arm64 -o cvt

# macOS (Intel)
curl -L https://github.com/sahina/cvt/releases/latest/download/cvt-darwin-amd64 -o cvt

# Linux (x86_64)
curl -L https://github.com/sahina/cvt/releases/latest/download/cvt-linux-amd64 -o cvt

# Linux (ARM64)
curl -L https://github.com/sahina/cvt/releases/latest/download/cvt-linux-arm64 -o cvt

chmod +x cvt
sudo mv cvt /usr/local/bin/

For Windows, download cvt-windows-amd64.exe or cvt-windows-arm64.exe from the releases page.

Verify the installation:

cvt version

Build from source (requires Go 1.25+):

go build -o cvt ./cmd/cvt

Usage

# Validate request/response against schema
cvt validate --schema ./openapi.json --request req.json --response resp.json

# Detect breaking changes between schema versions
cvt compare --old ./v1/openapi.json --new ./v2/openapi.json

# Start a mock HTTP server from a schema
cvt mock --schema ./openapi.json

# Check deployment safety
cvt can-i-deploy --schema my-api --version 2.0.0 --env prod

See CLI Reference for all commands.

Project Structure

/
├── api/protos/       # gRPC proto definitions
├── cmd/cvt/          # CLI entry point
├── server/           # Go gRPC server
├── sdks/             # Client SDKs (Node.js, Python, Go, Java)
├── docs/             # Documentation
└── observability/    # Prometheus & Grafana configs

Prerequisites

• Docker & Docker Compose (required)
• Node.js 20+ (for Node.js SDK)
• Optional: Go 1.25+, Python 3.11+, Java 21+

Documentation

Getting Started

Guides

Reference

Operations

For AI Agents / LLMs

• llms.txt - Index file with documentation links
• llms-full.txt - Complete API reference with examples

Comparison with Alternatives

Troubleshooting

See Development Guide for more troubleshooting tips.

License

MIT License - see LICENSE file for details

Built with: gRPC, kin-openapi, Ristretto, Zap