Skip to content

Commit 8966f38

Browse files
author
Jani Giannoudis
committed
Add root Docs/ folder with ProviderStubs template and README; update YYYY/Docs/README
1 parent 85e4872 commit 8966f38

File tree

3 files changed

+160
-7
lines changed

3 files changed

+160
-7
lines changed

‎Docs/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Docs — {CC}.{RegulationName}
2+
3+
Regulation-wide, timeless reference documents. These files are **not year-specific**
4+
and apply across all regulation versions.
5+
6+
## Distinction: root `Docs/` vs. `{YYYY}/Docs/`
7+
8+
| Location | Scope | Examples |
9+
|:---|:---|:---|
10+
| `Docs/` (this folder) | Regulation-wide, timeless | Provider stubs, payroll reference |
11+
| `{YYYY}/Docs/` | Year-specific | Analysis, TestSpecification, NoCodeDesign |
12+
13+
## Required files
14+
15+
| File | Purpose |
16+
|:---|:---|
17+
| `{CC}.{RegulationName}-ProviderStubs.md` | Describes all stub and approximation WageTypes — which employer-specific overrides are expected and how to implement them. **Required for every regulation.** |
18+
19+
## Optional files
20+
21+
| File | Purpose |
22+
|:---|:---|
23+
| `{CC}-Payroll-Reference.md` | Country payroll reference: statutory rates, contribution ceilings, filing deadlines, official source links. Useful for providers unfamiliar with the country. |
24+
25+
---
26+
27+
## ProviderStubs — Minimal Structure
28+
29+
`{CC}.{RegulationName}-ProviderStubs.md` must cover:
30+
31+
1. **What Is a Stub** — definition and the two stub patterns (data stub / extension point).
32+
2. **How to Override** — minimal regulation overlay JSON example.
33+
3. **Stub Overview** — table: WT number, name, default value, override trigger.
34+
4. **Stub Details** — one section per stub: when to override, implementation notes, legal source, collector impact.
35+
5. **Approximations** — WTs with working defaults that providers should override for precision.

‎Docs/{CC}.{RegulationName}-ProviderStubs.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# {CC}.{RegulationName} — Provider Stubs
2+
3+
> Version 1.0 · {Month} {YYYY}
4+
5+
---
6+
7+
## What Is a Stub?
8+
9+
A **stub** is a WageType in the base regulation that returns `0` (or a safe default)
10+
by design. It signals to providers and employers: *"this business rule is
11+
yours to implement — we give you the correct number, collector, and execution
12+
position; you supply the logic."*
13+
14+
`{CC}.{RegulationName}` uses stubs for:
15+
16+
1. **Employer-specific rules** — calculations that depend on company agreements
17+
(pension scheme, CAO, HR policy) that cannot be standardized in a national base regulation.
18+
2. **Approximations** — working implementations that cover the common case, but
19+
a more exact calculation requires employer data.
20+
21+
---
22+
23+
## How to Override a Stub
24+
25+
PE supports **regulation layering**: a provider or employer regulation can override
26+
any WageType from the base regulation without modifying it.
27+
28+
**Minimal override structure:**
29+
30+
```json
31+
{
32+
"regulations": [
33+
{
34+
"name": "Employer.MyCompany.{CC}",
35+
"baseRegulations": [
36+
"{CC}.{RegulationName}",
37+
"{CC}.{RegulationName}.Data.{Source1}.{YYYY}"
38+
],
39+
"cases": [...],
40+
"wageTypes": [
41+
{
42+
"wageTypeNumber": {nr},
43+
"name": "{StubWageTypeName}",
44+
"valueExpression": "{expression or valueActions reference}"
45+
}
46+
]
47+
}
48+
]
49+
}
50+
```
51+
52+
---
53+
54+
## Stub Overview
55+
56+
| WT | Name | Default | Override required? | Notes |
57+
|:---:|:---|:---:|:---:|:---|
58+
| {nr} | {StubName1} | 0 | Optional | {Short description} |
59+
| {nr} | {StubName2} | 0 | **Required for {scenario}** | {Short description} |
60+
61+
**Approximations:**
62+
63+
| WT | Name | Approximation | Override for |
64+
|:---:|:---|:---|:---|
65+
| {nr} | {ApproxName} | {What the base regulation does} | {When to override for precision} |
66+
67+
---
68+
69+
## Stub Details
70+
71+
### WT {nr} — {StubName1}
72+
73+
**Default:** `0` (no `valueActions`).
74+
75+
**Override when:** {Describe the business scenario that requires implementation.}
76+
77+
**Implementation notes:**
78+
- {Step 1}
79+
- {Step 2}
80+
81+
**Feeds:** `{CC}.{Collector}` ✓
82+
83+
**Source:** {Statutory reference — law, article, authority publication.}
84+
85+
---
86+
87+
### WT {nr} — {StubName2} ⚠️ {e.g. FiscaalLoon adjustment required}
88+
89+
**Default:** `0` (no `valueActions`).
90+
91+
**Override required when:** {Describe when this stub must be implemented.}
92+
93+
**Implementation steps:**
94+
1. {Step 1}
95+
2. {Step 2}
96+
97+
**Feeds:** `{CC}.{Collector}` ✓
98+
99+
**Source:** {Statutory reference.}
100+
101+
---
102+
103+
## Approximation Details
104+
105+
### WT {nr} — {ApproxName}
106+
107+
**Base approximation:** {What the regulation does by default.}
108+
109+
**Limitation:** {What the approximation misses or where it diverges from exact statutory calculation.}
110+
111+
**Override when:** {Describe when the employer needs an exact calculation.}
112+
113+
---
114+
115+
*Version 1.0 · {Month} {YYYY}*

‎YYYY/Docs/README.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
1-
# Docs — {CC}.{RegulationName}
1+
# Docs — {CC}.{RegulationName} {YYYY}
22

3-
Place regulation design and analysis documents here.
3+
Year-specific regulation documents for `{YYYY}`. For regulation-wide timeless
4+
documents (provider stubs, country reference), see the root [`Docs/`](../Docs/).
45

56
## Recommended files
67

78
| File | Content |
8-
|---|---|
9-
| `{CC}.{RegulationName}-Analysis.md` | System analysis, regulation design decisions, versioning strategy |
10-
| `{CC}.{RegulationName}-NoCodeDesign.md` | No-Code / Low-Code action specification with formulas |
11-
| `{CC}.{RegulationName}-TestSpec.md` | Test case calculations with statutory source references |
12-
| `{CC}-Reference.md` | Country payroll reference: rates, formulas, statutory sources |
9+
|:---|:---|
10+
| `{CC}.{RegulationName}-Analysis.md` | Regulation analysis: statutory rules, design decisions, scope, known limitations |
11+
| `{CC}.{RegulationName}-NoCodeDesign.md` | No-Code / Low-Code action specification with formulas and decision table |
12+
| `{CC}.{RegulationName}-TestSpecification.md` | Test case calculations with statutory source references and expected values |
13+
| `{CC}.{RegulationName}-PracticalTest.md` | Step-by-step manual test guide: setup commands, payrun execution, result verification |
14+
| `{CC}.{RegulationName}-Reports.md` | Report specification: output columns, data sources, filter parameters |
15+
| `{CC}.{RegulationName}-UncoveredCases.md` | Uncovered statutory cases: deferred implementation, known approximations, Tier-C edge cases |

0 commit comments

Comments
 (0)