Need a human friendly multi-line "description" in json-schemas

[darshakthakore]

I'm opening this one here to continue the discussion in #226 from the old repo.
Basically the "request" is that there should be some mechanism that somewhat acts as jsondoc for elements being defined in json-schema, mainly useful in cases where enums and tuple arrays are being defined. The current "description" property is a string only, can it be made into either a string or a string array so that it can be multi-line. This would help in cases where the json-schemas are being used for modeling and are consumed equally by humans and machines.

[awwright]

JSON usually represents newlines with the \n sequence, I'm not sure how wise it would be to add a new construct for the sole purpose of overcoming this limitation in the format.

[handrews]

I'll throw in again in favor of humans writing schemas in YAML and producing JSON as a build step to be consumed by machines (most YAML/JSON parsers have some sort of hook you can use to preserve ordering if you want the JSON to look like the YAML for human readability).

[Relequestual]

What do you want beyond using \n for newline? Would you want the fact that \n is available for new line to be part of the specification?

[erosb]

I would also advice using YAML instead of complicating the schema spec.

[Relequestual]

@erosb right. sure. I'm not familiar with the specifics of converting YAML to JSON. Are you saying you can create YAML, you can do so with line breaks, and it will convert to single strings with \n ?

[handrews]

@Relequestual YAML has formats for both "folded" block text (where it removes all newlines, so you can write long strings wrapped to be easier for humans to read in source) or "literal" block text (where you can wrap it and it preserves newlines). Both forms strip off uniform indentation and have various chomping options for terminal newlines, trailing blank lines, etc.

So the folded form would just be a long string in JSON, while the literal form would be a long string with embedded \n newline characters.

[erosb]

I'm not familiar with the specifics of converting YAML to JSON

You can think about YAML as a different "dialect" of JSON. They differ only in lexical elements, but they represent the same structure, so there is a 1:1 mapping between YAML and JSON.

[handrews]

there is a 1:1 mapping between YAML and JSON

Not quite- YAML can be used to instantiate specific types or classes when it is loaded, while JSON has no syntax to do so. An obvious difference is that YAML can specify an ordered map with !!omap or an unordered set with !!set, neither of which can be done in JSON.

[awwright]

As long as it can represent the full object model defined in JSON Schema, and people don't use more than that, I don't see a problem.

Using a more generic Javascript syntax (allowing unquoted keys and trailing commas) is also common.

[handrews]

As long as it can represent the full object model defined in JSON Schema, and people don't use more than that, I don't see a problem.

I see it as totally outside the scope of JSON Schema. To take an extreme example, if you've got a prose format that you can somehow read in and spit out valid JSON Schema in JSON, the JSON Schema specification doesn't care one way or the other. If a specific implementation wants to directly read (YAML, JavaScript, mythical prose format) and support it without explicitly producing JSON first, that's an implementation detail and not addressed by the spec one way or the other.

The only thing the spec requires is that if you want something to be recognized in an implementation-independent way as JSON Schema in a hypermedia system, it must be served as application/schema+json, so documents in those situations MUST be JSON.

[Relequestual]

(@erosb I'm semi familiar with YAML (I really like RAML), but I haven't used it much.)

I mostly agree with @handrews on this. http://json.org defines \n is new line character in string. Therefore the description field already supports multi line content because it is json.

If you're wanting to view the json in json format with line breaks, then no, json doesn't support that, and you'll need to use a text editor that can wrap text. I see this as a non issue and should be closed.

[handrews]

I see this as a non issue and should be closed.

Agreed, JSON's shortcomings are an issue to be raised with the JSON people (good luck), and are not problems we can fix here. At most we could add a note that other forms such as YAML may be easier for humans to use for working with schemas, but are outside of the formal standard.

[handrews]

@Relequestual , @awwright , @darshakthakore , it looks like this should be closed as out of scope for JSON Schema.

[awwright]

It's only 8 days old, let's wait for @darshakthakore to give an opinion

[handrews]

It's only 8 days old, let's wait for @darshakthakore to give an opinion

er... good point. Sorry, it's been a long week and I didn't realize it was that recent somehow.