Pay: limit Payment Means Keys and extend instructions

[samlown]

Hey All! Another ask for a take on your opinions. I've been thinking about the "payment mean keys" after the recent extensions proposal (#184). I'm wondering if it would make more sense now to apply the same technique to payment methods.

My theory is that GOBL adds most value for sharing when the keys used are those defined in the base standard. Value diminishes quickly when extended keys are used (like the Italian direct-debit+sepa, which translates to MP19), as they require a look up to understand. This is the case for example in Italy and Mexico which define their own list of for region specific methods in addition to the base.

My proposal would be to only allow the base Payment Means Keys to be used, and add an ext property to the Payment Instructions so that when other is selected (or potentially any of the other keys) an ext can be provided with something like:

"instructions": {
  "key": "direct-debit",
  "ext": {
    "it-sdi-payment-means": "MP19"
  }
}

This issue here of course is that the chosen payment means keys could potentially conflict with the main instruction key. The current Key Definitions don't yet support additional conditions or context.

There is also the additional concern of how best to present the list of available options in a UI. By using two values, the instruction key and extension code, selecting the appropriate combination is less obvious.

What do you think?

[cavalle]

Tough design choices! My two cents:

I don't have a super-strong opinion, but, if I were a developer building GOBL documents in my code, I think I would rather use only keys (as it happens today) or only ext to specify codes like it-sdi-payment-means. My code would be simpler than if I had to use one or both depending on the case (i.e. I'd need to add more conditions, or a more complex mapping table, to my code).

As for reading generated GOBL documents (which is another consideration that affects DevEx), I'm really not sure whether I would prefer the meaningfulness of using keys, or the explicitness of using ext codes. I suppose that having meaningful keys for the most common/standard cases and ext codes for the rare cases is a middle ground that will make it closer to GOBL documents in other countries.

Regarding possible conflicts between the key and the ext code, I think it could be the responsibility of each regime to validate that only valid combinations are allowed.

Finally, on how to translate this into a user interface, don't you think this will depend very much on the particular business domain of each customer? In many cases there will be no UI at all to select the value, as it will be the consequence of a business rule. And even if there is a need to present the user with an interface, they'll probably only need to choose from a small list of available options, which can then be transformed into whatever GOBL requires. In summary, I don't expect 1:1 mappings between the forms and fields of our client's UI's and GOBL. This will only happen if we (or someone else!) ever build a WYSIWYG GOBL editor or something like that.

[samlown]

I don't have a super-strong opinion, but, if I were a developer building GOBL documents in my code, I think I would rather use only keys (as it happens today) or only ext to specify codes like it-sdi-payment-means.

I think that's key. So in theory for the majority of cases with this proposal, you should be able to just use the standard GOBL key, and only break out into the very specific local extension code if needed. The developer experience would be "here are the main payment means keys... but wait! we need to be able to deal with this specific local method too... how do I do that? okay, with an extension code".

I'll continue to think about this, but it might be that the current solution with the invented local key extensions is best.

[cavalle]

I think that's key. So in theory for the majority of cases with this proposal, you should be able to just use the standard GOBL key, and only break out into the very specific local extension code if needed. The developer experience would be "here are the main payment means keys... but wait! we need to be able to deal with this specific local method too... how do I do that? okay, with an extension code".

Right, and my point in the paragraph you quoted is that if you need issue invoices with codes covered by the standard keys and invoices with codes that require the use of extensions keys, then you need to add conditionals to your code (or a more complex mapping table) than if you would simply would always use keys (standard and non-standard) or always use the extension code.