Defining an associative array

[Ynk33]

Hello all,

How can I define a property which would look like this : ["foo" =>"bar"] ?
Or even better, which would look like this : ["foo"=>["bar1","bar2"]] ?

I tried to look inside the spec or the issues, but I didn't find anything about this...

Thanks for your help

[JamesMessinger]

If I understand correctly, you're just trying to define an object with named properties, right? So something like this:

type: object
properties:
    foo:
        type: string
        example: "bar"
    fooArray:
        type: array
        items:
            type: string
        example: ["bar1", "bar2"]

You can find more examples at json-schema.org

[Ynk33]

It's not exactly that. In your example, the property must contain a foo which is a string, and a fooArray which is an array of string. And this property cannot contain anything else than that.
In my case, there could be as many of "foo" as the user want to add.

To be more concrete, I have an item which can have a name and a description in any language :

item1.translations = array(
  "en" => array(
    "name" => "item1",
    "description" => "this is item 1"
  ),
  "fr" => array(
    "name" => "objet1"
    "description" => "voici objet 1"
  )
)

And the number of languages can be different depending on the item. Maybe item2 will have a translation in spanish, and maybe item3 will not be translated in french.

[webron]

I'd start with how you'd expect it to be displayed in JSON (assuming that's your modeling form) and we can continue from there.

[Ynk33]

Maybe something like this :

{
  "name": "myArray",
  "type": "array",
  "items": {
    "key": {
      "type": "string"
    },
    "type": "array",
    "items": {
        "key": {
          "type": "string"
        },
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

[webron]

That definition is inaccurate with regards to what's valid within the spec, but I believe there's a possible proper definition. If you can show me a sample JSON of actual object (not its schema), then I could help you write a proper schema for it.

[Ynk33]

The PHP example with the translations is exactly what I need. I do not use JSON to modelize my object, but I guess it would look like this :

{
  "id": "item1",
  "translations": [
    {
      "lang": "en",
      "name": "item",
      "description": "a wonderful item"
    },
    {
      "lang": "fr",
      "name": "objet",
      "description": "un objet merveilleux"
    }
  ]
}

I can see exactly how to modelize this with Swagger, but this schema lose the "key => value" principle.
And as my API expects PHP data, if I test my API in Swagger-UI with this schema, it won't work.

[webron]

Your REST API expects PHP data? There's no clear way to define that with Swagger as that's not really a standard form of transferring data between client/servers. As such, there's no way to have the => integrated in the model.

However, if you do want to add support for JSON as a more common data structure, I'd be more than happy to assist in modeling it for the use with your API.

[yanjost]

Another related case : how can I define an input parameter (query or formData) which is an associative array ?

For example, in the "pet store" example, I could add a new operation "find" where I could pass an arbitrary number of criteria.

For example, if I'm searching for an available "Beagle" dog, the HTTP request would be the following

Text version of the parameters

criteria[status]: available
criteria[tags]: dog,beagle

POST /pet/find HTTP/1.1
Host: petstore.com
Content-Type: application/x-www-form-urlencoded

criteria%5Bstatus%5D=available&criteria%5Btags%5D=dog%2Cbeagle

[webron]

@yanjost - it's just an array of strings, possibly restricted by enums.

        name: criteria[tags]
        in: formData
        type: string
        enum: [ dog, beagle ]

[webron]

Closing this issue due to lack of activity. Please reopen if needed.

[yanjost]

My example was simplified, maybe too much. Let me be more precise.

Imagine that you can send multiple "find" requests in one. For that, you pass an array of associative arrays, which contain a list of integers (yes, that's what I'm dealing with here...)

Text version:

criteria[0][status]: 1
criteria[0][tags]: 2,3
criteria[1][status]: 2
criteria[1][tags]: 4,5

POST /find HTTP/1.1
Host: petstore.com
Content-Type: application/x-www-form-urlencoded

criteria%5B0%5D%5Bstatus%5D=1&criteria%5B0%5D%5Btags%5D=2%2C3&criteria%5B1%5D%5Bstatus%5D=2&criteria%5B1%5D%5Btags%5D=4%2C5

How would you define that ?

[webron]

Right, the only way to do that is to explicitly document all options (which I agree is cumbersome and in some cases impossible). You can't add 'logic' to the naming convention of the parameters.

There's #367 which remotely reminds it and I was sure we had another feature request for it. If this is important for you, you can either add a comment there or open a more specific issue on it.

[yanjost]

Added #380 for this specific issue