A data model for grants, rebates, forgivable loans, and repair programs
Home-repair assistance does not fit safely into a table with only a name, city, and amount. A useful model needs separate layers for record identity, service geography, benefit mechanics, published eligibility signals, timing, source evidence, localization, and operational state. Unknown facts must stay unknown.
Start from the current contract: compare the live sample records with the JSON Schema. Use dataset health for the current row and name-based identity notes, and paid readiness for the current commercial gate. Do not substitute a saved count or interpret readiness as a quality score.
Start with a city-program row
A city-program row is one served program record associated with one city. The current schema says id is stable within its city, so the safe application key includes both the city and record ID. A statewide, regional, or selected national program can appear in several cities by design.
That means city rows are discovery placements, not verified counts of separate legal programs. Do not count each repeated city association as a separate administrator, funding pool, or opportunity.
Understand the published distinct measures
The health endpoint defines distinctPrograms as unique stored program names. It defines locallyUniquePrograms as distinct names that appear in exactly one city. These are useful catalog measures, but neither is a verified registry of legal program identities.
Name-based grouping can split one program when naming varies or merge different programs that share a generic name. Before consolidating rows, compare the administrator, source URL, geography, benefit mechanics, and other evidence. Preserve the original city rows even when an analytical layer creates a tentative group.
Keep identity and presentation separate
| Layer | Examples | Modeling rule |
|---|---|---|
| Record identity | City plus id | Use the scoped key supplied by the API. Do not assume an ID is globally unique. |
| Published identity | name, source, cited URL | Retain the source wording and administrator. A name alone is not a deduplication key. |
| Analytical group | Name-based distinct estimate or a reviewed cross-city group | Label the method and do not present an inferred group as a verified legal identity. |
| User presentation | Localized description, amount label, deadline | Select localized fields independently and preserve the citation and fallback. |
Model the benefit mechanics, not only the marketing noun
Store the published assistance type without flattening unlike products:
- Grant: may not require repayment, but can still require prior approval, inspections, eligible costs, contractor controls, or continued occupancy.
- Rebate or reimbursement: may pay only after an approved purchase, installation, inspection, or submission.
- Forgivable loan: may become non-repayable only after conditions such as occupancy over time are met, and it may involve a lien.
- Deferred loan: may postpone payment until sale, transfer, refinance, or another event.
- Repayable financing: can involve underwriting, interest, fees, security, and lender terms outside a grant-discovery decision.
- Repair service or in-kind help: may provide labor, materials, assessment, or contractor payment rather than cash to a homeowner.
- Tax benefit: may reduce tax owed under separate rules and timing, not provide upfront project cash.
If a source does not establish the mechanics, store an unknown or source-specific label. Do not infer "grant" from a page title or convert a repair service into a dollar award.
Treat amount as a bundle of facts
A numeric field alone is ambiguous. Keep the numeric value, the published amount label, currency, role of the number, payment recipient, timing, cost share, repayment or forgiveness conditions, and supporting citation separate when those facts are known. The current API exposes maxAmount and localized amount-label fields, but their presence does not guarantee an award or establish every condition.
Do not sum maximums across rows, infer a household total, or assume a stored ceiling can reduce a loan. Combination and duplication-of-benefits rules require explicit administrator evidence.
Represent geography as scope, not a single string
Keep the city association used for discovery while allowing separate service-area notes such as county, state, utility territory, tribal jurisdiction, rural rule, neighborhood, or affiliate area. The selected city is not proof that a particular address qualifies.
When a product needs address-level behavior, it must use a separately reviewed geography method and still direct the user to confirm service with the administrator. Do not infer coverage from a nearby ZIP code or mailing-city label.
Keep screening signals non-decisional
Fields such as eligibilityType, incomeRequirement, specialPopulations, projectTypes, and fundingStatus can support discovery. They do not replace full program rules. The schema explicitly warns that fundingStatus can lag and that unknown requires confirmation with the administrator.
A filter result should be phrased as a possible program to research. Missing or conflicting household facts must not be silently treated as passing, failing, or qualifying.
Make provenance and localization first-class fields
Store the citation, freshness object, request identity, API version, and dataset revision with evaluation notes. A dataset revision identifies the served generation, not accuracy, freshness, rights, or suitability.
The current schema keeps names in English and defines Spanish variants for descriptions, amount labels, and deadlines. Do not translate identifiers, source names, enum values, or numeric semantics in place. Use a field-level fallback and make it clear when source-language material is unavailable.
Recommended downstream tables
- Program rows: city, ID, published identity, category, screening fields, and current served revision.
- Benefit mechanics: type, amount role, payment timing, repayment, lien, forgiveness, cost share, and unknown flags.
- Geography: discovery city plus any reviewed service-area evidence.
- Localization: one value and provenance record per language-capable field.
- Evidence: cited URL, link status, review scope, dates, and confidence fields.
- Analytical groups: optional cross-city group, grouping method, review status, and the member rows.
- Corrections: reported field, authoritative URL, source summary, review date, and disposition without applicant data.
Map the live sample into your own model
Preserve identity, evidence, unknown values, and language fallbacks before adding product-specific presentation.
Open the record schema Explore the public sampleCommon questions
Is every city row a different program?
No. A broader program can be associated with several cities. The row is a city-scoped discovery record.
Is a distinct program count a verified identity count?
No. The published measure groups unique stored names. Naming variation and generic names limit what that measure can establish.
Can a forgivable loan be stored as a grant?
Not without losing important obligations. Preserve the loan, forgiveness, lien, occupancy, and triggering conditions when the source establishes them.