13

I can't find a sample of currency data type in the object definition, nor a document on the subject.

Helen
  • 87,344
  • 17
  • 243
  • 314
vic
  • 2,548
  • 9
  • 44
  • 74

2 Answers2

13

There is no built-in "currency" type. You would typically use type: number with an optional format modifier to indicate the meaning of the numeric type:

type: number
format: currency

format can have arbitrary values, so you can use format: currency or format: decimal or whatever your tool supports. Tools that recognize the given format will map the value to the corresponding type.

Helen
  • 87,344
  • 17
  • 243
  • 314
  • 1
    Well. 'type: string' would avoid problem with generated code out of this spec. This is why a lot of APIs expect strings for prices and money.. – aholbreich Sep 14 '20 at 16:03
  • 2
    Acceptable values for format field are not well defined. You can use any string.A registry of common formats is in progress and "decimal" is the best-fit field proposed for addition to that registry today. https://github.com/OAI/OpenAPI-Specification/issues/845#issuecomment-378139730 – Marques Johansson Apr 28 '21 at 14:32
  • according to https://swagger.io/docs/specification/data-models/data-types/ nor decimal nor currency is accepted. – Simon Logic Mar 05 '22 at 15:04
-5

The type in the OpenAPI 2.0 standard closest to typical decimal dollar values seems to be type number, format float, which is a 32-bit floating point format (see other online discussions such as here)

Pavel Dvorak
  • 7
  • 5
  • 8
    Using floats for currency is very dangerous. If you do any maths on it, you'll end up with prices like $43.00000000000000000001 when you're expecting $43.0 – NickG Mar 21 '18 at 13:31
  • The float format is suitable is ONLY on the API level (note this is a question about "Swagger") where again no better fractional format appears to be standardized (see the link to OpenAPI types again). Of course you have to be careful and check your math ops in the application, where the language hopefully supports something like decimal or outright currency. – Pavel Dvorak Apr 25 '18 at 23:41
  • 3
    I don't think float is suitable at the API level if you know you're handling decimal values. Specifying float is likely to result in consumers of the API accidentally using floating point values, which are known to not map accurately to decimal values. It would be better to use a different format, such as one of the ones suggested by Helen. – Rich Dougherty Oct 03 '18 at 00:21
  • 1
    Yes, except - again - the "decimal" or currency format is not supported by the standard and I certainly worked with Swagger tool(s) that checked and didn't allow such definition. That was a much more real constraint than [theoretical] risks with deserialisation. And how else would you "know you are handling decimal values" from the API definition. from property name? Anyway. – Pavel Dvorak Oct 04 '18 at 01:21