Extracting Box Values From a W-2 Form

A W-2 is the friendliest document in this cluster to extract and the easiest to validate wrongly. Its fields are defined by the IRS rather than by a layout, which means the box number carries the meaning — and it means the sensible-looking checks people add are often the ones that reject correct forms.

What the numbered boxes mean

The lettered boxes identify the parties: the employee’s social security number, the employer’s identification number, the employer’s name and address, an optional control number set by the payroll system, and the employee’s name and address. The numbered boxes carry money and codes.

• Box 1 — wages, tips, other compensation. The federally taxable wage figure.
• Box 2 — federal income tax withheld.
• Box 3 — social security wages, subject to an annual cap.
• Box 4 — social security tax withheld.
• Box 5 — Medicare wages and tips, with no cap.
• Box 6 — Medicare tax withheld.
• Boxes 7 and 8 — social security tips, and allocated tips.
• Box 10 — dependent care benefits. Box 11 — distributions from nonqualified plans.
• Box 12 — up to four code-and-amount pairs.
• Box 13 — three checkboxes: statutory employee, retirement plan, third-party sick pay. Checkboxes, not text, and a model asked for “box 13” will often return prose.
• Box 14 — a free-text catch-all, discussed below.
• Boxes 15 to 20 — state and local wages, tax and identifiers.

Box 9 is unused on current revisions and appears greyed out or empty; a schema that requires it will fail on every real form. The authoritative definitions are in the IRS General Instructions for Forms W-2 and W-3, which is revised annually and is the document to read when a box behaves unexpectedly.

Boxes 1, 3 and 5 are supposed to differ

The single most common bad validation rule on a W-2 pipeline is asserting that box 1, box 3 and box 5 agree. They routinely do not, and the differences are the correct behaviour of the tax code rather than an extraction error.

Elective deferrals into a traditional retirement plan reduce box 1 and do not reduce boxes 3 and 5, because the deferral escapes income tax and not the payroll taxes. So an employee who deferred pay has a box 1 smaller than boxes 3 and 5 by exactly the deferral, which will also be reported as a box 12 code. Contributions through a cafeteria plan reduce all three. Box 3 is capped at the social security wage base and stops rising once the employee passes it, while box 5 keeps going, so a higher earner has box 5 substantially larger than box 3. And distributions from nonqualified deferred compensation can push box 1 above box 5.

What you can check instead are the ratios between a wage box and its tax box. Box 4 should be close to box 3 times the employee social security rate, and box 6 close to box 5 times the Medicare rate. The first is a tight check. The second runs high for employees over the Additional Medicare Tax threshold, because that surcharge is withheld on top and reported in the same box — so treat an excess as expected above the threshold and a shortfall as suspicious at any income.

Box 12 is four slots and a growing code list

Box 12 is printed as four sub-boxes labelled 12a, 12b, 12c and 12d. Those letters are positions on the paper, not fields with meanings. The meaning is entirely in the code letter written inside the slot, so a schema with fields named after the slot letters is a bug that will eventually produce two employees whose “box12a” values are incomparable. Model box 12 as a list of code-and-amount pairs and key on the code.

The layout trap named on this box is real. All four slots sit in one narrow visual column with the code in a tiny left compartment and the amount to its right, immediately adjacent to box 13’s checkboxes. A table-oriented extraction commonly returns one cell containing four codes and four amounts interleaved in reading order, and where a slot is blank the pairing slips by one — producing a valid-looking code attached to the wrong amount. Extract the pairs positionally, one slot at a time, and assert that each code sits to the left of the amount it is paired with.

The code list also grows. It already covers a wide range: elective deferrals under various plan sections, the cost of employer-sponsored health coverage, employer contributions to a health savings account, designated Roth contributions, uncollected tax on tips, and more. Recent revisions of the General Instructions have added codes for newly deductible categories of compensation, including qualified tips and qualified overtime, and box 14 has been split into 14a for the traditional free-text use and 14b for a Treasury tipped-occupation code.

The engineering consequence matters more than any individual code. A hard-coded enum of box 12 codes will reject a valid form the year a new code is introduced, and it will do so for every employee at a large employer at once, in filing season. Accept any code that matches the shape, quarantine the ones you do not recognise with their amounts intact, and alert rather than fail. The same reasoning applies to any schema built on a government form, which is why these pages carry a revisit date rather than being treated as settled.

The state boxes repeat

Boxes 15 through 20 — state, employer’s state ID number, state wages, state income tax, local wages, local income tax and locality name — are printed as two stacked rows, because an employee who worked in two states gets both on one form. Some employers issue additional forms instead when there are more than two.

So the state block is an array, not six scalar fields, and the sum of state wages across the rows bears no fixed relationship to box 1: two states can each tax the same wages, so the state figures may sum to more than the federal figure without anything being wrong. Locality rows nest inside a state row, and a locality with no name printed is common.

Building it

1. Identify the tax year and the copy first. The year is printed large; the copy letter determines the layout, since Copy A is the scannable version filed with the SSA and the employee holds Copy B, C and 2, which are laid out differently.
2. Extract the numbered boxes as a map from box number to value, not as named fields. The names are yours; the numbers are the form’s.
3. Extract box 12 as an ordered list of pairs, keeping the slot letter only as provenance.
4. Extract box 13 as three booleans with an ambiguous state available for a mark that cannot be resolved.
5. Run the ratio checks on boxes 3/4 and 5/6, and do not run an equality check between 1, 3 and 5.
6. Reconcile against the final payslip of the year where you have it, remembering that the cumulative figures correspond to different boxes and are not expected to agree with each other — see extracting year-to-date totals from a payslip.