Skip to main content

​
Overview

The W4 model extracts and structures information from W4 tax forms (Employee’s Withholding Certificate), including taxpayer information, filing status, and withholding adjustments.

​
Schema Structure

​
Form Metadata

FieldTypeDescription
TaxYearstring?Tax year for W-4 form submission

​
Taxpayer Information

FieldTypeDescription
TaxPayer.FirstNameAndInitialsstring?Taxpayer’s first name and initials
TaxPayer.LastNamestring?Taxpayer’s last name
TaxPayer.Addressstring?Taxpayer’s mailing address
TaxPayer.SSNstring?Taxpayer’s Social Security Number

​
Employer Information

FieldTypeDescription
Employer.NameAndAddressstring?Employer’s full name and address
Employer.EmploymentFirstDatestring?First date of employment
Employer.EINstring?Employer’s Identification Number

​
Filing Status and Options

FieldTypeDescription
FilingStatusstring?Taxpayer’s filing status
Box2cCheckBoxboolean?Multiple jobs or spouse works indicator

​
Dependents and Withholding

FieldTypeDescription
Box3number?Total amount claimed for dependents
Box3ChildrenUnder17number?Amount claimed for children under 17
Box3OtherDependentsnumber?Amount claimed for other dependents

​
Additional Income and Deductions

FieldTypeDescription
Box4anumber?Other income for withholding consideration
Box4bnumber?Deductions other than standard deduction
Box4cnumber?Extra amount for tax withholding per paycheck

​
Type Definitions

import type {
  W4TaxPayer,
  W4Employer,
  W4,
  W4Response,
  StrictW4Response
} from '@your-package/models';

​
Validation Rules

​
Basic Validation

  • All fields are optional by default

​
Strict Validation

The following fields are required in strict mode:
  • TaxYear
  • TaxPayer.FirstNameAndInitials
  • TaxPayer.LastName
  • TaxPayer.SSN
  • FilingStatus

​
Example Usage

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

// Example W4 data
const w4Data = {
  TaxYear: "2024",
  TaxPayer: {
    FirstNameAndInitials: "John A.",
    LastName: "Doe",
    SSN: "123-45-6789",
    Address: "123 Main St, Springfield, IL 62704"
  },
  FilingStatus: "Single",
  Box2cCheckBox: false,
  Box3: 3000.00,
  Employer: {
    NameAndAddress: "ABC Corp, 123 Corporate Dr",
    EmploymentFirstDate: "2024-01-01",
    EIN: "12-3456789"
  }
};

// Validate the W4
const validatedW4 = validateW4(w4Data);

// Access validated data through result property
console.log(validatedW4.result.TaxPayer.FirstNameAndInitials);

​
Date Handling

The model accepts dates in multiple formats:
  • ISO 8601 datetime strings
  • YYYY-MM-DD format
All dates are converted to ISO format during validation.

​
Best Practices

  1. Always validate W4 forms:
const w4 = validateW4(w4Data);
  1. Access data through the result property:
const taxpayer = w4.result.TaxPayer;
  1. Handle optional fields appropriately:
const box3Amount = w4.result.Box3 || 0;
  1. Verify required fields in strict mode:
if (!w4.result.TaxPayer?.FirstNameAndInitials || !w4.result.FilingStatus) {
  // Handle missing required fields
}
  1. Handle nested objects carefully:
const employerInfo = w4.result.Employer || {};
const employmentDate = employerInfo.EmploymentFirstDate;