[json] Allow (opt-in) 'description' field from JSON schema to behave as 'markdownDescription'

[mbronk]

Context:

VSCode extends JSON Schema with a markdownDescription property, allowing rich formatting in hovers.

• Separation of the raw description (ASCII-only) from Markdown-enriched markdownDescription is a good default practice, promoting toolset interoperability. JSON Schema specification is vague on the subject though. While plaintext is probably recommended, the specification wording:

  9.1. "title" and "description" The value of both of these keywords MUST be a string.

  does not necessarily specify whether rich formatting of description is not allowed (Markdown is a string after all).

• I work with schema files which are not VSCode-aware (I just happen to use VSCode as the JSON editor). These schemas do use Markdown for the primary description field. Would like these descriptions to render using rich formatting. While I could do a post-process of the file through jq and replace description --> markdownDescription, this doesn't scale well on updates and is cumbersome to work with.

Enhancements proposed

1. Keep the default (description is ASCII), but extend the json.schemas settings property allowing to specify per-schema if the user does want to treat it as if it was markdown. Ex. like so:

   {
       "settings": {
           "json.schemas": [           
               {
                   "fileMatch": [
                       "*-my-file-format.json"                 
                   ],
                   "url": "./my-json-schema.json",
                   "descriptionIsMarkdown": true   //<-- <new> proposed property
               }
           ]
       }
   }

2. Consider adding a schema extension (ex. descriptionsAreMarkdown top-level property or similar syntax, ex. using $comment), so that a VSCode-aware schema writer can opt-in to this behavior (instead of duplicating description/markdownDescription properties).

References:

• https://github.com/microsoft/vscode/issues/34498
• https://github.com/microsoft/vscode/issues/88927

[aeschli]

Are there other tools that interpret description as Markdown? I'm afraid that new flag will just add to the confusion.

[VSCodeTriageBot]

This feature request is now a candidate for our backlog. The community has 60 days to upvote the issue. If it receives 20 upvotes we will move it to our backlog. If not, we will close it. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[mbronk]

Are there other tools that interpret description as Markdown? I'm afraid that new flag will just add to the confusion.

Did not do any thorough research, but for example I use JSON Schema for Humans (pretty popular and quite awesome schema ▶️ HTML doc generator) and it offers this exact option: description_is_markdown.