About this series of articles

While my first series of articles on writing natural language rule statements^[1] explored a wide variety of issues in a rather organic and hence random manner, this series takes a more holistic and systematic approach and draws on insights gained while writing my recently-published book on the same topic.^[2]  Rule statements recommended in these articles are intended to comply with the Object Management Group's Semantics of Business Vocabulary and Business Rules (SBVR) version 1.0.^[3]

Data Items in a Transaction

In the previous article^[4] RS15 (reproduced below) stated a rule governing applications for travel insurance.  Specifically, it stated that a particular data item was mandatory, i.e., must be specified in each application for travel insurance.

RS15.

Each Travel Insurance Application must specify exactly one Birth Date for each Passenger.[5]

As with many transactions some (but not all) data items are mandatory.  What data items might there be in a typical travel insurance application?  For each passenger, we might expect to find the following:

1. a salutation or title (e.g., Mr, Ms, Dr), a family name, and one or more given names,
   
   
2. a birth date (or — possibly — age, as at the date of return),
   
   
3. an indication as to whether that passenger has any pre-existing medical condition, plus (if so) each such condition.

Each of these, of course, can be different for each passenger.  However, there are also data items that must be the same for all passengers, such as:

1. the dates of departure and return (or perhaps the departure date and duration),
   
   
2. whether the travel is international or domestic and, if international, the region(s) to be visited (e.g., Africa, Asia, Europe, North America, Oceania, South America) — some companies require a list of countries to be visited.

This is because, typically, separate policies would be required if the travellers have different itineraries.

Contact information is also required, such as:

1. postal address:  street number and name, locality name, state, postal code,^[6]
   
   
2. contact phone number,
   
   
3. e-mail address.

Only a single set of contact information is required, irrespective of the number of passengers.

Payment for insurance purchased online is typically by credit card, for which the following details are required:

1. the name of the cardholder,
   
   
2. the credit card issuer (e.g., Visa, Mastercard),
   
   
3. the credit card number,
   
   
4. the expiry date (month and year).

Again, only a single set of payment information is required, irrespective of the number of passengers.

Finally, some insurance companies allow for high-value items — such as jewellery or high-tech items — to be covered for an additional premium.  For each such item, a description and value would be required, plus (possibly) a make, model number, and serial number.

Non-repeatable data items

Let's look first at those data items that can only appear once in a travel insurance application, such as:

1. the dates of departure and return,
   
   
2. an indication as to whether the travel is international or domestic,
   
   
3. the set of contact details,
   
   
4. the set of credit card details.

While the first two data items are dates, which can have any of a number of values, the third data item can have only two values — 'international' and 'domestic' — and can therefore be considered as Boolean:  "Is the application for international travel ('yes' or 'no')?"

In most insurance companies' applications both departure and return dates are mandatory.  Rule statements RS16 to RS19 inclusive are required for the non-Boolean mandatory data items:

RS16.	Each Travel Insurance Application must specify exactly one Departure Date.
RS17.	Each Travel Insurance Application must specify exactly one Return Date.
RS18.	Each Travel Insurance Application must specify exactly one Set of Contact Details.
RS19.	Each Travel Insurance Application must specify exactly one Credit Card.

Note that these rule statements differ from RS15  in only two respects:

1. the name of the governed data item:  Departure Date, Return Date, Set of Contact Details, or Credit Card rather than Birth Date,
   
   
2. the absence of the phrase for each Passenger (since these data items are the same for all passengers).

This suggests a common formulation for mandatory data item rule statements:

1. the subject, identifying the type of transaction, in this case Each Travel Insurance Application,
   
   
2. must specify,
   
   
3. a determiner^[7] specifying, for the data item in question, the constraint on the number of instances required, in this case exactly one,
   
   
4. the name of the governed data item:  for example, Birth Date, Departure Date, Return Date, Set of Contact Details, Credit Card,
   
   
5. an optional phrase of the form for each <object name>, where <object name> can be, for example, Passenger.

Boolean data items (and those that can be considered as Boolean) that are mandatory require a slightly different form of rule statement, such as RS20:

RS20.

Each Travel Insurance Application must specify whether it is for international travel.

Alternatively, you may wish to make explicit what is meant by a travel insurance application that is not for international travel, as in RS21:

RS21.

Each Travel Insurance Application must specify whether it is for international travel or for domestic travel.

Since these rules require the selection of an option, I refer to them as mandatory option selection rules.

If you are not familiar with the SBVR, you may be curious about the styling of the Boolean characteristics is for international travel and is for domestic travel.  It is an SBVR convention to style the entire verb phrase representing a Boolean characteristic as a verb phrase, i.e., italic blue.

A Boolean characteristic is typically represented in on-screen forms by either a "checkbox" (such as "Doctor's Certificate" in Figure 1) or a pair of "radio buttons" (such as "Leave with pay" and "Leave without pay" in Figure 1).

