IPA-112: Field Names

Naming fields in a way that is intuitive to users can often be one of the most challenging aspects of designing an API. This is true for many reasons; often a field name that seems entirely intuitive to the author can baffle a reader.

Users rarely use only one API; they use many APIs together. As a result, a single company using the same name to mean different things (or different names to mean the same thing) can often cause unnecessary confusion.

It's important to keep consistency to allow users take what they've already learned from one API and apply that to another.

In short, APIs are easiest to understand when field names are simple, intuitive, and consistent with one another.

Guidance

Clarity

1. Field names should communicate the concept being presented and avoid ambiguous names.

   components:
     schemas:
       User:
         type: object
         properties:
           createdAt:
             type: string
             format: date-time
           accountStatus:
             type: string

   Why:

   createdAt and accountStatus clearly describe what the field represents without ambiguity.

   components:
     schemas:
       User:
         type: object
         properties:
           ts:
             type: string
             format: date-time
           status2:
             type: string

   Why:

   ts is ambiguous — it could mean timestamp, TypeScript, or something else. status2 implies a second status field without explaining the concept.

   1. Locate all field names across the spec's request and response schemas.

   2. For each field, determine whether its name clearly describes the concept it holds without requiring additional context.

   3. Flag fields whose names could be confused with a different concept or that require reading the description to understand their purpose.

2. Field names should avoid including unnecessary words.

   components:
     schemas:
       Order:
         type: object
         properties:
           status:
             type: string

   Why:

   status is concise. The Order schema context already implies it is the order's status.

   components:
     schemas:
       Order:
         type: object
         properties:
           orderStatus:
             type: string

   Why:

   orderStatus repeats the schema name. The Order context makes the order prefix redundant.

   1. For each field name, check whether any part of the name duplicates the surrounding schema name or other contextual information already implied by the location.

   2. Identify words that add no meaning and could be removed without loss of clarity.

   3. Flag fields where removing a word makes the name equally clear.

3. Field names should not use abbreviations unless the abbreviation is well-understood by the audience (for example: ip, aws, tcp).

   components:
     schemas:
       Server:
         type: object
         properties:
           ipAddress:
             type: string
           region:
             type: string

   Why:

   ipAddress uses the widely understood ip abbreviation. region is fully spelled out.

   components:
     schemas:
       Server:
         type: object
         properties:
           srvAddr:
             type: string
           rgn:
             type: string

   Why:

   srvAddr and rgn are non-standard abbreviations that require readers to guess the full meaning.

   1. List all field names across the spec.

   2. Identify names containing abbreviations (short sequences or missing vowels).

   3. Determine whether each abbreviation is widely understood in the target audience domain (networking, cloud infrastructure, etc.).

   4. Flag abbreviations that are not industry-standard or are ambiguous without additional context.

Casing and characters

1. Field names must use camelCase.

   components:
     schemas:
       User:
         type: object
         properties:
           firstName:
             type: string
           lastLoginAt:
             type: string
             format: date-time

   Why:

   firstName and lastLoginAt start with a lowercase letter and capitalize each subsequent word.

   components:
     schemas:
       User:
         type: object
         properties:
           first_name:
             type: string
           LastLoginAt:
             type: string
             format: date-time

   Why:

   first_name uses snake_case and LastLoginAt uses PascalCase. Both violate the camelCase requirement.

2. Fields must not contain leading, trailing, or adjacent underscores.

   components:
     schemas:
       Document:
         type: object
         properties:
           id:
             type: string

   Why:

   id contains no underscores. Field names use camelCase rather than underscore-separated words.

   components:
     schemas:
       Document:
         type: object
         properties:
           _id:
             type: string
           __metadata:
             type: object

   Why:

   _id has a leading underscore and __metadata has double leading underscores. Both are prohibited regardless of the originating storage convention.

Semantics

1. Field names must not reflect an intent or action — fields must not be verbs.

   components:
     schemas:
       User:
         type: object
         properties:
           disabled:
             type: boolean

   Why:

   disabled is an adjective describing state, not a verb instructing an action.

   components:
     schemas:
       User:
         type: object
         properties:
           disable:
             type: boolean

   Why:

   disable is a verb. Field names must represent state or data, not commands or intents.

   1. List all field names across request and response schemas.

   2. Identify names that are base-form verbs (e.g., disable, create, update).

   3. Verify that state-representing fields are adjectives (e.g., disabled, created) rather than verbs.

   4. Flag any field name that functions as a command or imperative verb.

