From e248817bfa27291c9104c7acd92e46f13fc6b52b Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 24 Jun 2020 18:08:25 +0530
Subject: docs

---
 libeufin/api-nexus.rst |  3 --
 libeufin/iso20022.rst  | 84 ++++++++++++++++++++++++++++++++++++++------------
 2 files changed, 65 insertions(+), 22 deletions(-)

(limited to 'libeufin')

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index d63fbd0b..9c752de1 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -327,9 +327,6 @@ to the real bank.
 
    Make a passphrase-encrypted backup of this connection.
 
-..
-  not implemented.
-
 .. http:post:: {nexusBase}/bank-connections/{connid}/accounts/fetch
 
    Update accounts that are accessible via this bank connection.
diff --git a/libeufin/iso20022.rst b/libeufin/iso20022.rst
index bc9f5901..304bd0d8 100644
--- a/libeufin/iso20022.rst
+++ b/libeufin/iso20022.rst
@@ -7,35 +7,81 @@ 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)
 ======================
 
-camt.052: Bank to Customer Account Report
------------------------------------------
+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.
+
+.. code-block:: typescript
+
+   interface CashManagementResponseMessage {
+     // ISO: MessageIdentification
+     messageId: string;
+
+     messageType: "report" | "statement" | "notification";
+
+     // ISO: CreationDateTime
+     creationDateTime: string;
+
+     entries: Entry[];
+
+   }
+
+   interface Entry {
+     transactions: Transaction[];
+   }
+
+   interface Transaction {
+     creditDebitIndicator: "credit" | "debit";
+     amount: string;
+     currency: string;
+
+     bookingDate?: string;
+     valueDate?: string;
 
-* pending and booked transaction
+     accountServicerRef?: string;
 
-Schema versions:
+     bankTransactionCode: BankTransactionCode;
 
-* GLS uses camt.052.001.02
+     details: TransactionDetails[];
+   }
 
-.. code-block:: none
+   interface TransactionDetails {
+     creditDebitIndicator: "credit" | "debit";
+     amount: string;
+     currency: string;
 
-  + Document/BkToCstmrAcctRpt
-  ++ GroupHeader [1..1]
-  ++ Report [1..*]
-  +++ Account [1..1]
-  +++ Balance [1..*]
-  +++ Entry [1..*]
-  ++++ Amount [1..1]
-  ++++ Status [1..1]
-  ++++ EntryDetails [1..1]
+     // Referenced message ID
+     messageId: string;
 
+     endToEndId: string;
+     paymentIdentificationId?: string;
 
-camt.053: Bank to Customer Statement
-------------------------------------
+     bankTransactionCode: BankTransactionCode;
+   }
 
-* only booked transactions
-* only for the last day (?)
+   interface BankTransactionCode {
+     domain?: string;
+     family?: string;
+     subfamily?: string;
+     proprietaryIssuer?: string;
+     proprietaryCode?: string;
+   }
 
-- 
cgit v1.2.3