Changes to the Example Object

[webron]

1. The name should be changed from "example" to "examples" (it can hold any number of examples), and the references to it should be fixed as well.
2. Shouldn't the definition of the example itself be a reference to "schema"? https://github.com/reverb/swagger-spec/blob/master/schemas/v2.0/schema.json#L92

[webron]

Okay, regarding the second point, I now realize it shouldn't be "schema" but it also shouldn't be left empty. I think the definition should be as such:

    "example": {
      "type": "object",
      "patternProperties": {
        "^[a-z0-9-]+/[a-z0-9-+]+$": { "type" : "string"}
      },
      "additionalProperties": false
    }

and also, this sample - https://github.com/reverb/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithExamplePayload.json - is wrong.

The examples part should look like this:

"examples": {
  "application/json": "{
    \"id\": 9,
    \"category\": {
      \"name\": \"domestic\"
    },
    \"name\": \"monster\",
    \"tags\": [
      {
        \"name\": \"for sale\"
      }
    ],
    \"status\": \"alive\"
  }"
}

Yes, it is very ugly, but I think there's no escape from doing that. The sample assumes this is an application/json content type, but if it's application/xml, it would have to be a string. For tooling support, I don't think we should have one property with a json structure as a value, and another with a string.

I imagine the equivalent xml example would look like:

"examples": {
  "application/json": "
    <pet>
        <id>9</id>
        <category name=\"domestic\"/>
        <name>monster</name>
        <tags>
            <tag name=\"for sale\"/>
        </tags>
        <status>alive</status>
    </pet>
  "
}

[webron]

We've decided to leave it intact, at least for this version.