Characteristics

Overview

The canonical object model for policy information in Socotra looks something like this:

This is simple, but things get more complicated when you consider revisions to these objects. For example, consider an endorsement that changed a peril to increase its deductible from $500 to $1000. This effectively splits the peril, with the pre-endorsement part of the peril being tagged with the $500 value, and the later part being tagged with $1000. In Socotra, this is accomplished using a data structure called characteristics, which is an array of sets of values associated with each primary object. So the “real” data model in Socotra after the endorsement now looks like this (looking at only one exposure and peril for brevity):

Note that each primary object (policy, exposure, peril) now has two characteristics objects attached to it. One of the characteristics objects holds the data for the time before the endorsement, and the other applies to the time after the endorsement. But it’s even more complicated than that: we don’t actually throw away the original characteristics; those are still maintained although they are now marked has having been replaced. So here’s the picture again, but now including replaced characteristics (and abbreviating “characteristics” as “ch”):

So, with every endorsement, a characteristics object is split, which means: marking it as having been replaced, and adding two new characteristics objects to represent the before and after state. And, each characteristics object contains timestamps for its effective and expiration time, as well as its create time and replacement time. This means that we can tell, as of any date, what the coverages were for that policy at the time.

For example, to know what the policy looked like, as if you were looking at it on some date X in the past:

Start with all characteristics that have been created before date X
Then, exclude those that were replaced before date X (i.e. have a replacementTimestamp and that replacementTimestamp is less than the timestamp for date X)

Alternatively, to find out whether coverage is in effect for date X based on the policy definition as of today:

Start with all peril characteristics that have a coverageStartTimestamp before date X and a coverageEndTimestamp after date X
Then, exclude all those that have a non-null replacementTimestamp

Note

Sometimes characteristics objects are replaced with only one additional object, such as for a simple extension or truncation of the term, or when the endorsement becomes effective precisely at the original start time. Also not all characteristics will be split if their data doesn’t change. For example, if the policy characteristics’ data doesn’t change it won’t be split. Likewise, if there are no changes on an exposure then that exposure’s characteristics won’t be split even if one of its peril’s characteristics does split.

Characteristics’ Data

Characteristics objects come in three types, each associated with a primary object:

Primary Objects and Characteristics

Primary Object

Characteristics Object

PolicyResponse

PolicyCharacteristicsResponse

ExposureResponse

ExposureCharacteristicsResponse

PerilResponse

PerilCharacteristicsResponse

All of the characteristics objects have a set of basic timestamp fields:

createdTimestamp
updatedTimestamp
startTimestamp (called coverageStartTimestamp for peril characteristics)
endTimestamp (called coverageEndTimestamp for peril characteristics)
issuedTimestamp (if the characteristics object has been issued)
replacedTimestamp (if the characteristics object has been replaced)

The timestamp data indicates if and when that particular set of characteristics is in force.

In addition, each characteristics object has a locator and a set of fields, field groups, and media.

The PolicyCharacteristicsResponse has additional aggregate tax and fee totals.

The PerilCharacteristicsResponse has premium for that particular peril/time combination, as well as several fields for deductibles and limits. It also has the rate used to calculate the premium, stored as monthPremium.