Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Specification

A business rule written once, as an object that answers whether a candidate satisfies it, combined with and, or and not, and reused to validate one object, filter a loaded list and build a database query. Where the query use stops: not every rule translates to SQL, and the object and its query are two implementations that can drift.

Sixty days in one place, forty-five in another

A building-supplies wholesaler sells to about 1,800 contractors and hardware stores on 30-day terms. Its credit policy fits in one sentence: an account goes on credit hold when any invoice is more than 45 days past its due date, or when the open balance is over the credit limit. One Monday, three parts of its software gave three different answers about the same roofing contractor, who owed €18,000 against a €20,000 limit and had one invoice 52 days past due:

  • Order entry accepted a €4,000 order. Its check still used 60 days, the rule before the credit team tightened it in April.
  • The collections worklist showed the account on hold. Its SQL had been updated to 45 days when the rule changed.
  • The sales reps' tablet app showed the account in good standing. It had only ever compared the balance with the limit.

The rule simply had no home: it lived as an if in order entry, a WHERE clause in the worklist and a comparison in the tablet app, so a change to the rule was three changes, and only one of them was made.

The rule gets a name and a class

A Specification gives a business rule that home. It is an object with one question, isSatisfiedBy(candidate), which answers true or false for the object it is handed. The wholesaler's hold becomes OnCreditHold, named the way the credit team says it, and the rest of the system asks onCreditHold.isSatisfiedBy(account) instead of writing its own version of what 45 days past due means.

Looked at closely, the hold is two rules joined by or, and each is useful alone: collections chases overdue accounts whatever their balance, and the sales team watches accounts over their limit. So the wholesaler writes two small specifications, PastDueOver(45) and OverCreditLimit, and builds the hold from them: PastDueOver(45).or(OverCreditLimit). The result is itself a specification, and and and not work the same way, each returning a new one. When collections decides that accounts on an agreed payment plan should not be chased, its worklist uses onCreditHold.and(OnPaymentPlan.not()), and the hold itself does not change.

One rule, built from two

The two small rules are combined into one composite specification. Callers test the account only through the composite, which delegates to its two parts and combines their answers. The same object is handed to the repository to select accounts.

Order entry, a tablet, a worklist

Order entry asks about one account, the one placing the order. If onCreditHold.isSatisfiedBy(account) is true, the order waits for a credit controller instead of going to the warehouse. That is validation. The answer is about the account as it was loaded, at the moment of asking: a payment posted a second later can change it.

The tablet holds one rep's 60 accounts, already in memory, and greys out the ones on hold by passing each through onCreditHold.isSatisfiedBy. That is selection in memory, and it is the same object answering, so the tablet and order entry now apply one rule instead of two.

The worklist cannot work that way. Loading all 1,800 accounts with their open invoices to keep the forty that match is slow, and gets slower as the wholesaler grows. So the worklist hands the specification to the repository, accounts.matching(onCreditHold), and the repository turns it into a query: an EXISTS over open invoices with a due date before the cutoff, OR a comparison of balance and limit. That is query building, and the shape of a repository that accepts a specification belongs to Repository.

Where the query and the object part ways

The third use quietly brings back the original problem. The rule now has two implementations again: the code behind isSatisfiedBy and the SQL the repository produces from it. They sit next to each other, which beats three teams in three places, but they can still disagree, and the wholesaler found a case in the first month. PastDueOver(45) compared due dates with today's date from the application's clock, on local time an hour ahead of UTC, while the generated SQL used the database's CURRENT_DATE, in UTC. For an hour after every midnight, an account that had just crossed 45 days was on hold at order entry and missing from the worklist.

The fix was to stop each side reading its own clock: the specification takes the date as a parameter, PastDueOver(45, asOf), and both implementations use it. The guard against the next drift is a test that runs the same accounts, including some right at the 45-day line, through both, isSatisfiedBy in memory and the query against a real database, and fails when the two lists differ.

And not every rule can become SQL. When the credit team asked for days past due counted in business days, skipping each region's public holidays, the calculation lived in a calendar library in the application, and the database had nothing to translate it into. A repository can only translate a specification built from pieces it knows how to translate; a specification whose isSatisfiedBy runs arbitrary code is opaque to it. Two ways out: ask the database for a wider set it can express, accounts more than 45 calendar days past due or over their limit, which contains every account the whole hold could match, and finish the filter in memory with isSatisfiedBy, at the cost of loading more rows; or store what the query needs, the date on which each invoice passes 45 business days overdue, computed with its region's calendar when the invoice is written and recomputed if the calendar changes, so the query becomes a plain comparison with asOf. What a repository must not do is skip the part of a specification it cannot translate: it returns a list that looks right and can include accounts that do not match or leave out ones that do.

A rule worth reusing

Among the six requirements of the DDD Tactical Building Blocks Challenge is "Model a Specification encapsulating a reusable business rule for selection or validation". The word to draw is reusable. Name the Specification after the rule, the way OnCreditHold is, keep it independent of any one screen, and connect it to every node in your use case that already needs the rule, such as the Repository that selects with it, or a Domain Service that validates with it while applying the rule to several aggregates at once. If you build it from smaller rules, the consumers that need the whole rule call isSatisfiedBy on the composite, which delegates to its parts and combines their answers, so on your Grid the composite, not its parts, holds the single edge to the aggregate.

Practice this