2. Repeated fields must use the proper plural form.

   components:
     schemas:
       Order:
         type: object
         properties:
           items:
             type: array
             items:
               $ref: "#/components/schemas/OrderItem"
           tags:
             type: array
             items:
               type: string

   Why:

   items and tags are correctly pluralized array fields.

   components:
     schemas:
       Order:
         type: object
         properties:
           item:
             type: array
             items:
               $ref: "#/components/schemas/OrderItem"
           tag:
             type: array
             items:
               type: string

   Why:

   item and tag are singular but represent collections. Singular names for array fields mislead readers about cardinality.

   1. Find all schema properties typed as array across the spec.

   2. Verify that each array property name uses the proper plural form.

   3. Flag array properties with singular names.

Boolean fields

1. Boolean fields should omit the is prefix.

   components:
     schemas:
       User:
         type: object
         properties:
           disabled:
             type: boolean
           active:
             type: boolean

   Why:

   disabled and active are clear boolean adjectives without a redundant is prefix.

   components:
     schemas:
       User:
         type: object
         properties:
           isDisabled:
             type: boolean
           isActive:
             type: boolean

   Why:

   isDisabled and isActive carry a redundant is prefix. The boolean type already implies a yes/no value.

Consistency

1. APIs should use the same name for the same concept and different names for different concepts, including across APIs and resources.

   components:
     schemas:
       User:
         type: object
         properties:
           createdAt:
             type: string
             format: date-time
       Order:
         type: object
         properties:
           createdAt:
             type: string
             format: date-time

   Why:

   Both User and Order use createdAt for the creation timestamp. Readers immediately recognize the semantics when they encounter it on any resource.

   components:
     schemas:
       User:
         type: object
         properties:
           createdAt:
             type: string
             format: date-time
       Order:
         type: object
         properties:
           creationDate:
             type: string
             format: date-time

   Why:

   createdAt and creationDate represent the same concept but use different names, forcing consumers to learn resource-specific vocabulary.

   1. Collect all field names across all schemas in the spec.

   2. Group fields by their documented description or semantic type (e.g., creation timestamps, identifiers, status enums).

   3. Flag groups where multiple names describe the same concept.

   4. Flag cases where the same field name appears on different schemas with different documented semantics.

2. Names should be unified between the GUI and the API wherever possible.

   components:
     schemas:
       Cluster:
         type: object
         properties:
           diskSizeGB:
             type: number
             description: >
               Storage capacity in gigabytes. Displayed as "Disk Size (GB)" in the
               UI.

   Why:

   The field description maps the API field name to the corresponding UI label, making it easy for users who switch between interfaces.

   components:
     schemas:
       Cluster:
         type: object
         properties:
           storageCapacity:
             type: number
             description: Storage capacity in gigabytes.

   Why:

   If the UI calls the same concept "Disk Size", storageCapacity in the API creates a disconnect. Users searching for "disk size" in API docs won't find it.

   1. Identify the UI labels for concepts exposed by the API.

   2. Compare each API field name against the corresponding UI label for the same concept.

   3. Flag API field names that diverge from their GUI counterparts without a documented justification.

3. Field names that represent common conventions must use the same name and description as established across existing APIs.

   components:
     schemas:
       Resource:
         type: object
         properties:
           id:
             type: string
             description: Unique identifier for the resource.
           createdAt:
             type: string
             format: date-time
             description: Timestamp when the resource was created.

   Why:

   id and createdAt match established standard names and descriptions used for identifiers and creation timestamps across APIs.

   components:
     schemas:
       Resource:
         type: object
         properties:
           resourceId:
             type: string
             description: The ID of this resource.
           dateCreated:
             type: string
             format: date-time
             description: The date the resource was created.

   Why:

   resourceId and dateCreated deviate from the standard names id and createdAt for well-known conventions, fragmenting the shared vocabulary across APIs.

   1. Identify fields in the spec that represent common cross-API concepts such as identifiers, timestamps, status, and error codes.

   2. Cross-reference these fields against established standard field names and descriptions documented in IPA guidelines or the API style guide.

   3. Flag fields that use a non-standard name or description for a well-known convention.

