Description
OpenAPI 2.0 allows the same property name in different object schemas. For example, several models may validly contain name. Names should express the data’s meaning within each object rather than be unique across the entire API.
Potential impact
- Ambiguous names for different concepts can cause API consumers to misunderstand the data.
- Unnecessarily renaming an established property can break existing clients.
Remediation
Check each property’s name and meaning within its object. Do not rename it solely because another model uses the same name. Reuse common structures with $ref where appropriate, and plan client compatibility and migration when a real rename is needed.
Examples
The two body schemas below can each use name, address and age. The referenced Address definition is omitted.
Before
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"basePath": "/api",
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
},
"parameters": [
{
"name": "limit2",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
},
"age": {
"type": "integer",
"format": "int32"
}
}
}
}
]
}
}
},
"parameters": {
"limitParam": {
"name": "limit",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
},
"age": {
"type": "integer",
"format": "int32"
}
}
}
}
}
}
After
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"basePath": "/api",
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
},
"parameters": [
{
"name": "limit2",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
},
"age": {
"type": "integer",
"format": "int32"
}
}
}
}
]
}
}
},
"parameters": {
"limitParam": {
"name": "limit",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "object",
"properties": {
"name_2": {
"type": "string"
},
"address_2": {
"$ref": "#/definitions/Address"
},
"age_2": {
"type": "integer",
"format": "int32"
}
}
}
}
}
}
The second example appends _2 to properties in the reusable parameter. This is an optional API contract change, not a requirement to eliminate names repeated across models. Properties with the same meaning can retain their original names.