Consistent Naming Conventions

Category: Naming & Style

Description

Enforces consistent naming patterns across all API components, including component structure names, URI parameters, and JSON schema properties.

What It Checks

This rule validates that naming conventions are applied consistently throughout your OpenAPI specification. It checks three distinct areas:

1. Component Structure Names: Schema component titles and names (e.g., UserProfile, OrderResponse)
2. URI Parameters: Path and query parameters (e.g., user_id, orderId, product-id)
3. JSON Schema Keys: Property names in request/response bodies (e.g., first_name, firstName, created-at)

The rule recursively validates:

• All schema components defined in #/components/schemas
• Request body schemas for all operations
• Response body schemas for all operations
• All path and query parameters (excluding headers)
• Nested object properties and array items

Why It Matters

Consistent naming conventions are critical for API usability and maintainability:

• Developer Experience: Developers can predict naming patterns, reducing cognitive load and errors
• Code Generation: Consistent naming enables reliable SDK and client code generation
• Team Alignment: Standardized conventions prevent style debates and ensure team consistency
• Integration Quality: Predictable patterns reduce integration bugs and simplify API consumption
• Professionalism: Consistent naming signals a well-designed, production-ready API

Examples

Good ✅

Using snake_case for JSON properties and URI parameters:

paths:
  /users/{user_id}:
    get:
      parameters:
        - name: user_id
          in: path
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                  first_name:
                    type: string
                  last_name:
                    type: string
                  created_at:
                    type: string
                    format: date-time

  /orders:
    get:
      parameters:
        - name: status_filter
          in: query
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'

components:
  schemas:
    OrderResponse:  # PascalCase for component names
      type: object
      properties:
        order_id:      # snake_case for properties
          type: string
        total_amount:
          type: number
        order_status:
          type: string

Using camelCase for JSON properties and URI parameters:

paths:
  /users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                  firstName:
                    type: string
                  lastName:
                    type: string
                  createdAt:
                    type: string
                    format: date-time

components:
  schemas:
    UserProfile:  # PascalCase for component names
      type: object
      properties:
        emailAddress:  # camelCase for properties
          type: string
        phoneNumber:
          type: string

Using kebab-case for URI parameters:

paths:
  /api/v1/products/{product-id}:
    get:
      parameters:
        - name: product-id
          in: path
          schema:
            type: string
        - name: include-reviews
          in: query
          schema:
            type: boolean

Bad ❌

Inconsistent naming across properties:

components:
  schemas:
    User:
      type: object
      properties:
        user_id:      # snake_case
          type: string
        firstName:    # camelCase - inconsistent!
          type: string
        last-name:    # kebab-case - inconsistent!
          type: string
        CREATED_AT:   # UPPER_SNAKE_CASE - inconsistent!
          type: string

Mismatched URI parameter and JSON property naming:

paths:
  /users/{user_id}:  # snake_case parameter
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:  # camelCase property - inconsistent!
                    type: string

Incorrect component structure naming:

components:
  schemas:
    user_profile:  # snake_case - should be PascalCase by default
      type: object
      properties:
        user_id:
          type: string

    order-response:  # kebab-case - should be PascalCase
      type: object

Configuration

This rule is highly configurable with three independent settings. Each setting can use a predefined naming convention or a custom regex pattern.

Configuration Variables

Available Naming Conventions

Each configuration variable accepts one of these predefined conventions:

1. snake_case - Lowercase words separated by underscores

   • Pattern: ^[a-z0-9]+(_[a-z0-9]+)*$
   • Examples: user_id, order_status, created_at

2. camelCase - First word lowercase, subsequent words capitalized

   • Pattern: ^[a-z][a-zA-Z0-9]*$
   • Examples: userId, orderStatus, createdAt

3. PascalCase - All words capitalized, no separators

   • Pattern: ^[A-Z][a-zA-Z0-9]*$
   • Examples: UserProfile, OrderResponse, PaymentMethod

4. kebab-case - Lowercase words separated by hyphens

   • Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
   • Examples: user-id, order-status, created-at

5. UPPER_SNAKE_CASE - Uppercase words separated by underscores

   • Pattern: ^[A-Z0-9]+(_[A-Z0-9]+)*$
   • Examples: USER_ID, ORDER_STATUS, CREATED_AT

6. Custom Regex - Provide your own regex pattern

   • Specify any valid regex pattern as the configuration value
   • Example: ^[a-z]{3,10}$ (lowercase, 3-10 characters)

Configuration Examples

