✨ Proposal: multi-line description array

[kr99]

Describe the inspiration for your proposal

Problem: Complex API parameters require longer documentation, but JSON Schema only allows single-string descriptions.

A single-string description field, for complex field documentation, forces either:

• Unreadable walls of text (cognitive overload)
• Incomplete documentation (missing critical details)
• External documentation (breaking single source of truth)

JSON Schema already supports some documentation fields:

• title (string)
• description (string)
• $comment (string - for schema authors only)
• examples (array)

Notable precedent: Issue #100 requesting multi-line descriptions was opened in 2016, closed without resolution.

Describe the proposal

I propose a longDescription array field that enables progressive disclosure - a more detailed field that can be shown as-needed.

Why an array?

• Tool-friendly: Native to JSON - no need to embed html/markdown inside JSON (but it makes doing so more readable)
• Consistent: JSON Schema already uses arrays for structured data (examples, enum)
• Human-readable: Allows natural line breaks and readable JSONschema documents - more maintainable
• Transform-ready: Tools can render as bullets, accordions, tooltips, etc.

Sort parameters are often complex, so make a good example:

{
  "sort": {
    "type": "string",
    "description": "Sort results by field(s)",
    "syntax": "field:asc|desc, ...",
    "examples": [
      "createdAt:desc",
      "lastName:asc,firstName:asc"
    ],
    "longDescription": [
      "Multiple fields: Left→right priority, <...>",
      "Format: <long explanation here>",
      "Default: createdAt:desc",
      "Security: Whitelisted fields are (...)",
      "Performance: May require <...>"
    ]
  }
}

This solves problems such as what you see here:

// WITHOUT THIS: Unreadable wall of text with delimiters reducing readability
{
  "sort": {
    "type": "string", 
    "description": "\nSort results by field(s). \nSyntax: field:asc|desc, comma-separated. \nMultiple fields processed left-to-right. \nDefault: createdAt:desc. \nSecurity: Whitelisted fields only. \nPerformance: May require pagination for large result sets."
  }
}

Describe alternatives you've considered

Issue #100 (opened 2016) requested array-based descriptions but was closed without resolution.

The examples field comes closest to offering structured details - and it is already an array, establishing precedent.

Current workarounds:

• Markdown formatting in description (but requires parsing, dialect wars)
• \n escape sequences (shown above - still hard to read in JSON)
• Vendor extensions like x-???? (non-standard)

I can use x-longDescription as a temporary workaround, but this seems evidently needed given:

• 8+ years of unresolved requests
• Natural fit with JSON Schema's existing array-based patterns

Additional context

This proposal is non-breaking: it doesn't replace description, just augments it with optional structured detail. Tools that don't recognize longDescription will simply ignore it and continue using description.

[dhiraj-143r]

Thanks for opening this proposal — it’s very clear and highlights a real documentation pain point in JSON Schema.

I agree that the current single-string description field becomes limiting for complex parameters. Large multi-line explanations, syntax details, warnings, and performance notes quickly turn into unreadable blobs filled with \n escapes or markdown hacks. This hurts both maintainability and tooling UX.