How the South Africa annual leave calculator is verified

Inputs

Input	Field	Type
Which method your agreement uses	`method`	string
Days you work per week	`daysPerWeek`	number
Months completed in this annual leave cycle	`monthsWorked`	number
Days you worked, or were entitled to be paid for	`daysWorked`	number
Days already taken	`daysTaken`	number

The formula

Each derived value below is computed by the Valem engine from the expression shown, in this order. Nothing else runs — there is no hidden code path.

Derived value	Field	Formula (JSONata)
Days Entitled	`daysEntitled`	`($m := $clampFloorCap($n(monthsWorked), 0, $const.cycleMonths); method = 'perDaysWorked' ? $round($n(daysWorked) / $const.daysWorkedPerLeaveDay, 1) : ($m >= $const.cycleMonths ? $round($const.consecutiveDaysPerCycle / $const.daysPerCalendarWeek * $n(daysPerWeek), 1) : 0))`
Days Remaining	`daysRemaining`	`($r := daysEntitled - $n(daysTaken); $r < 0 ? 0 : $round($r, 1))`

Rates and thresholds

The expressions above read these as $const. They are the figures the annual refresh replaces, so they live as data rather than being written into the formulas — which is what makes a year-on-year change a one-line diff instead of an edit to arithmetic.

Constant	Value
`consecutiveDaysPerCycle`	21
`daysWorkedPerLeaveDay`	17
`cycleMonths`	12
`daysPerCalendarWeek`	7

Test vectors (9)

Every case is executed against this model on each build, by the Java engine and independently by a JavaScript one. A mismatch of a single cent fails the build, so the page cannot ship advertising a figure the model no longer produces.

Case 1 — N1 21 consecutive days is about 15 working days on a five-day week

given `method`	consecutiveDays
given `daysPerWeek`	5
given `monthsWorked`	12
given `daysWorked`	250
given `daysTaken`	0
expect `daysEntitled`	15

Case 2 — N2 a six-day week gets 18 working days out of the same 21 consecutive ones

given `method`	consecutiveDays
given `daysPerWeek`	6
given `monthsWorked`	12
given `daysWorked`	250
given `daysTaken`	0
expect `daysEntitled`	18

Case 3 — N3 method (a) grants per cycle, so an incomplete cycle shows nothing

given `method`	consecutiveDays
given `daysPerWeek`	5
given `monthsWorked`	11
given `daysWorked`	230
given `daysTaken`	0
expect `daysEntitled`	0

Case 4 — N4 method (b) on a 250-day year gives 14,7 — LESS than (a)'s 15, not the same

given `method`	perDaysWorked
given `daysPerWeek`	5
given `monthsWorked`	12
given `daysWorked`	250
given `daysTaken`	0
expect `daysEntitled`	14.7

Case 5 — N5 method (b) accrues from the first 17 days, with no cycle to complete

given `method`	perDaysWorked
given `daysPerWeek`	5
given `monthsWorked`	1
given `daysWorked`	17
given `daysTaken`	0
expect `daysEntitled`	1

Case 6 — N6 method (b) on a 260-day year gives 15,3 — MORE than (a)'s 15

given `method`	perDaysWorked
given `daysPerWeek`	5
given `monthsWorked`	12
given `daysWorked`	260
given `daysTaken`	0
expect `daysEntitled`	15.3

Case 7 — N7 no days worked earns nothing under method (b)

given `method`	perDaysWorked
given `daysPerWeek`	5
given `monthsWorked`	0
given `daysWorked`	0
given `daysTaken`	0
expect `daysEntitled`	0

Case 8 — N8 days already taken come off the remainder

given `method`	consecutiveDays
given `daysPerWeek`	5
given `monthsWorked`	12
given `daysWorked`	250
given `daysTaken`	6
expect `daysRemaining`	9

Case 9 — N9 taking more than the entitlement never goes negative

given `method`	consecutiveDays
given `daysPerWeek`	5
given `monthsWorked`	12
given `daysWorked`	250
given `daysTaken`	40
expect `daysRemaining`	0

Sources

Basic Conditions of Employment Act 75 of 1997, s.20 — labour.gov.za (21 consecutive days per annual leave cycle; one day per 17 days worked by agreement; a cycle is 12 months) · checked 2026-10-11

Check it yourself — and reuse it

The whole model as JSON — inputs, outputs, formulas, vectors and sources in one re-runnable document.

This model is published under CC BY 4.0: use it, adapt it, build on it, with attribution. The licence covers the model — the expression of each rule and the arrangement of the catalog. The rates and thresholds are law, and nobody licenses those; the sources above are where they come from.

← Back to the South Africa annual leave calculator

Built with Valem — a live, verifiable calculator you can fork and embed.