$ref traps - sgpinkus/json-schema GitHub Wiki

NOTE: This information has been migrated to https://github.com/json-schema-org/json-schema-org.github.io/issues/24

If you implement JSON Reference support in your JSON Schema implementation, all points below should be considered carefully.

Some of these points are already mentioned by the JSON Reference draft, so if you have read the draft already, this may not be news to you.

This can of course happen. For the most obvious protocol out there, http, you may encounter a 404, for instance. Or the URI scheme may not be supported.

It should be noted that the draft does not dictate a specific implementation behavior in this kind of situation. Some implementations may choose to fail, others may not.

It can happen that you have this reference to resolve:

{
    "$ref": "http://one.site/oneschema.json#"
}

and when you resolve that reference, you have yet another JSON reference:

{
    "$ref": "otherschema.json#"
}

In this case, you MUST also resolve that reference, and so on, until you fetch content which is not a JSON Reference.

Consider this example:

{
    "a": { "$ref": "#/b" },
    "b": { "$ref": "#/a" }
}

Clearly, an infinite loop may arise. Implementations must detect loops in a chain of references being resolved and raise an exception.

Consider this example:

{
    "a": { "milk": "cow", "eggs": "bird" },
    "b": { "$ref": "#/a" },
    "c": { "$ref": "#/b/milk" }
}

(todo: is this situation resolvable in all cases?? Someone provide an algorithm.)

A JSON reference is only a URI, and if you happen to be able to dereference that URI, the content type is undefined.

Which means, you may get a valid JSON document which is not a schema. For instance:

3

Or you may get something which is not even JSON:

Hello!