international money amount and currency

[pvdbosch]

Support international money amounts by defining:

• a Currency type
• a type for the numerical money amount

To determine final naming of the types, an issue in fedvoc repo will be created.

For Currency, base on https://en.wikipedia.org/wiki/ISO_4217#Active_codes

Currency:
  type: string
  pattern: ^[A-Z]{3}$
  example: EUR

For amount:

• representation of decimals => see representation of decimal numbers rest-guide#79
• money amount can, according to the ISO codes, have 0 up to 4 decimal digits. Expressing the amount as integers is tricky then because you need to know where to place the comma
• EuroCentAmount can still be kept for use cases (APIs) where the currency is always Euro
• It is common that negative amounts are not allowed for a use case. We could, similarly to EuroCentPositiveAmount, create an additional type that only allows for positive amounts.

We could create an additional Money type to combine Currency and MoneyAmount in a composite type (also PositiveMoney then?)

For comparison: Zalando Money type.

[pvdbosch]

current draft for international money types, based on updated FedVoc draft in belgif/fedvoc#17

    Currency: # do we add Code suffix?
      description: A currency represented by its ISO 4217 alpha code
      type: string
      pattern: "^[A-Z]{3}$"
      example: "EUR"
    MonetaryAmount:
      description: A monetary value
      type: object
      properties:
        value:
          "$ref": "#/components/schemas/Decimal"
        currency:
          "$ref": "#/components/schemas/Currency"
      required: [value, currency]
      example:
        value: "0.01"
        currency: "EUR"

discussion on Decimal type is continued in belgif/rest-guide#79

[pvdbosch]

approved by REST functional WG, still to be approved by technical WG; MonetaryAmount only after solution for Decimal type

[pvdbosch]

types were updated after REST design WG discussion in belgif/rest-guide#79

Can be re-validated by both functional and technical WGs.

[pvdbosch]

validated by functional WG

[pvdbosch]

openapi-money 1.0.1 has been released with the types graduated to stable status.