Data Model

Universal Data Model

A normalized insurance schema underlying every Insurance Blueprint form: parties carry roles, anything insurable is one general entity, coverages are typed, and endorsements are attached forms. One integration handles every line of business.

IBP-DM-002

Insurance Blueprint Universal Data Model

A single normalized schema for all forms. Instead of flat, form-shaped fields, it models the real insurance entities — party + role, a general insurable, typed coverage, and form (endorsement) attachments — so it maps cleanly onto a carrier policy system.

Envelope (top-level)

Field Type Notes
form_idstringIBP form identifier
form_typeenumPOI, COI, GL_APP, HO_APP…
form_editionFormRefform_number + edition token
effective_dtdatePolicy start (v4 effective_dt)
expiration_dtdatePolicy end (v4 expiration_dt)
policy_identifierstringCarrier policy number
lob_major_cdcodelistPersonal, Commercial, Life, Health, Annuity
lob_minor_cdcodelistPrefixed sub-line, e.g. Personal/Automobile
partiesPartyRole[]Party + role (named insured, carrier, cert holder…)
insurablesInsurable[]Objects, persons, or activities being insured
coveragesCoverage[]Typed; each covers an insurable
signatureSignature?Optional e-signature block

No vehicles[], locations[], named_insured, certificate_holder, or endorsements: string[] fields — those are all expressed through the entities below.

PartyRole (party + role)

role: enum // named_insured, additional_insured, certificate_holder, carrier, producer, mortgagee, lienholder, beneficiary, driver, owner, other
is_primary_ind: bool
relationship_to_insured: enum? // self, spouse, child, employee…
party: Party

Party

party_type: enum // person, organization
display_name: string
addresses: Address[]
identities: Identity[] // SSN, FEIN…
identifiers: Identifier[] // NAIC, NPN…
licenses: License[] // producer, DL…
contact: Contact?

Insurable (anything at risk)

insurable_identifier: string // stable key coverages reference
insurable_type: enum // object, person, activity
insurable_subtype: enum // vehicle, dwelling, building, aircraft, watercraft, equipment, server, cargo, event…
party_ref: ref? // when the insurable is a person
address: Address?
attributes: map // year/make/model, construction, year_built…
identifiers: Identifier[] // VIN, serial, tail #

Coverage

coverage_cd: codelist // INS/US/PERS/BI, INS/US/COMM/GL…
insurable_identifier: ref? // the insurable it covers
limit_per_occurrence_amt: money
limit_aggregate_amt: money?
deductible_amt: money?
premium_amt: money?
forms: FormRef[] // attached endorsements

FormRef (endorsement = a form)

form_number: string // e.g. HO 04 90
edition: string // edition token, e.g. 09 08
is_base_form_ind: bool // 0 = endorsement, 1 = base/jacket
title: string?
attachment_reason: string?

Identity / Identifier / License

// Identity — permanent, never expires
identity_type: enum // ssn, fein, tin, birth_date
value / last4: string
// Identifier — registry-assigned
identifier_type: enum // naic, npn, duns, policy_number, vin
value, issuing_authority: string
// License — issued, expires, revocable
license_type: enum // drivers, producer, adjuster, professional
number, issuing_state: string
issued_dt, expiration_dt: date · status: enum

Address

address_type: enum // mailing, physical, garaging…
line1, line2: string
city, state_cd, postal_code, country_cd: string
IBP-DM-002 — Universal Data Model
v2.0.0 • JSON Schema, XML Schema • Normalized entity model with migration guide from v1
JSON Schema (Member) XML Schema (Member) Full Docs (Member)
Design Principles

Model the entities, not the paperwork

Parties Carry Roles

A named insured, additional insured, certificate holder, and carrier are one Party playing a role — not three different shapes. Add a role, not a new entity.

One General Insurable

A car, a house, an airplane, a server, or a concert are all an Insurable with a subtype. Coverage points at what it covers — no per-line vehicles[]/locations[] arrays.

Endorsements Are Forms

An endorsement is a real, editioned FormRef attached to a coverage — drawn from the IBP forms catalog — not an opaque string code.

Carrier-System Naming

Identity vs identifier vs license are distinct. Dates are effective_dt/expiration_dt, money is *_amt, booleans are *_ind — so the model maps straight onto a policy database.

Versioning

Semantic versioning with migration guides

The Universal Data Model uses semantic versioning (MAJOR.MINOR.PATCH). Breaking changes increment the major version and ship with a migration guide.

MAJOR
Breaking changes.
Migration guide required.
MINOR
New fields added.
Backward compatible.
PATCH
Doc fixes only.
No schema change.
Current version: 2.0.0 • Released 2026-08-30 • breaking realignment from v1 (flat) to the normalized entity model; v1→v2 migration guide included