Many numerical values are stored as strings

[oobayly]

Properties that contain number, such as GoCardless.Resources.TaxRate.Percentage or GoCardless.Resources.PayoutItem.Amount are presented as strings. This makes very little sense as they're numbers, and raises a few questions:

1. Can they be null or an empty string, or are they guaranteed to be parsed safely?
2. What locale do we parse them in?
3. Are we guaranteed that the decimal separator is always .,
4. Are we guaranteed that there will never be a decimal separator.

It seems a bizarre decision to make, especially as other properties are integers, eg. GoCardless.Resources.Payout.Amount, etc.

[IanKemp]

Yes, this package is extremely inconsistent in this regard. Another example of such an inconsistency is PaymentCreateRequest.ChargeDate, which is a string.

[jamiecobbett]

Thank you both for flagging these issues.

TaxRate.Percentage and PayoutItem.Amount are genuinely decimal values (fractions of a currency unit, or a percentage), not integer minor-units like Payout.Amount. Our schema doesn't currently specify that they are decimals in a machine readable way

Similarly, PaymentCreateRequest.ChargeDate is a string with format date. We could do a better job of parsing these into more useful, specific types in the library. I've added that to our feature request board internally.

@oobayly to answer your specific queries:

1. Null / empty string, guaranteed to parse safely? For a real, persisted resource, TaxRate.Percentage and the top-level PayoutItem.Amount will never be null or empty — they come from NOT NULL database columns. (Some nested fields, like a payout item's taxes[].amount, can genuinely be absent — but that's serialized as JSON null, never an empty string, so you won't get something you can't parse.)

2. What locale? None — formatting isn't locale-aware anywhere in this path. The value is a BigDecimal, serialized via its own to_s, with no I18n/locale formatting applied. The same string is returned regardless of Accept-Language or account locale.

3. Always . as the decimal separator? Yes — guaranteed.

4. Could there be no decimal separator at all? Yes, this can happen — BigDecimal#to_s trims trailing zeros, so a whole-number percentage could come back as "20" rather than "20.0". It'll never use scientific notation, but you shouldn't assume a fixed number of decimal places is always present.