modeling

27 annotations

schema application.authorizedRepresentatives[].type
Polymorphic discriminator; id points to application.contacts[].id when type = individual and application.organizations[].id when type = organization.
schema application.childSupport.parentsOutsideHome[].children[]
Array because one non-custodial parent may be the parent of multiple children in the household.
schema application.deductions[]
Some intake forms do not collect per-member deduction attribution; in those cases the adapter assigns deduction records to the primary applicant or the tax filer. States whose forms collect per-member attribution should map directly to that member.
schema application.deductions[].type
Stored at the application level with a memberId FK for per-member attribution. When a state's intake form does not associate deductions with specific members, the adapter should assign deduction records to the primary applicant. For prior_period records, only amount is relevant and all other fields are inapplicable.
schema application.healthPlans[]
Medicare plans use a single healthPlan record per person (type = medicare) with named sub-objects for each part (partA, partB, partC, partD). Parts A–D are a fixed closed set, so named sub-objects are cleaner than a discriminated array.
schema application.healthPlans[].medicareId
Treat as PII. The MBI replaced the SSN-based Health Insurance Claim Number (HICN) in 2018–2020.
schema application.healthPlans[].organizationId
Applies only when type = employer_sponsored or cobra.
schema application.healthPlans[].partA.premiumPaidBy
Stored as a controlled enum [self, state, employer, other] rather than free text to support automated MSP determination logic without string matching.
schema application.healthPlans[].partA.status
entitled = meets eligibility criteria but not yet actively receiving benefits (e.g., deferred Part B enrollment while on employer coverage); enrolled = actively receiving.
schema application.healthPlans[].partB.premiumPaidBy
Stored as a controlled enum [self, state, employer, other] rather than free text to support automated MSP determination logic without string matching.
schema application.healthPlans[].partC.premiumPaidBy
Stored as a controlled enum [self, state, employer, other] rather than free text to support automated MSP determination logic without string matching.
schema application.healthPlans[].partC.status
Part C replaces traditional Parts A and B — a member enrolled in Part C should not also have Part A and Part B populated.
schema application.healthPlans[].partD.premiumPaidBy
Stored as a controlled enum [self, state, employer, other] rather than free text to support automated MSP and Low Income Subsidy determination logic without string matching.
schema application.healthPlans[].premiumAmount
A null value means the premium amount is unknown, not that no premium exists. Adapters should preserve null rather than defaulting to zero when the applicant cannot provide the amount.
schema application.householdInfo.roomers[].mealsIncludedWithRent
Boarders are not modeled as a separate type — they are roomers where mealsIncludedWithRent = true. A single roomers[] array with this boolean covers both cases without a discriminated union.
schema application.incomes[]
For prior_period records, only amount is relevant; frequency is inapplicable and jobId should be populated where the source is known.
schema application.incomes[].amount
Stored as reported (per-period amount) rather than normalized to monthly, to preserve the precision of the applicant's reported figure and allow adapters to apply program-specific normalization methods.
schema application.incomes[].frequency
frequency = variable means amount is the projected annual income, not a per-period figure. Applies to employed and self_employed types only.
schema application.incomes[].jobId
uuid type because it is a foreign key reference, not a free-text identifier.
schema application.members[].citizenship.sponsored.hasBeenAbandonedBySponsor
Kept separate from hasBeenMistreatedBySponsor because abandonment (documented through lack of financial support or sponsor departure) and battery/mistreatment (VAWA-based, requiring police reports, court orders, or professional statements) have distinct legal bases and different verification pathways. Forms that combine them into a single yes/no require a state overlay.
schema application.members[].citizenship.sponsored.hasBeenMistreatedBySponsor
Kept separate from hasBeenAbandonedBySponsor; see that field's design note for the rationale.
schema application.members[].personalInformation.races[]
Array to comply with OMB standards requiring that individuals be able to select all applicable races simultaneously.
schema application.members[].programsAppliedFor[]
A member's selection must be a subset of the household-level programsAppliedFor[] selection.
schema application.personRelationships[]
Convention — from IS THE [relationshipType] OF to. Storing both directions (A→B parent, B→A child) means callers can query from = X to get all of X's relationships with the correct type label without requiring bidirectional joins.
schema application.signatures[].purpose
Discriminator enabling each signature event to be stored and audited independently on the same application record.
schema application.taxFilers[].dependents[].type
Polymorphic discriminator enabling FK linkage for both household members (via application.members[].id) and non-household dependents (via application.contacts[].id).
schema application.taxFilers[].memberId
A null memberId encodes a non-household filer (e.g. a non-custodial parent not on this application). This is the mechanism for representing filers whose name and identity are not already in application.members[].