ISO 20022
#########

ISO 20022 is the standard that defines many XML messages for FinTech.  It is
very general, and often countries/orgs define subsets (TVS, technical
validation subset) of the schema.

Documentation for message fields can be viewed at https://www.iso20022.org/standardsrepository

The primary syntax for ISO 20022 messages is XML.  To avoid LibEuFin clients
having to deal with XML, we define a mapping from ISO 20022 messages into JSON.

The specifics of this mapping are:

 * The JSON should be "idiomatic" and easy to process
 * When possible, the highly nested structures of ISO 20022 should be flattened
 * It must be possible round-trip between the LibEuFin JSON and ISO 20022
   XML messages. The mapping of message types is not 1-to-1, as some ISO 20022 messages are
   very similar and can be mapped to the same JSON structure.
 * JSON-mapped messages are not explicitly versioned.  Instead, changes
   are made in a backwards-compatible way, possibly preserving old versions
   of message elements in the same schema.


Cash Management (camt)
======================

LibEuFin combines camt.052, camt.053 and camt.054, as they essentially
have the same structure and serve the same purpose:  Reporting transactions
on a customer's bank account.

We also flatten the hierarchy a bit and only have entries ("money movement in one go")
and transactions.

.. code-block:: typescript

   interface AccountTransactionItem {
     // LibEuFin-internal identifier for the transaction
     nexusTransactionId: string;

     // Link to the entry that contains the transaction
     nexusEntryId: string;

     // At least one of entryId or accountServicerRef
     // must be non-null
     entryId?: string;
     accountServicerRef?: string;

     creditDebitIndicator: "credit" | "debit";
     amount: string;
     currency: string;
     instructedAmountDetails?: {
       amount: string;
       currency: string;
       currencyExchange?: {
         sourceCurrency: string;
         targetCurrency: string;
         unitCurrency: string;
         exchangeRate: string;
         contractId: string;
         quotationDate: string;
       };
     };
     status: "booked" | "pending" | "info";
     valueDate?: string;
     bookingDate?: string;
     mandateId?: string;
     endToEndId?: string;
     messageId?: string;

     creditor?: Party
     creditorAgent?: FinancialInstitution;
     creditorAccount?: FinancialInstitution;

     debtor?: Party
     debtorAgent?: FinancialInstitution;
     debtorAccount?: FinancialInstitution;

     unstructuredRemittanceInformation?: string;
     bankTransactionCode: BankTransactionCode;
   }

   interface Party {
     name?: string;
     partyType: "private" | "organization";
     otherId?: {
       id: string;
       schemeName?: string;
       issuer?: string;
     };
   }

   interface Account {
     name?: string;
     currency?: string;
     otherId?: {
       id: string;
       schemeName?: string;
       issuer?: string;
     };
   }

   interface FinancialInstitution {
     type: "financial-institution";
     name?: string;
     bic?: string;
     otherId?: {
       id: string;
       schemeName?: string;
       issuer?: string;
     };
   }

   interface BankTransactionCode {
     domain?: string;
     family?: string;
     subfamily?: string;
     proprietaryIssuer?: string;
     proprietaryCode?: string;
   }