> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ledgerbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# W2

> Documentation for the W2 Tax Form document model

## 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

| Field           | Type    | Description          |
| --------------- | ------- | -------------------- |
| `W2FormVariant` | string? | Type of W2 form      |
| `TaxYear`       | string? | Tax year of the form |
| `W2Copy`        | string? | Copy type of the W2  |
| `ControlNumber` | string? | Form control number  |

### Employee Information

| Field                           | Type    | Description          |
| ------------------------------- | ------- | -------------------- |
| `Employee.SocialSecurityNumber` | string? | Employee SSN         |
| `Employee.Name`                 | string? | Employee's full name |
| `Employee.Address`              | string? | Employee's address   |

### Employer Information

| Field               | Type    | Description                      |
| ------------------- | ------- | -------------------------------- |
| `Employer.IdNumber` | string? | Employer's identification number |
| `Employer.Name`     | string? | Employer's name                  |
| `Employer.Address`  | string? | Employer's address               |

### Wage and Tax Information

| Field                           | Type    | Description                         |
| ------------------------------- | ------- | ----------------------------------- |
| `WagesTipsAndOtherCompensation` | number? | Total wages, tips, and compensation |
| `FederalIncomeTaxWithheld`      | number? | Federal income tax withheld         |
| `SocialSecurityWages`           | number? | Social security wages               |
| `SocialSecurityTaxWithheld`     | number? | Social security tax withheld        |
| `MedicareWagesAndTips`          | number? | Medicare wages and tips             |
| `MedicareTaxWithheld`           | number? | Medicare tax withheld               |
| `SocialSecurityTips`            | number? | Social security tips                |
| `AllocatedTips`                 | number? | Allocated tips                      |
| `DependentCareBenefits`         | number? | Dependent care benefits             |
| `NonQualifiedPlans`             | number? | Non-qualified plans                 |
| `VerificationCode`              | string? | W2 form verification code           |

### Status Flags

| Field                 | Type     | Description                 |
| --------------------- | -------- | --------------------------- |
| `IsStatutoryEmployee` | boolean? | Statutory employee status   |
| `IsRetirementPlan`    | boolean? | Retirement plan status      |
| `IsThirdPartySickPay` | boolean? | Third party sick pay status |
| `Other`               | string?  | Other information           |

### Additional Information

Each entry in the `AdditionalInfo` array contains:

| Field        | Type    | Description               |
| ------------ | ------- | ------------------------- |
| `LetterCode` | string? | IRS W2 box 12 letter code |
| `Amount`     | number? | Code amount               |

### State Tax Information

Each entry in the `StateTaxInfos` array contains:

| Field                   | Type    | Description              |
| ----------------------- | ------- | ------------------------ |
| `State`                 | string? | Two letter state code    |
| `EmployerStateIdNumber` | string? | Employer state ID number |
| `StateWagesTipsEtc`     | number? | State wages and tips     |
| `StateIncomeTax`        | number? | State income tax         |

### Local Tax Information

Each entry in the `LocalTaxInfos` array contains:

| Field               | Type    | Description          |
| ------------------- | ------- | -------------------- |
| `LocalWagesTipsEtc` | number? | Local wages and tips |
| `LocalIncomeTax`    | number? | Local income tax     |
| `LocalityName`      | string? | Locality name        |

## Type Definitions

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
const w2 = validateW2(w2Data);
```

2. Access data through the result property:

```typescript theme={null}
const wages = w2.result.WagesTipsAndOtherCompensation;
```

3. Handle optional fields appropriately:

```typescript theme={null}
const tips = w2.result.SocialSecurityTips || 0;
```

4. Check arrays before processing:

```typescript theme={null}
const stateTaxes = w2.result.StateTaxInfos || [];
const localTaxes = w2.result.LocalTaxInfos || [];
```

5. Verify required fields in strict mode:

```typescript theme={null}
if (!w2.result.Employee?.Name || !w2.result.TaxYear) {
  // Handle missing required fields
}
```