Debian Codegraph @

texmf-dist/doc/latex/tkz-orm/tkz-orm.tex

raw
1 \documentclass[a4paper,10pt]{article}
2
3 \usepackage{tkz-orm}
4 \usepackage{pgfmanualstyle}
5
6 \usetikzlibrary{fit} % fitting library
7 \usetikzlibrary{positioning} % for left/right=of ...
8
9 \usepackage[colorlinks=false,pdfborder={0 0 0}]{hyperref}
10 % [pagebackref=true, backref=true
11 \usepackage{multirow}
12
13 \usepackage{makeidx}
14 \makeindex
15
16 \def\ormVersion{0.1.4}
17 \def\ormDate{January 15, 2016}
18 \newif\ifappendix
19 \appendixfalse
20 \appendixtrue
21
22 % --------------------------------------------------------------
23 %% Beginning of the documentation
24 % --------------------------------------------------------------
25 \title{The \tkzorm\ package\\Object-Role Model Drawing Library}
26 \author{Jakob Vo\ss\footnote{[email protected]}, Camil Staps\footnote{[email protected]}}
27 \date{Version \ormVersion\\\ormDate\\[5mm]\url{http://purl.org/net/tkz-orm}}
28
29 \begin{document}
30 \maketitle
31
32 \begin{abstract}\noindent
33 This package provides styles for drawing Object-Role Model (ORM2) diagrams
34 in \TeX\ based on the \textsc{pgf} and \tikzname\ picture environment.
35 \end{abstract}
36
37 \tableofcontents
38 \pagebreak
39
40 \section{Introduction}
41 \label{sec:introduction}
42
43 \tkzorm\ is intended to help you creating Object-Role Model (ORM) diagrams. It is based on the \textsc{pgf} and \tikzname\footnote{Available at \url{http://sourceforge.net/projects/pgf/}.\\This document was created with \tikzname\ version \pgftypesetversion} picture macro package for \TeX. and provides additional styles and commands to typeset ORM2 diagrams. With \tkzorm\ you can ``program'' ORM diagrams just as you ``program'' your document when you use \LaTeX\ -- including the inherental lack of \textsc{wysiwyg}. Unless multi-touch e-paper interfaces become usable, \tkzorm\ can best be combined with a whiteboard or paper and pencil --- but you may also find ways to automatically create ORM diagrams with \tkzorm.
44
45 \subsection*{Status of this package}
46 This is the developer version of \tkzorm. Please send your comments to the author so the package can be improved. All parts of the package are available at least under the \LaTeX{} Project Public License\cite{LPPL} and the GNU Public license\cite{GPL2}. For details have a look at the file |LICENSE| that is part of this package. The permament URL of \tkzorm is \url{http://purl.org/net/tkz-orm} which redirects you to its current location and a collection of examples.
47
48 \subsection*{ORM in a nutshell}
49 Object-Role Modeling (ORM)\footnote{See \url{http://www.orm.net/}.} is a fact-oriented modeling language that evolved from the \textit{Natural-language Information Analysis Method} (NIAM) by G.M. Nijssen. The current version (ORM2) is mainly based on works of Terry Halpin. Like ERM, UML, and other data modeling languages ORM helps to identify and abstract information objects, relationships, and rules of a Universe of Discourse to be formalized and implemented on another level. ORM includes a graphical notation and a precise verbalization in natural language. Models can further be validated by populating fact tables with sample data. An overview of the ORM2 graphical notation is given in \cite{Halpin2005} and more details in \cite{Halpin2008}. An ORM model consists of object types (section~\ref{sec:objecttypes}) and predicates (section~\ref{sec:predicates}). Each of the $n$ roles of an $n$-ary predicate is connected to an object type that plays the specific role in this predicate. Furthermore a model can contain constraints (section~\ref{sec:constraints}), subtypes (section~\ref{sec:subtyping}), and other features (section~\ref{sec:additionalfeatures}). \tkzorm also allows you to change the appearance of ORM diagrams (section~\ref{sec:generalstyles}).
50
51 \begin{figure}[ht]
52 \centering
53 \begin{tikzpicture}
54 \entity (A) at (0,0) {A};
55 \entity[right=of A] (blank) {};
56 \value[right=of blank] (value) {Value type};
57 \entity[right=of value] (fixedwidth) {Person};
58 \entity[right=of fixedwidth] (tabular) {Activity\\(Code)};
59 \entity[right=of tabular] (typenamelabel) {Type name\\(.reference)};
60 \entity[right=of typenamelabel,zoomed] () {Zoomed};
61 \end{tikzpicture}
62 \caption{Examples of object types in ORM}
63 \end{figure}
64
65 \pagebreak
66 \section{Object Types}
67 \label{sec:objecttypes}\index{Object types}\index{Entities}\index{Values}
68 Object types are drawn as rectangles with rounded borders. The object's type name is written as node text inside. \emph{Entity types} use solid border lines and \emph{value types} use dashed border lines. The minimal size of an object is set to 6mm$\times$6mm. This package provides the following styles for entities and values:
69
70 \begin{stylekey}{entity}
71 This style is to be used with nodes that represent entity types.
72 \begin{codeexample}[]
73 \begin{tikzpicture}
74 \node[entity] at (0,0) {Foo};
75 \node[entity] (unnamed) at (1.2,0) {};
76 \node[entity] at (2.5,0) {Person\\(.name)};
77 \end{tikzpicture}
78 \end{codeexample}
79 \end{stylekey}
80
81 \begin{stylekey}{value}
82 This style is to be used with nodes that represent value types.
83 \begin{codeexample}[]
84 \begin{tikzpicture}
85 \node[value] {Name};
86 \end{tikzpicture}
87 \end{codeexample}
88 \end{stylekey}
89
90 \begin{stylekey}{power}
91 This style is to be used with nodes that represent power types.
92 \begin{codeexample}[]
93 \begin{tikzpicture}
94 \node[entity,power=below:As] {A};
95 \node[entity,power=Bs] at (1.1,0) {B};
96 \node[entity,power] at (2.2,0) {C};
97 \end{tikzpicture}
98 \end{codeexample}
99 \end{stylekey}
100
101 \begin{stylekey}{sequence}
102 This style is to be used with nodes that represent sequence types.
103 \begin{codeexample}[]
104 \begin{tikzpicture}
105 \node[entity,sequence=below:As] {A};
106 \node[entity,sequence=Bs] at (1.1,0) {B};
107 \node[entity,sequence] at (2.2,0) {C};
108 \end{tikzpicture}
109 \end{codeexample}
110 \end{stylekey}
111
112 \begin{stylekey}{every entity}
113 \stylekeyheadline[]{every value}
114 Each of this styles is envoked by the styles \sty{entity} or \sty{value}. Change one of this styles to change the appearance of entity or value types.
115 \begin{codeexample}[width=3cm]
116 \begin{tikzpicture}[
117 every entity/.style={draw=blue!50,fill=blue!20},
118 every value/.style={draw=green!50,fill=green!20}]
119 \node[entity] (P) at (0,0) {Person};
120 \node[value] (N) at (1.5,0) {Name};
121 \end{tikzpicture}
122 \end{codeexample}
123 \end{stylekey}
124
125 \begin{stylekey}{every object}
126 This style is envoked by the styles \sty{entity} and \sty{value}. Change this style to change the common appearance of entity and value types.
127 \begin{codeexample}[width=3cm]
128 \begin{tikzpicture}[
129 every object/.style={shape=rectangle,draw=red}]
130 \node[entity] (P) at (0,0) {Person};
131 \node[value] (N) at (1.5,0) {Name};
132 \end{tikzpicture}
133 \end{codeexample}
134 \end{stylekey}
135
136 \noindent
137 Since entity types and value types are very frequent node types in an ORM diagram, there are two special abbreviations for creating object types:
138
139 \begin{command}{entity}
140 Inside |{tikzpicture}| this is an abbreviation for |\node[entity]|.
141 \end{command}
142
143 \begin{command}{value}
144 Inside |{tikzpicture}| this is an abbreviation for |\node[value]|.
145 \end{command}
146
147
148 \section{Predicates and Roles}
149 \label{sec:predicates}\index{predicates}\index{roles}
150 Relationship parts (\emph{roles}) played by objects are shown as boxes of fixed size (4mm$\times$2.5mm). A \emph{predicate} is a sequence of one or more concatenated role boxes. Predicates can be created with the following styles:
151
152 \begin{stylekey}[\opt{\meta{number of roles}}]{roles}
153 \stylekeyheadline[\opt{1}]{role}
154 Shapes the current node as predicate with a given number of role boxes. Numbers from 1 to 20 are supported. The default value is 2 (binary).
155
156 \begin{codeexample}[]
157 \begin{tikzpicture}[orm]
158 \entity (A) at (0,1) {A};
159 \entity (B) at (2.8,1) {B}
160 edge node[roles=3] (p) {} (A);
161 \entity (C) at (1.4,0) {C} edge (p.south);
162 \node[role] at (2.2,0){} edge (C);
163 \draw (A) |- node[roles,xshift=2mm]{} (C);
164 \end{tikzpicture}
165 \end{codeexample}
166 \end{stylekey} % roles
167
168 \begin{stylekey}[\opt{\meta{number of roles}}]{vroles}
169 \stylekeyheadline[\opt{1}]{vrole}
170 Shapes the current node as predicate rotated by 90 degree (vertical).
171 \end{stylekey} % vroles
172
173 \begin{stylekey}{relation}
174 \stylekeyheadline[]{relationship}
175 \stylekeyheadline[]{plays}
176 This equivalent styles are to be used with connection lines between objects and roles. By default it just includes the style \sty{every orm line} which results in a solid, black line of 0.25mm width.
177 % Alternatively of using this style you can enable the general style \sty{orm}
178 % (see section~\ref{sec:generalstyles}) and just draw a normal line.
179 \begin{codeexample}[width=3cm]
180 \begin{tikzpicture}
181 \node[entity,power] (A) {A};
182 \node[roles] (r) at (1,0) {};
183 \draw[relation] (A-power) -- (r);
184 \node[vrole] at (0,-.8){} edge[relation] (A);
185 \end{tikzpicture}
186 \end{codeexample}
187 \end{stylekey}
188
189 \noindent
190 The following table lists abbreviations that can be used for creating predicate nodes and relationship lines inside |{tikzpicture}|:
191
192 \begin{table}[ht]
193 \begin{tabular}{lll}
194 \textbf{command(s)} & \textbf{abbreviation for} & \\
195 \commandentry{unary} or \commandentry{role} & |\node[role]| &
196 \colorbox{graphicbackground}{\tikz \unary{};} \\
197 \commandentry{binary} or \commandentry{roles} & |\node[roles]| &
198 \colorbox{graphicbackground}{\tikz \binary{};} \\
199 \commandentry{ternary} & |\node[roles=3]| &
200 \colorbox{graphicbackground}{\tikz \ternary{};} \\
201 \commandentry{vunary} or \commandentry{vrole} & |\node[vrole]| &
202 \multirow{3}{2cm}{\colorbox{graphicbackground}{
203 \begin{tikzpicture}
204 \vunary at (0,0){} ;
205 \vbinary at (0.6,-0.2){};
206 \vternary at (1.2,-0.4){};
207 \end{tikzpicture}
208 }} \\
209 \commandentry{vbinary} or \commandentry{vroles} & |\node[vroles]| \\
210 \commandentry{vternary} & |\node[vroles=3]| \\
211 \commandentry{plays} & |\draw[relationship]| &
212 \colorbox{graphicbackground}{\tikz \plays (0,0) -- (1,0);} \\
213 \end{tabular}
214 \end{table}
215
216 \noindent The general style of predicates and roles can be modified by the following keys:
217
218 \begin{stylekey}{every predicate}
219 Changing this style to modify the common appearance of predicates.
220 \begin{codeexample}[width=3cm]
221 \begin{tikzpicture}[
222 every predicate/.style={draw=blue,fill=green!20}]
223 \entity at (2,0) (B) {B};
224 \entity (A) {A} edge[relation] node[roles]{} (B);
225 \vunary at (0,-0.8) (r) {} edge[relation] (A);
226 \end{tikzpicture}
227 \end{codeexample}
228 \end{stylekey}
229
230 \begin{stylekey}{every relationship}
231 This style is envoked by the style \sty{relationship}. To change the appearance of explicit relationship lines you can change this style. Please keep in mind that nodes placed on a line by |node| in one operation inherit properties from the line they refer to, so you should create relationship lines with \cmd{plays}.
232 \begin{codeexample}[width=3cm]
233 \begin{tikzpicture}[orm,
234 every relationship/.style={draw=blue,dotted}]
235 \entity (A) {A};
236 \plays (A) to node[roles]{} (2,0) node(B){B};
237 \vunary at (0,-0.8) (r) {} edge[relation] (A);
238 \end{tikzpicture}
239 \end{codeexample}
240 \end{stylekey}
241
242 \noindent
243 Predicates are drawn either horizontally (\sty{roles}) or vertically (\sty{vroles}) as nodes with one or more parts. Figure~\ref{fig:hanchors} shows some of the anchors. Vertical predicates are rotated by 90 degree so |north| is at the left, |west| is at the bottom etc.
244 % TODO: define better anchors or anchor aliases (start=west, end=east, top=north, bottom=south, role 1=one north)
245
246 \begin{figure}[h]
247 \centering
248 \begin{codeexample}[width=10cm]
249 \Large
250 \begin{tikzpicture}
251 \node[roles=3,shape example,inner ysep=0.75cm] (s) {};
252 \foreach \anchor/\placement in
253 {one north/below, one south/above,
254 three north/below, three south/above,
255 one split/below, one split north/above, one split south/below,
256 two split/below, two split north/above, two split south/below,
257 north/below, south/above, east/below, west/below, center/above,
258 north west/above, north east/above, south west/below, south east/below}
259 \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
260 node[\placement] {\scriptsize\texttt{s.\anchor}};
261 \end{tikzpicture}
262 \end{codeexample}
263 \caption{Node anchors of an ORM predicate}
264 \label{fig:hanchors}
265 \end{figure}
266
267 \noindent
268 The verbalization of a predicate can be given as |label| next to a predicate. For binary relationships forward and inverse readings can be seperated by a slash. To show the inverse reading, add an arrow tip with the commands \cmd{ormleft} or \cmd{ormup}. Labels for predicates with more then two roles must contain three dots (|\ldots|) for each inner role. Role names and indices can be added by different styles.
269 % TODO: Show how to change label distance with style |label distance| :
270 % \begin{tikzgraphic}[orm] % needed - there is no "every label/.style={orm}"
271 % \node[role,label={R}] (r1) {}; % put the label above
272 % \node[role,right=of r1,label={below:R}] (r2) {}; % put the label below
273 % \node[role,right=of r2,label={[label distance=1.5mm]above:{R}},unique] (r3) {};
274 % \end{tikzgraphic}
275
276 \begin{figure}[h]
277 \centering
278 \begin{codeexample}[]
279 \begin{tikzpicture}[orm]
280 \entity at (0,3) (P) {Person};
281 \entity at (3,3) (C) {Car};
282 \entity at (0,0) (L) {License};
283 \entity at (6.6,3) (M) {Maker};
284 \unary[label=valid] at (1.2,0) (V) {} edge (L);
285 \draw (P) to node[roles,
286 label=below:drives,label=\ormleft{is driven by}]{} (C);
287 \draw (P) to node[vroles,label=has,label=below:\ormup{of}]{} (L);
288 \draw (C) to node[roles,label=created by/created]{} (M);
289 \ternary[label=below:drives \ldots by] at (3,1) (t) {};
290 \plays (P) -- (t.west);
291 \plays (C) -- (t);
292 \plays (M) -- (t.east);
293 \end{tikzpicture}
294 \end{codeexample}
295 \end{figure}
296
297 \begin{stylekey}{role name}
298 This style is to be used with role names. Role names can be displayed in square brackets and blue color next to a role box. % TODO: add role name as 'label' style
299 \begin{codeexample}[width=3cm]
300 \begin{tikzpicture}[orm]
301 \entity (A) at (0,0) {A};
302 \entity (B) at (2.8,0) {B};
303 \plays (A) edge node(r)[roles]{} (B);
304 \node[role name,
305 at=(r.north),anchor=south east] {[role1]};
306 \node[role name,
307 at=(r.north),anchor=south west] {[role2]};
308 \end{tikzpicture}
309 \end{codeexample}
310 \end{stylekey}
311
312 \begin{stylekey}[\meta{n}\opt{\texttt{:}\meta{index}}]{index}
313 Adds a role index as small label at the $n$th role box (default: $n$).
314 \begin{codeexample}[]
315 \begin{tikzpicture}
316 \binary[index=1,index=2:X] {};
317 \vroles[index=A.1,index=2:A.2] at (.8,0) {};
318 \end{tikzpicture}
319 \end{codeexample}
320 \end{stylekey}
321
322
323 \section{Constraints}
324 \label{sec:constraints}\index{Constraints}
325 ORM provides a rich set of constraints: Mandatory constraints (section~\ref{sec:mandatoryconstraints}) and uniqueness constraints (section~\ref{sec:uniquenessconstraints}) limit the way objects can be combined in predicates. External constraints (section~\ref{sec:externalconstraints}) and subtype constraints (section~\ref{sec:subtyping}) involve multiple roles or object types. All constraints are displayed in magenta and either drawn directly at an object type or role, or linked to one or more object types or role with dotted or dashed lines or arrows (see the styles \sty{limits} and \sty{limits to}). ORM2 defines a set of symbols for external (section~\ref{sec:externalconstraints}), ring (section~\ref{sec:ringconstraints}) and other types of constraints. The general \textsc{tkz-orm} constraint key \sty{constraint} only sets the font to violet. An optional key value can be used to add a predefined constraint symbol at the current position.
326
327 \begin{stylekey}[\meta{color}]{constraintcolor}
328 Changes the constraint color (default: |magenta!100|).
329 \end{stylekey}
330
331 \subsection{Uniqueness Constraints}
332 \label{sec:uniquenessconstraints}
333 By default every row in a fact table is unique. To express additional uniqueness constraints on one or more roles of a fact table or to explicitly express the uniqueness on the full predicate, a \emph{uniqueness bar} is drawn above or below the fact roles. If the bar spans two or more non-adjacent roles, it is drawn as dotted line above or below the excluded roles. Bars can be stacked in multiple levels. To draw uniqueness bars you can use the following styles at predicate nodes:
334
335 % TODO: add preferred unique (double line)
336
337 \begin{stylekey}[\opt{\meta{from}\texttt{-}\meta{to}\texttt{:}\meta{level}}]{unique}
338 Draws a uniqueness constraint bar above one or more roles. All parts of the key value are optional. As default a simple uniqueness bar above (\meta{level}|=1|) the first role (\meta{from}|=1|) is drawn. To make a bar span multiple roles, use the \meta{from}|-|\meta{to} syntax. Negative levels drawn the bar below the roles.
339 \begin{codeexample}[]
340 \begin{tikzpicture}
341 \binary[unique] at (0,0) {};
342 \binary[unique=2] at (1.2,0) {};
343 \ternary[unique=2-3:-1] at (0.2,-0.6) {};
344 \unary[unique=1,unique=1:2] at (1.4,-0.6) {};
345 \end{tikzpicture}
346 \end{codeexample}
347 \end{stylekey}
348
349 \begin{stylekey}[\opt{\meta{from}\texttt{-}\meta{to}\texttt{:}\meta{level}}]{skip unique}
350 Draws a dotted uniqueness constraint bar. The syntax is the same as at the \sty{unique} key.
351 The bar includes background color in the gaps between dots, so it can be drawn on top of
352 another bar.
353 \begin{codeexample}[]
354 \begin{tikzpicture}
355 \ternary[unique=1-3,skip unique=2] {};
356 \end{tikzpicture}
357 \end{codeexample}
358 \end{stylekey}
359
360 \begin{stylekey}{uniqueness bar}
361 \stylekeyheadline[]{skipped uniqueness bar}
362 This styles can be used to draw a line in the same style as a uniqueness constraint bar or a dotted uniqueness constraint bar.
363 \begin{codeexample}[width=3cm]
364 \tikz\draw[uniqueness bar] (0,0) -- (2,0);
365 \end{codeexample}
366 \begin{codeexample}[width=3cm]
367 \tikz\draw[skipped uniqueness bar] (0,0) -- (2,0);
368 \end{codeexample}
369 \end{stylekey}
370
371 \noindent
372 Please note that elementary $n$-ary predicates should only have uniqueness constraints of at least $n-1$ roles. Picture~\ref{fig:splitternary} shows how to split a ternary predicate with unique constraint bar on one role.
373
374 \begin{figure}[h]
375 \centering
376 \begin{codeexample}[]
377 \begin{tikzpicture}[orm] % needs positioning library
378 \ternary[unique] (t) at (0,0) {};
379 \entity[left=of t] {A} edge (t);
380 \entity[above=of t] {B} edge (t);
381 \entity[right=of t] {C} edge (t);
382 \node at (2.3,0) {$\Rightarrow$};
383 \entity (A) at (3,0) {A};
384 \binary[right=of A.north east,yshift=1mm,unique] (t1) {};
385 \binary[right=of A.south east,yshift=-1mm,unique] (t2) {};
386 \plays (A) -- (t1.west); \plays (A) -- (t2.west);
387 \entity[right=of t1] {B} edge (t1);
388 \entity[right=of t2] {C} edge (t2);
389 \end{tikzpicture}
390 \end{codeexample}
391 \caption{A ternary predicate can be split into to binary predicates}
392 \label{fig:splitternary}
393 \end{figure}
394
395
396 \subsection{Mandatory Role Constraints}
397 \label{sec:mandatoryconstraints}
398 To indicate explicitly that a role is mandatory, a mandatory role dot is added to either end of the line that connects the role to its object. Usually it is placed at the object type end. This package defines the style key \sty{constraint dot} (alias \sty{cdot}) and the following keys which can be used to add mandatory role dots to lines drawn with the |to| operation.
399
400 \begin{stylekey}{constraint dot}
401 \stylekeyheadline[]{cdot}
402 Draws the current node as mandatory role dot.
403 \begin{codeexample}[]
404 \tikz \node[cdot] {};
405 \end{codeexample}
406 \end{stylekey}
407
408 \begin{stylekey}{mandatory}
409 \stylekeyheadline[]{required}
410 This styles enables the \sty{relationship} style and adds a mandatory role dot at the start of a straight line.
411 \begin{codeexample}[]
412 \begin{tikzpicture}
413 \entity (A) {A};
414 \entity at (2,0) {B} edge[mandatory]
415 node[roles] (p) {} (A);
416 \end{tikzpicture}
417 \end{codeexample}
418 \end{stylekey}
419
420 \begin{stylekey}{required by}
421 This styles enables the \sty{relationship} style and adds a mandatory role dot at the end of a straight line.
422 \begin{codeexample}[]
423 \begin{tikzpicture}
424 \entity (A) {A};
425 \entity at (2,0) {B} edge[required by]
426 node[roles] (p) {} (A);
427 \end{tikzpicture}
428 \end{codeexample}
429 \end{stylekey}
430
431 \begin{stylekey}{both required}
432 \stylekeyheadline[]{both mandatory}
433 This styles enables the \sty{relationship} style and adds mandatory role dots at both ends of a straight line.
434 \begin{codeexample}[]
435 \begin{tikzpicture}
436 \entity (A) {A};
437 \entity at (2,0) {B} edge[both required]
438 node[roles] (p) {} (A);
439 \end{tikzpicture}
440 \end{codeexample}
441 \end{stylekey}
442
443 \noindent To show that either of many roles is mandatory, you can add an \emph{inclusive-or} (\emph{disjunctive mandatory}) role constraint with |constraint=mandatory| as shown in section~\ref{sec:externalconstraints}. By default it is assumed that each entity or value must play at least some role. \emph{Independent object types} whose roles are collectively optional can be marked by an exclamation mark appended to its name. It is recommended not to include implied mandatory constraints unless they they refer to subtypes (section~\ref{sec:subtyping}).
444 \index{Independent object types}\index{Object types!Independent}
445
446
447 \subsection{External constraints}
448 \label{sec:externalconstraints}
449 External constraints span multiple roles that may come from different predicates. They are depicted by several circle symbols next the roles they limit, possibly linked to them with a dotted or dashed line (style \sty{limits} and \sty{limits to}). \tkzorm\ implements external constraint symbols as node shapes.
450
451 \begin{stylekey}[\opt{\meta{constraint type}}]{constraint}
452 This style sets the font to ORM style on constraint color (violet). If you provide a constraint type as key value, the current node is shaped as constraint circle and the symbol of the specified constraint type is drawn. The most common constraint types are |exclusive| (alias |x|) to indicate that populations of two or more role-sequences must be mutually exclusive, |mandatory| (alias |required|, |total|, and |or|) to indicate that each at least on of two more roles must be played by an object type, and |xor| (alias |partition|) to indicates that exactely one of two or more roles must be played by an object type. These constraints can also be used in subtyping (section~\ref{sec:subtyping}). The constraint type |unique| and |preferred unique| enforces combinations of object types that play a given set of roles to always be the same. The types |equal|, |subset|, and |supset| indicate that tuples of roles have to be equal, subset or superset compared to each other (|supset| is not included in standard ORM2). The constraint type is |external| only draws the circle and can be used for custom constraints.
453 % TODO: see more about rings and collections ...
454 \begin{codeexample}[]
455 \begin{tikzpicture}[orm]
456 \matrix[column sep=2mm, row sep=2mm]{
457 \node[constraint=x]{}; & \node[right]{exclusive / x}; &
458 \node[constraint=or]{}; & \node[right,text width=2.8cm]
459 {mandatory / total required / or}; &
460 \node[constraint=xor]{}; & \node[right]{xor / partition}; \\
461 \node[constraint=unique] {}; & \node[right]{unique}; &
462 \node[constraint=preferred unique]{};&\node[right]{preferred unique};&
463 \node[constraint=external]{}; & \node[right]{external}; \\
464 \node[constraint=equal] {}; & \node[right]{equal}; &
465 \node[constraint=subset] {}; & \node[right]{subset}; &
466 \node[constraint=supset] {}; & \node[right]{supset}; \\
467 };
468 \end{tikzpicture}
469 \end{codeexample}
470 \end{stylekey}
471 \index{\texttt{custom} constraint}
472 \index{\texttt{x} constraint}
473 \index{\texttt{or} constraint}
474 \index{\texttt{xor} constraint}
475 \index{\texttt{mandatory} constraint}
476 \index{\texttt{required} constraint}
477 \index{\texttt{total} constraint}
478 \index{\texttt{partition} constraint}
479 \index{\texttt{unique} constraint}
480 \index{\texttt{preferred unique} constraint}
481 \index{\texttt{equal} constraint}
482 \index{\texttt{subset} constraint}
483 \index{\texttt{supset} constraint}
484
485
486 \begin{stylekey}{limits} % TODO: add optional parameter
487 This style is to be used with lines that connect constraint circles and roles. It can also be used to link other kinds of constraints (for instance value constraints) to the entity, value, or role they belong to.
488 \begin{codeexample}[width=3cm]
489 \begin{tikzpicture}
490 \unary (r1) at (0,0) {};
491 \unary (r2) at (0,-1.4) {};
492 \draw[limits] (r1) to node[constraint=x] {} (r2);
493 \end{tikzpicture}
494 \end{codeexample}
495 % TODO: example of subtyping constraints
496 \end{stylekey}
497
498 \begin{stylekey}{limits to} % TODO: add optional parameter
499 This style is to be used with directed lines that connect constraint circles and roles. The line is drawn in the same style as \sty{limits} but dashed and with an arrow tip of style \arrowtip{orm arrow} at the head.
500 \begin{codeexample}[width=3.4cm]
501 \begin{tikzpicture}[orm]
502 \unary[index=2] (a) at (0,0) {};
503 \unary[index=1] (b) at (0,-1.4) {};
504 \draw[limits to] (b) -- (a)
505 node[pos=.4,constraint=subset,name=s]{};
506 \node[right=2mm of s,text width=2.3cm]
507 {Each object that plays role 1 also plays role 2};
508 \end{tikzpicture}
509 \end{codeexample}
510 \end{stylekey}
511
512 \begin{command}[]{limits}
513 \end{command}
514 \begin{command}[]{limitsto}
515 %\stylekeyheadline[]{limits to}
516 Inside |{tikzpicture}| these commands can be used as abbreviations for
517 |\draw[limits]| and |\draw[limits to]|.
518 \begin{codeexample}[width=3.4cm]
519 \begin{tikzpicture}[orm]
520 \limits (0,.4) to (1,.4); \limitsto (0,0) to (1,0);
521 \end{tikzpicture}
522 \end{codeexample}
523 \end{command}
524
525 \begin{command}[\marg{constraint type name}\marg{path code}]{constraintdeclare}
526 This command declares a new constraint type. The \marg{path code} is passed to the |append after command| key to be drawn after the constraint circle. Unless you want to extend ORM you do not need to declare new constraint types. This command is for internal use only!
527 \end{command}
528
529 \begin{command}[\marg{alias name}\marg{existing constraint type name}]{constraintdeclarealias}
530 This command can be used to create an alias (another name) for an existing constraint type.
531 This command is for internal use only!
532 \end{command}
533
534 \begin{stylekey}{every constraint}
535 This style is envoked at every constraint. You can change this style to change for instance the constraint color.
536 \end{stylekey}
537
538
539 \subsection{Ring Constraints}
540 \label{sec:ringconstraints}
541
542 A ring constraint can be applied to any two roles of a predicate that are
543 played by the same object type (or the same supertype). Such constraints can
544 also be viewed as properties of a binary relation or as properties of a
545 directed graph. There are 10 ring constraints that combined can be used in 26
546 forms. The graphical syntax of `irreflexive' and `antisymmetric' provided by
547 this package are slightly changed compared to the official ORM2 syntax and
548 some combinations are omitted or changed.
549
550 %and the two symbols for `asymmetric and
551 %intransitive', and for `symmetric and intransitive' have been omitted because
552 %of complexity.
553
554 % TODO: additional: tree, otree
555 % combined: acyclic intransitive, symmetric irreflexive etc.
556 \begin{codeexample}[]
557 \centering
558 \begin{tikzpicture}[orm]
559 \foreach \n/\s in {0/irreflexive,1/asymmetric,2/strongly intransitive,
560 3/antisymmetric,4/acyclic,5/acyclic intransitive,
561 6/symmetric,7/purely reflexive,8/symmetric irreflexive,
562 9/intransitive,10/reflexive,11/transitive}{
563 \path ($mod(\n,3)*(3.4,0)-int(\n/3)*(0,0.8)$) node [constraint=\s] {}
564 +(4mm,0) node[anchor=west] {\s}; };
565 \end{tikzpicture}
566 \end{codeexample}
567
568 \begin{codeexample}[width=2.5cm]
569 \begin{tikzpicture}[orm]
570 \entity (P) {Person};
571 \binary[below=of P,unique=2,label=below:mother of] (r) {};
572 \plays (P) to (r.one north) (P) to (r.two north);
573 \limits (r.north) to +(-1,0.4) node[constraint=acyclic]{};
574 \end{tikzpicture}
575 \end{codeexample}
576
577
578 \subsection{Number and Value Constraints}
579 Value constraints, cardinality constraints, and occurrence frequencies can simply be drawn beside the object type or role they refer to, optionally linked to with a dotted or dashed limitation line.
580
581 \noindent\textbf{Frequency Constraints} specify the number of times an object can play a role. Usually it is connected to the roles with a limtation line. % TODO: better syntax as pin
582
583 \begin{codeexample}[width=3cm]
584 \begin{tikzpicture}
585 \binary[index=1:1] (b) {};
586 \limits (b.one south) -- +(0,-.4) node[constraint]{f};
587 \end{tikzpicture}
588 \end{codeexample}
589
590 \noindent A \textbf{Value constraint} indicates which values are allowed in an object type or role. It can be defined by declaring the set of possible values enclosed in curly brackets next to an object or role type. The commands \cmd{ormbraces} and \cmd{ormvalues} are handy abbreviations to create curly brackets.
591 \index{value constraints}\index{constraints!values}
592
593 \begin{codeexample}[]
594 \begin{tikzpicture}
595 \entity (A) {A};
596 \node[constraint,anchor=north west,inner ysep=0]
597 at (A.north east) {\ormbraces{a, b, c}};
598 \end{tikzpicture}
599 \end{codeexample}
600
601 \noindent\textbf{Value comparision-constraints} are depicted by one of four comparision operators $<$, $\le$ (|le|), $>$, and $\ge$ (|ge|). The constraints are shown at a dashed arrow between two roles in the same way as |constraint=subset| and |constraint=supset| (but the value-comparision is between instances not between sets). Equality can be stated with |constraint=equal| which should not be confused with similar looking |constraint=purely reflexive|.
602 \index{value-comparision constraints}\index{constraints!value-comparision}
603 \index{\texttt{<} constraint}
604 \index{\texttt{>} constraint}
605 \index{\texttt{le} constraint}
606 \index{\texttt{ge} constraint}
607
608 \begin{codeexample}[]
609 \tikz \foreach \x/\s in {0/<,1/ge,2/>,3/le}{
610 \draw[limits to] (\x,0) to (\x,1.2);
611 \node[constraint=\s] at (\x,.5) {};
612 };
613 \end{codeexample}
614
615 \noindent\textbf{Cardinality constraints} are rarely included in ORM diagrams since the are often implied by other constraints. However you can explicitely say that each population of an object type or a role includes exactely, at most, or at least a given number of instances. This is done by adding a cardinality constraint next to the object or role. The hash sign (``\#'') stands for the cardinality.
616 \index{cardinality constraints}\index{constraints!cardinality}
617
618 % TODO: Use text mode instead of math?
619 \begin{codeexample}[]
620 \begin{tikzpicture}[orm]
621 \entity[label={[constraint]\#=$n$}] {A};
622 \entity[label={[constraint]below:1$\leq$\#$\leq$6}]
623 at (1.1,0) {A};
624 \role[label={[constraint]\#$\leq$2}] at (2,0) {};
625 \end{tikzpicture}
626 \end{codeexample}
627
628
629
630 \subsection{Textual constraints}
631 \index{textual constraints}\index{constraints!textual}
632 Constraints not expressed by predefined graphical notation may be specified as textual rules. Textual rules can be displayed as footnotes with footnote numbers or signs that mark the involved elements in the diagram.
633
634 \begin{stylekey}[\opt{\meta{mark}}]{rule}
635 This key is to be used with nodes that contain textual rules. The optional \meta{mark} is shown as footnotes index left to the rule.
636 \begin{codeexample}[]
637 \begin{tikzpicture}
638 \node[rule=1] {{\ormbf Each} Number identifies {\ormbf at most one} Room.};
639 \end{tikzpicture}
640 \end{codeexample}
641 \end{stylekey}
642
643 \begin{command}[]{rules}
644 This command is an abbreviation for |\matrix[row sep=0mm,nodes={right}]| inside |{tikzpicture}|.
645 Matrices are useful to draw multiple textual rules below each other.
646
647 \begin{figure}[h]
648 \centering
649 \begin{codeexample}[]
650 \begin{tikzpicture}
651 \entity (E) {Employee\ormind{1}\\(.nr)};
652 \binary[left=of E.north west,unique=2,label=\ormleft{has}] (h) {};
653 \binary[left=of E.south west,unique=1-2,
654 label=below:\ormleft{uses\ormind{2,3}}] (u) {};
655 \entity[left=of h] (Rank) {Rank\\(.code)};
656 \entity[left=of u] (Car) {CompanyCar\\(.regNr)};
657 \node[constraint=text,align=left,anchor=east] at (Rank.west)
658 {\textbraceleft`Exec',\\`NonExec'\textbraceright};
659 \plays[mandatory] (E) to (h.east);
660 \plays (h) to (Rank) (E) to (u.east) (u) to (Car);
661 \binary[right=of E.north east,unique,label=was born on] (b) {};
662 \binary[right=of E.south east,unique,label=below:was hired on] (i) {};
663 \entity[right=1.8 of E] (Date) {Date\\(mdy)};
664 \plays[mandatory] (E) to (b.west) (E) to (i.west);
665 \plays (b.east) to (Date) (i.east) to (Date);
666 \node[role name,anchor=south west] at (b.east) {[birthdate]};
667 \node[role name,anchor=north west] at (i.east) {[hiredate]};
668 \rules at (-.4,-2) {
669 \node[rule=1] {{\ormbf For each} Employee, birthdate $<$ hiredate.}; \\
670 \node[rule=2] {
671 {\ormbf Each} Employee {\ormbf who} has Rank `NonExec' uses
672 {\ormbf at most one} CompanyCar.};\\
673 \node[rule=3] {
674 {\ormbf Each} Employee {\ormbf who} has Rank `Exec' uses
675 {\ormbf some} CompanyCar.};\\
676 };
677 \end{tikzpicture}
678 \end{codeexample}
679 \end{figure}
680 \end{command}
681
682 \section{Subtyping}
683 \label{sec:subtyping}
684
685 To draw type hierarchies you can use the tree syntax of \tikzname.
686 Euler diagrams are a less used alternative for simple type hierarchies.
687 % TODO: add Euler diagram example
688
689 \begin{stylekey}{subtype}
690 Draws a subtype relationship arrow from the supertype to the subtype.
691 \begin{figure}[h]
692 \centering
693 \begin{codeexample}[]
694 \begin{tikzpicture}[
695 edge from parent/.style=subtype]
696 \node[entity] {Animal}
697 child {node[entity] {Mammal}}
698 child {node[entity] {Bird}
699 child {node[entity] {Penguin}}
700 child {node[entity] {Parrot}}
701 };
702 \end{tikzpicture}
703 \end{codeexample}
704 \end{figure}
705 \end{stylekey}
706
707 \begin{stylekey}{suptype}
708 Works in the same way as \sty{subtype} but with reverse direction.
709 \begin{codeexample}[]
710 \begin{tikzpicture}
711 \node[entity] (A) {Animal};
712 \node[entity] (S) [right=6mm of A] {Sheep};
713 \draw[suptype] (S) to (A);
714 \end{tikzpicture}
715 \end{codeexample}
716 \end{stylekey}
717
718 \noindent Multiple inheritance may require to select one path as primary.
719 You can distinguish primary and secondary subtypes by drawing the latter
720 with a dashed arrow (\sty{subinterface} or \sty{supinterface}).
721
722 \begin{stylekey}{subinterface}
723 \stylekeyheadline[]{supinterface}
724 Draw secondary subtype/supertype relationship arrows.
725 \begin{codeexample}[]
726 \begin{tikzpicture}
727 \node[entity] (A) {Animal};
728 \node[entity] (P) [right=8mm of A] {Person};
729 \draw[supinterface] (P) to (A);
730 \end{tikzpicture}
731 \end{codeexample}
732 \end{stylekey}
733
734
735 \noindent
736 Subtype constraints can be shown linked to the subtype arrrows:
737
738 \begin{figure}[h]
739 \centering
740 \begin{codeexample}[]
741 \begin{tikzpicture}[orm]
742 \foreach \c/\x in {exclusive/0,total/2.5,partition/5}{
743 \entity (A) at (\x,0) {A} [edge from parent/.style=subtype]
744 child {node [entity] (B) {B}} child {node [entity] (C) {C}};
745 \limits ($(A)!.7!(B)$) to node[constraint=\c] {} ($(A)!.7!(C)$);
746 \node at (\x,-2) {\c};
747 };
748 \end{tikzpicture}
749 \end{codeexample}
750 \end{figure}
751
752
753 \section{Additional Features}
754 \label{sec:additionalfeatures}
755 %\ldots partly no standard ORM2 \ldots
756
757 \subsection{Duplicated and implied parts of a model}
758 \label{sec:duplicatedandimplied}
759 Sometimes an object type or predicate is referred to without describing all its details because it is defined in an external model or because it is shown duplicated at some other place in the same model. To indicate such an external or duplicated object type or a predicate, a shadow is added to its shape. Alternatively ORM2 allows to add a circumflex ``\^{}'' to an object type's name. A different kind of redundancy are roles and constraints that deduce from other parts of the model. ORM2 includes the possibility to shade redundant roles. This is useful for instance to show conceptual pathes or join fact types that are normally excluded. Moreover ORM allows a \emph{zooming} on object types. This means that only objects and roles connected to a given object type are shown.
760
761 \begin{stylekey}{duplicated model}
762 This style modifies the styles \sty{every object} and \sty{every predicate} so all object types and predicates in the current scope get a shadow.
763 \begin{codeexample}[]
764 \begin{tikzpicture}[orm]
765 \begin{scope}[duplicated model]
766 \entity (A) {A};
767 \node[role] (r1) [right=of A] {};
768 \node[role] (r2) [right=0 of r1] {};
769 \draw[relationship] (A) -- (r1);
770 \end{scope}
771 \entity (B) [right=of r2] {B\^{}};
772 \plays (r2) -- (B);
773 \end{tikzpicture}
774 \end{codeexample}
775 \end{stylekey} % duplicated model
776
777 \begin{stylekey}{implied model}
778 This style modifies the styles \sty{every orm line} and \sty{every object} in the current scope to draw all lines thin and all objects filled gray.
779 The style is currently broken.
780 \begin{figure}[h]
781 \centering
782 \begin{codeexample}[]
783 \begin{tikzpicture}
784 \matrix[column sep=4mm] {
785 \entity (A) {A}; & \binary (ab) {}; & \entity (B) {B}; &
786 \binary (bc) {}; & \entity (C) {C}; \\ };
787 \plays (A) -- (ab) -- (B) -- (bc) -- (C);
788 \begin{scope}[implied model]
789 \node[constraint=unique] (con) [above=of B] {};
790 \limits (ab.one north) -- (con) -- (bc.two north);
791 \ternary[unique=1-3,skip unique=2] (abc) [below=4mm of B] {};
792 \plays (A) -- (abc.west); \plays (B) -- (abc); \plays (C) -- (abc.east);
793 \end{scope}
794 \end{tikzpicture}
795 \end{codeexample}
796 \end{figure}
797 \end{stylekey}
798
799 \begin{stylekey}{duplicated}
800 \stylekeyheadline[]{implied}
801 This styles work like \sty{duplicated model} and \sty{implied model} but only affect the current element.
802 The style are currently broken.
803 \begin{codeexample}[]
804 \begin{tikzpicture}
805 \entity[duplicated] (P) {Person};
806 \value[implied,right=1.6 of P] (V) {PersonName};
807 \draw[implied,both required] (P) to
808 node[roles,unique=1,unique=2]{} (V);
809 \end{tikzpicture}
810 \end{codeexample}
811 \end{stylekey}
812
813
814 \begin{stylekey}{zoomed}
815 This styles visualizes an object type as {\emph zoomed} by using a thicker line.
816 \begin{codeexample}[]
817 \begin{tikzpicture}
818 \entity at (0,0) {Normal};
819 \entity[zoomed] at (2,0) {Zoomed};
820 \end{tikzpicture}
821 \end{codeexample}
822 \end{stylekey}
823
824
825 \subsection{Arrow heads}
826 \label{sec:arrowheads}
827 Constraint dots are implemented as arrow heads. The normal constraint
828 dot is drawn with arrow head |mdot| for mandatory. Furthemore there is an
829 implicit mandatory constraint dot (|idot|), a deontic mandatory constraint
830 dot (|odot|), and a implied deontic mandatory constraint dot (|iodot|). You
831 \emph{should not} directly use this arrow heads but the mandatory role
832 constraints |cdot|, |required| etc. (\ref{sec:mandatoryconstraints}) which
833 can be modified by other styles. This feature is not fully tested yet.
834
835 \begin{codeexample}[]
836 \begin{tikzpicture}[orm]
837 \matrix [row sep=2mm,column sep=3mm,every entity/.style={minimum width=10mm}]{
838 \entity[label=left:strict,label=above:explicit,right] (m) {mdot}; &
839 \entity[label=above:implicit] (i) {idot}; \\
840 \entity[label=left:deontic,right] (o) {odot}; &
841 \entity (io) {iodot}; \\ };
842 \plays[mdot-idot] (m) to (i);
843 \plays[odot-iodot] (o) to (io);
844 \end{tikzpicture}
845 \end{codeexample}
846
847
848 \subsection{Macros for text layout}
849 \label{sec:ormtext}
850 The following macros can be used both in \tikzname{} pictures or normal text:
851
852 \begin{command}{ormtext}
853 Sets the font to the same sans-serif variant which is used in ORM diagrams.
854 \end{command}
855
856 \begin{command}{ormbf}
857 Sets the font to a bold variant of \cmd{ormtext}.
858 \end{command}
859
860 \begin{command}{ormc}
861 Sets the font to a \cmd{ormtext} in constraint color.
862 \end{command}
863
864 \begin{command}[\marg{text}]{ormsup}
865 Puts some text in a superscript variant of \cmd{ormtext}.
866 \end{command}
867
868 \begin{command}[\marg{text}]{ormsub}
869 Puts some text in a subscript variant of \cmd{ormtext}.
870 \end{command}
871
872 \begin{command}[\marg{text}]{ormind}
873 Puts some text in a superscript variant of \cmd{ormbf}.
874 \end{command}
875
876 \begin{command}[\marg{text}]{ormbraces}
877 Puts some text as \cmd{ormtext} in braces.
878 \end{command}
879
880 \begin{command}[\marg{text}]{ormvalues}
881 Puts some text as \cmd{ormc} in braces in constraint color.
882 \end{command}
883
884 \begin{codeexample}[]
885 \ormind{1}A {\ormtext Person} is not \ormbraces{0,1},~
886 {\ormc Male} {\ormbf or} {\ormtext Female}, \ormup{up}~
887 {\ormbf or} \ormleft{left} but \ormsub{queer}multi\ormsup{gender}!
888 \end{codeexample}
889
890
891 \section{Settings and Utilities}
892 \label{sec:generalstyles}
893
894 \begin{stylekey}{orm}
895 This style sets the font and line width and the default node distance
896 \end{stylekey}
897
898 \begin{stylekey}{orm-spacious}
899 If you prefer to have entities and labels typeset as circles, you can use \texttt{orm-spacious} instead of \texttt{orm}.
900 \begin{codeexample}[width=3cm]
901 \begin{tikzpicture}[orm-spacious]
902 \node[entity] (P) at (0,0) {Person};
903 \node[value] (N) at (1.5,0) {Name};
904 \end{tikzpicture}
905 \end{codeexample}
906 \end{stylekey}
907
908 \begin{stylekey}{every orm line}
909 This style is envoked by all styles of this package that draw lines. By default it sets the line width to 0.3mm.
910 \end{stylekey}
911
912 % \begin{stylekey}{every orm object}
913 % \end{stylekey}
914 % For this purpose (and for subtype arrows) this package defines the arrow tip \arrowtip{orm arrow}.
915 % TODO: document arrow tip \arrowtip{orm arrow}
916 % TODO: replace search path with |/orm/| instad of |/tikz/|.
917
918
919 \section*{Changes}
920
921 \begin{description}
922 \item[\ormVersion, \ormDate]
923 Unstable developer version (at Github).
924 \item[0.1.4, January 15, 2016]
925 Power types, sequence types, \texttt{orm-spacious} added.
926 \item[0.1, January 25, 2010]
927 First release (at CTAN).
928 \end{description}
929
930 \ifappendix
931 \bibliographystyle{alpha}
932 \addcontentsline{toc}{section}{References and Index}
933 \bibliography{tkz-orm}
934 \printindex
935 \fi
936
937 \end{document}