Changelog
Every Board Ontology release — added, removed, promoted, and changed KPIs. Pin to a specific version using the immutable snapshots at /api/ontology/v/<version>/.
This page lists every Board Ontology release. Each release has an immutable snapshot URL — pin to it if your integration needs reproducibility. See methodology § 4 for the versioning policy.
The entries below are appended by the docs build (see
packages/docs/scripts/generate-ontology-changelog.ts) when a new
ONTOLOGY_VERSION is detected. Hand-edit only above this marker:
v1.22.0 — 2026-10-22
Payroll is a monthly fully-loaded run-rate (#4801).
hr.payroll_run_rate was described as an annualized cost while every screen, the
audit rule and the demo data read it as monthly. The definition now says monthly
(an annual source figure is divided by 12), its label is "Payroll · monthly
run-rate · fully loaded", and it gains a calculation policy. Stored values are
not rescaled.
Meaning changes
hr.payroll_run_rate: a monthly fully-loaded run-rate; it was described as annual. Values entered under the annual definition read 12× too high; divide those by 12.hr.payroll_as_pct_of_burn: monthly payroll ÷ gross monthly burn; the formula no longer divides by 12.hr.fte_metrics: cost per FTE is monthly; annualized payroll is monthly payroll × 12.
Calculation policy added (1): hr.payroll_run_rate
Snapshot: /api/ontology/v/1.22.0/index.json
v1.21.0 — 2026-10-22
Three-state missing values in computed KPIs (#4803, folded #4823).
A computed KPI now resolves to one of three states. Known: a real number, where an entered 0 is a real 0. Unknown: an input was never entered, so the value is N/A and names the missing input. Undefined: every input is known but the maths has no meaningful value, so it shows a plain-language fact such as "Not burning cash". Only declared optional additive lines (P&L breakdown lines, the four opex function totals within total opex, below-EBITDA items, working-capital adjustments, and nonprofit support/revenue and functional-expense lines) count as 0 when blank, and the result marks them "assumed 0". A subtotal with no line entered at all is unknown. Stored values are not rewritten.
Meaning changes
finance.runway_months: burn of 0 or below reads "Not burning cash" (was 0, or ∞ for negative burn); missing cash or burn is N/A.finance.total_cash_in_bank,finance.total_restricted_cash,finance.total_unrestricted_cash,finance.current_asset_adjustments,finance.current_liability_adjustments: N/A when no row is entered, a row has no amount, or a currency has no FX rate to the report's base currency (was a silent 1:1 sum, #4823). A row with no currency is in the report's base currency.finance.gross_margin_pct,finance.np_program_expense_ratio,finance.np_cost_to_raise_a_dollar: a 0 denominator reads "Not meaningful" (was 0); a missing input is N/A.finance.operationally_available_cash,finance.net_working_capital_adjustment,finance.total_revenue,finance.total_cogs,finance.gross_profit,finance.total_rnd,finance.total_sm,finance.total_cs,finance.total_ga,finance.total_opex,finance.ebitda,finance.net_income,finance.np_total_support_revenue,finance.np_total_functional_expenses,finance.np_change_in_net_assets: a missing required input is N/A (was counted as 0); declared optional lines count as "assumed 0".
Snapshot: /api/ontology/v/1.21.0/index.json
v1.20.0 — 2026-10-21
Roll-up rules declared on every numeric KPI (#4818, folded #4822).
timeAggregation gains a first value for opening balances. Every numeric KPI
now declares its rule, and the roll-up engine no longer falls back to sum for
a catalog KPI. Stored monthly values are unchanged.
Meaning changes
Before 1.20.0 these KPIs had no rule, so quarterly and annual views summed them.
last(closing value):sales.bookings_backlog,sales.bookings_backlog_total,sales.pipeline_value,sales.weighted_forecast,sales.pipeline_deal_count,sales.quarterly_forecast,customers.nps_score,customers.nps_responses,hr.payroll_run_rate,hr.total_contractors,hr.at_risk_count,hr.performance_watch_count,hr.approved_headcount_budget,product.total_engineers,product.scalability_headroom,fundraising.target_raise,fundraising.committed_amount,fundraising.investors_in_pipeline,fundraising.pre_money_valuation,fundraising.post_money_valuation,fundraising.minimum_valuation,fundraising.target_valuation,fundraising.total_round_size,fundraising.total_received,fundraising.venture_debt_drawn,fundraising.venture_debt_available,fundraising.minimum_close_amount,fundraising.total_capital_raised.first(opening value):sales.starting_arr,sales.opening_pipeline_value,customers.prior_quarter_total_customers,customers.prior_quarter_acv.avg(monthly average):product.rd_monthly_spend.none(N/A in roll-ups, never summed):sales.avg_contract_value,sales.cac,sales.ltv,sales.ltv_cac_ratio,sales.cac_payback_period,sales.blended_cac_ratio,sales.new_cac_ratio,sales.expansion_cac_ratio,sales.avg_sales_cycle_days,sales.average_deal_size,sales.median_deal_size,customers.avg_contract_value,hr.arr_per_fte,hr.avg_days_to_fill,hr.in_jurisdiction_jobs_created,product.rd_efficiency.
Declared sum with no change in meaning: finance.net_working_capital_adjustment, finance.total_operational_inflow, finance.total_operational_outflow, finance.current_asset_adjustments, finance.current_liability_adjustments, sales.new_business, sales.expansion, sales.churn_arr, sales.downgrades, sales.new_customers_added, sales.total_revenue, sales.closed_won_count, sales.closed_won_value, sales.closed_lost_count, sales.closed_lost_value, sales.new_opps_added_value, customers.customers_churned, customers.new_customers_added, customers.nps_trend, hr.new_hires, hr.voluntary_exits, hr.terminations, hr.headcount_change.
Snapshot: /api/ontology/v/1.20.0/index.json
v1.19.0 — 2026-10-21
Loss magnitudes and the NPS trend binding (#4818).
No KPIs added or removed. Stored values are not rewritten.
Meaning changes
sales.churn_arr,sales.downgrades,sales.closed_lost_value— stored as a non-negative loss; the bridge subtracts it once. Values stored as negative numbers before 1.19.0 read as the same loss (absolute value).sales.closed_won_count,sales.closed_won_value,sales.closed_lost_count— stored as non-negative; the open-pipeline bridge subtracts them. Legacy negatives read as the same removal.customers.customers_churned— stored as a non-negative count; the customer bridge subtracts it once. Legacy negatives read as the same count.sales.bookings_backlog_changes— converted, lost and decreases are non-negative removal magnitudes; the backlog bridge subtracts them.customers.nps_trend— the NPS gauge reads it as a change in points (itstrendslot), not a prior absolute score. A stored prior score should be re-entered as score minus prior.
Snapshot: /api/ontology/v/1.19.0/index.json
v1.18.0 — 2026-10-21
Meaning versioning and basis labels (#4796).
Four optional fields on OntologyKpi, each omitted when empty:
meaningChanges— per-KPI history of changes to what an existingrogueIdmeans (version,date,summary,compatibility). From this release on, a release that changes the unit, sign, population, time basis, formula or aggregation of an existing KPI lists it under a separate Meaning changes block. A guard test fails the build when such a change ships without an entry and a version bump.basisLabel,basisDetail,verticalBasisLabels— the short measurement basis shown under a KPI's name, and its full basis lines. Populated onsales.arr,customers.nps_score,finance.runway_monthsandhr.payroll_run_rate; more KPIs follow.
Meaning changes in this release: none. Additive only.
Snapshot: /api/ontology/v/1.18.0/index.json
v1.9.0 — 2026-06-25
Calculation policy — Wave 2 (6 of 6): the 13 fundraising production: "primary" inputs.
Final batch of Wave 2 (epic #2287, PR #2320) — hardening the raw fundraising inputs (round sizing, valuations, commitments, and debt) that the fundraising and runway metrics read from.
Calculation policy added (13): fundraising.target_raise,
fundraising.total_round_size, fundraising.committed_amount,
fundraising.total_received, fundraising.minimum_close_amount,
fundraising.investors_in_pipeline, fundraising.pre_money_valuation,
fundraising.minimum_valuation, fundraising.target_valuation,
fundraising.convertible_outstanding, fundraising.venture_debt_drawn,
fundraising.venture_debt_available, fundraising.total_capital_raised.
Additive only — calculationPolicy remains optional; KPIs without one emit the
same JSON shape as before.
Snapshot: /api/ontology/v/1.9.0/index.json
v1.8.0 — 2026-06-25
Calculation policy — Wave 2 (5 of 6): the 7 product production: "primary" inputs.
Hardens the raw product/R&D inputs (epic #2287, PR #2319) — spend, headcount, scalability headroom, and roadmap allocation — that the product efficiency and capacity metrics read from.
Calculation policy added (7): product.rd_monthly_spend,
product.total_engineers, product.scalability_headroom,
product.offensive_roadmap_pct, product.defensive_roadmap_pct,
product.commitments_roadmap_pct, product.capacity_allocation_pct.
Additive only — calculationPolicy remains optional; KPIs without one emit the
same JSON shape as before.
Snapshot: /api/ontology/v/1.8.0/index.json
v1.7.0 — 2026-06-25
Calculation policy — Wave 2 (4 of 6): the 9 HR production: "primary" inputs.
Hardens the raw HR inputs (epic #2287, PR #2318) — headcount, hires and exits, open positions, and the approved headcount budget — that the headcount, attrition, and burn-per-head metrics read from.
Calculation policy added (9): hr.total_headcount, hr.total_contractors,
hr.new_hires, hr.voluntary_exits, hr.terminations, hr.open_positions,
hr.approved_headcount_budget, hr.at_risk_count, hr.performance_watch_count.
Additive only — calculationPolicy remains optional; KPIs without one emit the
same JSON shape as before.
Snapshot: /api/ontology/v/1.7.0/index.json
v1.6.0 — 2026-06-25
Calculation policy — Wave 2 (3 of 6): the 9 sales production: "primary" inputs.
Hardens the raw sales inputs (epic #2287, PR #2317) — revenue, pipeline, and closed-won/closed-lost counts and values — that the pipeline-coverage, win-rate, and forecast metrics read from.
Calculation policy added (9): sales.total_revenue, sales.pipeline_value,
sales.pipeline_deal_count, sales.new_opps_added_value,
sales.closed_won_count, sales.closed_won_value, sales.closed_lost_count,
sales.closed_lost_value, sales.quarterly_forecast.
Additive only — calculationPolicy remains optional; KPIs without one emit the
same JSON shape as before.
Snapshot: /api/ontology/v/1.6.0/index.json
v1.5.0 — 2026-06-25
Calculation policy — Wave 2 (2 of 6): the 44 finance production: "primary" inputs.
The largest batch of Wave 2 (epic #2287, PR #2315) — hardening the raw finance inputs (cash, the full operational inflow/outflow and burn ledger, every revenue and COGS line, the operating-expense payroll and tooling lines, and below-the-line items) that the P&L, burn, runway, and Rule-of-40 metrics read from.
Calculation policy added (44): finance.total_cash_in_bank,
finance.total_restricted_cash, finance.total_operational_inflow,
finance.total_operational_outflow, finance.burn_rate_actual,
finance.current_asset_adjustments, finance.current_liability_adjustments,
finance.subscription_revenue, finance.usage_revenue,
finance.services_revenue, finance.other_revenue, finance.cloud_hosting,
finance.customer_support_delivery, finance.services_delivery_costs,
finance.payment_transaction_costs, finance.third_party_data,
finance.other_cogs, finance.rd_payroll, finance.product_design_payroll,
finance.marketing_payroll, finance.sales_payroll, finance.cs_payroll,
finance.ga_payroll, finance.sales_commissions, finance.recruiting,
finance.paid_marketing, finance.events_conferences,
finance.rd_tools_software, finance.sm_tools_software,
finance.cs_tools_software, finance.software_it,
finance.legal_accounting_professional, finance.office_facilities,
finance.travel_entertainment, finance.insurance_compliance,
finance.contractors_outsourcing, finance.other_rnd, finance.other_sm,
finance.other_cs, finance.other_ga, finance.depreciation_amortization,
finance.interest_income_expense, finance.fx_gain_loss, finance.tax.
Additive only — calculationPolicy remains optional; KPIs without one emit the
same JSON shape as before.
Snapshot: /api/ontology/v/1.5.0/index.json
v1.4.0 — 2026-06-25
Calculation policy — Wave 2 (1 of 6): the 12 customers production: "primary" inputs.
First batch of Wave 2 (epic #2287, PR #2313) — hardening the raw customer inputs (customer counts, ARR at risk, average contract value, churn and additions, NPS, and the prior-quarter anchors) that the retention, concentration, and NRR/GRR metrics read from.
Calculation policy added (12): customers.total_customers,
customers.arr_at_risk, customers.avg_contract_value,
customers.customers_churned, customers.new_customers_added,
customers.nps_responses, customers.nps_score,
customers.prior_quarter_acv, customers.prior_quarter_concentration,
customers.prior_quarter_grr, customers.prior_quarter_nrr,
customers.prior_quarter_total_customers.
Additive only — calculationPolicy remains optional; KPIs without one emit the
same JSON shape as before.
Snapshot: /api/ontology/v/1.4.0/index.json
v1.3.0 — 2026-05-20
metricBasis — structured, machine-filterable measurement metadata.
Where calculationPolicy (v1.1.0–v1.2.0) is free-text guidance for an LLM,
metricBasis is a small set of enum axes a consumer can filter on
deterministically — "all point-in-time metrics", "all cohort-based
metrics", "all metrics measured on a cash basis".
New optional field metricBasis on every KPI, with five optional axes:
timeBasis—point_in_time/period_flow/trailing_windowmoneyBasis—contracted_arr/recognized_revenue/cash/bookingscohortBasis—closed_start_cohort/all_activedateBasis—go_live/signed/period_closeproduction—computed/primary(derived from other KPIs vs a raw input)
Each axis is independently optional and omitted when not meaningful — a KPI
carries only the axes that apply. Populated for all 101 numeric KPIs;
narrative (text) KPIs carry no metricBasis.
Additive — metricBasis is optional; consumers that ignore it see the same
shape as v1.2.1. The JSON Schema at /api/ontology/schema.json picks up
OntologyMetricBasis automatically (it is generated from the types).
Snapshot: /api/ontology/v/1.3.0/index.json
v1.2.1 — 2026-05-20
Correction — two KPI formulas were wrong. If you copied either formula, recompute.
An external review surfaced two formula strings (both predating the
calculationPolicy work and never re-audited) that produced incorrect
results:
sales.cac_payback_period— the formula paired a per-customer numerator (CAC, thesales.cacKPI) with an aggregate denominator (Monthly New ARR). Per-customer ÷ aggregate yields months-per-customer, not months. Corrected: the numerator is now total fully-loaded S&M spend for the period, so both terms are period aggregates.finance.runway_months— the formula usedmax(operationally_available_cash, total_unrestricted_cash), which always selects the less conservative figure when working capital is a headwind — the exact pitfall the KPI's own description warns against. Corrected: the cash basis is now stated explicitly (operationally-available at Series A+, unrestricted at early stage); nomax().
Both KPIs' calculationPolicy text was updated to match the corrected
formulas. No schema change, no KPI added or removed — patch release.
Snapshot: /api/ontology/v/1.2.1/index.json
v1.2.0 — 2026-05-20
Calculation policy — 20 more KPIs, covering the rest of the ARR waterfall, the CAC family, and cash/runway.
v1.1.0 seeded calculationPolicy on the 5 highest-leverage KPIs. v1.2.0
extends coverage to 25 total — adding the metrics most likely to be
miscomputed in agent-generated board packs after the original five.
Calculation policy added (20): finance.gross_burn_rate,
finance.net_burn_rate, finance.operationally_available_cash,
finance.runway_months, operations.rule_of_40,
sales.avg_contract_value, sales.blended_cac_ratio, sales.cac,
sales.churn_arr, sales.downgrades, sales.expansion,
sales.expansion_cac_ratio, sales.gross_margin, sales.growth_rate_yoy,
sales.new_business, sales.new_cac_ratio, sales.new_customers_added,
sales.starting_arr — plus customers.logo_retention_rate and
customers.logo_churn_rate.
Additive only — calculationPolicy remains optional; the 118 KPIs without
one emit the same JSON shape as before. The remaining KPIs gain policy
incrementally in future minor releases (see the draft pipeline at
packages/shared-types/scripts/draft-calculation-policies.ts).
Snapshot: /api/ontology/v/1.2.0/index.json
v1.1.0 — 2026-05-19
Calculation policy — first 5 KPIs gain an agent-safe execution contract.
PR #1481 (v1.0.0) gave each KPI a definition, a formula, and interpretation
guidance — enough for humans, not enough for AI agents asked to compute the
metric from a company's messy data. v1.1.0 introduces calculationPolicy, a
per-KPI block of inclusion / exclusion / required-input rules + edge cases +
validation checks + common miscomputations. Free-text strings consumed by
LLM agents at reasoning time (no DSL).
Calculation policy added (5): sales.arr, sales.carr,
sales.cac_payback_period, customers.net_revenue_retention,
customers.gross_revenue_retention.
Additive only — calculationPolicy is optional on every KPI; consumers with
no use for it can ignore it entirely. The 138 KPIs without a policy emit the
same JSON shape as in v1.0.0. Each editorial → published promotion
(epic #1415) is a
natural moment to add a policy block.
Snapshot: /api/ontology/v/1.1.0/index.json
v1.0.0 — 2026-05-19
Initial public release of the full Board Ontology.
- 143 KPIs across 7 domains: customers, finance, fundraising, hr, operations, product, sales.
- 27 anchored to third-party standards (
tier: "published") — SMSB, KBCM/Sapphire, Mercer, Carta, SaaS Capital, Retently, NVCA, YC SAFE, SHRM. - 116 I'mBoard-authored (
tier: "editorial") — visible in the JSON / MCP surface, tier-labeled so consumers can filter to the strict subset. - New: versioned response envelope
{ version, releasedAt, kpis }(breaking — the previous gated endpoint returned a flat array of 27). - New: immutable snapshots at
/api/ontology/v/1.0.0/— pin consumers here for reproducibility. - New: this changelog page.
Snapshot: /api/ontology/v/1.0.0/index.json
Methodology
Why every I'mBoard Board Ontology KPI cites its source — industry-backed vs I'mBoard-authored tiers, the versioned envelope, SMSB attribution requirements, definition lifecycle, and how disputes are handled.
Finance KPIs
Cash, revenue, burn, runway, expenses. 83 KPIs in this domain — 16 anchored to third-party standards, 67 editorial.