Validation of context in Domain-Driven Design

Domain-driven design (DDD) is not just a technology or a methodology. It offers a set of practices and terms to help make design choices that simplify and speed up software projects, especially those dealing with complex domains. As described by Eric Evans and Martin Fowler have noted, Domain objects are a suitable place for storing validation rules and business logic.

Eric Evans states:

The Domain Layer (or Model Layer) is key to representing business concepts, information about the business situation, and business rules. It manages and uses the state that reflects the business situation, although the technical storage details are handled by the infrastructure. This layer is at the core of business software.

Martin Fowler adds:

The logic within a domain object should be domain logic - validations, calculations, business rules - whatever term you prefer.

Context Validation in Domain-Driven Design

However, placing all validation within Domain objects can lead to unwieldy and complicated objects. I believe in separating domain validations into independent validator components that can be reused whenever needed and adapt to the context and user action.

Martin Fowler writes in an insightful article: ContextualValidation.

I frequently observe developers creating validation routines for objects. These routines can take different forms: within the object or external, returning a boolean or throwing an exception to signal failure. However, developers often stumble when they view object validity without considering the context, like an isValid method suggests. […] I believe it’s more helpful to consider validation as something tied to a specific context, usually an action you want to perform. For instance, asking if an order is valid for fulfillment or a customer is valid for hotel check-in. Therefore, instead of methods like isValid, use methods like isValidForCheckIn.

Action Validation Proposal

This article will demonstrate a simple interface, ItemValidator, requiring you to implement a validate method returning a ValidationResult. This object contains the validated item and a Messages object, which gathers errors, warnings, and information validation states (messages) based on the execution context.

Validators are self-contained components, easily reusable wherever needed. This approach allows for the straightforward injection of any dependencies required for validation checks. For instance, validating if a user with a specific email exists in the database would only require the UserDomainService.

Validator separation will be context (action) specific. So, UserCreate and UserUpdate actions will have separate components, and the same applies to other actions (UserActivate, UserDelete, AdCampaignLaunch, etc.). This can lead to a rapid increase in validation components.

Each action validator should have a corresponding action model containing only the permitted fields for that action. For creating users, the necessary fields are:

UserCreateModel:

1
2
3
4
5
6
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@gmail.com",
  "password": "MTIzNDU="
}

For updating a user, the allowed fields are externalId, firstName, and lastName. The externalId is used for user identification, and only changes to firstName and lastName are permitted.

UserUpdateModel:

1
2
3
4
5
{
  "externalId": "a55ccd60-9d82-11e5-9f52-0002a5d5c51b",
  "firstName": "John Updated",
  "lastName": "Doe Updated"
}

Validations related to field integrity can be shared. For instance, the maximum length for firstName is always 255 characters.

During validation, it is beneficial to gather all encountered issues instead of just the first error. For example, the following three issues could occur simultaneously and should be reported accordingly:

invalid address format [ERROR]
email must be unique among users [ERROR]
password too short [ERROR]

To achieve this, a validation state builder is needed, which is where Messages comes in. I learned about the concept of Messages from a mentor who introduced it for validation and various other purposes, as Messages are not limited to validation.

Note: We will be using Scala to illustrate the implementation in the following sections. Don’t worry if you are not a Scala expert; it should be easy to understand.

Messages in Context Validation

Messages is an object representing the validation state builder. It offers a convenient way to collect error, warning, and information messages during validation. Each Messages object contains a collection of Message objects and can reference a parentMessages object.

A Message object includes the following: type, messageText, key (optional, used to support validation of specific inputs identified by an identifier), and childMessages (enables the creation of composable message trees).

A message can be one of these types:

Information
Warning
Error

Structuring messages in this way allows for iterative building and enables decisions about subsequent actions based on the current message state. For instance, consider validation during user creation:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
@Component
class UserCreateValidator @Autowired (private val entityDomainService: UserDomainService) extends ItemValidator[UserCreateEntity] {
  Asserts.argumentIsNotNull(entityDomainService)

