DEV Community: Henrique Moody

Keeping boundaries clean: Upstream vs. Downstream

Henrique Moody — Fri, 16 Oct 2026 11:25:52 +0000

Boundaries are hard to get right. Not only between the big parts of a system, but anywhere we draw a line: between classes, objects, even methods.

I've spent a lot of time describing systems, both new and existing ones. I try not to throw terms like "Domain-Driven Design" at people, because they are open to a lot of interpretation and there are many nuances to them. But then, how do you help someone understand boundaries, whether they have a technical background or not?

I start with the parts of the business they already know: Acquisition, Distribution, Billing. Then we explore which of those parts depends on which, and in what way. Those dependencies play an important role in how we build products and design systems, and making them visible is where I've had the most success. The words that help us understand them are upstream and downstream.

This article goes a bit deeper than those conversations, so the parts need a name. Domain-Driven Design calls them bounded contexts: boundaries within which one model and its language stay consistent. A bounded context can be a single service, or a module inside one. Bounded contexts rarely stand alone: each one depends on others, and others depend on it.

What follows explains which way those dependencies should point, how to tell the sides apart, why that matters, how to spot a boundary that has started to leak, and why dependencies must never go in a circle.

Upstream vs. Downstream

Think of a river: the downstream part only gets the water that comes from upstream.

Upstream

Upstreams provide capabilities that Downstreams can use. Upstreams should not depend on Downstreams. Ideally they don't know their Downstreams exist; if they do, they still contain none of their concepts.

Downstream

Downstreams consume what Upstreams provide. Downstreams depend on Upstreams.

The Request Paradox (Data vs. Control Flow)

Data, business value and events flow downstream, like water. Network requests flow the other way: the Downstream calls up to the Upstream to fetch data or to ask it to do something. Two things cross every boundary, in opposite directions. Calls go up, data comes down.

That is the paradox, and it is why context maps often end up drawn upside down. Follow the request and you draw the arrow from caller to callee. But the arrow on a context map shows the dependency, and the dependency follows the water, not the request. So if the call doesn't settle it, what does?

Telling the sides apart

The contract decides the direction, not the call. The Upstream defines the contract, and the Downstream adapts to it. The call is still a good hint, because the caller is usually downstream. When the two disagree, the contract wins.

Webhooks look like an exception, but they aren't. A payment provider calls your endpoint, so the call travels from Upstream to Downstream. Yet the provider defines the payload and you adapt to it. You registered your URL with it: the Downstream subscribes, and the Upstream delivers to whatever address it was given. It knows where to send, not who you are or what your model looks like.

Rule of thumb. Start with the network calls, but don't stop there. Ask: whose model does the other one have to know about? The side that can be described without the other is the Upstream; the side that can't is the Downstream. If neither can be described without the other, the boundary is either leaking or in the wrong place.

Why it matters

Keeping an Upstream unaware of its Downstreams pays off on both sides of the boundary:

Reuse. The Upstream can serve any Downstream, not only the one it was first built for.
Replaceability. The Upstream can be replaced (by a vendor, a rewrite, a new platform), and Downstreams only change an adapter.
Independent testing. The Upstream can be tested without fixtures from any Downstream.
A stable foundation. Downstreams build on a language that doesn't change just because one Downstream changed.
Contained blast radius. A change in one Downstream can't break the Upstream or its other Downstreams.
Team autonomy. A Downstream can change without the Upstream team in its planning meeting, and the Upstream can change its internals freely. Only changes to the Upstream's contract need coordinating, because every Downstream adapts to it.

Signs of a leaking boundary

The boundary leaks the moment downstream concepts start showing up inside the Upstream:

Downstream identifiers in upstream data or APIs. The Upstream stores or accepts IDs that only mean something to one Downstream.
Downstream-specific APIs. The Upstream exposes endpoints or accepts payloads shaped around one Downstream's model.
Downstream state in upstream events. The Upstream's events carry statuses or fields that describe a Downstream's state, not its own.
Downstream rules in upstream logic. The Upstream checks conditions that belong to a Downstream's business rules.
Releases driven by a Downstream. The Upstream has to change just because one Downstream changed its model or request format. This is the Request Paradox going wrong: the call travels upstream, and the Downstream's concepts travel with it.

