Overview of schema configuration

The following section provides a brief overview of schema configuration. For a more detailed discussion of schema architecture and extension file syntax in Cloud API, see Overview of schema configuration.

Schemas and resources

A schema is metadata that identifies how data is structured. In Cloud API, schemas are used to define resources. A resource is a JSON object included in a REST request or response that contains the data for the request or the response.

For example, Cloud API has an Activity schema. It defines properties such as subject (a string) and priority (a value from the Priority typelist). This schema is used by the various /common/v1/activities endpoints. For example:

  • When you submit a POST /common/v1/activities request, the request object contains an Activity resource that defines the activity to create.
  • When you submit a GET /common/v1/activities request, the response object contains one or more Activity resources that contain the data you requested.

Schema, mapping, and updater files

The behavior of each property is defined in the following files:

  • A schema file defines the structure of the property. This includes its datatype and any special behaviors, such as whether the property is read-only.
  • A mapping file defines how to map data from the Guidewire data model into the resource. It is used for the responses to GETs, POSTs, and PATCHes. In nearly every case, if a property is defined in a schema file, it is also defined in a mapping file.
  • An updater file defines how to map data from the resource to the Guidewire data model. It is used for the requests for POSTs and PATCHes. It is used only for writeable properties. So some properties defined in a schema file may not appear in an updater file.

Extension files

Whenever you configure a schema, you modify an extension file. Within the context of Cloud API, an extension file is a file that insurers can modify that adds or overrides the base configuration. All extension files have "ext" in their name and are located in an ext subdirectory.

For schema configuration, Cloud API includes the following types of extension files:

  • schema extension files, where insurers add new properties to a schema
  • mapping extension files, where insurers define how data is mapped from the data model to the schema
  • updater extension files, where insurers define how data is mapped from the schema to the data model (for properties that are writeable)

Every API has its own set of extension files. The names of the files, and the nodes in Guidewire Studio that you can use to access them, are:

  • <API>_ext-1.0.schema.json
    • integration -> schemas -> ext -> <API>.v1
  • <API>_ext-1.0.mapping.json
    • integration -> mappers -> ext -> <API>.v1
  • <API>_ext-1.0.updater.json
    • integration -> updaters -> ext -> <API>.v1