In Domain-Driven Design, what is a Domain Vision Statement and why do teams write one when distilling the core domain?

## What the document is A **domain vision statement** is a short, plain-language document — typically no more than half a page — that names the **core domain** of a system and articulates the value it delivers that competitors or off-the-shelf alternatives cannot easily replicate. It is written early in a project, often before the model itself is fully understood, and it stays intentionally free of implementation detail: - no class names - no database schemas - no API contracts Instead it answers a narrower question than a corporate mission statement: among everything this software could do, which part is the reason this software needs to be built in-house at all, and why will that part make the product succeed? The statement is usually drafted collaboratively by whoever holds the sharpest domain knowledge — often a **domain expert** paired with a lead developer or architect — precisely because getting it right requires understanding both what the business needs and what is actually hard or valuable to model in software. ## Why the practice exists The reason this practice exists is that any non-trivial system quickly accumulates many subdomains — **core**, **supporting**, and **generic** — and, left unmanaged, a team's attention distributes itself roughly evenly across all of them. Generic subdomains (authentication, notifications, PDF generation) are often more concrete and easier to reason about than the ambiguous, evolving core, so they attract disproportionate design effort and the most experienced engineers' attention almost by default — engineers gravitate toward well-defined problems. Meanwhile the core domain, which is where the competitive differentiation and the majority of the domain complexity actually live, gets whatever time and people are left over. A domain vision statement counteracts this drift by giving the whole team — including non-technical stakeholders, who rarely read code — an explicit, shared, and revisitable answer to 'what matters most here,' stated early enough, before large amounts of effort have already been misallocated, to influence: - **staffing** - **architecture reviews** - **sprint prioritization** ## The trade-off The trade-off is that writing a good one is genuinely hard and consumes scarce domain-expert time up front, at a point in a project when uncertainty about the model is at its highest — so there is a real risk of writing a plausible-sounding but wrong statement that then misdirects the team's best people toward the wrong subdomain. This is why the statement is treated as a **living artifact** rather than a one-time deliverable: it should be revisited whenever the team's understanding of the domain shifts materially. - after a major discovery in domain-expert conversations - after a pivot in business strategy - when the 'core' starts to feel like it's actually a supporting concern in disguise Skipping revision is itself a cost, because a stale vision statement actively misleads rather than merely failing to help. ## Failure modes 1. In production practice, the most common failure mode is a vision statement that is **technically present but functionally useless** — vague corporate-speak like 'we deliver value to our customers through innovative technology,' which is true of literally any company and gives zero guidance about where developer effort should concentrate. 2. A second failure mode is **writing it top-down**, by management or marketing, without direct domain-expert or developer involvement; the result reads well in a slide deck but does not correspond to where the actual modeling complexity sits, so engineers ignore it and default back to even-handed effort distribution. 3. A third is **treating it as done once written**: teams that never revisit the statement end up with a document that described the core domain accurately eighteen months ago but now points at a subdomain the business has since deprioritized, actively steering new hires and code reviews in the wrong direction. 4. A fourth is **conflating it with a mission or vision statement for the whole company** — that document serves marketing and recruiting, not architectural prioritization, and mixing the two produces something too broad to guide any specific decision about where to invest modeling effort. ## A concrete scenario A concrete scenario: a company building cargo-shipping software has, among others, a **booking** subdomain, an **invoicing** subdomain, and a **route-and-handling** subdomain that dynamically tracks cargo through transfers and re-routes around disruptions. Invoicing and booking are largely solved problems available in off-the-shelf logistics packages; the dynamic routing and handling logic is where this particular company's competitive edge and hardest domain complexity live. A domain vision statement naming 'responsive, disruption-aware cargo routing' as the core domain tells the team to put its most experienced modelers there, to invest in a segregated, cleanly bounded model for routing, and to treat invoicing as a generic subdomain worth buying or building with minimal customization — a decision that would otherwise require re-litigating on every planning cycle.