FHIR Search Validator

A pre-flight validator for FHIR REST search queries. Given a URL like Patient?gender=male, it checks syntax and semantics against a FHIR server's declared capabilities before you send the request.

FHIR servers expose what they support via a CapabilityStatement (fetched from /metadata). Search parameters, modifiers, and comparators vary by server. This tool validates a query URL against that metadata so you catch unsupported resource types, unknown search params, invalid modifiers, and bad values early.

flowchart TB
    subgraph entry [EntryPoints]
        CLI[scripts/run_validator.py]
        Notebook[examples/notebooks]
        Lib[Python_import]
    end

    subgraph services [services]
        ValidatorService[FhirValidatorService]
    end

    subgraph config [config]
        Settings[settings.py]
    end

    subgraph core [core]
        Parser[query_parser]
        Validator[validator]
        Codesets[codeset_validator]
    end

    subgraph infra [infrastructure]
        CapIndex[capability_index]
    end

    subgraph external [External]
        FHIRServer[FHIR_Server_metadata]
    end

    CLI --> ValidatorService
    Notebook --> ValidatorService
    Lib --> ValidatorService
    ValidatorService --> Settings
    ValidatorService --> CapIndex
    ValidatorService --> Validator
    Validator --> Parser
    Validator --> Codesets
    CapIndex --> FHIRServer

1. Parse the query URL into resource type and query parameters
2. Load the server's CapabilityStatement from /metadata
3. Validate against allowed resource types, search params, modifiers, and comparators
4. Apply extra rules for known value sets and Patient identifiers

• Patient.gender — male, female, other, unknown
• AllergyIntolerance.verification-status — unconfirmed, confirmed, refuted, entered-in-error
• AllergyIntolerance.clinical-status — active, inactive, resolved

Built-in public test servers require no authentication — suitable for local dev, integration tests, and manual validation. Registry informed by the HL7 Public Test Servers list.

Select via FHIR_DEFAULT_SERVER_KEY in config/.env.local:

Full details: docs/public-test-servers.md

# Use Firely instead of HAPI
export FHIR_DEFAULT_SERVER_KEY=firely
fhir-validate "https://server.fire.ly/Patient?gender=male"

# Test all public servers
python3 scripts/run_all_tests.py

Override with FHIR_METADATA_URL and FHIR_SERVER_BASE for custom (possibly authenticated) servers.

fhir_query_validator-DS-fhir/
├── config/
│   └── .env.example          # Environment variable template
├── docs/
│   └── adr/                  # Architectural decision records
├── examples/
│   └── notebooks/            # Demo Jupyter notebook
├── planning/                 # Sprint notes and roadmap
├── scripts/
│   ├── run_validator.py      # CLI entry point
│   └── run_all_tests.py      # Multi-server integration script
├── src/
│   └── fhir_validator_agent/
│       ├── config/           # Environment and server settings
│       ├── core/             # Parsing and validation rules
│       ├── infrastructure/   # HTTP calls (CapabilityStatement, OAuth)
│       └── services/         # Application orchestration
└── tests/
    ├── unit/                 # Fast, offline unit tests
    ├── regression/           # JSON-driven regression cases
    └── integration/          # Live FHIR server tests (optional)

Get validating in under two minutes. No configuration required — defaults target the public HAPI FHIR R4 server.

• Python 3.11+
• pip and a virtual environment (recommended)

git clone <repo-url>
cd fhir_query_validator

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e ".[dev,notebook]"

fhir-validate "https://hapi.fhir.org/baseR4/Patient?gender=male"

Expected output:

Valid: True

Try an invalid query to see structured errors:

fhir-validate "https://hapi.fhir.org/baseR4/Patient?gender=fe"

Valid: False
Errors:
 - Value 'fe' for 'Patient.gender' is not allowed. Allowed values: {'male', 'female', 'other', 'unknown'}

from fhir_validator_agent import FhirValidatorService

service = FhirValidatorService.from_env()
result = service.validate_query("https://hapi.fhir.org/baseR4/Patient?gender=male")

print(result)
# {"valid": True, "errors": []}

FhirValidatorAgent is a backward-compatible alias for FhirValidatorService.

Defaults use HAPI R4. To switch servers or enable OAuth:

cp config/.env.example config/.env.local

Edit config/.env.local — for example, to use Spark (no auth):

FHIR_DEFAULT_SERVER_KEY=spark
FHIR_USE_AUTH=false

See Configuration for all variables.

The test suite uses pytest. All offline tests (unit + regression) run without network access and are suitable for CI.

Install dev dependencies (included if you followed Quick Start):

pip install -e ".[dev]"

All offline tests (recommended before every commit):

pytest -m "not integration" -v

Unit tests — parser, validator, config, CLI, service (mocked):

make test-unit
# equivalent: pytest tests/unit -v

Regression tests — fixed scenarios in tests/regression/cases.json that guard known good/bad behavior:

make test-regression
# equivalent: pytest tests/regression -m regression -v

Coverage — reports coverage on core/ and services/ with an 80% minimum:

make test-cov
# equivalent: pytest -m "not integration" --cov=fhir_validator_agent --cov-report=term-missing

Integration tests — hits live HAPI FHIR server (skippable if offline):

make test-integration
# equivalent: pytest tests/integration -m integration -v

Multi-server manual script — HAPI and Firely positive/negative scenarios:

python3 scripts/run_all_tests.py

tests/
├── conftest.py              # Shared fixtures (CapabilityStatement, validator)
├── unit/                    # Isolated unit tests per module
├── regression/
│   ├── cases.json           # Fixed regression scenarios
│   └── test_regression.py   # Parametrized regression runner
└── integration/             # Live FHIR server tests

Append an entry to tests/regression/cases.json:

{
  "id": "patient_gender_unknown_value",
  "description": "Reject unknown gender coded value",
  "query": "https://hapi.fhir.org/baseR4/Patient?gender=fe",
  "expected_valid": false,
  "expected_error_substrings": ["Patient.gender", "fe"]
}

Then run:

make test-regression

Exclude integration tests: pytest -m "not integration"

Run only regression: pytest -m regression

Copy config/.env.example to config/.env.local and edit. Never commit .env.local — it is gitignored.

Edit src/fhir_validator_agent/core/codeset_validator.py and add an entry to STATIC_VALUESETS:

STATIC_VALUESETS = {
    "Patient.gender": {"male", "female", "other", "unknown"},
    # Add new entries as "ResourceType.param_name": {allowed, values}
}

python scripts/run_all_tests.py

See the 3-Week Implementation Plan for the full delivery schedule (delivery date: May 15, 2026):