null type: add language specific info for YAML

[stefan-wenig]

when specifying the schema in yaml, the null type must be quoted as in { type: "null" }. otherwise the type property will have no value instead of "null".

(specifiying null leads to a formally valid schema, but all kinds of confusing validation errors, especially in complex scenarios such as schema extension.)

this is not the case for any other type AFAIK.

https://github.com/json-schema-org/understanding-json-schema/blob/main/source/reference/null.rst

[gregsdennis]

specifiying null leads to a formally valid schema

Are you saying that

type: null

is a valid schema? It's not. type can only be a string or array of strings, specifically those strings MUST be one of the predefined type values.

Having the null in quotes is also required in JSON.

{ "type": null }

is also invalid. (It's equivalent to the YAML above.)

What's the ask here?

[stefan-wenig]

Let me clarify:

type: string
type: object

etc. are all valid JSON schema declaration in YAML syntax. And that's how it's usually done, it's quite uncommon to quote identifiers in YAML. However,

type: null 

has the unexpected result of a property with type == null, as null is one of the very few keywords in YAML. You need to type

type: "null"

Obvious if you think about it, but easy to make the mistake. It is valid YAML and for some reason seems to be valid JSON schema too, but not what you'd expect and therefore kinda hard to identify the problem. Especially when you're getting unexpected validation results in more complex scenarios. I think a hint could really help!

[gregsdennis]

This is just how JSON and YAML work, though. There's nothing we can do as JSON Schema.

type requires a string. One of the valid strings is "null". If you try to do "type": null, you should get an error from the implementation/editor saying the schema is invalid. If you don't then it's an issue with the implementation/editor, not the specs, which is what we control.

[stefan-wenig]

Understood, but I'm not asking for an error, just suggesting a "language-specific info" hint for YAML.

[gregsdennis]

Are you asking for a spec change, or something in docs, or in an editor somewhere? Where would you like this hint?

JSON Schema doesn't care about the textual format in which the data is encoded. We care about the data model. Therefore, any encoding issues are beyond the scope of the spec.

[stefan-wenig]

I thought the link I provided would be a good place, along with the Ruby and Python hints. I realize that's not quite the same category, and I'm not gonna argue formalities here. Just think it'd be helpful.

[gregsdennis]

That page is taking about the difference between instance data being null vs absent.

[stefan-wenig]

It does mention that, but generally it's just the reference page for the null data type.

[Relequestual]

I don't know where the right place for this would be without looking, but I think adding such a note somewhere wouldn't hurt.

[Relequestual]

However, we shouldn't be documenting all the oddities and rules for pre-processors that compile to JSON. I don't think such belongs in reference documentation (which is what this repo is). But you might find it fits for another page at some later date with other YAML specific considerations... more general documentation.

[github-actions[bot]]

Hello! :wave:

This issue has been automatically marked as stale due to inactivity :sleeping:

It will be closed in 180 days if no further activity occurs. To keep it active, please add a comment with more details.

There can be many reasons why a specific issue has no activity. The most probable cause is a lack of time, not a lack of interest.

Let us figure out together how to push this issue forward. Connect with us through our slack channel : https://json-schema.org/slack

Thank you for your patience :heart:

[github-actions[bot]]

This issue did not get any activity in the past 180 days and thus has been closed. Please check if the main branch has fixed it. Please, create a new issue if the issue is not fixed.