leave_balance contract v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.demiton.io/registers/leave_balance/v1.json",
  "title": "leave_balance contract v1",
  "type": "object",
  "required": [
    "accrued_balance",
    "balance_as_of",
    "leave_category",
    "leave_category_name",
    "worker_ref"
  ],
  "properties": {
    "worker_ref": {
      "type": "string",
      "description": "The employee the balance belongs to; the shelf's subject anchor. Rows without it are dropped by `build_atom`'s no-anchor guard.",
      "x-demiton-requiredness": "required",
      "x-demiton-reference": true
    },
    "balance_unit": {
      "type": "string",
      "description": "The denomination of `accrued_balance`. Optional because every observed row today is one payroll system's single denomination; mandatory the moment a second jurisdiction is loaded.",
      "x-demiton-requiredness": "optional"
    },
    "legal_entity": {
      "type": "string",
      "description": "Which employing entity owns the balance. Optional by declaration, not by accident: KeyPay is multi-business and the business is resolvable from the record.",
      "x-demiton-requiredness": "optional",
      "x-demiton-reference": true
    },
    "balance_as_of": {
      "type": "string",
      "description": "When the balance was observed. A current-state balance with no observation date cannot be aged, cannot answer \"as at\", and cannot satisfy a record-keeping duty that turns on currency.",
      "x-demiton-requiredness": "required",
      "format": "date",
      "x-demiton-type": "date"
    },
    "leave_category": {
      "type": "number",
      "description": "Which entitlement the balance is for. Without it the grain collapses into one ambiguous balance per worker rather than one per category.",
      "x-demiton-requiredness": "required"
    },
    "accrued_balance": {
      "type": "number",
      "description": "The accrual balance itself — a lifetime meter, never additive across readings. The shelf's only measure.",
      "x-demiton-requiredness": "required",
      "x-demiton-unit": "see `balance_unit`"
    },
    "entitlement_cap": {
      "type": "number",
      "description": "The ceiling on the accrued balance where one applies. Absent today and absent from every observed field, so it is optional; it exists because a bare balance cannot express a statutory maximum.",
      "x-demiton-requiredness": "optional",
      "x-demiton-unit": "see `balance_unit`"
    },
    "financial_period": {
      "type": "string",
      "description": "The period context of the balance reading, where the host supplies one.",
      "x-demiton-requiredness": "optional"
    },
    "leave_category_name": {
      "type": "string",
      "description": "Human-readable label for that entitlement (annual, personal/carer's, long service, …). Mandatory because a balance identified only by an opaque source code is unreadable to a person and unmappable across systems.",
      "x-demiton-requiredness": "required"
    }
  },
  "x-demiton-register-type": "leave_balance",
  "x-demiton-contract-version": "1.0.2",
  "x-demiton-store": "tenant",
  "x-demiton-axes": [
    {
      "axis": "financial_period",
      "requirement": "optional",
      "role": "context"
    },
    {
      "axis": "legal_entity",
      "requirement": "optional",
      "role": "context"
    },
    {
      "axis": "worker",
      "requirement": "required",
      "role": "subject"
    }
  ],
  "x-demiton-measures": [
    {
      "key": "accrued",
      "accumulation": "cumulative",
      "dtype": "decimal",
      "unit": "by_coordinate"
    }
  ],
  "x-demiton-provenance": {
    "standards": [
      {
        "code": "Fair Work Act 2009 (Cth)",
        "title": "Fair Work Act 2009 - employee records and National Employment Standards",
        "access": "full_text_verified",
        "clause": "ss.87, 96 ; s.113",
        "region": "Australia",
        "edition": "compilation 2026-07-07",
        "checked_on": "2026-09-14"
      },
      {
        "code": "Fair Work Regulations 2009 (Cth)",
        "title": "Fair Work Regulations 2009 - employee record content",
        "access": "full_text_verified",
        "clause": "reg 3.36",
        "region": "Australia",
        "edition": "compilation 2026-06-20",
        "checked_on": "2026-09-14"
      },
      {
        "code": "Single Touch Payroll Phase 2 (ATO)",
        "title": "Single Touch Payroll Phase 2 employer reporting guidelines",
        "access": "public_summary",
        "region": "Australia",
        "edition": "Phase 2 (mandatory from 1 Jan 2022)",
        "checked_on": "2026-09-14"
      },
      {
        "code": "ISO 30414:2025",
        "title": "Human resource management - Requirements and recommendations for human capital reporting and disclosure",
        "access": "paywalled_secondary",
        "region": "International",
        "edition": "2nd ed. 2025 (supersedes ISO 30414:2018)",
        "checked_on": "2026-09-14"
      },
      {
        "code": "Employment Leave Act 2026 (NZ)",
        "title": "Employment Leave Act 2026 (2026 No 48)",
        "access": "full_text_verified",
        "clause": "ss.24(1), 73(1), 75(1), 127",
        "region": "New Zealand",
        "edition": "assent 6 Aug 2026; not yet in force",
        "checked_on": "2026-09-14"
      },
      {
        "code": "Holidays Act 2003 (NZ)",
        "title": "Holidays Act 2003 (2003 No 129) - holiday and leave record",
        "access": "full_text_verified",
        "clause": "ss.16, 65(2), 81",
        "region": "New Zealand",
        "edition": "version as at 20 Dec 2023 (repealed on commencement of Employment Leave Act 2026)",
        "checked_on": "2026-09-14"
      },
      {
        "code": "SI 1998/1833",
        "title": "Working Time Regulations 1998",
        "access": "full_text_verified",
        "clause": "regs 13(1), 13A(3), 15B",
        "region": "United Kingdom",
        "edition": "as amended by SI 2023/1426 from 1 Jan 2024",
        "checked_on": "2026-09-14"
      }
    ]
  },
  "description": "Current leave balances per employee and leave category.",
  "x-demiton-contract-url": "https://docs.demiton.io/registers/leave_balance/",
  "x-demiton-register-catalog": "https://docs.demiton.io/concepts/register-catalog"
}