JSON naming conventions

Contract

Enforces the Google-JSON-Style-Guide naming grammar on the keys and value forms of any JSON object you design: camelCase keys, plural array names, omit-vs-null, and SCREAMING_SNAKE enum strings. Apply when shaping a payload's keys; not to the transport envelope and not to the meaning of the data.

Rules

1. Keys are camelCase — the whole document. Every property name is camelCase: firstName,

postalCode, createdAt, isActive. Never snake_case (first_name), never PascalCase (FirstName), and never a MIX of styles inside one document (firstName beside created_at is the most common error). One casing, applied to every key.

1. Array keys are plural; single-object keys are singular. A property holding a list gets a plural

noun: tags, phoneNumbers, lineItems. A property holding one nested object stays singular: address, owner. The key's number matches its cardinality.

1. Omit an absent value; do not send null. When a field has no value and absent-vs-null carries no

meaning, drop the key entirely rather than emitting "middleName": null. Send an explicit null ONLY when null is a distinct, meaningful state the client must tell apart from "missing".

1. Enum values are SCREAMING_SNAKE_CASE strings. A value from a fixed set is an uppercase,

underscore-joined string: "ACTIVE", "IN_PROGRESS", "BANK_TRANSFER". Never a magic integer ("status": 2), never a lowercase or camelCase word ("active", "inProgress").

1. No leading _ or $ on keys. Property names start with a lowercase letter. Reserve nothing with a

leading underscore or dollar sign (_id, $type); those collide with framework/reserved conventions.

1. Timestamps are ISO-8601 strings. A date or time is an ISO-8601 string in UTC:

"2026-01-15T09:00:00Z". Never a Unix epoch integer and never a locale-formatted string ("01/15/2026").

1. Booleans read as predicates. A boolean key is phrased as a yes/no question: isActive,

hasDiscount, canEdit — not a noun like active or discount.

Worked examples

The base's DB-flavored default is on the left; the conforming JSON on the right.

A book record — snake_case keys and an integer status become camelCase and a string enum:

BEFORE  { "book_title": "...", "page_count": 320, "status": 1 }

AFTER   { "bookTitle": "...", "pageCount": 320, "status": "PUBLISHED" }

An invoice with a missing paid date — an explicit null becomes an omitted key:

BEFORE  { "invoiceNumber": "A-91", "paidDate": null }

AFTER   { "invoiceNumber": "A-91" }        // paidDate simply absent

A sensor reading — a singular array name and a mixed-casing pair get fixed:

BEFORE  { "reading": [ ... ], "captured_at": 1737019800 }

AFTER   { "readings": [ ... ], "capturedAt": "2026-01-16T08:10:00Z" }

Edge cases & exceptions

• An acronym in a key stays camelCase, not upper-run: userId, htmlContent, apiKey — not

userID or HTMLContent.

• null IS meaningful (a form field the user explicitly cleared vs never filled) → keep the explicit

null; the omit rule only covers "no meaning to the distinction".

• A map/dictionary of dynamic keys (user-supplied labels → values) is exempt from camelCase — its keys

are data, not property names.

• A single-element list is still a plural key — tags holding one tag, not tag. Cardinality follows

the type, not the current count.

• An enum that is genuinely an open string (a free-text label) is not forced to SCREAMING_SNAKE; the

rule covers closed sets only.

Do / Don't

• Do use camelCase for every key. Don't use snake_case, and never mix the two in one object.
• Do give array keys plural names. Don't call a list item or tag.
• Do omit an absent optional field. Don't send "field": null for a value that is merely missing.
• Do encode enums as SCREAMING_SNAKE strings. Don't use integer codes or lowercase words.
• Do start keys with a lowercase letter. Don't prefix with _ or $.
• Do use ISO-8601 strings for time. Don't send epoch integers or locale dates.

Common mistakes

• Emitting snake_case keys straight from a database column set.
• Mixing camelCase and snake_case keys in the same object.
• A singular array name (user: [...]) where a plural belongs (users).
• "status": 0 / "type": 3 integer enums instead of named string constants.
• Explicit null littered across every optional field.
• Epoch timestamps (1737019800) instead of ISO-8601 strings.

Quick checklist

• ] Every key is camelCase; no snake_case, no mixing.
• ] Array keys plural, single-object keys singular.
• ] Absent optional values omitted, not null.
• ] Enum values are SCREAMING_SNAKE strings, not ints or lowercase.
• ] No key starts with _ or $.
• ] Timestamps are ISO-8601 strings.