The Natural Rule Language - Advanced User Guide

This document is an advanced user guide that shows how to use the more complex features of the Natural Rule Language (NRL). The Natural Rule Language is an open specification hosted on SourceForge, at http://nrl.sourceforge.net. Its principal purpose is to enable the expression of constraints over models in a restricted language that is reasonably close to English.

The web site contains some related documents, most importantly the language specification. It also contains a collection of example rule sets that can provide further insight into the language.

STOP: Please read the basic user guide first if you are unfamiliar with the NRL.

Christian Nentwich
Rob James

This version was published on the 7th of April 2010.

The Model and Some Rules
Using Variables
Validation Fragments
External Operators
What's Next?

The Model And Some Rules

You will know from the basic user guide or your experience with the NRL that NRL rules are written against a model, such as UML or XML Schema. In this advanced guide we will use the same example model as in the basic guide. If you require an explanation of the meaning, please refer to the model section in the basic user guide.

UML Model

Let's now add some more advanced rules to constrain this model. The following rules are complete and correct and could be used in a project. They make use of various features that will be discussed below:

Model "userguide.uml2"

Context: Settlement
Validation Rule "v1"
code represents settlementCurrency.ccyCode, if code = 'GBP' or code = 'EUR' then tax = 0.175 otherwise tax = 0

Context: Settlement
Validation Rule "v2"
code represents settlementCurrency.ccyCode, type represents transaction.type, if the type is equal to 'PURCHASE' then the code is equal to 'GBP'

Context: Settlement ("settlement")
Validation Fragment "taxable"
settlement.settlementCurrency.ccyCode is one of 'GBP', 'EUR'

Context: Settlement
Validation Rule "p1"
If the Settlement is taxable then netAmount = grossAmount * (1 + tax) else netAmount = grossAmount

Context: Settlement
Validation Rule "o1"
transaction.date [is not a holiday]

Using Variables

When computing values or performing complex navigations along a model, it is sometimes useful to hold part of a rule in a variable, to prevent any repetition. It can also be useful to declare a variable that has a more meaningful name than a model attribute in a given context:

Context: Settlement
Validation Rule "v1"
code represents settlementCurrency.ccyCode, if code = 'GBP' or code = 'EUR' then tax = 0.175 otherwise tax = 0

Here, in order to avoid having to type settlementCurrency.ccyCode twice, we have assigned it to a variable 'code'. We can then make use of that variable in a rule as normal. Note the following conventions:

The rule in which the variable holds is given after the variable, and all variables must be at the start of the rule
Values or even arithmetic expressions can be represented by a variable

If it is necessary for rule simplification, several variables can be declared at once, separated by a comma or just a newline:

Context: Settlement
Validation Rule "v2"
code represents settlementCurrency.ccyCode, type represents transaction.type, if the type is equal to 'PURCHASE' then the code is equal to 'GBP'

Validation Fragments

It sometimes happens that we want to check that a condition holds for a particular context in multiple rules. In our example model, a transaction is taxable if it occurs with a currency of "GBP" or "EUR" and we may have several rules that hold only for taxable transactions. It would be tedious to have to write out the currency check over and over again - instead we define a validation fragment called "taxable", which we can then make use of in multiple rules:

Context: Settlement ("settlement")
Validation Fragment "taxable"
settlement.settlementCurrency.ccyCode is one of 'GBP', 'EUR'

Note the following here:

A fragment works like a rule but is introduced using the Validation Fragment keyword
The fragment name is in quotes - this allows you to use spaces in the fragmnent name if desired, to make them more readable
A fragment must have a boolean result, i.e. be a true/false assertion

Validation fragments are referred to in rules simply by referring to the fragment name - the parser will identify the fragment automatically:

Context: Settlement
Validation Rule "p1"
If the Settlement is taxable then netAmount = grossAmount * (1 + tax) else netAmount = grossAmount

A fragment has to be applied to some attribute or to the context. In this rule, it is being applied to the context, Settlement. The "is" keyword is optional - if it was part of the fragment name, we would omit it. Here is a summary of how to refer to fragment:

NRL Text Comments

attribute is "property" The attribute must be an attribute of the context, or refer to the context itself

attribute has "property" Alternative to "is"

attribute "property" If the property name contains "has" or "is" or a similar verb

NRL Text	Comments
attribute is "property"	The attribute must be an attribute of the context, or refer to the context itself
attribute has "property"	Alternative to "is"
attribute "property"	If the property name contains "has" or "is" or a similar verb

External Operators

The Natural Rule Language, as a restricted language, will always be too limited to express some types of rules. Frequently seen examples that come to mind include:

Checking that items with certain values exist in data stores, on the internet or other locations (e.g. currency lists)
Performing complex computations to verify attribute values (e.g. determine if a number is prime)
Complex date manipulation (e.g. check if a date falls on a weekend)

Such computations are not covered in the NRL, however they can be referenced using external operators. This is really quite simple: an external operator is referenced in square brackets. If it requires any attribute as a parameter, it is written before or after it, or if it requires two, by surrounding it. Here is an example:

Context: Settlement
Validation Rule "o1"
transaction.date [is not a holiday]

In this rule we have referenced an operator "is not a holiday", in square brackets, and the date given before it is passed as a parameter. The operator will check the date for us.

At this stage, one wonders how the operators actually get implemented. We make a distinction here between rule writers, the people charged with writing rules - who could be business analysts or technical analysts - and implementors charged with an eventual implementation. This distinction is necessary and useful, because some rules are provided only for documentation and never actually get implemented.

The NRL specification does not state how operators like "is not a holiday" actually map to a target implementation. If NRL rules are translated to Java, they may be implemented as helper methods in some class, in a rule engine they may be scripted. The mapping implementation will hold further details in these cases.

The following is a summary of the permissible operator syntax:

NRL Text Comments

attribute [applied operator] For example, "date [is not a holiday]"

[applied operator] attribute For example, "[there is a] currency"

attribute [operator] attribute For example, "dateA [is in the same year as] dateB"

NRL Text	Comments
attribute [applied operator]	For example, "date [is not a holiday]"
[applied operator] attribute	For example, "[there is a] currency"
attribute [operator] attribute	For example, "dateA [is in the same year as] dateB"

What's Next?