Domain Concept Modeling Using Clafer - Tutorial v9.4

A Tutorial By Michał Antkiewicz
Version 9.4, Sep 19, 2014
http://gsd.uwaterloo.ca/mantkiew

Please email comments/questions/critique/corrections/suggestions to the author at mantkiew@gsd.uwaterloo.ca. Constructive feedback is much appreciated!

Why concept modeling?

During software development, you need to model your domain concepts to precisely communicate them to people with different backgrounds and/or perspectives. The complexities of the business domain are the leading cause of imprecise software requirements, which are the major cause for software bugs. Fixing bugs later can be up to 200 times more expensive then fixing them during domain and requirements elicitation. Different perspectives mean that different people may be interested in different properties/features of the same concept. All stakeholders need their perspectives included in concept definitions. Some stakeholders, such as developers and testers, need to understand all perspectives to properly implement the concepts and test their implementations.

Some methods, such as Domain-Driven Design, explicitly recommend growing the so called Ubiquitous Language which contains definitions of all important domain concepts, such as business entities, rules, processes, scenarios, objectives, etc. In this tutorial, we show how domain concepts can be easily, naturally, concisely, and precisely modeled using Clafer – a modeling language under development in Generative Software Development Lab @ University of Waterloo, Canada and MODELS group at IT University of Copenhagen.

Standard metaphors used in writing

In many organizations, people use word processing software for communication. Among most popular are Microsoft Word (documents) and PowerPoint (slides). When creating both documents and slides, people use some standard ways of structuring content, such as, using section headers, subsections, lists, tables, indentation, hyperlinks, etc.

Concept modeling using Clafer leverages these natural metaphors used in structuring text documents:

  • Header to represent a concept/topic,
  • Sections and subsections to represent hierarchy and document outline,
  • Bullet lists to represent points about the concept,¬
  • Indentation (sub-bullets) to represent sub-points related to the concept or other points,
  • Hyperlinks or citations to represent references to other concepts or points.

Additionally, people often use forms and examples:

  • Forms to represent general structure and attributes of all concepts of the given kind,
  • Examples to represent particular details about a concrete concept instance.

For example, a form to collect data about a person would include fields such as name, surname, date of birth, gender, marital status, and address. A form filled with data about some person would represent that concrete person (example). So, the forms are abstract (they apply to any person but none in particular) and examples are concrete (they represent concrete person or a set of persons).

One definition of abstract is: “disassociated from any specific instance

One definition of concrete is: “naming a real thing or class of things

A form for the concept person often looks as follows:

An example (instance) of a person could look as follows:

There are, however, a few problems with using just forms. In this example, everybody knows what type of information they should enter because it is common knowledge. Name and Surname should be text, Date of birth should be a date, Gender should be Male or Female or both (although, the government, for example, may choose to require either Male or Female, never both), and Marital status should be exactly one of Never Married, Married, and Divorced. When it comes to the section of the form about address, two things are not clear: 1) whether data should be provided in the line of Address, and 2) what to enter if there is no Unit #. Additionally, entering Unit # does not make any sense if the Street information is not given.

If our example concept was from some specialized domain, non-experts would not be able to provide correct data and understand examples. The lack of precise concept definition would make communication among different stakeholders very difficult.

Concept modeling allows for precisely specifying the kinds of data and the rules for entering valid data about examples.

A not so standard metaphor: Inheritance

All children inherit genes from their biological parents. In conceptual modeling, concepts can also be defined to inherit points from other concepts.

For example, a concept Student could be defined to inherit all properties of a Person concept because the Student is a Person. The “is a” relationship indicates the inheritance.

Additionally, the substitution principle states that because Student is a Person, the Student can participate in all situations a Person can participate.

For example, if a line to the store consists of Persons, then it can also consist of Students because Students are also Persons.

Clafer by Example

In this tutorial, we use Clafer (CLAss FEature Relationship) – a lightweight structural modeling language developed at Generative Software Development Lab at University of Waterloo and MODELS group at IT University of Copenhagen. . All examples are expressed in Clafer version 0.3.6.1, which is the most recent release. See Clafer Tools 0.3.6.1 Released.

