Commit 4727b38d authored by RieksJ's avatar RieksJ
Browse files

updates of Notations and Conventions

parent 2e428c21
Pipeline #49054 passed with stage
in 2 minutes and 58 seconds
......@@ -20,27 +20,46 @@ We are working towards deprecating this convention, as we now have better ways o
### Pattern diagram notations
%%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation. The following diagram represents the %%jurisdiction pattern|pattern-jurisdiction%%, which shows most of the notations we use:
%%Pattern|pattern%% diagrams will be visualized in this document using a notation that is very similar to that used by [UML](https://www.uml-diagrams.org/). The following diagram shows the various notations that we will be using that are basically taken from [UML](https://www.uml-diagrams.org/). There are a few exceptions, that are not shown in the figure; they are explained at the end.
<br/><br/>
<img
alt="Notations and conventions"
src={useBaseUrl('images/essif-lab-notations-and-conventions.png')}
/>
<br/><br/>
A **rectangle**, e.g. 'Person', represents a (named) %%concept|concept%%, or [entity-class](https://www.uml-diagrams.org/class.html). The (operational) extension of a %%concept|concept%% is the sets of its instances (for 'Person', the extension consists of the set of actual people of flesh and blood tha are in the scope of the model). The extensions of different concepts are disjunct (do not overlap), unless there is an 'ISA' relation between them (see below).
A **solid line with a closed arrowhead**, e.g. 'owns', represents a (named) relation/[association](https://www.uml-diagrams.org/association.html) between the two %%concepts|concept%% it connects. The concept at the arrowhead ('House') is called the 'target %%concept|concept%%' (TGT) for that relation; the other ('Person') is called the 'source %%concept|concept%%' (SRC). The relation is labeled such that `<SRC> <relation label> <TGT>` (Person owns House) suggests the phrase that descibes the intension(al definition) of that relation. The (operational) extension of a relation embraces all pairs (SRC,TGT) for which the relation holds. In the example, it consists of all pairs (P,H), where P is a Person and H is a House, such that the phrase 'P owns H' is true.
A **green name** at either [end of a relation/association](https://www.uml-diagrams.org/association.html#association-end) is what UML calls 'role'; this name may be used to refer to (an instance of) the %%concept|concept%% at which the name is placed as it performs its/this role in this relation. In the figure, `owner` is the role that a Person fulfills in the relation 'owns'. If we assert that a Person (P) is the owner of a specific House (H), or that House H is owned by Person P, this means that (P,H) is an element of the extension of the relation 'owns'.
A **solid line with an open arrowhead**, represents a [generalization relation](https://www.uml-diagrams.org/generalization.html). It can be read as `<SRC> is a <TGT>`, and is therefore also referred to as an ISA-relation. The SRC of the relation is the specialization (subclass) of the TGT (which in turn is a generalization of SRC). This means that SRC satisfies all constraints that TGT satisfies, and also that SRC has all attributes (properties, characteristics) that TGT has. The figure shows 'Self Employed Retailer is a Person' as an example.
A **line with a solid diamand** at one end represents a [composition](https://www.uml-diagrams.org/composition.html) relation. The element at the 'diamond-end' is called the 'parent', or the 'whole'. The other element is called the 'child' or the 'part'. A 'part' in a composition relation cannot be part of more than one 'whole'. Normally, if a 'whole' in a composition relation ceases to exist, then so do all of its composite parts. In the figure, at least one Bedroom and precisely one Living Roomn are parts of a (every) House. Obviously, if a House ceases to exist, then so do these rooms.
A **line with a hollow diamand** at one end represents an [aggregation](https://www.uml-diagrams.org/aggregation.html) relation. The element at the 'diamond-end' is called the 'parent', or the 'whole'. The other element is called the 'child' or the 'part'. A 'part' can be a part in multiple aggregation relations, and hence be part of multiple 'wholes'. If a 'whole' in an aggregation relation ceases to exist, the parts typically continue their existence. In the figure, 'Documentation' (about a Building Type) is an aggregation of a 'User Manual' and at least one 'Technical Document'. Obviously, if the Documentation ceases to exist, then the 'User Manual' and 'Technical Documents' typically continue to exist.
- A **dashed line** with a pointed arrow (`>`) represents a [dependency](https://www.uml-diagrams.org/dependency.html), where the SRC concept somehow depends on the TGT concept. The kind of dependency is specified by a `<<text>>`. In the figure, we see a dependency relation relation `<<instance>>`, indicating that 'House' is a specific instance of 'Building Type'.
- A **[n..m]** structure represents a [multiplicity](https://www.uml-diagrams.org/multiplicity.html). When it appears
- **at the TGT end of a relation**, it means that for every SRC element there must be at least *n* and at most *m* TGT elements in the relation. For example, the [0..n] multiplicity in the 'owns' relation in the figure means that for every 'Person' element, there must be at least 0 and at most *n* (i.e. any number) 'House' elements. Effectively, this says that every Person can own any number of Houses.
- **at the SRC end of a relatipon**, it means tha tfor every TGT element there must be at least *n* and at most *m* SRC elements in the relation. For example, the [0..1] multiplicity in the 'owns' relation in the figure means that for every 'House' element, there must be at least 0 and at most 1 'Person' elements. Effectively, this means that every House can be owned by at most 1 Person.
- is typically of any of the following forms (altough there may be others, e.g. [1..2]):
[0..1]: at most one;
[1..1]: precisely one;
[0..n]: any number - as this is not a constraint, this is the default multiplicity and may be omitted;
[1..n]: at least one.
Note that the term *multiplicity* is distinct from *cardinality*, the difference being that a cardinality states the *actual* number of SRC/TGT elements that a specific TGT/SRC element has in a relation, whereas a multiplicity states the *possible* number of such elements. In short, the multiplicity is the set of all possible cardinalities in a relation. We note this becaus it is common practice for people to use the term 'cardinality' where 'multiplicity' is intended.
### Notational Exceptions
The following notational conventions are not used by [UML](https://www.uml-diagrams.org/), but are specific to our use.
We use a **coloring convention** to distinguish between what is 'officially' part of the eSSIF-Lab models, and parts that are not.
- **blue** is used to color the lines and other symbols that are part of the 'official' models. Typically, they are explicitly defined or otherwise explained, e.g. in a %%mental model|pattern%%. Their definitions/meanings may differ from 'common knowledge'.
- **red** is used to color the lines and other symbols that are part of our 'common knowledge', and hence need not be explicitly defined. They appear to explain where eSSIF-Lab models link to these commonly known/used concepts. We think of them as necessary in order to bridge possible gaps between 'common understanding' and the eSSIF-Lab ways of thinking. Whenever a 'red concept' is nevertheless defined, this is for the purpose of conveying what we conceive the 'common knowledge' to be.
- Objects (lines, rectgangles, etc.) can be colored
- in **blue**, in which case they are properly defined (in a meaning that may deviate from what casual readers might expect).
- in **red**, in which case their meaning is expected to be part of 'common knowledge'. Their meaning may not be defined, yet if it is, the definition is an attempt to make this 'common knowledge' explicit. Red objects are used to bridge possible gaps between 'common understanding' and the eSSIF-Lab ways of thinking, that deviates in various respects.
- Lines can be drawn
- **solid**, in which case they are part of the %%model|pattern%% that is shown in a figure, or
- **dashed**, in which case they are (better) explained in other %%models|pattern%%.
- A **rectangle** represents a (named) %%concept|concept%%, examples of which include %%entity|entity%%, %%legal entity|legal-entity%% and %%party|party%%. %%Concepts|concept%% serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct, unless there is an 'ISA' relation between them (see below).
- A **line with a closed arrowhead** represents a (named) relation/association between the two %%concepts|concept%% it connects. We may refer to the concept at the arrowhead as the 'target %%concept|concept%%' (TGT) for that relation. Similarly, the %%concept|concept%% at the other end will be referred to as the 'source %%concept|concept%%' (SRC) for that relation. Names are chosen such that `<SRC> <relation name> <TGT>` is a phrase that suggests the intension(al definition) of that relation. For example, `operates` is a relation that has `Jurisdiction` as its `<SRC>`, and `Legal System` as its `<TGT>`. It may be read as `Jurisdiction operates Legal System`.
- A **line with an open arrowhead** represents an 'ISA' (pronounce as 'is a') relation, which can be read as `<SRC> is a <TGT>`. It means that SRC *is a* specialization of TGT (which in turn is a generalization of SRC). It means that SRC satisfies all constraints that TGT satisfies, and also that it has all attributes (properties, characgteristics) that TGT has. An example from the figure is: 'Jurisdiction is a Party'.
- A **line with a solid diamand** at one end is a composition; the element at the 'non-diamond-end' of the line is 'part of' the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' also cease to exist. In the figure, we see that %%knowledge|knowledge%% is 'part of' a %%party|party%% (the fact that it can also be part of a %%jurisdiction|jurisdiction%% follows from the fact that a %%jurisdiction|jurisdiction%% ISA %%party|party%%). Note that if the %%party|party%% ceases to exist, then so does the associated %%knowledge|knowledge%%. We say that %%party|party%% is 'the whole' in the relation, and %%knowledge|knowledge%% is a 'part' in the relation.
- A **line with a hollow diamand** at one end is an aggregation; the element at the 'non-diamond-end' of the line is 'part of' the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' do not necessarily cease to exist, but may 'live on'. In the figure, we see that 'legislation', 'enforcement' and 'juridicary' are all parts of a %%legal system|legal-system%%. If the %%legal system|legal-system%% ceases to exist, then it is possible that the 'legislation', 'enforcement' and 'juridicary' may continue their existence.
- A **green name** at either end of a relation/association is what UML calls 'role'; this name may be used to refer to (an instance of) the %%concept|concept%% at which the name is placed as it performs its/this role in this relation. In the figure, `governor` is the role that a %%party|party%% (or %%jurisdiction|jurisdiction%%) is said to be in as it governs its %%knowledge|knowledge%%.
- A **dashed line** with a pointed arrow (`>`) represents a dependency, where the SRC concept somehow depends on the TGT concept. The kind of dependency is specified by `<<text>>`, where `text` specifies the kind of dependency. Example: `<<instance>>` says that SRC is an instance (or: instantiates) TGT. This isn't shown in the figure.
- **Multiplicities** (or: **cardinalities**) use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended. A [multiplicity](https://www.uml-diagrams.org/multiplicity.html) specifies the minimum (*n*) and maximum (*m*) of possible instances of the concept where it is specified in a relation. Here are a few examples from the figure:
- the [1..1] multiplicity in the relation 'controls' must be read as "Every jurisdiction controls exactly one Scope of Control"
- the [1..n] multiplicity in the relation 'owns' reads: "Every party owns one or more (or: at least one) objectives".
- a multiplicity at the SRC of a relation can be read by first reversing the relation. For example, the [1..1] multiplicity at the SRC of relation 'owns' results in "Every objective *is owned by* precisely one party".
We use a **line typing convention** within a diagram, as follows:
- **solid lines** are used for lines and other symbols that are part of the %%model|pattern%% that is represented by the diagram;
- **dashed lines** are used for lines and other symbols that are (authoritatively) defined elsewehere.
For example, the concept %%party|party%% is authoritatively defined in the %%party, actor and action pattern|pattern-party-actor-action%%, so the diagram there shows a solid (blue) line fo rthat concept. It also appears in other diagrams, e.g. in the %%jurisdiction pattern|pattern-jurisdiction%%, where the concept is represented with a (blue) dashed line.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment