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:

  1. Field: type, width, format, valid value set, or numeric range.
  2. Record: required/conditional fields, uniqueness, date order, or arithmetic.
  3. Relational: parent-child keys, line identity, and coverage.
  4. Temporal: service windows, admission/discharge, and death-date ordering.
  5. Administrative: enrollment, setting, and source-specific compatibility.
  6. 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.