Skip to main content

​
Overview

The W2 model extracts and structures information from W2 tax forms, including employee and employer information, wage data, and tax withholdings.

​
Schema Structure

​
Form Metadata

FieldTypeDescription
W2FormVariantstring?Type of W2 form
TaxYearstring?Tax year of the form
W2Copystring?Copy type of the W2
ControlNumberstring?Form control number

​
Employee Information

FieldTypeDescription
Employee.SocialSecurityNumberstring?Employee SSN
Employee.Namestring?Employee’s full name
Employee.Addressstring?Employee’s address

​
Employer Information

FieldTypeDescription
Employer.IdNumberstring?Employer’s identification number
Employer.Namestring?Employer’s name
Employer.Addressstring?Employer’s address

​
Wage and Tax Information

FieldTypeDescription
WagesTipsAndOtherCompensationnumber?Total wages, tips, and compensation
FederalIncomeTaxWithheldnumber?Federal income tax withheld
SocialSecurityWagesnumber?Social security wages
SocialSecurityTaxWithheldnumber?Social security tax withheld
MedicareWagesAndTipsnumber?Medicare wages and tips
MedicareTaxWithheldnumber?Medicare tax withheld
SocialSecurityTipsnumber?Social security tips
AllocatedTipsnumber?Allocated tips
DependentCareBenefitsnumber?Dependent care benefits
NonQualifiedPlansnumber?Non-qualified plans
VerificationCodestring?W2 form verification code

​
Status Flags

FieldTypeDescription
IsStatutoryEmployeeboolean?Statutory employee status
IsRetirementPlanboolean?Retirement plan status
IsThirdPartySickPayboolean?Third party sick pay status
Otherstring?Other information

​
Additional Information

Each entry in the AdditionalInfo array contains:
FieldTypeDescription
LetterCodestring?IRS W2 box 12 letter code
Amountnumber?Code amount

​
State Tax Information

Each entry in the StateTaxInfos array contains:
FieldTypeDescription
Statestring?Two letter state code
EmployerStateIdNumberstring?Employer state ID number
StateWagesTipsEtcnumber?State wages and tips
StateIncomeTaxnumber?State income tax

​
Local Tax Information

Each entry in the LocalTaxInfos array contains:
FieldTypeDescription
LocalWagesTipsEtcnumber?Local wages and tips
LocalIncomeTaxnumber?Local income tax
LocalityNamestring?Locality name

​
Type Definitions

import type {
  W2Employee,
  W2Employer,
  W2AdditionalInfo,
  W2StateTaxInfo,
  W2LocalTaxInfo,
  W2,
  W2Response,
  StrictW2Response
} from '@your-package/models';

​
Validation Rules

​
Basic Validation

  • All fields are optional by default
  • Arrays (AdditionalInfo, StateTaxInfos, LocalTaxInfos) default to empty arrays if not specified

​
Strict Validation

The following fields are required in strict mode:
  • TaxYear
  • Employee.Name
  • Employee.SocialSecurityNumber
  • Employer.Name
  • Employer.IdNumber
  • WagesTipsAndOtherCompensation
  • FederalIncomeTaxWithheld

​
Example Usage

import { validateW2 } from '@your-package/models';

// Example W2 data
const w2Data = {
  TaxYear: "2024",
  Employee: {
    Name: "John A. Doe",
    SocialSecurityNumber: "123-45-6789",
    Address: "123 Main St, Springfield, IL 62701"
  },
  Employer: {
    Name: "Contoso Corporation",
    IdNumber: "12-3456789",
    Address: "456 Business Ave, Chicago, IL 60601"
  },
  WagesTipsAndOtherCompensation: 50000.00,
  FederalIncomeTaxWithheld: 7500.00,
  SocialSecurityWages: 50000.00,
  SocialSecurityTaxWithheld: 3100.00
};

// Validate the W2
const validatedW2 = validateW2(w2Data);

// Access validated data through result property
console.log(validatedW2.result.WagesTipsAndOtherCompensation);

​
Best Practices

  1. Always validate W2 forms:
const w2 = validateW2(w2Data);
  1. Access data through the result property:
const wages = w2.result.WagesTipsAndOtherCompensation;
  1. Handle optional fields appropriately:
const tips = w2.result.SocialSecurityTips || 0;
  1. Check arrays before processing:
const stateTaxes = w2.result.StateTaxInfos || [];
const localTaxes = w2.result.LocalTaxInfos || [];
  1. Verify required fields in strict mode:
if (!w2.result.Employee?.Name || !w2.result.TaxYear) {
  // Handle missing required fields
}