Enhancements to Banking documentation

[nils-work]

The Banking Candidate Standards included a number of minor documentation enhancements that can be incorporated into the main Standards without changing meaning. Aligning these changes would improve the binding Standards and make any comparison between the two versions more straightforward.

For example, the current statements:

• Values can be OPEN, CLOSED or ALL. If absent then ALL is assumed
• True if extended information is available using the transaction detail end point. False if extended data is not available

would become:

• Values can be OPEN, CLOSED or ALL. If absent then ALL is assumed
• true if extended information is available using the transaction detail endpoint. false if extended data is not available

[perlboy]

I question whether the description should have this sort of info in it. Does a boolean need an explanation? For the "if absent" parts it could be just as well served with the openapi default field as this is the implied value if the server does not receive a value from the client.

[nils-work]

That's a good point @perlboy. Most Booleans do have simpler descriptions than that one though, and some have additional qualifying text for a default. We could consider simplifying as we go through, but would need to be more careful with any rewording to ensure the interpretation doesn't change and further guidance on specific fields is not needed.

Do you think changing this description for the isDetailAvailable Boolean:

True if extended information is available using the transaction detail end point. False if extended data is not available

to this, would be an improvement?:

Whether extended information is available using the transaction detail endpoint

Many Banking fields do have a default specified, but those values are not currently rendered to the documentation. Do you think displaying them in a consistent way would be valuable? There is a handful of fields missing a default where it could be specified, and others describe a more complex default that may need to be considered, like:

If absent defaults to newest-time minus 90 days.

[nils-work]

The changes incorporated with this issue include:

• styling changes in descriptions:
  • italic where referring to field names
  • code where referring to field values
• minor punctuation corrections and additions throughout as noted in Maintenance Issue #527
  • removed double spaces
  • added full-stops to sentences
  • changed 'end point' to 'endpoint'
• minor formatting changes to improve readability
  • added links to enum detail
  • examples updated to use more common values (VARIABLE instead of BONUS, FIXED instead of BUNDLE_DISCOUNT_FIXED)
  • updates in descriptions including changing 'bonus' to BONUS and 'True' to true to show correct value form
• alignment in formatting across the Banking API specification files:
  • Banking APIs (Binding)
  • Banking APIs (DP306 Candidate)
  • Banking APIs (Non-Bank Lending Candidate

Also note:

• No changes have been made to specify default values as suggested, but these can be reviewed in future.
• A number of minor typos will be addressed separately.
• No change in the meaning of the Standards is intended.