Validating Swagger schemas

The general philosophy in validating Swagger schema combination is that the schema that results from a combination of files needs to be a logical, backwards-compatible extension of the combined pieces. For example, if schema A combines with schema B, Guidewire requires the following restrictions:

Schema A must not change the type of a parameter defined in schema B.
Schema A must not introduce new, required parameters to operations defined in schema B.
Schema A can remove or loosen validation constraints on input parameters defined in schema B, but schema A must not add or tighten validation constraints

However, even with these restrictions on changes to schema A, it is possible that custom code written against schema B does not work against schema A. The reason is that requests that are valid with respect to B are not necessarily valid against A. However, in general, most validation errors that occur during schema combination are warnings rather than hard errors, as there may be no way to avoid the error.

Schema verification errors

Standard schema validation occurs after schema combination happens. Thus, validation rules such as the following all happen in the context of the combined schemas:

Which fields are required
Which fields can or cannot be used in combination
Which parameter, response, or schema references are valid

As schema validation takes place after schema combination, it can sometimes make tracking down the root source of a problem more complicated. For example, if a parameter specifies an invalid combination of type, format, and x-gw-type properties, the error can be the result of the combination of schema A with schema B. In this case, the validation error messages report the line numbers of the parameter from all files that contained that parameter object.