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. However, you cannot specify the editionCode when you specify more than one product. 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.

includePolicyEntities

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, x-gw-scheduledItems, x-gw-actions, x-gw-canonicalCollectionUri, x-gw-canonicalElementUri, x-gw-canonicalParent, and x-gw-children.
• 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

packageId

The packageId query parameter specifies the package to load the requested edition from. If no packageId is provided, the entity schema loads the requested edition from the current active package associated with this PolicyCenter instance.

This query parameter cannot be used without also specifying the editionCode and product query parameters. This query parameter only applies to only applies to installed products managed in APD.

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

product

The product query parameter filters the returned schema entities based on the products 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 products 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

You can specify more than one product by including multiple product IDs in a comma-separated list.