When you spot one, the fix is the same: move the downstream-specific knowledge back into the Downstream, and let the Downstream hold the reference to the Upstream, never the other way round.

Avoid dependency cycles

Getting the direction right between two bounded contexts is not enough: a bounded context must never end up downstream of itself.

Cycle: Spring → River → Delta → Spring. Spring ends up downstream of itself.

No cycle: every arrow points the same way.

A cycle cancels the benefits above: changes travel around the loop and come back, and concepts leak in through a third bounded context. Two bounded contexts that depend on each other directly are the smallest version of the same problem.

To break one, find the arrow that points the wrong way. Usually one bounded context should coordinate the others; if two bounded contexts can't be described without each other, they may be one bounded context.

Example: Shipping and Ordering

Shipping and Ordering show up in almost any business that sells things and delivers them.

Shipping is the Upstream
Ordering is the Downstream

That might surprise people at first, because Ordering is the one that "kicks things off". The sections below show why.

The Request Paradox in action

Ordering starts the process and makes the call, and Shipping is the Upstream. Calls go up, data comes down.

Ordering calls Shipping

Request travels upstream.

When an Order is paid, Ordering asks Shipping to create a shipment: "ship these parcels to this address". It speaks Shipping's language: parcels, weights, an address. It does not send an Order object and expect Shipping to figure out what to do with it. Ordering saves the ID of the shipment to later get information about that shipment.

Shipping publishes what happened

Data flows downstream.

ShipmentCreated, ShipmentDispatched, ShipmentDelivered. These events are about shipments. They carry a shipment id, a carrier, timestamps. They do not carry an order id, an order status, or a customer's purchase history.

Ordering consumes those events

The Downstream adapts.

Ordering translates events into its own concepts: ShipmentDelivered becomes "Order fulfilled". Ordering keeps the mapping order ↔ shipment on its side, because Ordering is the one that cares about it.

Telling the sides apart, in practice

Shipping defines the contract (the CreateShipment request and the Shipment… events), and Ordering adapts to it. Here the hint and the contract agree: the caller, Ordering, is the Downstream.

	Shipping (Upstream)	Ordering (Downstream)
Purpose	Move a parcel from an origin to a destination address, through a carrier, and report where it is.	Turn what a customer bought into a fulfilled purchase: items, prices, payment, and getting the goods to the customer.
Concepts	Shipment, Parcel, Weight, Dimensions, Address, Carrier, Label, Tracking number, Delivered.	Order, Line item, Customer, Total, Payment, Fulfilment status, and Shipment (borrowed from Shipping).
What it knows about the other	Nothing. Shipping has no idea what an Order is. It ships parcels for whoever asks: a sales order, a warranty replacement, a sample sent to a partner, a return.	Quite a lot. Ordering knows that a Shipment exists, how to request one, and what "Delivered" means for an Order's fulfilment status.

Shipping can be fully described without the word "Order" ever appearing. Ordering cannot be described without Shipping. That is the rule of thumb at work: the side that can be described without the other is the Upstream.

Why it matters, in practice

Applied to this example, the benefits of a clean Upstream mean Shipping can ship returns, warranty replacements and partner samples, not just orders; it can be replaced by a carrier platform behind an adapter; it can be tested without an Order fixture; and only changes to Shipping's contract need coordinating with Ordering.

Signs of a leaking boundary, in practice

Here is what each of the signs of a leaking boundary looks like between Shipping and Ordering:

Sign	In Shipping and Ordering
Downstream identifiers in upstream data or APIs	An `order_id` column on the `Shipment` table, or an `order_id` parameter in Shipping's REST API
Downstream-specific APIs	`POST /shipments/from-order` taking an Order payload
Downstream state in upstream events	`ShipmentDelivered` carrying `orderStatus: FULFILLED`
Downstream rules in upstream logic	Shipping checking "is this order paid?" before printing a label
Releases driven by a Downstream	Shipping redeploying because the Order's shape changed

Avoiding dependency cycles, in practice

To see why dependency cycles are a problem, add a third bounded context, Billing, and a reasonable rule: don't dispatch a parcel until it has been paid for.

The mistake

Billing listens to OrderPlaced, and Shipping waits for InvoicePaid. Shipping is now downstream of itself: a change to the Order travels through Billing to Shipping and back to Ordering, and an order_id reaches Shipping through Billing.

