✨ Proposal: Allow $comment to be an array of strings for multiline support #1663

Describe the inspiration for your proposal

The inspiration comes from the daily challenge of documenting complex architectural decisions directly within JSON Schemas. Currently, the $comment keyword only accepts a single string, which limits how developers can organize information.

Specifically, this proposal is inspired by the need for:

1. Hierarchical Documentation: Many developers prefer to include a "General Documentation Header" at the top of the schema to explain the overall architecture, while using more specific, granular comments as they go deeper into the nested properties of the file.

2. Readability: Developers are forced to write extremely long single lines or use escaped newline characters (\n), which are hard to read and maintain in standard text editors.

3. Version Control Noise: When a long comment is modified in a single-line string, the git diff highlights the entire block. An array of strings allows for cleaner, line-by-line diffs, making code reviews much more efficient.

Describe the proposal

The proposal is to update the meta-schema definition for the $comment keyword to allow both a single string and an array of strings.

Changes to the Meta-Schema:
From:

"$comment": {
    "type": "string"
}

To:

"$comment": {
    "anyOf": [
        { "type": "string" },
        { 
            "type": "array",
            "items": { "type": "string" }
        }
    ]
}

Example Use Case (Documentation Header & Deep Notes):

{
  "$schema": "...",
  "$comment": [
    "Project: User Management API",
    "Version: 2.4.0",
    "Maintainer: Backend Team",

    "This schema defines the strict requirements for user profiles,",
    "ensuring compliance with GDPR and internal security auditing."
  ],
  "type": "object",
  "properties": {
    "auth_metadata": {
      "type": "object",
      "$comment": [
        "Internal Note: This section is temporary.",
        "Ref: Ticket-402 (Migration to OAuth2)."
      ]
    }
  }
}

Implementation Behavior:

Implementations should treat an array of strings as a single logical comment.

Since $comment is strictly for developers and must not affect validation, this change maintains the keyword's core purpose while increasing flexibility for documentation-heavy workflows.

Describe alternatives you've considered

1. Using \n in strings: The current workaround. It is cumbersome and fails to solve the "Clean Diff" and "Hierarchical Header" organization problem.

2. Using description: Intended for end-users and UI generation. Using it for internal implementation notes or architectural headers pollutes the public-facing documentation. The comment would show itself in a context menu like Visual Studio Code.

3. Custom keywords (e.g., x-comment): Fragments the ecosystem. Since $comment is the standard for internal notes, it should support standard documentation practices like multiline blocks.

Additional context

This change aligns with how other modern configuration formats (like YAML) handle text blocks. It acknowledges that JSON Schemas are not just for machines, but are critical documents for human engineers to understand complex systems.

My proposal is retro compatible with the old-style behavior, preventing existing tools from breaking and reduces cognitive load by reusing existing patterns.