Figure 1:  An on-screen form for employee leave applications.

Of course, there is no reason why a set of radio buttons should be limited to just two.  However, a set of more than two radio buttons cannot be used for a single Boolean characteristic.  For example, a flight booking request form could allow for one-way journeys, return journeys, or multi-stop journeys (in which there may be more than one intermediate stop and/or the final destination is not the initial departure point), and it would be obligatory to specify which of these three options is required.  Each of these options can be considered as a separate Boolean characteristic, i.e., none of them is a complementary characteristic of one of the others.  Rule statement RS22  expresses the obligation to specify one of the three options:

RS22.

Each Flight Booking Request must specify whether it is for a one-way journey, for a return journey or for a multi-stop journey.

Mandatory option selection rule statements also have a common formulation:

1. the subject, identifying the type of transaction, such as Each Travel Insurance Application or Each Flight Booking Request,
   
   
2. must specify whether it,
   
   
3. a list of one or more predicates, each specifying a Boolean characteristic that a transaction of the type in question may or may not exhibit (such as is for international travel or is for a one-way journey), in which:
   
   
1. each predicate in the list, other than the first, may omit the initial is,
   
   
2. each predicate in the list, other than the last two, is followed by a comma,
   
   
3. the last two are separated by or (or , or if preferred when there are more than two).

An alternative styling is available for some mandatory option selection rules; rule statement RS22 can alternatively be styled as:

RS23.

Each Flight Booking Request must specify whether it is for a One-Way Journey, for a Return Journey or for a Multi-Stop Journey.

This is only available if the nouns following for are countable nouns (or count nouns).  These are nouns that can be meaningfully used after the word 'each'.  For example, it makes sense to say "each one-way journey …" whereas it does not make sense to say "*each international travel …."^[8]  'One-way journey' is therefore a countable noun, whereas 'international travel' is a non-countable noun (or mass noun).  Only countable nouns can be rendered as terms, i.e., underlined.

Repeatable Data Items

Some data items may appear more than once.  Rule statements governing these can also use the common formulation for mandatory data item rule statements:

RS24.	Each Travel Insurance Application must specify at least one Passenger.
RS25.	Each Travel Insurance Application that is for international travel must specify at least one Region.

No such rule is required for high-value items, of which there can be one, more than one, or none at all.

Note that:

1. the subject may include a qualifying clause,^[9] such as that is for international travel,
   
   
2. the determiner in these rule statements is at least one rather than exactly one.

Complex Data Items

Each of the following data items is actually a complex data item, in that it consists of two or more component data items:

1. Passenger, in which Birth Date, Salutation, Family Name, and Given Name are mandatory, as provided for by rule statements RS15, RS26, RS27, and RS28 respectively;
   
   
2. Postal Address, in which Street Number and Name, Locality Name, State Code, and Postal Code are mandatory, as provided for by rule statements RS29, RS30, RS31, and RS32 respectively;
   
   
3. Set of Contact Details, in which Contact Phone Number is mandatory, as provided for by rule statement RS33;
   
   
4. Credit Card, in which Cardholder Name, Credit Card Issuer, Credit Card Number, and Expiry Date are mandatory, as provided for by rule statements RS34, RS35, RS36, and RS37 respectively;
   
   
5. High Value Item, in which Description and Value are mandatory, as provided for by rule statements RS38 and RS39 respectively.

RS26.	Each Travel Insurance Application must specify exactly one Salutation for each Passenger.
RS27.	Each Travel Insurance Application must specify exactly one Family Name for each Passenger.
RS28.	Each Travel Insurance Application must specify exactly one Given Name for each Passenger.
RS29.	Each Travel Insurance Application must specify exactly one Street Number and Name in the Postal Address (if any).
RS30.	Each Travel Insurance Application must specify exactly one Locality Name in the Postal Address (if any).
RS31.	Each Travel Insurance Application must specify exactly one State Code in the Postal Address (if any).
RS32.	Each Travel Insurance Application must specify exactly one Postal Code in the Postal Address (if any).
RS33.	Each Travel Insurance Application must specify exactly one Contact Phone Number in the Set of Contact Details.
RS34.	Each Travel Insurance Application must specify exactly one Cardholder Name for the Credit Card.
RS35.	Each Travel Insurance Application must specify exactly one Credit Card Issuer for the Credit Card.
RS36.	Each Travel Insurance Application must specify exactly one Credit Card Number for the Credit Card.
RS37.	Each Travel Insurance Application must specify exactly one Expiry Date for the Credit Card.
RS38.	Each Travel Insurance Application must specify exactly one Description for each High Value Item (if any).
RS39.	Each Travel Insurance Application must specify exactly one Value for each High Value Item (if any).

