Consistent naming and casing of JSON fields

What it is

JSON (RFC 8259, cited) constrains only syntax: objects are name/value pairs, names are strings, and names within an object should be unique. How names look is convention. Google's JSON Style Guide (cited) requires property names to be camel-cased ASCII strings with defined semantics, warns against arbitrary grouping of data, represents enum values as strings and formats dates as RFC 3339 strings. The ProtoJSON mapping (cited) serialises protobuf field names as lowerCamelCase keys, enums by their names, and 64-bit integers as decimal strings because many JSON consumers cannot represent them exactly. snake_case (created_at) is equally common. What matters is that one convention holds across every endpoint, including error bodies and webhook payloads.

Why it matters

Inconsistent names are a visible sign of an API assembled from several teams: clients need per-endpoint mapping code, generated SDKs produce awkward identifiers, and agents reading the description cannot infer field names from patterns.

How to apply

• Write the convention into the API style guide with examples: case, plural names for arrays (items), boolean prefixes (isActive, hasChildren), unit or format suffixes (durationSeconds, sizeBytes), identifier fields ending in Id.
• Enforce it mechanically: a linter over the OpenAPI document, or protobuf field-name rules plus the ProtoJSON mapping.
• Name by meaning, not by storage: customerId, not cust_fk; do not rename when the database column changes.
• Choose value formats once: RFC 3339 timestamps with an offset, explicit unit suffixes or ISO 8601 durations, enum strings rather than numbers, money as strings or integer minor units.
• Use the same name for the same concept across resources; owner on one resource and ownerId on another is a defect.
• Treat JSON objects used as maps differently: their keys are data and follow no naming rule, and the documentation must say which objects are maps.

Pitfalls

Renaming a field to fix its case is a breaking change; add the new name and keep the old one for a deprecation period. Leaking implementation identifiers such as $type or __typename into a public contract without documenting them. Abbreviations only the originating team understands. Mixed-case duplicates (userId and userID) that survive because nobody lints.