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

[mewalig]

Please consider allowing a description to be an array of strings, or an alternative keyword that provides the equivalent functionality.

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).

Using the default example at https://editor.swagger.io/ as an example:

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 is:

{
  "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?

(moved from json-schema-org/json-schema-spec#875)

[mewalig]

Regarding the concern that this may raise the same issues as json-schema-org/json-schema-spec#864 (re items being polymorphous), my view is that the critical issue there-- namely, that a non-array single item must be treated differently from an array with that single item as its sole contents-- does not exist in this case, and therefore the only issue that this proposal raises is the fact that the use of this new form (array of string vs string), while not causing breakage for schema writers, would create a breaking change for JSON Schema readers.

An existing example of an string/array-of-strings union is the keyword type, which allows either a string or an array of strings, where a string is treated the same as an array with that one string as its contents.

[Relequestual]

In the vocabularies repo, the idea is that orgs or groups get together to establish groups of keywords to form a purposefull extension to JSON Schema. The core team are NOT activly working on this, and do not intend to do so.

We DO need to write better guidance that explains this mind, so apologies.

I guess your suggestion would fit more in a "documentation" vocabulary extension.
With extensions, I think you can only ADD as opposed to modify expectations.

[mewalig]

Thank you. The reason this was posted here is because that's what was suggested by @handrews here. So, I'm not sure how to respond to your comment, other than to say that I'm happy to post it wherever the proper home is deemed to be. And to confirm, the proposal is to modify the vocabulary (add is only suggested as a fallback in case there is some other compelling reason not to modify, which reason I'm not seeing at the moment).

[handrews]

@mewalig I meant posting the idea for a new keyword that does what you want. This is a holding area for proposals to give people who are interested in implementing extensions a place to look for ideas.

We will definitely not be changing the existing keywords.

[handrews]

If you want to discuss this sort of thing in more detail, please join our slack (go to json-schema.org and click "Join our Slack" in the upper right). It is more conversational than GitHub issues.

[mewalig]

OK, I will take this to slack. One question though: if the result of the slack conversation is "we definitely won't change the existing keyword but we'll consider adding a new one (such as $$description)", then does that mean I will be coming right back here to make the same proposal (with the minor change that it would propose addition vs modification)? Or is the expectation that it will be possible to fully resolve this proposal, even if it is accepted (whether as addition or modification), entirely through the slack conversation? I'm just trying to understand what I should be aiming to do in terms of navigating the process in the most efficient manner possible.

[handrews]

If you want to discuss things discuss them on slack.

[handrews]

you don't need ot write a big proposal just say hi and ask questions. GitHub is lousy for this kind of back and forth

[Relequestual]

We will not be modifying the existing keywords as you propose. This is why Handrews suggested you put your proposal here.

I don't mean to be negative. We welcome new ideas and proposals, but this isn't one we're going to be interested in.

[handrews]

Also, you can use slack on the web, you don't have to install the app. We have built a JSON Schema community here using various common infrastructure pieces. Showing up and saying "nope, I hate your tools, I won't go where the discussion is" means that you're rejecting that community and is not going to inspire anyone to work with you.

Looks like you deleted your last comment?

This has turned into a discussion of process, which is not useful in GitHub, and we are not going to implement the keyword change requested. I'm going to close this, it just doesn't seem like it's going anywhere.

You will still be welcome on slack should you choose to join us and learn more about how we work and what options might be available to achieve your goals.

[mewalig]

@handrews: I apologize in advance for taking more of your time but felt that your last comment needed a response.

Looks like you deleted your last comment?

The comment was mistakenly posted under the wrong account and had to be immediately deleted. I had to then get back to work and didn't have time to return until now.

Showing up and saying "nope, I hate your tools, I won't go where the discussion is" means that you're rejecting that community and is not going to inspire anyone to work with you

Here is the comment that was deleted due to having been erroneously posted under the wrong account, which as you can see is not at all saying "nope, I hate your tools":

thx. Might just let this one go, I've never been a slack user, not sure I want to start now, don't need this change in order to just implement our own variant of the standard and just thought it would be a helpful suggestion. but maybe will stop by later

Although this message was brief, it was not impolite, it was not rejecting, it was not "hating", and it was not conclusive about anything except for the immediate term. Throughout this entire discussion I have been sincere in my attempts to contribute to your community. I never needed to post the suggestion, which took up quite a bit of my time, and even if it was welcomed and accepted with open arms, I never stood to gain anything, other than the satisfaction of contributing something which I was trying to do in more ways than just suggestions, and I was willing (or at least about to be) to put $ on that (if you have access to do so you can verify that I registered a few days ago to be able to donate to your org), and as far as I'm concerned, inspiring others is less important than conveying ideas that can make your wares more valuable to the community (and while this idea seems so far to not be very interesting, I do know with 100% certainty that actual $ has been invested in developing and implementing the idea in actual business practice). All that said, we all place limits on ourselves in order to keep our lives in a manageable state, and one of my limits is that I hold back on new platforms unless/until a certain threshold is met, and that is not the case for slack. I hope you view this as you would an old relative who doesn't want to use Facetime and instead sticks to plain old phone calls (and hopefully his/her family does not take offense to that and we just live with the fact that he/she is missing out on some conversations).

Anyway, as I said before, I may stop by slack later, and I hope this helps to clarify what I was trying to do, however misplaced that attempt ended up being, which was simply to helpful within the practical limits of my time budget, which is now well overdrawn for the foreseeable future.

[Relequestual]

Text based chat sometimes gets confused and the meaning or intent is lost. I think this is such a case. I’m pretty sure neither of you intended to to upset or frustrate.

We try to avoid discussions on GitHub where possible and use slack in stead. Using slack or not is obviously your call, but that’s the place we discuss things.

In this instance, it isn’t something we are implementing. Of course you can make your own variant of the spec, but it’s not portable and you may encounter tooling issues.

At any rate, I certainly wouldn’t wait around for this change, which won’t happen.

Best of luck.

[mewalig]

Thank you @Relequestual, I appreciate your explanation.