Household

A group of people who apply for benefits together.

HouseholdBase

The persistent eligibility data record for a group of people applying for benefits together. Accumulates over time as the household fills out additional forms.

Property	Type	Required	Description
`id`	`uuid`	Yes	The household's unique identifier.
`addresses`	`AddressCollection`	No	The household's residential, mailing, and other addresses.
`members`	`PersonBase`[]	Yes	The members of the household. At least one member is required.
`relationships`	`HouseholdRelationship`[]	No	Relationships between members of the household.
`customFields`	`RecordCustomField`	No	Implementation-defined custom fields.
`createdAt`	`string`	Yes	The timestamp (in UTC) at which the record was created.
`lastModifiedAt`	`string`	Yes	The timestamp (in UTC) at which the record was last modified.

{
  "id": "50a12e5e-5940-4c08-921c-17a8960fcf4b",
  "members": [
    {
      "identifiers": {
        "systemId": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
        "ssn": "123-45-6789"
      },
      "name": {
        "prefix": "Ms.",
        "firstName": "Jane",
        "lastName": "Smith"
      },
      "dateOfBirth": "1985-03-15",
      "isHeadOfHousehold": true,
      "legalProfile": {
        "citizenshipStatus": {
          "value": "us_citizen",
          "description": ""
        },
        "immigrationStatus": {
          "value": "not_applicable",
          "description": ""
        }
      },
      "healthProfile": {
        "disability": {
          "status": {
            "value": "none",
            "description": ""
          }
        },
        "pregnancy": {
          "status": {
            "value": "not_pregnant",
            "description": ""
          }
        }
      },
      "workProfile": {
        "employmentStatus": {
          "value": "employed_part_time",
          "description": "Part-time retail"
        },
        "studentStatus": {
          "value": "not_enrolled",
          "description": ""
        },
        "hoursWorkedPerWeek": 20,
        "caregiverStatus": {
          "value": "none",
          "description": ""
        }
      },
      "incomeSources": [
        {
          "type": {
            "value": "wages",
            "description": "Part-time retail"
          },
          "amount": {
            "amount": "1200",
            "currency": "USD"
          },
          "frequency": {
            "value": "monthly",
            "description": ""
          }
        }
      ]
    }
  ],
  "createdAt": "2026-05-24T10:00:00Z",
  "lastModifiedAt": "2026-05-24T10:00:00Z"
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: HouseholdBase.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: The household's unique identifier.
  addresses:
    $ref: AddressCollection.yaml
    description: The household's residential, mailing, and other addresses.
  members:
    type: array
    items:
      $ref: PersonBase.yaml
    description: The members of the household. At least one member is required.
  relationships:
    type: array
    items:
      $ref: HouseholdRelationship.yaml
    description: Relationships between members of the household.
  customFields:
    $ref: "#/$defs/RecordCustomField"
    description: Implementation-defined custom fields.
  createdAt:
    type: string
    format: date-time
    description: The timestamp (in UTC) at which the record was created.
  lastModifiedAt:
    type: string
    format: date-time
    description: The timestamp (in UTC) at which the record was last modified.
required:
  - id
  - members
  - createdAt
  - lastModifiedAt
examples:
  - id: 50a12e5e-5940-4c08-921c-17a8960fcf4b
    members:
      - identifiers:
          systemId: 30a12e5e-5940-4c08-921c-17a8960fcf4b
          ssn: 123-45-6789
        name:
          prefix: Ms.
          firstName: Jane
          lastName: Smith
        dateOfBirth: 1985-03-15
        isHeadOfHousehold: true
        legalProfile:
          citizenshipStatus:
            value: us_citizen
            description: ""
          immigrationStatus:
            value: not_applicable
            description: ""
        healthProfile:
          disability:
            status:
              value: none
              description: ""
          pregnancy:
            status:
              value: not_pregnant
              description: ""
        workProfile:
          employmentStatus:
            value: employed_part_time
            description: Part-time retail
          studentStatus:
            value: not_enrolled
            description: ""
          hoursWorkedPerWeek: 20
          caregiverStatus:
            value: none
            description: ""
        incomeSources:
          - type:
              value: wages
              description: Part-time retail
            amount:
              amount: "1200"
              currency: USD
            frequency:
              value: monthly
              description: ""
    createdAt: 2026-05-24T10:00:00Z
    lastModifiedAt: 2026-05-24T10:00:00Z
description: |-
  The persistent eligibility data record for a group of people applying for
  benefits together. Accumulates over time as the household fills out
  additional forms.
$defs:
  RecordCustomField:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: CustomField.yaml

/** The persistent eligibility data record for a group of people applying for
 * benefits together. Accumulates over time as the household fills out
 * additional forms.
 */
@example(Examples.Household.singleAdult)
@Versioning.added(Versions.v0_1)
model HouseholdBase {
  /** The household's unique identifier. */
  id: Types.uuid;

  /** The household's residential, mailing, and other addresses. */
  addresses?: Fields.AddressCollection;

  /** The members of the household. At least one member is required. */
  members: PersonBase[];

  /** Relationships between members of the household. */
  relationships?: HouseholdRelationship[];

  /** Implementation-defined custom fields. */
  customFields?: Record<Fields.CustomField>;

  /** Standard system metadata (createdAt, lastModifiedAt). */
  ...Fields.SystemMetadata;
}

HouseholdRelationship

A directed edge between two members of a household describing how they are related (e.g., parent → child).

Property	Type	Required	Description
`fromMemberId`	`uuid`	Yes	The unique identifier of the source member (`PersonIdentifiers.systemId`).
`toMemberId`	`uuid`	Yes	The unique identifier of the target member.
`relationshipType`	`HouseholdRelationshipType`	Yes	The type of relationship (from → to).

{
  "fromMemberId": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "toMemberId": "40a12e5e-5940-4c08-921c-17a8960fcf4b",
  "relationshipType": {
    "value": "parent",
    "description": ""
  }
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: HouseholdRelationship.yaml
type: object
properties:
  fromMemberId:
    $ref: uuid.yaml
    description: The unique identifier of the source member (`PersonIdentifiers.systemId`).
  toMemberId:
    $ref: uuid.yaml
    description: The unique identifier of the target member.
  relationshipType:
    $ref: HouseholdRelationshipType.yaml
    description: The type of relationship (from → to).
required:
  - fromMemberId
  - toMemberId
  - relationshipType
examples:
  - fromMemberId: 30a12e5e-5940-4c08-921c-17a8960fcf4b
    toMemberId: 40a12e5e-5940-4c08-921c-17a8960fcf4b
    relationshipType:
      value: parent
      description: ""
description: |-
  A directed edge between two members of a household describing how they
  are related (e.g., parent → child).

/** A directed edge between two members of a household describing how they
 * are related (e.g., parent → child).
 */
@example(Examples.Household.parentChild)
@Versioning.added(Versions.v0_1)
model HouseholdRelationship {
  /** The unique identifier of the source member (`PersonIdentifiers.systemId`). */
  fromMemberId: Types.uuid;

  /** The unique identifier of the target member. */
  toMemberId: Types.uuid;

  /** The type of relationship (from → to). */
  relationshipType: HouseholdRelationshipType;
}

HouseholdRelationshipType

The type of a relationship between two household members.

Property	Type	Required	Description
`value`	`HouseholdRelationshipTypeOptions`	Yes	The selected value, typed to `T`.
`customValue`	`string`	No	Caller-defined value when `value` is the `custom` option (or otherwise does not fit a predefined option in `T`).
`description`	`string`	No	Human-readable description or annotation for the value.

{
  "value": "spouse",
  "customValue": "string",
  "description": "string"
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: HouseholdRelationshipType.yaml
type: object
properties:
  value:
    $ref: HouseholdRelationshipTypeOptions.yaml
    description: The selected value, typed to `T`.
  customValue:
    type: string
    description: |-
      Caller-defined value when `value` is the `custom` option (or otherwise
      does not fit a predefined option in `T`).
  description:
    type: string
    description: Human-readable description or annotation for the value.
required:
  - value
description: The type of a relationship between two household members.

/** The type of a relationship between two household members. */
@Versioning.added(Versions.v0_1)
model HouseholdRelationshipType is Fields.ExtensibleEnumT<HouseholdRelationshipTypeOptions>;

// #########################################################
// HouseholdRelationship
// #########################################################

/** A directed edge between two members of a household describing how they
 * are related (e.g., parent → child).
 */
@example(Examples.Household.parentChild)
@Versioning.added(Versions.v0_1)
model HouseholdRelationship {
  /** The unique identifier of the source member (`PersonIdentifiers.systemId`). */
  fromMemberId: Types.uuid;

  /** The unique identifier of the target member. */
  toMemberId: Types.uuid;

  /** The type of relationship (from → to). */
  relationshipType: HouseholdRelationshipType;
}

HouseholdRelationshipTypeOptions

Predefined set of household relationship types.

Value	Description
`spouse`	Spouse.
`domestic_partner`	Domestic partner.
`parent`	Parent (biological, adoptive, or step).
`child`	Child (biological, adoptive, or step).
`sibling`	Sibling.
`tax_dependent`	Tax dependent.
`cohabitant`	Cohabitant not otherwise related.
`legal_guardian`	Legal guardian.
`foster_parent`	Foster parent.
`foster_child`	Foster child.
`custom`	A caller-defined relationship.

"spouse"

$schema: https://json-schema.org/draft/2020-12/schema
$id: HouseholdRelationshipTypeOptions.yaml
type: string
enum:
  - spouse
  - domestic_partner
  - parent
  - child
  - sibling
  - tax_dependent
  - cohabitant
  - legal_guardian
  - foster_parent
  - foster_child
  - custom
description: |-
  Predefined set of household relationship types.

  - `spouse`: Spouse.
  - `domestic_partner`: Domestic partner.
  - `parent`: Parent (biological, adoptive, or step).
  - `child`: Child (biological, adoptive, or step).
  - `sibling`: Sibling.
  - `tax_dependent`: Tax dependent.
  - `cohabitant`: Cohabitant not otherwise related.
  - `legal_guardian`: Legal guardian.
  - `foster_parent`: Foster parent.
  - `foster_child`: Foster child.
  - `custom`: A caller-defined relationship.

/** Predefined set of household relationship types.
 *
 * - `spouse`: Spouse.
 * - `domestic_partner`: Domestic partner.
 * - `parent`: Parent (biological, adoptive, or step).
 * - `child`: Child (biological, adoptive, or step).
 * - `sibling`: Sibling.
 * - `tax_dependent`: Tax dependent.
 * - `cohabitant`: Cohabitant not otherwise related.
 * - `legal_guardian`: Legal guardian.
 * - `foster_parent`: Foster parent.
 * - `foster_child`: Foster child.
 * - `custom`: A caller-defined relationship.
 */
@Versioning.added(Versions.v0_1)
enum HouseholdRelationshipTypeOptions {
  spouse,
  domestic_partner,
  parent,
  child,
  sibling,
  tax_dependent,
  cohabitant,
  legal_guardian,
  foster_parent,
  foster_child,
  custom,
}