Combining Swagger schema files

Guidewire provides a mechanism for creating Swagger schemas that combine together multiple pieces to form a single, logical resulting schema document. It is possible to use this combination mechanism for a number of different purposes. The following list describes the possible ways that you can combine Swagger schemas.

Simple hierarchical extension	Works by extending an application schema, which, in turn, can extend a platform schema.
Content composition	Works by combining together several different content pieces. For example, it is possible to combing LOB-specific schemas, along with their own extensions, and, perhaps, a base schema.
Schema aggregation	Works by breaking a large, complex schema into multiple files for maintenance by different teams. You can then aggregate the individual files together again for publishing as a single logical API with a single, consistent base URL and version.
Minor version change	Works by creating a new minor version of a schema that extends the previous major or minor version. This new version can minimize schema duplication and ensure the changes are backwards-compatible
API template	Works by implicitly adding the API template to the list of combined schemas for a given, published schema.

One way to think about schema combination is as a well-defined, ordered, textual merge of the documents. For example, suppose that schema A combines schemas [B, C], listing the two schemas in that order in the x-gw-combine property. After combination, schema A essentially looks exactly as if you did the following:

Merged the contents of schema B on top of schema C, overwriting any properties common to both documents with those in schema B.
Merged the contents of schema A on top of the first result, again overwriting any properties that schema A respecified.

The result is that schema A can override items in either schema B or schema C, and can add entirely new items, but the merge cannot remove any items from either schema B or schema C. Schema B can also behave the same way to schema C because of the ordering defined in x-gw-combine ([B, C]). However, ideally, any two schemas that you want to combine in this manner are disjoint.

After the schema combination happens, PolicyCenter then validates the resulting combined schema against its component pieces to ensure that the changes are logical extensions or otherwise backwards compatible. In this example, PolicyCenter needs to validate schema A against schema B and against schema C. Thus, if schema A changes the type of a parameter that was defined in Schema B, PolicyCenter reports that as an error. And, if schema A introduced a new validation constraint on top of a parameter defined in schema B, PolicyCenter reports that as a warning.

Schema naming

One important consequence of schema combination is that PolicyCenter does not modify the original schemas. Schema A is a different schema, with a different name, from either schema B or schema C. The end result can also have an entirely different versioning schema. For example, you can extend a schema version gw.pc.policy-10.0 as mycompany.pc.policy-1.0.

It is also possible to extend the same schema an arbitrary number of times. For example, you can extend gw.pc.policy-1.0 as myCompany.pc.policy-1.0, myCompany.pc.policy-2.0, and so on.

For this reason (among others), Guidewire requires that you publish your schema files explicitly in published-apis.yaml. If you extend a base configuration schema, you mostly likely want to publish your extension only, not the base configuration schema.

Any schema that you create based on a Guidewire schema does not automatically pick up updates to the schema provided by Guidewire. If you want to pick up changes in a Guidewire-provided schema, you must explicitly migrate your changes to the new Guidewire schema.