Provenance and validation
The project distinguishes “the value is structurally usable” from “the value is supported by evidence” and from “the value is representative of Medicare.” Those are different claims.
Provenance statuses
Every extension or transformed field should carry one of these statuses:
| Status | Meaning |
|---|---|
PRESERVED |
Copied from an official synthetic baseline without semantic modification. |
NORMALIZED |
Typed or reformatted while retaining the baseline meaning and recoverable raw value. |
REKEYED |
Identifier replaced deterministically to support expansion or release isolation. |
DERIVED |
Calculated deterministically from documented source fields. |
IMPUTED |
Completed conditionally where the source or target layout lacks a value. |
SYNTHESIZED |
Generated by an explicit statistical or rule-based model. |
EXTERNALLY_CALIBRATED |
Adjusted toward a documented external aggregate target. |
SCENARIO_GENERATED |
Created intentionally for a named test or teaching case. |
The status is a disclosure, not a quality score. A preserved value can still come from a synthetic source; a synthesized value can still be useful for a specific test.
Validation boundaries
Validation is layered so a failure says which contract needs attention:
- Field: type, width, format, valid value set, or numeric range.
- Record: required/conditional fields, uniqueness, date order, or arithmetic.
- Relational: parent-child keys, line identity, and coverage.
- Temporal: service windows, admission/discharge, and death-date ordering.
- Administrative: enrollment, setting, and source-specific compatibility.
- Accounting: non-negative payments, charges, deductibles, coinsurance, and utilization counts.
A validator report contains a boolean status and structured findings. Use the CLI for a quick check:
uv run medicare-synth validate --scenario invalid_temporal_inversion
Or compose it in Python:
from medicare_synth import RelationalValidator, ScenarioCompiler
slice_data = ScenarioCompiler.valid_baseline_cohort()
report = RelationalValidator().validate_slice(slice_data)
assert report.is_valid
Fidelity claims
The strongest supported public claims are structural: a release has a declared grain, explicit keys, deterministic generation, and the checks recorded in its validation report. Passing those checks does not establish national representativeness, causal validity, clinical realism, or formal privacy.
When documenting a release, name the source year, evidence snapshot, methods, provenance statuses, checks run, known deviations, and unmodeled behavior. The release workflow shows where those disclosures are written.