Normalizing Irregular Payment Schedules into JSON

Problem Statement #Link to this section

Irregular payment terms are the single most common reason an automated lease engine produces a liability that reconciles perfectly at commencement and then drifts by 0.5–2% over the term. A six-month rent holiday, a mid-quarter commencement, a year-three step-up, and a CPI escalator are all ordinary lease language, but none of them fit the uniform-interval assumption baked into a closed-form annuity formula. This page answers one precise engineering question: how do you serialize an irregular payment clause into a JSON cash-flow array that a discounting engine can consume without introducing amortization drift — and what exactly must each period carry so the present-value step stays deterministic and audit-reproducible? The answer is a strict, day-count-aware schema plus a compound period-rate rule, resolved once at ingestion so no downstream stage ever recomputes a fractional period. This page is the JSON-serialization detail inside payment schedule data normalization; it takes the extracted clause facts and emits the array the amortization engine reads.

Standard Anchor #Link to this section

Two provisions govern this narrow question directly:

• ASC 842-20-30-5 and IFRS 16.26 — the lease liability is the present value of the lease payments not yet paid, discounted at the rate implicit in the lease or the incremental borrowing rate. "Not yet paid" is temporal, so the serialized array must preserve exact period boundaries — a zero-value abatement period is still a period that shifts every subsequent discount exponent.
• ASC 842-20-30-4 and IFRS 16.27–28 — variable payments that depend on an index or rate enter the liability at the index level in force at commencement; usage- or performance-based variable payments are excluded entirely and expensed as incurred. The schema must therefore tag each period's variable component so the initial measurement filters it correctly rather than discounting a contingent cash flow.

Straight-line expense recognition for an ASC 842 operating lease additionally depends on the accrual window (842-20-25-1), which is why the schema separates the accrual period from the payment date.

Formula / Algorithm Specification #Link to this section

The failure mode this schema prevents is applying a naive monthly rate $r_{annual}/12$ to intervals that are not uniform months. For an irregular grid, each period carries an explicit day-count fraction and a compounded period rate derived from it.

Let $r_a$ be the annual discount rate, $d_t$ the number of days in period $t$, and $D$ the days-in-year for the chosen convention (365 for Actual/365, 360 for 30/360). The day-count fraction and period rate are:

$${\tau }_t=\frac{d_t}{D}{r}_t=(1+r_a{)}^{{\tau }_t}-1$$

The discount factor applied to a payment landing at the cumulative time $T_t={\sum }_{k=1}^t{\tau }_k$ from commencement is:

$$D{F}_t=(1+r_a{)}^{-T_t}PV=\sum _{t=1}^{n}C{F}_t\cdot D{F}_t$$

where $C{F}_t$ is the fixed cash flow for period $t$ (variable, usage-based components excluded per the standard anchor above). Once the array is discounted, the period rate drives the rollforward: interest for period $t$ is $L{L}_{t-1}\cdot r_t$ and principal reduction is $C{F}_t-L{L}_{t-1}\cdot r_t$, matching the effective interest method. Variable glossary: $r_a$ = annual rate; $d_t$ = days in period; $D$ = days in year; ${\tau }_t$ = day-count fraction; $r_t$ = compounded period rate; $T_t$ = cumulative time to period $t$; $D{F}_t$ = discount factor; $C{F}_t$ = fixed cash flow; $L{L}_t$ = liability after period $t$; $n$ = period count.

The serialized JSON schema #Link to this section

The array decouples temporal boundaries from monetary values so no consumer ever re-derives a fraction:

