Description
Misspelled fixed properties or properties placed in the wrong OpenAPI 3.0 object may be ignored or cause document rejection. Distinguish these from x- extensions where allowed and user-defined data field names in schemas.
Potential impact
Descriptions or contract information may disappear from documentation, or client generation and validation may fail.
Remediation
Check spelling, case and placement against the object definition for the OpenAPI version in use. Add extensions with x- names only where allowed and check consumer support. Do not rename actual data fields by mistaking them for fixed documentation properties.
Examples
These excerpts compare the spelling of description in a response and a tag. The referenced exampleSecurity scheme definition is omitted here.
Before
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"descrinnption": "200 response"
}
}
}
}
},
"security": [
{
"exampleSecurity": []
}
],
"tags": [
{
"name": "pets",
"desdddcription": "Everything about your Pets",
"externalDocs": {
"url": "http://docs.my-api.com/pet-operations.htm"
}
},
{
"name": "store",
"description": "Access to Petstore orders",
"externalDocs": {
"url": "http://docs.my-api.com/store-orders.htm"
}
}
]
}
After
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
}
}
}
},
"security": [
{
"exampleSecurity": []
}
],
"tags": [
{
"name": "pets",
"description": "Everything about your Pets",
"externalDocs": {
"url": "http://docs.my-api.com/pet-operations.htm"
}
},
{
"name": "store",
"description": "Access to Petstore orders",
"externalDocs": {
"url": "http://docs.my-api.com/store-orders.htm"
}
}
]
}
The revision changes descrinnption and desdddcription to description. It does not change the structure of the data returned by the API.