Consider allowing description (and $comment) to be an 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?

[handrews]

@mewalig description is a long-standing keyword that serves many use case just fine, so we're not going to break compatibility on it. If you would like a multi-string description, that is a good candidate for an extension vocabulary. We have the repository https://github.com/json-schema-org/json-schema-vocabularies if you would like to propose such a keyword.

The JSON Schema organization is not actively working on further vocabularies at this time, but that repository serves as a reference for keyword proposals that might be of interest to anyone building such vocabularies.

[handrews]

@liquidaty I'm a little confused on what just happened with email notifications and issues. You mentioned items having two forms in a comment somewhere that I can't find right now. Note that we are planning to change that because it is a source of frustration and confusion: #864

You are welcome to file this in the vocabularies repo, so I'm not sure why you closed it there.

[liquidaty]

Thank you @handrews. We realized that our assertion about not breaking compatibility was incorrect and will leave it to @mewalig to open in the vocabularies repo