--- title: Domain Concept Modeling Using Clafer - Tutorial v9.4 ... A Tutorial By Michał Antkiewicz
Version 9.4, Sep 19, 2014
[http://gsd.uwaterloo.ca/mantkiew](http://gsd.uwaterloo.ca/mantkiew) Please email comments/questions/critique/corrections/suggestions to the author at [mantkiew@gsd.uwaterloo.ca](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](http://domaindrivendesign.org/), 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](http://clafer.org) – a modeling language under development in [Generative Software Development Lab](http://gsd.uwaterloo.ca) @ University of Waterloo, Canada and [MODELS group](http://www.itu.dk/research/models/wiki/index.php/Process_and_System_Models_Group) at [IT University of Copenhagen](http://www.itu.dk/). 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: ![](/Tutorial/form.png) An example (instance) of a person could look as follows: ![](/Tutorial/instance.png) 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](http://clafer.org) (CLAss FEature Relationship) – a lightweight structural modeling language developed at [Generative Software Development Lab](http://gsd.uwaterloo.ca) at [University of Waterloo](http://uwaterloo.ca) and [MODELS group](http://www.itu.dk/research/models/wiki/index.php/Process_and_System_Models_Group) at [IT University of Copenhagen](http://www.itu.dk/). . 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](http://www.clafer.org/2014/07/clafer-compiler-and-ig-036-released.html). A model of a person from previous section expressed using Clafer could look as follows:
```clafer 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:
```clafer 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](http://gsd.uwaterloo.ca/clafer-tools-binary-distributions) 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](http://t3-necsis.cs.uwaterloo.ca:8099/) 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.
```clafer abstract Student : Person StudentId -> string ``` ```clafer 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:
```clafer MaryJane : Student [ Name = "Mary Jane" ] [ StudentId = "MJ13421354" ] ``` Need to fill in the form for the `Person` here
```clafer BusLine : WaitingLine [ JohnDoe in participants ] [ MaryJane in participants ] ``` `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:
```clafer JohnAndMaryLine : WaitingLine [ participants = JohnDoe, MaryJane ] ``` 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`.
```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).
```clafer 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`.
```clafer enum NorthAmericanCountry = Canada | USA | Mexico abstract Person2 Country -> NorthAmericanCountry ``` Country can only point at (link to) one of the north American countries
We could then specify that `JohnDoe2` comes from Canada as follows: ```clafer JohnDoe2 : Person2 [ Country = Canada ] ``` 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: ```{.clafer .summary} ``` 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: ```{.clafer .ide} ``` You can view, filter, and explore multiple instances of a model at the same time using ClaferConfigurator: ```{.clafer .config} ``` In the next chapter of the tutorial, we are going to introduce ![next](/next.png)[Clafer a bit more precisely](ClaferMorePrecisely).