Crossing System Boundaries
In this pack:
sizing,
notation,
rule strictness.
Overview
Every system the clinic talks to keeps a model of its own. A partner
reads an appointment through an API, another organisation answers a
lookup, and a queue carries a message to code that runs later. Each of
those is a contract: a shape both sides agreed on, and a promise about
what a change may do to it. This skill gives each contract transfer
types of its own, maps them to the domain in one place per boundary,
wraps an outside API behind a port in the clinic's terms, and changes a
published contract only in ways its readers and writers survive. When a
change cannot be compatible, it versions the contract and retires the
old version on a schedule.
When to use
- An API or message must keep its shape while the domain model changes.
- A partner's data has to become clinic values, or the clinic's answer
has to become the partner's format.
- A published contract needs a version, or two versions must run side
by side.
- A provider changes its API and the clinic must decide what else
changes.
- A queued message, an outbox event, a cache or an exported file will
be read by a later version of the code.
When not to use
- The data never leaves the process and no other system or stored form
reads it: pass domain objects as they are.
- The question is whether a type should be a class with rules or plain
data: that is
deciding object or data.
- The question is how a domain class reaches a database, a clock or
another outside service at all: that is
inverting dependencies.
- The question is which team's model a boundary separates, and how the
two teams relate: that is
bounding contexts.
- The question is whether to publish a domain event, whether to record
it in the aggregate, or how to deliver it after the commit: that is
publishing domain events.
The stored shape that later code reads stays here, under rule 6.
Core rules
Rule. Give each contract with another system its own transfer
types, owned by the adapter for that system and separate from the
domain model. The appointment a partner's app reads is a
PortalAppointment with the fields the contract promises, not the
domain's Appointment sent as it is. The domain can then rename a
field or change a rule without breaking a reader, and the contract
can change without reaching the model. A transfer object is plain
data shaped by the contract and holds no rules; rule 3 of
deciding object or data
decides that and converts it once at the edge.
Rule. Map between a contract's transfer types and the domain's in
one place for each boundary, in both directions. The class that
does this mapping is the mapper for that boundary. Incoming data
becomes domain values through their constructors, which refuse what
the domain cannot accept, and the domain's answer becomes the
contract's types on the way out. A missing or unreadable field the
clinic relies on is refused at the mapping, never passed on as an
empty value for the domain to trip on later.
Rule. Wrap another organisation's API behind a port that speaks
the clinic's terms and asks only for what the clinic needs, with one
adapter that alone knows the provider's types, error codes and
calls. This is rule 1 and rule 6 of
inverting dependencies and
rule 3 of
hiding implementation,
applied to a provider outside the clinic. When the provider changes
its API, the adapter and its tests are the only code that changes.
Default. Change a published contract only in ways its existing
readers and writers survive: add a field old readers may ignore,
accept a new field only as optional, and never rename, remove or
retype a field, or make an optional one required. Read incoming
data tolerantly: use the fields the clinic relies on and ignore the
ones it does not know. The exception is a change that cannot be made
compatible, such as a field whose meaning changes: it gets a new
version.
Judgement. When a change cannot be compatible, give the contract a
new version, serve the old version beside the new one until its
readers and writers have moved, and retire it on a schedule agreed
with them; name the version where its readers can see it, in the
address, in a header or in the message. What tips the balance is
how many readers there are and how quickly they can move: one
reader the clinic controls can move in the same release, while
partners need both versions for months.
Rule. Treat what is stored to be read later as a contract with
future code. A queued message, an event in an outbox, a cached
document or an exported file written today is read by a later
version of the code, which must still read it, or must convert the
stored data in a planned migration. The same compatibility rules
then apply to a shape no reader sees at run time.
Pattern
Before, PortalFeed sends the domain's Appointment itself to the
patient portal, so the portal reads the domain's field names and
renaming one breaks it.
Before:
class PortalFeed
- channel: PortalChannel
+ new(channel: PortalChannel)
+ publish(appointment: Appointment): void
channel.send(appointment)
return
After, PortalFeed sends a PortalAppointment built by one mapper, and
the portal reads only the fields the contract promises.
After:
value PortalAppointment
- appointmentId: String
- startsAt: String
- status: String
+ new(appointmentId: String, startsAt: String, status: String)
class PortalAppointmentMapper
+ toMessage(appointment: Appointment): PortalAppointment
return new PortalAppointment(appointment.id().text(),
appointment.startsAt().text(), appointment.status().text())
class PortalFeed
- channel: PortalChannel
- mapper: PortalAppointmentMapper
+ new(channel: PortalChannel, mapper: PortalAppointmentMapper)
+ publish(appointment: Appointment): void
channel.send(mapper.toMessage(appointment))
return
startsAt() and status() are queries this example adds to the
repositories skill's Appointment, text() is taken to answer each
value written as the contract's text, channel.send is taken to send
one message and change no aggregate, and the fences store nothing.
In both versions publish sends one message: the Before sends the
appointment itself once, and the After builds one PortalAppointment
and sends it once.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A domain class sent or returned as it is through a public API or a
message.
- A domain class that carries a serialization format's markers or
field names.
- A provider's types, error codes or client classes used outside the
one adapter that talks to it.
- The same mapping between a partner's format and the domain written
in more than one place.
- A renamed or removed field in a published reply, with no new
version.
- A reader that fails on a field it does not know.
Common mistakes
- Reusing one transfer type for several partners' contracts, so a
change for one breaks the others.
- Putting business rules into transfer objects or mappers.
- Turning a missing field into a default value at the boundary instead
of refusing it.
- Starting a new version for every change, compatible or not.
- Changing the shape of stored messages with no plan for those already
stored.
Related skills
Further reading
- Changing a contract
- Wrapping an outside API
1---2name: oo-crossing-system-boundaries3description: Use when an API or message must keep its shape as the model changes, when mapping partner data into the domain, or a contract needs a version.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-crossing-system-boundaries7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Crossing System Boundaries1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920Every system the clinic talks to keeps a model of its own. A partner21reads an appointment through an API, another organisation answers a22lookup, and a queue carries a message to code that runs later. Each of23those is a contract: a shape both sides agreed on, and a promise about24what a change may do to it. This skill gives each contract transfer25types of its own, maps them to the domain in one place per boundary,26wraps an outside API behind a port in the clinic's terms, and changes a27published contract only in ways its readers and writers survive. When a28change cannot be compatible, it versions the contract and retires the29old version on a schedule.3031## When to use3233- An API or message must keep its shape while the domain model changes.34- A partner's data has to become clinic values, or the clinic's answer35 has to become the partner's format.36- A published contract needs a version, or two versions must run side37 by side.38- A provider changes its API and the clinic must decide what else39 changes.40- A queued message, an outbox event, a cache or an exported file will41 be read by a later version of the code.4243## When not to use4445- The data never leaves the process and no other system or stored form46 reads it: pass domain objects as they are.47- The question is whether a type should be a class with rules or plain48 data: that is49 [deciding object or data](../oo-deciding-object-or-data/SKILL.md).50- The question is how a domain class reaches a database, a clock or51 another outside service at all: that is52 [inverting dependencies](../oo-inverting-dependencies/SKILL.md).53- The question is which team's model a boundary separates, and how the54 two teams relate: that is55 [bounding contexts](../oo-bounding-contexts/SKILL.md).56- The question is whether to publish a domain event, whether to record57 it in the aggregate, or how to deliver it after the commit: that is58 [publishing domain events](../oo-publishing-domain-events/SKILL.md).59 The stored shape that later code reads stays here, under rule 6.6061## Core rules62631. Rule. **Give each contract with another system its own transfer64 types, owned by the adapter for that system and separate from the65 domain model.** The appointment a partner's app reads is a66 `PortalAppointment` with the fields the contract promises, not the67 domain's `Appointment` sent as it is. The domain can then rename a68 field or change a rule without breaking a reader, and the contract69 can change without reaching the model. A transfer object is plain70 data shaped by the contract and holds no rules; rule 3 of71 [deciding object or data](../oo-deciding-object-or-data/SKILL.md)72 decides that and converts it once at the edge.73742. Rule. **Map between a contract's transfer types and the domain's in75 one place for each boundary, in both directions.** The class that76 does this mapping is the mapper for that boundary. Incoming data77 becomes domain values through their constructors, which refuse what78 the domain cannot accept, and the domain's answer becomes the79 contract's types on the way out. A missing or unreadable field the80 clinic relies on is refused at the mapping, never passed on as an81 empty value for the domain to trip on later.82833. Rule. **Wrap another organisation's API behind a port that speaks84 the clinic's terms and asks only for what the clinic needs, with one85 adapter that alone knows the provider's types, error codes and86 calls.** This is rule 1 and rule 6 of87 [inverting dependencies](../oo-inverting-dependencies/SKILL.md) and88 rule 3 of89 [hiding implementation](../oo-hiding-implementation/SKILL.md),90 applied to a provider outside the clinic. When the provider changes91 its API, the adapter and its tests are the only code that changes.92934. Default. **Change a published contract only in ways its existing94 readers and writers survive: add a field old readers may ignore,95 accept a new field only as optional, and never rename, remove or96 retype a field, or make an optional one required.** Read incoming97 data tolerantly: use the fields the clinic relies on and ignore the98 ones it does not know. The exception is a change that cannot be made99 compatible, such as a field whose meaning changes: it gets a new100 version.1011025. Judgement. **When a change cannot be compatible, give the contract a103 new version, serve the old version beside the new one until its104 readers and writers have moved, and retire it on a schedule agreed105 with them; name the version where its readers can see it, in the106 address, in a header or in the message.** What tips the balance is107 how many readers there are and how quickly they can move: one108 reader the clinic controls can move in the same release, while109 partners need both versions for months.1101116. Rule. **Treat what is stored to be read later as a contract with112 future code.** A queued message, an event in an outbox, a cached113 document or an exported file written today is read by a later114 version of the code, which must still read it, or must convert the115 stored data in a planned migration. The same compatibility rules116 then apply to a shape no reader sees at run time.117118## Pattern119120Before, `PortalFeed` sends the domain's `Appointment` itself to the121patient portal, so the portal reads the domain's field names and122renaming one breaks it.123124Before:125126```text127class PortalFeed128 - channel: PortalChannel129 + new(channel: PortalChannel)130 + publish(appointment: Appointment): void131 channel.send(appointment)132 return133```134135After, `PortalFeed` sends a `PortalAppointment` built by one mapper, and136the portal reads only the fields the contract promises.137138After:139140```text141value PortalAppointment142 - appointmentId: String143 - startsAt: String144 - status: String145 + new(appointmentId: String, startsAt: String, status: String)146147class PortalAppointmentMapper148 + toMessage(appointment: Appointment): PortalAppointment149 return new PortalAppointment(appointment.id().text(),150 appointment.startsAt().text(), appointment.status().text())151152class PortalFeed153 - channel: PortalChannel154 - mapper: PortalAppointmentMapper155 + new(channel: PortalChannel, mapper: PortalAppointmentMapper)156 + publish(appointment: Appointment): void157 channel.send(mapper.toMessage(appointment))158 return159```160161`startsAt()` and `status()` are queries this example adds to the162repositories skill's `Appointment`, `text()` is taken to answer each163value written as the contract's text, `channel.send` is taken to send164one message and change no aggregate, and the fences store nothing.165166In both versions `publish` sends one message: the Before sends the167appointment itself once, and the After builds one `PortalAppointment`168and sends it once.169170## Red flags171172Places to look, not verdicts. A red flag becomes a finding only with173evidence: a measurement, a reproducible bug, or a failing test.174175- A domain class sent or returned as it is through a public API or a176 message.177- A domain class that carries a serialization format's markers or178 field names.179- A provider's types, error codes or client classes used outside the180 one adapter that talks to it.181- The same mapping between a partner's format and the domain written182 in more than one place.183- A renamed or removed field in a published reply, with no new184 version.185- A reader that fails on a field it does not know.186187## Common mistakes188189- Reusing one transfer type for several partners' contracts, so a190 change for one breaks the others.191- Putting business rules into transfer objects or mappers.192- Turning a missing field into a default value at the boundary instead193 of refusing it.194- Starting a new version for every change, compatible or not.195- Changing the shape of stored messages with no plan for those already196 stored.197198## Related skills199200- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule201 labels.202- [oo-deciding-object-or-data](../oo-deciding-object-or-data/SKILL.md)203 rule 3 keeps a transfer object free of rules and converts it once at204 the edge.205- [oo-inverting-dependencies](../oo-inverting-dependencies/SKILL.md)206 rules 1 and 6 put a provider behind a port the domain owns, shaped by207 the domain's need.208- [oo-hiding-implementation](../oo-hiding-implementation/SKILL.md)209 rule 3 keeps a provider's types and errors behind the adapter.210- [oo-bounding-contexts](../oo-bounding-contexts/SKILL.md) rule 4211 decides where a context translates another model at its edge; this212 skill says how that translation is written.213- [oo-publishing-domain-events](../oo-publishing-domain-events/SKILL.md)214 rule 4 stores an outbox event, which is also a stored message read215 later.216217## Further reading218219- [Changing a contract](references/changing-a-contract.md)220- [Wrapping an outside API](references/wrapping-an-outside-api.md)