$ref issues about docson

[McFoggy]

In order to ease tests, I have pushed a running demo application at: http://blog.matthieu.brouillard.fr/docson-reference-demo/app/

Thanks for any help.

[rom1504]

I'm currently having I think the same issue : this schema doesn't work with docson.

Did you find any way to fix it @McFoggy ?

[McFoggy]

not at all but I admit that I had to switch to another topic meanwhile. If you find something, please post a comment.

[rom1504]

alright I fixed it in #35 @McFoggy

demo that it works there http://prismarinejs.github.io/minecraft-data/?d=protocol

[cneijenhuis]

@McFoggy are you sure only a $ref is a valid schema? I'd say no, because a schema needs to contain $schema at the root. Also, $ref must be the only field in the object, so you can't create something like this:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "$ref": "..."
}

I can think of only one hack to create a schema that exists only of a reference:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "oneOf": [{"$ref": "..."}]
}

It basically says: This is a schema. It must contain at least one of the following elements. Since there is only one element, it must contain that one. 😐
You could also use anyOf or allOf, they all have the same semantic when the list only contains one element.

It's an ugly hack, and Docson will render the oneOf. I'm facing similar issues when working with $ref...

[cneijenhuis]

@rom1504 What are you trying to achieve with this: "type": {"$ref": "..."}?

It is not a valid schema, according to the spec:

The value of this keyword type MUST be either a string or an array. If it is an array, elements of the array MUST be strings and MUST be unique.

String values MUST be one of the seven primitive types defined by the core specification. 

http://json-schema.org/latest/json-schema-validation.html#anchor79

Probably the hack I described above should work for your use case as well, but it's not pretty... 😞

[rom1504]

@cneijenhuis Yeah you're right, the "type": {"$ref": "..."} doesn't seem valid (https://www.npmjs.com/package/jsonschema has no problem with it though...)

Why does the $ref have to be the only field in the object ? I can't find this in the reference, and http://jsonschemalint.com/draft4/ says it's valid to have

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "$ref": "..."
}

[McFoggy]

@cneijenhuis I do not find in the spec the fact that $schema is mandatory. Explicitly at the pointer you mention it is written: It is _RECOMMENDED_ that schema authors include this keyword in their schemas..

Also the schema-core itself doesn't defined any required attribute.

But you are right that on the other hand I am not even sure that a schema with only a $ref is valid.

[rom1504]

I believe a schema with only a $ref is valid. Docson even has a test for this https://github.com/lbovet/docson/blob/master/tests/ref.json#L113 which is still broken but for different reasons now. (edit: I just fixed that too)

I removed the type thing that was indeed wrong in my PR and added a regression test https://github.com/lbovet/docson/pull/35/files#diff-e039c6140a632eef1d13cd1ceba8bb12R160 that doesn't work with master code, but works with my PR (#35)

[cneijenhuis]

@rom1504 The References are defined in another draft, there it says:

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

• http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3

So, yeah, it's not an invalid Reference-object but $schema would be ignored... Therefore it doesn't make a difference whether you add $schema or not.

@McFoggy You are right. I understood this sentence wrong: This keyword MUST be located at the root of a JSON Schema. I understood it as in "You must include the keyword at the root". But it probably means "If you include the keyword, it must be located at the root".

[cneijenhuis]

@rom1504 Okay, after re-reading I guess a schema with only $ref is valid, although it feels strange.

I still think this: https://github.com/lbovet/docson/blob/master/tests/ref.json#L113 is not what it intends to be. According to the JSON Reference draft, you need to ignore the other fields (in this case definitions).

There is also a good reason for this, because if you don't ignore other fields, you end up with conflicts. Say you have two schemas:

(foo.schema.json)
{
  "type" : "object" 
}

(bar.schema.json)
{
  "type" : "string",
  "$ref" : "foo.schema.json"
}

Then you need to ignore "type" : "string" in bar.schema.json to end up with something valid.

[rom1504]

Yeah I guess you are right, the spec does say every other members should be ignored.

I guess it makes some kind of sense, I'll change my PR to ignore all other members.

[artem-korolev]

have no time to get into this thread, but I created one pull request that is trying to solve one of the problem with $ref. check it please - #47

[yanick]

I'm fairly sure this issue is now resolved. I'll close it. If I'm wrong and the issue is still not vanquished, please let me know.