Description
A standard numeric format should agree with the schema type: int32 and int64 describe integer values, while float and double describe number values. The format field is optional, and custom formats are allowed.
Potential impact
Conflicting types and formats, or formats unsupported by the tools in use, can produce unexpected SDK models, validation results, or serialization.
Remediation
Choose a type and standard format that describe the actual data. When a custom format is needed, verify that the code generator and validator handle it consistently.
Examples
This OpenAPI 3.0 excerpt changes the format of id to int64 for its integer type, and the format of percentage to float for its number type.
Before
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "double"
},
"percentage": {
"type": "number",
"format": "int32"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"percentage": {
"type": "number",
"format": "float"
}
}
}
}
}
}