Language defines the boundary to our world: it sets what we can describe and what we can’t. This talk describes and demonstrates how to formalize a ubiquitous language into a domain-specific language. If we do this move the language is not used only for communication and collaboration as well as used as a basis for generating code, tests, configs, etc. It means that domain experts/subject matter experts use the language. The talk is based on industry cases from various domains, such as banking and insurance, industry automation and automotive, and been demonstrated during the talk.

1. 1
How to upgrade a ubiquitous
language into a domain-specific
language:
Cases from practice
Dr. Juha-Pekka Tolvanen
9 February 2023

2. 2
2
Route
DDD and ubiquitous language
Elements of language
Examples
A task
How to find suitable language elements
Discussion

3. 3
3
Your questions, comments,
counter arguments and
experiences are welcome.
=> Chat

4. 4
4
On languages
◼ Ubiquitous Language
– A language structured around the domain model
– Shared understanding
– Used by team members to connect all the activities
◼ Domain-Specific (Modeling) Languages
– Focus on expressing a specific problem domain
– Usually based on formal definition
– Computer supported language

5. 5
5
Similarities
◼ Narrow focus
◼ Addresses the gap between problem and solution
domains
◼ Raise the level of abstraction, away from “code”
◼ Allows participation with non-technical stakeholders
– Communicate
– Verify
– Create
◼ No reason to be limited to software only
– systems engineering, product lines, safety, etc.

6. 6
6
Differences
◼ DSL is based on a formal definition of the shared
understanding
– Rigor, not vague
◼ Ubiquitous language in DDD may cover also other parts
that DSL aims
◼ DSL enables stakeholders to:
– Verify specifications
– Create specifications
– Define working solutions/products or their parts

7. 7
7
Elements for a language
1. Terminology
2. Glossary/dictionary
3. References with glossary items
4. Domain model
5. Rules and constraints with a metamodel
6. Guidance
7. Concrete syntax

8. 8
8
1. Terminology
◼ Terms and specific words often applied “naturally” even
without realizing it
– Railway interlocking systems: tracks, signals, switches,
routes, sections, etc.
– Insurance products: risks, damages, surpluses, tariffs,
compensations, etc.
– Medical machine: needle, belt, shutter, cup, cleaning etc.
◼ Spoken form: jargon, “domain-speak”
◼ Written form: “task-related documents”, like
specifications

9. 9
9
2. Glossary (dictionary)
◼ Terms specific to a particular subject
◼ Terms with definitions

10. 10
10
Glossary example (insurance)
• A Versicherungsnehmer represents the person legally signing
the insurance contract
• A Gegenstand (object) defines an insurance specific
classification of insurable objects / persons / rights etc.
• A Gefahr (hazard) is a description of the qualitative insurance
coverage
• An Ereignis (event) is a classification of real world processes,
that can have an impact on Gegenstand or cause Schäden (for
example reaching a certain age, stroke of lightning, theft,
natural death, redemption)
• Schaden (damage) is insurance specific classification of
damages as an result of Ereignissen (events) (e.g. destruction of
residence contents, loss of cash, disability, demolition of a car)

11. 11
11
3. References with glossary items
◼ E.g. Pensions in Finland

12. 12
12
Snomed CT: clinical concepts

13. 13
13
4. Domain model
◼ Ubiquitous language is structured around the domain
model
– “should be based on domain model: need to be rigorous
and not vague”, M. Fowler
◼ From DSL point of view domain model:
– May have elements that DSL would not need
– Does not have elements or rules that DSL should cover
– Does not provide guidance
– Does not provide concrete syntax for the language

14. 14
14
OpenEHR: Blood pressure

15. 15
15
Universal scope
◼ Slow process when universal
◼ 12% published*
* Huttunen, Open platform based clinical decision support, 2022

16. 16
Fowler’s Gothic Security example*
* Fowler, Domain-Specific Languages, Addison-Wesley, 2010

17. 17
◼ What is missing from
domain model?
– Datatypes
– code is number/string…
– Mandatory values
– state name
– Legal values
– event/command code
– Unique values
– state name
– etc.
Fowler’s Gothic Security example

18. 18
18
5. Rules and constraints with a
metamodel
◼ Domain model may include many rules and constraints
of the domain but not all for a language, like
– Uniqueness
– Mandatory
– Legal values, value ranges, default values
– Naming conventions (capital, prefix, exclude marks…)
– Occurrence
– Reuse rules (must reuse, not create own)
– Namespaces
– “Structuring”, like hierarchies, reuse, referrals to libraries
◼ Often best to define these by applying the language

19. 19
Fowler’s Gothic Security example

20. 20
Metamodel of Gothic Security
◼ Away from implementation: refer to event, not its internal code
◼ Code is unique
◼ State name is unique within a state machine
◼ Explicit multiplicities

