Adding one-to-ones

A one-to-one relationship is a relationship that two entities have. One acts as the parent, and the other as the child. For the parent, each instance may have an association with up to one instance of the child entity. For the child, each instance must be associated with exactly one parent.

The Guidewire data model supports a <one-to-one> element. This element enforces the parent's "up-to-one" cardinality and the child's "exactly-one" cardinality. Many one-to-one relationships are implemented using this element. However, in some situations, the one-to-one relationship is built using only a <foreignKey> element.

Common use cases

A common use case for one-to-one relationships is to separate extension fields that apply to only a sufficiently small subset of the entities. This is done to avoid database tables that are wide and sparsely populated.

For example, suppose an insurer has a regulatory requirement to have a set of activities periodically reviewed by the insurer's legal team. There are several fields needed to track this legal review, but they are applicable to only about 5% of all activities.

The insurer could add these fields directly to the Activity entity. But given that so few activities need these fields, this would make the xc_activity table in the database wider and more sparsely populated.

To improve database performance, the insurer opts to create a second entity, ActivityLegalInfo_Ext, which has a one-to-one relationship with Activity.

  • The Activity entity is the parent. Each activity can be associated with up to one ActivityLegalInfo_Ext.
  • ActivityLegalInfo_Ext is the child. Each instance must be associated with exactly one Activity.

A common use case in ClaimCenter involves damageables. A damageable is an object that stores information about a covered item that is inherent to the covered item before any loss has occurred. For example, Vehicle is a damageable. It is an item that can be covered on a policy, and it stores information about the vehicle that is inherent to the vehicle itself, such as Make, Model, and LicensePlate.

Risk units and incidents can have one-to-one relationships with a corresponding damageable. For example:

  • VehicleRU has a one-to-one relationship with Vehicle, where VehicleRU is the parent.
  • VehicleIncident has a one-to-one relationship with Vehicle, where VehicleIncident is the parent.

Inline objects: Foreign key fields

In Cloud API, foreign key relationships follow a typical pattern:

  • Typically, there are CRUD endpoints for both the parent and the child.
  • The child appears in the parent schema using the SimpleReference schema. (This schema has a small set of fields applicable to all entities, such as displayName, id, type, and uri.)

For example, the Activity entity has an assignedUser field, which is a foreign key that references User.

  • There are CRUD endpoints for both Activity and User.
  • In the Activity schema, there is an assignUser field which includes information about the associated User. It uses the SimpleReference schema, as shown in the example below.
"attributes": {
    "activityPattern": "contact_insured",
    "assignedUser": {
        "displayName": "Andy Applegate",
        "id": "demo_sample:1",
        "type": "User",
        "uri": "/admin/v1/users/demo_sample:1"
    },
    "id": "cc:SO8RJJZtEa-Tyqlrxw97y",
    "subject": "Contact insured"
},

Inline objects: One-to-one fields

One-to-one relationships follow a different pattern:

  • Typically, there are CRUD endpoints for the parent only.
    • Because there are no separate endpoints for the child object, all operations on the child take place in the context of the parent. You GET the child along with the parent. When you POST the parent, you can also POST the child.
  • The child appears in the parent schema as an inline object. The inline object can include any set of fields from the child entity.

For example, an insurer extends the data model so that the Activity entity shared a one-to-one relationship with a custom ActivityLegalInfo_Ext entity.

  • There are CRUD endpoints for Activity.
  • There are no CRUD endpoints for ActivityLegalInfo_Ext.
  • In the Activity schema, there is an ActivityLegalInfo_Ext field which includes information about the associated ActivityLegalInfo_Ext. It is an inline object and includes a custom set of fields from the child entity, as shown in the example below.
"attributes": {
    "activityLegalInfo_Ext": {
        "id": "cc:S2qhgxij6HvhXz6K3t39K",
        "legalCaseNumber": "0003",
        "legalReviewDate": "2022-05-05T07:00:00.000Z"
    },
    "activityPattern": "contact_insured",
    "assignedUser": {
        "displayName": "Andy Applegate",
        "id": "demo_sample:1",
        "type": "User",
        "uri": "/admin/v1/users/demo_sample:1"
    },
    "id": "cc:SO8RJJZtEa-Tyqlrxw97y",
    "subject": "Contact insured"
},