Search code examples
openapijsonschemanumber-formatting

Format value for string typed large number in OpenAPI Specification


To represent large numbers in a JSON Schema with high precision, it is a common practice to represent them as a string type to avoid precision loss.

I am wondering if there is a typical format value to be used for this, like numeric-string for example.

properties:
 - pi_to_hundred_decimals:
     type: string
     format: numeric-string
     description: The value of pi to hundred decimal places.

Is this a common practice? Or the format should be only numeric or eventually something else?


Solution

  • The format keyword is strictly an annotation for the data type defined. There are some schema validators that use the format keyword to extend additional validation on the value but this is not standard JSON Schema behavior.

    You can make up any format value your heart desires but, unless you write a custom validation with your preferred validator, it doesn't really mean much to anyone else except you and your peers.

    If you're interested in following a pseudo standard, OpenAPI maintains a format registry where a number of format keywords are defined.