skavuri143/mapverity

What it does

MapVerity targets a specific failure mode in ETL and data-platform work: output that is typed correctly, non-null and in-domain, yet wrong. Instead of profiling target data, it reads the source-to-target mapping sheet analysts already maintain and compiles each mapped field into an executable check: it re-derives the expected value from the source record and compares it with what the pipeline wrote. Supported rules include direct, trim, upper, lower, lookup:, date:, concat:, constant:, count, ref: and expr:, with a full table in the mapping sheet reference.

Beyond per-field comparison, the tool covers record completeness under the job's selection filter, nested arrays matched by composite key, array cardinality, foreign keys, required fields and domains. It reads COBOL copybooks (EBCDIC, COMP-3, binary, zoned decimal, OCCURS, REDEFINES), multi-record fixed-width layouts with control totals, CSV/JSON/Parquet, S3, DocumentDB/MongoDB, any SQLAlchemy database and paginated REST APIs. It is aimed at teams running healthcare, insurance, government or financial pipelines with mainframe extracts and long transformation chains.

The suite can also be scored: mutation testing injects 15 classes of realistic ETL faults into the output and reports which ones the checks miss. Optional analysis adds a defect-risk model trained on public NASA MDP data with SHAP explanations, and ERAD-QA ordering that runs the checks most likely to fail per unit of cost. Deterministic quality gates produce PASS/WARN/BLOCK/INCOMPLETE from evidence, while predicted risk stays advisory.

Quickstart

The README's 15-minute example needs no cloud account. Install the package with all extras, clone the repository and enter the member-eligibility example, then generate the synthetic source data and run the pipeline under test:

pip install "mapverity[all]"
git clone https://github.com/skavuri143/mapverity && cd mapverity/examples/member_eligibility
python generate_data.py
python transform.py
mapverity from-mapping mapping/member_data_model_mapping.csv --datasets datasets.yaml -o member.mapverity.yaml
mapverity validate member.mapverity.yaml --html report.html

The expected result is 49 passed · 0 failed · 0 errors and an HTML report. To see a failure, rerun the pipeline with an intentional defect and validate again:

python transform.py --defect D07_comp3_scale_lost
mapverity validate member.mapverity.yaml

The mapping-derived check on monthlyIncome should fail with the row count for mismatches. A second example, insurance_claims, exercises a multi-record fixed-width file with nested claim lines.

Measuring and gating

After restoring a clean run, mutation testing scores the suite, and validation can consume the report together with a gates policy:

python transform.py
mapverity mutate member.mapverity.yaml --dataset members --json mutation.json
mapverity validate member.mapverity.yaml --mapping mapping/member_data_model_mapping.csv \
    --mutation-report mutation.json --gates gates.yaml --html report.html --junit results.xml

The README shows a PASS gate for this flow. Risk-based ordering is a separate opt-in path: train the model, score transformation functions, diff mappings and plan a prioritized run. Risk ordering never removes a check — blocking checks always run, and a run shortened by a time budget reports INCOMPLETE rather than PASS.

Constraints

• The Python package core depends on pandas, numpy, pyyaml and typer; S3/MongoDB, SQL, REST and AI features each need their own extra, so install the matching extra rather than core alone.
• The project is alpha and the spec format may change before 1.0.
• Risk scores are advisory; the model card's limitations section should be read before relying on them, especially since the project's own study found the risk signal did not improve prioritization.
• All examples and tests run on synthetic or public data; real member, patient or policyholder records should not be attached to issues.
• The license is Apache-2.0.

Evidence and scope

The README reports results reproduced by scripts in experiments/: 20/20 realistic Glue-job defects caught by mapping-derived checks versus 5/20 for data-model constraints and 15/20 for profiled inference; 99.0% and 100% mutant kill rates on the two examples; zero false alarms across 20 clean runs; and 100,000 member documents (163,107 nested segments) validated with 49 checks in 8.7 s on 2 vCPUs. These are the maintainers' own reported measurements, with confidence intervals, ablations and negative findings included in the experiments directory.

HotRepo's take

The repository appeared in HotRepo's new-project list for Python on 2026-11-04, recording 4 stars and 4 forks gained over roughly an hour, at 105 stars and 106 forks in total. That is a very short observation window and no all-language daily rank was recorded, so the snapshot supports only the fact of early pickup, not a trend. What stands out is the mismatch between the near-equal star and fork counts and the effort behind the artifact: a published package, readers for copybook and fixed-width formats, a mutation engine, CI templates and a written-up experiments directory with negative findings. Judge the project by the example pipelines and the model card rather than by the early growth numbers.