Skip to main content

​
Overview

The PlanRules object is where you define the stable, legal framework of your ESOP, as specified in your plan document. These rules change infrequently and typically require a formal plan amendment. Getting the PlanRules right is the first and most important step in accurately modeling your ESOP.
Source of Truth: Your ESOP’s Plan Document.

​
Complete Field Reference

Below is a detailed walkthrough of each field in the PlanRules object.

​
plan_name

  • Type: string
  • Required: Yes
  • Description: The official name of your ESOP plan.
  • Example: "Acme Corp Employee Stock Ownership Plan"

​
plan_year_end

  • Type: string (MM/DD format)
  • Required: Yes
  • Description: The end date of your plan year. This is a critical field that affects the timing of many calculations.
  • Example: "12/31"

​
vesting_schedule

  • Type: object
  • Required: Yes
  • Description: Defines how participants earn ownership of their ESOP shares over time.
  • Type: string
  • Values: "graded", "cliff"
  • Description: The type of vesting schedule. “Graded” vesting increases gradually over time, while “cliff” vesting happens all at once.
  • Type: array of numbers
  • Description: Required for graded vesting. An array representing the percentage of shares vested at each year of service.
  • Example: [0, 0, 20, 40, 60, 80, 100] for a 6-year graded schedule where vesting begins after 2 years.
  • Validation: Must start at 0, end at 100, and be monotonically increasing.
  • Type: integer
  • Description: Required for cliff vesting. The number of years of service required to become 100% vested.
  • Example: 3 for a 3-year cliff.

​
distribution_policy

  • Type: object
  • Required: Yes
  • Description: Defines when and how participants receive their vested account balances after termination.
  • Type: string
  • Values: "immediate", "termination_plus_1_year", etc.
  • Description: When distributions begin after a termination event.
  • Type: string
  • Values: "lump_sum", "installments"
  • Description: How distributions are paid out.

​
cash_usage_policy

  • Type: array of strings
  • Required: No
  • Description: The priority order for using different sources of cash within the trust to fund distributions and repurchases.
  • Example: ["unallocated_company_contributions", "unallocated_forfeiture_cash", "participant_cash_accounts"]

​
diversification_rules

  • Type: object
  • Required: No
  • Description: Defines the rules for statutory diversification. The engine can model this automatically if this section is included.

​
Complete Example

{
  "plan_name": "Acme Corp ESOP",
  "plan_year_end": "12/31",
  "vesting_schedule": {
    "type": "graded",
    "schedule": [0, 0, 20, 40, 60, 80, 100]
  },
  "distribution_policy": {
    "timing": "termination_plus_1_year",
    "form": "lump_sum"
  },
  "cash_usage_policy": [
    "unallocated_company_contributions",
    "unallocated_forfeiture_cash",
    "participant_cash_accounts"
  ],
  "diversification_rules": {
    "min_age": 55,
    "min_service": 10
  }
}