representation of decimal numbers

[pvdbosch]

How to represent decimal numbers with fixed precision: as number or as string type?

For use in MonetaryAmount, see belgif/openapi-money#2

For decimals with fixed precision:

• floating point numbers aren't advisable for money, because of calculation errors
• in the wild, we encounter "type: number with format: decimal" (Zalando) and "type: string with format: number" (openapi-generator) for precise decimal numbers (BigDecimal etc.)
  • There's some talk about this in JSON Schema list: better support for decimals encoded as strings json-schema-org/json-schema-vocabularies#45
• limiting min/max is difficult when reusing an existing (string) type. Do we provide two types: allowing pos+neg and allowing only non-negative?

So two options:

A) use number type with format, not in openapi-common

MoneyAmount:
  type: number
  format: decimal 

=> might be converted to float by default which is dangerous (can someone test?)

variant: add "multipleOf: 0.0001" to express precision. But this can also lead to other floating point problems for libraries implementing this (json-schema-org/json-schema-spec#312 , xeipuuv/gojsonschema#149).

B) define Decimal type based on string

  Decimal:
      type: string
      format: decimal # decimal is a custom format only supported in some tooling
      pattern: '^(\-|\+)?((\d+(\.\d*)?)|(\.\d+))$'  # based on BigDecimal (Java) but without exponent support. At least one digit required, before or after comma
      # valid values:  "100.234567", "010", "-.05", "+1", "10", "100." 
  UnsignedDecimal:
      type: string
      format: decimal # decimal is a custom format only supported in some tooling
      pattern: '^((\d+(\.\d*)?)|(\.\d+))$'  
      # valid values:  "100.234567", "010", "10", "100." but not "+1", "-1"

=> has to be converted in code from string to appropriate decimal type (e.g. BigDecimal in Java)

[pvdbosch]

The spec on number type: (JSON Schema refers to JSON RFC for this)

https://tools.ietf.org/html/rfc8259#section-6

• This specification allows implementations to set limits on the range and precision of numbers accepted.
• Since software that implements IEEE 754 binary64 (double precision) numbers is generally
  available and widely used, good interoperability can be achieved by implementations that expect no more precision or range than these provide
• number type supports scientific notations like 5e-2 (=0.0.5)

[pvdbosch]

update 13/1: add new results with newer swagger-codegen (the one in SwaggerHub), and tests with string type and format number

I did some tests with code generation:

• type: number (without format or with decimal format) gets converted to:
  • decimal in C#
  • BigDecimal in Java
  • number/Number in typescript/javascript (which is like a Java double)
• type: string, format: decimal gets converted to:
  • Java: BigDecimal using openapi-generator, String using swagger-codegen
  • typescript: string
  • couldn't test javascript (crashes)
• type: string, format: number gets converted to:
  • Java: BigDecimal using both openapi-generator and swagger-codegen
  • typescript: Decimal (import from 3rd party decimal lib)
  • couldn't test javascript (crashes)

[pvdbosch]

proposition:
document in REST guide, when precision is important, to use this:
type: string format: decimal
according to use case, a regexp pattern can be added to enforce digit pattern, number of digits before/after comma, ...

In openapi-money, for MonetaryAmount, use

      type: string
      format: decimal # decimal is a custom format only supported in some tooling
      pattern: '^(\-|\+)?((\d+(\.\d*)?)|(\.\d+))$'  # based on BigDecimal (Java) but without exponent support. At least one digit required, before or after comma
      # valid values:  "100.234567", "010", "-.05", "+1", "10", "100." 

I'll create a PR for validation next time.

[pvdbosch]

did some more tests with codegen tooling; updated the above comment with results.

Seems like type: string, format: number is better supported than decimal format so I'll go with that.

[pvdbosch]

PR ready for review: #90
The beta version of openapi-money can also be reviewed: https://github.com/belgif/openapi-money/blob/master/src/main/openapi/money/v1beta/money-v1beta.yaml

[pvdbosch]

pull request was review in WG of March, and merged

[pvdbosch]

For future reference this page also sums up this problem space quite well: https://github.com/zalando/jackson-datatype-money/blob/main/MONEY.md
We took the "quoted decimal" option for MonetaryAmount and "fixed point" for EurocentAmount, prioritizing to avoid loss of precision over other downsides.