JSON Coding Standards and Best Practices
This document defines a baseline JSON standard for configuration files, API payloads, and system data structures.
Core Principles
Keep JSON valid, predictable, and easy to parse.
Prefer clear naming and stable structure over short or clever key names.
Use consistent property ordering so similar objects read the same way.
Choose the correct JSON type and keep that type stable for the same field.
Keep objects focused and avoid deeply nested structures unless they add real clarity.
Property Naming
Property names should be descriptive, stable, and consistent across the codebase. A reviewer should understand what each field represents without needing separate explanation.
Use camelCase for JSON keys unless a system integration explicitly requires a different format.
Use descriptive names that communicate the meaning of the field, for example
"customerName"instead of"cust".
Use nouns for values and collections, such as
"documentId","fullName", or"lineItems".
Where a field exists only for reference or internal use, prefix it with an underscore when that convention is used in the project, for example
"_workflowNames".
Recommended JSON Property Patterns
camelCase
General keys
"customerName", "workflowIds"
Boolean prefix
True/false flags
"isActive", "hasAccess"
Underscore prefix
Internal/reference-only fields
"_workflowNames", "_notes"
Consistent suffix
Identifiers and metadata
"documentId", "createdDate"
Readability and Formatting
Formatting should help humans read the data quickly while keeping the JSON machine-safe.
Use consistent indentation throughout the file. Two spaces is common for JSON, but the project should use one standard consistently.
Use double quotes for all keys and string values, because valid JSON requires double quotes.
Place each property on its own line when the object has multiple fields.
Avoid trailing commas, because they are invalid in strict JSON and may break parsing.
Use line breaks and indentation so nested objects and arrays are visually clear.
Format example payloads consistently across documentation, configuration, and testing artifacts.
Structure and Responsibility
Each object should represent one coherent unit of information. Related properties should stay together, and unrelated concerns should not be mixed into the same object without a clear reason.
Keep each object focused on one logical responsibility.
Group related data under nested objects only when the grouping improves clarity.
Avoid unnecessary nesting that makes payloads difficult to read and validate.
Use arrays for repeated items and keep the shape of each array item consistent.
When the same concept appears in multiple places, use the same key names and the same structure
Additional Best Practices
JSON should be reviewed not only for syntax, but also for naming, type consistency, structural clarity, and schema alignment.
JSON Review Checklist
Validity
JSON is syntactically valid: double quotes used, commas placed correctly, no trailing commas, and brackets are balanced.
Naming
Keys follow a consistent convention such as camelCase and use descriptive, stable names.
Structure
Objects and arrays are organized logically, with nesting kept reasonable and repeated groups modeled consistently.
Typing
Values use appropriate JSON types and similar fields do not switch between string, number, boolean, array, or object unexpectedly.
Ordering
Property order is deliberate and aligned with how the data is read, configured, or displayed.
Clarity
Optional or internal-use fields are clearly named, and redundant properties are avoided.
Last updated