Business entity schema query parameters
The following table includes query parameters that are specific to business entity schemas. For each parameter, a short description is provided along with possible values. Also listed for each parameter are any other parameters that must be included in order for the given parameter to be used. See below for detailed descriptions of each.
Parameter |
Description |
Values |
Other parameters required |
---|---|---|---|
editionCode |
Enriches the schema based on the rules in the specified product edition. |
{editionId} |
product |
includeLocalizations |
Include localization strings in the schema for all localizable strings for the specified installed languages. |
|
none |
inlineProductDefinition |
Include information about coverages, answers, and scheduled items inline in the schema. |
Boolean |
product |
inlineTypelists |
Include typelist values in the schema. |
Boolean |
none |
onlyReturnChangedSchemas |
Return only schema definitions that have changed between the specified edition and the base product. |
Boolean |
|
product |
Return the schema for the specified product and any non-product specific entities. Use null to retrieve only non-product schema entities. |
|
none |
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).