This requires an enhancement to the common formulation for mandatory data item rule statements:

1. the subject, identifying the type of transaction, in this case Each Travel Insurance Application;
   
   
2. must specify;
   
   
3. a determiner specifying, for the data item in question, the constraint on the number of instances required, such as exactly one or at least one;
   
   
4. the name of the governed data item, e.g., Description, Value;
   
   
5. if the governed data item is part of a complex data item, a phrase having the following form:
   
   
1. for the (if there can only be one of the complex data item) or for each (if there can more than one of the complex data item),
   
   
2. the name of the complex data item, e.g., Credit Card, High Value Item,
   
   
3. (if any) if the complex data item is optional;
   
   
6. (as we shall see shortly in RS42) an optional qualifying clause.

Mandatory option selection rules may also apply within complex data items, as in RS40.  Note that, in these rule statements, the phrase identifying the complex data item (for each Passenger) appears immediately after must specify rather than at the end of the rule statement as in RS41.

RS40.	Each Travel Insurance Application must specify for each Passenger whether that Passenger has any pre-existing medical condition.
RS41.	†Each Travel Insurance Application must specify whether that Passenger has any pre-existing medical condition for each Passenger.[10]

This requires an enhancement to the common formulation for mandatory option selection rules:

1. the subject, identifying the type of transaction, in this case Each Travel Insurance Application;
   
   
2. must specify;
   
   
3. if the governed data item is part of a complex data item, a phrase having the following form:
   
   
1. for the (if there can only be one of the complex data item) or for each (if there can more than one of the complex data item),
   
   
2. the name of the complex data item, e.g., Passenger,
   
   
3. (if any) if the complex data item is optional,
   
   
4. whether that,
   
   
5. the name of the complex data item again;
   
   
4. if the governed data item is not part of a complex data item, whether it;
   
   
5. a list of one or more predicates, each specifying a Boolean characteristic that a transaction of the type in question may or may not exhibit (such as is for international travel or is for a one-way journey), in which:
   
   
1. each predicate in the list, other than the first, may omit the initial is,
   
   
2. each predicate in the list, other than the last two, is followed by a comma,
   
   
3. the last two are separated by or (or , or if preferred when there are more than two).

One further rule statement is required.  This is a mandatory data item rule statement with a qualifying clause (who has any pre-existing medical condition) qualifying the term signifying the complex data item (Passenger):

RS42.

Each Travel Insurance Application must specify at least one Medical Condition for each Passenger (if any) who has any pre-existing medical condition.

To be continued...
The next article in this series will discuss other data cardinality rules.^[11]

References

[1]  The first of which is:  Graham Witt, "A Practical Method of Developing Natural Language Rule Statements (Part 1)," Business Rules Journal, Vol. 10, No. 2 (Feb. 2009), URL:  http://www.BRCommunity.com/a2009/b461.html  

[2]  Graham Witt, Writing Effective Business Rules.  Morgan Kaufmann (2012).  

[3]  Semantics of Business Vocabulary and Business Rules (SBVR), v1.0.  Object Management Group (Jan. 2008).  Available at http://www.omg.org/spec/SBVR/1.0/PDF.  

[4]  Graham Witt, "Writing Natural Language Rule Statements — a Systematic Approach:  Part 1 — Basic Principles," Business Rules Journal, Vol. 13, No. 7 (July 2012), URL:  http://www.BRCommunity.com/a2012/b660.html  

[5]  The font and colour conventions used in these rule statements reflect those in the SBVR, namely underlined teal for terms, italic blue for verb phrases, orange for keywords, and double-underlined green for names and other literals.  Note that, for clarity, these conventions are not used for rule statements that exhibit one or more non-recommended characteristics.  

[6]  Typically insurers only operate within one country, thus a country name or code is not required.  For this example, I am assuming an insurer operating within Australia or the US, in which the State must be included in each address.  

[7]  A word or phrase used before a noun to provide some information as to which instance(s) or how many instances of the noun's concept are being referred to, such as the, each, all, any, the first, exactly one.  

[8]  Syntactically incorrect constructions are conventionally indicated by way of an initial asterisk.  

[9]  A clause used after a term in two ways:
    a) following the subject term of a rule statement, to restrict the scope of that rule statement to a subset of the set of objects signified by that term, rather than the set of all objects signified by that term (e.g., for a return journey in Each flight booking request for a return journey must specify exactly one return date.)
    b) following any other term in a rule statement, to make a constraint more specific than if the qualifying clause were absent (e.g., that is current in Each passenger must present a passport that is current.).  

[10]  Each rule statement example that does not comply with the constrained natural language described in this series of articles is marked with an initial dagger.  

[11]  A rule that requires the presence or absence of a data item and/or places a restriction on the maximum or minimum number of occurrences of a data item.  

# # #