Policyengine Parameter Patterns

PolicyEngine Parameter Patterns

Comprehensive patterns for creating PolicyEngine parameter files.

Critical: Required Structure

Every parameter MUST have this exact structure:

description: [One sentence description].
values:
  YYYY-MM-DD: value

metadata:
  unit: [type]       # REQUIRED
  period: [period]   # REQUIRED
  label: [name]      # REQUIRED
  reference:         # REQUIRED
    - title: [source]
      href: [url]

Missing ANY metadata field = validation error

---

1. File Naming Conventions

Study Reference Implementations First

Before creating ANY parameter files, read 3-5 files from a similar program in another state. Match their structure — don't invent your own. This is the single most effective way to produce correct parameter files.

Search broadly by program concept (not just program name):

# For a childcare program, search by concept keywords:
Glob 'policyengine_us/parameters/gov/states/*/*/*child*care*/'
Glob 'policyengine_us/parameters/gov/states/*/*/*ccap*/'
Glob 'policyengine_us/parameters/gov/states/*/*/*ccfa*/'

Good references by program type:

• TANF: DC, IL, TX — /parameters/gov/states/{st}/{agency}/tanf/
• Childcare: MA CCFA, CO CCAP — /parameters/gov/states/{st}/{agency}/ccfa/ or ccap/
• LIHEAP: AZ — /parameters/gov/states/az/{agency}/liheap/

Naming Patterns

Dollar amounts → /amount.yaml

income/deductions/work_expense/amount.yaml     # $120
resources/limit/amount.yaml                    # $6,000
payment_standard/amount.yaml                   # $320

Percentages/rates → /rate.yaml or /percentage.yaml

income_limit/rate.yaml                         # 1.85 (185% FPL)
benefit_reduction/rate.yaml                    # 0.2 (20%)
income/disregard/percentage.yaml               # 0.67 (67%)

Thresholds → /threshold.yaml

age_threshold/minor_child.yaml                 # 18
age_threshold/elderly.yaml                     # 60
income/threshold.yaml                          # 30_000

---

2. Description Field

The ONLY Acceptable Formula

description: [State] [verb] [category] to [this X] under the [Full Program Name] program.

Components:

1. [State]: Full state name (Indiana, Texas, California)
2. [verb]: ONLY use: limits, provides, sets, excludes, deducts, uses
3. [category]: What's being limited/provided (gross income, resources, payment standard)
4. [this X]: ALWAYS use generic placeholder

• this amount (for currency-USD)
• this share or this percentage (for rates/percentages)
• this threshold (for age/counts)

1. [Full Program Name]: ALWAYS spell out (Temporary Assistance for Needy Families, NOT TANF)

Copy These Exact Templates

For income limits:

description: [State] limits gross income to this amount under the Temporary Assistance for Needy Families program.

For resource limits:

description: [State] limits resources to this amount under the Temporary Assistance for Needy Families program.

For payment standards:

description: [State] provides this amount as the payment standard under the Temporary Assistance for Needy Families program.

For disregards:

description: [State] excludes this share of earnings from countable income under the Temporary Assistance for Needy Families program.

Keep Descriptions Practical

Descriptions should focus on what matters for simulation, not copy regulatory language verbatim. Omit regulatory details that have no practical impact:

# ❌ Too literal — no one simulates a 1-week-old:
description: Rhode Island defines the infant/toddler age range as 1 week up to 3 years under the Child Care Assistance Program.

# ✅ Practical:
description: Rhode Island defines the infant/toddler age range as up to 3 years under the Child Care Assistance Program.

Description Validation Checklist

Run this check on EVERY description:

# Pseudo-code validation
def validate_description(desc):
    checks = [
        desc.count('.') == 1,  # Exactly one sentence
        'TANF' not in desc,     # No acronyms
        'SNAP' not in desc,     # No acronyms
        'this amount' in desc or 'this share' in desc or 'this percentage' in desc,
        'under the' in desc and 'program' in desc,
        'by household size' not in desc,  # No explanatory text
        'based on' not in desc,           # No explanatory text
        'for eligibility' not in desc,    # Redundant
    ]
    return all(checks)

CRITICAL: Always spell out full program names in descriptions!

---

3. Values Section

Format Rules

values:
  2024-01-01: 3_000    # Use underscores
  # NOT: 3000

  2024-01-01: 0.2      # Remove trailing zeros
  # NOT: 0.20 or 0.200

  2024-01-01: 2        # No decimals for integers
  # NOT: 2.0 or 2.00

Effective Dates

Use exact dates from sources:

# If source says "effective July 1, 2023"
2023-07-01: value

# If source says "as of October 1"
2024-10-01: value

# NOT arbitrary dates:
2000-01-01: value  # Shows no research

Date format: YYYY-MM-01 (always use 01 for day)

Effective Date Accuracy

Use the program's effective date, not filing or publication dates:

# Regulation filed June 5, 2003; effective January 1, 2004
❌ 2003-06-05: 500    # Filing date — WRONG
✅ 2004-01-01: 500    # Effective date — CORRECT

