Decision Proposal 013 - Primitive Data Types

[JamesMBligh]

This decision proposal outlines a recommendation for an initial list of primitive data types to be used when defining fields in JSON payloads..

Feedback is now open for this proposal. Feedback is planned to be closed on the 21st September. Decision Proposal 013 - Primitive Data Types.pdf

[da-banking]

We broadly accept the proposal, with 2 suggestions:

1. The term PCIString seems to be named a little indirectly. PCI standards are broad and evolving. It might be better to call it what it is, maybe MaskedCardNumber, or MaskedPAN.

2. We would ask for clarity on the intended use of the String and UnicodeString types. We would expect that all text fields that a human enters should be defined as UnicodeString, and not String. For example a transaction description, or an account nickname should all be UnicodeString. For coded fields, a String seems appropriate.

[bazzat]

The ABA Open Banking Technical Working Group is broadly supportive of the recommendation but we note the following:

Pedantic: "positive" is used in various contexts where "non-negative" is meant. The "inclusive of zero" is not always remembered where it is needed.

Strings and UnicodeStrings will need a max length before being used to describe fields. Document should described how this will be covered off. Perhaps by a naming convention, e.g. “Max40String means…”

UnicodeString - A comment about escaping characters and valid JSON would not go astray.

DateTimes etc may need to support time zones. For example specifying when an event would occur relative to Sydney time. Strictly speaking, dates in RFC-3339 represent instants in time and UTC might not make much sense in may contexts. It may be better to omit the time zone for e.g. the posting date of a transaction or to rename the existing proposed data types to e.g. UTCDateTime and add an additional datatype without timezones.

DateTimeString - there seem to be a lot of formats there to choose from. I think a few MUST and should statements here would help. E.g.: ASPSPs MUST represent datetimes in RFC-3339 format and MUST use UTC and SHOULD NOT include fractional seconds. E.g. 2012-12-25T15:43:00Z. TPPs MUST accept any RFC-3339 datetime that is in UTC time.

TimeString – It is likely that we will also need to represent non-UTC times. For example, representing that a banking event takes place 5pm Sydney time each weekday. Consider renaming this to UTCTimeString.

PCIString – We may have other masked fields and other PCI fields. A more future-proof name for this would be MaskedPANString.

RateString doesn't specify if it is a fractional or percentage interest rate.

Number doesn't specify how to write very small or very large numbers using e.g. scientific notation.

CurrencyString is a specific Enum - it could be argued that this is not primitive.

[TKCOBA]

COBA’s view is that the recommended primitive data type ‘PCIString’ should be renamed to ‘MaskedPAN’ – we note that similar comments have been made by other stakeholders. The proposal to expose last 4 digits only for this primitive data type is appropriate and consistent with best practice. However, controls should be put in place, if possible, to prevent an accidental full string (i.e. the maximum allowable under the PCI standard is first 6 digits and last 4 digits).

In relation to the recommended primitive data type ‘AmountString’, should this be limited to 2 digits after a decimal point, for simplicity? What is Data61’s rationale to extend this beyond 2 digits after the decimal point?

[NationalAustraliaBank]

NAB agrees with the proposal that

the payloads of the API end points should be strongly typed.

The initial set of primitive data types proposed will evolve, and as such should be versioned components too. Furthermore, every time these base components are used within the specification they should reference out to a versioned primitive data type. This will avoid inconsistent instance usages of the same base data types across the scheme.

These primitive data types then become reusable building blocks which can be iterated on in their own right, so long as they are versioned appropriately.

For example a 'PCIString' OR 'MaskedPAN' might be versioned independently of its usage within an API definition.

MaskedPAN v1 may have a certain regular expression MaskedPAN v2 may have a more constrained/refined regular expression. (a breaking change)

In general, we believe it would benefit the scheme to define the regular expressions for all of the primitive data types too.

[JamesMBligh]

My response to feedback prior to decision closure.

• I will change the name of PCIString to MaskedPANString (it is still a string and the aligns the type with the others).

• Versioning of primitive types is unlikely to be an issue. If it does arise we will cross that bridge when we come to it (although I suspect something along the lines of MaskedPANStringv2 as a new type is likely).

• Due to the system specific nature of regular expressions (they can be very implementation specific) I would prefer not to provide regular expressions in the formal standards. That doesn't preclude providers from sharing the appropriate regexs if they so desire.

• Thank you ABA for the pedantry. Specificity is always welcome. I will incorporate the suggested amendments where appropriate. I will note that the data and time strings already incorporate timezone as the RFC allows for a time offset in the specification of the time string (ie. the Z notation)

• COBA, the reason the amount string is not limited to 2 decimal places is that I have previously encountered some corner cases in financial services (especially for overseas currencies and some trading use cases) where the extra significant digits are required.

• The reason for separate string and UnicodeString is that the majority of banking providers and interbank protocols are specifically limited in string encoding. While JSON strings are always Unicode the underlying data that can be consistently delivered is not. This is obviously more important for end points that allow for write rather than read but it is still a real limitation across the industry.

-JB-

[JamesMBligh]

I have now closed consultation on this decision. A recommendation incorporating feedback will be made to the Chair in due course.

-JB-

[JamesMBligh]

The finalised decision for this topic has been endorsed. Please refer to the attached document. Decision 013 - Primitive Data Types.pdf

-JB-