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
andsortable
requiredForCreate
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:
- In the schema file, set the
readOnly
property to true - In the mapping file, specify a mapper as normal.
- 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.
- This
"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
}
}
...
"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.
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
|