swagger-js: A $ref needs to be wrapped inside a schema which is not according to spec.

This is a followup to https://github.com/swagger-api/swagger-ui/issues/1228

I have

 "Person" : {
         "type" : "object",
         "title" : "Information about a person",
         "properties" : {
            "externalId1" : {
               "title" : "first",
               "type" : "object",
               "$ref" : "#/definitions/map1"
            }

which does not work. The answer was to wrap it inside a “schema” and then it works:

"externalId1" : {
               "title" : "first",
               "type" : "object",
               "schema": {  // < -------------- This will make it work like you expect
                    "$ref" : "#/definitions/map1"
                } // ------------------- :)
            },

However, after looking into the spec of both swagger and JSON schema, there is no reference anywhere the “schema” wrapper is required.

As far as I can tell, my version without the “schema” wrapper is correct.

The example here https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#simple-model does not use the “schema” wrapper.

Am I missing something?

About this issue

Original URL
State: closed
Created 9 years ago
Comments: 21 (11 by maintainers)

Most upvoted comments

Ok, I thought the description is used to describe the field (externalId1 and externalId2 in this case). If the description must be on the referenced object, then you can not have a different description if you have multple references to the same object?

So something like:

"properties" : {
            "externalId1" : {
                "$ref" : "#/definitions/map1",
                "description": "This is the ID for the first thing."
            },
            "externalId3" : {
                "$ref" : "#/definitions/map1",
                "description": "This is the ID for the third thing."
            },

is not correct and not otherwise possible?

x12a1f on May 4, 2015

Okay, just wanted to make sure.

This how "Person" should be defined:

{
  "type": "object",
  "title": "Information about a person",
  "properties": {
    "externalId1": {
      "$ref": "#/definitions/map1"
    },
    "externalId2": {
      "title": "second",
      "type": "array",
      "items": {
        "$ref": "#/definitions/map2"
      }
    }
  }
}

webron on May 4, 2015

You add anything when there’s $ref. This is a restriction of JSON Reference.

webron on May 4, 2015