Section 1.  Introduction

The RuleSpeak® keyword "the following" is used to organize multiple conditions in a single business rule statement.  Otherwise the conditions would need to be expressed using either:

• Strings of "and's" and "or's".  Business people and others often find such strings difficult and tedious to comprehend.
  
  
• Multiple statements.  The overall number of business rule statements to be managed is already likely to be significant.  The prudent approach is to reduce the total, rather than increase it unnecessarily.

The RuleSpeak keyword "the following" is always accompanied by:

1. A list of indented bulleted conditions.
2. A threshold indicating how many of the conditions are required to be true.

Common thresholds include all the following and any of the following.

RuleSpeak tabulation in no way replaces or substitutes for decision tables.  If a decision table can be used to represent some business rules, it should be.^[1]  A very large number of business rules, however, simply cannot be represented in decision tables in any meaningful way.

Tabulation in Formal Writing

Using lists of indented bullet items is called tabulation (after the keyboard tab key used to indent).  Tabulation is a stylistic device commonly applied in legal and other forms of writing for simplification and clarity.

Example of contractual provisions without tabulation^[2] …

For a one-year period after the Term, the Executive shall not employ any person who was an employee during the Term.  In addition during that period, the Executive shall not interfere with the relationship between the Company and any of its employees.

Tabulated version …

For a one-year period after the Term, the Executive

1. shall not employ any person who was an employee during the Term; and
2. shall not interfere with the relationship between the Company and any of its employees.

The tabulated version is more approachable and much easier for the reader to assimilate correctly.

As the above example illustrates, in tabulation the subject matter must be common to each subsequent item.  Specifically, the phrase at top, "For a one-year period after the Term, the Executive", applies equally and directly to each item below it.  Showing common subject matter at the top of a statement is a basic rule for tabulation.

Tabulation in Expressing Business Rules

This basic rule for tabulation also applies to expressing business rules.  The following example illustrates how the common subject matter in three separate business rules can be unified, thus enabling consolidation.  The common subject matter has been italicized for emphasis only.

Example without tabulation …

A claim must be considered potentially fraudulent if the claimant has made more than six claims in the last two years.

A claim must be considered potentially fraudulent if the claimant has owned more than five vehicles in the last year.

A claim must be considered potentially fraudulent if the claimant has a history of fraudulent claims.

Tabulated version …

A claim must be considered potentially fraudulent if any of the following is true:

• The claimant has made more than six claims in the last two years.
• The claimant has owned more than five vehicles in the last year.
• The claimant has a history of fraudulent claims.

Now there is only a single business rule statement instead of three.

All business rules properly expressed under RuleSpeak are declarative.  Note in the revised version of the example above, the tabulated conditions are bulleted rather than numbered or lettered (as was the case in the earlier contractual example). 

This bullet convention avoids any suggestion of sequence, importance, or priority.  (If priority is intended, the statement must mention priority explicitly.)

Since the order in which bullets are listed is logically immaterial, they can appear in random sequence — or better, in the sequence readers find most friendly.

In the example above, note that each bulleted condition begins with "The claimant has".  This phrase could also be removed and consolidated with the common subject matter. 

How far unification of all common subject matter in a given case should be taken is a judgment call.  The answer should hinge on what proves the most readable and business-friendly. 

We will return to this issue in Section 3, which discusses specific usage guidelines for "the following".

Section 2.  Why Use Tabulation

There are important reasons to use tabulation in writing business rules.  It provides structure both for thinking about business rules and laying them out in a manner that lends itself naturally to asking questions and identifying ambiguities, gaps, and inconsistencies.  Understanding the related issues can enhance your skills in writing business rules significantly.

Eliminating Ambiguity

1.  Use of "and" where "or" is actually meant

Example …

A shipment may be made only to the European countries United Kingdom and The Netherlands.

This business rule statement could be interpreted to mean any given shipment may be made only to both countries listed.  Sending the same shipment to both countries is almost certainly not what is intended.

Tabulated version …

A shipment may be made only to one of the following European countries:

• United Kingdom.
• The Netherlands.

Using tabulation along with a clear threshold ("… only to one …") eliminates the mistaken use of "and" and eliminates the potential ambiguity.

2.  Potential ambiguity in what is "and'ed"

Consider the following statement (from a lawyer) …

"Our agreement is that our firm shall receive $3,750.00 in fees and reimbursement for costs advanced."

