Skip to content

Welcome to FastSSV Documentation

FastSSV (Fast Semantic Static Validator) is a semantic validation framework for OMOP CDM SQL queries. It catches the silent failures that pass any SQL linter and fail any replication attempt.

OMOP SQL that runs without errors can still be analytically wrong.

A query that silently drops 30% of patients because it misses concept descendants, filters on a deprecated concept, or applies a temporal constraint outside a patient's observation window will execute cleanly, return plausible numbers, and produce a flawed study. FastSSV catches these violations before they reach results.

What's in these docs

  • Architecture

    How FastSSV is laid out, the rule engine, and the plugin registry.

  • Plugin system

    Add your own rules without modifying core code.

  • Semantic rules guide

    The reasoning behind each rule category and when violations matter.

  • Rules reference

    Every built-in rule with its ID, severity, and example violation.

  • HTTP API

    Run FastSSV as a FastAPI service with an HTMX web UI.

  • JSON output

    The structured report format for CI integration.

  • Logging

    Configure log level, file destination, and JSON-structured output for log aggregators.

Quick start

pip install fastssv
fastssv path/to/query.sql

For local development:

uv sync
uv run fastssv path/to/query.sql

Why FastSSV

  • Targets silent failures. Catches cases where SQL is valid, the query returns results, and those results are wrong.
  • Static and deterministic. Parses SQL into an AST and checks structural patterns against the OMOP CDM v5.4 schema — same query, same result, every time, without a database connection.
  • AI-agnostic. Validates SQL from humans, ATLAS, scripts, or AI agents identically.
  • Rule-based and extensible. Every check is a discrete, documented rule with a unique ID, severity level, violation message, and suggested fix.