Can You Define a Response Consisting of an Array With Two Different Objects?

[BostonKevin]

Hi!

It is easy to define a response that consists of an array made up of several objects.  Is it possible to define a response consisting of two separate objects?

When I have attempted to do this in Swagger Editor, the message

duplicated mapping key

appears.

Thanks!

[HKosova]

Hi Kevin, can you please post your YAML that causes the error?

[BostonKevin]

Helen,

Gladly. Here it is:

      "inline_response_GET_XXX": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "content_status": {
                  "type": "string",
                  "description": "There are several values that may appear here.",
                  "example": "captured."
                },
                "content_url": {
                  "type": "string",
                  "description": "The URL of the node.",
                  "example": "https://www.massis.com/aboutus.html"
                },
                "content_url_hash": {
                  "type": "string",
                  "description": "The hash of the URL of the node.",
                  "example": 4467086592462243000
                },
                "context_url": {
                  "type": "string",
                  "description": "The URL of the node from which the node was spidered.",
                  "example": "www.massis.com"
                },
                "total_num_blocks": {
                  "type": "integer",
                  "description": "The total number of blocks in this node.",
                  "example": 4
                },
                "total_num_words": {
                  "type": "integer",
                  "description": "The total number of words in this node.",
                  "example": 4
                }            
            },

              "type": "object",
              "properties": {
                "label": {
                  "type": "string",
                  "description": "A label for the node.",
                  "example": "aboutus.html"
                },
                "my_num_blocks": {
                  "type": "integer",
                  "description": "The number of blocks in this node.",
                  "example": 4
                },
                "my_num_words": {
                  "type": "integer",
                  "description": "The number of words in this node.",
                  "example": 4
                },

            },

          },
          "total_word_count": {
            "type": "integer",
            "description": "The total number of words spidered on this node. This value includes words captured on child nodes.",
            "example": 34
          }
        }
      },

The duplicated mapping key error shows up at the third

              "type": "object",

Perhaps Swagger thinks that I am trying to create a multi-dimensional array?

Thanks,

Kevin

[HKosova]

From what I understand, the "data" array in the actual JSON should look like this:

  "data": [
    {
      "content_status": "captured.",
      "content_url": "https://www.massis.com/aboutus.html",
      "content_url_hash": "4467086592462243000",
      "context_url": "www.massis.com",
      "total_num_blocks": 4,
      "total_num_words": 4
    },
    {
      "label": "aboutus.html",
      "my_num_blocks": 4,
      "my_num_words": 4
    }
  ],

An array of different objects can be defined in OpenAPI 3.0 ("openapi": "3.0.0") using the oneOf keyword:

{
  "openapi": "3.0.0",
  ...

  "components": {
    "schemas": {
      "inline_response_GET_XXX": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "oneOf": [
                { "$ref": "#/components/schemas/Schema1" },
                { "$ref": "#/components/schemas/Schema2" }
              ]
            }
          },
          "total_word_count": {
            "type": "integer",
            "description": "The total number of words spidered on this node. This value includes words captured on child nodes.",
            "example": 34
          }
        }
      },

      "Schema1": {
        "type": "object",
        "properties": {
          "content_status": {
            "type": "string",
            "description": "There are several values that may appear here.",
            "example": "captured."
          },
          "content_url": {
            "type": "string",
            "description": "The URL of the node.",
            "example": "https://www.massis.com/aboutus.html"
          },
          "content_url_hash": {
            "type": "string",
            "description": "The hash of the URL of the node.",
            "example": "4467086592462243000"
          },
          "context_url": {
            "type": "string",
            "description": "The URL of the node from which the node was spidered.",
            "example": "www.massis.com"
          },
          "total_num_blocks": {
            "type": "integer",
            "description": "The total number of blocks in this node.",
            "example": 4
          },
          "total_num_words": {
            "type": "integer",
            "description": "The total number of words in this node.",
            "example": 4
          }
        }
      },

      "Schema2": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "A label for the node.",
            "example": "aboutus.html"
          },
          "my_num_blocks": {
            "type": "integer",
            "description": "The number of blocks in this node.",
            "example": 4
          },
          "my_num_words": {
            "type": "integer",
            "description": "The number of words in this node.",
            "example": 4
          }
        }
      }
    }
  }

}

If you use OpenAPI 2.0 ("swagger": "2.0") it doesn't support oneOf, but as a workaround you can use a single object schema containing properties of both objects (i.e. content_status, content_url, ..., label, my_num_blocks, ...) where all properties as optional.

[BostonKevin]

Hi!

Thanks for your help but the problem is that it is not that the response can be one or the other.  Data is packed into two distinct objects that are in the same array. For the sack of clarity, I am referring to Schema1 and Schema2.

It might be best to return two different arrays with one array containing the Schema1 objects and the other array containing the Schema2 objects.  I will investigate.

Best,

Kevin

[HKosova · Accepted solution]

---

@BostonKevin wrote:

Data is packed into two distinct objects that are in the same array.

---

That's exactly how the first example with oneOf works.

"type": "array",
"items": {
  "oneOf": [
    { "$ref": "#/components/schemas/Schema1" },
    { "$ref": "#/components/schemas/Schema2" }
  ]
}

means that the array contains Schema1 and/or Schema2.

[BostonKevin]

Just to be clear, the oneOf directive does NOT work like an exclusive OR (EOR).  It specifies that any member of an array can have the structure defined in either Schema1 or Schema2, correct? 

[HKosova · Accepted solution]

Correct.

[BostonKevin]

That is a very useful feature.

[swaggerUser]

Hi All,

I have a similar issue where I need to define an array with two separate objects in swagger 2.0. Do you have any suggestions on how to implement this in 2.0 ?