The statement can be read either as:

1. Lawyer's interpretation:  "...  our firm shall receive $3,750.00 in fees [and reimbursement for costs advanced]."
   
   
2. Client's interpretation:  "...  our firm shall receive $3,750.00 in [fees and reimbursement for costs advanced]."

A lawyer should know better.  The statement should have been written as below.

Tabulated version …

A client must pay all the following:

• $3,750.00 in fees.
• reimbursement for costs advanced.

3.  Potential ambiguity in whether "or's" are exclusive or inclusive

Natural language generally makes no assumption about whether an "or" is meant to be exclusive or inclusive.  The ambiguity can be eliminated, of course, by stating "exclusively" or "inclusively" explicitly in each case.  For business rules, however, tabulation is generally much more effective.

Example with an ambiguous "or" …

A project must be considered active if it has a manager, a budget, or a sponsor.

Does the statement mean exactly one or at least one of the three listed items?  Different readers may make different assumptions.  Let's assume at least one is intended.

Tabulated version …

A project must be considered active if at least one of the following is true:

• It has a manager.
• It has a budget.
• It has a sponsor.

4.  Potential ambiguity in strings of "and's" and "or's"

Natural language also generally makes no assumption about the precedence of "and's" and "or's" — i.e., which logically should be applied first in a statement that includes both.  Consider the statement below from a menu for a restaurant.^[3]

With each entree, you get a vegetable and salad or soup.

Which of the interpretations below is correct?

1. With each entree, you get (a vegetable and (salad or soup)).
   
   
2. With each entree, you get ((a vegetable and salad) or soup).

This ambiguity can be addressed, of course, by punctuation or parentheses (as above).  The result, however, is seldom as straightforward or as reader-friendly as desirable, especially where the number of "and'ed" and "or'ed" conditions increases.  Tabulation eliminates the ambiguity.  Let's assume the first interpretation above is the correct one.

Tabulated version …

With each entree, you get the following:

• a vegetable.
• salad or soup.

Enhancing the Readability of Business Rule Statements by Using Tabulation

1.  Awkward sentence construction

Tabulation can sometimes straighten out very awkward sentence construction, bringing it at least to the point that it can be validated and corrected (if needed).

Example …

A territory must not include any non-candidate traditional gas station if it includes any ultra-service or food outlet; must not include any ultra-service if it includes any non-candidate traditional gas station or food outlet; etc.

Tabulated version …

A territory must not include more than one of the following:

• Non-candidate traditional gas station.
• Ultra-service.
• Food outlet.

2.  Repetition of business rule keywords

In RuleSpeak each statement of a business rule should have one and only one rule keyword.  Experience has proven this to be an important practice in enhancing clarity.

Example …

The status of a closed loan must be 'approved' and the category must not be 'high-risk' if it is for a restaurant.

The rule keyword "must" appears twice in this statement.  Does the "if" condition at the end apply to both "must's" or just to the latter? Let's assume the condition applies to both.

Tabulated version …

All the following must be true for a closed loan if it is for a restaurant:

• The status is 'approved'.
• The category is not 'high-risk'.

The revised statement centers on a single rule keyword in the common subject matter at the top of the statement.  The qualification "for a restaurant" now clearly applies to both bulleted conditions.

3.  Front-Loaded Qualification

Putting multiple qualifications at the front of a business rule statement tends to make it 'dense' and hard to comprehend.  Putting such 'heavy lifting' toward the end of the statement instead produces a statement much easier to read.  Tabulation makes this simplification possible.

Example ...

A machine owned by an employee included in a team assigned to a high-security project must not be serviced by a company located in a country suspected of terrorist activity.

Tabulated version …

A machine must not be serviced by a company if all the following are true:

• The company is located in a country suspected of terrorist activity.
• The machine is owned by an employee included in a team assigned to a high-security project.

As the tabulated version illustrates, keeping the common subject matter as simple as possible provides a mental anchor for the reader in then wading through the qualifications.

Grouping Business Rules to Enhance Manageability

Tabulation can be used in certain cases to unify business rule statements that could actually stand on their own.^[4]  Such unification eliminates the fragmentation of business logic that might otherwise occur.  It also provides single points of coordination for the related business rules, to ensure they can be located, reviewed, and potentially revised in concert.

1.  Many things that must all be true for something

