What is a Domain Event?

There has been much confusion of late over the definition of what a Domain Event is. I was writing some stuff that will go into both the course manual and the book and figured that it might be timely to put it up on the blog as well.

An event is something that has happened in the past.

All events should be represented as verbs in the past tense such as CustomerRelocated, CargoShipped, or InventoryLossageRecorded. For those who speak French, it should be Passé Composé, they are things that have completed in the past. There are interesting examples in the English language where one may be tempted to use nouns as opposed to verbs in the past tense, an example of this would be “Earthquake” or “Capsize”, as a congressman recently worried about Guam, but avoid the temptation to use names like this for Domain Events and stick with the usage of verbs in the past tense when creating Domain Events. These nouns tend to match up with “Transaction Objects” discussed later from Streamlined Object Modelling. It is imperative that events always be verbs in the past tense as they are part of the Ubiquitous Language.

Consider the differences in the Ubiquitous Language when we discuss the side effects from relocating a customer, the event makes the concept explicit where as previously the changes that would occur within an aggregate or between multiple aggregates were left as an implicit concept that needed to be explored and defined. As an example, in most systems the fact that a side effect occurred is simply found by a tool such as Hibernate or Entity Framework, if there is a change to the side effects of a use case, it is an implicit concept. The introduction of the event makes the concept explicit and part of the Ubiquitous Language; relocating a customer does not just change some stuff, relocating a customer produces a CustomerRelocatedEvent which is explicitly defined within the language.

In terms of code, an event is simply a data holding structure as can be seen in Listing 1.

Listing 1 A Simple Event

public class InventoryItemDeactivatedEvent {
    public readonly Guid InventoryItemId;
    public readononly string Comment;
    public InventoryItemDeactivatedEvent(Guid id, string comment) {
      InventoryItemId = id;
      Comment = comment;
    }
}

clip_image001

The code listing looks very similar to the code listing that was provided for a Command the main differences exist in terms of significance and intent.

Other Definitions and Discussion

There is a related concept to a Domain Event in this description that is defined in Streamlined Object Modeling (SOM). Many people use the term “Domain Event” In SOM when discussing “The Event Principle”

Model the event of people interacting at a place with a thing with a transaction object. Model a point-in-time interaction as a transaction with a single timestamp; model a time-interval interaction as a transaction with multiple timestamps. (Jill Nicola, 2001, p. 23)

Although many people use the terminology of a Domain Event to describe this concept the terminology is not having the same definition as a Domain Event in the context of this document. SOM uses another terminology for the concept that better describes what the object is, a Transaction. The concept of a transaction object is an important one in a domain and absolutely deserves to have a name. An example of such a transaction might be a player swinging a bat, this is an action that occurred at a given point in time and should be modeled as such in the domain, this is not however the same as a Domain Event.

This also differs from Martin Fowler’s definition of what a Domain Event is.

Example: I go to Babur’s for a meal on Tuesday, and pay by credit card. This might be modeled as an event, whose type is “Make Purchase”, whose subject is my credit card, and whose occurred date is Tuesday. If Babur’s uses and old manual system and doesn’t transmit the transaction until Friday, then the noticed date would be Friday. (Fowler)

Further along

By funneling inputs of a system into streams of Domain Events you can keep a record of all the inputs to a system. This helps you to organize your processing logic, and also allows you to keep an audit log of the system (Fowler)

The astute reader may pick up on the fact that what Martin is actually describing here is a Command as was discussed previously when discussing Task Based UIs. The language of “Make Purchase” is wrong. A purchase was made. It makes far more sense to introduce a PurchaseMade event. Martin did actually make a purchase at the location, they did actually charge his credit card, and he likely ate and enjoyed his food. All of these things are in the past tense.

An example such as the sales example given here also tends to lead towards a secondary problem when applied within a system. The problem is that the domain may be responsible for filling in parts of the event. Consider a system where the sale is processed by the domain itself, how much is the sales tax? Often the domain would be calculating this as part of its calculations. This leads to a dual definition of the event, there is the event as is sent from the client without the sales tax then the domain would receive that and add in the sales tax, it causes the event to have multiple definitions, as well as forcing mutability on some attributes. One can bypass this by having dual events (one for the client with just what it provides and another for the domain including what it has enriched the event from the client with) but this is basically the command event model and the linguistic problems still exist.

