Ambivalent feelings about details in domain modeling

When you are exploring the problem space, you must stop at some point. You have to make decisions and avoid getting stuck in an infinite process of learning everything.

Exploration without decision is not progress.

Of course, deciding what to do with the answers you receive and the information you still lack is a challenge on its own, but you already know how to approach this problem.

The difficulty of finding the right moment to stop is not the only one that comes with deeper understanding. Another important decision you face is determining which details you truly need in your system.

The value of a model is not in how much it contains, but in how precisely it reflects the problem.

Before we move further, I want to emphasize that details do not refer only to data. They can include vocabulary, policies, rules, assumptions valid at the moment a decision was made, and more. In short, any business-relevant information.

Why details can cause a problem

If knowledge is power, then storing everything might seem like the right approach. That is true in some scenarios, for example audit. It is far less true in many others. For now, I will leave aside the cost aspect, because even if we could afford such an approach, it would still not be beneficial.

Since we are discussing understanding the problem space, these approaches introduce several risks:

• keeping all details - this creates unnecessary noise, making it difficult to understand which elements are truly required to solve a given problem. It also introduces challenges with maintaining boundaries and responsibilities. If everything is available everywhere, there is no clear guidance on where changes should be introduced. It becomes difficult to determine where constraints must be protected - and even harder to enforce them.
• keeping too few details - when essential information is missing, we tend to simplify the problem, rely on false assumptions, or treat it as easier than it actually is. As a result, the risk of breaking something that previously worked increases. This scenario can be more damaging than the previous one. Here, the model and architecture cannot provide the answers we need - because the required information simply is not there.
• a mix of both problems - this is the most challenging situation. It becomes even harder to decide which details are unnecessary. This happens because something may appear irrelevant only when other crucial information is missing. You can observe this in non-modular monoliths, where everything is coupled without a clear business reason.

How to find the right amount of details

There are situations where, thanks to strong analysis, experience in a given domain, or other factors, you already know which details should be captured by the solution.

More interesting, however, are the cases where we are not certain. Let’s explore what we can do then.

There are two approaches you can start with. Both are valid. Neither is free:

• include all available details
• include only the details required based on your current level of understanding

You can start with either, but the initial choice is not the end. The next step requires discipline. Both approaches can be used during learning and exploration, especially when validating a proposed solution.

Each approach comes with its own cost:

1. starting with everything - without discipline, there is a risk that you will never remove what is unnecessary. It is easier and cheaper (in the short term) to do nothing than to actively refine the model.
2. starting with what is required - there is a risk of frequent changes. It may feel repetitive: add a new detail, store it if needed, and use it. If this happens often, you may be tempted to revert to including everything. However, this approach is safer - you will not be able to ignore missing elements, because they will surface when they become necessary.

Based on this, it might seem that the second option is always better. In an ideal world, I would agree - especially since the risk of ending up with an unvalidated solution is higher with the first approach.

On the other hand, the first option gives you the flexibility to postpone validation and focus on other areas of the system - for example, when responding to unexpected market regulations that must be supported quickly. Yes, this introduces information chaos, but it also ensures that required data is already present.

To make the decision, look at domain types. If you face this challenge in generic or supporting subdomains, I would lean toward the first option. For core domains, I strongly recommend the second.

Why? Core domains change more frequently and are tightly coupled with the main problem space. That is exactly where investment in clarity and quality delivers the highest return.

How to continuously validate what is needed

Systems evolve. At some point, you may split something that originally started as a single solution - or merge components that were initially separate. At the same time, features are added, removed, and modified. A decision that is valid today may not hold in a few months or years.

To control the risk that the level of detail drifts too far in either direction I recommend tests that cover business processes. These can be component tests, end-to-end tests, or anything in between - as long as they validate that, for a given input, the system behaves as expected.

A few key principles when building such tests:

• verify behavior, not implementation
• validate decisions, not database structure
• check API contracts - does the system produce the expected output for a given input?
• when mocking, ensure it closely mimics real behavior

These tests are especially valuable during impactful or disruptive changes. They help verify whether the current level of detail in the solution is still appropriate.

Detail is a decision

Knowledge is powerful. As I wrote previously, deeper understanding leads to better, more informed decisions that support the business.

At the same time, knowledge brings responsibility. You must decide which information is essential - and which is only noise in a given context.

Detail is not truth. It is a decision - and every decision shapes your architecture.