JSON / JSON5¶

Trailing commas should be rejected for JSON unless JSON5 is explicitly targeted.

Trailing commas are valid JSON5 but illegal in strict JSON (RFC 8259). Many tools silently strip them during parsing, making them an invisible source of diff noise and interoperability failures.

Common Violations:

• Trailing commas in strict JSON mode

Detectable Patterns:

• ,\]
• ,\}

Configuration:

Example — violation:

{
  "name": "my-package",
  "version": "1.0.0",
}

Example — compliant (JSON5):

// zen-config: target_format=json5
{
  "name": "my-package",
  "version": "1.0.0",
}

Deeply nested objects/arrays are hard to reason about and validate.

Beyond a few levels of nesting reviewers lose the mental model of which object they are editing. Flat schemas or $ref-based splitting improve readability and testability.

Common Violations:

• Nesting depth exceeds configured threshold

Configuration:

Example — violation (depth 7):

{"a": {"b": {"c": {"d": {"e": {"f": {"g": 1}}}}}}}

Duplicate object keys silently override values in many parsers.

RFC 8259 §4 states that key uniqueness should apply, but most parsers accept duplicates and retain — or discard — earlier values without warning. This leads to latent bugs that are invisible in code review.

Common Violations:

• Duplicate keys in an object

Example — violation:

{
  "timeout": 30,
  "timeout": 60
}

Repeated string literals should be extracted or referenced consistently.

When the same string value appears in many places (e.g. a base URL, an environment name), a single typo or an update leaves files in an inconsistent state. Consider JSON Schema $ref anchors or a shared constants fragment.

Common Violations:

• Repeated magic string values

Configuration:

Example — violation:

{
  "dev_url":  "https://api.example.com",
  "test_url": "https://api.example.com",
  "prod_url": "https://api.example.com"
}

Avoid mixing camelCase, snake_case, and PascalCase at the same object level.

JSON keys are case-sensitive identifiers. Mixing conventions at the same object level creates inconsistency that makes it harder to predict key names programmatically.

Common Violations:

• Mixed key casing at same object level

Example — violation:

{
  "firstName": "Alice",
  "last_name": "Smith",
  "Email": "alice@example.com"
}

Very large inline arrays are hard to review and often belong in separate data files.

Arrays with many elements clutter configuration files and obscure intent. Move large data sets to separate files and reference them by path.

Common Violations:

• Oversized inline arrays

Configuration:

Excessive null usage usually indicates optional keys that can be omitted.

A document littered with null values signals that the schema was designed around a relational model where absent values must be declared. JSON schemas benefit from key omission — absent means absent.

Common Violations:

• Excessive null values across the document

Configuration:

Date strings should use ISO 8601 format for unambiguous, sortable representation.

JSON has no native date type — dates are encoded as strings. Locale-dependent formats such as MM/DD/YYYY are ambiguous (is 02/03/2024 the 2^nd of March or the 3^rd of February?). YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ sort correctly as strings, interoperate across time zones, and are universally recognised.

Common Violations:

• Non-ISO 8601 date string detected

Detectable Patterns:

• \d{1,2}/\d{1,2}/\d{2,4} (MM/DD/YYYY)
• \d{1,2}\.\d{1,2}\.\d{4} (DD.MM.YYYY)

Configuration:

Example — violation:

{
  "created_at": "03/15/2024",
  "expires":    "31.12.2025"
}

Example — compliant:

{
  "created_at": "2024-03-15",
  "expires":    "2025-12-31T23:59:59Z"
}

Top-level object keys set explicitly to null should be omitted entirely.

Setting a top-level key to null communicates intentional absence but adds noise to the schema. In most cases the correct action is to omit the key altogether, letting consumers default-construct missing values rather than handle explicit null.

Common Violations:

• Top-level key set to explicit null

Configuration:

Example — violation:

{
  "name": "my-service",
  "database": null,
  "cache": null
}

Example — compliant:

{
  "name": "my-service"
}