A model of a person from previous section expressed using Clafer could look as follows:

abstract Person
Name -> string
Surname -> string
DateOfBirth -> string
or Gender
Male
Female
xor MaritalStatus
NeverMarried
Married
Divorced
Address
Street -> string
UnitNo -> string ?
City -> string
Country -> string
PostalCode -> string

form of a Person
Name is a point about the Person and it should be text

DateOfBirth is a date
at least one of Male and Female must be chosen (or)
Male is a point about Gender and it is indirectly a point about Person

exactly one of NeverMarried, Married, and Divorced must be chosen (xor)


points about a Person related to address are grouped below
Address itself holds no value
UnitNo is an optional point but can only be given when Street is given




Note: Names of clafers do not have to start with a capital letter; however, they have to be continuous strings of non-white-space characters beginning with a letter (no spaces are allowed).

An example of a person could be specified as follows:

JohnDoe : Person
[ Name = "John" ]
[ Surname = "Doe" ]
[ DateOfBirth = "01-02-1985" ]
[ Male ]
[ Married ]
[ Street = "123 Main St." ]
[ City = "Great Town" ]
[ Country = "Canada" ]
[ PostalCode = "A1B 2C3" ]

JohnDoe is an example of a Person (precisely an instance specification)
the value of Name is John

the value of date is a string formatted appropriately
he is a Male
he is Married
his address does not have a UnitNo
also has Address but do not need to assert explicitly;
Address is assumed present because its children are present,
e.g., Street

Note: Currently, Clafer does not have a notation for expressing instance data directly. Instead, we write instance specifications, which can be underspecified (details can be left out) and which must be evaluated (and perhaps completed) to produce concrete instance data. The experimental Clafer 0.4.0 supports redefinition, which allows for writing concrete clafers without constraints but by redefining cardinality and supertypes of clafers.

Note: The square brackets [ and ] are used to assert certain facts and impose certain restrictions ( [ ] indicate constraints). They can be used in both forms (abstractions) and in examples (instance specifications). Here, we use them to fix certain facts about the example, i.e., that JohnDoe is a Male and that his Name is "John". These facts can never change (they are hard constraints). For example, additionally asserting that JohnDoe is a Female, will cause a violation of the xor group constraint of MaritalStatus.

JohnDoe satisfies all requirements of being a person set by the concept definition Person. Possible violations of the definition would include: 1) not having a name (name is mandatory), 2) not being a Male nor a Female (Gender is an or group), 3) being both NeverMarried and Married at the same time (MaritalStatus is an xor group), and 4) having a UnitNo without having a Street (cannot have a property without the parent property).

Note: There is no need to specify that JohnDoe has Gender and MaritalStatus. Simply specifying that he is a Male implies that he also has Gender. In case of name ambiguity, Male could be qualified as [ Gender.Male ].

Note: The difference between the abstraction, instance specification, and instance data is very important to understand. Abstractions specify the structure and constraints of instances but they do not specify any instances directly. Instance specifications, on the other hand, specify one or more instances. Fully constrained instance specifications result in exactly one instance (actually, you can produce an infinite number of instances that will be isomorphic), underconstrained ones can result in multiple different instances. We refer to the actual instances as instance data.

Note: Clafer Instance Generator (ClaferIG) is a tool that generates instance data for instance specifications. We currently have three instance generators: Alloy-based (ClaferIG), Choco3-based (ClaferChocoIG), and Z3-based (ClaferSMT). The latter two are also multi-objective optimizers, that is they can produce instances that are Pareto-optimal given a set of objectives. Every Pareto-optimal instance represents a certain tradeoff among the objectives. Visit Variability Management, Multi-Objective Optimization and Decision-Making in Software Product Line Engineering for more information.

We could define a concept of Student by inheriting from Person and by adding additional points related only to students. We could define the concept of a waiting line as follows.

abstract Student : Person
StudentId -> string
abstract WaitingLine
participants -> Person *
form of a Student that “is a” Person.
StudentId is a property specific to a Student

The WaitingLine consists of many (as indicated by *) participants who can also be students.