A further example of the linguistic problems involved can be shown in error conditions. How should the domain handle the fact that a client told it to do something that it cannot? This condition can exist for many reasons but let’s imagine a simple one of the client simply not having enough information to be able to source the event in a known correct way. Linguistically the command/event separation makes much more sense here as the command arrives in the imperative “Place Sale” while the event is in the past tense “SaleCompleted”. It is quite natural for the domain to reject a client attempting to “Place a sale”, it is not natural for the domain to tell the client that something in the past tense no longer happened. Consider the discussion with a domain expert, does the domain have a time machine? Parallel realities are far too complex and costly to model in most business systems.

These are exactly the problems that have led to the separation of the concepts of Commands and Events. This separation makes the language much clearer and although subtle it tends to lead developers towards a clearer understanding of context based solely on the language being used. Anytime one ends up with dual definitions of a concept there is a weight placed on the developer to recognize and distinguish context, this weight can translate into both ramp up time for new developers on a project and another thing a member of the team needs to “remember”. Anytime a team member needs to remember something to distinguish context there is a higher probability that it will be overlooked or mistook for another context. Being explicit in the language and avoiding dual definitions helps make things clearer both for domain experts, the developers, and anyone who may be consuming the API.

 

Works Cited

Fowler, M. (n.d.). Domain Event. Retrieved from EAA Dev: http://martinfowler.com/eeaDev/DomainEvent.html

Jill Nicola, M. M. (2001). Streamlined Object Modelling. Prentice Hall.

This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.

