Document supported JSON Schema versions

[sdirix]

It would be very helpful if you could document in the README or on the API website which versions of JSON Schema are supported. For example draft-04, draft-06 and draft-07.

[JamesMessinger]

In retrospect, I now realize that "JSON-Schema-Ref-Parser" was a poor name choice for this library. It doesn't actually support any version of JSON Schema, and it's not intended to.

This library is an implementation of the JSON Reference and JSON Pointer specs, not the JSON Schema spec. The three specs are all very closely related to each other, and are very often used together, which causes people to think of all three as a single spec, but that's not actually the case.

[sdirix]

Hi @JamesMessinger, thanks for the quick answer! I wasn't aware that JSON Schema $Ref Parser handles JSON Reference and JSON Pointer exclusively and just assumed (because of the name) that it would handle JSON Schema specialties like $id too. I now found #97, so I understand where you are coming from. In the spirit of the original request I would like to suggest to more clearly describe what the library does and doesn't do in the README and the documentation website to avoid any potential confusions in the future.

The reason I was asking in the first place was because I'm using Json Schema $Ref Parser in combination with Typescript and the typings indicate that the library only supports JSON Schema 4 and 6.

[handrews]

@JamesMessinger as a heads up, the next draft of JSON Schema (which we will have published soon... really... within a month... probably... I hope... it's been a long year 🤕 ) changes the behavior of $ref slightly in the context of JSON Schema.

Specifically, adjacent keywords are no longer ignored, so given the following (note that $defs is now recommended in place of definitions, although definitions is still valid since as a keyword it doesn't exactly do anything):

{
    "type": "object",
    "properties": {
        "foo": {
            "title": "Foo",
            "maximum": 100,
            "$ref": {"#/$defs/foo"}
        }
    },
    "$defs": {
        "foo": {
            "type": "integer",
            "minimum": 0
        }
    }
}

the appropriate dereferenced version is:

{
    "type": "object",
    "properties": {
        "foo": {
            "title": "Foo",
            "maximum": 100,
            "allOf": [
                {
                    "type": "integer",
                    "minimum": 0
                }
            ]
        }
    }
}

If there had already been an allOf present adjacent to $ref, then to "dereference" the $ref, its target schema's contents would be appended as another subschema in that allOf's array.

I actually came here to file an issue specifically on this and then noticed that this issue is relevant. I can also file it separately if preferred.

[philsturgeon]

I dont think a dereference should be rewriting your Schemas with an allOf like that, but there are plans to get this library replaced with something a little more true to JSON Schema than this current implementation. I'll close this one down and you should get some information about the new libs through deprecation warnings if/when this happens. Thanks!