Additional properties for describing restrictions on number values

[ralfhandl]

Sometimes the data provided or accepted by an API ultimately resides in a (relational) database, and most databases have a NUMBER type that allows storing numbers with decimal mantissa. The potential values of a NUMBER column are restricted by

• precision: number of significant decimal digits
• scale: the place where the decimal point resides, counted from the right

This can of course be expressed with minimum, maximum, and multipleOf, e.g.

minimum: -9999999.999
maximum: 9999999.999
multipleOf: 1e-3

Yet it would be nicer to just say

precision: 10
scale: 3

This could also be used for DECFLOAT values:

precision: 34
# scale is variable

is a long DECFLOAT, the short one would have precision: 16

[mspiegel]

Request to amend the proposal such that the following formats are valid:

precision: variable
scale: variable

This corresponds to a true arbitrary precision number. This is also a plain old JSON "number" type according to the JSON specification. It is basically equivalent to the java.lang.BigDecimal type with the caveat that BigDecimal supports at most 2,147,483,647 digits to the right of the decimal point.

precision: variable
scale: 5

This corresponds to a FixedPoint number. The Scala Spire library has a FixedPoint type.

CC: @non he has a lot of experience working with weird number types.

[ralfhandl]

Would we want to explicitly state variable/unlimited precision or scale, or would this rather be expressed by not stating a finite precision or scale?

The latter would be in style with miminum, maximum, and multipleOf.

[mspiegel]

I'd like to have a special value ('variable', 'unlimited', not picky on the name) that can be used to explicitly document unlimited precision or scale. Do the fields 'precision' and 'scale' only apply when 'type' is number and 'format' is decimal? Do they also apply when 'type' is number and 'format' is unspecified? I think at one point I understood the difference between (number, decimal) and (number, not specified) but I can't recall now. What is the difference?

[ralfhandl]

Good questions! Similar to minimum etc. precision and scale should apply to type:number without requiring a specific format.

Given the issues mentioned in #704 they might also apply to type:string and imply that the string will contain a number.

The intention of format:decimal was to advise storing these numbers with a decimal mantissa to avoid rounding issues. This is similar to the OAS formats double and float which indicate numbers that are stored as binary floating-point numbers on the origin server.

[webron]

Tackling PR: #741

[ralfhandl]

We've opted for "vendor-specific" extension keywords x-sap-precision and x-sap-scale and published them under the Apache-2.0 licence, so everyone is free to use them 😉