Eligibility determination

An eligibility decision and supporting rationale for a household and program.

EligibilityDeterminationBase

A point-in-time eligibility outcome for a specific Enrollment.

Property	Type	Required	Description
id	uuid	Yes	The determination's unique identifier.
household	DeterminationHousehold	Yes	Reference to the household data used for this determination.
outcome	DeterminationOutcome	Yes	The outcome of the determination.
estimatedBenefit	DeterminationEstimatedBenefit | null	No	The estimated benefit, if eligible and the amount is calculable.
basis	DeterminationBasis	Yes	The basis on which the determination was made.
determinedAt	string	Yes	The timestamp at which the determination was made.
producedBy	DeterminationProducer	Yes	Provenance information for the determination.

Example

{
  "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "household": {
    "id": "40a12e5e-5940-4c08-921c-17a8960fcf4b",
    "revisionId": "50a12e5e-5940-4c08-921c-17a8960fcf4b",
    "snapshot": null
  },
  "outcome": {
    "value": "eligible",
    "description": ""
  },
  "estimatedBenefit": {
    "amount": {
      "amount": "450",
      "currency": "USD"
    },
    "frequency": {
      "value": "monthly",
      "description": ""
    }
  },
  "basis": {
    "type": {
      "value": "direct",
      "description": ""
    }
  },
  "determinedAt": "2026-05-24T10:31:00Z",
  "producedBy": {
    "adapterId": "commonbenefits-adapter-policy-engine",
    "adapterVersion": "0.1.0",
    "rulesVersion": "2026-05"
  }
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: EligibilityDeterminationBase.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: The determination's unique identifier.
  household:
    $ref: DeterminationHousehold.yaml
    description: Reference to the household data used for this determination.
  outcome:
    $ref: DeterminationOutcome.yaml
    description: The outcome of the determination.
  estimatedBenefit:
    anyOf:
      - $ref: DeterminationEstimatedBenefit.yaml
      - type: "null"
    description: The estimated benefit, if eligible and the amount is calculable.
  basis:
    $ref: DeterminationBasis.yaml
    description: The basis on which the determination was made.
  determinedAt:
    type: string
    format: date-time
    description: The timestamp at which the determination was made.
  producedBy:
    $ref: DeterminationProducer.yaml
    description: Provenance information for the determination.
required:
  - id
  - household
  - outcome
  - basis
  - determinedAt
  - producedBy
examples:
  - id: 30a12e5e-5940-4c08-921c-17a8960fcf4b
    household:
      id: 40a12e5e-5940-4c08-921c-17a8960fcf4b
      revisionId: 50a12e5e-5940-4c08-921c-17a8960fcf4b
      snapshot: null
    outcome:
      value: eligible
      description: ""
    estimatedBenefit:
      amount:
        amount: "450"
        currency: USD
      frequency:
        value: monthly
        description: ""
    basis:
      type:
        value: direct
        description: ""
    determinedAt: 2026-05-24T10:31:00Z
    producedBy:
      adapterId: commonbenefits-adapter-policy-engine
      adapterVersion: 0.1.0
      rulesVersion: 2026-05
description: A point-in-time eligibility outcome for a specific Enrollment.

TypeSpec

/** A point-in-time eligibility outcome for a specific Enrollment. */
@example(Examples.EligibilityDetermination.directEligible)
@Versioning.added(Versions.v0_1)
model EligibilityDeterminationBase {
  /** The determination's unique identifier. */
  id: Types.uuid;

  /** Reference to the household data used for this determination. */
  household: DeterminationHousehold;

  /** The outcome of the determination. */
  outcome: DeterminationOutcome;

  /** The estimated benefit, if eligible and the amount is calculable. */
  estimatedBenefit?: DeterminationEstimatedBenefit | null;

  /** The basis on which the determination was made. */
  basis: DeterminationBasis;

  /** The timestamp at which the determination was made. */
  determinedAt: utcDateTime;

  /** Provenance information for the determination. */
  producedBy: DeterminationProducer;
}

DeterminationOutcome

The outcome of an eligibility determination.

Property	Type	Required	Description
value	DeterminationOutcomeOptions	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.

Example

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

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: DeterminationOutcome.yaml
type: object
properties:
  value:
    $ref: DeterminationOutcomeOptions.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 outcome of an eligibility determination.

TypeSpec

/** The outcome of an eligibility determination. */
@Versioning.added(Versions.v0_1)
model DeterminationOutcome is Fields.ExtensibleEnumT<DeterminationOutcomeOptions>;

// #########################################################
// DeterminationEstimatedBenefit
// #########################################################

/** An estimated benefit amount and the cadence at which it would be paid. */
@Versioning.added(Versions.v0_1)
model DeterminationEstimatedBenefit {
  /** The estimated monetary amount. */
  amount: Fields.Money;

  /** The cadence at which the benefit would be paid. */
  frequency: Fields.Frequency;
}

