Commit d5ca92f5 authored by RieksJ's avatar RieksJ
Browse files

updates of notations/conventions

parent 642698de
Pipeline #48896 passed with stage
in 2 minutes and 46 seconds
...@@ -4,6 +4,8 @@ title: Notations and Conventions ...@@ -4,6 +4,8 @@ title: Notations and Conventions
date: 20210601 date: 20210601
--- ---
import useBaseUrl from '@docusaurus/useBaseUrl'
This document provides an overview of the notations and conventions being used within eSSIF-Lab. This document provides an overview of the notations and conventions being used within eSSIF-Lab.
### RFC 2119 ### RFC 2119
...@@ -18,15 +20,27 @@ We are working towards deprecating this convention, as we now have better ways o ...@@ -18,15 +20,27 @@ We are working towards deprecating this convention, as we now have better ways o
### Pattern diagram notations ### Pattern diagram notations
%%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation, as follows: %%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation. The following diagram shows the various notations we use:
- A **rectangle** represents a (named) concept that is explicitly defined. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct. <img
- A **rectangle that is coloured red(dish)** represents a (named) concept that is commonly used 'in the wild' (and hence needs not be defined here), relates to one or more concepts that are explicitly defined yet is not the same. We include such 'red concepts' to help readers identify and subsequently bridge gaps between commonly held thoughts and the (sometimes subtly) different meanings we need in our model. alt="Notations and conventions"
- A **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. We may refer to the concept at the arrowhead as the 'target concept' (TGT) for that relation. Similarly, the concept at the other end will be referred to as the 'source 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. src={useBaseUrl('images/essif-lab-notations-and-conventions.png')}
- A **solid line with an open arrowhead** represents an 'ISA' relation, which can be read as `<SRC> ISA <TGT>`. It means that SRC is a specialization of TGT (which in turn is a generalization of SRC). It means that SRC must satisfy all constraints that TGT must satisfy, and also that it has all attributes (including properties) that TGT has. />
- A **solid 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 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' also cease to exist.
- A **solid 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 'part') 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'. - Objects (lines, rectgangles, etc.) can be colored
- 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 at which the name is placed as it performs its/this role in this relation. - in **blue**, in which case they are properly defined (in a meaning that may deviate from what casual readers might expect).
- A **dashed line** with a closed arrow (solid triangle) signifies that while the relation is significant in combination with the model, its actual meaning relies on an assumption or is implied by some rule, or is specified in another pattern. The pattern text will state what this meaning is. - 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.
- 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. - Lines can be drawn
- **Multiplicities** (or: **cardinalities**) use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended. - **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".
---
id: tag
title: "Tag"
scopeid: essifLabTerminology
type: concept
typeid: term
stage: draft
hoverText: "Tag: an alphanumeric string that is used to identify Scopes and/or group Terms, and that satisfies the regex `#[a-z-0-9]+`."
glossaryText: "an alphanumeric string that is used to identify %%scopes^scope%% and/or group %%terms^term%%, and that satisfies the regex `#[a-z-0-9]+`."
date: 20210601
---
### Short Description
A Tag is an alphanumeric string that is used to identify %%scopes^scope%% and/or group %%terms|term%%, and that satisfies the regex `#[a-z-0-9]+`. As an %%identifier|identifier%% for a %%scope|scope%%, it can be used to disambiguate meanings. For example `#essif-lab:term` is an %%identifier|identifier%% for the %%concept|concept%% that within the %%scope|scope%% of eSSIF-Lab is referred to by the %%term|term%% 'Term'. In other situations, it may be used in combination with texts that document e.g. %%concepts|concept%%, so as to enable tools to group such texts.
### Criteria
is an alphanumeric string that is used to identify %%scopes^scope%% and/or group %%terms|term%%, and that satisfies the regex `#[a-z-0-9]+`.
### Examples
Examples of tags are:
- #essif-lab
- #toip
- #ctwg
Supports Markdown
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