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. |
|
name |
The name of the choice. |
|
description |
The description of the choice. |
|
sortOrder |
The canonical sort order for the choice, relative to other choices in the same list. |
|
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. |
|
values |
An array of additional values relating to coverage terms. |
|
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. |
|
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. |
|
Option and package terms |
value |
A string containing the actual value. |
|
Option and package terms |
valueType |
What the value number represents |
|
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.
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
ortypekeyValue
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
.