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 "Editions 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 Product Definition API:

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

See Product definitions for products for more details on the Product Definition 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}
• GET /job/v1/graph-schema?inlineProductDefinition=true&product={productId}

The following top-level properties are returned in the schema:

• entity-schemas endpoint: x-gw-coverages, x-gw-answers, x-gw-modifiers, and x-gw-scheduledItems
• graph-schema endpoint: coverages, answers, modifiers, and scheduledItems

These properties function as if they were schema property definitions, with a $ref property that references the appropriate schema definition.

Note that these properties are always returned by the graph-schema endpoint, even if you don't set the inlineProductDefinition query parameter to true. However, without this parameter the $ref points to a generic schema. When you set inlineProductDefinition to true, the $ref points to specific schema definitions created for each coverable.

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
• GET /job/v1/graph-schema?product={productId}&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}
• GET /job/v1/graph-schema?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. The product query parameter can be set to null only on the entity-schemas endpoint; the graph-schema endpoint must have a valid productId specified. Here are some examples.

Return only non-product specific entities:

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

This option is available only for the entity-schemas endpoint. The graph-schema endpoint must include a valid product.

Return entities for the PersonalAuto product:

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

GET /job/v1/graph-schema?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).

Return entities for the PersonalAuto and GeneralLiability products:

GET /job/v1/graph-schema?product=PersonalAuto,GeneralLiability

When using the graph-schema query parameter, you can specify more than one product by including multiple product IDs in a comma-separated list. This option is not available with the entity-schemas endpoint.