Retrieve a business entity schema

The entity-schemas and graph-schema endpoints both return a JSON representation of business entities. The information returned is similar to what you would find in the swagger and openapi endpoints, but with additional metadata. (See Viewing API definitions for information on the swagger and openapi endpoints.)

As a general rule, use graph-schema if you're consuming a graph, such as from AppEvents. Use entity-schemas if you want a schema for everything in the API, or you want to use one endpoint that works across all InsuranceSuite applications.

Retrieve an entity schema

The entity-schemas endpoints return one or more complete product schemas. They can also be filtered to target specific sets of entities. For more information on query parameters, see Business entity schema query parameters.

Use the following command to retrieve a JSON-formatted entity schema:

GET /common/v1/entity-schemas

To retrieve the schema for a single entity, use the following command:

GET /common/v1/entity-schemas/{entityId}

For example, you can return the schema for the User entity with the following command:

GET /common/v1/entity-schemas/User
Java

The schema returned by the entity-schemas/{entityId} endpoint returns the schema for the specified entity and other schemas transitively referenced from that entity. In the preceding example, in the base configuration the returned entity schema would include User, plus related schemas such as UserGroupReference and UserRoleReference. However, it won’t return the schemas for any child entities. Instead it will return a list of children (if any) in the x-gw-children property for each entity. (See "Child entities" in Schema properties usage for more information.)

To retrieve a specific entity along with the complete schema information for all its children, filter the entity-schemas endpoint on rootEntity:

GET /common/v1/entity-schemas?filter=rootEntity:eq:{entityId}

Filtering on rootEntity retrieves a more detailed schema than using the entity-schemas/{entityId} endpoint by traversing the entity graph tree and including all the child entities of the specified entity.

Retrieve a graph schema

The graph-schema endpoint returns a graph schema. A graph schema is a JSON representation of one or more logical entities and their children.

Use the following command to retrieve a graph schema:

GET /job/v1/graph-schema?product={productId}

Note that the product query parameter is required. For more information on query parameters, see Business entity schema query parameters.

The response returned by the graph-schema endpoint is a JSON Schema Draft-7 document that contains schema definitions for the primary business object graphs for the application. The schema definitions are similar to the schema definitions found in the API schemas and entity-schemas endpoints, but will include additional properties that embed child objects in their parents. For example, an entity accessed through an endpoint as /entity with a child accessed as /entity/{entityId}/entityChild would be represented in the graph schema as an "Entity" definition with an "entityChild" property.

The schema returned in the response can contain multiple logical "graphs." However, it does not return all entities. For example, Admin entities such as User are not included in the graph-schema response. To retrieve all entities, use the entity-schemas endpoint.

The following command retrieves a graph schema with entities such as Account, Coverage, Job, and (for a sample PersonalAuto product) PersonalVehicle.

Command

GET /job/v1/graph-schema?product=PersonalAuto
Java

Response

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "Account": {
      "description": "An `Account` represents a person or company that applies for or purchases insurance from the insurer",
      "properties": {
        "accountHolder": {
        …
    "Coverage": {
      "description": "A `Coverage` represents a clause in the policy contract. It can represent a coverage, exclusion, or other condition that is part of the policy.",
      "properties": {
        …
    "Job": {
      "description": "A `Job` represents a policy transaction that creates or alters an insurance policy. Each specific type of job is represented by a different `jobType` that represents the specific type of transaction, such as a `Submission` to create a new policy or a `Renewal` to renew the policy.",
      "properties": {
        …
    "PersonalVehicle": {
        …
Java