Business entity schema query parameters

editionCode

Use the editionCode query parameter to enrich the schema with additional information based on the rules for that edition. When fetching the schema with an edition specified, the schema properties are adjusted based on changes that have been made in that edition, such as to whether coverage options are available or what a field's maximum value can be. For changes made in the edition that do not have any rule conditions, the associated schema element will be changed directly. For example, if an integer field has a maximum set to 10000 for a given edition, the schema property for that field will have "maximum": 10000 added to it. If the change is conditional, it will result in a rule added to the x-gw-rules schema property. See Rules for more details.

The product parameter must also be included in the query string, because editions are tied to products. (For more information on editions, see "Editons for product lines" in "Advanced Product Designer in PolicyCenter".)

• GET /common/v1/entity-schemas?editionCode={editionId}&product={productId}

For example, to retrieve the entity schema for the BaseEditon edition of the PersonalAuto product, use the following command:

GET /common/v1/entity-schemas?editionCode=BaseEdition&product=PersonalAuto

If the specified edition doesn’t match a valid edition for the requested product, the request will fail.

To allow for testing of existing products that have been defined with rules but no editions, the edition code BaseEdition is a valid code for visualized products. In that case, the main template serves as the base edition. The BaseEdition code is also accepted for cloud-synced installed lines managed via Advanced Product Designer (APD), since APD always creates a base edition.

To retrieve a list of editions available for a product, use the productdefinition API:

• GET /productdefinition/v1/products/{productId}/editions

See Product definitions for products for more details on the productdefinition API.

includeLocalizations

The includeLocalizations query parameter includes localized versions of all strings in the schema response. Any element that can be localized will include an x-gw-localizations property containing localized versions of the associated schema property. (If no localized version for a given language exists, the value will be provided in the default language.)

The localized languages that are displayed depend on the value assigned to the parameter. You can retrieve localized strings for all installed languages (languages in the LangaugeType typelist) by assigning the *all value to the parameter.

To retrieve localized strings for only specific languages, include the language code as the value. The language code can be in any of the following formats:

• Language code, such as fr (French).

• Language and region, such as fr-CA (French, Canada) or fr-FA (French, France).

• Language and region with either a hyphen or an underscore. Both fr-CA and fr_CA will return French (Canada) localized strings.

Note that the value is case-sensitive; you’ll receive an error if the installed language is en_US and you specify en_us.

Only installed languages can be specified. If you set a value to a language that is not installed you’ll receive an error.

The following examples show different options for calling includeLocalizations:

Retrieve localized values for all installed languages:

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

Retrieve localized values for US English:

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

Retrieve localized values for all versions of French:

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

Retrieve localized values for English and French (Canada):

GET /common/v1/entity-schemas?includeLocalizations=en,fr_CA

For details on the schema structure, see Localizations.

inlineProductDefinition

Setting the inlineProductDefinition query parameter to true will cause information about coverages, answers, and scheduled items to be inlined into the returned schema. The product parameter must also be included in the query string.

• GET /common/v1/entity-schemas?inlineProductDefinition=true&product={productId}

The top-level properties x-gw-coverages, x-gw-answers, and x-gw-scheduledItems are returned in the schema. These function as if they were schema property definitions, with a $ref property that references the appropriate schema definition.

See Product definition properties for more information.

inlineTypelists

The inlineTypelists query parameter is used to include typelist metadata for each typekey field or term so that typelist metadata doesn’t need to be fetched separately. Set inlineTypelists to true to enable this feature.

• GET /common/v1/entity-schemas?inlineTypelists=true

See Choice values for more information and schema examples.

onlyReturnChangedSchemas

This query parameter cannot be used without also specifying the editionCode and product query parameters. If onlyReturnChangedSchemas is set to true, only schema definitions that have changed between the edition specified by the editionCode and the base product are returned.

• GET /common/v1/entity-schemas?editionCode={editionId}&product={productId}&onlyReturnChangedSchemas=true

product

The product query parameter filters the returned schema entities based on the product specified.

GET /common/v1/entity-schemas?product={productId}

If product is set to a non-null value, entities that match the specified product and all non-product specific entities will be returned. If product is set to null, only non-product-specific entities will be returned. Here are some examples.

Return only non-product specific entities:

GET /common/v1/entity-schemas?product=null

Return entities for the PersonalAuto product:

GET /common/v1/entity-schemas?product=PersonalAuto

If product is used along with the inlineProductDefintion parameter, the product value will be used to determine which product to use for Job, PolicyLocation, and PolicyLine questions (and anything else that attaches to the product).