Schema properties usage

The following topics provide detailed descriptions and examples that will help in understanding the properties returned in the business entity schemas. See Schema properties overview for a list of properties that are specific to these schemas.

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"
    },

Special child types

Some of the entity children in PolicyCenter need special product model metadata. The primary use case for this is for creating user interface elements, which in some cases have special components associated with them. Those children can be one of the following types:

  • coverage
  • scheduledItem
  • questions

To distinguish these types of children, each one has the type indicator property childType. For example, the Job entity might include the following children:

"Job": {
  ...
    {
      "id": "Note",
      "urlPart": "notes"
    },
    ...
,   {
      "childType": "questions",
      "id": "PolicyQuestions",
      "urlPart": "questions"
    },
    ...

Notice that the child PolicyQuestions has a childType property. There is no childType property on Notes because Notes are not among the types of children requiring special components.

Policy line children

The entity schema treats policy lines as direct child properties of the Job entity. This relationship is shown in the schema by including the policy line child on the Job with a urlPart property that includes “lines”. The following example shows the PersonalAutoLine child of the Job:

"Job": {
  ...
  "x-gw-children": [
    ...
    {
      "description": "Personal Auto",
      "graphProperty": "PersonalAutoLine",
      "id": "PersonalAutoLine",
      "title": "Personal Auto Line",
      "urlPart": "lines/PersonalAutoLine"
    },

Notice the urlPart property is set to lines/PersonalAutoLine.

Choice values

For entities that contain choice values, the entity schema returns the x-gw-choices object. You must include the query parameter inlineTypelists set to true to retrieve this object. The object contains the following properties:

Property

Description

Used with
code

The unique identifier for the choice.
  • Typelists
  • Option/package choices
  • Coverage term choices
name

The name of the choice.
  • Typelists
  • Option/package choices
  • Coverage term choices
description

The description of the choice.
  • Typelists
  • Option/package choices
  • Coverage term choices
sortOrder

The canonical sort order for the choice, relative to other choices in the same list.
  • Typelists
  • Option/package choices
  • Coverage term choices
categories

A list of strings that indicate the categories the typekey belongs to. Categories are presented in the form Typelist.​Code, such as Country.​US.
  • Option/package choices
  • Coverage term choices
values

An array of additional values relating to coverage terms.
  • Coverage term choices

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.

Coverage term choices

When the inlineProductDefinition query parameter is set to true, additional values are returned in the schema for coverage term choices. Coverage terms include option and package terms that offer choices in the form of numerical values. For an option term, there's one numerical value per choice, whereas for a package term there can be more than one. In addition, a package term such as "100/250" might represent the numbers 100 and 250, or they might actually be 100,000 and 250,000.

To distinguish between option terms and package terms, the x-gw-choiceType field is included on the choiceValue property. Possible values are option and package.

"choiceValue": {
   "$ref": "#/definitions/ProductModelChoice",
   "description": "The value of this term as an enumerated choice. Only applicable if the `covTermType` is `choice`.",
   "nullable": true,
   "title": "Choice value",
   "x-gw-choiceType": "option",

Because the coverage terms typically involve monetary amounts, the currency field is included on each x-gw-choices array element.

"x-gw-choices": [
  {
    "code": "00",
    "currency": "usd",
    "name": "No Deductible",

Each x-gw-choices array element also includes a values array. For option terms there will only ever be one value in the array. Package terms can have multiple values. Each value in the array can have the following fields:

Field

Description

Examples

Applies to
aggregationModel

A typecode value that indicates how a limit or deductible needs to be aggregated during claims handling.
  • pp (per person)
  • ea (each)

Option and package terms
name

The name of the value. The name explains what that part of a package value means.

 Bodily injury per-person limit

Package terms
restrictionModel

A typecode value that indicates what sort of exposure the term applies to.
  • bi (bodily injury)
  • pd (property damage)

Option and package terms
value

A string containing the actual value.
  • 5000.​0000
  • 0

Option and package terms
valueType

What the value number represents
  • money
  • count
  • other

Option and package terms

The following are examples of option and package term choice values.

Option term values:

"x-gw-choiceType": "option",
  "x-gw-choices": [
  {
    "code": "00",
    "currency": "usd",
    "name": "No Deductible",
    "sortOrder": 0,
    "values": [
      {
        "aggregationModel": "po",
        "restrictionModel": "prp",
        "value": "0",
        "valueType": "money"
      }
    ]
  },

Package term values:

"x-gw-choiceType": "package",
  "x-gw-choices": [
    {
      "code": "0/0/5",
      "currency": "usd",
      "name": "0/0/5",
      "sortOrder": 5,
      "values": [
        {
          "aggregationModel": "pp",
          "name": "PA_person_agglimit",
          "restrictionModel": "bi",
          "value": "0",
          "valueType": "money"
        },
        {
          "aggregationModel": "ea",
          "name": "PA_accident_agglimit",
          "restrictionModel": "bi",
          "value": "0.0000",
          "valueType": "money"
        },
        {
          "aggregationModel": "ea",
          "name": "PA_property_agglimit",
          "restrictionModel": "pd",
          "value": "5000.0000",
          "valueType": "money"
        }
      ]
    },

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.

Note: See Rules and Forbidden fields for more information.

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",
              ...

Coverage category

The x-gw-coverageCategory property is attached to the coverage in the schema. It provides the following information about the coverage category:

  • code: The coverage category code.
  • description: A description of the coverage category.
  • name: The name of the coverage category.
  • sortOrder. The sort order. See Sort order for more information.

The following is an example of a coverage category as it appears in the schema. In this case, it describes the coverage category in the base configuration Personal Auto line for collision (PACollisionCov) coverage.

"x-gw-coverageCategory": {
  "code": "PAPPhysDamGrp",
  "description": "Personal Auto Physical Damage Group",
  "name": "Personal Auto Physical Damage Group",
  "sortOrder": 50
}

This property is included with the schema only when the inlineProductDefinition query string is set to true.

Coverage parent/child dependencies

Coverages in PolicyCenter have clauses, which can have subclauses. In some cases a subclause can be applied to a coverage only if its parent clause has been selected. For example, Liability coverage could have a subclause of Bodily Injury. You can’t apply Liability for Bodily Injury if you haven’t selected Liability coverage.

You must set the inlineProductDefinition query parameter to true to see these dependencies. If you don’t set this parameter to true, the *Coverages schemas (such as PersonalAutoLine_Coverages) that contain these dependencies aren’t included in the response.

The entity schema tracks subclause requirements through rules. If a child entity (the subclause) cannot be added without the parent entity (parent clause), a rule such as the following is attached to the *_Coverages schema that contains the properties for each individual coverage:

"x-gw-rules": [
  {
    "jsonLogic": {
      "if": [
        {
          "!==": [
            {
              "var": "TSTParentCov.selected"
            },
            true
          ]
        },
        {
          "x-gw-dynamicPropertiesMarker": true,
          "x-gw-forbidden": [
            "TSTChildCov"
          ]
        }
      ]
    }
  },

In this example, the rule is checking to see if the selected property on the parent entity (TSTParentCov) is not true (meaning the parent clause has not been selected). If that’s the case, the child coverage (TSTChildCov) is listed as forbidden.

See Rules for more information on working with rules. See Forbidden fields for more information on the x-gw-forbidden property.

Covered location field

The x-gw-coveredLocationField property applies to location properties that are automatically added to a covered location, such as "addressLine1" or "city". The purpose of this property is to differentiate address information for a covered location from LOB-specific additions. Every schema property that is inherited from the CoveredLocationBase schema definition is marked as true.

"x-gw-coveredLocationField": true

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.

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
},

Owning policy line

If an entity is associated with a particular policy line pattern, the x-gw-owningPolicyLine property will contain the ID and name of that policy line. In this example, the entity is associated with the Personal Auto policy line:

"x-gw-owningPolicyLine": {
  "id": "PersonalAutoLine",
  "name": "Personal Auto Line"
},

No query parameters are required in the API command to retrieve this property.

Owning products

If an entity is LOB-specific, the x-gw-owningProducts property will contain an array of products that include that entity. In this example, the entity is part of the PersonalAuto product:

"x-gw-owningProducts": [
  {
    "id": "PersonalAuto",
    "name": "Personal Auto"
  }
]

No query parameters are required on the command to retrieve this property. However, if you include the product query parameter, all entities returned will either not have any owning products or will contain the specified product in the x-gw-owningProducts array.

Product definition properties

When the inlineProductDefinition query parameter is set to true, the following additional properties are returned inline with the schema:

  • x-gw-coverages
  • x-gw-answers
  • x-gw-scheduledItems

Only defined properties are returned. For example, if there are no scheduled items, the x-gw-scheduledItems property is not in the response schema.

The product definition properties contain a $ref property, which references the appropriate schema definition. Here’s an example for a coverage:

"x-gw-coverages": {
  "$ref": "#/definitions/PersonalAutoLine_Coverages"
},

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.

  • requiredForBind: The property must have a value for a job to bind.
  • requiredForCreate: The property must have a value for an entity to be created.
  • requiredForQuote: The property must have a value for a job to be quoted.
  • 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:

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"
  }
},

Segments

Fields of type "segment" in Advanced Product Designer (APD) are special in that they can cause the product edition to change. Because of this, a user interface (or any other consumer) might need to treat those fields specially if they're edited, in case the edition (and thus the appropriate edition-related rules) changes as a result.

Segment fields are shown in the schema with the x-gw-segmentField property set to true.

"x-gw-segmentField": true

Sort order

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

x-gw-sortOrder

APD attaches a sequence number to every coverable field. The entity schema preserves that ordering through the x-gw-sortOrder property.

In this example, the PersonalVehicle entity has been configured so Annual Mileage is ordered before Basis Amount, followed by Body Type, and so on.

"PersonalVehicle": {
  "description": "Personal Vehicle",
  "properties": {
    "annualMileage": {
      "description": "Annual miles for this vehicle",
      "nullable": true,
      "title": "Annual Mileage",
      "type": "integer",
      "x-gw-sortOrder": 1
    },
    "basisAmount": {
      "description": "Basis Amount",
      "nullable": true,
      "title": "Basis Amount",
      "type": "integer",
      "x-gw-sortOrder": 2
    },
    "bodyType": {
      "$ref": "#/definitions/TypeKeyReference",
      "description": "Body type of the vehicle.",
      "nullable": true,
      "title": "Body Type",
      "x-gw-filterBy": [
        "vehicleType"
      ],
      "x-gw-sortOrder": 3,
      "x-gw-typelist": "BodyType"
    },

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.

Tags

In APD, you can attach tags to most things that can be modeled, such as:

  • Clauses
  • Clause terms
  • Clause term choices (options, packages, or typekeys)
  • Risk object fields
  • Risk object field choices (typekeys)

See Product Designer Guide for more information on applying tags in APD.

Tags consist of a particular code that either applies or does not apply. Tags can also have rules, such that they apply conditionally.

Tags are represented in the entity schema via the x-gw-tags object, where each property is the code for a tag, and the value of each code is an object with a single applies Boolean property. If a tag has no conditions, x-gw-tags is attached directly to the resulting schema. If the tags do have conditions, the associated rules are in the x-gw-rules array, and the tag-related rules produce JSON schema fragments that contain the x-gw-tags object. See Rules for more information on working with rules.

Tags are returned with the entity schema only when the editionCode query parameter is included with the command. (See Business entity schema query parameters for more information.)

This example shows tags as part of a rule on a coverage. In this case, if this property is less than 100, it’s rateable (rate is applicable), otherwise it’s not rateable (rate is not applicable).

"x-gw-rules": [
  {
    "jsonLogic": {
      "if": [
        {
          "<": [
            {
              "uri": "/jobs/{jobId}/lines/PersonalAutoLine/integerProperty"
            },
            100
          },
          {
            "x-gw-tags": {
              "rate": {
                "applies": true
              }
            }
          },
          {
            "x-gw-tags": {
              "rate": {
                "applies": false
              }
            }

This example shows a tag that is not conditional:

"name": {
  "description": "Name field",
  "maxLength": 255,
  "minLength": 1,
  "nullable": true,
  "x-gw-tags": {
    "rate": {
      "applies": true
    }
  }
},

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"
}

Value properties

The x-gw-valueProperty property is in the schema attached to terms, scheduled item properties, and answers. This property provides the name of the property that actually stores the term, scheduled item property, or answer value. This makes it easier to determine the term, scheduled item property, or answer type without having to parse through the other properties.

For example, this schema excerpt shows a term named PAMedLimit. The x-gw-valueProperty is set to “choiceValue”, so you know that for this particular term you need to look for the choiceValue property to get or set the value of the term.

"terms": {
  "description": "The terms of a coverage",
  "properties": {
    "PAMedLimit": {
      "properties": {
        …
        "choiceValue": {
          "$ref": "#/definitions/ProductModelChoice",
          …
          "x-gw-choices": [
            …
          ],
        },
      },
    },
    …
    "x-gw-valueProperty": "choiceValue"
},

This property is only relevant to schemas created for product model entities, and therefore it will only appear when the inlineProductDefinition query parameter is set to true.