Often there are many things that must be true for some subject matter of interest.  For example, the following six business rules statements all indicate things that must be true for claims.

Individual business rule statements …

A claim must indicate which active policy covers it.

A claim must indicate who the claimant is.

A claim must indicate what health care was provided.

A claim must indicate what health care provider provided the health care.

A claim must indicate what the injury/illness was.

A claim must indicate when the initial date of the injury/illness was.

These six statements could be among hundreds (or thousands) of other business rules.  A better approach is to unify them using a single business rule statement with tabulation.

Tabulated version …

A claim must indicate all the following:

• which active policy covers it.
• who the claimant is.
• what health care was provided.
• what health care provider provided the health care.
• what the injury/illness was.
• when the initial date of the injury/illness was.

This single business rule statement replaces the earlier set of six.  All the bulleted conditions must be true.  The statement provides a single point of coordination for all the things that must be indicated for a claim.

2.  Something that must be true if any of multiple conditions is true

A somewhat more complicated pattern and opportunity for consolidation occurs when something must be true if any of multiple conditions is true.  For example, the following five business rule statements each indicate the same thing for an order must be true — that it be credit-checked — if a particular condition holds true.

Individual business rule statements …

An order must be credit-checked if the order total is more than $500.

An order must be credit-checked if the outstanding balance of the customer's account plus the order amount is more than $600.

An order must be credit-checked if the customer's account is not older than 30 days.

An order must be credit-checked if the customer's account is inactive.

An order must be credit-checked if the customer is out-of-state.

These five statements could be among hundreds (or thousands) of other business rules.  A better approach is to unify them using a single statement with tabulation.

Tabulated version …

An order must be credit-checked if any of the following is true:

• the order total is more than $500.
• the outstanding balance of the customer's account plus the order amount is more than $600.
• the customer's account is not older than 30 days.
• the customer's account is inactive.
• the customer is out-of-state.

This single business rule statement replaces the earlier set of five.  It provides a single point of coordination for all the things that require an order to be credit-checked.

Section 3.  Usage Notes

Tabulation in RuleSpeak is always based on the keyword "the following".  This Section discusses specific RuleSpeak guidelines for its use.

Thresholds

Every business rule statement using "the following" must reference some threshold number.  This threshold number, which can be implicit or explicit, refers to the number of bulleted conditions that must be true.

Example of implicit threshold …

An employee must receive a demerit each time any of the following is true.  The employee:

• is absent from work for an unexcused reason.
• takes a coffee break for longer than 25 minutes.
• smokes a cigarette in a designated non-smoking area.

In this example, "any" serves as an implicit threshold meaning "at least one".  It logically expresses a non-exclusive OR for the bulleted conditions.  "At least one" could be substituted in the business rule statement rendering the threshold explicit with no change in the statement's meaning.

An explicit threshold number associated with a "the following" clause can be any arbitrary number.  All the forms below are valid.

• at least n of the following
  
  
• at most n of the following
  
  
• exactly n of the following

The phrase "exactly one" expresses an exclusive OR.

Example of an explicit threshold expressing an exclusive OR …

A customer must be exactly one of the following:

• an individual person.
• a corporate entity.
• a government body.

Example of a higher explicit threshold …

A customer must be considered a high-value customer if at least 5 of the following are true.  The customer has flown:

• at least 50,000 miles on paid tickets during the last calendar year.
• at least 50 flight segments on paid tickets during the last calendar year.
• at least 40,000 miles and 25 flight segments on paid tickets during the last calendar year.
• at least 25,000 miles and 40 flight segments on paid tickets during the last calendar year.
• at least 150,000 miles or 150 flight segments on paid or unpaid tickets during the last calendar year.
• at least 500,000 miles on paid tickets during the last 7 calendar years.
• at least 500 flight segments on paid tickets during the last 7 calendar years.
• at least 10 highest-fare tickets during the last calendar year.
• on exactly the same route on the same days of the week at least 3 times a month in each of at least 7 months during the last calendar year.
• on tickets totaling more than $15,000 during the last calendar year that were paid at least one month in advance.
• with at least two family members on paid tickets 4 times during the last calendar year.

Use of "True"

As previous examples have illustrated, use of the special keyword "true" is often useful in statements using tabulation.

Example using the keyword "true" …

A claim must be considered potentially fraudulent if any of the following is true.  The claimant has:

• made more than six claims in the last two years.
• owned more than five vehicles in the last year.
• a history of fraudulent claims.

