{
  "$defs": {
    "IsoCountry": {
      "description": "ISO 3166-1 alpha-2 country code.",
      "pattern": "^[A-Z]{2}$",
      "type": "string"
    },
    "IsoCurrency": {
      "description": "ISO 4217 currency code.",
      "pattern": "^[A-Z]{3}$",
      "type": "string"
    },
    "IsoDate": {
      "description": "ISO 8601 date (YYYY-MM-DD).",
      "format": "date",
      "type": "string"
    },
    "PathRef": {
      "description": "Path-based cross-reference relative to .corpospec/ root.\nPattern: `^[a-z0-9_-]+(/[a-z0-9_.-]+)+$`",
      "pattern": "^[a-z0-9_-]+(/[a-z0-9_.-]+)+$",
      "type": "string"
    },
    "PiiClass": {
      "description": "Personal-data classification on every record carrying personal data, per\nBDR 0070 / BDR 0069 / BDR 0078. Used by `corpospec-report` to gate\nrendering and by the privacy pillar's RoPA records to determine\nsafeguards.",
      "oneOf": [
        {
          "const": "none",
          "description": "No personal data.",
          "type": "string"
        },
        {
          "const": "public_personal",
          "description": "Public personal data (already disclosed by the subject, e.g. CEO name).",
          "type": "string"
        },
        {
          "const": "internal",
          "description": "Internal-only personal data (employee directory).",
          "type": "string"
        },
        {
          "const": "personal",
          "description": "Personal data per GDPR Art. 4(1).",
          "type": "string"
        },
        {
          "const": "special_category",
          "description": "Special-category data per GDPR Art. 9 (health, biometric, genetic,\nreligion, ethnicity, sex life, political opinion, trade union).",
          "type": "string"
        },
        {
          "const": "criminal_data",
          "description": "Criminal data per GDPR Art. 10.",
          "type": "string"
        },
        {
          "const": "sensitive",
          "description": "CCPA / CPRA \"sensitive personal information\".",
          "type": "string"
        }
      ]
    },
    "YearEndFormKind": {
      "description": "Year-end form kind.",
      "oneOf": [
        {
          "enum": [
            "other"
          ],
          "type": "string"
        },
        {
          "const": "de_lohnsteuerbescheinigung",
          "description": "DE — Lohnsteuerbescheinigung.",
          "type": "string"
        },
        {
          "const": "us_w2",
          "description": "US — Form W-2 (Wage and Tax Statement).",
          "type": "string"
        },
        {
          "const": "us1099_nec",
          "description": "US — Form 1099-NEC (non-employee comp).",
          "type": "string"
        },
        {
          "const": "us1099_misc",
          "description": "US — Form 1099-MISC.",
          "type": "string"
        },
        {
          "const": "uk_p60",
          "description": "UK — P60 End of Year Certificate.",
          "type": "string"
        },
        {
          "const": "uk_p11d",
          "description": "UK — P11D (benefits in kind).",
          "type": "string"
        },
        {
          "const": "fr_dsn_annual",
          "description": "FR — DSN annual recap.",
          "type": "string"
        },
        {
          "const": "nl_jaaropgaaf",
          "description": "NL — Jaaropgaaf.",
          "type": "string"
        },
        {
          "const": "at_lohnzettel_l16",
          "description": "AT — Lohnzettel L16.",
          "type": "string"
        },
        {
          "const": "ch_lohnausweis",
          "description": "CH — Lohnausweis.",
          "type": "string"
        }
      ]
    },
    "YearEndFormStatus": {
      "description": "Lifecycle.",
      "oneOf": [
        {
          "enum": [
            "draft",
            "issued",
            "reissued",
            "voided"
          ],
          "type": "string"
        },
        {
          "const": "filed",
          "description": "Filed with the tax authority.",
          "type": "string"
        }
      ]
    }
  },
  "$id": "https://corpospec.com/schemas/v0.16.0/year-end-form.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "One year-end form per person per jurisdiction per year.",
  "properties": {
    "currency": {
      "$ref": "#/$defs/IsoCurrency"
    },
    "document_ref": {
      "anyOf": [
        {
          "$ref": "#/$defs/PathRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "PathRef into the issued document PDF / XML."
    },
    "entity": {
      "$ref": "#/$defs/PathRef"
    },
    "gross_taxable": {
      "description": "Gross taxable wages.",
      "format": "double",
      "type": "number"
    },
    "id": {
      "$ref": "#/$defs/PathRef"
    },
    "income_tax_withheld": {
      "description": "Income tax withheld.",
      "format": "double",
      "type": "number"
    },
    "issued_on": {
      "$ref": "#/$defs/IsoDate"
    },
    "jurisdiction": {
      "$ref": "#/$defs/IsoCountry"
    },
    "kind": {
      "$ref": "#/$defs/YearEndFormKind"
    },
    "other_withholdings": {
      "description": "Other withholdings (church tax, solidarity, etc.).",
      "format": "double",
      "type": [
        "number",
        "null"
      ]
    },
    "payroll_runs": {
      "description": "PathRefs to underlying payroll-run records.",
      "items": {
        "$ref": "#/$defs/PathRef"
      },
      "type": "array"
    },
    "person": {
      "$ref": "#/$defs/PathRef"
    },
    "pii_class": {
      "$ref": "#/$defs/PiiClass"
    },
    "retention_until": {
      "$ref": "#/$defs/IsoDate",
      "description": "Retention until (10y per HGB §257 / AO §147)."
    },
    "social_contributions_withheld": {
      "description": "Social security / NIC contributions.",
      "format": "double",
      "type": "number"
    },
    "status": {
      "$ref": "#/$defs/YearEndFormStatus"
    },
    "statutory_due_date": {
      "$ref": "#/$defs/IsoDate",
      "description": "Statutory due date (DE: 28 Feb; US W-2: 31 Jan; UK P60: 31 May)."
    },
    "tax_year": {
      "description": "Tax year covered (calendar year for DE/US/NL; Apr-Apr for UK).",
      "format": "int32",
      "type": "integer"
    }
  },
  "required": [
    "id",
    "person",
    "entity",
    "kind",
    "tax_year",
    "jurisdiction",
    "currency",
    "gross_taxable",
    "income_tax_withheld",
    "social_contributions_withheld",
    "status",
    "issued_on",
    "statutory_due_date",
    "retention_until",
    "pii_class"
  ],
  "title": "YearEndForm",
  "type": "object",
  "x-corpospec-pillar": "financials"
}