Syntax for resource definition files

This section describes the syntax for the different types of resource definition files.

Schema file syntax

The file attributes

The initial part of a schema extension file contains attributes about the file itself. Do not modify these attributes, as doing so could cause Cloud API to behave in unexpected ways.

  • $schema: References the JSON Schema namespace declaration
  • x-gw-combine: Lists an array of files that contain schema definitions that are either referenced by schemas in this file or extended by schemas in this file.

The definitions section

The definitions section lists definitions for one or more schemas. For each schema, the following attributes are specified:

  • A schema title and description, which is used for API definition documentation.
  • The resource type, which, for Cloud API, is typically set to object.
  • A list of properties for the schema.

Every schema property includes:

  • The property name (such as activityPattern in the example below)
  • The property's title and description, which is used for API definition documentation.
  • A "datatype" for the property.
    • For scalar value properties, type is specified. This defines the JSON datatype of the property.
    • For compound value properties (such as typekeys), ref is specified. This defines the URI reference for the property.
  • Optional attributes as needed for the business functionality of the property.
For example, the following is a portion of the base configuration Activity schema:
"definitions": {
  "Activity": {
    "title": "Activity",
    "description": "An `Activity` is an assignable item...",
    "type": "object",
    "properties": {
      "activityPattern": {
        "title": "Activity pattern",
        "description": "The code of the `ActivityPattern` used...
        "type": "string"
        ...
      },
      "activityType": {
        "title": "Activity type",
        "description": "The type of this activity, such as `general`...",
        "$ref": "#/definitions/TypeKeyReference",
        ...
      },
      ...
    }
  }
}

Mapping file syntax

The file attributes

The initial part of a mapping extension file contains attributes about the file itself. Do not modify these attributes, as doing so could cause Cloud API to behave in unexpected ways.

  • $schema: References the JSON Schema namespace declaration
  • x-gw-combine: Lists an array of files that contain schema definitions that are either referenced by schemas in this file or extended by schemas in this file.

The mapping section

A mapping file contains a mappers section, which lists one or more API resources and, for each readable property in the resource, the way data is mapped to the property.

For each resource, the following attributes are specified:

  • The schemaDefinition that defines the structure of the resource
    • This references a schema declared in a schema.json file.
  • The data model entity that serves as the root for mapping information for this resource.
  • A list of properties

Every mapper property includes:

  • The property name (such as closeDate, description, and mandatory in the example below)
    • A path attribute. This is a Gosu expression that is used to populate the value of the property. Typically, this expression returns a value from the entity defined in the root attribute.
    • Depending on the nature of the property, there may be additional attributes.
For example, the following is a portion of the mapper for the base configuration Activity resource:
"mappers": {
  "Activity": {
    "schemaDefinition": "Activity",
    "root": "entity.Activity",
    "properties": {
      "closeDate": {
        "path": "Activity.CloseDate"
      },
      "description": {
        "path": "Activity.Description"
      },
      "mandatory": {
        "path": "Activity.Mandatory"
      },
      ...
    }
  }
}

Note the following:

  • This resource is defined in the schema who name is Activity (This schema is defined in some other schema.json file.)
  • The root for the resource mapping is entity.Activity.
  • For each instance of the resource:
    • The closeDate property is set to the Activity entity's CloseDate field.
    • The description property is set to the Activity entity's Description field.
    • The mandatory property is set to the Activity entity's Mandatory field.

Updater file syntax

The file attributes

The initial part of an updater extension file contains attributes about the file itself. Do not modify these attributes, as doing so could cause Cloud API to behave in unexpected ways.

  • $schema: References the JSON Schema namespace declaration
  • x-gw-combine: Lists an array of files that contain schema definitions that are either referenced by schemas in this file or extended by schemas in this file.

The updaters section

An updater file contains an updaters section, which lists one or more API resources and, for each writeable property in the resource, the way data is mapped to the data model.

For each resource, the following attributes are specified:

  • The schemaDefinition that defines the structure of the resource
    • This references a schema declared in a schema.json file.
  • The data model entity that serves as the root for mapping information for this resource.
  • A list of properties

Every updater property includes:

  • The property name (such as description and mandatory in the example below)
  • A path attribute. This defines, for each resource property, the data model entity property into which the resource property is to be written.
  • Depending on the nature of the property, there may be additional attributes.
For example, the following is a portion of the updater for the base configuration Activity resource:
"updaters": {
  "Activity": {
    "schemaDefinition": "Activity",
    "root": "entity.Activity",
    "properties": {
      "description": {
        "path": "Activity.Description"
      },
      "mandatory": {
        "path": "Activity.Mandatory"
      },
      ...
    }
  }
}

Note the following:

  • This resource is defined in the schema who name is Activity (This schema is defined in some other schema.json file.)
  • The root for the resource mapping is entity.Activity.
  • For each instance of the resource:
    • The value of the description property is written to the Activity entity's Description field.
    • The value of the mandatory property is written to the Activity entity's Mandatory field.

Note that there may be properties that appear in the mapping file but not the updater file. This typically occurs with properties that are read-only. For example, the Activity entity has a CloseDate property, which the application sets when the activity is closed. This property appears in the mapping file, as it can be read. But it does not appear it the updater file because it cannot be written to.

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

Extension files have the same syntax as base configuration files. But extension files often omit some information that is not necessary for extending a schema. For example, when a resource is declared in a base configuration file, the schema file defines the resource's title, description, and type. When that same resource is extended in an extension file with additional properties, there is no need to repeat the title, description, or type. These values are inherited from the base configuration file.

Every ext subdirectory has a sibling gw subdirectory. The gw subdirectory holds the base configuration files. Insurers are not permitted to modify these files. However, you may find it helpful to review those files for example of how base configuration resources are defined.