Schema organization

The system APIs are defined by a large collection of Swagger and JSON Schema files that are located in the Project/configuration/config/Integration directory of Guidewire Studio. That directory includes the following relevant subdirectories:

  • apis contains Swagger files that define the system APIs and their associated endpoints.
  • schemas contains schema definitions of the resource types associated with system API endpoints.
  • mappings contains mappers that map schema definitions to PolicyCenter entities.
  • updaters contains updaters that make resource data writeable to PolicyCenter.

To give a concrete example:

  • Within apis, the Swagger file for the Common API includes a definition for the /common/v1/activities/{activityId} endpoint, the root resource of which is Activity. This endpoint supports GET and PATCH operations.
  • Within schemas, the Activity schema definition delineates the properties and associated data types for the Activity resource. The schema definition is required to define the resource.
  • Within mappings, the Activity mapper maps the Activity schema definition with the Activity entity in PolicyCenter. The mapper is required to enable GET operations for the resource.
  • Within updaters, the Activity updater declares Activity resource properties that can be written to Activity entity fields in PolicyCenter. The updater is required to enable POST or PATCH operations for the resource.

Extension directories

The apis, schemas, mappings, and updaters directories each contain two subdirectories, gw and ext. The gw subdirectory holds the base configuration files, and users must not alter these. The ext subdirectory contains the extensions facilities. When extending an API, you will work with files in the ext subdirectories.

Note: While you must not alter the files in gw subdirectories, you might find it helpful to review those files to gain a deeper understanding of how the API schemas are structured.

Swagger specification syntax

All of the schema files conform to the Swagger 2 specification. For syntax details, refer to the spec at https://swagger.io/specification/v2/.

The Swagger specification files in the schemas, mappings, and updaters subdirectories are in JSON format, using JSON Schema syntax. For details on JSON Schema syntax, refer to the spec at http://json-schema.org/.

Additionally, you can find guidance on how Guidewire uses JSON Schema syntax in the Plugins, Prebuilt Integrations, and SOAP APIs. This documentation includes information on fully qualified names, which are used for file naming and include references.