  private val MAX_ALLOWED_LENGTH = 80
  private val MAX_ALLOWED_CHARACTER_ERROR = s"must be less than or equal to $MAX_ALLOWED_LENGTH character"

  override def validate(item: UserCreateEntity): ValidationResult[UserCreateEntity] = {
    Asserts.argumentIsNotNull(item)

    val validationMessages = Messages.of

    validateFirstName (item, validationMessages)
    validateLastName  (item, validationMessages)
    validateEmail     (item, validationMessages)
    validateUserName  (item, validationMessages)
    validatePassword  (item, validationMessages)

    ValidationResult(
      validatedItem = item,
      messages      = validationMessages
    )
  }

  private def validateFirstName(item: UserCreateEntity, validationMessages: Messages) {
    val localMessages = Messages.of(validationMessages)

    val fieldValue = item.firstName

    ValidateUtils.validateLengthIsLessThanOrEqual(
      fieldValue,
      MAX_ALLOWED_LENGTH,
      localMessages,
      UserCreateEntity.FIRST_NAME_FORM_ID.value,
      MAX_ALLOWED_CHARACTER_ERROR
    )
  }

  private def validateLastName(item: UserCreateEntity, validationMessages: Messages) {
    val localMessages = Messages.of(validationMessages)

    val fieldValue = item.lastName

    ValidateUtils.validateLengthIsLessThanOrEqual(
      fieldValue,
      MAX_ALLOWED_LENGTH,
      localMessages,
      UserCreateEntity.LAST_NAME_FORM_ID.value,
      MAX_ALLOWED_CHARACTER_ERROR
    )
  }

  private def validateEmail(item: UserCreateEntity, validationMessages: Messages) {
    val localMessages = Messages.of(validationMessages)

    val fieldValue = item.email

    ValidateUtils.validateEmail(
      fieldValue,
      UserCreateEntity.EMAIL_FORM_ID,
      localMessages
    )

    ValidateUtils.validateLengthIsLessThanOrEqual(
      fieldValue,
      MAX_ALLOWED_LENGTH,
      localMessages,
      UserCreateEntity.EMAIL_FORM_ID.value,
      MAX_ALLOWED_CHARACTER_ERROR
    )

    if(!localMessages.hasErrors()) {
      val doesExistWithEmail = this.entityDomainService.doesExistByByEmail(fieldValue)
      ValidateUtils.isFalse(
        doesExistWithEmail,
        localMessages,
        UserCreateEntity.EMAIL_FORM_ID.value,
        "User already exists with this email"
      )
    }
  }

  private def validateUserName(item: UserCreateEntity, validationMessages: Messages) {
    val localMessages = Messages.of(validationMessages)

    val fieldValue = item.username

    ValidateUtils.validateLengthIsLessThanOrEqual(
      fieldValue,
      MAX_ALLOWED_LENGTH,
      localMessages,
      UserCreateEntity.USERNAME_FORM_ID.value,
      MAX_ALLOWED_CHARACTER_ERROR
    )

    if(!localMessages.hasErrors()) {
      val doesExistWithUsername = this.entityDomainService.doesExistByUsername(fieldValue)
      ValidateUtils.isFalse(
        doesExistWithUsername,
        localMessages,
        UserCreateEntity.USERNAME_FORM_ID.value,
        "User already exists with this username"
      )
    }
  }

  private def validatePassword(item: UserCreateEntity, validationMessages: Messages) {
    val localMessages = Messages.of(validationMessages)

    val fieldValue = item.password

    ValidateUtils.validateLengthIsLessThanOrEqual(
      fieldValue,
      MAX_ALLOWED_LENGTH,
      localMessages,
      UserCreateEntity.PASSWORD_FORM_ID.value,
      MAX_ALLOWED_CHARACTER_ERROR
    )
  }
}

This code snippet utilizes ValidateUtils, utility functions for populating the Messages object in predefined scenarios. You can examine the implementation of the ValidateUtils on Github code.

