Category: Semantic Analysis
Description
APIs should use consistent naming for the same concepts across endpoints. This rule detects when similar concepts use different names (e.g., user_id vs userId vs userIdentifier).
What It Checks
This rule analyzes naming across the entire API:
- Parameter names across all operations
- Request body field names
- Response field names from 2XX responses
- Groups names by normalized form (removing case and separators)
- Uses AI to determine if different spellings represent the same concept
Why It Matters
Consistent naming improves:
- Developer Experience: Predictable naming reduces cognitive load
- Code Quality: Consistent client code without special cases
- Maintainability: Easier to understand and modify the API
- Documentation: Clear, consistent terminology
Examples
Good
paths:
/users:
get:
parameters:
- name: user_id
in: query
responses:
'200':
content:
application/json:
schema:
properties:
user_id:
type: string
/orders:
get:
parameters:
- name: user_id # Consistent with above
in: query
Bad
paths:
/users:
get:
parameters:
- name: user_id
in: query
responses:
'200':
content:
application/json:
schema:
properties:
userId: # Inconsistent: user_id vs userId
type: string
/orders:
get:
parameters:
- name: userIdentifier # Inconsistent: another variation
in: query
Exceptions
- Intentionally different concepts that happen to normalize similarly
- Legacy endpoints that cannot be changed
- External API integrations with different conventions
Configuration
This rule has no configuration options. It is either enabled or disabled.
Related Rules
- Rule 75: Consistent Naming Conventions - Naming pattern enforcement
- Rule 80: Schema Field Naming - Field name quality