Model the domain, not the message.

The argument, up front

It is a tempting shortcut: the payload is concrete, it is right there, and it is “the data we actually have.” But a message is one system’s projection of one interaction, shaped by a protocol. Its structure — envelopes, arrays, embedded copies, string-typed codes — exists to serialize, not to describe. Reverse-engineer classes and properties from it and every one of those accidents becomes a modelling commitment you did not mean to make.

This brief is the companion to Start with the questions. That one names what should drive a module — the questions the business must answer. This one names what must not: the shape of the messages that happen to move the data around.

The message and the domain are different kinds of thing, and conflating them is a category error — the same family of mistake a well-built ontology guards against (has-a, not is-a, for terms; no serialization-shaped intersections). Read a payload field by field and you will find that most of what is there is about the transmission, not about insurance.

What the payload carries vs. what the domain means

Two whole rows map to nothing: envelopes and correlation metadata belong to the message, and importing them pollutes an ins/ module with plumbing. The rows that do map, map differently — because the domain has identity, typed concepts, and open-world semantics that a flat payload throws away.

Beyond the field-by-field leaks, letting the message’s shape drive the model does structural damage that is hard to undo later.

The same policy fact, modelled two ways

If one idea explains all the rest, it is this. A message is a tree: hierarchical containment, chosen for self-contained transport. A domain is a graph: shared entities identified once and pointed at from many places. Derive structure from the tree and you fragment exactly the identity the graph exists to unify.

The message and the domain both have a place. The trick is to keep them in separate layers and connect them with an explicit mapping, so each can change on its own clock.

What each layer looks like

# ✗ Shape dictated by the payload — accidents become axioms
msg:ClaimBatch   a owl:Class .                # an envelope, not a thing
msg:hasItem      a owl:ObjectProperty .       # the "items[]" wrapper
msg:party        a owl:DatatypeProperty ;     # insured embedded as a blob
                 rdfs:range xsd:string .
msg:premium      rdfs:range xsd:decimal .     # money flattened; currency lost
msg:correlationId a owl:DatatypeProperty .   # transport cruft in the domain

# ✓ Shape dictated by the domain — shared identity, typed concepts
claim:Claim        rdfs:subClassOf core:Event ;
                 policy:underPolicy  ?policy .    # link by IRI — one shared Policy
claim:claimant     rdfs:range claim:Claimant .   # a Party in a reified role
coverage:hasPremium rdfs:range coverage:Premium . # Premium ⊑ core:MoneyAmount

The payload still reaches the graph — but as a mapping, not as a schema. An items[] array becomes a set of claim:Claim individuals; a repeated party block resolves to a single IRI; "amount": 500.00 plus a currency code lifts to a core:MoneyAmount. The envelope and the correlation id are simply dropped at the boundary, where they belong.

None of this means ignore the messages. They are among your best inputs — just not your template. Mine them for two things:

• Vocabulary. The nouns and verbs a payload uses are candidate classes and properties. Harvest the terms; that is real signal about what the business exchanges.
• Coverage. Every field that carries business meaning should have a semantic home in the ontology. Walk the messages to make sure none is orphaned.

And you must eventually connect every message to the model — that is what the mapping layer is for. The line to hold is precise: mine messages for terms; derive structure from the domain.