DeterminationOutcomeOptions

Predefined set of eligibility determination outcomes.

Value	Description
eligible	Determined eligible.
ineligible	Determined ineligible.
pending	Determination is pending additional data or processing.
needs_verification	Eligible pending verification of submitted data.
custom	A caller-defined outcome.

Example

"eligible"

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: DeterminationOutcomeOptions.yaml
type: string
enum:
  - eligible
  - ineligible
  - pending
  - needs_verification
  - custom
description: |-
  Predefined set of eligibility determination outcomes.

  - `eligible`: Determined eligible.
  - `ineligible`: Determined ineligible.
  - `pending`: Determination is pending additional data or processing.
  - `needs_verification`: Eligible pending verification of submitted data.
  - `custom`: A caller-defined outcome.

TypeSpec

/** Predefined set of eligibility determination outcomes.
 *
 * - `eligible`: Determined eligible.
 * - `ineligible`: Determined ineligible.
 * - `pending`: Determination is pending additional data or processing.
 * - `needs_verification`: Eligible pending verification of submitted data.
 * - `custom`: A caller-defined outcome.
 */
@Versioning.added(Versions.v0_1)
enum DeterminationOutcomeOptions {
  eligible,
  ineligible,
  pending,
  needs_verification,
  custom,
}

DeterminationBasis

The basis on which a determination was made. For `categorical`, `sourceProgramId` and `sourceEnrollmentId` are required.

Property	Type	Required	Description
type	DeterminationBasisType	Yes	The type of basis.
sourceProgramId	uuid	No	The program that confers categorical eligibility. Required when `type` is `categorical`.
sourceEnrollmentId	uuid	No	The enrollment that confers categorical eligibility. Required when `type` is `categorical`.

Example

