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 characterstics 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 maintaned 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
replacementTimestampand 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
coverageStartTimestampbefore date X and a
coverageEndTimestampafter date X
Then, exclude all those that have a non-null
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 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 objects come in three types, each associated with a primary object:
All of the characteristics objects have a set of basic timestamp fields:
coverageStartTimestampfor peril characteristics)
coverageEndTimestampfor 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.
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
The Modifications topic describes how characteristics and modifications are releated, and how to get information about the policy transactions that caused characteristics to change.