Consider allowing description (and $comment) to be array of strings

[mewalig]

Please consider allowing a description to be an array of strings.

The utility of this alternative representation is hopefully self-evident. In any case, an example of this idea in practice is https://pypi.org/project/sphinx-jsonschema/, which supports description arrays through an alternative keyword ($$description) (so there's at least one other person out there who would seem to find a use for this if it was in the spec...).

For example, using the default example at https://editor.swagger.io/:

yaml:

swagger: '2.0'

info:
  version: 1.1.0
  title: Simple API
  description: |
    A simple API to learn how to write OpenAPI Specification.
    This file uses almost every single aspect of the [Open API Specification](https://openapis.org/).  
    This API will use JSON.  
    JSON looks like this:  
    
    ```JSON
    {
      "key": "value",
      "anotherKey": "anotherValue"
    }
    ```
  termsOfService: http://simple.api/terms-of-service

As converted to JSON Schema:

{
  "swagger": "2.0",
  "info": {
    "version": "1.1.0",
    "title": "Simple API",
    "description": "A simple API to learn how to write OpenAPI Specification.\nThis file uses almost every single aspect of the [Open API Specification](https://openapis.org/).  \nThis API will use JSON.  \nJSON looks like this:  \n\n```JSON\n{\n  \"key\": \"value\",\n  \"anotherKey\": \"anotherValue\"\n}\n```\n",
    "termsOfService": "http://simple.api/terms-of-service"
  }
}

Notice that the description is a 293-character line with embedded \n chars.

Under the proposed approach, this could equivalently be written as:

{
  "swagger": "2.0",
  "info": {
    "version": "1.1.0",
    "title": "Simple API",
    "description": [
        "A simple API to learn how to write OpenAPI Specification.",
        "This file uses almost every single aspect of the [Open API Specification](https://openapis.org/).",
        "This API will use JSON.",
        "JSON looks like this: ",
        "",
        "```JSON",
        "{",
        "  \"key\": \"value\",",
        "  \"anotherKey\": \"anotherValue\"",
        "}",
        "```"
    ],
    "termsOfService": "http://simple.api/terms-of-service"
  }
}

This proposed change would also apply to $comment and/or any other JSON Schema string types that are intended to capture arbitrary-length and potentially multi-line strings.

Seems like this would be an easy spec change that doesn't have much downside. Thoughts?

[mewalig]

Sorry. Just realized this is in the wrong json schema repo. Will move to json schema spec