On Business Rules project best practices – Part VII – Model and Vocabulary

This entry is part 7 of 7 in the series Business Rules Project Best Practices

In the first post of this series, I started listing a list of best practices that can and should be used when working on a business rules project. This post is about detailing one of these practices further.

Of all the best practices listed so far, this is the one that I believe to be the most critical to the success of a rules project.

Why did I wait so long in the series to introduce it? Well, I could have started with it, but it is not the only best practice that needs to be considered and if the first best practice is being followed (Get help and educate yourself), hopefully the model and vocabulary will be one of the main things some external help will push for.


You can choose to skip this section and refer back to it when you encounter the word for the first time later in the article.

Before we continue with the rest of this article, it will be useful for me to provide some definitions that will be used in the article.

  • Term: a word or phrase used to describe a thing or to express a concept [1]
  • Concept: an abstract idea. Concepts are expressed by terms. [1]
  • Fact: Facts relate terms [2]
  • Fact Type: a fact type is an association between two or more concepts
  • Vocabulary: the body of words used in a particular language or in a particular sphere [1]
  • Terminology: the body of terms used in a subject of study, profession, etc. [1]
  • Fact Model: A fact model establishes the basis for shared operational business knowledge. [2] This model is usually graphical and can also be called the business object model or BOM.

The business vocabulary

Let me start with the vocabulary. This refers to the language being used by the business people to do their day to day work when they refer to what they are working on. It can also be called terminology [3]. In our specific case, we are interested in the vocabulary used by the business people, so we are referring to a business vocabulary. In the article I will usually use the shorter “vocabulary”, but it means “business vocabulary”.

Why are we talking about vocabulary? Because we need to formalize this vocabulary, clarify definitions and meanings to remove as much ambiguity as possible. This vocabulary will be used to create a fact model that will be used by the rest of the project and by the rules.

This formalized vocabulary needs to be well documented, agreed upon and communicated by the business people. There needs to be a central location for the documentation of this vocabulary.

Some will ask: I know my business, so why should I document and formalize a vocabulary? The answer is simple. Not all the people working on an IT project are as knowledgeable about the business, and ambiguity or misunderstanding of terms used by the business people can have unexpected results. I will try to explain more with a couple of examples.

I once worked with a customer that was in the importing and distribution of goods. One of the first things I usually try to do is to either look for an existing vocabulary (which did not exist) or to learn about the business to start building a vocabulary.

As I was learning about their particular business, the business person I was talking to referred to a “Purchase Order” (or PO) a few times and at some point I had to stop him and ask: “When you talk about the PO, which PO are you referring to?” He looked at me with a blank stare. “Well”, I continued, “when you place an order to your SUPPLIERS, you use a PO correct?” He simply answered “Yes”. I continued “Also, when your CUSTOMERS place an order to you they use a PO, correct?” He nodded. “Well then which PO are you talking about? The supplier PO or the customer PO?”

I will spare you the rest of the conversation in which we went on to clarify the vocabulary that they were using in that particular business, but that short conversation shows how something seemingly simple sometimes requires some clarification.

Both Purchase Orders had similar attributes but they also had specific attributes that made them different. These need to be documented well in any project, but specifically in a business rules project where some rules may need to refer to Purchase Orders and in that case we may need to know which one it is.

As a second (shorter) example

On a another project that I worked on dealing with the company customers, in discussions the business people were using the terms customer and client somewhat interchangeably. We needed to clarify if they were the same thing or if they were actually different things for that system. Once again clarification of the vocabulary was required.

The point to this exercise is that we need to document, formalize and clarify a vocabulary that will be used in the project. If there is confusion about a term, go back to the vocabulary, discuss it and if required, make the necessary adjustments since it is a work of progress after all.

Building the vocabulary

The vocabulary can be built using multiple techniques, but some of the usual ones are:

  • Interviews with business people
  • Review of documentation
  • Review of current systems

The vocabulary will be a work in progress and you should not expect to build it completely before starting other work. You should start building the vocabulary with the most common terms, and eventually put it aside to come back and add or update the vocabulary as needed throughout the project. It is an incremental piece of work (sometimes tedious) but essential to the rest of your rule project.

The model

Now that we have a vocabulary that the business agrees upon, it is time to start working on the model (sometimes called a fact model). This model is used to represent the main entities from our vocabulary (if not all) and their relationships to each other. This will be a very useful tool when trying to write business rules since it will graphically show what the business and the rules are about.

Here is an example of a simple model:

It may also be used to identify gaps in the current vocabulary as I will demonstrate below.

The model on the left shows the first pass at coming up with a vocabulary and building a model from it. It became apparent that there was a concept missing and therefore the vocabulary was amended to add the term “pet” of which Dog and Cat are types. The resulting model is shown on the right.

The model can also become the starting point for other work that will be required in the project such as a data model and an object model. So we could add additional information such as multiplicity between the facts as shown below.

All of these details will give the business a common starting point when discussing anything between themselves or with other people, especially IT technical people.

The Foundation for other work

When discussing the importance of the vocabulary and model when dealing with rules, I often compare it to the foundation for a house.

Having a good foundation for a house will allow building sound structure on top. Having a good vocabulary and model will allow you to build good rules.

Adding an extension to the foundation and structure of an existing house will allow the house to evolve and fit the new needs of the owners. Similarly, it is possible to add to a good vocabulary and model and eventually to rules and it is to be expected.

The danger lies in the inappropriate foundation of a house. If the foundation for a house is inappropriate and needs to be redone without touching too much of the existing structure, it is possible, but it is complicated and costly. The house needs to be lifted of the current foundation, the current foundation need to be destroyed, the new foundation needs to be built and then the house can rest on the new foundation again.

The same goes for the vocabulary and model used for business rules. If the vocabulary and model are not done properly to start with, it will be hard work to change it later, especially if rules have already been built using them.


Should you start with the model or the vocabulary? I personally like working the model and building the vocabulary that goes with it alongside. How you decide to do it in your environment is not that important. What IS important is that you DO actually create the model and vocabulary. These will be the building blocks of the foundation for a lot more work in the future. If you don’t have it, your foundation may be too flimsy to support that future.

[1] From askoxford.com, oxford dictionaries

[2] Ross, Ronald G., Business Rule Concepts, 2005, Business Rules Solutions

[3] Terminology denotes a more formal discipline which systematically studies the labeling or designating of concepts particular to one or more subject fields or domains of human activity, through research and analysis of terms in context, for the purpose of documenting and promoting correct usage. From wikipedia.

Series Navigation<< On Business Rules project best practices – Part VI – Divide and Conquer

Leave a Reply

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