At Monochrome, naming is not cosmetic. Names define how fast teams move, how few bugs we ship, and how easy the system is to understand six months later. Every name should read like natural English, be predictable, and never force the developer to guess what something means. We use camelCase everywhere, without exception.

IDs and Identity

Every object must use id as its identifier. We never expose database-specific names like _id or objectId to clients. This keeps the API database-agnostic and avoids leaking implementation details. If a relationship must be expressed, it should be done using a clear name such as userId, driverId, or orderId. We never mix user_id and userId, and we never shorten IDs into unclear forms like uid.

If the endpoint already implies the owner, we avoid repeating the ID in each item. For example, in “Get user addresses,” we do not repeat userId inside every address unless the response genuinely supports multiple users in one call.

Timestamps and Dates

All timestamps must be ISO-8601 strings and use consistent naming. Creation time is always createdAt, last modification time is always updatedAt, and scheduled or future times should be explicit, such as startsAt, endsAt, or expiresAt. We never use vague names like date, time, or timestamp without context.

If a time represents a duration, we do not overload date fields. Instead, we use names like durationMinutes, offlineMinutes, or remainingSeconds, so the unit is obvious without reading documentation.

Booleans

Boolean fields must read naturally when spoken out loud. They should almost always start with is, has, can, or should. Examples include isDefault, hasUnreadMessages, canCancel, or shouldRetry. We never use ambiguous booleans like default, active, or enabled without a prefix, because they become unclear in conditionals and logs.

Boolean values should always be true booleans, not 0 or 1, and not strings like "true".

Location and Geography

Coordinates must always be named latitude and longitude. We never shorten them to lat or long, because long is ambiguous and inconsistent across platforms. A readable address should be named formattedAddress or displayAddress, not just address, unless the meaning is unambiguous.

If an object contains multiple location types, we name them clearly, such as pickupLocation, dropoffLocation, or homeLocation, each containing its own latitude and longitude.

Text, Labels, and Human-Readable Fields

Any text intended for display should be clearly named to reflect that purpose. Titles are named title, short UI strings are named label, longer descriptions are named description, and system-generated messages should be named message. We avoid overloading one field to serve multiple purposes.

If text is meant to be user-facing, it should be safe to display without extra processing. If it is not user-facing, it should not live in the same field.

Arrays and Plurals

Arrays must always be plural and describe what they contain. We use addresses, drivers, items, routes, or notifications. We never use vague names like list, results, or dataList unless there is no better alternative.

When an array is empty, it should be returned as an empty array, not null. This prevents defensive coding on the client and keeps behavior consistent.

Numbers, Counts, and Totals

Counts should be explicitly named and never overloaded. We use names like count, totalCount, unreadCount, or completedTripsCount. If a number represents money, the currency should be implied by the product context or made explicit using a paired field like amount and currency.

We never return calculated numbers that could be misleading. If a value is unknown, we omit it or return null instead of guessing or defaulting to zero.

Status and State

Status fields should be predictable and finite. We use status for high-level state and represent it as a string enum, such as pending, active, completed, or cancelled. We do not mix numeric and string statuses across endpoints.

If there are multiple independent states, they should be separated into clearly named fields rather than packed into one overloaded status.

API Envelope (Top-Level Fields)

Every response uses the same top-level structure. The success flag is always named success and is a boolean. The message is always named message and written in a friendly, human tone. The payload lives in data. Optional metadata such as pagination or totals lives in meta. Errors live in error and never share space with data.

This consistency allows clients to handle responses generically and reduces custom parsing logic.

What We Avoid On Purpose

We avoid redundant fields that restate what the endpoint already tells us. We avoid leaking database structure. We avoid abbreviations that save a few characters but cost clarity. We avoid adding fields “just in case” without a clear consumer. We avoid mixed naming styles, even when integrating third-party services.

The Guiding Test

If a developer can read a response aloud and it sounds like normal English, the naming is correct. If they have to pause and think, the name needs improvement.

Monochrome API Ship Summary

Every endpoint must return a consistent top-level structure and never mix success and error states. Responses should be predictable, friendly, and easy for the app to decode without guesswork.

All field names must use camelCase, follow the Monochrome naming dictionary, and avoid database leakage such as _id. Booleans must read clearly (is, has, can), timestamps must be ISO strings with consistent naming, and locations must always use latitude and longitude.

Endpoints should only return what the client needs. Avoid redundant fields, repeated context, or unused database properties. Arrays must never be null, optional fields should be intentional, and defaults must not mislead.

Error responses must be stable and actionable, with a consistent error.code for logic and a friendly message for humans. No raw errors or stack traces should ever reach the client.

Responses must behave the same in all edge cases: empty data, new users, missing optional values. Shapes must not change depending on data availability.

Finally, every endpoint should be easy to decode in Swift and Kotlin and pass the “read-aloud test”: if the field names don’t sound like normal English, they’re not ready to ship.

#MoveWithMonochrome