Provide better error messages for `oneOf` schema validation failures

This Swagger Spec has a “body” parameter that is missing the required “schema” property:

---
swagger: "2.0"
info:
  description: "Tax Blaster"
  version: "1.0.0"
  title: "TaxBlaster"
host: "taxblaster.com"
basePath: "/api"
tags:
- name: "TaxFilingObject"
  description: "An individual Tax Filing record, accessed by its ID"
schemes:
- "http"
parameters:
  idParam:
    name: "id"
    in: "path"
    description: "filingID of the requested TaxFiling"
    required: true
    type: "string"
paths:
  /taxFilings/{id}:
    put:
      tags:
      - "TaxFilingObject"
      description: ""
      operationId: "getTaxFiling"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "MyPayload"
        in: "body"
        description: "Here's something" 
        required: true
      responses:
        200:
          description: ""
          schema:
            $ref: "#/definitions/TaxFilingObject"
        404:
          description: ""
definitions:
  TaxFilingObject:
    type: "object"
    description: "An individual Tax Filing record, accessed by its ID"
    properties:
      filingID:
        type: "string"
      jurisdiction:
        type: "string"

I would hope for an error message like missing required property: 'schema'. But what it shows is a long, repetitive list of error messages on the parameter object:

Multiple markers at this line
- value body is not allowed, value should be one of "header"
- object has missing required properties "$ref"
- object has properties "description", "in", "name", "required" which are not allowed
- value body is not allowed, value should be one of "query"
- instance failed to match exactly one schema (matched 0 out of 2)
- instance failed to match exactly one schema (matched 0 out of 4)
- object has missing required properties "schema"
- value body is not allowed, value should be one of "path"
- value body is not allowed, value should be one of "formData"
- object has missing required properties "type"

If it’s reasonably easy to provide the user with a simple, helpful error message in cases like this, we should. If it’s going to require a lot of work, we can defer it.

[tedepstein]

@ghillairet , @tfesenko , I had made some comments about this in #9. Essentially, my suggestion is to list the schemas individually, like this:

Failed to match exactly one schema:
  schema 1 :
    - value of type integer is not allowed, value should be of type string
  schema 2:
    - object has properties "description" which are not allowed
    - object has missing required properties "$ref"

There are a couple of challenges here:

First, the individual candidate schemas within a oneOf group may not be named; and it’s difficult to explain the problem to the user when it involves an anonymous schema. If a candidate schema is defined in the definitions section, we can use its key. For inline, anonymous schemas we could (a) move them to the definitions section, and assign a name there; or (b) put extended properties into the schema, with names or brief descriptions on each schema, so we can reference it in a more meaningful way. These changes would have to go into our private version of the schema.

Second, the schemas can be recursive. So we can A = oneOf (B, C), and C= oneOf(D, E). To report that, it’s logically something like this:

Failed to match A because it's neither B nor C
  Failed to match B because
    missing required properties 'foo' and 'bar'
    contains property 'blip' which is not allowed.
  Failed to match C because it's neither D nor E
    Failed to match D because
      missing required property 'bling'
    Failed to match E because
      missing required properties 'blang'
      contains property 'boing' which is not allowed.

In an earlier comment, I suggested that we should not expand beyond the first level, but now I think this is the only way to provide useful output.

A possible optimization: detect cases where the instance data is clearly “trying” to conform to one candidate schema, and only report errors related to that schema. We could do this by using certain properties as discriminators. For example, in a parameter, we could use the in property as a discriminator, and only show validation errors related to that candidate schema. We would hide error messages related to body parameters.

We might want to encode those rules into the schema itself (e.g. using extended properties in the schema to specify criteria for each candidate schema in a oneOf group). Or it might make more sense to maintain this logic in code, separate from the schema.

There could still be cases where there is no logical discriminator, where the discriminator value(s) are not provided, or not legal. In those cases, the changes above (schema names + recursive error messages) would still be useful.

For the moment, this is the best I can suggest. And because it’s likely to be a significant amount of work, I think we should put it on the backlog.

[tedepstein]

Opened new issue #111 to track the code review follow-ups. Closing this now.