ConsumerDataStandardsAustralia / standards-maintenance

This repository houses the interactions, consultations and work management to support the maintenance of baselined components of the Consumer Data Right API Standards and Information Security profile.
41 stars 9 forks source link

APCA Number is specified as String but is a Number #30

Closed perlboy closed 4 years ago

perlboy commented 5 years ago

Description

The APCA Number in the standards is specified as a string but is described (and actually is) a zero padded 6 digit number.

Area Affected

Transaction and TransactionDetail

Change Proposed

a) Create a string field format for APCA numbers similar to MaskedPANString b) Change to a PositiveInteger on the basis of maintaining a consistent approach to zero padded values as previously communicated for thoroughfareNumber1 and thoroughfareNumber2

james-callahan commented 5 years ago

A zero padded 6 digit "number" essentially is a string; I would put it into the same classification as telephone numbers.

perlboy commented 5 years ago

A zero padded 6 digit "number" essentially is a string; I would put it into the same classification as telephone numbers.

I would agree but previous communication on zero padded numbers related in that case to PAF fields was as follows: "The PAF is a fixed field length structure so padding is always required. The CDR standard has no such requirement so a positiveInteger is considered a valid type for these fields"

The handling for zero padded number is inconsistent.

CDR-API-Stream commented 5 years ago

The reference to PAF fields was related to thoroughfareNumber1, thoroughfareNumber2 and postalDeliveryNumber. Leading zeroes are not significant for these fields.

Leading zeroes are significant for numbers that are IDs such as BSB, Account Number, APCA Number, Swift Codes, etc. This is especially true where these fields are externally defined so the possibility always exists that they become alpha numeric in the future.

perlboy commented 5 years ago

The reference to PAF fields was related to thoroughfareNumber1, thoroughfareNumber2 and postalDeliveryNumber. Leading zeroes are not significant for these fields. Leading zeroes are significant for numbers that are IDs such as BSB, Account Number, APCA Number, Swift Codes, etc.

I would suggest leading zeroes are always significant which is why the first option for change implied the introduction of a type similar to MaskedPANString so that it's format could be suitably identified during interpolation. Specifically on the PAF example the specified value for "not used" is explicitly 00000.

This is especially true where these fields are externally defined so the possibility always exists that they become alpha numeric in the future.

PAF is an externally defined format also so this possibility applies.

CDR-API-Stream commented 5 years ago

Leading zeroes are not always significant, especially in fixed width file formats. In JSON an absence of value is accommodated by the field being absent instead of a padded zero value.

If the concern here is related to understanding the detailed format of the fields then that is a different discussion. In general in the CDR standards the common types have been used to define detailed formats that are fully in the scope of the standards to define. MaskedPANString is an example of this.

Values, especially IDs, defined by other standards are generally accommodated by the use of the ExternalRef type. This was not used for the PAF related fields because the external standard is not being strictly used (as it is a fixed width based standard).

Based on that it would be reasonable to modify the APCA field to use the ExternalRef type. Also, the use of PostiveInteger for the PAF number fields would also be reasonable.

Would this address the concern being raised?

perlboy commented 4 years ago

As someone involved in how ExternalRef came into existence this was as a workaround for what were previously completely undefined types of string. At the time proposals to introduce specific types where appropriate was opposed and therefore ExternalRef was "better than nothing". Following formalisation of the Standards and consequential implementation into infrastructure, particularly SQL Databases, it seems appropriate to review.

Based on the current Swagger specification, ExternalRef is used 18 times. These are broken downs as follows:

I would suggest that all ExternalRef fields should be considered for x-cds-type creation, particularly those which are likely to be used multiple times. This would include essentially all of the above and APCA numbers.

Doing so results in minimal impact to those using standard Swagger tools (it is ignored) while providing clear structure to those developing solutions designed to validate them.

While this thread is about APCA number, the ISO8601 durations in particular is something I don't believe the Data61 Conformance Suite currently verifies (because it can't based on ExternalRef without manual intervention) and which some Holder's products are currently non-compliant to (CBA's Term Deposits from memory).

CDR-API-Stream commented 4 years ago

The proposed change for this issue is unlikely to be actioned but the suggestion above may warrant independent consultation and review in the next maintenance iteration. If this is desired it would be welcome if it was raised as a separate change request.

CDR-API-Stream commented 4 years ago

Hi @perlboy, regarding the APCA Number CR specifically, we have reviewed the proposal and the preference is to keep the field unchanged. There is no publicly available external reference to an APCA ID format, so an ExternalRef cannot be supported. Treating the type as a Number would not be correct in this instance because the field is actually a fixed-width zero-padded string. This will be clarified in the documentation.

perlboy commented 4 years ago

@CDR-API-Stream Firstly, there is a publicly available specification available from APCA:

image

I don't disagree with the statement that this is a zero-padded string, in fact it is a zero padded 5 character string with a fixed prefix of 0. With this said however, this request came about because of previous statements made by @CDR-API-Stream regarding other zero padded strings (those from PAF): "The PAF is a fixed field length structure so padding is always required. The CDR standard has no such requirement so a positiveInteger is considered a valid type for these fields"

Essentially, what I'm requesting is consistent handling of zero padded numbers across the standards. Either

In direct response to to the PAF side of things there is an explicit statement that a value of 00000 means "unused" which is important for the validation rule that thoroughfareNumber1 must be less than thoroughfareNumber2 UNLESS it isn't used (ie. "00025/00000" for "Thoroughfare 25" vs. "00021/00022" for thoroughfare 21-22 vs. an invalid value of "00021/00001" or "00021/____0 where is a space).

perlboy commented 4 years ago

Preamble: Biza currently has 42 open issues within Standards Maintenance. In an effort to optimise our own backlog we are closing those which have no actual response from the DSB. They may be reopened at a later time or referenced when the issues are highlighted by third parties.

Despite having a "preference" to leave the APCA Field unchanged, in 1.3.0 APCA Number references were modified with the following additional sentence: "The field is fixed-width and padded with leading zeros if applicable".

Beyond this change the DSB appears committed to interpreting what is a number or string on a case by case basis with PAF DPID being a String in CDR but the source document being a number, while thoroughfareNumber1/2 are aligned with number's. There does not appear to be additional value to be gained from continuing to attempt to highlight this inconsistency but the line from the PAF file format highlighting how they are specifically stated as numbers only (5 or 9 numbers in length) versus the Standards which split them between string/number is supplied below:

image

image

This change will result in the need to perform type conversion between Integer and String's when using a certified Auspost PAF parser. Consequently, Babelfish includes utility functions to convert thoroughfare's and delivery point identifiers to/from string/integers.