Use of the keyword "true" is optional in statements using "the following".

Example of a statement not using the keyword "true" …

A document submitted as evidence of current liability insurance must be considered acceptable if the document is any of the following:

• a current renewal notice.
• an acknowledgment by the previous insurance company of a request by the candidate to cancel the previous policy.
• a notice by the previous insurance company of cancellation of the previous policy.

Use of "Both" and "Either"

RuleSpeak recommends avoiding the words both and either in lists of only two bulleted conditions.  The reason is that if additional bullets are subsequently added the sense of "both" or "either" will no longer apply.

Example using "both" …

An order may be accepted only if both the following are true:

•  The order has a delivery address.
•  The customer's credit is good.

It is likely that additional conditions will be added in the future to the current bulleted list of conditions.  RuleSpeak therefore recommends replacing "both" with "all," as below.

Revised example eliminating "both" …

An order may be accepted only if all the following are true:

•  The order has a delivery address.
•  It indicates the customer who is placing it.

Example using "either" …

An order may be shipped only if either of the following is true:

•  Payment for the order has been received.
•  The customer's credit is good.

It is quite possible that some additional condition(s) will be added in the future to the bulleted list of conditions — e.g., "A valid credit card number is given".  RuleSpeak therefore recommends replacing "either" with "at least one," as below.

Revised example eliminating "either" …

An order may be shipped only if at least one of the following is true:

•  Payment for the order has been received.
•  The customer's credit is good.

Starting a Business Rule Statement with a Threshold

"The following" along with an appropriate threshold can serve to initiate a business rule statement.

Example using "all" to initiate a statement …

All the following must be true for a customer.  The customer:

• has a name.
• provides a valid e-mail address.
• indicates a preferred ship-to address.

Example using "at most" to initiate a statement …

At most only one of the following may be true for a received rental car:

• It is being washed.
• It is being refueled.
• It is being inspected.

Example using "at least" to initiate a statement …

At least 2 of the following must be true for a credit account:

• An account manager is assigned to the credit account.
• The credit account has a deposit amount.
• A good customer holds the credit account.
• The customer that holds the credit account has placed an order.

Starting a business rule statement with the threshold "none" is generally not recommended in RuleSpeak.

Example using "none" to initiate a statement …

None of the following must be true for an auditor who audits a client:

• The auditor lives in the same city as the client.
• The auditor eats a meal together with the client.
• The auditor spends more than 5 minutes together with the client without a third person present.

The phrase "None … must …" is awkward.  RuleSpeak recommends using "All … must not …" instead.

Revised version using "All … must not …" …

All the following must not be true for an auditor who audits a client:

• The auditor lives in the same city as the client.
• The auditor eats a meal together with the client.
• The auditor spends more than 5 minutes together with the client without a third person present.

Sometimes a business rule statement that involves different verb concepts in each of its bulleted conditions (e.g., lives, eats, spends in the list above) can be simplified by introducing a generic or derived verb such as "to involve" or "to relate".

Revised version using "to involve" …

An auditor must not be involved with a client in any of the following ways:

• live in the same city.
• eat a meal together.
• spend more than 5 minutes together without a third person present.

This revised version still includes "the following" although placed differently.  The "… not … any …" in the revised version is equivalent to the "All … not …" in the previous version.

Ending Text

If a business rule statement includes ending text beyond the scope of the bulleted list, the statement can often be redrafted to bring that text into the common subject matter (lead-off text).

Example of tabulation with ending text …

The purpose of a closed loan must not be any of the following:

• 'no cash-out refinance'.
• 'streamlined refinance'.
• 'special purpose cash-out refinance'.

if the kind of loan is 'construction conversion / renovation mortgage — site built'.

Revised example without ending text …

The purpose of a closed loan must not be any of the following if the kind of loan is 'construction conversion / renovation mortgage — site built':

• 'no cash-out refinance'.
• 'streamlined refinance'.
• 'special purpose cash-out refinance'.

Double Tabulation

More than one "the following" clause can appear in the same business rule statement.  If these clauses are at the same level of indentation, the result is called double tabulation.

Example of double tabulation …

The purpose of a closed loan must not be any of the following:

• 'no cash-out refinance'.
• 'streamlined refinance'.
• 'special purpose cash-out refinance'.

if the kind of loan is one of the following:

