Not validating swagger-spec's examples

[maxlinc]

I created OAI/OpenAPI-Specification#267, but I'm not sure if the issue is with the example or the validator. The validator changed more recently, so it's either catching errors that previously went unnoticed or there's a bug in how it handles refs:

Several of the examples in the https://github.com/swagger-api/swagger-spec are not valid according to swagger-tools:

For example, the uber.yaml example shows these errors in via swagger-tools or the editor:

$ swagger-tools validate examples/v2.0/yaml/uber.yaml

API Errors:

  #/definitions/Activities/properties/history: Missing required property: items
  #/paths/~1products/get/responses/200/schema/items/$ref: Not a valid JSON Reference
  #/paths/~1products/get/responses/default/schema/$ref: Not a valid JSON Reference
  #/paths/~1estimates~1price/get/responses/200/schema/items/$ref: Not a valid JSON Reference
  #/paths/~1estimates~1price/get/responses/default/schema/$ref: Not a valid JSON Reference
  #/paths/~1estimates~1time/get/responses/200/schema/items/$ref: Not a valid JSON Reference
  #/paths/~1estimates~1time/get/responses/default/schema/$ref: Not a valid JSON Reference
  #/paths/~1me/get/responses/200/schema/$ref: Not a valid JSON Reference
  #/paths/~1me/get/responses/default/schema/$ref: Not a valid JSON Reference
  #/paths/~1history/get/responses/200/schema/$ref: Not a valid JSON Reference
  #/paths/~1history/get/responses/default/schema/$ref: Not a valid JSON Reference
  #/definitions/Activities/properties/history/$ref: Not a valid JSON Reference

API Warnings:

  #/definitions/Product: Definition is defined but is not used: #/definitions/Product
  #/definitions/PriceEstimate: Definition is defined but is not used: #/definitions/PriceEstimate
  #/definitions/Profile: Definition is defined but is not used: #/definitions/Profile
  #/definitions/Activity: Definition is defined but is not used: #/definitions/Activity
  #/definitions/Activities: Definition is defined but is not used: #/definitions/Activities
  #/definitions/Error: Definition is defined but is not used: #/definitions/Error

12 errors and 6 warnings

[whitlockjc]

The examples are wrong. :) I see only two errors:

• Missing required property items: All items of type array MUST have an items property but for some reason, the JSON Schema doesn't enforce it. There is an open bug: Schema does not enforce requirement of array items object OAI/OpenAPI-Specification#174
• Not a valid JSON Reference: Swagger 2.0 DOES NOT support shorthand references anymore. So no more "$ref": "SomeModelId", you have to use "$ref": "#/definitions/SomeModelId".

The warnings are accurate as well. In the 2.0 Specification, both of these are mentioned in one place or another.