We could now create an example waiting line which contains John Doe and Mary Jane and possibly some more people as follows:

MaryJane : Student
[ Name = "Mary Jane" ]
[ StudentId = "MJ13421354" ]
Need to fill in the form for the Person here
JohnDoe and MaryJane are participants in the BusLine.

We can restrict that John Doe and Marry Jane are the only participants in the bus line as follows:

JohnAndMaryLine : WaitingLine
The line consists of exactly JohnDoe and MaryJane.

The number of participants can also be set to a specific number or given lower or upper bounds. The operator # applied to a clafer indicates the number of examples of that clafer.

abstract TwoPersonLine : WaitingLine
[ # participants = 2 ]
A specialized concept with a restriction: the line consists of exactly 2 participants.

Note: Any clafer can have constraints. The concept TwoPersonLine represents a subset of WaitingLines that consist of only two participants. The participants, however, are not yet specified: TwoPersonLine is abstract and it does not yet represent any concrete instances. Similarly, we could have added some constraints directly to the definition of the concept Person as well.

Note: Using redefinition, one would instead redefine the clafer participants in TwoPersonLine by restricting its cardinality to 2 as follows: participants -> Person 2. Redefinition has an advantage over constraining that it declares a new clafer under which new clafers and constraints can be added (nested).

abstract OneToTenPersonLine : WaitingLine
[ # participants >= 1 ]
[ # participants <= 10 ]
The line consists of at least one and at most 10 participants.

Note: The lower and upper bounds on the number of instances are usually given using clafer cardinality but this can only be done when the clafer is first declared, e.g., participants -> Person 1..10. The bounds can only be further restricted using a constraint as shown in the example above or using redefinition.

The model could be improved by restricting the choice of country to a specific list of countries, for example Canada and USA only. In Clafer, we would specify a new concept NorthAmericanCountry and list possible countries as follows. Additionally, we would specify that the value of the property Country of a Person can be one of the NorthAmericanCountries.

enum NorthAmericanCountry = Canada | USA | Mexico
abstract Person2
Country can only point at (link to) one of the north American countries

We could then specify that JohnDoe2 comes from Canada as follows:

JohnDoe2 : Person2
Country points to Canada (note that quotes are removed because we link to the clafer Canada instead of specifying the country’s name!)

Finally, the following is the summary produced by the wiki for all our example models on this page:

c0_Person abstract Person c0_JohnDoe JohnDoe : Person c0_JohnDoe->c0_Person c0_Student abstract Student : Person c0_Student->c0_Person c0_WaitingLine abstract WaitingLine c0_WaitingLine->c0_Person participants c0_MaryJane MaryJane : Student c0_MaryJane->c0_Student c0_BusLine BusLine : WaitingLine c0_BusLine->c0_WaitingLine c0_JohnAndMaryLine JohnAndMaryLine : WaitingLine c0_JohnAndMaryLine->c0_WaitingLine c0_TwoPersonLine abstract TwoPersonLine : WaitingLine c0_TwoPersonLine->c0_WaitingLine c0_OneToTenPersonLine abstract OneToTenPersonLine : WaitingLine c0_OneToTenPersonLine->c0_WaitingLine c0_Person2 abstract Person2 c0_NorthAmericanCountry c0_NorthAmericanCountry c0_Person2->c0_NorthAmericanCountry Country c0_JohnDoe2 JohnDoe2 : Person2 c0_JohnDoe2->c0_Person2
Module Statistics: | All clafers: 34 | Abstract: 7 | Concrete: 27 | Reference: 11 | Constraints: 18 | Goals: 0 | Global scope: 1..* | Can skip name resolver: no |

Module Downloads: | [.cfr] | [.html] |

The graph presents an inheritance hierarchy of our model.

Double clicking on the graph shows/hides references among clafers.

The source code can be downloaded using the link [.cfr] below the module statistics. Run the model using Clafer Instance Generator to see what the instance data looks like.

You can work with the model from this page in ClaferIDE:


You can view, filter, and explore multiple instances of a model at the same time using ClaferConfigurator:


In the next chapter of the tutorial, we are going to introduce nextClafer a bit more precisely.