Beware backward extrapolation: A parameter's first entry (e.g., 2006-07-01: 20) is returned for ALL prior periods. If the program didn't exist before that date, add an explicit zero:

# ❌ Phantom $20 appears in 2005:
values:
  2006-07-01: 20

# ✅ Zero before program start:
values:
  2000-01-01: 0
  2006-07-01: 20

Don't duplicate unchanged values. If a value is the same across eras, keep one entry at the earliest applicable date.

Before removing "duplicate" date entries, verify ALL sub-categories — what looks identical at the top level may differ in specific combinations (e.g., School Age Part Time rates changed while other age/time categories stayed the same).

Flag unverified historical values in the PR description rather than silently including them.

---

4. Metadata Fields (ALL REQUIRED)

unit

Common units:

• currency-USD - Dollar amounts
• /1 - Rates, percentages (as decimals)
• month - Number of months
• year - Age in years
• bool - True/false
• person - Count of people

period

• year - Annual values
• month - Monthly values
• day - Daily values
• eternity - Never changes

Match period to the parameter's semantic meaning. A dimensionless rate or ratio should use period: year, not the period of the quantity it modifies (e.g., don't use period: week for a weekly copay rate — the rate itself is time-invariant).

label

Pattern: [State] [PROGRAM] [description]

label: Montana TANF minor child age threshold
label: Illinois TANF earned income disregard rate
label: California SNAP resource limit

Rules:

• Spell out state name
• Abbreviate program (TANF, SNAP)
• No period at end

reference

Requirements:

1. At least one source (prefer two)
2. Must contain the actual value
3. Title: Include FULL section path (all subsections and sub-subsections)
4. PDF links: Add #page=XX at end of href ONLY (never in title)
5. Verify page numbers — open the PDF and confirm the page number is correct before using it

Reference Source Hierarchy — prefer online over PDF:

1. Online statute/regulation (best): Cornell LII, state legislature sites, public.law

• Example: https://www.law.cornell.edu/regulations/rhode-island/218-RICR-20-00-4.6

1. Official government HTML page: .gov pages with section anchors
2. PDF with verified page number (last resort): Only when no online HTML version exists

• Rate schedules, policy manuals without HTML versions
• Always verify the #page=XX is correct

Why: Online references are linkable, searchable, and don't require page number verification. PDF page numbers are error-prone (file page vs printed page) and links break when documents are updated.

Title Format - Include ALL subsection levels (NO page numbers):

# ❌ BAD - Too generic:
title: OAR 461-155  # Missing subsections!
title: Section 5    # Which subsection?
title: TEA Manual, page 13  # Page number belongs in href, not title!

# ✅ GOOD - Full section path, no page number:
title: OAR 461-155-0030(2)(a)(B)     # All levels included
title: 7 CFR § 273.9(d)(6)(ii)(A)    # Federal regulation with all subsections
title: Indiana Admin Code 12-14-2-3.5(b)(1)  # State admin code
title: Arkansas TEA Manual Section 5.2.3    # Manual with section (page in href)

PDF Link Format - Always include page in href:

CRITICAL: Use the PDF file page number, NOT the printed page number inside the document.

• The #page=XX value is the page position in the PDF file (1st page = 1, 2nd page = 2, etc.)
• This may differ from the page number printed on the document itself
• Why? When users click the link, they must land directly on the page showing the referenced values

# ❌ BAD - No page number:
href: https://state.gov/manual.pdf

# ✅ GOOD - Page anchor in href (file page number):
href: https://humanservices.arkansas.gov/wp-content/uploads/TEA_MANUAL.pdf#page=13
href: https://adminrules.idaho.gov/rules/current/16/160503.pdf#page=8

Complete Examples:

✅ GOOD (page number in href only):
reference:
  - title: OAR 461-155-0030(2)(a)(B)
    href: https://oregon.public.law/rules/oar_461-155-0030
  - title: Oregon DHS TANF Policy Manual Section 4.3.2
    href: https://oregon.gov/dhs/tanf-manual.pdf#page=23

✅ GOOD:
reference:
  - title: 7 CFR § 273.9(d)(6)(ii)(A)
    href: https://www.ecfr.gov/current/title-7/section-273.9#p-273.9(d)(6)(ii)(A)
  - title: Arkansas TEA Manual Section 2100
    href: https://humanservices.arkansas.gov/wp-content/uploads/TEA_MANUAL.pdf#page=45

❌ BAD (page number in title):
reference:
  - title: Arkansas TEA Manual, page 13  # Page belongs in href!
    href: https://humanservices.arkansas.gov/wp-content/uploads/TEA_MANUAL.pdf

❌ BAD (missing info):
reference:
  - title: Federal LIHEAP regulations  # Too generic - no section!
    href: https://www.acf.hhs.gov/ocs  # No specific page
  - title: OAR 461-155  # Missing subsections (2)(a)(B)!
    href: https://oregon.gov/manual.pdf  # Missing #page=XX

Reference Verification Rules

Distinguish statute from regulation. Cite the statute that establishes a rule and the regulation that implements it separately — they are different legal instruments.