{
  "type": {
    "value": "direct",
    "customValue": "string",
    "description": "string"
  },
  "sourceProgramId": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "sourceEnrollmentId": "30a12e5e-5940-4c08-921c-17a8960fcf4b"
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: DeterminationBasis.yaml
type: object
properties:
  type:
    $ref: DeterminationBasisType.yaml
    description: The type of basis.
  sourceProgramId:
    $ref: uuid.yaml
    description: The program that confers categorical eligibility. Required when `type` is `categorical`.
  sourceEnrollmentId:
    $ref: uuid.yaml
    description: The enrollment that confers categorical eligibility. Required when `type` is `categorical`.
required:
  - type
description: |-
  The basis on which a determination was made. For `categorical`,
  `sourceProgramId` and `sourceEnrollmentId` are required.

TypeSpec

/** The basis on which a determination was made. For `categorical`,
 * `sourceProgramId` and `sourceEnrollmentId` are required.
 */
@Versioning.added(Versions.v0_1)
model DeterminationBasis {
  /** The type of basis. */
  type: DeterminationBasisType;

  /** The program that confers categorical eligibility. Required when `type` is `categorical`. */
  sourceProgramId?: Types.uuid;

  /** The enrollment that confers categorical eligibility. Required when `type` is `categorical`. */
  sourceEnrollmentId?: Types.uuid;
}

DeterminationBasisType

The type of basis on which a determination was made.

Property	Type	Required	Description
value	DeterminationBasisTypeOptions	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.

Example

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

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: DeterminationBasisType.yaml
type: object
properties:
  value:
    $ref: DeterminationBasisTypeOptions.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 basis on which a determination was made.

TypeSpec

/** The type of basis on which a determination was made. */
@Versioning.added(Versions.v0_1)
model DeterminationBasisType is Fields.ExtensibleEnumT<DeterminationBasisTypeOptions>;

// #########################################################
// DeterminationBasis
// #########################################################

/** The basis on which a determination was made. For `categorical`,
 * `sourceProgramId` and `sourceEnrollmentId` are required.
 */
@Versioning.added(Versions.v0_1)
model DeterminationBasis {
  /** The type of basis. */
  type: DeterminationBasisType;

  /** The program that confers categorical eligibility. Required when `type` is `categorical`. */
  sourceProgramId?: Types.uuid;

  /** The enrollment that confers categorical eligibility. Required when `type` is `categorical`. */
  sourceEnrollmentId?: Types.uuid;
}

DeterminationBasisTypeOptions

Predefined set of bases on which a determination can be made. (e.g., already enrolled in a qualifying program).

Value	Description
direct	The determination was made directly from the household's data.
categorical	The determination was made via categorical eligibility
custom	A caller-defined basis.

Example

"direct"

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: DeterminationBasisTypeOptions.yaml
type: string
enum:
  - direct
  - categorical
  - custom
description: |-
  Predefined set of bases on which a determination can be made.

  - `direct`: The determination was made directly from the household's data.
  - `categorical`: The determination was made via categorical eligibility
  (e.g., already enrolled in a qualifying program).
  - `custom`: A caller-defined basis.

TypeSpec

/** Predefined set of bases on which a determination can be made.
 *
 * - `direct`: The determination was made directly from the household's data.
 * - `categorical`: The determination was made via categorical eligibility
 *   (e.g., already enrolled in a qualifying program).
 * - `custom`: A caller-defined basis.
 */
@Versioning.added(Versions.v0_1)
enum DeterminationBasisTypeOptions {
  direct,
  categorical,
  custom,
}

DeterminationProducer

Provenance information for an eligibility determination.

Property	Type	Required	Description
adapterId	string	Yes	The identifier of the adapter that produced this determination.
adapterVersion	string	Yes	The semantic version of the adapter.
rulesVersion	string	Yes	The rules version used by the adapter (e.g., a date stamp like "2026-05").

Example

{
  "adapterId": "string",
  "adapterVersion": "string",
  "rulesVersion": "string"
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: DeterminationProducer.yaml
type: object
properties:
  adapterId:
    type: string
    description: The identifier of the adapter that produced this determination.
  adapterVersion:
    type: string
    description: The semantic version of the adapter.
  rulesVersion:
    type: string
    description: The rules version used by the adapter (e.g., a date stamp like "2026-05").
required:
  - adapterId
  - adapterVersion
  - rulesVersion
description: Provenance information for an eligibility determination.

TypeSpec

/** Provenance information for an eligibility determination. */
@Versioning.added(Versions.v0_1)
model DeterminationProducer {
  /** The identifier of the adapter that produced this determination. */
  adapterId: string;

  /** The semantic version of the adapter. */
  adapterVersion: string;

  /** The rules version used by the adapter (e.g., a date stamp like "2026-05"). */
  rulesVersion: string;
}

DeterminationHousehold

Reference to the household data used for an eligibility determination. If the implementation supports household revisions, `revisionId` references the immutable revision record and `snapshot` is null. If not, `snapshot` carries the full household JSON inline and `revisionId` is null. Both MAY be present if the implementation populates both.

Property	Type	Required	Description
id	uuid	Yes	The household this determination applies to.
revisionId	uuid | null	No	The household revision record, if revisions are implemented.
snapshot	HouseholdBase | null	No	The full household snapshot, if revisions are not implemented.

Example

{
  "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "revisionId": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "snapshot": {
    "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"
  }
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: DeterminationHousehold.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: The household this determination applies to.
  revisionId:
    anyOf:
      - $ref: uuid.yaml
      - type: "null"
    description: The household revision record, if revisions are implemented.
  snapshot:
    anyOf:
      - $ref: HouseholdBase.yaml
      - type: "null"
    description: The full household snapshot, if revisions are not implemented.
required:
  - id
description: |-
  Reference to the household data used for an eligibility determination.

  If the implementation supports household revisions, `revisionId` references
  the immutable revision record and `snapshot` is null. If not, `snapshot`
  carries the full household JSON inline and `revisionId` is null. Both MAY
  be present if the implementation populates both.

TypeSpec

/** Reference to the household data used for an eligibility determination.
 *
 * If the implementation supports household revisions, `revisionId` references
 * the immutable revision record and `snapshot` is null. If not, `snapshot`
 * carries the full household JSON inline and `revisionId` is null. Both MAY
 * be present if the implementation populates both.
 */
@Versioning.added(Versions.v0_1)
model DeterminationHousehold {
  /** The household this determination applies to. */
  id: Types.uuid;

  /** The household revision record, if revisions are implemented. */
  revisionId?: Types.uuid | null;

  /** The full household snapshot, if revisions are not implemented. */
  snapshot?: HouseholdBase | null;
}

DeterminationEstimatedBenefit

An estimated benefit amount and the cadence at which it would be paid.

Property	Type	Required	Description
amount	Money	Yes	The estimated monetary amount.
frequency	Frequency	Yes	The cadence at which the benefit would be paid.

Example

{
  "amount": {
    "amount": "-50.50",
    "currency": "USD"
  },
  "frequency": {
    "value": "monthly",
    "description": ""
  }
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: DeterminationEstimatedBenefit.yaml
type: object
properties:
  amount:
    $ref: Money.yaml
    description: The estimated monetary amount.
  frequency:
    $ref: Frequency.yaml
    description: The cadence at which the benefit would be paid.
required:
  - amount
  - frequency
description: An estimated benefit amount and the cadence at which it would be paid.

TypeSpec

/** An estimated benefit amount and the cadence at which it would be paid. */
@Versioning.added(Versions.v0_1)
model DeterminationEstimatedBenefit {
  /** The estimated monetary amount. */
  amount: Fields.Money;

  /** The cadence at which the benefit would be paid. */
  frequency: Fields.Frequency;
}