Data intake validation

The validator exists so that the person supplying data finds out immediately whether what they supplied is adequate — not days later when an analysis quietly produces nothing, or worse, produces a number built on a column that didn't parse. You drop a file; within the same second you get a verdict, the specific rows and cells behind that verdict, and a list of which analyses the data as supplied can and cannot feed.

Everything runs inside your browser. Files are read locally, parsed locally and judged locally. No upload occurs during validation.

The three verdicts

A verdict is always relative to the enabled checks. Disable a check and its findings stop counting; the verdict recomputes instantly.

How a file is judged

1. Parse. The format is detected from the bytes, never from the filename: spreadsheet workbooks by their zip signature, JSON and NDJSON by structure, tab- versus comma-delimited by the header line, fixed-width remittance and payroll registers by their record layout, and statement letters by their prose. Comment banners are stripped and noted.
2. Identify. The parsed columns and field names are scored against the signature of every known document type. The best match wins; the margin to the runner-up is itself a check, so a file that could be two things tells you so instead of guessing silently. A filename like final_v2 (3).xlsx affects nothing.
3. Validate. Every enabled check that applies to the identified type runs over every row. Findings carry the row number, the column and the offending value.
4. Verdict. Errors ⇒ INADEQUATE; warnings only ⇒ ISSUES; neither ⇒ READY.
5. Cross-file. Once more than one document is present, set-level checks join them: do the invoice's members appear in the census, do child files reference known employees, does the rate sheet cover the plans the census uses.

If the identifier picks the wrong type — or the margin warning asks you to confirm — the type selector on the file card overrides it, and every check re-runs against the corrected type.

Document types

Eleven document types are recognized. Required fields are the fields the type cannot work without — each row below lists the accepted spellings, since every payroll and carrier system names columns differently; any one spelling in a group satisfies it. Optional fields enrich the analyses but their absence never blocks intake.

File formats

Every check

Each check is one checkbox in the validator. Severity decides what a finding does to the verdict: an error makes the file INADEQUATE, a warning makes it ISSUES, an info finding changes nothing. The how to fix column is addressed to the person who exported the file.

Tuning, and the required-fields filter

Validation strictness is a decision, not a constant. Two controls exist:

Per-check checkboxes

Every check can be switched off individually. The live count next to each checkbox shows how many findings that check is currently producing across all dropped files, so you can see before toggling exactly what you are about to silence or surface. Verdicts recompute the moment a box changes.

Required fields only

The Required fields only switch narrows the value-level checks — blanks, unreadable dates, malformed amounts, unrecognized tiers — to the columns the document type is required to carry. A census with a messy optional location column stops failing on it; a census with a blank tier still fails, because the tier is load-bearing.

Use it when onboarding a new data supplier: first get the required fields clean and the file to READY, then switch it off and work through the optional-column warnings at leisure. The two views are the same engine with a different scope, so nothing is hidden — only deferred.

Cross-file checks

Single files can be individually perfect and still describe different worlds. The set-level checks run automatically once two or more documents are present:

• Invoice members appear in the census. If fewer than half of the invoice's people can be found in the census, the pairing is wrong — wrong group, wrong month, or wrong census — and the reconciliation would be fiction. This is an error.
• Child files reference known employees. Dependent, deduction, compensation, org, offer/waiver and state-program rows whose employee id is absent from the census cannot be joined to anyone; each orphaned file is flagged with a count and an example id.
• The rate sheet covers the census plans. A plan+tier in use with no rate row has no entitled premium, so those members silently fall out of rate verification. Missing plans are listed by name.

What the data feeds

Each analysis needs specific document types. The validator's analysis strip lights up as adequate files arrive; this is the same table.

Supplying adequate data — a checklist for the data provider

The two files below unlock the core work. Everything else widens it.

Start with these two

• Carrier invoice — the carrier's own bill for one period, exactly as received: the block export, the fixed-width remittance file, or the statement letter all work. Do not retype it and do not trim the totals section; the stated totals are checked against the detail lines.
• Benefit census — one row per enrolled employee from the HRIS or ben-admin system, carrying the employee id, the plan, the coverage tier and the monthly cost, with effective dates.

Then, as available

• Dependent file with birth dates — unlocks the aging-out audit.
• Payroll deduction register — must state its pay frequency; per-pay amounts without a frequency cannot be converted to monthly and are rejected. Unlocks deduction verification.
• Compensation extract — salary or hourly basis; if it carries an employee-only contribution figure, the column must say whether it is monthly or per-pay. Unlocks affordability testing.
• Rate sheet, renewal proposal, prior invoices, org structure, offer / waiver tracking, state retirement roster — each unlocks the analyses shown in the table above.

Ground rules that prevent round trips

• Export, never retype. Retyping creates the arithmetic drift the totals check exists to catch.
• One billing period per file.
• Keep the header row; keep the system's own column names — the identifier knows the common spellings, and unfamiliar ones are a warning, not a failure.
• Blank cells in identifier, tier or amount columns are the single most common cause of an INADEQUATE verdict. Fill them or remove the rows deliberately.
• Dates in any of YYYY-MM-DD, MM/DD/YYYY or YYYYMMDD; amounts as plain numbers with at most two decimals.

Troubleshooting