The fix

Ordering coordinates. It asks Billing for an invoice in Billing's language and, once InvoicePaid arrives, asks Shipping to ship. Neither Upstream knows the other exists.

See the fixed flow step by step

What is new on Respect\Validation 3.0

Henrique Moody — Mon, 05 Jan 2026 08:28:29 +0000

Respect\Validation is a PHP validation library that makes complex validations simple, with many validators out of the box.

It's built for engineers who validate real data and might need to display meaningful messages to end-users without hassle. It was first released over a decade ago, and has since grown to over 35 million installs on Packagist, nearly 6k stars on GitHub, and hundreds of public packages depending on it.

Validation 3.0 lands in February, 2026 — and it's a big one.

I've been the main maintainer of Validation for a long time, and after a lot of thought and several conversations with users and dear engineer friends, I've refactored the whole library and rebuilt the engine from the ground up.

Validation still has the simplicity of making complex validations easier to end users, but now features consistent naming, better separation of concerns, higher customization capabilities, modern PHP features, and a developer experience that just feels right.

In this post:

Accurate errors for nested validators
Result composition
Prefixed shortcuts
PHP attributes
No need for exceptions
Paths in error messages
Helpful stack traces
Use your own exception
Use your own templates
Attaching templates to the chain
Placeholder pipes
Naming validators

Accurate errors for nested validators

Previous versions of Validation had a fundamental limitation: when a validator passed, nothing happened — and when it failed, it threw an exception. That sounds reasonable until you consider validators that wrap other validators, like Not.

Here's the problem. In previous versions, when you wrote:

// Before v3 🤔
v::not(v::not(v::intType()))->assert('not an integer');
// → These rules must not pass for "not an integer"

Cryptic. Which rules? Why? The library couldn't produce a coherent message because the inner not(intType()) passed (since 'not an integer' isn't an integer), but the outer Not had no idea why it passed — only that it did.

Years ago I read Replacing Throwing Exceptions with Notification in Validations by Martin Fowler, and that sparked some ideas. What if we could do something similar in Validation? What if every validator (pass or fail) would return a result object that captures what happened and why?

After playing around with different prototypes and with PHP's newest features, I came up with a result object that has everything we need, without a lot of verbosity. Now, when validators compose, they can inspect each other's results and produce messages that actually make sense:

// v3 👍
v::not(v::not(v::intType()))->assert('not an integer');
// → "not an integer" must be an integer

No matter how deep the nesting, Validation now knows exactly what happened and tells you clearly.

This change also unlocked capabilities that simply weren't possible before — like result composition.

Result composition

I always found it a pity that we couldn't compose validators and their messages. I wrote lots of customizations on top of Validation in Assertion, but there were quite some limitations.

In v3, validators can finally wrap others and combine their results into a single, coherent message. The outer validator provides context (what was extracted), and the inner validator provides the validation (what was expected).

v::all(v::intType())->assert(['1', '2', '3']);
// → Every item in `["1", "2", "3"]` must be an integer

v::length(v::greaterThan(3))->assert('abc');
// → The length of "abc" must be greater than 3

v::min(v::positive())->assert([3, 1, 0, -5]);
// → The minimum of `[3, 1, 0, -5]` must be a positive number

v::max(v::positive())->assert([-1, -2, -3]);
// → The maximum of `[-1, -2, -3]` must be a positive number

v::size('MB', v::not(v::greaterThan(5)))->assert('path/to/file.zip');
// → The size in megabytes of "path/to/file.zip" must not be greater than 5

v::dateTimeDiff('years', v::greaterThan(18))->assert('2025');
// → The number of years between now and "2025" must be greater than 18

Prefixed shortcuts

In a distant past, Validation had a not prefix as part of the Validator class, but we removed it. Many years later, when I wrote Assertion, I added several prefixes to make it easier to use validators that wrap other validators. I decided to bring them to Validation too.

v::allEmoji()->assert($input);                 // all items must be emojis
v::keyEmail('email')->assert($input);          // key 'email' must be valid email
v::propertyPositive('age')->assert($input);    // property 'age' must be positive
v::lengthBetween(5, 10)->assert($input);       // length between 5 and 10
v::maxLessThan(100)->assert($input);           // max value less than 100
v::minGreaterThan(0)->assert($input);          // min value greater than 0
v::nullOrEmail()->assert($input);              // null or valid email
v::undefOrPositive()->assert($input);          // undefined or positive number

