Specify units of currency to be used for the AmountString field type

[mattyp]

Description

As referenced in issue #644, there is currently ambiguity as to the units of currency to be used for the AmountString type. This ambiguity is exposed within the Energy sector that frequently quotes amounts in fractional units (i.e. cents) rather than main units (i.e. dollars). As a result, some DHs are populating Energy sector payload values with main units (e.g. dollars) while others are populating with fractional units (e.g. cents).

While main units makes intuitive sense within the Banking sector and there are suggestions based on the field type of CurrencyString that perhaps all amounts are to be in main units of the currency being used, it is sufficiently ambiguous within a sector that frequently uses fractional units for there to be incongruence between implementations.

Intention and Value of Change

Explicitly specifying the units of currency as part of the standards will help with consistency and quality of data for a number of payloads within the Energy sector. This will subsequently ensure accuracy for data recipient producing consumer products who otherwise currently need to rely on heuristics to best-guess the units of currency in payloads.

Area Affected

The AmountString definition in https://consumerdatastandardsaustralia.github.io/standards/#common-field-types, is currently:

A string representing an amount of currency.

• A positive, zero or negative number
• Negative numbers identified with a ‘-‘
• Currency symbols MUST NOT be supplied
• At least 1 and up to a total of 16 significant digits before decimal point
• Minimum 2 digits following a decimal point (more digits allowable but only if required)
• No additional formatting, eg thousand separating commas

Within this definition there is no explicit reference to currency units to be used. There is no other explicit reference in the standards outside of the field type that I can find, either.

Change Proposed

There may be more appropriate places for the specification of unit of currency, but it logical and has some precedence with RateString to specify this as part of the type definition for AmountString. For example:

A string representing a monetary amount in main currency units with fractional units after a decimal point (e.g., if working with Australian dollars: "123.45" for one hundred twenty-three dollars and forty-five cents).
- A positive, zero or negative number
- Negative numbers identified with a ‘-‘ prefix
- Currency symbols MUST NOT be supplied
- At least 1 and up to a total of 16 significant digits before decimal point
- Minimum 2 digits following a decimal point (more digits allowable but only if required)
- No additional formatting, eg thousand separating commas

The two updates to the definition in this example are:

A string representing a monetary amount in main currency units with fractional units after a decimal point (e.g., if working with Australian dollars: "123.45" for one hundred twenty-three dollars and forty-five cents).

and

- Negative numbers identified with a ‘-‘ prefix

DSB Proposed Solution

The current DSB proposal for this issue is in https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/652#issuecomment-2297968195

[perlboy]

I think where we got to as a suggestion was to tweak this as:

A string representing a monetary amount with fractional units after a decimal point (e.g., if working with Australian dollars: "123.45" for one hundred twenty-three dollars and forty-five cents). - Negative numbers identified with a ‘-‘ prefix

Additionally add a clarifying statement to state where dollar values are mentioned they are assumed to be in AUD.

[mattyp]

Any particular reason for not including the clarifying "main currency units" or the negative value "prefix" in the proposal?

[perlboy]

Any particular reason for not including the clarifying "main currency units" or the negative value "prefix" in the proposal?

Mainly to work around potentially non AUD values questions (ie. should it be translated to AUD or not). Sorry negative is included in my alignment just wasn't discussed too much.

[mattyp]

Ahh, ok, because "main" could be construed as "AUD"? Currencies have a "main" portion (eg dollars, pound, sterling) and a "fractional" portion (eg cents, penny), and the original proposal was in this context.

Maybe we drop "main", eg "... a monetary amount in currency units..." just so it explicitly references units still.

[CDR-API-Stream]

Based on the discussion and feedback on this issue thus far, the DSB is proposing to update the description of AmountString to the following:

A string representing a monetary amount in currency units with fractional units after a decimal point (e.g., if working with Australian dollars: "123.45" represents one hundred twenty-three dollars and forty-five cents).
- A positive, zero or negative number
- Negative numbers identified with a ‘-‘ prefix
- Currency symbols MUST NOT be supplied
- At least 1 and up to a total of 16 significant digits before decimal point
- Minimum 2 digits following a decimal point (more digits allowable but only if required)
- No additional formatting, eg thousand separating commas
- Assumed to be in AUD unless specified otherwise

The three updates specifically are:

1. A string representing a monetary amount in currency units with fractional units after a decimal point (e.g., if working with Australian dollars: "123.45" for one hundred twenty-three dollars and forty-five cents).
2. Negative numbers identified with a ‘-‘ prefix
3. Assumed to be in AUD unless specified otherwise

The changes would be considered non-breaking.

Feedback on the proposed change is welcome.

[CDR-API-Stream]

The proposed change has been staged for review.

[nils-work]

Incorporated into Standards v1.32.0.