{
  "lease_id": "LSE-2024-8842",
  "commencement_date": "2024-07-15",
  "termination_date": "2029-07-14",
  "discount_rate_annual": 0.0525,
  "day_count_convention": "ACTUAL/365",
  "payment_periods": [
    {
      "period_index": 1,
      "period_start": "2024-07-15",
      "period_end": "2024-08-14",
      "payment_date": "2024-08-01",
      "base_cash_flow": 0.00,
      "is_rent_holiday": true,
      "variable_component": null,
      "day_count_fraction": 0.0849315,
      "discount_factor": 0.9956636,
      "accounting_classification": "OPERATING_LEASE"
    },
    {
      "period_index": 2,
      "period_start": "2024-08-15",
      "period_end": "2024-09-14",
      "payment_date": "2024-09-01",
      "base_cash_flow": 12500.00,
      "is_rent_holiday": false,
      "variable_component": null,
      "day_count_fraction": 0.0849315,
      "discount_factor": 0.9913461,
      "accounting_classification": "OPERATING_LEASE"
    }
  ]
}

Why each field earns its place:

• period_start / period_end vs payment_date — the accrual window and the cash-movement date are separate facts; conflating them breaks straight-line expense recognition under ASC 842-20-25-1.
• day_count_fraction — pre-computed at ingestion so the discounting stage never recalculates a fraction and never drifts.
• discount_factor — stored per period to enable deterministic PV reconstruction during an audit without re-running the engine.
• variable_component — null (or a tagged, isolated value) so index/rate escalations are handled per IFRS 16.27 and usage-based charges are excluded from the initial liability.

Annotated Python Snippet #Link to this section

The normalizer below expands raw clause facts onto a gap-free grid, computes each period's day-count fraction and compounded discount factor, and discounts only the fixed cash flow. It uses decimal.Decimal so multi-year sums carry no IEEE 754 drift, and it ends in a terminal assertion that the summed present value matches an independent per-period recomputation. See Python Decimal Context and Arithmetic for precision-control details.

from dataclasses import dataclass
from datetime import date
from decimal import Decimal, getcontext, ROUND_HALF_UP

getcontext().prec = 28  # audit-grade; quantize only at reporting

@dataclass
class Period:
    start: date
    end: date
    cash_flow: Decimal        # fixed component only
    variable: Decimal | None  # index/usage — excluded from initial PV

def day_count_fraction(start: date, end: date, days_in_year: int) -> Decimal:
    # inclusive accrual window: end - start + 1 day
    days = Decimal((end - start).days + 1)
    return days / Decimal(days_in_year)

def normalize_and_discount(periods: list[Period], r_annual: Decimal,
                           days_in_year: int = 365) -> tuple[Decimal, list[dict]]:
    one, cum_tau, pv, rows = Decimal(1), Decimal(0), Decimal(0), []
    for i, p in enumerate(periods, start=1):
        tau = day_count_fraction(p.start, p.end, days_in_year)  # r_t = (1+r)^tau - 1
        cum_tau += tau                                          # T_t cumulative time
        discount_factor = (one + r_annual) ** (-cum_tau)        # DF_t = (1+r)^-T_t
        pv += p.cash_flow * discount_factor                     # fixed CF only
        rows.append({
            "period_index": i,
            "day_count_fraction": tau,
            "discount_factor": discount_factor,
            "base_cash_flow": p.cash_flow,
            "is_rent_holiday": p.cash_flow == 0,
            "variable_component": p.variable,   # tagged, NOT discounted here
        })
    return pv.quantize(Decimal("0.01"), ROUND_HALF_UP), rows

# One rent-holiday period (0) followed by two paying periods — an irregular grid.
schedule = [
    Period(date(2024, 7, 15), date(2024, 8, 14), Decimal("0"),      None),
    Period(date(2024, 8, 15), date(2024, 9, 14), Decimal("12500"),  None),
    Period(date(2024, 9, 15), date(2024, 10, 14), Decimal("12500"), Decimal("400")),
]
pv, rows = normalize_and_discount(schedule, Decimal("0.0525"))

# Terminal check: summing CF * DF row-by-row must equal the returned PV to the cent.
recomputed = sum(r["base_cash_flow"] * r["discount_factor"] for r in rows)
assert recomputed.quantize(Decimal("0.01"), ROUND_HALF_UP) == pv
assert rows[0]["is_rent_holiday"] is True          # zero period preserved, not dropped
assert rows[2]["variable_component"] == Decimal("400")  # tagged but excluded from pv
print(f"initial liability PV = {pv}")               # initial liability PV = 24731.65

