$ref vs title/description

[Andreas Kohn]

Hi,

We're looking into JSON Schema to describe our data structures used in our APIs and internally. As part of that I started having a library of "core types", such as "list of user ids", and refer to them in different contexts, for example "list of members of this discussion group". What I'm not sure about is how to apply "title"/"description" in this case: these are context-dependent, even though the underlying type is the same.

Is "title"/"description" attached to the type, and I need to do something like 

{
  "type": "object",
  "properties": {
    "members": {
      "allOf": [
        { "$ref": "..../user-id-list" },
        { "description": "List of members of this discussion group" }
      ]
    }
  }
}

Or is it correct to use this form: 

{
  "type": "object",
  "properties": {
    "members": {
      "$ref": "..../user-id-list",
      "description": "List of members of this discussion group" }
    }
}

(According to http://jsonschemalint.com/draft4/# both validate).

Regards,

--

Andreas

[Ivan Goncharov]

According to http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03

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

That mean you can't use second form.

[Andreas Kohn]

Hi Ivan,

Thanks for that, indeed this would mean my second form is invalid (and I guess the jsonschemalint site should mark it as such :D). 

Using the first form unfortunately means that processing the schema gets a bit harder: I fear that resolving the allOf/$ref first would lead to me losing the rich type information, which we also want to retain, as the consumer of the schema knows some of the types such as 'user-id-list', and treats them specially.

Back to the drawing board :)

Thanks & Regards,

--

Andreas

[xmlbuddy]

Just FYI, one of the most popular and standard compliant JSON schema validators (https://github.com/fge/json-schema-validator) also accepts your second format successfully.

In addition, usually if the sepcification says "shall be ignored" the validators are really simply ignoring other members/content.

Regards

Clemens

[Ivan Goncharov]

I actually submit PR to enable validation of JSON Pointers: https://github.com/json-schema/json-schema/pull/162

Maybe it will get it's way into Draft 5.

[Ivan Goncharov]

>>>Using the first form unfortunately means that processing the schema gets a bit harder: I fear that resolving the allOf/$ref first would lead to me losing the rich type information, which we also want to retain, as the consumer of the schema knows some of the types such as 'user-id-list', and treats them specially.

You can try to use "id" field. It have little bit misleading name because it's main purpose is to alter scope resolution, see:

http://json-schema.org/latest/json-schema-core.html#anchor29

But you can try to use it as unique ID field.