DeadlineReport

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/foretak-dev/json-schema/foretak-dev-deadline-report-schema.json",
  "title": "DeadlineReport",
  "description": "The answer to \"what must this company file, and by when?\".\n\nThis is the **only** shape the deadlines operation returns, on both\nsurfaces (``DECISIONS.md`` D-010): REST\n``GET /v1/{country}/company/{id}/deadlines`` and the MCP tool\n``company_deadlines`` each emit ``model_dump(mode=\"json\")`` of this model,\nunchanged. Neither surface may return a bare ``list[Deadline]``, because a\nlist has nowhere to put ``today`` or ``notes`` — and an empty list without\na note is indistinguishable from a bug.\n\nBuild it with ``Registry.deadline_report(report, today)``; do not construct\nit in a surface.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/foretak-dev-openapi.yml#/components/schemas/DeadlineReport",
  "properties": {
    "country": {
      "type": "string",
      "title": "Country",
      "description": "ISO-3166-1 alpha-2, upper-case."
    },
    "registry": {
      "type": "string",
      "title": "Registry",
      "description": "Registry slug, e.g. 'brreg'."
    },
    "company_id": {
      "type": "string",
      "title": "Company Id",
      "description": "Canonical national identifier the deadlines were computed for."
    },
    "company_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Company Name",
      "description": "Registered name, so the caller can echo it back to a user."
    },
    "today": {
      "type": "string",
      "format": "date",
      "title": "Today",
      "description": "The date 'next occurrence' was computed from, inclusive. Echoed back so the answer is reproducible and an agent can tell a cached answer from a fresh one."
    },
    "deadlines": {
      "items": {
        "$ref": "#/$defs/Deadline"
      },
      "type": "array",
      "title": "Deadlines",
      "description": "One entry per obligation kind, always the next occurrence, sorted by due_date. An empty list is a real answer, not an error — read `notes` for why."
    },
    "notes": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Notes",
      "description": "Caveats to surface to the user, carried over from the company report: why the list is empty, an unclassified legal form, a status that suspends filing."
    },
    "rules_last_reviewed": {
      "type": "string",
      "format": "date",
      "title": "Rules Last Reviewed",
      "description": "The date this country's deadline rules — the statutes and their day-count arithmetic — were last checked against the law; a deadline computed long after this date should be re-verified before anyone acts on it."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "country",
    "registry",
    "company_id",
    "today",
    "rules_last_reviewed"
  ],
  "$defs": {
    "Deadline": {
      "properties": {
        "country": {
          "type": "string",
          "title": "Country",
          "description": "ISO-3166-1 alpha-2, upper-case."
        },
        "registry": {
          "type": "string",
          "title": "Registry",
          "description": "Registry slug that produced this deadline."
        },
        "kind": {
          "type": "string",
          "title": "Kind",
          "description": "Stable machine slug for the obligation, e.g. 'annual_accounts', 'tax_return', 'vat_return', 'shareholder_register_statement'. Unique within a country."
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Short English label, e.g. 'Annual accounts filing'."
        },
        "local_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Local Name",
          "description": "The name a local accountant would use, e.g. 'Årsregnskap'."
        },
        "authority": {
          "type": "string",
          "title": "Authority",
          "description": "Who receives the filing, e.g. 'Regnskapsregisteret', 'Skatteetaten'."
        },
        "statutory_date": {
          "type": "string",
          "format": "date",
          "title": "Statutory Date",
          "description": "The date named by law, before weekend/holiday roll-forward."
        },
        "due_date": {
          "type": "string",
          "format": "date",
          "title": "Due Date",
          "description": "The date the caller must actually file by (statutory date rolled forward)."
        },
        "rolled_forward": {
          "type": "boolean",
          "title": "Rolled Forward",
          "description": "True when due_date differs from statutory_date because of a non-working day.",
          "default": false
        },
        "period_label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Period Label",
          "description": "Which period this filing covers, e.g. '2025' or '2026 term 3 (May–Jun)'."
        },
        "period_start": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Period Start",
          "description": "First day of the covered period."
        },
        "period_end": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Period End",
          "description": "Last day of the covered period."
        },
        "recurrence": {
          "$ref": "#/$defs/DeadlineRecurrence",
          "description": "How often the obligation repeats.",
          "default": "annual"
        },
        "mandatory": {
          "type": "boolean",
          "title": "Mandatory",
          "description": "True when the obligation follows from the legal form alone. False when it depends on facts we cannot see (e.g. VAT turnover threshold) — in that case applies_because explains the assumption.",
          "default": true
        },
        "applies_because": {
          "type": "string",
          "title": "Applies Because",
          "description": "One sentence an agent can quote to the user explaining why this deadline applies to this company, including any assumption made."
        },
        "days_until": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Days Until",
          "description": "due_date minus the `today` the calculation was run with. Negative = overdue."
        },
        "source_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source Url",
          "description": "Authoritative page describing the obligation."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "country",
        "registry",
        "kind",
        "name",
        "authority",
        "statutory_date",
        "due_date",
        "applies_because"
      ],
      "title": "Deadline",
      "description": "One filing obligation with a concrete calendar date.\n\nDeadlines are *computed*, never fetched: a registry module derives them\nfrom the entity's legal form and status plus a ``today`` parameter, so the\nsame input always produces the same output and tests are deterministic.\n\n``due_date`` is always the date the caller should act on; ``statutory_date``\nis the date the statute names before any weekend/holiday roll-forward."
    },
    "DeadlineRecurrence": {
      "type": "string",
      "enum": [
        "annual",
        "bimonthly",
        "quarterly",
        "monthly",
        "one_off"
      ],
      "title": "DeadlineRecurrence",
      "description": "How often a deadline repeats."
    }
  }
}