Default configuration (snake_case for properties and parameters, PascalCase for components):

{
  "component_structure_names": "PascalCase",
  "uri_arg_pattern": "snake_case",
  "json_schema_key": "snake_case"
}

JavaScript/TypeScript style (camelCase everywhere except components):

{
  "component_structure_names": "PascalCase",
  "uri_arg_pattern": "camelCase",
  "json_schema_key": "camelCase"
}

Web-friendly style (kebab-case for URIs, camelCase for JSON):

{
  "component_structure_names": "PascalCase",
  "uri_arg_pattern": "kebab-case",
  "json_schema_key": "camelCase"
}

Environment variable style (UPPER_SNAKE_CASE):

{
  "component_structure_names": "PascalCase",
  "uri_arg_pattern": "snake_case",
  "json_schema_key": "UPPER_SNAKE_CASE"
}

Custom regex (strict 3-10 character lowercase identifiers):

{
  "component_structure_names": "PascalCase",
  "uri_arg_pattern": "^[a-z]{3,10}$",
  "json_schema_key": "^[a-z]{3,10}$"
}

Custom regex (prefixed identifiers):

{
  "component_structure_names": "^[A-Z][a-zA-Z0-9]*Dto$",
  "uri_arg_pattern": "snake_case",
  "json_schema_key": "^(str|int|bool)_[a-z_]+$"
}

Setting Configuration in REST Lens

Configure this rule in your project settings or .restlens.json:

{
  "rules": {
    "75": {
      "enabled": true,
      "config": {
        "component_structure_names": "PascalCase",
        "uri_arg_pattern": "snake_case",
        "json_schema_key": "snake_case"
      }
    }
  }
}

How to Fix

Step 1: Choose Your Conventions

Decide on naming conventions for each area. Consider:

• Your organization's existing standards
• Your target programming language(s)
• Industry conventions for your domain
• Client SDK generation requirements

Common combinations:

• Python/Ruby APIs: snake_case everywhere, PascalCase for components
• JavaScript/TypeScript APIs: camelCase for properties/parameters, PascalCase for components
• RESTful Web APIs: kebab-case for URIs, camelCase for JSON
• Enterprise APIs: snake_case for everything, PascalCase for components

Step 2: Update Component Names

Rename schema components to match your chosen convention:

# Before (inconsistent)
components:
  schemas:
    user_profile:
      type: object
    order-response:
      type: object

# After (PascalCase)
components:
  schemas:
    UserProfile:
      type: object
    OrderResponse:
      type: object

Step 3: Update URI Parameters

Rename path and query parameters:

# Before (inconsistent)
paths:
  /users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
        - name: include-details
          in: query

# After (snake_case)
paths:
  /users/{user_id}:
    get:
      parameters:
        - name: user_id
          in: path
        - name: include_details
          in: query

Step 4: Update JSON Schema Properties

Rename all property names in schemas:

# Before (inconsistent)
components:
  schemas:
    User:
      type: object
      properties:
        user_id:
          type: string
        firstName:     # Inconsistent!
          type: string
        last-name:     # Inconsistent!
          type: string

# After (snake_case)
components:
  schemas:
    User:
      type: object
      properties:
        user_id:
          type: string
        first_name:
          type: string
        last_name:
          type: string

Step 5: Handle Nested Objects

Ensure nested properties also follow conventions:

components:
  schemas:
    Order:
      type: object
      properties:
        order_id:
          type: string
        customer:
          type: object
          properties:
            customer_id:    # Nested properties match too
              type: string
            email_address:  # Consistent naming
              type: string
        line_items:
          type: array
          items:
            type: object
            properties:
              product_id:
                type: string
              quantity:
                type: integer

Step 6: Update References

Update all $ref references to use new component names:

# Before
responses:
  '200':
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/user_profile'

# After
responses:
  '200':
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/UserProfile'

Step 7: Document Your Conventions

Add your naming conventions to your API documentation:

info:
  description: |
    # Naming Conventions

    This API follows these naming conventions:
    - Component names: PascalCase (e.g., UserProfile, OrderResponse)
    - URI parameters: snake_case (e.g., user_id, order_id)
    - JSON properties: snake_case (e.g., first_name, created_at)

Related Rules

• Rule 26: Hyphens vs Underscores - Validates URI path segment naming style (hyphens vs underscores)
• Rule 28: Lowercase Letters in URIs - Enforces lowercase-only URIs for consistency
• Rule 1: Plural Collections - Ensures collection endpoints use plural nouns for consistency