{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api.gofile.co.uk/schemas/v1/schema-bundle.json",
  "title": "#GoFile Connect API v1 canonical schemas",
  "$defs": {
    "MoneyPence": {
      "type": "integer",
      "minimum": -999999999999999,
      "maximum": 999999999999999,
      "description": "Exact amount in integer pence. £1.23 is 123."
    },
    "Period": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "start",
        "end"
      ],
      "properties": {
        "start": {
          "type": "string",
          "format": "date",
          "description": "Inclusive period start date."
        },
        "end": {
          "type": "string",
          "format": "date",
          "description": "Inclusive period end date."
        }
      }
    },
    "VatReturn": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "vat_due_sales_pence",
        "vat_due_acquisitions_pence",
        "total_vat_due_pence",
        "vat_reclaimed_current_period_pence",
        "net_vat_due_pence",
        "total_value_sales_ex_vat_pence",
        "total_value_purchases_ex_vat_pence",
        "total_value_goods_supplied_ex_vat_pence",
        "total_acquisitions_ex_vat_pence"
      ],
      "properties": {
        "vat_due_sales_pence": {
          "$ref": "#/$defs/MoneyPence",
          "description": "Box 1: VAT due on sales and other outputs, in pence."
        },
        "vat_due_acquisitions_pence": {
          "$ref": "#/$defs/MoneyPence",
          "description": "Box 2: VAT due on acquisitions from other EC member states, in pence."
        },
        "total_vat_due_pence": {
          "$ref": "#/$defs/MoneyPence",
          "description": "Box 3: total VAT due; must equal boxes 1 plus 2."
        },
        "vat_reclaimed_current_period_pence": {
          "$ref": "#/$defs/MoneyPence",
          "description": "Box 4: VAT reclaimed on purchases and other inputs, in pence."
        },
        "net_vat_due_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 999999999999999,
          "description": "Box 5: absolute difference between boxes 3 and 4, in pence."
        },
        "total_value_sales_ex_vat_pence": {
          "description": "Box 6: whole-pound sales excluding VAT, represented as pence and therefore a multiple of 100.",
          "allOf": [
            {
              "$ref": "#/$defs/MoneyPence"
            },
            {
              "type": "integer",
              "multipleOf": 100
            }
          ]
        },
        "total_value_purchases_ex_vat_pence": {
          "description": "Box 7: whole-pound purchases excluding VAT, represented as pence and therefore a multiple of 100.",
          "allOf": [
            {
              "$ref": "#/$defs/MoneyPence"
            },
            {
              "type": "integer",
              "multipleOf": 100
            }
          ]
        },
        "total_value_goods_supplied_ex_vat_pence": {
          "description": "Box 8: whole-pound goods supplied excluding VAT, represented as pence and therefore a multiple of 100.",
          "allOf": [
            {
              "$ref": "#/$defs/MoneyPence"
            },
            {
              "type": "integer",
              "multipleOf": 100
            }
          ]
        },
        "total_acquisitions_ex_vat_pence": {
          "description": "Box 9: whole-pound acquisitions excluding VAT, represented as pence and therefore a multiple of 100.",
          "allOf": [
            {
              "$ref": "#/$defs/MoneyPence"
            },
            {
              "type": "integer",
              "multipleOf": 100
            }
          ]
        }
      },
      "examples": [
        {
          "vat_due_sales_pence": 12500,
          "vat_due_acquisitions_pence": 0,
          "total_vat_due_pence": 12500,
          "vat_reclaimed_current_period_pence": 2500,
          "net_vat_due_pence": 10000,
          "total_value_sales_ex_vat_pence": 100000,
          "total_value_purchases_ex_vat_pence": 20000,
          "total_value_goods_supplied_ex_vat_pence": 0,
          "total_acquisitions_ex_vat_pence": 0
        }
      ]
    },
    "ValidationIssue": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "description": "Stable machine-readable validation rule."
        },
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "JSON Pointer to the affected input field, or null for a request-level problem."
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable explanation; program logic should use code and path."
        },
        "severity": {
          "type": "string",
          "enum": [
            "error",
            "warning"
          ]
        },
        "expected_value": {
          "type": [
            "integer",
            "string",
            "null"
          ],
          "description": "Deterministic expected value or rule, when one exists."
        },
        "actual_value": {
          "type": [
            "integer",
            "string",
            "null"
          ],
          "description": "Rejected value or value type, when safely reportable."
        },
        "auto_correctable": {
          "type": "boolean",
          "description": "Whether the expected value is mathematically deterministic; #GoFile never changes it automatically."
        }
      }
    },
    "AuthorisationStanding": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "state",
        "reason",
        "checked_at",
        "continue_url",
        "continue_url_expires_at",
        "message"
      ],
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "authorised",
            "unauthorised"
          ]
        },
        "reason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "authorisation_missing",
            "authorisation_lapsed",
            "client_not_authorised",
            null
          ],
          "description": "Why the account is unauthorised; null when authorised. client_not_authorised is fixed at HMRC between agent and client, so it carries no continue_url."
        },
        "checked_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "continue_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Hosted renewal URL when GoFile can repair the grant. Authorisation journeys expire after 20 minutes. Follow the returned URL and expiry."
        },
        "continue_url_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "message": {
          "type": "string"
        },
        "relationship_state": {
          "type": "string",
          "description": "Income Tax only: the HMRC relationship state, e.g. active."
        },
        "hmrc_connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$",
          "description": "Income Tax only: the exact grant serving this client."
        },
        "grant_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Income Tax only: expiry of the HMRC grant, when known."
        }
      },
      "description": "Authorisation standing inside a status body. Unauthorised is a valid HTTP 200 status (envelope state action_required), never an error."
    },
    "VatFilingRef": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "status"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^vfs_[a-f0-9]{48}$"
        },
        "status": {
          "type": "string"
        },
        "continue_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Hosted approval journey for an in-flight filing. Null unless the key also holds vat:prepare and the filing is still awaiting approval; a read-only key never receives approval credentials."
        },
        "gofile_reference": {
          "type": "string",
          "pattern": "^GF-VAT-[0-9]+$",
          "description": "Present once submitted through #GoFile."
        }
      },
      "description": "Pointer from an obligation to the #GoFile filing that covers it."
    },
    "VatOpenObligation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "period",
        "due",
        "overdue",
        "filing"
      ],
      "properties": {
        "period": {
          "$ref": "#/$defs/Period"
        },
        "due": {
          "type": "string",
          "format": "date"
        },
        "overdue": {
          "type": "boolean"
        },
        "filing": {
          "oneOf": [
            {
              "$ref": "#/$defs/VatFilingRef"
            },
            {
              "type": "null"
            }
          ],
          "description": "The in-flight #GoFile filing for this period, or null."
        }
      }
    },
    "VatFulfilledObligation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "period",
        "due",
        "received",
        "hmrc_confirmed",
        "return",
        "filing"
      ],
      "properties": {
        "period": {
          "$ref": "#/$defs/Period"
        },
        "due": {
          "type": "string",
          "format": "date"
        },
        "received": {
          "type": "string",
          "format": "date"
        },
        "hmrc_confirmed": {
          "type": "boolean",
          "description": "false while a #GoFile submission has not yet been re-confirmed against HMRC's own record."
        },
        "return": {
          "oneOf": [
            {
              "$ref": "#/$defs/VatReturn"
            },
            {
              "type": "null"
            }
          ],
          "description": "The filed nine-box figures in integer pence, or null with a sibling return_status."
        },
        "return_status": {
          "type": "string",
          "enum": [
            "pending",
            "unavailable",
            "unavailable_hmrc_age_limit"
          ],
          "description": "Present only when return is null: pending fetch, given up, or beyond HMRC's ~4-year window."
        },
        "filing": {
          "oneOf": [
            {
              "$ref": "#/$defs/VatFilingRef"
            },
            {
              "type": "null"
            }
          ],
          "description": "The submitted #GoFile filing for this period, or null when filed elsewhere."
        }
      }
    },
    "VatObligation": {
      "oneOf": [
        {
          "$ref": "#/$defs/VatOpenObligation"
        },
        {
          "$ref": "#/$defs/VatFulfilledObligation"
        }
      ],
      "description": "One entry from /api/v1/vat obligations.open or obligations.fulfilled."
    },
    "VatLiability": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "period",
        "amount",
        "outstanding",
        "due"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "HMRC charge type, e.g. VAT Return Debit Charge."
        },
        "period": {
          "$ref": "#/$defs/Period"
        },
        "amount": {
          "type": "string",
          "pattern": "^-?[0-9]+\\.[0-9]{2}$",
          "description": "Decimal pounds as a string."
        },
        "outstanding": {
          "type": "string",
          "pattern": "^-?[0-9]+\\.[0-9]{2}$",
          "description": "Decimal pounds as a string."
        },
        "due": {
          "type": "string"
        }
      }
    },
    "VatPayment": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "amount",
        "received"
      ],
      "properties": {
        "amount": {
          "type": "string",
          "pattern": "^-?[0-9]+\\.[0-9]{2}$",
          "description": "Decimal pounds as a string."
        },
        "received": {
          "type": "string"
        }
      }
    },
    "VatBalance": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "state",
        "liabilities",
        "payments",
        "as_of"
      ],
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "ready",
            "syncing"
          ],
          "description": "syncing (with empty arrays) until the first balance sync completes."
        },
        "liabilities": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/VatLiability"
          }
        },
        "payments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/VatPayment"
          }
        },
        "as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "VatReturnDraft": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "return",
        "software_user_id",
        "software_user_login"
      ],
      "properties": {
        "external_filing_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Optional reference from your software. Replays an identical filing and rejects reuse with changed content."
        },
        "software_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Current authenticated user in the originating software. Required on every preparation request; not inherited from the authorisation initiator."
        },
        "period": {
          "$ref": "#/$defs/Period"
        },
        "return": {
          "$ref": "#/$defs/VatReturn"
        },
        "return_url": {
          "type": "string",
          "format": "uri",
          "maxLength": 500
        },
        "software_user_login": {
          "type": "string",
          "minLength": 1,
          "maxLength": 254,
          "pattern": "^[^\\x00-\\x1f\\x7f]+$",
          "description": "Current authenticated user's login identifier (username, email or phone), supplied by the backend and stored encrypted for fraud evidence."
        }
      }
    },
    "ItsaSelfEmploymentCumulative": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "turnover_pence",
        "consolidated_expenses_pence"
      ],
      "properties": {
        "turnover_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999
        },
        "other_income_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "tax_taken_off_trading_income_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "consolidated_expenses_pence": {
          "type": "integer",
          "minimum": -9999999999999,
          "maximum": 9999999999999
        }
      },
      "description": "Cumulative year-to-date Self Employment totals in integer pence. Only turnover and consolidated expenses are required; omitted optional totals become zero. This consolidated-expenses product is for customers eligible for HMRC's under-£90,000 annual-turnover option."
    },
    "ItsaUkPropertyCumulative": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "property_income_pence",
        "consolidated_expenses_pence"
      ],
      "properties": {
        "property_income_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999
        },
        "other_income_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "premiums_of_lease_grant_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "reverse_premiums_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "tax_deducted_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "rent_a_room_income_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "consolidated_expenses_pence": {
          "type": "integer",
          "minimum": -9999999999999,
          "maximum": 9999999999999
        },
        "residential_financial_cost_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "residential_financial_costs_carried_forward_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        },
        "rent_a_room_amount_claimed_pence": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999999999999,
          "default": 0
        }
      },
      "description": "Cumulative year-to-date UK Property totals in integer pence. Only property income and consolidated expenses are required; omitted optional totals become zero. This consolidated-expenses product is for customers eligible for HMRC's under-£90,000 annual-turnover option."
    },
    "ItsaCumulative": {
      "oneOf": [
        {
          "$ref": "#/$defs/ItsaSelfEmploymentCumulative"
        },
        {
          "$ref": "#/$defs/ItsaUkPropertyCumulative"
        }
      ]
    },
    "ItsaQuarterlyUpdateDraft": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "software_user_id",
        "business_id",
        "tax_year",
        "period",
        "cumulative",
        "software_user_login"
      ],
      "properties": {
        "external_update_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "software_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "business_id": {
          "type": "string",
          "pattern": "^X[A-Z0-9]IS[0-9]{11}$"
        },
        "tax_year": {
          "type": "string",
          "pattern": "^20(2[5-9]|[3-9][0-9])-\\d{2}$"
        },
        "period": {
          "$ref": "#/$defs/Period"
        },
        "cumulative": {
          "$ref": "#/$defs/ItsaCumulative"
        },
        "software_user_login": {
          "type": "string",
          "minLength": 1,
          "maxLength": 254,
          "pattern": "^[^\\x00-\\x1f\\x7f]+$",
          "description": "Current authenticated user's login identifier (username, email or phone), supplied by the backend and stored encrypted for fraud evidence."
        }
      }
    },
    "ItsaQuarterlyUpdateIntent": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "software_user_id",
        "obligation_id",
        "cumulative",
        "software_user_login"
      ],
      "properties": {
        "external_update_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "software_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "obligation_id": {
          "type": "string",
          "pattern": "^ito_[a-f0-9]{24}$",
          "description": "Copy this from POST /api/v1/itsa; it resolves the business, income-source type, tax year and period."
        },
        "cumulative": {
          "$ref": "#/$defs/ItsaCumulative"
        },
        "software_user_login": {
          "type": "string",
          "minLength": 1,
          "maxLength": 254,
          "pattern": "^[^\\x00-\\x1f\\x7f]+$",
          "description": "Current authenticated user's login identifier (username, email or phone), supplied by the backend and stored encrypted for fraud evidence."
        }
      }
    },
    "ClientActionAuthentication": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "mfa_type",
        "mfa_at",
        "factor_reference"
      ],
      "properties": {
        "mfa_type": {
          "type": "string",
          "enum": [
            "TOTP",
            "AUTH_CODE",
            "OTHER"
          ]
        },
        "mfa_at": {
          "type": "string",
          "format": "date-time"
        },
        "factor_reference": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._-]{1,120}$"
        }
      }
    },
    "ItsaObligation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "obligation_id",
        "period",
        "due",
        "status",
        "received",
        "overdue",
        "can_submit"
      ],
      "properties": {
        "obligation_id": {
          "type": "string",
          "pattern": "^ito_[a-f0-9]{24}$"
        },
        "period": {
          "$ref": "#/$defs/Period"
        },
        "due": {
          "type": "string",
          "format": "date"
        },
        "status": {
          "type": "string",
          "enum": [
            "open",
            "fulfilled"
          ]
        },
        "received": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "overdue": {
          "type": "boolean"
        },
        "can_submit": {
          "type": "boolean"
        }
      }
    },
    "ItsaBusiness": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "business_id",
        "business_type",
        "trading_name",
        "trading_type",
        "quarterly_period_type",
        "commencement_date",
        "cessation_date",
        "obligations",
        "current_cumulative_update"
      ],
      "properties": {
        "business_id": {
          "type": "string",
          "pattern": "^X[A-Z0-9]IS[0-9]{11}$"
        },
        "business_type": {
          "type": "string",
          "enum": [
            "self-employment",
            "uk-property"
          ]
        },
        "trading_name": {
          "type": "string"
        },
        "trading_type": {
          "type": "string"
        },
        "quarterly_period_type": {
          "type": "string"
        },
        "commencement_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "cessation_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "obligations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ItsaObligation"
          }
        },
        "current_cumulative_update": {
          "type": [
            "object",
            "null"
          ],
          "description": "HMRC's latest cumulative totals for this tax year, when one has been submitted."
        }
      }
    },
    "ItsaSubmission": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "submission_id",
        "business_id",
        "business_type",
        "period",
        "cumulative",
        "submitted_at",
        "hmrc_correlation_id",
        "source"
      ],
      "properties": {
        "submission_id": {
          "type": "string",
          "pattern": "^itu_[a-f0-9]{24}$"
        },
        "business_id": {
          "type": "string"
        },
        "business_type": {
          "type": "string",
          "enum": [
            "self-employment",
            "uk-property"
          ]
        },
        "period": {
          "$ref": "#/$defs/Period"
        },
        "cumulative": {
          "$ref": "#/$defs/ItsaCumulative"
        },
        "submitted_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "hmrc_correlation_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "const": "gofile"
        }
      },
      "description": "One immutable submission made through #GoFile; HMRC itself exposes only the latest cumulative update."
    },
    "ValidationReport": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "valid",
        "errors",
        "warnings",
        "canonical_draft",
        "payload_hash",
        "submission_occurred"
      ],
      "properties": {
        "valid": {
          "type": "boolean"
        },
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ValidationIssue"
          }
        },
        "warnings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ValidationIssue"
          }
        },
        "canonical_draft": {
          "oneOf": [
            {
              "$ref": "#/$defs/VatReturnDraft"
            },
            {
              "$ref": "#/$defs/ItsaQuarterlyUpdateDraft"
            },
            {
              "type": "null"
            }
          ]
        },
        "payload_hash": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[a-f0-9]{64}$"
        },
        "submission_occurred": {
          "const": false
        },
        "validate_only": {
          "const": true,
          "description": "Present when the report came from a validate_only prepare call."
        }
      }
    },
    "ApprovalRequirement": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "kind",
        "declaration_roles",
        "continue_url",
        "ai_approval_is_sufficient"
      ],
      "properties": {
        "kind": {
          "const": "hosted_human_approval"
        },
        "continue_url": {
          "type": "string",
          "format": "uri"
        },
        "ai_approval_is_sufficient": {
          "const": false
        },
        "declaration_roles": {
          "type": "array",
          "items": {
            "enum": [
              "business",
              "agent"
            ]
          }
        }
      }
    },
    "SubmissionReceipt": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "gofile_reference",
        "processing_date",
        "form_bundle"
      ],
      "properties": {
        "gofile_reference": {
          "type": "string",
          "pattern": "^GF-VAT-[0-9]+$"
        },
        "processing_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "form_bundle": {
          "type": [
            "string",
            "null"
          ]
        },
        "reconciled": {
          "type": "boolean"
        }
      }
    },
    "WebhookEvent": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "event_id",
        "event_version",
        "event_type",
        "occurred_at",
        "integration_id",
        "connection_id",
        "resource_id",
        "resource_type",
        "data"
      ],
      "properties": {
        "event_id": {
          "type": "string"
        },
        "event_version": {
          "const": "2"
        },
        "event_type": {
          "enum": [
            "connection.authorised",
            "connection.disconnected",
            "connection.reauthorisation_required",
            "vat.status.updated",
            "vat.filing.awaiting_approval",
            "vat.filing.requires_review",
            "vat.filing.submitted",
            "vat.filing.failed",
            "itsa.status.updated",
            "itsa.quarterly_update.submitted",
            "itsa.client_action.completed"
          ]
        },
        "occurred_at": {
          "type": "string",
          "format": "date-time"
        },
        "integration_id": {
          "type": "string"
        },
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        },
        "resource_id": {
          "type": "string"
        },
        "resource_type": {
          "enum": [
            "hmrc_connection",
            "vat_status",
            "vat_filing_session",
            "itsa_status",
            "itsa_quarterly_update",
            "itsa_client_action"
          ]
        },
        "data": {
          "type": "object",
          "properties": {
            "connection_id": {
              "type": "string"
            },
            "vat_number": {
              "type": "string",
              "pattern": "^[0-9]{9}$"
            }
          },
          "required": [
            "connection_id"
          ]
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "connection.authorised"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "hmrc_connection"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "connection.disconnected"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "hmrc_connection"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "connection.reauthorisation_required"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "hmrc_connection"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "vat.status.updated"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "vat_status"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "vat.filing.awaiting_approval"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "vat_filing_session"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "vat.filing.requires_review"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "vat_filing_session"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "vat.filing.submitted"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "vat_filing_session"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "vat.filing.failed"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "vat_filing_session"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "itsa.status.updated"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "itsa_status"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "itsa.quarterly_update.submitted"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "itsa_quarterly_update"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "event_type": {
                "const": "itsa.client_action.completed"
              }
            }
          },
          "then": {
            "properties": {
              "resource_type": {
                "const": "itsa_client_action"
              }
            }
          }
        }
      ]
    },
    "ConnectionVatStatus": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "vat_number",
        "mode",
        "authorisation",
        "obligations",
        "balance",
        "history",
        "data_as_of",
        "connection_id"
      ],
      "properties": {
        "vat_number": {
          "type": "string",
          "pattern": "^[0-9]{9}$"
        },
        "mode": {
          "type": "string",
          "enum": [
            "sandbox",
            "live"
          ]
        },
        "authorisation": {
          "$ref": "#/$defs/AuthorisationStanding"
        },
        "obligations": {
          "oneOf": [
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "open",
                "fulfilled"
              ],
              "properties": {
                "open": {
                  "type": "array",
                  "items": {
                    "$ref": "#/$defs/VatOpenObligation"
                  }
                },
                "fulfilled": {
                  "type": "array",
                  "items": {
                    "$ref": "#/$defs/VatFulfilledObligation"
                  }
                }
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "null while unauthorised."
        },
        "balance": {
          "oneOf": [
            {
              "$ref": "#/$defs/VatBalance"
            },
            {
              "type": "null"
            }
          ],
          "description": "null while unauthorised."
        },
        "history": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "syncing",
            "complete",
            null
          ],
          "description": "syncing until the one-off deep history walk to 2017-01-01 completes; null while unauthorised."
        },
        "data_as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Last successful ledger reconciliation. Refreshed weekly, when a read finds it older than five minutes, and 30 minutes after a return filed through GoFile; HMRC failures and throttling can make data older. This is not the response fetched_at timestamp or a maximum-age guarantee."
        },
        "simulated": {
          "const": true,
          "description": "Present on simulated-sandbox bodies only."
        },
        "sandbox_note": {
          "type": "string",
          "description": "Present on simulated-sandbox bodies only."
        },
        "retry": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "safe"
          ],
          "properties": {
            "safe": {
              "const": true
            },
            "after_seconds": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        }
      },
      "description": "The data payload of POST /api/v1/vat: everything about one client's VAT account in one call."
    },
    "ConnectionVatFiling": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "submission_id",
        "mode",
        "method",
        "external_filing_id",
        "vat_number",
        "period",
        "filing_version",
        "payload_hash",
        "submission_occurred",
        "provenance",
        "created_at",
        "connection_id"
      ],
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "sandbox",
            "live"
          ]
        },
        "method": {
          "const": "vat"
        },
        "external_filing_id": {
          "type": "string",
          "maxLength": 120
        },
        "vat_number": {
          "type": "string",
          "pattern": "^[0-9]{9}$"
        },
        "period": {
          "$ref": "#/$defs/Period"
        },
        "filing_version": {
          "type": "integer",
          "minimum": 1
        },
        "payload_hash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "submission_occurred": {
          "type": "boolean"
        },
        "provenance": {
          "$ref": "#/$defs/RecordedProvenance"
        },
        "continue_url": {
          "type": "string",
          "format": "uri",
          "description": "Hosted human approval journey; present while the filing is open."
        },
        "approval_requirement": {
          "$ref": "#/$defs/ApprovalRequirement"
        },
        "receipt": {
          "$ref": "#/$defs/SubmissionReceipt"
        },
        "failure": {
          "type": "object"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "submitted_at": {
          "type": "string",
          "format": "date-time"
        },
        "simulated": {
          "const": true,
          "description": "Present on simulated-sandbox bodies only."
        },
        "sandbox_note": {
          "type": "string",
          "description": "Present on simulated-sandbox bodies only."
        },
        "retry": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "safe"
          ],
          "properties": {
            "safe": {
              "const": true
            },
            "after_seconds": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        },
        "submission_id": {
          "type": "string",
          "pattern": "^vfs_[a-f0-9]{48}$"
        },
        "continue_url_expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "Expiry of this hosted approval capability: five minutes after the action was created. Separate from retention of the submission and receipt."
        }
      }
    },
    "ConnectionItsaStatus": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "tax_service",
        "mode",
        "tax_year",
        "national_insurance_number",
        "nino_verified",
        "authorisation",
        "businesses",
        "gofile_submission_history",
        "data_as_of",
        "connection_id"
      ],
      "properties": {
        "tax_service": {
          "const": "itsa"
        },
        "mode": {
          "type": "string",
          "enum": [
            "sandbox",
            "live"
          ]
        },
        "tax_year": {
          "type": "string",
          "pattern": "^20(2[5-9]|[3-9][0-9])-\\d{2}$"
        },
        "national_insurance_number": {
          "type": "string",
          "pattern": "^\\*{6}[0-9]{2}[A-D]$"
        },
        "nino_verified": {
          "type": "boolean",
          "description": "true only after HMRC accepts this authorisation for the NINO."
        },
        "authorisation": {
          "$ref": "#/$defs/AuthorisationStanding"
        },
        "businesses": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ItsaBusiness"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Self Employment and UK Property businesses, or null while unauthorised."
        },
        "gofile_submission_history": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ItsaSubmission"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "null while unauthorised."
        },
        "history_note": {
          "type": "string"
        },
        "synced_at": {
          "type": "string",
          "format": "date-time"
        },
        "data_as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Last successful ledger reconciliation. Refreshed weekly, when a read finds it older than five minutes, and 30 minutes after an update submitted through GoFile; HMRC failures and throttling can make data older. This is not the response fetched_at timestamp or a maximum-age guarantee."
        },
        "simulated": {
          "const": true,
          "description": "Present on simulated-sandbox bodies only."
        },
        "sandbox_note": {
          "type": "string",
          "description": "Present on simulated-sandbox bodies only."
        },
        "retry": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "safe"
          ],
          "properties": {
            "safe": {
              "const": true
            },
            "after_seconds": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        }
      },
      "description": "POST /api/v1/itsa: verified identity, supported businesses, obligations, latest HMRC cumulative data and #GoFile receipts."
    },
    "ConnectionVatFilingRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "connection_id",
        "vat_number",
        "return",
        "software_user_id",
        "software_user_login"
      ],
      "properties": {
        "external_filing_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Optional reference from your software. Replays an identical filing and rejects reuse with changed content."
        },
        "software_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Current authenticated user in the originating software. Required on every preparation request; not inherited from the authorisation initiator."
        },
        "period": {
          "$ref": "#/$defs/Period"
        },
        "return": {
          "$ref": "#/$defs/VatReturn"
        },
        "return_url": {
          "type": "string",
          "format": "uri",
          "maxLength": 500
        },
        "validate_only": {
          "type": "boolean",
          "default": false,
          "description": "true runs only the canonical validation and creates nothing; the response is the validation report."
        },
        "client_action": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "authentication": {
              "$ref": "#/$defs/ClientActionAuthentication"
            }
          },
          "description": "Software-user MFA attestation for the hosted approval action. Required in live mode by default; no GoFile end-user account is required."
        },
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        },
        "vat_number": {
          "type": "string",
          "pattern": "^[0-9]{9}$"
        },
        "software_user_login": {
          "type": "string",
          "minLength": 1,
          "maxLength": 254,
          "pattern": "^[^\\x00-\\x1f\\x7f]+$",
          "description": "Current authenticated user's login identifier (username, email or phone), supplied by the backend and stored encrypted for fraud evidence."
        }
      },
      "description": "Request body of POST /api/v1/vat/prepare: the canonical VAT return draft plus the optional validate_only flag."
    },
    "RecordedProvenance": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "integration": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "id",
            "name"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "description": "Registered integration identity captured by GoFile when the submission record was created."
        },
        "actor_software": {
          "const": "#GoFile",
          "description": "Present for a GoFile-authenticated MCP actor."
        }
      }
    },
    "VatRetrieveRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "connection_id",
        "vat_number"
      ],
      "properties": {
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        },
        "vat_number": {
          "type": "string",
          "pattern": "^[0-9]{9}$"
        },
        "submission_id": {
          "type": "string",
          "pattern": "^vfs_[a-f0-9]{48}$",
          "description": "Optional: retrieve one submission and its receipt instead of account information."
        }
      }
    },
    "ItsaRetrieveRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "connection_id",
        "national_insurance_number"
      ],
      "properties": {
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        },
        "national_insurance_number": {
          "type": "string",
          "minLength": 9,
          "maxLength": 13
        },
        "submission_id": {
          "type": "string",
          "pattern": "^itu_[a-f0-9]{24}$",
          "description": "Optional: retrieve one submission and its receipt instead of account information."
        },
        "tax_year": {
          "type": "string",
          "pattern": "^20[0-9]{2}-[0-9]{2}$",
          "description": "Optional, 2025-26 or later. Defaults to the current UK tax year. Omit when retrieving a specific update."
        }
      },
      "not": {
        "required": [
          "tax_year",
          "submission_id"
        ]
      }
    },
    "ConnectionItsaPrepareRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "connection_id",
        "national_insurance_number",
        "software_user_id",
        "obligation_id",
        "cumulative",
        "software_user_login"
      ],
      "properties": {
        "external_update_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "software_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "obligation_id": {
          "type": "string",
          "pattern": "^ito_[a-f0-9]{24}$"
        },
        "cumulative": {
          "$ref": "#/$defs/ItsaCumulative"
        },
        "client_action": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "authentication": {
              "$ref": "#/$defs/ClientActionAuthentication"
            }
          },
          "description": "Optional. Live mode may require the authentication MFA assertion."
        },
        "validate_only": {
          "type": "boolean",
          "default": false,
          "description": "true runs validation and creates nothing."
        },
        "software_user_login": {
          "type": "string",
          "minLength": 1,
          "maxLength": 254,
          "pattern": "^[^\\x00-\\x1f\\x7f]+$",
          "description": "Current authenticated user's login identifier (username, email or phone), supplied by the backend and stored encrypted for fraud evidence."
        },
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        },
        "national_insurance_number": {
          "type": "string"
        }
      },
      "description": "Prepare one Self Employment or UK Property cumulative update using an obligation returned by status."
    },
    "ConnectionItsaUpdate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "connection_id",
        "submission_id",
        "external_update_id",
        "business_id",
        "business_type",
        "tax_year",
        "period",
        "cumulative",
        "submitted_at",
        "last_error"
      ],
      "properties": {
        "connection_id": {
          "type": "string",
          "pattern": "^hmc_[a-f0-9]{24}$"
        },
        "submission_id": {
          "type": "string",
          "pattern": "^itu_[a-f0-9]{24}$"
        },
        "external_update_id": {
          "type": "string"
        },
        "business_id": {
          "type": "string"
        },
        "business_type": {
          "enum": [
            "self-employment",
            "uk-property"
          ]
        },
        "tax_year": {
          "type": "string"
        },
        "period": {
          "$ref": "#/$defs/Period"
        },
        "cumulative": {
          "$ref": "#/$defs/ItsaCumulative"
        },
        "submitted_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "last_error": {
          "type": [
            "string",
            "null"
          ]
        },
        "continue_url": {
          "type": "string",
          "format": "uri"
        },
        "continue_url_expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "Expiry of this hosted approval capability: five minutes after the action was created. Separate from retention of the submission and receipt."
        },
        "receipt": {
          "type": "object",
          "required": [
            "hmrc_correlation_id",
            "accepted_at",
            "business_type"
          ],
          "additionalProperties": false,
          "properties": {
            "hmrc_correlation_id": {
              "type": [
                "string",
                "null"
              ]
            },
            "accepted_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "business_type": {
              "type": "string"
            },
            "confirmed_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "resolution": {
              "enum": [
                "hmrc_readback",
                "operator"
              ]
            }
          }
        }
      }
    },
    "PreparationValidation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "valid",
        "errors",
        "warnings",
        "canonical_draft",
        "payload_hash",
        "submission_occurred"
      ],
      "properties": {
        "valid": {
          "type": "boolean"
        },
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ValidationIssue"
          }
        },
        "warnings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ValidationIssue"
          }
        },
        "canonical_draft": {
          "oneOf": [
            {
              "$ref": "#/$defs/VatReturnDraft"
            },
            {
              "$ref": "#/$defs/ItsaQuarterlyUpdateDraft"
            },
            {
              "type": "null"
            }
          ]
        },
        "payload_hash": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[a-f0-9]{64}$"
        },
        "submission_occurred": {
          "const": false
        },
        "validate_only": {
          "const": true
        }
      }
    },
    "GoFileProblem": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "request_id",
        "fetched_at",
        "state",
        "data"
      ],
      "properties": {
        "request_id": {
          "type": "string"
        },
        "fetched_at": {
          "type": "string",
          "format": "date-time"
        },
        "state": {
          "const": "error"
        },
        "data": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "errors": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/$defs/ValidationIssue"
              }
            },
            "next_action": {
              "type": "object"
            },
            "retry": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "safe"
              ],
              "properties": {
                "safe": {
                  "const": true
                },
                "after_seconds": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "AuthorisationSession": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "authorisation_session_id",
            "expires_at"
          ],
          "properties": {
            "authorisation_session_id": {
              "type": "string",
              "pattern": "^aus_[a-f0-9]{48}$"
            },
            "expires_at": {
              "type": "string",
              "format": "date-time"
            },
            "authorisation_url": {
              "type": "string",
              "format": "uri"
            },
            "notice": {
              "type": "string",
              "description": "Sandbox only: the start omitted the client identifier that a live authorisation requires, so nothing is fetched at consent."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "connection_id"
          ],
          "properties": {
            "connection_id": {
              "type": "string",
              "pattern": "^hmc_[a-f0-9]{24}$"
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string"
            }
          }
        }
      ]
    },
    "VatAuthorisationRequest": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "software_user_id"
          ],
          "properties": {
            "software_user_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120,
              "description": "Current authenticated software user initiating this authorisation. Does not identify subsequent filers."
            },
            "return_url": {
              "type": "string",
              "format": "uri",
              "description": "Optional HTTPS callback on the integration allowlist. No fragment or gofile_session parameter. After consent GoFile fetches the client's information, then redirects here with gofile_session; the backend validates its own state and retrieves the result with a signed request."
            },
            "connection_id": {
              "type": "string",
              "pattern": "^hmc_[a-f0-9]{24}$",
              "description": "Renew this existing connection instead of creating one. A renewal may omit the tax identifier; the connection's known clients are refreshed."
            },
            "vat_number": {
              "type": "string",
              "pattern": "^[0-9]{9}$",
              "description": "The client this authorisation is for. Required for a new LIVE connection (422 required without it); the sandbox accepts its absence and returns data.notice. After consent GoFile fetches this client's VAT information at once."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "authorisation_session_id"
          ],
          "properties": {
            "authorisation_session_id": {
              "type": "string",
              "pattern": "^aus_[a-f0-9]{48}$"
            }
          }
        }
      ]
    },
    "ItsaAuthorisationRequest": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "software_user_id"
          ],
          "properties": {
            "software_user_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120,
              "description": "Current authenticated software user initiating this authorisation. Does not identify subsequent filers."
            },
            "return_url": {
              "type": "string",
              "format": "uri",
              "description": "Optional HTTPS callback on the integration allowlist. No fragment or gofile_session parameter. After consent GoFile fetches the client's information, then redirects here with gofile_session; the backend validates its own state and retrieves the result with a signed request."
            },
            "connection_id": {
              "type": "string",
              "pattern": "^hmc_[a-f0-9]{24}$",
              "description": "Renew this existing connection instead of creating one. A renewal may omit the tax identifier; the connection's known clients are refreshed."
            },
            "national_insurance_number": {
              "type": "string",
              "minLength": 9,
              "maxLength": 13,
              "description": "The client this authorisation is for. Required for a new LIVE connection (422 required without it); the sandbox accepts its absence and returns data.notice. After consent GoFile fetches this client's Income Tax information at once."
            },
            "tax_year": {
              "type": "string",
              "pattern": "^20[0-9]{2}-[0-9]{2}$",
              "description": "Optional, 2025-26 or later. Defaults to the current UK tax year."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "authorisation_session_id"
          ],
          "properties": {
            "authorisation_session_id": {
              "type": "string",
              "pattern": "^aus_[a-f0-9]{48}$"
            }
          }
        }
      ]
    }
  }
}