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

[EduApps-CDG]

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.

[gregsdennis]

Please see the discussion from #1645. I believe it applies here as well.

[EduApps-CDG]

Yeah. It's almost the same deal, with different approaches. I was afraid of writing about description because it's unclear to me how should parsers join the lines (as a \n, as a whitespace or as a empty string).

Yet, creating $longComment or longDescription will cause a future where everyone would use the long version and nobody would use the default standard (fragmentation).

Besides, instead, tools will have to support an extra property instead of just improving the existing property.

Also, it would create a two-source-of-truth problem where both properties could exist at the same time and tools will have to prioritize one of both.

[jdesrosiers]

My opinion on this is the same as it is for the description proposal Greg linked. This is a JSON problem, not a JSON Schema problem. There's no reason you need to develop schemas in JSON. JSONC, JSON5, and YAML are some options that have native support for comments. We probably shouldn't have defined $comment at all. It's really should be left as a media type feature, not a feature of the JSON Schema language.

[EduApps-CDG]

I fully agree this is ultimately a JSON syntax limitation, and YAML/JSON5 are excellent alternatives with native multiline and comment support and many people already use them widely.

That said, a lot of teams and tools still author and distribute schemas strictly in plain JSON (for CI/CD integration, auto-generation, cross-language portability, or just because "it's JSON Schema").

My proposal isn't about fixing JSON itself. It's about improving improving a existing feature in JSON Schema for those who stick with and really want to use JSON Schema: making the existing, ignored $comment annotation more readable and maintainable with an array of strings, at minimal cost, fully backward-compatible, and with zero impact on validation or consumers.