Pydantic v2 vs Cerberus for Clinical Schema Validation

Problem Statement

Choosing a validation library for clinical result schemas is a decision you live with for years, because the library becomes the control point where a malformed OBX is either caught or waved through to a patient chart. Two mature Python options sit at opposite ends of a real design axis: Pydantic v2 expresses the schema as code — typed models with a Rust-backed core — while Cerberus expresses it as data — a plain dictionary you can load from a database row or a YAML file and change without a deploy. Neither is universally correct. A validator baked into a typed model gives you IDE completion, static analysis, and raw throughput on a busy ingestion path; a validator expressed as a dictionary lets a non-programmer lab informaticist adjust an allowed range without touching Python. This page compares the two on the dimensions that actually decide clinical-integration outcomes, shows the same result payload validated correctly in each, and gives a defensible when-to-choose-each. It sits under Schema Validation & Error Handling, the stage that owns structural truth at the ingestion boundary.

The Decision Axis

The single most important distinction is where the schema lives. Pydantic v2 is schema-as-code: the schema is a Python class, versioned in the repository, validated by the type checker, and executed by a compiled core (pydantic-core, written in Rust). Cerberus is schema-as-data: the schema is a dict, so it can be stored, transmitted, diffed by non-engineers, and swapped at runtime — but it is invisible to mypy and slower per-record because validation is interpreted in Python. Everything else — performance, error shape, coercion behavior — follows from that root choice.

Side-by-Side Comparison

Coercion Is the Clinical Crux

For clinical data the coercion column deserves special attention, because silent coercion is a patient-safety hazard. If a validator quietly turns the string "H" into a number, or accepts "7.0.1" as a float by truncation, a wrong value reaches the chart. Both libraries can coerce and both can refuse to — the difference is how you spell “refuse.” In Pydantic v2 you set strict=True (per field via Field(strict=True) or per model) so a float field rejects a string outright. In Cerberus, coercion is opt-in: a field coerces only if you attach a coerce callable, and absent one a type mismatch is an error. The safe default in both is: never coerce a numeric result field; require the upstream to send the right type, and let the validator reject anything else into the dead-letter queue.

Equivalent Code: The Same Payload in Both

Consider one canonical result payload — a serum potassium from a chemistry analyzer — and validate it identically in each library: accession is a required non-empty string, analyte_loinc matches the LOINC pattern, value is a strict float, unit is constrained to an allowed set, and no numeric coercion is permitted.

Pydantic v2 (schema-as-code)

from __future__ import annotations

from pydantic import BaseModel, ConfigDict, Field, ValidationError


class ResultV2(BaseModel):
    model_config = ConfigDict(strict=True, extra="forbid")

    accession: str = Field(min_length=1)
    analyte_loinc: str = Field(pattern=r"^\d{1,5}-\d$")
    value: float
    unit: str = Field(pattern=r"^(mmol/L|mg/dL|g/dL|U/L)$")


payload = {"accession": "A100", "analyte_loinc": "2823-3", "value": 4.2, "unit": "mmol/L"}

try:
    result = ResultV2.model_validate(payload)
except ValidationError as exc:
    errors = exc.errors()  # list of {"loc", "type", "msg", "input"}
    raise

With strict=True, sending "value": "4.2" (a string) raises ValidationError instead of silently casting — exactly the behavior a numeric result field needs.

Cerberus (schema-as-data)

from cerberus import Validator

RESULT_SCHEMA: dict = {
    "accession": {"type": "string", "required": True, "empty": False},
    "analyte_loinc": {"type": "string", "required": True, "regex": r"^\d{1,5}-\d$"},
    "value": {"type": "float", "required": True},  # no `coerce` => strings rejected
    "unit": {"type": "string", "required": True, "allowed": ["mmol/L", "mg/dL", "g/dL", "U/L"]},
}

payload = {"accession": "A100", "analyte_loinc": "2823-3", "value": 4.2, "unit": "mmol/L"}

validator = Validator(RESULT_SCHEMA, require_all=False)
if not validator.validate(payload):
    errors = validator.errors  # {"field": ["message", ...]}
    raise ValueError(errors)

Because no coerce is attached to value, Cerberus rejects "4.2" as a type error — the same safe refusal, expressed in data rather than code. The RESULT_SCHEMA dictionary can be stored in a table and edited by an informaticist to add an allowed unit without a deploy, which is precisely the flexibility Pydantic trades away for typing and speed.

When to Choose Each

Choose Pydantic v2 when validation sits on a high-throughput ingestion path where per-record latency matters, the schema is owned by engineers and versioned with the code, you want mypy and IDE support to catch schema drift at author time, or you need to export JSON Schema / integrate with FastAPI. Its compiled core makes it the default for the hot path that drains analyzer batches, and its typed models compose cleanly with the rest of an async pipeline. This is why the other implementation pages in this stage — including the ASTM E1394 validation build — are written in Pydantic v2.

Choose Cerberus when the schema must be edited at runtime by clinical informaticists without a deploy, stored as data in a database or configuration file, or generated dynamically from a data dictionary. If your allowed-unit list or per-analyte constraint changes frequently and is maintained by non-programmers, expressing the schema as a dictionary they can edit — with the same rejection guarantees — is worth the throughput cost. A common hybrid uses Pydantic v2 for the structural envelope on the hot path and Cerberus for a runtime-tunable per-analyte constraint layer.

Compliance Note

Whichever library validates the payload, the compliance obligations are identical: CLIA §493.1291 requires that reported results be complete and accurate, and 21 CFR Part 11 requires that the validation applied to an electronic record be documented, attributable, and reproducible on review. Two implications follow. First, forbid silent numeric coercion in both — a validator that casts "4.2" to 4.2 has altered the record’s meaning without a decision. Second, the schema version must be recorded with each validation outcome so an inspector can reconstruct which rules were live when a result passed; with Pydantic this is the code commit, with Cerberus it is the version of the stored dictionary. Schema-as-data raises the bar on change control precisely because a dict is easy to edit — it must be version-controlled and audited exactly as strictly as code, or the runtime flexibility becomes an unaudited path to altered validation.

Troubleshooting / FAQ

Related

• Schema Validation & Error Handling — the stage contract both libraries implement, including the ingress/egress boundary and the quarantine-never-guess invariant.
• Validating ASTM E1394 Instrument Output with Python — a concrete Pydantic v2 validation build for a framed instrument protocol.
• Routing Malformed HL7 Messages to a Dead-Letter Queue — where the rejections from either library are quarantined with failure metadata for re-drive.
• Instrument Data Ingestion & HL7/CSV Pipelines — the ingestion tier that owns structural truth at the boundary.

Part of: Schema Validation & Error Handling.