• 'construction conversion / renovation mortgage — site built'.
• 'construction conversion / renovation mortgage — special approval'.

Double-tabulation structures can become cumbersome, however — especially if the number of bulleted conditions is relatively long.  A bulleted list may be eliminated by creating a second business rule that derives some new vocabulary entry.  In the example that follows, the new vocabulary entry is special-case loan.

Original business rule using new vocabulary in place of a second bulleted list …

The purpose of a closed loan must not be any of the following if it is a special-case loan:

• 'no cash-out refinance'.
• 'streamlined refinance'.
• 'special purpose cash-out refinance'.

New business rule for deriving the new vocabulary entry …

A loan must be considered a special-case loan if it is one of the following:

• 'construction conversion / renovation mortgage — site built'.
• 'construction conversion / renovation mortgage — special approval'.

Use of a derived vocabulary entry in place of double tabulation is generally preferred. 

An additional benefit of such revision is that the new vocabulary entry (e.g., special-case loan) can be used in expressing other business rules (none shown) that would otherwise need to include the very same bulleted list.  The derivation logic can thus be single-sourced (localized in a single business rule statement) and re-used via reference (using the new vocabulary entry as now in the original business rule statement).  If the same bulleted list is needed frequently, this approach can significantly reduce overall complexity.

Nested Use of "The Following"

Sometimes a bulleted condition for a "the following" clause contains an "and" or an "or" itself.  If useful, an additional ("nested") level of tabulation (also using "the following") can be applied to eliminate it. 

The result is multi-level tabulation.  Any additional level of tabulation should always be set-off visually by additional indentation.

Example with an "or" in a bulleted condition …

A credit check must be performed for a customer if all the following are true:

• A credit check has not been performed for that customer in the last 6 months.
• The customer places an order for which the order total is more than $500, or the outstanding balance of the customer's account plus the order amount is more than $600, or the account designated for the order is not older than 30 days.
• A waiver has not been authorized.

The second bulleted item in the list above includes two "or's".  The clause is long and complex.  A better approach is to eliminate the "or's" with a nested "the following" clause.

Revised version using multi-level tabulation …

A credit check must be performed for a customer if all of the following are true:

•  A credit check has not been performed for that customer in the last 6 months.
•  The customer places an order for which any of the following is true:
  • The order total is more than $500.
  • The outstanding balance of the customer's account plus the order amount is more than $600.
  • The account designated for the order is not older than 30 days.
•  A waiver has not been authorized.

In the revised version, a second-level of tabulation (and indentation) has been introduced using a second-level "the following" clause to eliminate the embedded "or's".  The threshold "any" has been specified.  The overall result is a much more approachable statement.

Nested "the following" clauses can be used as many times in a business rule statement as is useful and productive.

Example of multiple nested tabulations …

The P&C risk group created for an insured must include all the following:

• Each person for whom any of the following is true.  The person is:
  • another member of the household of the insured.
  • an operator of a vehicle owned by any member of the household of the insured.
  • a co-owner of an item of personal property owned by the insured.
• Each policy for which a member of the household of the insured is one of the following:
  • a named insured.
  • an operator of a vehicle covered by the policy.
• Each vehicle located at the primary residence where the insured resides.
• Each item of personal property located at the primary residence where the insured resides.

References

[1]  For explanation, refer to Decision Tables: A Primer — How to Use TableSpeak™, by Ronald G. Ross, 2013.  Available (free, April 2013) on www.BRSolutions.com

[2]  From Drafting Contracts:  How and Why Lawyers Do What They Do, by Tina L. Stark, Aspen Publishers — Wolters Kluwers, 2007, p. 211.

[3]  Berry, Daniel M., Erik Kamsties, Michael M. Krieger, and Willenken Loh Stris Lee & Tran.  [November 2003].  From Contract Drafting to Software Specification:  Linguistic Sources of Ambiguity:  A Handbook, (Version 1.0).  ["Ambiguity Handbook"], p. 44.  Available [1/5/2013] at:  http://se.uwaterloo.ca/~dberry/

[4]  In the OMG standard Semantics of Business Vocabulary and Business Rules (SBVR), the underlying principle is called Severability.  Severability is the business counterpart to what in propositional logic is often called the universal 'and'.  In general, this assumption permits individual statements of manageable size to be expressed — a very good thing.  In the strictly-limited cases described here, however, it works against overall manageability.

# # #