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 anActivity
resource that defines the activity to create. - When you submit a GET
/common/v1/activities
request, the response object contains one or moreActivity
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
-