Prefer direct document URLs over landing-page or index-page URLs. Agency websites frequently reorganize navigation pages while direct document links remain stable.

Annotate reference coverage windows. When a source has a known publication cutoff (e.g., last published in 2011), note which values it corroborates — don't cite it for values postdating the cutoff.

Secondary sources (WorkWorld, SSA reports) are simplified. They may omit eligibility requirements, payment categories, or add interpretive language. Always treat the Admin Code/state regulation as authoritative; use secondary sources for cross-verification only.

Verify regulation text is present. When fetching from legal databases (Cornell LII, Westlaw), verify the content contains actual regulation body text, not just a JavaScript shell — many databases render client-side.

When a regulation portal migrates domains, update ALL parameter files referencing the old domain in one pass — broken redirects are systematic.

For state policy choices, cite the state regulation, not the federal CFR that merely sets the ceiling.

---

5. Federal/State Separation

Federal Parameters

Location: /parameters/gov/{agency}/{program}/

# parameters/gov/hhs/fpg/first_person.yaml
description: HHS sets this amount as the federal poverty guideline for one person.

State Parameters

Location: /parameters/gov/states/{state}/{agency}/{program}/

# parameters/gov/states/ca/dss/tanf/income_limit/rate.yaml
description: California uses this multiplier of the federal poverty guideline for TANF income eligibility.

---

5.5 Parameter Folder Organization

Core Principles

1. Group logically - Parameters that relate to the same aspect should be together
2. Don't create subfolder for 1 file - If only 1 parameter for an aspect, keep it at parent level
3. Payment standard at root - Main benefit amounts can stay at program root

Common Aspects (adapt to your program)

• income/ - Income limits, deductions, disregards
• eligibility/ - Age thresholds, citizenship requirements
• resources/ - Asset/resource limits

Study Existing Implementations

Each program is different. Before organizing, look at similar programs:

ls policyengine_us/parameters/gov/states/{state}/{agency}/

---

6. Common Parameter Patterns

Income Limits (as FPL multiplier)

# income_limit/rate.yaml
description: State uses this multiplier of the federal poverty guideline for program income limits.
values:
  2024-01-01: 1.85  # 185% FPL

metadata:
  unit: /1
  period: year
  label: State PROGRAM income limit multiplier

Benefit Amounts

# payment_standard/amount.yaml
description: State provides this amount as the monthly program benefit.
values:
  2024-01-01: 500

metadata:
  unit: currency-USD
  period: month
  label: State PROGRAM payment standard amount

Age Thresholds (Simple)

# age_threshold/minor_child.yaml
description: State defines minor children as under this age for program eligibility.
values:
  2024-01-01: 18

metadata:
  unit: year
  period: eternity
  label: State PROGRAM minor child age threshold

Age-Based Eligibility (Bracket Style) - PREFERRED

When eligibility depends on age ranges, use a single bracket-style parameter instead of separate min/max files.

# eligibility/by_age.yaml
description: Massachusetts determines eligibility for the Bay Transportation reduced fare program based on age.

metadata:
  threshold_unit: year
  amount_unit: bool
  period: year
  type: single_amount
  label: Massachusetts Bay Transportation reduced fare age eligibility
  reference:
    - title: MBTA Reduced Fare Program
      href: https://www.mbta.com/fares/reduced

brackets:
  - threshold:
      2024-01-01: 0
    amount:
      2024-01-01: false    # Under 18: not eligible
  - threshold:
      2024-01-01: 18
    amount:
      2024-01-01: true     # Ages 18-64: eligible
  - threshold:
      2024-01-01: 65
    amount:
      2024-01-01: false    # 65+: not eligible (different program)

Federal example (SNAP student eligibility):

# parameters/gov/usda/snap/student_age_eligibility_threshold.yaml
description: The United States includes students in this age range for SNAP eligibility.

brackets:
  - threshold:
      2018-01-01: 0
    amount:
      2018-01-01: true     # Under 18: eligible
  - threshold:
      2018-01-01: 18
    amount:
      2018-01-01: false    # Ages 18-49: not eligible (student restrictions)
  - threshold:
      2018-01-01: 50
    amount:
      2018-01-01: true     # 50+: eligible

metadata:
  type: single_amount
  threshold_unit: year
  amount_unit: bool
  label: SNAP student age eligibility threshold
  reference:
    - title: 7 U.S. Code § 2015 - Eligibility disqualifications
      href: https://www.law.cornell.edu/uscode/text/7/2015

When to use bracket-style:

• ✅ Eligibility varies by age range (eligible for ages X-Y only)
• ✅ Multiple age cutoffs affect the same benefit
• ✅ Boolean eligibility that changes at different thresholds
• ✅ Non-contiguous eligibility (e.g., eligible under 18 AND over 50, but not 18-49)

When NOT to use bracket-style:

• ❌ Single threshold (just use simple `thr

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: PolicyEngine
• Source: PolicyEngine/policyengine-claude
• License: MIT

Install and usage instructions live in the source repository linked above.