Schema properties usage

Calculated values

APD supports calculated values for coverage terms on a parent coverage where the minimum or maximum are calculated based on terms on the child coverages. For example, the parent coverage can have a limit whose minimum value is the sum of the limits of a set of child coverages. Calculated values can use a sum, min, or max across the child terms, or be a direct reference to a child term.

The entity schema provides the x-gw-calculatedValues property to support this type of scenario. This property is an object whose keys represent schema properties that have dynamic values rather than static values. Each schema property will have a value with a jsonLogic property that can be evaluated, resulting in the concrete value to attach to that schema property.

The x-gw-calculatedValues property is primarily intended for use by client code that uses schema-based validation. In order to interpret the calculated values at runtime, a client needs to iterate through each property on the x-gw-calculatedValues object, evaluate the JsonLogic expression for that property, and then attach the resulting value to the containing schema definition.

See https://jsonlogic.com/ for more information on using JsonLogic.

The following is an example of a calculated value. This is a simple example where the value must be retrieved from another entity:

"x-gw-calculatedValues": {
  "x-gw-maximum": {
    "jsonLogic": {
      "+": {
        "uri": "/jobs/{jobId}/lines/TSTLine/test-coverables/{testCoverableId}/coverages/TSTChildCov/terms.TSTChildCovPackageTerm.choiceValue.values[0].value"
      }
    }
  }
}

Child entities

An entity can (but doesn’t have to) have child objects. These child objects are returned in the x-gw-children schema object. The following properties can be included with the x-gw-children object:

• childType: The type related to certain product model metadata. See "Special child types" below.
• description: A description of the children.
• graphProperty: The property used to attach these children in the schema.
• id: The id of the child entity.
• title: The title for the children.
• urlPart: The URL fragment used for the collection of child entities in the API.

The following example shows some of the children for the Account entity in the base configuration:

"x-gw-children": [
    {
        "id": "Activity",
        "urlPart": "activities"
    },
    {
        "id": "Assignee",
        "urlPart": "activity-assignees"
    },
    {
        "id": "ActivityPattern",
        "urlPart": "activity-patterns"
    },

Choice values

For entities that contain choice values, the entity schema returns the x-gw-choices object. You can set the query parameter inlineTypelists to true to retrieve this object for typelists.

The object contains the following properties:

Typelist choice values

The x-gw-choices property can contain typelist values associated with the entity objects. For example, in the PolicyCenter base configuration the Account Status on the Account entity is a typelist of type AccountStatus. The typekeys in the AccountStatus typelist are Active, Merged, Pending, and Withdrawn. Without inlineTypelists set to true, the schema endpoint returns the following:

"accountStatus": {
  "$ref": "#/definitions/TypeKeyReference",
  "description": "The current status of this account",
  "readOnly": true,
  "title": "Account status",
  "x-gw-typelist": "AccountStatus"
},

This example shows that accountStatus is a typelist of type AccountStatus, but the values of that typelist are not displayed. When you add inlineTypelists=true to the endpoint query string, the individual values are included in the schema in the x-gw-choices object:

"accountStatus": {
  "$ref": "#/definitions/TypeKeyReference",
  "description": "The current status of this account",
  "readOnly": true,
  "title": "Account status",
  "x-gw-choices": [
    {
      "code": "Active",
      "description": "The account is fully ready and open, and submissions have been created for it.",
      "name": "Active",
      "sortOrder": 0
    },
    {
      "code": "Merged",
      "description": "The account has been merged into another account and is available for read only access.",
      "name": "Merged",
      "sortOrder": 1
    },
    {
      "code": "Pending",
      "description": "The account is ready for data entry, but data entry is still ongoing and the account is not considered fully open.",
      "name": "Pending",
      "sortOrder": 2
    },
    {
      "code": "Withdrawn",
      "description": "The account has been withdrawn from consideration for business with the carrier.",
      "name": "Withdrawn",
      "sortOrder": 3
    }
  ],
  "x-gw-typelist": "AccountStatus"

Notice the sortOrder value under each choice. This ordering can be used to ensure the desired order of user interface elements. See Sort order for more information.

Cloud API endpoint elements

For schema entities that can be accessed through Cloud API endpoints, the schema includes information on options for accessing those endpoints:

• x-gw-canonicalParent: The parent entity.
• x-gw-canonicalCollectionUri: The endpoint that accesses a collection of entities.
• x-gw-canonicalElementUri: The endpoint that accesses individual instances of the entity.
• x-gw-actions: An array of actions that can be taken on the endpoints. Each object in the array includes:
  • httpMethod: A command that can be used with the endpoint.
  • actionTarget: Whether the command applies to the individual element endpoint or the collection endpoint.
  • description: Optional. Describes the action.
  • urlSuffix: Optional. An additional action that can be taken on the endpoint by using the httpMethod with the endpoint, followed by the urlSuffix at the end of the endpoint. (See example below.)

For example, here are the endpoint elements available for the RolePermission entity:

"title": "Role permission",
"type": "object",
"x-gw-actions": [
  {
    "actionTarget": "collection",
    "httpMethod": "GET"
  },
  {
    "actionTarget": "collection",
    "httpMethod": "POST"
  },
  {
    "actionTarget": "element",
    "httpMethod": "DELETE"
  },
  {
    "actionTarget": "element",
    "httpMethod": "GET"
  }
],
"x-gw-canonicalCollectionUri": "/admin/v1/roles/{roleId}/permissions",
"x-gw-canonicalElementUri": "/admin/v1/roles/{roleId}/permissions/{permissionId}",
"x-gw-canonicalParent": {
  "id": "Role"
},

This example shows that you can take the following actions on the RolePermission entity through Cloud API:

• GET a collection of role permissions. (GET /admin/v1/roles/{roleId}/permissions)
• Create a new role permission with the POST command on the permissions collection. (POST /admin/v1/roles/{roleId}/permissions)
• DELETE a single role permission. (DELETE /admin/v1/roles/{roleId}/permissions/{permissionId})
• GET a single role permission. (GET /admin/v1/roles/{roleId}/permissions/{permissionId})

Note that the x-gw-canonicalParent identifies the Role entity as the canonical parent of RolePermissions.

Cloud API responses

When an element is retrieved with a Cloud API command, it’s possible that not all properties of that element will be displayed in the response by default. This might be desirable, for example, in cases where retrieving the contents of a certain property could impact performance if it were to be retrieved for every instance of that element.

You can identify the circumstances under which a property will be displayed based on the x-gw-defaultViews property. This property is an array with the following possible values:

• detail: This property is in the response when a single instance of the element is retrieved, not when a collection is retrieved.
• summary: This property is in the response when a collection is retrieved.
• none: This property is in the response only when it is explicitly identified in the fields query parameter.

In this example, the accountContactRoles property is displayed in the response only when a single instance of an AccountContact is retrieved:

"AccountContact": {
    ...
    "properties": {
        "accountContactRoles": {
             ...
             "x-gw-defaultViews": [
                 "detail"
             ],
             ...
        },

The following command retrieves a single account contact, and therefore displays the accountContactRoles property:

Command

GET /account/v1/accounts/pc:Su4p27AlTSug_SWq-8koA/contacts/pc:S9rwT9nWtFBArb3GFDwkc

Response

{
    "data": {
        "attributes": {
            "accountContactRoles": [
                {
                    "code": "AccountHolder",
                    "name": "AccountHolder"
                }
            ],
            "active": true,
            "authorizationID": "S5qmqyeE_7azM0VwejF2r",
            "cellPhone": {
                "countryCode": {
                    "code": "US",
                    "name": "United States (1)"
                },

However, when the collection of account contacts is retrieved, account contact roles is not included:

Command

GET /account/v1/accounts/pc:Su4p27AlTSug_SWq-8koA/contacts

Response

{
    "count": 5,
    "data": [
        {
            "attributes": {
                "authorizationID": "S5qmqyeE_7azM0VwejF2r",
                "cellPhone": {
                    "countryCode": {
                        "code": "US",
                        "name": "United States (1)"
                    },

Country-specific fields

Entity schemas use JSON logic conditional rules to define whether certain fields are forbidden or required based on the country. In some cases a field might be forbidden for use in a particular county. In other cases, such as addresses, required fields differ by country. These rules are specified in the x-gw-rules property.

In this example, there is a rule on PolicyLocation that makes certain location fields forbidden and others required for the US:

"x-gw-entityId": "PolicyLocation",
  "x-gw-rules": [
    {
      "jsonLogic": {
        "if": [
          {
            "===": [
              {
                "var": "country"
              },
              "US"
            ]
          },
          {
            "x-gw-dynamicPropertiesMarker": true,
            "x-gw-forbidden": [
              "CEDEX",
              "addressLine1Kanji",
              "addressLine2Kanji",
              "area",
              "cityKanji",
              "department",
              "emirate",
              "island",
              "oblast",
              "parish",
              "prefecture",
              "province"
            ],
            "x-gw-requiredForValidation": [
              "addressLine1",
              "city",
              "postalCode",
              "state"
            ]
          },

In some cases the same set of rules apply to multiple countries. In those cases, all countries are listed in an array using in logic on the rules, as shown here:

"x-gw-rules": [
  {
    "jsonLogic": {
      "if": [
        {
          …
        },
        {
          "in": [
            {
              "var": "country"
            },
            [
              "AS",
              "AU",
              "FM",
              "GU",
              "IN",
              "MH",
              ...

Date and date-time fields

Some properties that contain dates have restrictions on the date range allowed. There are instances where a date must be before or after a certain timeframe. To allow for this, the following attributes can be found on a date or date-time property when applicable:

• x-gw-before: The date or date-time must be earlier than this value.

• x-gw-after: The date or date-time must be later than this value.

In the following example, dateOfBirth is a date that must have a value before the date the value is entered (now):

"dateOfBirth": {
    "description": "The person's date of birth. Only applicable for an `AccountContact` that represents a person.",
    "format": "date",
    "nullable": true,
    "title": "Date of birth",
    "type": "string",
    "x-gw-before": "now"
},

Entity ID

Every schema that contains an entity has a corresponding entity ID. For example, the User schema has an entity ID of User:

"x-gw-entityId": "User"

In contrast, the SimpleReference schema is not an entity, and therefore does not have an x-gw-entityId property.

Note that the x-gw-entityId property is available only when a schema is retrieved through the entity-schemas endpoints.

Event safety

When you’re integrating with Guidewire InsuranceSuite through App Events, it’s important to know whether a property is event safe. You can determine the event safety of a property by looking for the x-gw-includedInAppEvents property.

If a property is not event safe, it will have an x-gw-includedInAppEvents property with a value of false. If a property is event safe, x-gw-includedInAppEvents will not be present on the property.

If you are not integrating through App Events, you can ignore the x-gw-includedInAppEvents property.

See App Events for more information on App Events.

Forbidden fields

The schema can include the x-gw-forbidden property. This property is an array used to indicate that one or more properties are not allowed or available under certain conditions. It is often defined inside JsonLogic decisions that provide the conditions under which something is forbidden. (See https://jsonlogic.com/ for more information on using JsonLogic.)

This example shows a section of the schema that indicates certain properties are forbidden based on a contact subtype:

"x-gw-rules": [
  {
    "jsonLogic": {
      "if": [
        …
        {
          "in": [
            {
              "var": "contactSubtype"
            },
            [
              "Adjudicator",
              "Person",
              "PersonVendor",
              "UserContact"
            ]
          ]
        },
        {
          "x-gw-dynamicPropertiesMarker": true,
          "x-gw-forbidden": [
            "companyName"
          ]
        },
        {
          "in": [
            {
              "var": "contactSubtype"
            },
          [
            "LegalVenue",
            "Place"
          ]
        ]
      },
      {
        "x-gw-dynamicPropertiesMarker": true,
        "x-gw-forbidden": [
          "applicableGoodDriverDiscount",
          "cellPhone",
          "companyName",
          …
  ]
},

The x-gw-forbidden property is used in several contexts. It is used to designate forbidden fields for things such as:

• Subtype-specific fields.

• Product edition rules that indicate that a given element is unavailable for that edition.

• Choices on options, packages, or typekeys. In these cases, x-gw-forbidden is an array of objects, where each object has a code and name for the forbidden choice.

See Country-specific fields for more examples of x-gw-forbidden.

Localizations

When you call the schema retrieval endpoint with the includeLocalizations parameter set to true, the returned schema will contain localized versions of all localizable strings in the schema. (See includeLocalizations for information on using this parameter.) If you also specify the inlineTypelists parameter, localized strings will be included for typelist values. Similarly, if you specify the inlineProductDefinition parameter, localized strings will be included for localizable product model elements such as coverage names and descriptions.

Localization strings are returned on the x-gw-localizations property on the associated element. The value of x-gw-localizations is an object with a key for each localized property, such as title or description. The values of those keys are another object with key/value pairs for each requested language and the localized value for those languages.

For example, suppose you have two languages configured, English (US) and French (France). You also have a schema object on an entity named username. The object looks like this:

"username": {
  "description": "The username for the user",
  "maxLength": 30,
  "minLength": 1,
  "pattern": "\\S",
  "title": "Username",
  "type": "string",

Retrieve localized values for all installed languages:

Command

GET /common/v1/entity-schemas?includeLocalizations=*all

Schema example

"x-gw-localizations": {
  "description": {
    "en_US": "The username for the user",
    "fr_FR": "Le nom d’utilisateur de l’utilisateur"
  },
  "title": {
    "en_US": "Username",
    "fr_FR": "Nom d’utilisateur"
  }
}

Retrieve localized values for US English:

Command

GET /common/v1/entity-schemas?includeLocalizations=en_US

Schema example

"x-gw-localizations": {
  "description": {
    "en_US": "The username for the user"
  },
  "title": {
    "en_US": "Username"
  }
}

Retrieve localized values in US English including typelists:

Command

GET /common/v1/entity-schemas?includeLocalizations=en_US&inlineTypelists=true

Schema example

"vacationStatus": {
  "$ref": "#/definitions/TypeKeyReference",
  "description": "Indicates whether the user is considered to be on vacation",
  "title": "Vacation status",
  "x-gw-choices": [
    {
      "code": "atwork",
      "description": "The user is at work",
      "name": "At work",
      "sortOrder": 0,
      "x-gw-localizations": {
        "description": {
          "en-US": "The user is at work"
        },
          "name": {
            "en-US": "At work"
          }
        }
      },
      {
        "code": "onvacation",
        "description": "The user is on vacation",
        "name": "On vacation",
        "sortOrder": 1,
        "x-gw-localizations": {
          "description": {
            "en-US": "The user is on vacation"
          },
          "name": {
            "en-US": "On vacation"
          }
        }
      },
      …
    ],
    "x-gw-localizations": {
      "description": {
      "en-US": "Indicates whether the user is considered to be on vacation"
    },
      "title": {
        "en-US": "Vacation status"
      }
    },
    "x-gw-typelist": "VacationStatusType"
  },

A value will always be included in x-gw-localizations for each installed language. If the value has not been localized for a language, normal localization fallback rules will apply. If a language code and region are specified, the first fallback will be to language code, then to the default language. For example, suppose fr_CA (Frech, Canada) is an installed language. If there is no localization for a particular property for fr_CA, it will fall back to a value specified for fr (French). If there is no localized value for fr, the value will be the default language (if the default language is not fr_CA or fr).

Command

GET /common/v1/entity-schemas?includeLocalizations=en_US,fr_FR

Schema example

"x-gw-localizations": {
  "description": {
    "en_US": "The username for the user",
    "fr_FR": "The username for the user"
  },
  "title": {
    "en_US": "Username",
    "fr_FR": "Username"
  }
}

Numeric values

Properties that are numeric types can have additional defining properties depending on the type of value.

Fixed-point decimal values

Certain decimal values need to be restricted as to the maximum number of digits allowed in the value. This is depicted in the schema through the x-gw-precision and x-gw-scale properties:

• x-gw-precision: The maximum number of digits allowed for a value.
• x-gw-scale: The scale of the value, such as the maximum number of digits to the right of a decimal point.

These properties apply only to elements of type gw-bigdecimal and to MonetaryAmount references.

In this example, the cost of a new car can be up to 18 digits, with up to two digits following the decimal point:

"PersonalVehicle": {
    "description": "Personal Vehicle",
    "properties": {
        ...
        "costNew": {
            "$ref": "#/definitions/MonetaryAmount",
            "description": "Original retail cost of car.",
            "nullable": true,
            "title": "Cost New",
            "x-gw-precision": 18,
            "x-gw-scale": 2,
            "x-gw-sortOrder": 6
        },

Minimum and maximum values

Numeric properties that are non-standard JSON decimal or integer types (such as MonetaryAmount and gw-bigdecimal) can have maximum and minimum values defined in the x-gw-maximum and x-gw-minimum properties. In this example, the maximum amount allowed is 5000, and the minimum is 250:

"amount": {
    "$ref": "#/definitions/MonetaryAmount",
    "description": "The transaction amount for the effective time",
    "readOnly": true,
    "title": "Amount",
    "x-gw-maximum": 5000,
    "x-gw-minimum": 250
},

References

There are some schema definitions that are references to other entities. Examples are entities such as SimpleReference and GroupReference. When this is the case, the entity has an x-gw-resourceReference property set to true.

"x-gw-resourceReference": true

For properties that are reference types, such as SimpleReference, the name of the referenced entity type is defined in the x-gw-referenceType property. The name of the schema definition associated with a given type is specified in the x-gw-reference-schema property. In this example, accountHolder is a SimpleReference associated with the AccountContact schema, of type AccountContact:

"accountHolder": {
  "$ref": "#/definitions/SimpleReference",
  "description": "A reference to the `AccountContact` that represents the owner of the policies for this account",
  "title": "Account holder",
  "x-gw-reference-schema": "AccountContact",
  "x-gw-referenceType": "AccountContact"
},

Required properties

Some entities have a required property. This property is an array containing a list of properties that must have values on instances of the entity. In addition, there are properties that are required only when certain actions, such as creation or validation, take place on those entities.

• requiredForCreate: The property must have a value for an entity to be created.
• requiredForValidation: The property must have a value for the object to validate.

For example, the following specifies that an address cannot be validated if there are not values for addressLine1, city, postalCode, and state:

"x-gw-requiredForValidation": [
    "addressLine1",
    "city",
    "postalCode",
    "State"
]

Rules

The entity schema applies rules to some entities, both conditional and non-conditional. Rules are required for several different areas of the schema. For details on some of the specific areas of the entity schema where rules are used, see the following sections:

• Country-specific fields

Rules Overview

In some cases there is schema metadata about a business entity, or associated product model entity, that is conditional rather than static. To support those use cases, where possible the Guidewire schema APIs translate those rules into conditions using the JsonLogic format. The JsonLogic expressions, when evaluated, will return a JSON object that might contain additional JSON Schema properties to apply to the attached schema.

For example, if a direct coverage term has a conditional maximum value, the directValue schema property for the term's schema will have an x-gw-rules array with an object representing this rule. Evaluating the JsonLogic expression for the associated rule might return a result such as:

{
  "x-gw-dynamicPropertiesMarker": true,
  "x-gw-maximum": "500.00"
}

This means that the x-gw-maximum schema property needs to be applied to the term's schema dynamically, replacing any value that might already be there. If the result returns null or the empty object, it means no changes to the schema are needed. (The x-gw-dynamicPropertiesMarker property is a marker property that can be ignored at runtime).

JsonLogic expressions need to be evaluated using the associated root API object's attributes as the context for evaluation.

See https://jsonlogic.com/ for more information on using JsonLogic.

The following are examples of places where rules can be attached:

• Field existence rules are attached to the containing schema definition.
• Field min/max/default rules are attached to the associated property definition.
• Field typekey existence rules are attached to the associated property definition.
• Clause existence rules are attached to the _Coverages schema definition that defines a container for all coverages on the coverable.
• Term existence rules are attached to the terms property on the _Coverage schema definition.
• Term min/max/default rules are attached to the Value property for the term, such as directValue.
• Term option/package/typekey existence rules are attached to the choiceValue or typekeyValue property for the term.

Rules Examples

Conditional rules are provided with JsonLogic. Often (but not always) this logic is nested within the x-gw-rules array. Here’s an example. (Note that while this example pertains specifically to PolicyCenter, the functionality of x-gw-rules is the same across all InsuranceSuite products.)

"x-gw-rules": [
  {
    "jsonLogic": {
      "if": [
        {
          "===": [
            {
              "uri": "/jobs/{jobId}/lines/PersonalAutoLine/integerProperty"
            },
            1002
          },
          {
            "x-gw-dynamicPropertiesMarker": true,
            "x-gw-maximum": "500.00"
          }
        },
        {
          "===": [
            {
              "uri": "/jobs/{jobId}/lines/PersonalAutoLine/integerProperty"
            },
            1003
          ]
        },
        {
          "x-gw-dynamicPropertiesMarker": true,
          "x-gw-maximum": "400.00"
        },

In this case, if the property at the specified uri is equal to 1002, the maximum value for this property is 500. But if the value is 1003, the maximum is 400.

Rules can also exist without conditions. For example, if a direct coverage term always has a maximum of 500.00 for a particular product edition, fetching the schema in the context of that edition includes the property directly.

"directValue": {
  "x-gw-maximum": "500.00",
  …
}

The x-gw-rules property is an array of JsonLogic rules. Another property, x-gw-dynamicProperties, is similar to x-gw-rules, but instead of being an array, it’s an object containing named rules. In this example, there are two named rules, one for accountHolderCreation and one for primaryLocationCreation:

"x-gw-dynamicProperties": {
  "accountHolderCreation": {
    "forbiddenError": "Exactly one of either 'accountHolder' or 'initialAccountHolder' is required on creation",
    "jsonLogic": {
      "if": [
        {
          "===": [
            {
              "var": "accountHolder"
            },
            null
          ]
        },
        {
          "x-gw-dynamicPropertiesMarker": true,
          "x-gw-requiredForCreate": [
            "initialAccountHolder"
          ]
        },
        {
          "x-gw-dynamicPropertiesMarker": true,
          "x-gw-forbidden": [
            "initialAccountHolder"
          ]
        }
      ]
    },
    "requiredError": "Exactly one of either 'accountHolder' or 'initialAccountHolder' is required on creation"
  },
  "primaryLocationCreation": {
    "forbiddenError": "Exactly one of either 'primaryLocation' or 'initialPrimaryLocation' is required on creation",
    "jsonLogic": {
      "if": [
        {
          "===": [
            {
              "var": "primaryLocation"
            },
            null
          ]
        },
        {
          "x-gw-dynamicPropertiesMarker": true,
          "x-gw-requiredForCreate": [
            "initialPrimaryLocation"
          ]
        },
        {
          "x-gw-dynamicPropertiesMarker": true,
          "x-gw-forbidden": [
            "initialPrimaryLocation"
          ]
        }
      ]
    },
    "requiredError": "Exactly one of either 'primaryLocation' or 'initialPrimaryLocation' is required on creation"
  }
},

Sort order

Sort order is preserved in various situations and can be used to ensure the desired order of user interface elements.

sortOrder

In this example, the order of Account Status choices has been preserved through the sortOrder on the choice options, with Active first, Merged second, and so on. Note that counting starts at 0, so the first choice is sortOrder 0.

"accountStatus": {
  "$ref": "#/definitions/TypeKeyReference",
  "description": "The current status of this account",
  "readOnly": true,
  "title": "Account status",
  "x-gw-choices": [
    {
      "code": "Active",
      "description": "The account is fully ready and open, and submissions have been created for it.",
      "name": "Active",
      "sortOrder": 0
    },
    {
      "code": "Merged",
      "description": "The account has been merged into another account and is available for read only access.",
      "name": "Merged",
      "sortOrder": 1
    },
    {
      "code": "Pending",
      "description": "The account is ready for data entry, but data entry is still ongoing and the account is not considered fully open.",
      "name": "Pending",
      "sortOrder": 2
    },

See Choice values above for more information.

Update restrictions

Some properties can be assigned values only when the entity is first created. In those cases, the property will have a value of x-gw-createOnly set to true.

For example, an initial account holder can be specified only at the time the account is created (POST), and cannot be modified later.

"Account": {
        ...
        "initialAccountHolder": {
            ...
            "title": "Initial account holder",
            "x-gw-createOnly": true
        },

In other cases, a property can be assigned a value only when the entity is updated (PATCH). In those cases, the property will have x-gw-patchOnly set to true:

"x-gw-patchOnly": true

Typekey references

Some properties in the schema are used to identify typekey properties and behaviors.

Typelist

If an element in the schema is a TypeKeyReference, the applicable typelist is specific in the x-gw-typelist property.

In this example, the organizationType property is a TypeKeyReference to the AccountOrgType typelist:

"organizationType": {
    "$ref": "#/definitions/TypeKeyReference",
    "description": "The type of organization of the company or person represented by this account, such as `individual` or `corporation`",
    "nullable": true,
    "title": "Organization type",
    "x-gw-typelist": "AccountOrgType"
},

Filter

Some typelists are filtered by categories from other typelists represented on the same object. The x-gw-filterBy property contains an array of categories on which to filter. For example, a country typelist might include states, provinces, islands, and so on. Not all of these options apply to all countries. In these cases, the typelist needs to be filtered by country, as in the following examples:

"province": {
  "$ref": "#/definitions/TypeKeyReference",
  "description": "The province of the location's address. Only applicable in certain countries.",
  "nullable": true,
  "title": "Province",
  "x-gw-createOnly": true,
  "x-gw-filterBy": [
    "country"
  ],
  "x-gw-typelist": "State"
},
"state": {
  "$ref": "#/definitions/TypeKeyReference",
  "description": "The state of the location's address. Only applicable in certain countries.",
  "nullable": true,
  "title": "State",
  "x-gw-createOnly": true,
  "x-gw-filterBy": [
    "country"
  ],
  "x-gw-typelist": "State"
}