# JSON Coding Standards and Best Practices

### 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.                                           |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.cumuluspro.net/json/json-coding-standards-and-best-practices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.