PHP attributes

PHP attributes have been available for years, and I always found it a shame we didn't support validating object properties with them. Symfony Validator has been supporting annotations/attributes for a very long time, but it doesn't have as many validators out-of-the-box as we have. Now, we can use any validator as an attribute.

use Respect\Validation\Rules\{Email, Between, GreaterThan, Length};

class User
{
    public function __construct(
        #[Email]
        public string $email,
        #[Between(18, 120)]
        public int $age,
        #[Length(new GreaterThan(1))]
        public string $name,
    ) {
    }
}

// Validate everything at once
v::attributes()->assert($user);

No need for exceptions

Sometimes you just want to validate data and handle the result manually. In previous versions, the only way to do that was wrapping the validation in a try block. In v3, you can skip the exception entirely:

$result = v::numericVal()->positive()->between(1, 255)->validate($input);
if (!$result->isValid()) {
    echo $result;
}

The validate() method returns a ResultQuery object that has the methods getMessage(), getFullMessage(), and getMessages() to output messages.

$mysqlUserResult = $result->findByPath('mysql.user');
if ($mysqlUserResult !== null) {
    echo $mysqlUserResult;
}

The findByPath() returns either a ResultQuery or null, and you can also use findByName() and findById().

Paths in error messages

Because previous versions of Validation didn't have result objects, it was impossible to trace paths of nested structures. Consider the following chain:

$validator = v::init()
    ->key(
        'mysql',
        v::init()
            ->key('host', v::stringType())
            ->key('user', v::stringType())
            ->key('password', v::stringType())
            ->key('schema', v::stringType()),
    )
    ->key(
        'postgresql',
        v::init()
            ->key('host', v::stringType())
            ->key('user', v::stringType())
            ->key('password', v::stringType())
            ->key('schema', v::stringType()),
    );

In previous versions of Validation, this is what would happen:

// Before v3 🤔
$validator->assert($input);
// → host must be a string

Was it host from mysql or postgresql? You had no idea which one failed.

In v3, because every validator returns a result object, we can trace the path of nested structures and display much more helpful messages.

// v3 👍
$validator->assert($input);
// → `.mysql.host` must be a string

Not only do you have the full path of the nested structure, but it's also clear that .mysql.host is a path, not a name.

Helpful stack traces

When an exception is thrown, PHP reports where it was created, not where it was caused. In most validation libraries (including older versions of Validation) that means stack traces point deep inside library internals. You end up hunting through the trace to find your actual code.

v3 fixes this. If v::intType()->assert($input) fails in example.php line 11, your stack trace looks like this:

Stack trace:
#0 /opt/example.php(11): Respect\Validation\Validator->assert(1.0)
#1 {main}

Your file. Your line. Your problem to fix — not ours to hide.

I picked up this technique while digging into Pest's source code. Kudos to Pest's engineers!

Use your own exception

Even with a helpful stack trace, at times we just want to use our own exceptions. The trouble with older versions of Validation (and some other libraries) is that when a validation fails, you have to wrap it in a try/catch or manually check the result so you can throw your own exception.

I implemented this in Assertion years ago. It was an awesome idea that Jefersson Nathan suggested while I was working on it. In v3, you can do that right when you're using the assert() method:

v::email()->assert($input, new DomainException('Invalid email'));

But sometimes, you might want to reuse the message from Validation. For cases like that, you can just pass a callable to assert(). This idea came from seeing how openapi-psr7-validator uses Validation. It made a lot of sense that people might want their own exceptions without having to rebuild the message.

v::email()->assert(
    $input, 
    fn(ValidationException $e) => new DomainException($e->getMessage()),
);

The callable receives the exception that Validation would have thrown. You can do whatever you want in there (log it, wrap it, enrich it), but it needs to return an exception.

Use your own templates

Sometimes, you don't need your own exception, but you need a specific message. You can pass your template to assert() just as a string, and Validation will throw ValidationException with it as the message.

v::email()->assert($input, 'This is my template');
// → This is my template

When you have multiple validators in a chain, you can define one template for each validator:

v::intVal()->positive()->lessThan(100)->assert($input, [
    'intVal' => 'Must be an integer',
    'positive' => 'Must be positive',
    'lessThan' => 'Must be under 100',
]);

When using validators that handle structures (like Key and Property), you can define the template by the path of the validator:

// Target nested structures by path
v::key('name', v::stringType())
    ->key('age', v::intVal())
    ->assert($input, [
        '__root__' => 'Please check your user data',
        'name' => 'Please provide a valid name',
        'age' => 'Age must be a number',
    ]);

The __root__ key targets the root validator. In this case, that's an AllOf that wraps the chain.

Passing templates to assert() is best for when you don't want to reuse the templates. When you do, you'll want to keep the templates in the chain.

Attaching templates to the chain

In previous versions of Validation, you could use the setTemplate method in the chain to define your template.

v::email()->setTemplate('This is my template')->assert($input);
// → This is my template

There are a couple of issues with setTemplate:

It can be confusing when you have nested validators in the chain
It's not as explicit as I would have liked it to be
It added some overhead to the Validator class that was already quite complex

Because of the new engine (result composition), I created a validator called Templated that overwrites the template of the result of a wrapped validator.

v::templated('This is my template', v::email())->assert($input);
// → This is my template

This makes the validation more explicit and less confusing. The Templated validator also allows you to pass parameters to your template, so you can inject your own placeholders.

v::templated(
    'Every {{user_type}} user needs a valid email',
    v::email(),
    ['user_type' => $userType],
)->assert('not an email');
// → Every "admin" user needs a valid email

Placeholder pipes

Validation uses Stringifier to convert values into strings for templates. By default, strings get double quotes around them. With placeholder pipes, you can customise how values are rendered. Just add a pipe (|) followed by the modifier name.

raw: removes quotes, useful for field names or labels that shouldn't look like string values:

v::templated(
    'The {{field|raw}} field is required',
    v::notEmpty(),
    ['field' => 'email'],
)->assert('');
// → The email field is required
// (instead of: The "email" field is required)

quote: uses backticks, great for patterns or code-like values:

v::templated(
    'Product SKU must follow the {{pattern|quote}} format',
    v::regex('/^[A-Z]{3}-\d{4}$/'),
    ['pattern' => 'XXX-0000'],
)->assert('invalid-sku');
// → Product SKU must follow the `XXX-0000` format

trans: translates the value when using a translator:

v::templated(
    'Le champ {{field|trans}} est invalide',
    v::email(),
    ['field' => 'email_address'], // key in your translation file
)->assert('not-an-email');
// → Le champ "adresse e-mail" est invalide

list:or and list:and: formats arrays as readable lists:

v::templated(
    'Status must be {{haystack|list:or}}',
    v::in(['active', 'pending', 'archived']),
)->assert('deleted');
// → Status must be "active", "pending", or "archived"

v::templated(
    'User must have {{roles|list:and}} roles to perform this action',
    v::callback(fn(User $user) => $user->hasRoles(['admin', 'editor'])),
    ['roles' => ['admin', 'editor']],
)->assert($user);
// → User must have "admin" and "editor" roles to perform this action

Naming validators

The same reasoning applies to naming. In previous versions, you could use setName to give a validator a custom name in messages:

v::email()->setName('Your email')->assert($input);
// → Your email must be a valid email

This had the same issues as setTemplate: confusing with nested validators, not explicit, and added overhead to the Validator class.

In v3, there's a Named validator that wraps another validator and gives it a name:

v::named('Your email', v::email())->assert($input);
// → Your email must be a valid email

Same pattern as Templated, same benefits. And because they're just validators, they work as PHP attributes too:

class User
{
    public function __construct(
        #[Named('Your email', new Email())]
        public string $email,
        #[Templated('You must be at least {{age}} years old', new GreaterThanOrEqual(18))]
        public int $age,
    ) {
    }
}

Closing thoughts

This is the biggest release in Validation's history! The new engine, the result objects, the composition capabilities, the customization options... it's all been a long time coming.

This post focused on the most exciting user-facing changes, but there's a lot more to this version:

Ability to customize a lot of standard behavior
Improved validation messages
Renamed validators for better semantic meaning
More validators that are only possible due to the new engine

I'm incredibly grateful to everyone who contributed ideas, feedback, and code over the years! I can't wait to get feedback on the new version!