How to add a new state or territory - 18F/snap-js-api-prototype GitHub Wiki

This documentation is meant for web developers.

There are two chunks of work to add a new state or territory to this SNAP eligibility API:

1. Look up the state or territory's SNAP rules and add them to the state_options.js file.
2. Add an integration test for the state. (examples)

Adding state options

All states and territories share a core set of federal SNAP eligibility rules. At the same time: "SNAP’s statutes, regulations, and waivers provide state agencies with various policy options that enable state agencies to adapt their programs to meet the unique needs of states" (source).

We express these differences as configuration in the project state_options.js file.

Here is an example of the shape of this data:

'IL': {
    '2020': {
        // Broad-based categorical eligibility, resource and income limits:
        'uses_bbce': true,
        'resource_limit_elderly_or_disabled': null,
        'resource_limit_elderly_or_disabled_income_twice_fpl': 3500,
        'resource_limit_non_elderly_or_disabled': null,
        'gross_income_limit_factor': 1.65,
        // State deduction options:
        'child_support_payments_treatment': 'EXCLUDE',
        'standard_medical_deduction': true,
        'standard_medical_deduction_amount': 200,
        'standard_medical_deduction_ceiling': 200,
        'standard_utility_allowances': {
            'BASIC_LIMITED_ALLOWANCE': 328,
            'HEATING_AND_COOLING': 478,
            'PHONE': 30,
            'SINGLE_UTILITY_ALLOWANCE': 74
        }
    }
}

To add a new state or territory to the file:

1. Add the state key (examples: "VA", "IL") to the outermost layer of the config option. Use the U.S. Postal Abbreviation of the state or territory for this key.
2. Add the current year to the next level. This helps us pin each set of state configuration to a point in time.
3. Add information about Broad-Based Categorical Eligibility, income and asset limits. (See below.)
4. Add information about state deduction options. (See below.)

BBCE, income, and asset limits

See the USDA Broad-Based Categorical Eligibility Chart PDF from December 2019 for information about these fields.

uses_bbce

Broad-Based Categorical Eligibility (BBCE) is a state option that allows states to customize their own income and asset limits for SNAP eligibility.

If a state or territory is listed in the Broad-Based Categorical Eligibility Chart, set uses_bbce: true; otherwise set uses_bbce: false. For this step, and every step in this document, it's best if you can double-check with someone who knows the state or territorial SNAP program well, such as a human services staffer or a legal aid attorney.

resource_limit_elderly_or_disabled, resource_limit_non_elderly_or_disabled, resource_limit_elderly_or_disabled_income_twice_fpl

Use the "Asset Limit of TANF/MOE Program" column in the USDA Broad-Based Categorical Eligibility Chart to determine the values for these fields.

gross_income_limit_factor

Use the "Gross Income Limit of TANF/MOE Program" column in the USDA Broad-Based Categorical Eligibility Chart to determine the value for this field.

Deductions

Figuring out the exact rules for state SNAP deductions can be tricky. You might find different or contradictory information across the USDA State Options Report, legal aid websites, and other sources. The most authoritative source is the state or territory's SNAP manual.

That said, the most recent USDA State Options Report is a starting point.

child_support_payments_treatment

Some states treat court-ordered child support payments as a deduction (from gross to net income) for SNAP purposes, others exclude it from gross income entirely. Check the Treatment of Child Support Payments page in the most recent USDA State Options Report, or consult the state SNAP manual or a local expert.

standard_medical_deduction, standard_medical_deduction_amount, standard_medical_deduction_ceiling

Some states allow a standard medical deduction for elderly or disabled household members whose unreimbursed medical expenses come to more than $35 monthly. The Demonstrations for the Elderly and Disabled page in the most recent USDA State Options Report gives a little bit of information on this topic, but consulting the state SNAP manual or a local expert is best.

• standard_medical_deduction (boolean): Does the state allow for a standard medical deduction?
• standard_medical_deduction_amount (number): What is the standard medical deduction amount?
• standard_medical_deduction_ceiling (number): Beyond what medical expense amount should we stop using the standard deduction and use the medical expenses amount?

standard_utility_allowances

Some states allow households to deduct a standard amount for utility bills rather than actual utility costs. Because states implement standard utility allowances (SUAs) differently, depending on the state, you may need to write some custom code within the ShelterDeduction class to handle a state's logic.

For example, USDA says: "SUA’s vary based on household size in Arizona, Guam, Hawaii, North Carolina, Tennessee, and Virginia. SUA’s vary based on location in Alaska and New York." (source)

The USDA website on Standard Utility Allowance contains data on SUAs by state; however, checking the state SNAP manual or a local expert for the most up-to-date information is a good idea.

Adding tests

Once you've added a state's data to the state_options.js file, please add integration tests to verify what you've added. These tests are written in a programming language called Gherkin, which is meant to be readable by non-programmers and programmers alike.

See the /features folder for examples. Depending on the level at which you'd like to use the API, you may need more or fewer tests.

You may want to experiment with writing and editing the Gherkin tests collaboratively with a state policy or legal expert in SNAP. If you experiment with this, please let us know how it goes!