{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://customshive.local/schemas/canonical/declaration.schema.json",
  "title": "CanonicalDeclaration",
  "description": "Unified ingestion contract for all customs regimes (IM/EX/T1/T2). Send via POST /api/declarations or publish to the canonical ServiceBus queue. Property names are case-insensitive; snake_case is the recommended format. Unknown fields are accepted and ignored.",
  "type": "object",
  "required": ["declaration_type"],
  "properties": {
    "declaration_type": {
      "type": "string",
      "enum": ["IM", "EX", "T1", "T2"],
      "description": "Customs regime. Determines which adapter processes the dossier."
    },
    "regime": {
      "type": ["string", "null"],
      "description": "Regime sub-type (e.g. H1, H2, B1). Derived from declaration_type when omitted."
    },
    "ucr": {
      "type": ["string", "null"],
      "description": "Caller-supplied house bill / UCR reference. Auto-generated when omitted."
    },
    "client_code": {
      "type": ["string", "null"],
      "description": "Internal Client.Code shortcut. Takes precedence over EORI party lookup when set."
    },
    "parties": { "$ref": "#/$defs/CanonicalParties" },
    "shipment": { "$ref": "#/$defs/CanonicalShipment" },
    "transport": { "$ref": "#/$defs/CanonicalTransport" },
    "customs_offices": { "$ref": "#/$defs/CanonicalOffices" },
    "authorised_location_of_goods": { "$ref": "#/$defs/CanonicalLocationOfGoods" },
    "loading_location": { "$ref": "#/$defs/CanonicalLoadingLocation" },
    "totals": { "$ref": "#/$defs/CanonicalTotals" },
    "documents": {
      "type": ["array", "null"],
      "items": { "$ref": "#/$defs/CanonicalDocument" },
      "description": "Header-level supporting/previous documents."
    },
    "authorisations": {
      "type": ["array", "null"],
      "items": { "$ref": "#/$defs/CanonicalAuthorisation" }
    },
    "guarantees": {
      "type": ["array", "null"],
      "items": { "$ref": "#/$defs/CanonicalGuarantee" }
    },
    "house_consignments": {
      "type": ["array", "null"],
      "items": { "$ref": "#/$defs/CanonicalHouseConsignment" },
      "description": "T2 groupage only. Each consignment groups one or more goods_items via house_consignment_sequence."
    },
    "goods_items": {
      "type": "array",
      "items": { "$ref": "#/$defs/CanonicalGoodsItem" },
      "default": []
    }
  },

  "$defs": {
    "CanonicalParties": {
      "type": "object",
      "properties": {
        "declarant":          { "$ref": "#/$defs/CanonicalParty" },
        "representative":     { "$ref": "#/$defs/CanonicalParty" },
        "exporter":           { "$ref": "#/$defs/CanonicalParty" },
        "importer":           { "$ref": "#/$defs/CanonicalParty" },
        "consignee":          { "$ref": "#/$defs/CanonicalParty", "description": "Top-level consignee (simple declarations). Per-HC consignees go inside house_consignments." },
        "consignor":          { "$ref": "#/$defs/CanonicalParty", "description": "T1/T2 — typically the forwarder." },
        "transit_principal":  { "$ref": "#/$defs/CanonicalParty", "description": "T1/T2 — holder of the transit procedure; often the same as consignor." },
        "buyer":              { "$ref": "#/$defs/CanonicalParty" },
        "seller":             { "$ref": "#/$defs/CanonicalParty" }
      }
    },

    "CanonicalParty": {
      "type": "object",
      "properties": {
        "eori":             { "type": ["string", "null"] },
        "vat_number":       { "type": ["string", "null"] },
        "name":             { "type": ["string", "null"] },
        "street_and_number":{ "type": ["string", "null"] },
        "postcode":         { "type": ["string", "null"] },
        "city":             { "type": ["string", "null"] },
        "country":          { "type": ["string", "null"], "description": "ISO 3166-1 alpha-2 country code." },
        "contact_name":     { "type": ["string", "null"] },
        "contact_phone":    { "type": ["string", "null"] },
        "contact_email":    { "type": ["string", "null"] }
      }
    },

    "CanonicalShipment": {
      "type": "object",
      "properties": {
        "invoice_number":       { "type": ["string", "null"] },
        "invoice_date":         { "type": ["string", "null"], "description": "ISO 8601 date string, e.g. 2025-03-15." },
        "currency":             { "type": ["string", "null"], "description": "ISO 4217 currency code, e.g. EUR." },
        "total_invoice_amount": { "type": ["number", "null"] },
        "exchange_rate_to_eur": { "type": ["number", "null"] },
        "incoterm":             { "type": ["string", "null"], "description": "Incoterm code, e.g. DAP." },
        "incoterm_location":    { "type": ["string", "null"] }
      }
    },

    "CanonicalTransport": {
      "type": "object",
      "properties": {
        "mode_at_border":              { "type": ["integer", "null"], "description": "EU transport mode code at border crossing." },
        "border_means_id":             { "type": ["string", "null"], "description": "Registration number / ID of the means at border." },
        "border_means_nationality":    { "type": ["string", "null"], "description": "ISO 3166-1 alpha-2 country of registration." },
        "inland_means_id":             { "type": ["string", "null"] },
        "inland_means_nationality":    { "type": ["string", "null"] },
        "departure_means_id":          { "type": ["string", "null"], "description": "Vehicle plate used for T2 departure transport means." },
        "departure_means_nationality": { "type": ["string", "null"] },
        "departure_means_mode_code":   { "type": ["integer", "null"] },
        "departure_means_type_code":   { "type": ["string", "null"] },
        "route": {
          "type": ["array", "null"],
          "items": { "type": "string" },
          "description": "Ordered list of ISO 3166-1 alpha-2 transit country codes."
        }
      }
    },

    "CanonicalOffices": {
      "type": "object",
      "properties": {
        "departure":   { "type": ["string", "null"], "description": "Office of departure (T1/T2)." },
        "export":      { "type": ["string", "null"], "description": "Customs office of export (EX)." },
        "exit":        { "type": ["string", "null"], "description": "Office of exit." },
        "import":      { "type": ["string", "null"], "description": "Office of import (IM)." },
        "destination": { "type": ["string", "null"], "description": "Office of destination (T1/T2)." },
        "transit":     { "type": ["string", "null"], "description": "Office of transit (T1/T2 en-route)." }
      }
    },

    "CanonicalLocationOfGoods": {
      "type": "object",
      "properties": {
        "type_of_location":           { "type": ["string", "null"] },
        "qualifier_of_identification": { "type": ["string", "null"] },
        "un_locode":                  { "type": ["string", "null"] },
        "authorisation_number":       { "type": ["string", "null"] }
      }
    },

    "CanonicalLoadingLocation": {
      "type": "object",
      "properties": {
        "loading_place":                { "type": ["string", "null"] },
        "loading_place_code":           { "type": ["string", "null"] },
        "loading_place_additional_code":{ "type": ["string", "null"] }
      }
    },

    "CanonicalTotals": {
      "type": "object",
      "properties": {
        "gross_mass":     { "type": ["number", "null"] },
        "net_mass":       { "type": ["number", "null"] },
        "packages":       { "type": ["integer", "null"] },
        "invoice_amount": { "type": ["number", "null"] }
      }
    },

    "CanonicalDocument": {
      "type": "object",
      "properties": {
        "sequence_number": { "type": ["integer", "null"] },
        "type":            { "type": ["string", "null"] },
        "reference":       { "type": ["string", "null"] },
        "date":            { "type": ["string", "null"] }
      }
    },

    "CanonicalAuthorisation": {
      "type": "object",
      "properties": {
        "type":      { "type": ["string", "null"] },
        "reference": { "type": ["string", "null"] }
      }
    },

    "CanonicalGuarantee": {
      "type": "object",
      "required": ["sequence_number"],
      "properties": {
        "sequence_number":  { "type": "integer" },
        "type":             { "type": ["string", "null"] },
        "grn":              { "type": ["string", "null"], "description": "Guarantee Reference Number." },
        "access_code":      { "type": ["string", "null"] },
        "amount":           { "type": ["number", "null"] },
        "currency":         { "type": ["string", "null"] },
        "pot_customs_debt": { "type": ["string", "null"] }
      }
    },

    "CanonicalHouseConsignment": {
      "type": "object",
      "required": ["sequence_number"],
      "description": "One consignment within a T2 groupage. Sequence numbers are Navision/Qargo internal IDs — not necessarily sequential from 1.",
      "properties": {
        "sequence_number":      { "type": "integer", "description": "Navision/Qargo shipment line ID. Preserved as-is." },
        "gross_mass":           { "type": ["number", "null"] },
        "reference_number_ucr": { "type": ["string", "null"] },
        "consignee":            { "$ref": "#/$defs/CanonicalParty" }
      }
    },

    "CanonicalGoodsItem": {
      "type": "object",
      "required": ["sequence_number"],
      "properties": {
        "sequence_number":              { "type": "integer" },
        "declaration_goods_item_number":{ "type": ["integer", "null"] },
        "description":                  { "type": ["string", "null"] },
        "commodity_code":               { "type": ["string", "null"], "description": "Combined nomenclature code (8 or 10 digits)." },
        "country_of_origin":            { "type": ["string", "null"], "description": "ISO 3166-1 alpha-2." },
        "gross_mass":                   { "type": ["number", "null"] },
        "net_mass":                     { "type": ["number", "null"] },
        "statistical_value":            { "type": ["number", "null"] },
        "house_consignment_sequence":   { "type": ["integer", "null"], "description": "Links to CanonicalHouseConsignment.sequence_number. Null for simple (non-groupage) declarations." },
        "packages": {
          "type": ["array", "null"],
          "items": { "$ref": "#/$defs/CanonicalPackage" }
        },
        "additional_references": {
          "type": ["array", "null"],
          "items": { "$ref": "#/$defs/CanonicalDocument" }
        },
        "previous_documents": {
          "type": ["array", "null"],
          "items": { "$ref": "#/$defs/CanonicalDocument" }
        },
        "supporting_documents": {
          "type": ["array", "null"],
          "items": { "$ref": "#/$defs/CanonicalDocument" }
        },
        "unit_price":             { "type": ["number", "null"] },
        "total_price":            { "type": ["number", "null"] },
        "extra_cost":             { "type": ["number", "null"] },
        "supplementary_unit":     { "type": ["string", "null"] },
        "supplementary_quantity": { "type": ["number", "null"] }
      }
    },

    "CanonicalPackage": {
      "type": "object",
      "properties": {
        "type":           { "type": ["string", "null"], "description": "Package type code (e.g. CT, BX, PK)." },
        "quantity":       { "type": ["integer", "null"] },
        "shipping_marks": { "type": ["string", "null"] }
      }
    }
  }
}