Currency amounts are a common use case for APIs.
In a typical JSON implementation, you often see something like:
{"amount": 5.00, "currencyId": "USD"}
^ This is incorrect, since most parsers will treat the number amount as a floating point value, leading to rounding errors when performing financial calculations. It's also not particularly compact.
A slightly better alternative is:
{"amount": "5.00", "currencyId": "USD"}
This assumes that the receiving end knows enough to convert the amount field to a BigDecimal-equivalent type.
It's also fairly common to see:
{"amount": 500, "currencyId": "USD"}
This assumes that the receiving end knows that the value is expressed in pennies. This also makes it difficult to express sub-penny amounts.
To express this correctly, it would be extremely useful to have a currency type that combines an arbitrary precision decimal with a currency code. Alternatively, just decimal support would be sufficient. In the Java model, this is expressed as an "arbitrary precision integer unscaled value and a 32-bit integer scale".
Using the numeric currency codes described in the spec would be more compact, although not as human readable without an up-to-date mapping table: https://en.wikipedia.org/wiki/ISO_4217
I'd be happy to take a crack at adding this to the spec if there's interest.
Currency amounts are a common use case for APIs.
In a typical JSON implementation, you often see something like:
{"amount": 5.00, "currencyId": "USD"}^ This is incorrect, since most parsers will treat the number amount as a floating point value, leading to rounding errors when performing financial calculations. It's also not particularly compact.
A slightly better alternative is:
{"amount": "5.00", "currencyId": "USD"}This assumes that the receiving end knows enough to convert the amount field to a BigDecimal-equivalent type.
It's also fairly common to see:
{"amount": 500, "currencyId": "USD"}This assumes that the receiving end knows that the value is expressed in pennies. This also makes it difficult to express sub-penny amounts.
To express this correctly, it would be extremely useful to have a currency type that combines an arbitrary precision decimal with a currency code. Alternatively, just decimal support would be sufficient. In the Java model, this is expressed as an "arbitrary precision integer unscaled value and a 32-bit integer scale".
Using the numeric currency codes described in the spec would be more compact, although not as human readable without an up-to-date mapping table: https://en.wikipedia.org/wiki/ISO_4217
I'd be happy to take a crack at adding this to the spec if there's interest.