Description
The format field gives an integer or number schema a more specific representation. It is optional, so omitting it is not itself an error. Specifying it can reduce differences between implementations when an API needs a particular representation.
Potential impact
If clients and servers choose different numeric sizes or precision, values may be truncated or serialized differently.
Remediation
Where representation matters, specify an appropriate format, such as int32 or int64 for integer, or float or double for number. Check tool support and generated types. Define business limits separately with minimum and maximum.
Examples
This OpenAPI 3.0 excerpt adds the int32 representation while retaining the existing integer range of 0 through 50.
Before
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": 0,
"maximum": 50
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 50
}
}
}
}
}
}