Can a schema document just be a "$ref"?

[handrews]

In IRC with @awwright (and related to #167) the question came up as to whether a single JSON reference is a valid schema document. Currently, it is allowed for any subschema but not mentioned for the root schema.

I am in favor of allowing it as a root schema as it doesn't increase the chances of circular references all that much and I can see a situation where an ecosystem of schemas may end up with a schema that degenerates into a reference to a larger packaged schema definition.

[Relequestual]

...I can see a situation where an ecosystem of schemas may end up with a schema that degenerates into a reference to a larger packaged schema definition.

@handrews Would you be able to elaborate how you see this might happen? (In as tarse means as possible). It doesn't sound unreasonable, but I'm not clear on the use case.

[handrews]

@Relequestual Let's say you have a schema documents A and B that declare complex data types, where B is something like {"allOf": [{"$ref": A}, {"maxItems": 10}]} (basically, A with some small modification). You have a bunch of resources in an API that use A and/or B. A and B are logically used for rather different things, even though the schemas are nearly identical.

As time goes on, the limitation for B that it could only support 10 items is removed. So its schema is now just {"$ref": A}. The reason to do that and not just change all references to B to references to A and eliminate B entirely is that, as noted, A and B are logically different despite similar syntax. In the future, you may need to make a change to B that does not affect A. So it needs to stay a separate type even though it is (currently) identical to A.

So that's how you might have a schema that starts separate, degenerates to a plain ref, and then becomes separate again.

[handrews]

This issue is addressed by PR #194.

[awwright]

In #194 I stated my opinion it probably makes sense if $ref is allowed anywhere a schema is.

A use case would be that a third party is asked to provide a schema to validate instances against. For instance, filtering a list of JSON documents. In this case, they will frequently want to use the true or false shortcuts, they may likewise want to simply reference an existing schema. If $ref can only be used as a subschema, it would force seemingly arbitrary usage of {allOf:[{$ref:""}]}

[handrews]

OK so everyone agrees that as of right now without throwing in new proposals and alternatives this should be true ("$ref" should be allowed at the root), the spec as currently written allows it, and PR #194 does implement this.

Numerous further changes, such as changing how we treat other fields in an object with "$ref", or dropping "$ref" entirely in favor of just using URI strings without an object to wrap them, but those can and should be debated separately.

Can we PLEASE just merge in #194 and open new issues for all the other mutually incompatible ideas floating around for "$ref"?

[epoberezkin]

@handrews @awwright @Relequestual I completely agree with this issue, $ref should be a valid schema on its own. But I don't think #194 should be merged - see my comment there: #194 (comment).

[handrews]

@awwright @Relequestual after much discussion, I've closed #194 and endorsed @epoberezkin's #211 in its place.

[handrews]

Resolved by #211.