> For the complete documentation index, see [llms.txt](https://help.cumuluspro.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.cumuluspro.net/json/json-coding-standards-and-best-practices.md).

# 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

| Area      | What to Verify                                                                                                                     |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 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.                                           |