21. 21
Metamodel -> Model

22. 22

23. 23
23
Insurance products

24. 24
24
Domain model to
metamodel

25. 25
25
Language definition

26. 26
26
How to find suitable language
concepts?
Task

27. 27
27
Language creation task
◼ Mixing medicine in
a special machine

28. 28
28
Language for mixing medicine?
“take from the second
cup 5 units with filter A
and put 2 units to cup 6
and 3 units to cup 7 and
then clean the needle”
01 move(-3); filt(1); suck(5);
02 move(4); filt(0); blow(2);
03 move(1); blow(3);
04 move(-3); suck(30);
05 move(1); blow(30);

29. 29
29
Implementation based language
01 move(-3); filt(1); suck(5);
02 move(4); filt(0); blow(2);
03 move(1); blow(3);
04 move(-3); suck(30);
05 move(1); blow(30);

30. 30
30
Language specification example
move(-3); filt(1); suck(5);
move(4); filt(0); blow(2);
move(1); blow(3);
move(-3); suck(30);
move(1); blow(30);

31. 31
31

32. 32
32
A
“take from the
second cup 5
units with filter A
put 2 units
to cup 6
put 3
units to
cup 7
then clean
the needle”
01 move(-3); filt(1); suck(5);
02 move(4); filt(0); blow(2);
03 move(1); blow(3);
04 move(-3); suck(30);
05 move(1); blow(30);

33. 33
33
Language specification example
A

34. 34
34
A
 Filter used only with Take
 Used Filter removed before Put
 Can not Clean needle after Take
 Needle is always complete cleaned
 Never forget remove cleaning fluid
 …

35. 35
35
move(-3);
filt(1);
suck(5);
move(4);
filt(0);
blow(2);
move(1);
blow(3);
move(-3);
suck(30);
move(1);
blow(30);

36. 36
36
Language specification example

37. 37
37
Different languages. Best one?
A
B
C

38. 38
38
A
35 elements 8 elements
17 elements
Effort to use the language?
A B
C

39. 39
39
How to find suitable language
concepts
◼ “How do I start creating language?”
– Hard problem for beginners
– Analyzed tens of cases to find good toolbox of approaches
◼ Initial analysis suggested five approaches:
A. Domain expert’s or developer’s concepts
B. Generation output
C. Physical structure
D. Look and feel of the system built
E. Variability space

40. 40
40
A. (Some) domain concepts exists
◼ A good start, but needs revision as often differs from
metamodel/grammar
– Lack details
– Few constraints only
– No consideration of reuse
– No concrete syntax
◼ Refine with examples
– legal
– illegal

41. 41
41
Functional Safety: ISO 26262
domain model
◼ ISO26262
– Item
– Hazard
– Hazard event
– Safety goal
– Safety concept
– Feature flaw
– ASIL
• Exposure
• Severity
• Controllability

42. 42
42
Added to obtain domain-specific
language
◼ What is
– element
– connection
– connection end
– attribute
– submodel
– combination of elements
– etc.
◼ Above is dependent on
the capabilities of the
metamodeling language

43. 43
43
Dependability ISO 26262 modeling

44. 44
44
Added to obtain domain-specific
language
◼ What is an element | connection | connection end |
attribute | submodel | combination of elements etc.
◼ What rules and constraints are relevant:
– Mandatory: e.g. short name
– Naming rules: e.g. short name as in AUTOSAR
– Default values:
• Boolean, value from enumeration or allow empty
– Order for setting attributes, e.g. for hazardous event
– Expect referring to existing data (e.g. features defined in
feature models, or allow defining new features)
– Preferred order for defining safety models
• E.g. as in ISO 26262: start with Item, Feature, Hazard…

45. 45
45
<subaction id="Call redirected to the voicemail address">
<location url="sip:jones@voicemail.example.com">
<redirect />
</location>
</subaction>
<incoming>
<location url="sip:jones@phone.example.com">
<proxy timeout="8">
<failure>
<log name="Failed calls">
<mail url="sip:jones@email.example.com">
</mail>
</log>
</failure>
<noanswer>
<address-switch field="origin">
<address is = "sip:boss@example.com">
<location url="tel:+19175551212">
<proxy/>
</location>
</address>
<otherwise>
<sub ref="Call redirected to the voicemail
</otherwise>
</address-switch>
</noanswer>
<busy>
<sub ref="Call redirected to the voicemail address
</busy>
</proxy>
</location>
</incoming>
B. Generation output
◼ Low abstraction (≠problem domain)
– No domain concepts
– No domain rules
– Notation?
◼ Danger: Little
productivity gains
case EditMinutes:
switch (button)
{
case Mode:
state = EditHours;
break;
case Up:
roll(alarmTime, MINUTE, 1, displayTime());
break;
case Set:
setAlarm("AlarmClock", 1, AlarmRang, alarmTime - clockTime);
icon (1, "alarm");
state = Show;
break;
case Down:
roll(alarmTime, MINUTE, -1, displayTime());
break;
default:
break;
}