4. Field names must refer to a singular concept when used across APIs.

   components:
     schemas:
       User:
         type: object
         properties:
           status:
             type: string
             enum: [active, inactive, suspended]
             description: Lifecycle state of the user account.
       Order:
         type: object
         properties:
           status:
             type: string
             enum: [pending, fulfilled, cancelled]
             description: Fulfillment state of the order.

   Why:

   Both schemas use status for a lifecycle/state concept. Enum values differ, but the semantic type is the same across both usages.

   components:
     schemas:
       User:
         type: object
         properties:
           status:
             type: string
             description: Lifecycle state of the user account.
       ServerResponse:
         type: object
         properties:
           status:
             type: integer
             description: HTTP status code of the last operation.

   Why:

   status means "lifecycle state" on User but "HTTP status code" on ServerResponse. The same name maps to two unrelated concepts.

   1. Find all field names that appear in more than one schema across the spec.

   2. For each repeated name, compare the descriptions and types across schemas.

   3. Flag field names where the same name is used for semantically different concepts.

5. Existing concepts must map to a singular field name.

   components:
     schemas:
       User:
         type: object
         properties:
           groupId:
             type: string
             description: The group this user belongs to.
       Project:
         type: object
         properties:
           groupId:
             type: string
             description: The group this project belongs to.

   Why:

   Both schemas use groupId for the organizational grouping concept. Consumers learn the name once and recognize it everywhere.

   components:
     schemas:
       User:
         type: object
         properties:
           groupId:
             type: string
             description: The group this user belongs to.
       Project:
         type: object
         properties:
           teamId:
             type: string
             description: The group this project belongs to.

   Why:

   groupId and teamId describe the same organizational grouping but use different names, forcing consumers to learn schema-specific synonyms.

   1. Identify concepts that appear across multiple schemas (e.g., group membership, ownership, timestamps).

   2. List all field names used for each concept across the spec.

   3. Flag concepts represented by more than one distinct field name.

6. Field names must be consistent between the request body, response body, and path parameters for the same concept.

   paths:
     /users/{userId}:
       get:
         parameters:
           - name: userId
             in: path
             required: true
             schema:
               type: string
         responses:
           "200":
             content:
               application/json:
                 schema:
                   properties:
                     userId:
                       type: string
       patch:
         requestBody:
           content:
             application/json:
               schema:
                 properties:
                   userId:
                     type: string

   Why:

   userId appears consistently in the path parameter, response body, and request body.

   paths:
     /users/{userId}:
       get:
         parameters:
           - name: userId
             in: path
             required: true
             schema:
               type: string
         responses:
           "200":
             content:
               application/json:
                 schema:
                   properties:
                     id:
                       type: string
       patch:
         requestBody:
           content:
             application/json:
               schema:
                 properties:
                   user_id:
                     type: string

   Why:

   The same concept appears as userId in the path, id in the response, and user_id in the request. Consumers must map these manually.

   1. For each resource path with path parameters, note the parameter names.

   2. Inspect the request and response schemas for the same operation and verify that the same concept uses the same field name in all locations.

   3. Flag any discrepancy where request body, response body, or path parameter names differ for the same concept.

7. For enum fields, the allowable values may differ from values allowed in other instances of the same field name across APIs or resources.

Group vs. Project

For historical reasons, some MongoDB APIs used project and projectId where the concept is more accurately described as a group. New APIs must align on the group terminology.

1. For consistency, APIs must use group, groups, or groupId rather than project, projects, or projectId.

   paths:
     /groups/{groupId}/clusters:
       get:
         parameters:
           - name: groupId
             in: path
             required: true
             schema:
               type: string

   Why:

   groupId is the canonical name for the organizational grouping concept.

   paths:
     /projects/{projectId}/clusters:
       get:
         parameters:
           - name: projectId
             in: path
             required: true
             schema:
               type: string

   Why:

   projectId is a legacy term. Using it in new APIs diverges from the established groupId convention.