Repository navigation
Add a New State
This page walks you through adding a state to OpenBridge: a new adapter file, its test cases, and the records that go with it. It is for contributors who can edit JSON and run commands, ideally working with someone who knows that state's benefit rules.
The checklist here comes from "Adding a state" in
.kiro/steering/eligibility-rules.md and
from docs/STATE_ADAPTERS.md. If they change, they
win.
A new state ships as
draft. It is not "done" until a subject-matter expert signs off, and nobody but that expert marks it verified.
- Open a "New state request or offer" issue so others know you are working on it.
- Gather the official sources for every value: SNAP limits and whether the state uses broad-based categorical eligibility (BBCE), Medicaid and CHIP limits by group and age, WIC, LIHEAP, and TANF limits, and each program's official application site.
- Set up the code. See Developer setup.
-
Pick the closest existing adapter and copy it to
data/states/<code>/adapter.json, with a lowercase folder name (for exampledata/states/pa/):- Washington (
wa): Medicaid expansion, SNAP BBCE at 200%. - Ohio (
oh): Medicaid expansion, SNAP BBCE at 130%. - Texas (
tx): no Medicaid expansion, no SNAP BBCE (net income and asset tests apply).
- Washington (
-
Replace every value from a cited source. Update
stateCode,stateName,medicaidExpansion, eachprogramsblock, andportalUrls. Do not keep a copied number because it looks about right. If you cannot source a program, leave that program out rather than guess; the engine returnsunknownfor it. -
Write
sources[]with one entry per value:field,sourceName,url,publishedDate, and an optionalnote. The validator fails if any configured program has no source. -
Leave
verificationStatus: "draft"and setlastVerifiedByto apending-...value. -
Add the golden test cases in
data/states/<code>/fixtures/. Cover each of these:- a clear pass and a clear fail;
- a threshold boundary, just under and just over;
- a near-threshold
possibly_eligible; - categorical or adjunctive eligibility (for example a household that already gets cash assistance);
- an elderly or disabled household;
- a mixed-status household;
- for a state without Medicaid expansion, children eligible while parents are not.
See Golden test cases for the format. The
/reviewpage can draft them for you. -
Register the state in the web app. The app bundles adapters by import, so add your adapter to the
adapterslist inpackages/web-app/src/data/index.ts. The scripts and the MCP server find states by reading thedata/states/folder. -
Run the checks:
npm run validate:adapters && npm run test:fixtures npm run verify -
Add a pending row for the state in
docs/SME_SIGNOFF.md, with the reviewer as_pending_. -
Add a line to
CHANGELOG.mdunder## [Unreleased], for example in aDatagroup: "Draft adapter for Pennsylvania, pending expert review." -
Open a pull request using the template, linking the issue and listing every source.
A maintainer reviews the pull request. A subject-matter expert then checks the values, sources,
and test cases. Only when they approve does the SME_SIGNOFF.md row become Approved and the
adapter become verified. Until then the app shows that the rules are drafts.
OpenBridge is a prototype. Its rules are drafts that experts have not verified yet, and results are
estimates, not decisions. It is not legal advice. Need help applying for benefits? Call 211 or visit
211.org. This wiki is edited in the wiki/ folder of the repository.
Questions: openbridge@starlingtek.com.
Start here
Use OpenBridge
- Using OpenBridge
- Understanding your results
- Guide for navigators
- Privacy and your data
- Run it on your computer
- Host it for others
- Use it with an AI assistant
Help without code
- Ways to help
- Review rules as an expert
- Record a test case
- Report a rule problem
- Translate OpenBridge
- Test accessibility
- Community rule toolkit
Rules and policy (with code)
- How the rules engine works
- State adapters
- Add or change a rule
- Add a new state
- Golden test cases
- Yearly data updates
Developers