46. 46
46
C. Physical structure as a base
◼ Great as mimic higher level of abstractions
– Do not cover constraints
– Enable creating different examples
– Easier for external language engineers
– Suggest a notation

47. 47
47
One DSL per domain?

48. 48
48
D. Look and feel of end system
◼ High level of abstraction
– Domain concepts visible
– Notation can mimic
the “real world”
– Finalize by applying all UI
concepts in examples
◼ Often state machine as a basis
– Extend with data & control flow

49. 49
49
D. Look and feel of end system

50. 50
50
E. Variability space
◼ Direct domain concepts
= What can vary in a product line?
– Language express variability
– Apply domain concepts and rules
– Notation?
◼ Based on domain engineering
– Feature modeling

51. 51
51
Fish farm automation system

52. 52
52
Constraints and rules have different
scopes
◼ Set to be ensured on final (complete) specification
◼ Set as exchange format
– Enable partial, allow “illegal”
◼ Storage format
◼ Expected at certain phase or usage time
– Producing output (generating code, tests etc.)
– Versioning time
– Separate checking time
– Specification time
◼ Guidance

53. 53
53
6. Guidance
◼ Suggestions for the language user on what to do next
– Often - but not always - related to correctness,
completeness and consistency of the created specification
◼ Review of 23 cases* shows that
guidance and annotations seems
to be are added:
– Over time
– As use grows
• Number of (new) users
Icon 1
Color 3
Text 5
Graphical 9
LiveCheck 5
Report 1
Generation 0
Textual 6
* Kelly, Tolvanen, International Workshop on Foundations and Practice of Visual Modeling, ECMFA, 2021

54. 54
54

55. 55
55
Guidance example

56. 56
56
Apply ISO 26262 as a language
◼ ISO26262
– Item
– Hazard
– HazardEvent
– SafetyGoal
– Requirement
– SafetyConcept
– …

57. 57
57
Guidance example
◼ Item must link to one or more features
◼ Hazard must be related to one or more Items
◼ Hazard must be related to one or more Feature Flaws
◼ HazardousEvent must be related to one or more
Hazards
◼ HazardousEvent must be related to one or more Use
Cases
◼ FeatureFlaws must be related to one or more Items
◼ SafetyGoal must be derived from one or more
HazardousEvents

58. 58
58
7. Concrete syntax
◼ Text
◼ Diagram
◼ Matrix
◼ Map
◼ Tree
◼ Table
◼ ?
◼ + combinations of the above
◼ Often the best is something that mimics the domain
been addressed

59. 59
59
Use existing if available, e.g. ISO
and IEC

60. 60
60
Warehouse automation systems

61. 61
61
Blood separator machines: Mix and
match

62. 62
62
Guidance for defining concrete
syntax*
◼ Mimic the problem domain addressed
◼ Symbols should use full range of visual variables
* D. Moody, The “Physics” of Notations, IEEE Transactions on Software Engineering, vol. 35, no. 6, 2009

63. 63
Fowler’s Gothic Security example

64. 64
64
Pseudo-realistic, alternative
notations

65. 65
65
Insurance products

66. 66
66
Summary
1. Terminology
2. Glossary/dictionary
3. References with glossary items
4. Domain model
5. Rules and constraints with a metamodel
6. Guidance
7. Concrete syntax

67. 67
67
Cost of DSL creation: industry cases
0 2 4 6 8 10 12 14 16
Blood separator
(Djukic et al. 2014)
Warehouse automation
(Preschern et al. 2014)
Heating remote control
(Puolitaival 2011)
Terminal network testing
(Puolitaival et al. 2011)
Heart rate monitors
(Kärnä et al. 2009)
Touch screen UI applications
(Safa 2007)
Days
Domain

68. 68
68
Summary
◼ Domain models provide a good start for defining a
(domain-specific) language, but:
– Lack details, usually cover limited set of constraints
– No consideration of reuse
– No concrete syntax
◼ We discussed ways to upgrade towards DSL
◼ Validate with examples of legal (and illegal) cases
– Involvement and participation from users
◼ Formalize early
– People can react on use, not so well on language definition
– Tools help here

69. 69
Thank you
Questions?
Comments?
Counter arguments?
Experiences?
For further details: jpt@metacase.com

70. 70
70
About me: Juha-Pekka Tolvanen
◼ Works for MetaCase
– Provider of modeling and code generation tool MetaEdit+
◼ Acts as a consultant for creating DSLs
– 100+ DSL solutions
◼ Co-author of a book on
Domain-Specific Modeling, IEEE-Wiley
◼ PhD in computer science,
adjunct professor
◼ Enjoys sailing and skiing