During email validation, we first check if the email is valid using ValidateUtils.validateEmail(…, followed by checking its length using ValidateUtils.validateLengthIsLessThanOrEqual(…. Only if both checks pass do we proceed to verify if the email is already assigned to a user using if(!localMessages.hasErrors()) { …. This approach avoids unnecessary database calls. Keep in mind that this is only a part of UserCreateValidator; the complete source code is available here.

Notice the validation parameter UserCreateEntity.EMAIL_FORM_ID. This parameter links the validation state to a specific input ID.

In the previous examples, the next action depends on whether the Messages object contains errors (using the hasErrors method). You could easily check for “WARNING” messages and retry if necessary.

Another notable aspect is the use of localMessages. Local messages are created like any other message but with a parentMessages reference. The goal is to have a reference solely to the current validation state (in this example, emailValidation), allowing the use of localMessages.hasErrors. This checks for errors only within the emailValidation context. Additionally, adding a message to localMessages also adds it to parentMessages, ensuring that all validation messages are present in the higher context of UserCreateValidation.

Having seen Messages in action, let’s focus on ItemValidator in the next section.

ItemValidator - Reusable Validation Component

ItemValidator is a simple trait (interface) that requires developers to implement a validate method returning a ValidationResult.

ItemValidator:

1
2
3
trait ItemValidator[T] {
  def validate(item:T) : ValidationResult[T]
}

ValidationResult:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
case class ValidationResult[T: Writes](
  validatedItem : T,
  messages      : Messages
) {
  Asserts.argumentIsNotNull(validatedItem)
  Asserts.argumentIsNotNull(messages)

  def isValid :Boolean = {
    !messages.hasErrors
  }

  def errorsRestResponse = {
    Asserts.argumentIsTrue(!this.isValid)

    ResponseTools.of(
      data      = Some(this.validatedItem),
      messages  = Some(messages)
    )
  }
}

By implementing ItemValidators, such as UserCreateValidator, as dependency injection components, you can inject and reuse them in any object requiring UserCreate action validation.

After validation, we check if it was successful. If so, user data is saved to the database; otherwise, an API response containing validation errors is returned.

Next, we will explore how to present validation errors in a RESTful API response and communicate execution action states to API consumers.

Unified API Response - Simple User Interaction

After successfully validating a user action (in this case, user creation), you need to present the results to the RESTful API consumer. The best approach is to use a unified API response, where only the context changes (specifically, the “data” value in JSON). Unified responses facilitate the presentation of errors to API consumers.

Unified response structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "messages" : {
        "global" : {
            "info": [],
            "warnings": [],
            "errors": []
        },
        "local" : []
    },
	"data":{}
}

The unified response has two message tiers: global and local. Local messages are tied to specific inputs (e.g., “username is too long, at most 80 characters allowed”), while global messages reflect the state of the entire page’s data (e.g., “user will not be active until approved”). Both local and global messages have three levels: error, warning, and information. The “data” value is context-specific. When creating users, it contains user data; when retrieving a list of users, it contains an array of users.

This structured response allows for creating a simple client UI handler to display error, warning, and information messages. Global messages are displayed at the top of the page due to their relation to the global API action state, while local messages appear near their corresponding input fields. Error messages are displayed in red, warnings in yellow, and information in blue.

For example, in an AngularJS client app, you could have two directives handling local and global response messages. This ensures consistent handling of all responses.

The local message directive needs to be applied to the parent element of the element holding all the messages.

localmessages.direcitive.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
(function() {
  'use strict';

  angular
    .module('reactiveClient')
    .directive('localMessagesValidationDirective', localMessagesValidationDirective);

  /** @ngInject */
  function localMessagesValidationDirective(_) {
    return {
      restrict: 'AE',
      transclude: true,
      scope: {
        binder: '='
      },
      template: '<div ng-transclude></div>',
      link: function (scope, element) {

        var messagesWatchCleanUp = scope.$watch('binder', messagesBinderWatchCallback);
        scope.$on('$destroy', function() {
          messagesWatchCleanUp();
        });

        function messagesBinderWatchCallback (messagesResponse) {
          if (messagesResponse != undefined && messagesResponse.messages != undefined) {
            if (messagesResponse.messages.local.length > 0) {
              element.find('.alert').remove();
              _.forEach(messagesResponse.messages.local, function (localMsg) {

                var selector = element.find('[id="' + localMsg.inputId + '"]').parent();

                _.forEach(localMsg.info, function (msg) {
                  var infoMsg = '<div class="form-control validation-alert alert alert-info alert-dismissable"><button type="button" class="close" data-dismiss="alert" aria-hidden="true">×</button>' + msg + '</div>';
                  selector.after(infoMsg);
                });

                _.forEach(localMsg.warnings, function (msg) {
                  var warningMsg = '<div class="form-control validation-alert alert alert-warning alert-dismissable"><button type="button" class="close" data-dismiss="alert" aria-hidden="true">×</button>' + msg + '</div>';
                  selector.after(warningMsg);
                });

                _.forEach(localMsg.errors, function (msg) {
                  var errorMsg = '<div class="form-control validation-alert  alert alert-danger alert-dismissable"><button type="button" class="close" data-dismiss="alert" aria-hidden="true">×</button>' + msg + '</div>';
                  selector.after(errorMsg);
                });
              });
            }
          }
        }
      }
    }
  }

})();

The global message directive will be included in the root layout document (index.html) and register for an event to handle all global messages.

globalmessages.directive.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
(function() {
  'use strict';

  angular
    .module('reactiveClient')
    .directive('globalMessagesValidationDirective', globalMessagesValidationDirective);

  /** @ngInject */
  function globalMessagesValidationDirective(_, toastr, $rootScope, $log) {
    return {
      restrict: 'AE',
      link: function (scope) {

        var cleanUpListener = $rootScope.$on('globalMessages', globalMessagesWatchCallback);
        scope.$on('$destroy', function() {
          cleanUpListener();
        });

        function globalMessagesWatchCallback (event, messagesResponse) {
          $log.log('received rootScope event: ' + event);
          if (messagesResponse != undefined && messagesResponse.messages != undefined) {
            if (messagesResponse.messages.global != undefined) {
              _.forEach(messagesResponse.messages.global.info, function (msg) {
                toastr.info(msg);
              });

              _.forEach(messagesResponse.messages.global.warnings, function (msg) {
                toastr.warning(msg);
              });

              _.forEach(messagesResponse.messages.global.errors, function (msg) {
                toastr.error(msg);
              });
            }
          }
        }
      }
    }
  }

})();

For a clearer illustration, consider the following response containing a local message:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "messages" : {
        "global" : {
            "info": [],
            "warnings": [],
            "errors": []
        },
        "local" : [
           {
                "inputId" : "email",
                "errors" : ["User already exists with this email"],
                "warnings" : [],
                "info" : []
            }
        ]
    },
	"data":{
	    "firstName": "John",
	    "lastName": "Doe",
	    "email": "john.doe@gmail.com",
      "password": "MTIzNDU="
    }
}

This response could lead to the following:

Conversely, consider a response with a global message:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "messages" : {
        "global" : {
            "info": ["User successfully created."],
            "warnings": ["User will not be available for login until is activated"],
            "errors": []
        },
        "local" : []
    },
	"data":{
	    "externalId": "a55ccd60-9d82-11e5-9f52-0002a5d5c51b",
	    "firstName": "John",
	    "lastName": "Doe",
	    "email": "john.doe@gmail.com"
    }
}

The client app can then display this message with higher prominence:

These examples demonstrate how a unified response structure allows handling different requests with the same handler.

Conclusion

Implementing validation in large projects can easily become disorganized, leading to validation rules scattered throughout the codebase. Maintaining consistent and well-structured validation makes it easier to manage and reuse.

You can find these ideas implemented in two different boilerplate versions:

This article presented my suggestions for implementing deep, composable context validation and presenting it to the user effectively. I hope this helps you tackle the challenges of proper validation and error handling. Feel free to leave your comments and share your thoughts below.