Additional behaviors for properties

You can configure schema properties with additional behaviors, such as:

  • Setting the property to read-only
  • Indicating the property is required by the database
  • Making the property sortable or filterable by the corresponding collection
  • Adding additional metadata, such as the first version of the API to include the property

The x-gw-extension object

Some property attributes are declared directly on the property itself. This includes:

  • Standard JSON properties, such as readOnly
  • Guidewire extension properties declared directly off the attribute, such as x-gw-sinceExtensionVersion

Other property attributes are Guidewire extensions declared in an object named x-gw-extension. This includes:

  • filterable and sortable
  • requiredForCreate
For example, if you had an expirationDate property that was filterable, sortable, and required for creation, the syntax for the declaration of these properties would be as follows:
      "properties": {
        "expirationDate": {
          ...
          "x-gw-extensions": {
            "requiredForCreate": true,
            "filterable": true,
            "sortable": true
          }
        }

Read-only properties

A read-only property is a property whose value cannot be set or modified through Cloud API. This can occur for the following reasons:

  • The property is read-only in the base application.
  • The property is settable in the base application, but there is a business requirement that it cannot be modified through Cloud API.

To set a property as read-only:

  1. In the schema file, set the readOnly property to true
  2. In the mapping file, specify a mapper as normal.
  3. Omit the property from the updater file.

For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. The corresponding resource property is read-only. The property declaration would be:

  "definitions": {
    "CustomEntityExt": {
      ...
      "properties": {
        ...
        },
        "expirationDate": {
          "type": "string",
          "format": "date-time",
          "readOnly": true
        }
        ...

The mapping declaration would be:

  "mappers": {
    "CustomEntityExt": {
      "expirationDate": {
        "path": "CustomEntity_Ext.ExprationDate"
      }

There would be no updater declaration.

Properties required by the database

In the data model, some entity fields are required. You cannot create an instance of the entity without specifying a value for the field, and the value can never be null. For example, suppose that an insurer has a business rule stating every activity must have an end date (the date by which it is expected to be completed). To enforce this, the Activity entity's EndDate field is required. These fields are sometimes referred to as required by the database.

In a schema, you can configure a resource property to reflect that it is required by the database. To do this, you must set the following properties:

  • "requiredForCreate": true
    • This x-gw-extensions attribute indicates the property must be included in POST payloads.
  • "x-gw-nullable": false
    • This attribute indicates that when the property is specified, its value cannot be set to null

The "requiredForCreate": true attribute, by itself, only mandates that the property must be specified in a POST. There is nothing to prevent a caller from including the property but setting the property's value to null.

The "x-gw-nullable": false attribute, by itself, only mandates that if the property is specified, the property's value cannot be set to null. There is nothing to prevent a caller from omitting the property.

By combining the two expressions, you are stating that the property must be specified in a POST and set to a non-null value, and anytime thereafter that the property is specified, it must be set to a non-null value. This is the equivalence of setting a data model entity field to required.

For example, suppose the CustomEntity_Ext entity has an CustomDescription field, which is a string. The field is required. The property declaration would be:

  "definitions": {
    "CustomEntityExt": {
      ...
      "properties": {
        ...
        "customDescription": {
          "type": "string",
          "x-gw-nullable": false,
          "x-gw-extensions": {
            "requiredForCreate": true
          }
        }
        ...
Note: There is also a concept of requiredness at the schema level. You can specify a property is required at the schema level by specifying "required": true. When a schema property is set to required, it must be provided every time a payload is submitted. In most cases, this is not something you would want to specify in Cloud API schemas, as it forces you to specify a value for PATCHes, even if the property in question is not being changed.

Overriding base configuration properties

If a base configuration property is not required by the database, you can make it required by the database by adding it to the appropriate schema extension file and setting the appropriate properties as shown in the previous example.

If a base configuration property is required by the database, you cannot make it non-required.

Properties writeable at creation only

A "writeable only at creation" property is a property whose value can only be specified in a POST and not in any PATCH. This is used for fields that, once set, cannot be modified.

To specify a property is writeable only at creation, set the x-gw-extensions object's create-only property to true:

"x-gw-extensions": {
  "create-only": true
}

For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. This field can be set on a POST, but not in any PATCH. The property declaration would be:

"definitions": {
  "CustomEntityExt": {
    ...
    "properties": {
      ...
	"expirationDate": {
	  "x-gw-extensions": {
	    "create-only": true
	  }
      }
    }
  }
}

Sortable properties

A sortable property is a property that can be optionally used to sort the elements of a collection resource.

To specify a property is sortable, set the x-gw-extensions object's sortable property to true:

"x-gw-extensions": {
  "sortable": true
}

For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. When retrieving a collection of CustomEntity_Ext instances, the caller application can opt to sort the collection based on the expiration date using a call such as:

GET /common/v1/customentity-exts?sort=expirationDate

The property declaration would be:

"definitions": {
  "CustomEntityExt": {
    ...
      "properties": {
	...
	"expirationDate": {
	  "x-gw-extensions": {
	    "sortable": true
	  }
	}

Overriding base configuration properties

If a base configuration property is not sortable, you can make it sortable by adding it to the appropriate schema extension file and, in the x-gw-extensions object, specifying sortable: true as shown in the previous example.

If a base configuration property is sortable, you cannot make it unsortable.

Limitations and performance considerations

In order to make a property sortable using the sortable attribute, the property must be directly mapped to a single data model entity field. The property cannot be mapped to any of the following:

  • A Gosu expression
  • A POJO or POGO property
  • Some other type of complex expression

Adding new sortable columns can have performance implications, particularly if the collection to be sorted tends to have a very large number elements. In these cases, insurers may need to add new database indexes to maintain acceptable performance.

Filterable properties

A filterable property is a property that can be used to filter the elements of a collection resource.

To specify a property is filterable, set the x-gw-extensions object's filterable property to true:

"x-gw-extensions": {
  "filterable": true
}

For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. When retrieving a collection of CustomEntity_Ext instances, the caller application can opt to filter the collection based on the expiration date using a call such as:

GET /common/v1/customentity-exts?filter=expirationDate:gt:2020-05-11T07::00::00.000Z

The property declaration would be:

"definitions": {
  "CustomEntityExt": {
    ...
      "properties": {
	...
	"expirationDate": {
	  "x-gw-extensions": {
	    "filterable": true
	  }
	}

Overriding base configuration properties

If a base configuration property is not filterable, you can make it filterable by adding it to the appropriate schema extension file and, in the x-gw-extensions object, specifying filterable: true as shown in the previous example.

If a base configuration property is filterable, you cannot make it unfilterable.

Additional metadata for properties

The x-gw-sinceExtensionsVersion attribute

Every property can have an x-gw-sinceExtensionsVersion attribute. This is a string value that specifies the first version of the API that included the extension property.

For example, the following specifies that the CustomEntity_Ext entity has an ExpirationDate field that was added in version 1.1.0.
  "definitions": {
    "CustomEntityExt": {
      ...
      "properties": {
        ...
        "expirationDate": {
          "x-gw-sinceExtensionsVersion": "1.1.0"
        }
        ...

There is also an x-gw-sinceVersion used by Guidewire to identify the first version of the API that included a base configuration property.

Summary of property attributes

The following attributes are direct children of the property declaration:

Attribute Description Example
readOnly Boolean identifying if the property as read-only. (The default is false.) "readOnly": true
x-gw-nullable Boolean identifying if the property can be explicitly set to null. (The default is true.) Used to set a property as required by the database. For more information, see Properties required by the database. "x-gw-nullable": false
x-gw-sinceExtensionsVersion String identifying the first version of the API to include the extension property "x-gw-sinceExtensionsVersion": "1.​1.​0"

The following attributes are declared in the x-gw-extension object:

Attribute Description Example
createOnly Boolean identifying if the property can be specified only when the object is created. (The default is false.) "createOnly": true
filterable Boolean identifying if the filter query parameter can be used on this property. In other words, collections can be filtered using this property. (The default is false.) "filterable": true
requiredForCreate Boolean identifying if the property must be specified when the object is created. (The default is false.) Used to set a property as required by the database. For more information, see Properties required by the database. "requiredForCreate": true
sortable Boolean identifying if the sort query parameter can be used on this property. In other words, collections can be sorted using this property. (The default is false.) "sortable": true