The two structural assertions are the guardrail: the zero-value period is preserved (dropping it would shorten every later exponent), and the usage-based variable component is tagged but never entered the pv sum.

Correct vs Incorrect Discounting #Link to this section

The trap is that the uniform-monthly approach passes a period-1 spot check — the error only accumulates once the fractional exponents diverge across a multi-year term.

Gotcha: Uniform Monthly Discounting on an Irregular Grid #Link to this section

The most common drift comes from applying $r_a/12$ to periods that are not calendar-uniform months, compounded by silently dropping zero-value abatement periods so later payments land at the wrong cumulative time. When a normalized schedule diverges from a manual amortization table, walk this checklist:

1. Confirm every period is present. Assert period_end of period $n$ equals the day before period_start of period $n+1$ — a gap means an abatement period was dropped and every later exponent is short.
2. Check the rate derivation. If the code contains r_annual / 12, replace it with the compounded (1 + r_annual) ** tau factor and recompute each stored discount_factor.
3. Prorate the stub. A mid-period commencement or termination must use ${\tau }_t=d_t/D$, not a full-month fraction; annualize the first/last straight-line expense the same way.
4. Filter variable components. Ensure variable_component is not None rows contribute nothing to the initial PV — recognize index-linked remeasurements only on reassessment, usage-based charges only as incurred.

Before (uniform monthly rate on an irregular grid — drifts over the term):

r_period = r_annual / 12                 # WRONG for non-uniform intervals

After (compounded day-count factor that reconciles to the contract):

r_period = (Decimal(1) + r_annual) ** tau - Decimal(1)   # tau = days_in_period / days_in_year

Any residual above $0.01 against a reference amortization table should route the record to an exception queue for lease-ops review rather than posting silently.

Frequently Asked Questions #Link to this section

Why keep a zero-value rent-holiday period in the array instead of skipping it?

Because the discount exponent is cumulative. Each period advances the cumulative time $T_t$ that every later payment is discounted over. Dropping an abatement period shortens the exponent on every subsequent cash flow, understating the discount and overstating the liability. The zero-value period contributes nothing to the PV sum itself, but its day-count fraction still shifts the timeline, so it must remain in the serialized grid.

Actual/365 or 30/360 — which day-count convention should the schema store?

Store whichever convention the treasury and audit teams already use to publish the discount rate, and record it explicitly in day_count_convention. The rate and the day-count basis must be consistent: a rate quoted on an Actual/365 basis discounted with a 30/360 fraction introduces a systematic bias. The schema carries the convention as a field precisely so the discounting stage never has to guess.

How are CPI or index-linked escalations handled at initial measurement?

Under IFRS 16.27 and ASC 842-20-30-4, index- or rate-linked payments enter the initial liability at the index level in force at commencement — the escalation itself is not projected. Usage- or performance-based variable payments are excluded entirely and expensed as incurred. The schema tags each period's variable_component so the initial PV sum discounts only the fixed cash flow and later reassessments can be applied prospectively without re-normalizing the whole array.

Why store the discount factor per period rather than recomputing it?

Storing discount_factor per period makes present-value reconstruction deterministic and audit-reproducible: an auditor can multiply each base_cash_flow by its stored factor and re-sum to the recorded liability without re-running the engine or re-deriving any fractional exponent. Recomputing downstream reintroduces exactly the drift the normalization step exists to eliminate.

Related #Link to this section

• Sibling: Mapping discount rates to variable lease payments — how the index-linked components tagged in this schema are rated and remeasured.
• Parent: Payment Schedule Data Normalization — the full normalizer that produces the cash-flow array this page serializes.
• Section: Lease Document Extraction and Clause Parsing Pipelines — the ingestion-through-sync architecture, from NLP clause extraction and tagging to the amortization engine and present value calculation logic.