Advertise use of markdown inside descriptions

[ssbarnea]

Many JSON Schemas make use of markdown inside their description fields as this is extremely useful for IDEs.

One notable example is vscode which uses the alternative markdownDescription field for that purpose. Still, almost nobody populates both fields, so the idea of having a different field name proves to be less than ideal.

That is why I want to propose a top level property such hasMarkdown: true that we can set at schema level that declares that descriptions and maybe other fields are using markdown.

Keep in mind that markdown is still valid as text so there is no major problem if a dump program would display description as plaintext when in fact it is markdown.

[gregsdennis]

This proposal is merely an annotation that describes the content of a known keyword. Since 2020-12, this will automatically be collected as an annotation since that's the prescribed behavior for all unknown keywords.

I think this actually raises a larger question about extension vocabs that contain annotation-only keywords.

[Relequestual]

There have been discussions about removing the ability in the future to support unknown keywords. I haven't looked into the arguments, but it feels sensible and plausible we could do that.

[handrews]

@Relequestual it's not so much "remove unknown keywords" as it is "require declaring a vocabulary for all keywords". However, the ability to set a vocabulary to false in $vocabulary essentially preserves the "unknown keywords" functionality, because it means that you can include an unknown vocabulary and (as is already the case) its keywords are treated the way unknown non-vocabulary keywords are treated.

There are some subtleties around this change, but I suspect some variation of it is likely. The reason, as awwright pointed out in the last community call, is that allowing arbitrary keywords outside of any namespace (and vocabularies are, among other things, namespaces) makes it impossible to have a useful forward compatibility strategy in JSON Schema. Shifting to allowing unknown vocabularies (which we already do, if they are set to false) instead of arbitrary unknown keywords ensures that everything is namespaced.