25 Responses to What is a Domain Event?

  1. Pingback: OCTO talks ! » CQRS, l’architecture aux deux visages (partie2)

  2. I’m opposed to the orthodoxy of standardized human grammars that are purported to exist outside of human contextualization.

  3. Hi, Scott and Greg

    “Ultimately, anything processed after the user clicks the submit button is in past tense.”

    I think the key point here is to recognise that software systems are not necessarily just event recorders. They can assume a more active role.

    For instance, in a system where credit approval is automated, the command AcceptOrder may result in an OrderAccepted event, but it could also result in an OrderDeclined event.

    In this case, the difference between AcceptOrder and OrderAccepted is relevant for the domain model. It is *not* “entirely a matter of perspective and the arbitrary point at which you begin running the clock.”

    In general, I think it is essential do make very clear the difference between commands and events. Adopting distinct naming styles (eg. imperative vs. past participle forms) is an immediate way to achieve this and has worked best for me.

    Considering the Ubiquitous Language’s value as a premisse, it is of course possible to adopt other linguistic conventions, as long as the difference is made explicit.

  4. Greg says:

    @Scott

    If the definition of a domain event is “a notification provided of something that occurred within the domain” then past tense is the only thing that makes sense … it is specified within the definition that it occurred (past tense).

    The definition in this way is deliberate. As I mentioned there is a very large difference in intent if I raise an event during a process (so others can join in a decoupled way) and after the process (so others can be notified of it). To put both of the contexts under a single pattern would lead to a very broad pattern that did not really expose the intent of either pattern. Making them separate makes the intents explicit. It also allows me to say the word “Domain Event” to someone and for them to have it carry with it the context and intent that I intend.

    A secondary reason of the definition is that the same events are used as an integration model later where they are necessarily asynchronous. This really forces the idea that the action already completed.

    This is not to say that the other type does not have value. This is to say that keeping them separate has value. The two have very different properties (including linguistics). This is roughly as if I am using a proxy to add functionality to an object is it still a proxy? No its a decorator, part of the value of the patterns being separated though structurally identical is that the name carries the intent as well as the structure.

    That said people have misused patterns as long as they have existed. If you feel the need to use an event that is representing “a notification of an action that occurred” and wish to name it with a present tense verb or a noun, its not that big of a deal. The only issue is that you won’t be able to use them in a sentence of your ubiquitous language with domain experts to concisely represent the context that you are in.

    What you seem to be arguing more with is the concept of maintaining the Ubiquitous Language than the specifics of Domain Events, frankly I don’t feel inclined towards a meta-discussion on the validity of the ubiquitous language. You may have found it to be of little value, I have found it of value, I am prepared to agree to disagree on this point. Though I must admit that discussion would be interesting in a more generalized way on the DDD list.

  5. Greg,

    From whence does this definition that prescribes past tense come? If I do everything else in the architecture pattern other than using past tense naming am I not using the pattern or the architecture?

    Ultimately, where can I go to have my architecture Domain Event Certified ™?

    Definitely not buying it. I sure wish that we could transfer knowledge of successful and sustainable development without the intellectual rigidity that makes sure that our best ideas have a shelf life of only a few months to a year.

  6. Greg says:

    @JeffG yes that is something that you would want to do in many cases for integration purposes.

  7. Greg says:

    @Scott

    “The tense depends entirely on the perspective you choose when modeling. While a purchase event is being processed, the purchase as a whole can still be seen as in-progress. There are parts of the whole that are still incomplete unless completeness is arbitrarily confined to a particular or a smaller perspective.”

    As I said previously the perspective is included in the defintion of what a domain event is. It is a notification of something that happenned. You could make up a different concept of a notification of something that is happening as I mention above, I do not even doubt the usefulness fo such a concept, but it would cease to be a domain event. Perhaps in the naming of these other things it may make sense to have different naming but in the context of a domain event it does not.

    The usage of past tense naming is directly related to the definition of a domain event. It really doesn’t make any sense in the context of a domain event to use any other form of naming.

  8. Jeff G says:

    Great stuff.
    I haven’t yet used an ESB, but it sounds like Domain Events are the type of events that others modules are interested in and are typically published via an ESB.

  9. Greg,

    It’s perfectly clear. It never was unclear. It’s not that I don’t understand what you’re proposing, but that I refute it utterly and completely on the basis that a finer analysis of context and contextualization presents a meaningful challenge to this language fundamentalism.

    Ultimately, anything processed after the user clicks the submit button is in past tense. Even the receipt of the web request on the front controller is in the past tense. The language tense is entirely a matter of perspective and the arbitrary point at which you begin running the clock.

    The message processor is doing its work in the present tense, regardless of atomicity of transactions.

    In the end, there’s no such thing as an atomic transaction in material space. It’s turtles all the way down… until you get to the message loop, and then it’s turtles and anti-turtles. Some of the anti-turtles are executed transparently, providing a semblance of atomic transactional. It’s still just an act when you get down to the bare metal.

    The tense depends entirely on the perspective you choose when modeling. While a purchase event is being processed, the purchase as a whole can still be seen as in-progress. There are parts of the whole that are still incomplete unless completeness is arbitrarily confined to a particular or a smaller perspective.

    I don’t symbolize or identify events as past tense because this couples a particular perspective to them. It binds them to a particular dimension that is ultimately superfluous.

    If any particular dimension is significant, to how an event is processed, it can become part of the event’s data itself, its metadata, or it can be represented as a naming convention.

    The naming convention isn’t significant unless we give it significance. If we choose to give it significance, then we respect in within the confines of the software where it has significance. Nonetheless, it’s still a choice, and a choice that should be driven by context and perspective, which in the end doesn’t necessarily dictate an orthodox prescription for naming convention and tense.

    I don’t think the community in particular or society in general benefits from more orthodoxy, which is what I see this proposal as.

  10. Greg says:

    Scott “When purchasing an item” is perfectly valid for something that is in the use case of purchasing an item in terms of a context specification. remember that the event is being processed asynchronously some point *after* the use case has run (it may be done synchronously but is assumed to be asynchronous). The context is not that an item is being purchased it is that an item was purchased (the operation has already completed by the time you get the event). This is also put forward in the definition of an event being a notification of something that has occurred.

    If you accept the definition of a domain event as being “a notification of something that has occurred” then “purchasing” doesn’t work, it is not something that has occurred it is something that is occurring. The contextual differences between something that has occurred and something that is occurring are large.

    If we were in the context of “when purchasing and item” it would be feasible to stop the purchasing of an item as its “in process”. An event handler can’t just cancel the event it receives, it needs to apply a compensating action, it can’t undo the thing that occurred. The contextual differences here are being expressed in the language.

    That said there may be a case where you could could have use for something operating in the context of the process utilizing a code pattern similar to a domain event, I do not discount this possibility (.net events come to mind, they can be cancelled and are considered to be running in the same transaction as the producer). It would however not be a Domain Event, it would be another pattern as it has a slightly different intent. My linguistic discussion here is limited to the scope of a Domain Event not an Event or even Message. Does that make sense?

  11. Greg,

    > When a purchase in the sales system then ….

    You can specify the same thing in present tense and it can mean the exact same thing:

    “When purchasing, then …”

    Which, by the way is the basis of the Context Specification method that I use. It’s feasible because context is also communicated as part of the specification:

    “Event Processing
    - When purchasing, then … ”

    It matters more how disambiguation is done within the very human realm of communication of meaning within an organization. Naming conventions for systems artifacts are useful, but not definitive without the human considerations that they ultimately serve.

    I find a lot of discussion about ubiquitous language to be a bit shallow when it has too much of the 1990′s OOA&D predilections.

    Ultimately, I value this discussion about the grammar and cultural linguistic particularities that are usually left implicit in discussions about ubiquitous language. In the end, I’m not in favor of a grammar than tries to have the formality of a machine-processed language that can live outside the contextualization that serves shared meaning between people and organizations.

    I’m not just opposed to the particular grammar that you’ve proposed as an orthodoxy, I’m opposed to the orthodoxy of standardized human grammars that are purported to exist outside of human contextualization.

    There’s little doubt in my mind that I still have much to learn from you about the particularities of implementing the patterns that you have great expertise in, but I remain unphased by the propositions for human specification and human communication that we’re presently debating, and have been debating for the past few years.

    I respectfully disagree and suggest that there’s more to this issue than the kind of mere linguistic standardization that programmers are prone to use as a lens to see the world that they are caused to serve.

  12. Greg says:

    @Ryzam moment-interval is roughly the same as SOM’s Transaction Object. I will include it in the full version of the text. Thanks for the heads up.

    Greg

  13. Greg says:

    @Gabriel perhaps you are missing that this is involved with Domain Driven Design and these “Domain Events” are part of the Ubiquitous Language? This is not being brought up in a general context of what is an event.

    It is extremely important what language the events are in and has nothing to do with coding standards in an organization etc. It has to do with how you talk with domain experts. All of the examples you gave in the past tense are valid, and its a matter of how the domain experts talk about it. The others are not as there is no way the domain experts would possibly use those words.

    I still welcome you to come up with a sentence from a domain expert that would use the noun form (transaction object) to describe a notification. The fact is that you cannot, you need to introduce a helper verb. If you cannot make a valid English sentence in that form how can you expect it to be in your Ubiquitous Language? Will you just use incorrect grammar in all of your conversations with your domain experts?

    Also you should never have an “OrderIsProcessing” Event. Events are by their nature asynchronous, you have no idea how long it will take to get to a receiver or if the order will still be processing when the receiver gets the event. This is a well known messaging anti-pattern instead use “OrderBeganProcessing”. Note again we are back to a verb that has completed in the past. This is not some fluffy rule where organizational preferences come into play, the usage of verbs in the past tense is always more correct as you can’t build English sentences in any other way and these events are part of the Ubiquitous Language.

  14. ryzam says:

    What is the different between your Domain Events definition compare to Moment Interval (Peter Coad) Color Modeling?

    Is it similar

  15. Gabriel Lozano-Moran says:

    Depending on the needs from the business there might be a need for a “OrderIsProcessing” event and a “OrderIsProcessed” event but in all honestly when I encounter this, I would look for a better name for this event.

    I am just saying that in all honestly it does not matter what YOUR naming convention is. Just accept that fact that neither mine, yours nor Scotts convention is BEST convention. Just agree on a convention @ your company and stick to that convention. Don’t mix conventions and don’t start a holy war on naming conventions.

    You can name the event whatever you want such as “OrderProcess”, “OrderProcessed”, “OrderBecameProcessed”, “OrderIsProcessed”, “ProcessedOrder” … as long as we don’t forget the main purpose of domain events. And that is what I meant whith my comment. Your blog post is titled what is a domain event and the discussion ends up arguing about naming conventions for the events… This is some kind of illness I am starting to see more and more with technical people.

  16. Greg says:

    @Gabriel Love the tone in your comment…

    I spend most of my time WORKING with domain experts. The whole problem with using the noun there is that they end using a helper verb when they discuss it as a trigger for an action. A “purchase was created” you can’t actually build a valid english sentence describing an event you can trigger off of if you use the “Transaction Object” noun form from SOM.

    The “Transaction Object” is not meaningless. It is often used within the domain to model that particular transaction within the domain as an entity, it is however not something that is being published to trigger off of. In many cases you will actually end up with a pair of objects, the first a SOM style “Transaction Object” in the domain the second a “Domain Event” that the domain publishes to anyone subscribing to it. The second concept is a “Notification of an Occurence” not a modeling of the occurrence. I will make this point clearer in my original text. This goes to Nuno’s comment as well though I put up a comment on the DDD list. Its not that the Domain Event replaces the SOM transaction object, they are different things with different goals.

    @Gabriel Of course if you believe it depends on context and domain maybe you can make me a sentence involving a notification of an occurence that doesn’t use a helper verb?

    Greg

  17. Greg says:

    Szymon the events as Eric is describing there a “Transient Event Stream” would be the same style events as described above.

    I am pretty sure Udi and I have been in agreement on the definition of an Event for a long time. You will note he is also using the past tense structure. There may be some slight differentiations in how we use them but the fundamental definition probably doesn’t change.

  18. Nuno Lopes says:

    Hi Greg,

    If the domain-events are suppose to capture for events in the domain I find some challenges with your interpretation of it.

    As you describe them, they fundamentally report about domain occurrences rather then actually model The Occurrence. I think that is why the wording in the past tense as well as being anaemic works quite well (its about data, message, although well named)

    If they aren’t suppose to capture the actual occurrences then I can live with the name :)

    Interesting read anyway. Glad that SOM is getting some recognition amongst DDD.

    Cheers

    Nuno

  19. Gabriel Lozano-Moran says:

    Whether the event should be called Purchase or Purchased depends on the event it itself and the actions it triggers. Maybe from the viewpoint of the business there should be two domain events? Purchase and Purchased? I love how technical guys always have these theological debates about these, and if you really think about it you will admit it, meaningless details.

  20. AFAIK Eric was talking about what he learned since the book at QCon. The video is here: http://www.infoq.com/presentations/ddd-eric-evans. Event-related part starts after 13 minutes. Actually Eric discusses three different event implementation options (including yours). I agree that immutable entity one is similar to SOM style you discussed. He also mentions the option of publishing ‘transient’ event stream, for example used to decouple transaction and reporting systems. This seems similar to Udi Dahan’s domain events described here: http://www.udidahan.com/2009/06/14/domain-events-salvation/. I am not sure, but Eric mentions something called system events and what Udi describes seems to fit in that definition. What do you think?

  21. Mark Rogers says:

    Your work cited url for Fowler’s ‘DomainEvent’ article is off by one letter, the ‘eea’ in ‘http://martinfowler.com/eeaDev/DomainEvent.html’ should be ‘eaa’, for the correct url is: ‘http://martinfowler.com/eaaDev/DomainEvent.html’.

    It might help people who want to look it up.

    Thanks,
    Mark

  22. Greg says:

    Scott,

    Purchase is a great example of the SOM style event definition it is a transaction that occurred at a point in time, it has temporal information associated with it. For these types of events it can feel natural to use the noun form as you do in some scenarios (say as a transaction object in the domain which it probably would be and the linguistics there make sense).

    Outside though it becomes a bit weirder when you are triggering behaviors off of it. Triggering a behavior off of “Purchase” becomes interesting in terms of building a sentence.

    When a purchase in the sales system then ….
    When an item was purchased in the sales system then ….

    What is happening here is that you are using a noun that is representing a verb. The “purchase” is in fact representing a verb that happened. The differences are indeed subtle and one can especially with a good team get over any problems that may come up, I would still say though that as a general rule one should be using events in the past tense to avoid confusion.

  23. Greg says:

    Can you provide citings for these so I can better understand their context? I would be happy to add a section with contrasts with these definitions. I have been writing this in a very formal style and would need citations in order to put them in.

    Off the cuff it sounds like Eric is talking more about the SOM definition …

  24. I completely disagree that events need to be named in past tense and they must be named as verbs. This seems to me to be a vestige of programming language culture, and specifically the static object-oriented language culture.

    I’ve found a greater willingness in myself to break from the orthodoxy of VerbNoun naming forms since adopting programming languages that are more amenable to language-oriented development, and I’ve found myself looking back on the strictures of my mind as primarily a C# or Java programmers as a kind of naivete and the kind of cognitive attachment that obstructs learning and seeing the next evolutionary stage.

    I’ve got no problem with symbolizing a purchase that has been made with an event named “Purchase”, is in, “this event represents a purchase that has been made”. What matters more is semantics and how they’re treated both by the team and by the event listeners. It’s how we disambiguate as cognitive beings and how we inform our systems to do the same.

    In the end, the machines will do what they’re told, and tenses of verbs don’t make a lick of difference except if the machines are told to respect a certain convention implicitly.

    There are so many meaningful ways to semantically model the goings-on in our systems, and while it may be confusing for a system to have both a “Purchase” event and a “Purchase” command, I wouldn’t agree at all that it’s necessary to impose a single orthodoxy on the means of disambiguation, and it’s possible that Martin – having also been quite deeply entwined in language-oriented approaches – may also be reflecting this nascent tendency.

  25. There are at least two more Domain Event definitions which confuse me more than these two you’ve just described (although I must say you did awesome work contrasting your understanding with Fowler’s and not being afraid to not agree with him):
    * Udi Dahan’s ‘transient’ events as a way of pushing data out of the domain
    * I saw a presentation where Eric Evans discussed gaps in his Blue Book and was speaking about Domain Events are immutable entities, possibly aggregate roots in the model
    Could you clarify how, in your opinion, these additional definitions relate to your understanding of Domain Events?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>