Missing essential documentation for Transaction fields.

[denisld]

There appears to be no documentation of the members in the Transaction object. The lack of documentation, in combination with obscure/unfortunate naming of the fields makes the module difficult and error-prone to use.

Specific problematic fields are:

• The 'date', 'entry_date', 'guessed_entry_date' fields: my best guess is that 'date' is the value date and 'entry_date' is the transaction date. I would not bet any money on either guess. The meaning and purpose of 'guessed_entry_date' eludes me entirely.
• The 'id' field contains a sub-field from Tag :61: which, in the documentation from most banks I've seen, should contain the Transaction Code. 'id' seems like a misnomer for this field. If it can't be changed without breaking compatibility, at least document it properly, please.

[wolph]

The unfortunate naming is mostly copied from the banks' MT940 definition files and other MT940 definition standards documentation. And that is the problem as well, the MT940 standard is not well defined, some parts are defined as a standard but most banks have their own interpretation of the standard and what to put in specific fields.

In general my advise would be to read the documentation of the bank who's MT940 file you are reading because the entry_date that one bank uses can be inconsistent with what another bank calls the entry_date. The entry_date and value_date field names themselves appear to be standard, there meaning however, do not.

This is also why the guessed_entry_date exists, there are cases where the entry_date combined with the entry_day and entry_month cross over to a new year or the previous year. In those cases we need to add or remove a year from the actual entry_date. That is why the guessed_entry_date exists, it uses some heuristics to automatically determine the real entry_date. But since it's based on heuristics and is not a fixed standard between multiple banks, I have added the guessed prefix.

The same goes for the id field. When I initially created the library I was expecting that the standard was well defined so I used the documentation from the first source I could find to define the tags and the names of the fields. After a little while this turned out to be a mistake but the first releases were already out in the wild and I really hate breaking backwards compatibility.

The source I used most initially was: https://www.sepaforcorporates.com/swift-for-corporates/account-statement-mt940-file-format-overview/

[wolph]

I've added some additional documentation that might help, but the entire standard is honestly a huge mess... every bank has its own opinion about the fields: https://mt940.readthedocs.io/en/latest/mt940.tags.html#mt940.tags.Statement