Schema Field Naming

Category: Semantic Analysis

Description

Schema field names should be intuitive and self-explanatory, not cryptic abbreviations like flg1, dt_crt, or single letters like x.

What It Checks

This rule analyzes schema property names across the API:

• Identifies suspicious patterns: very short names, numbered abbreviations, consonant-only names
• Skips obviously good names: common terms like id, name, email, created_at
• Skips acceptable abbreviations: url, uri, api, http, json, etc.
• Uses AI to evaluate if suspicious names are actually intuitive

Why It Matters

Clear field names improve:

• Readability: Code using the API is self-documenting
• Maintainability: Easier to understand data structures
• Onboarding: New developers understand the API faster
• Documentation: Schema serves as documentation

Examples

Good

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        createdAt:
          type: string
          format: date-time
        isActive:
          type: boolean
        profileImageUrl:
          type: string

Bad

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        eml:  # Cryptic abbreviation for email
          type: string
        dt_crt:  # Unclear abbreviation
          type: string
        flg1:  # Meaningless flag name
          type: boolean
        x:  # Single letter, no meaning
          type: string

Exceptions

• Industry-standard abbreviations (ISO codes, established acronyms)
• Legacy schemas that cannot be changed
• Fields from external systems with fixed naming

Configuration

This rule has no configuration options. It is either enabled or disabled.

Related Rules

• Rule 75: Consistent Naming Conventions - Naming pattern enforcement
• Rule 77: Semantic Consistency - Cross-API naming consistency
• Rule 76: Allowed Dictionary - Domain vocabulary enforcement