Merge branch 'terminology' into 'master'

Terminology feature - plugin

See merge request !2

.dockerignore

+node_modules
+build

.gitlab-ci.yml

 image: node:13.7
 
+stages:
+  - build
+  - deploy
+
 before_script:
   - node -v
 
@@ -11,8 +15,18 @@ cache:
 before_script:
   - yarn
 
+build:
+  stage: build
+  script:
+    - yarn parse
+    - yarn glossary
+    - STAGING=true yarn build
+
 pages:
+  stage: deploy
   script:
+    - yarn parse
+    - yarn glossary
     - STAGING=true  yarn build
     - rm -rf public
     - mv build public

Dockerfile

+FROM node:lts
+
+RUN mkdir /srv/code
+
+COPY . /srv/code
+
+WORKDIR /srv/code
+
+RUN yarn global add serve
+
+RUN yarn install
+RUN yarn parse
+RUN yarn glossary
+RUN yarn build
+
+WORKDIR /srv/code/build
+
+CMD serve
+
+EXPOSE 5000

Dockerfile.dev

+FROM node:lts
+
+RUN mkdir /app
+WORKDIR /app
+RUN yarn global add serve
+COPY package.json yarn.lock ./
+RUN yarn --pure-lockfile
+
+COPY . ./
+
+EXPOSE 5000
+CMD yarn parse && yarn glossary && yarn build && cd build && serve

README.md

@@ -53,3 +53,140 @@ This command generates static content into the `build` directory and can be serv
 ### Deployment
 
 Just push your changes to the `master` branch and they will be automatically deployed at https://essif-lab.pages.grnet.gr/framework/
+
+## Terminology/Glossary plugin usage
+
+This project has a plugin integrated that can generate terms in a useful way so contributors can write a special syntax to reference terms and generate a glossary based on those terms.
+
+This plugin is designed to work in the pre-build stage. This means, it is strongly suggested that you do **not** run manually
+the script in your local computer (or at least do not commit changes). In order to view the final result, you can instead use
+Docker and/or Docker Compose, as follows.
+
+#### Docker
+
+You can run the following commands to see the output of the website, just as it will look like when deployed to a production environment:
+
+```
+docker build -t essif-lab-terminology:latest .
+docker run -ti -p 5000:5000 essif-lab-terminology:latest
+```
+
+You can then visit http://localhost:5000 to view the website
+
+To stop docker from running, you can just hit `ctrl+c` in the terminal window.
+
+#### Docker Compose
+
+Docker Compose is a wrapper of docker, so you can run less commands to do the same job as you would do with docker commands. You only need to run:
+
+```
+docker-compose up --force-recreate --build
+```
+
+and then visit http://localhost:5000 to view the website.
+
+To stop docker-compose, just like docker, hit `ctrl+c` in the terminal window.
+
+## Terminology/Glossary plugin explanation
+
+### How it works
+
+This plugin parses docs in two ways:
+
+  1. Parses all `*.mdx` files under `docs/` and replaces each pattern with an
+  appropriate React component supporting a tooltip functionality (see below)
+  2. Generates a glossary with all terms corresponding to the `*.md` files under `docs/terms/`.
+
+Parses all markdown files and generates a glossary page with all the pattern terms found in the .md files
+
+### Replace patterns with dynamical elements
+
+When writing docs, in order to refer to a term, you may use the following syntax:
+
+```
+%%term_text|term_name%%
+```
+
+where:
+- `term_text`: The terminology text you want it to be visible in the documentation
+page
+- `term_name`: The filename of the term file, which resides under `./docs/terms` directory.
+
+inside `docs/*.mdx` files. After successfully running the script, the above occurrence
+will be replaced by a React component, which will render `term_text` as a link to the
+corresponding term page, which is in turn generated from the `term_name` attribute;
+furthermore, *hovering* over `term_text` displays a term summary, as extracted from the
+corresponding term page.
+
+### Example usage
+
+Say you want to reference a term that exists under the `./docs/terms/` directory,
+e.g. `./docs/terms/party.md`. You can use the following syntax to reference
+this term in your documentation page:
+
+```
+Some content that wants to reference the %%Party|party%% term
+```
+
+When the script runs, this will be replaced as follows:
+
+```
+Some content that wants to reference the <Term reference="party" popup="Popup text">Party</Term> term
+```
+
+which supports the functionality explained above.
+
+### How to correctly write a term
+
+This plugin assumes that you follow the structure, as explained below:
+
+Each term should have its own `.md` file, inside the `./docs/terms` directory,
+and it needs to consist of the following structure:
+
+```title="./docs/terms/term.md"
+---
+id: term
+title: Term page
+hoverText: This hover text will appear in the documentation page that you reference this term
+---
+
+### Term explanation
+
+content here
+```
+
+> Pay attention to the `hoverText` attribute, as it's important to provide this
+>attribute (along with the default docusaurus attributes), so the plugin can
+>fetch the correct popup text to show when referencing a term.
+
+### Running the script
+
+When you are finished referencing terms and have written corresponding term pages,
+you can test this locally by running the following command:
+
+```.shell script
+$ yarn parse
+yarn run v1.22.5
+ docusaurus parse
+Replacing patterns with <Term />
+Done in 1.41s.
+```
+
+This will replace all `%%term_text|term_name%%` occurrences with the React component
+supporting the required functionality.
+
+### Generate the glossary page
+
+If everything works well with the above procedure, you can then generate a
+glossary page, by running the following command:
+
+```.shell script
+$ yarn glossary
+yarn run v1.22.5
+ docusaurus glossary
+Alphabetical list of terms
+Done in 1.53s.
+```
+
+This will generate a file in `./docs/glossary.md` where every term that has been
+mentioned above, will be populated in the `glossary.md` page.

doc-sources/ampersand/terminology.adl

+CONTEXT Terminology
+
+--[Scopes]
+
+scopeID   :: Scope * ScopeID [UNI,TOT] -- simple text, satisfying regex `[\w-]+`, that machines may use to refer to the scope (by machines).
+scopeName :: Scope * ScopeName [UNI,TOT] -- alphanumeric text that humans may use to refer to the scope.
+scopeURI  :: Scope * URI [UNI] -- Place where all the content of the scope can be found.
+
+REPRESENT ScopeIdfr, ScopeID, ScopeName TYPE ALPHANUMERIC
+REPRESENT URI TYPE BIGALPHANUMERIC
+
+isSubscopeOf :: Scope * Scope [IRF,ASY] -- SRC scope is a subscope of TGT scope; TGT Scope contains (everything contained in) SRS Scope.
+
+--[Terms and Term References]
+IDENT MachineTerms: Term(termScope,termID)
+IDENT HumanTerms: Term(termScope,termName)
+termScope :: Term * Scope [UNI,TOT] -- Scope within which the Term is defined
+termID    :: Term * TermID [UNI,TOT] -- text, satisfying regex `[\w-]+`, that machines may use to refer to the Term
+termName  :: Term * TermName [UNI,TOT] -- alphanumeric text that humans may use to refer to the Term
+termHover :: Term * HoverText [UNI] -- a text that may be used as a short explanation of the term
+termSpec  :: Term * TermSpec [UNI] -- (the file that contains) the specification of the meaning of the Term
+termRef   :: Term * TermRef [UNI] -- the meaning of the term is given by the meaning of Term to which TermRef refers
+
+REPRESENT TermID, TermName, HoverText TYPE ALPHANUMERIC
+
+IDENT TermRefs: TermRef(trefOrigTerm, trefRefScope, trefRefTerm)
+trefOrigTerm :: TermRef * Term  [UNI,TOT] -- the Term that uses this TermRef to define its meaning
+trefRefScope :: TermRef * Scope [UNI,TOT] -- the Scope in which the referred-to Term is defined
+trefRefTerm  :: TermRef * Term  [UNI,TOT] -- the Term (from that scope) to which is being referred
+
+--[Glossaries and Dictionaries]
+
+glosID      :: Glossary * GlossaryID [UNI,TOT] -- text, satisfying regex `[\w-]+`, that machines may use to refer to the Term
+glosName    :: Glossary * GlossaryName [UNI,TOT] -- alphanumeric text that humans may use to refer to the Term
+glosPurpose :: Glossary * PurposeText [UNI] -- text, describing the purpose for having the Glossary
+glosTerms   :: Glossary * Term -- Terms that are included in the Glossary
+glosEntries :: Glossary * GlossaryEntry -- Entries that constitute the body of the Glossary.
+
+REPRESENT GlossaryID, GlossaryName TYPE ALPHANUMERIC
+REPRESENT PurposeText TYPE BIGALPHANUMERIC
+
+glentTermName :: GlossaryEntry * TermName [UNI,TOT] -- the name of the entry as it appears in the glossary
+glentTerm :: GlossaryEntry * TermName [UNI,TOT] -- the name of the entry as it appears in the glossary
+
+
+
+
+
+
+ENDCONTEXT
\ No newline at end of file

doc-sources/essif-lab-vision-and-purpose.md

+---
+id: vision-and-purpose
+title: eSSIF-Lab Vision and Purpose
+---
+
+The eSSIF-Lab vision is that Self-sovereign Identity (SSI) will *empower European and other citizens* by providing new means to manage privacy by eliminating logins and making electronic transactions fast and safe both in the Internet and in physical life. SSI will *empower European organisations and governments* by providing new means to speed up, secure and automate transactions with citizens, customers, suppliers and partners, resulting in tens of billions of euros savings annually on administrative costs in Europe. SSI will be *a new business ecosystem paradigm* with thousands of new jobs, many new job categories and new business opportunities for existing and new European companies. And last, but certainly not least, SSI fosters *inclusiveness* and supports organizations and citizens to exercise their rights and fulfil their duties under the GDPR.
+
+The current situation is that SSI solutions that are being created and brought to the market either target specific applications for which they provide a vertical solution (‘stovepipes’), many need some kind of centralized governance/control, others have privacy issues, and none that we know of are interoperable with other such solutions.
+
+The situation we would like to see is one in which we have SSI-enabled, interoperable and scalable technologies, that form an infrastructure that every application in any vertical can use in a very easy manner, for the exchange of verified (personal and non-personal) data. In that situation people, businesses and governments think more about the information they need and/or provide as they conduct business transactions. They no longer need to be concerned about the SSI technologies that have empowered them to make this happen.
+
+:::tip **The purpose of the eSSIF-Lab...**
+... is to specify, develop and validate technological and non-technological means that support people, businesses and governments to think about, design and operate their (information) processes and (electronically) conduct business transactions with one another.
+:::
+
+The context of the eSSIF-Lab vision can be found in articles 8-10 of the [*European Convention on Human Rights (ECHR)*](https://www.echr.coe.int/Pages/home.aspx?p=basictexts/convention), that state the rights of individuals regarding their privacy, and their freedoms to collect, process, store, and express information in a self-sovereign fashion, i.e. in a way that they can decide for themselves. This is without prejudice to Member States’ laws that exist to protect their national security, public safety, the economic well-being of the country, health or morals or the rights and freedoms of others, or to prevent disorder or crime. The eSSIF-Lab vision extends these rights and freedoms - within the limits of the law - to public and private organizations. Thus, we say that individuals as well as public and private organizations (that we collectively refer to as ‘parties’) are self-sovereign<sup>[1]</sup>.
+
+In the context of these rights and freedoms, we seek to support electronic business transactions, i.e. the electronic exchange of goods, services, funds, or data between parties, which we call ‘participants’ to the transaction<sup>[2]</sup>.
+
+An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic agent, i.e. equipment (e.g. an app on a mobile phone, a webserver, a browser, …) that acts on behalf of its owner in the transaction.
+
+An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic agent, i.e. equipment (e.g. an app on a mobile phone, a web server, a browser, …) that acts on behalf of its owner in the transaction.
+
+
+## High-Level Example of a Business Transaction
+
+In its simplest form, this may be envisaged as one party (requestor) that requests another party (provider) to provide some product, e.g. a parking permit, by using his web-browser to navigate to the web-server of the provider (e.g. his municipality) where he is prompted to fill in a form to provide the details of his request (such as name, address, plate number, etc.). When the form is submitted, the provider decides whether or not to service the request (provide the parking permit) based on the data in the form, and take actions accordingly.
+
+In order for this to work, the provider must design the form such that when a requestor submits a completed form, it can actually decide whether or not to service the request. This has two parts: first, the provider must specify the argument (i.e. the way of reasoning) that it uses to reach this decision - i.e. provide the parking permit. Doing so implicitly specifies the kinds of data that the form will ask for. Secondly, the provider must decide for each of the data it receives, whether or not it is valid to be used in that argument - the process of deciding this is called ‘validation’. Common criteria that help to make this distinction include whether or not the data is presented in the expected format, whether or not it is true (not so easy), whether it is not outdated, or whether or not it satisfies validation rules (in the example, the municipality may require that the specified license plate belongs to a car owned by the person that requests the permit). Validation is important, because reasoning with invalid data may result in wrong conclusions and cause damage.
+
+Perhaps the most important contribution that the eSSIF-Lab project aims to make, is to create a ubiquitously used infrastructure for designing, filling in, and validating forms (not just web-forms, but also for ‘forms’ - e.g. JSON objects - in API requests). The benefits this will bring are enormous, but outside the scope of this document to list.
+
+The figure below is a high-level visualization of the filling in and validation parts:
+
+![eSSIF-Lab - vision context](https://essif-lab.pages.grnet.gr/framework//images/vision-context.png) *Figure 1. High-level visualization of the filling in and validation of a form.*
+ 
+The transaction that is envisaged here is the issuing of a parking permit. Participants are a person (requestor) that requests such a permit, and an organization (provider) that can issue such a permit. The requestor has one electronic agent, *the Requestor Agent (RA)*, i.e. an SSI-aware app on their mobile phone that can access a secure storage that contains ‘credentials’, i.e. data that is digitally signed by some third party, thus attesting to the truth of that data. The provider has two agents: one is an SSI-aware component *Provider Agent (PA_* that works with the web-server that presents the form, and the other is a person *P* whose task is to validate any data (on behalf of the provider) that is not validated electronically. The form itself contains a means, e.g. a QR-code or a deep-link, that allows *RA* and *PA* to set up a secure communications channel (e.g. SSL, [DIDComm](https://openssi.github.io/peer-did-method-spec/)) and agree on the specific form that needs to be filled in.
+
+After the *RA* and *PA* have established a communications channel and agree on the form to be filled in, *PA* informs *RA* about the information it needs to fill in the form, and the requirements that this information should satisfy<sup>[3]</sup>. *RA* then checks its data store to see whether or not such data is available, sends such data to *PA*, which subsequently validates it and uses it to fill in (appropriate parts of) the form. Finally, *P* validates the remaining data, which either results in a ‘clean’ form, i.e. a form that contains valid data that can subsequently be used to decide whether or not to provide the parking permit, or a message to the requester informing him about missing and/or invalid data.
+
+When the transaction has been completed, both participants can issue a credential that attests to the results of the transaction. For example, the provider could issue a credential stating that the requestor has obtained a parking permit for a car with a specific plate number (and other attributes). The requestor can store this credential and from that moment on use it in new electronic transactions.
+
+--------
+
+[1] We realize that by doing this we have a different definition of what self-sovereignty entails than many others. We are open to suggestions for a better phrase.
+
+[2] A good mental model for describing and designing transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations).
+
+[3] Since transactions are symmetric, the requestor could also have a form that the provider needs to fill in so as to provide the requestor with the data it needs to commit to that transaction. We have left that out of this description for the sake of simplicity. 

doc-sources/glossary.md

+---
+id: essifLab-glossary
+title: "eSSIF-Lab Glossary"
+---
+
+:::note Editor's note
+TNO to write the introduction paragraph
+:::

doc-sources/introduction.md

+---
+id: introduction
+title: Introduction
+---
+
+The European Self-Sovereign Identity Lab ([eSSIF-Lab](https://essif-lab.eu/)) views itself as an ecosystem of parties 
+that work together to make existing (and new) Self-Sovereign Identity (SSI) technology into 
+a scalable and interoperable infrastructure that businesses can use very easily
+for conducting (business) transactions with other businesses and individuals alike.
+Typically, the libraries, code or components for the infrastructure should be open source.
+
+In order to support the use of such an infrastructure by businesses and individuals,
+eSSIF-Lab parties also create applications and other tooling to support such actual use
+on top of the interoperable infrastructure, which may or may not be open source,
+and are expected to be used as/in products of organizations that want to make this their business.
+
+At the start, eSSIF-Lab is one of the European [NGI projects](https://www.ngi.eu/ngi-projects/)
+and helps (EU) parties that want to contribute by publishing [open calls](https://essif-lab.eu/?page_id=134) 
+to which such parties can submit work proposals that eSSIF-Lab will then consider for funding.
+
+## eSSIF-Lab Framework Repository
+
+This repo contains the documents that describe the vision, architecture and other
+topics that are relevant to the eSSIF-Lab Framework. Currently, it contains:
+
+- [Vision and purpose](vision-and-purpose)
+- [Functional architecture](functional-architecture)
+- [SSI standards](ssi-standards)
+
+## Acknowledgement
+
+This site is part of the eSSIF-Lab project that has received funding from the [European Union’s Horizon 2020 Research and Innovation Programme] under grant agreement Nº 871932.
\ No newline at end of file

doc-sources/notations-and-conventions.md

+---
+id: notations-and-conventions
+title: Notations and Conventions Used in this Documentation
+---
+
+Here, we provide an overview of the notations and conventions being used within eSSIF-Lab.
+
+
+## RFC 2119
+We shall use keywords such as “shall”, “should”, “may” etc. as defined by [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+## Capitalization of words in mid-sentence
+Also, we capitalize words in mid-sentence whenever it is used in the meaning as provided by a corresponding Definition. This allows us to also use the more colloquial meanings of words (by not capitalizing them). We appreciate any feedback regarding our (im)proper use of this kind of capitalization of words.
+
+We are working towards deprecating this convention, as we now have better ways to refer to %%definitions|definition%%.
+
+## Pattern diagram notations
+
+%%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation, as follows:
+
+- a **rectangle** represents a (named) concept. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct. 
+- a **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. The concept at the arrowhead is called the ‘target concept’ (TGT) for that relation. The concept at the other end is called 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.
+- a **dashed line** signifies that its intension is created by combination the intensions of other relations (it is a ‘shorthand’ for a path of other relations).
+- an **open-ended arrow** is an ‘ISA’ relation, which can be read as `<SRC> ISA <TGT>`. It means that SRC is a specialization of TGT (which is a generalization of SRC). Thus, SRC must satisfy all constraints that TGT must satisfy, and has all attributes (including properties) that TGT has.
+- **Multiplicities** use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended.
+- A **concept that is coloured red(dish)** represents a notion that is commonly used ‘in the wild’ (and hence needs not be defined here), relates to one or more concepts we need for the pattern, 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.
\ No newline at end of file

doc-sources/pattern-list.md

+---
+id: essifLab-pattern-list
+title: "eSSIF-Lab List of Patterns"
+---
+
+:::note Editor's note
+TNO to write the introduction paragraph
+:::

doc-sources/terminology-plugin-instructions.md

+---
+id: terminology-plugin-instructions
+title: Terminology & Glossary plugin docs
+---
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+
+### How it works
+
+This plugin parses docs in two ways:
+
+  1. Parses all `*.mdx` files under `docs/` and replaces each pattern with an
+  appropriate React component supporting a tooltip functionality (see below)
+  2. Generates a glossary with all terms corresponding to the `*.md` files under `docs/terms/`.
+
+Parses all markdown files and generates a glossary page with all the pattern terms found in the .md files
+
+## Replace patterns with dynamical elements
+
+When writing docs, in order to refer to a term, you may use the following syntax:
+
+```
+%%term_text|term_name%%
+```
+
+where:
+- `term_text`: The terminology text you want it to be visible in the documentation
+page
+- `term_name`: The filename of the term file, which resides under `./docs/terms` directory.
+
+inside `docs/*.mdx` files. After successfully running the script, the above occurrence
+will be replaced by a React component, which will render `term_text` as a link to the
+corresponding term page, which is in turn generated from the `term_name` attribute;
+furthermore, *hovering* over `term_text` displays a term summary, as extracted from the
+corresponding term page.
+
+### Example usage
+
+Say you want to reference a term that exists under the `./docs/terms/` directory,
+e.g. `./docs/terms/party.md`. You can use the following syntax to reference
+this term in your documentation page:
+
+```
+Some content that wants to reference the %%Party|party%% term
+```
+
+When the script runs, this will be replaced as follows:
+
+```
+Some content that wants to reference the <Term reference="party" popup="Popup text">Party</Term> term
+```
+
+which supports the functionality explained above.
+
+### How to correctly write a term
+
+This plugin assumes that you follow the structure, as explained below:
+
+Each term should have its own `.md` file, inside the `./docs/terms` directory,
+and it needs to consist of the following structure:
+
+```title="./docs/terms/term.md"
+---
+id: term
+title: Term page
+stage: draft
+hoverText: This hover text will appear in the documentation page that you reference this term
+---
+
+### Term explanation
+
+content here
+```
+
+> Pay attention to the `hoverText` attribute, as it's important to provide this
+>attribute (along with the default docusaurus attributes), so the plugin can
+>fetch the correct popup text to show when referencing a term.
+
+### Running the script
+
+When you are finished referencing terms and have written corresponding term pages,
+you can test this locally by running the following command:
+
+```.shell script
+$ yarn parse
+yarn run v1.22.5
+ docusaurus parse
+Replacing patterns with <Term />
+Done in 1.41s.
+```
+
+This will replace all `%%term_text|term_name%%` occurrences with the React component
+supporting the required functionality.
+
+Here's an example where the terms have been replaced. When the project is up
+and running, you can visit the test example on the `/docs/replacement-test` page:
+
+<img alt="replacement-test" src={useBaseUrl('images/replacement-test.png')}/>
+
+
+## Generate the glossary page
+
+If everything works well with the above procedure, you can then generate a
+glossary page, by running the following command:
+
+```.shell script
+$ yarn glossary
+yarn run v1.22.5
+ docusaurus glossary
+Alphabetical list of terms
+Done in 1.53s.
+```
+
+This will generate a file in `./docs/glossary.md` where every term that has been
+mentioned above, will be populated in the `glossary.md` page.
+
+When the project is up and running, you can visit the glossary on the `/docs/essifLab-glossary` page:
+
+ <img alt="glossary-page" src={useBaseUrl('images/glossary-page.png')}/>

doc-sources/terminology.md

+---
+id: terminology
+title: "eSSIF-Lab: Concepts and Terminology"
+scopeid: essifLab
+---
+
+:::info **UNDER CONSTRUCTION**
+*This (initial version of the) terminology chapter is currently under construction. If you feel like making a contribution, please contact [the editor](mailto:rieks.joosten@tno.nl)*
+:::
+
+The purpose of the eSSIF-Lab Terminology is to provide mental models that all of its stakeholders interpret in sufficiently the same way, so as to be able to talk, think and discuss about what it is we try to achieve and ways to achieve this.
+
+## Introduction
+
+Contributors to and users of eSSIF-Lab come from various backgrounds. Their culture may not be Western. English may not be their native tongue. They may be experts in non-technological topics. Working with one another presumes a setting where participants have some level of shared understanding. Often, sharing one's understanding at a superficial level suffices. Other situations require that underlying concepts are shared in a more in-depth fashion. It's like cars: people buying, selling, or driving cars do not need in-depth shared knowledge about cars, whereas (maintenance or construction) engineers or liability lawyers need to share a deeper knowledge of how cars do (or do not) work.
+
+We expect to see situations of "language confusion", i.e. in which people use words or phrases, the intension (not: intention) of which differs from the interpretation of some listeners/readers. Sometimes a casual glance at a dictionary or glossary is the solution. In other cases, deeper understanding matters, e.g. in when drafting specifications or contracts. Then [we need more than a set of definitions](https://www.sfu.ca/~swartz/definitions.htm). 
+
+The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community participants understand one another at whatever level of precision they need.
+
+## Glossaries
+
+The traditional tool for fostering common understanding is using glossaries, i.e. alphabetical lists of words relating to a specific subject, text, or dialect, with explanations; a brief dictionary ([OED](https://www.lexico.com/definition/glossary)). Examples include the [Sovrin Glossary](https://sovrin.org/library/glossary/) and the [NIST Glossary](https://csrc.nist.gov/glossary). Other initiatives attempt to provide more background, e.g. the [terminology for talking about privacy by data minimization](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) by Pfitzmann and Hansen (2010), or the [EBSI Terminology (login required)](https://ec.europa.eu/cefdigital/wiki/display/EBP/EBSI+Terminology).
+
+The eSSIF-Lab project will also develop a [Glossary](/docs/essifLab-glossary).
+
+However, since the use of such glossaries is limited to short explanations, we will also provide (a) mental model(s) that provide a more in-depth explanation of the concepts that underly the words listed in the [eSSIF-Lab Glossary](/docs/essifLab-glossary). 
+
+## Mental Models
+
+We have the following mental (conceptual) models:
+
+
+
+
+A Mental Model, or Conceptual Model, is a set of of concepts (i.e. entity classes), relations between such concepts (i.e. sets of pairs of members of classes that a relation connects), and rules/constraints expressed in terms of these relations and concepts.
+
+The first purpose of a Mental Model is to help us think and reason about a certain topic or issue.
+One signal that indicates the need of such a model is when we’re running circles in our thoughts, and we have this feeling of not understanding, of the topic being (too) complex. Often, we are thinking in terms of concepts that are not fit for the objectives we pursue.
+
+So a mental model requires careful construction, that allows the choices for its elements to be validated against many use-cases. Such validation instills trust that our model elements (concepts, relations, rules) are well-chosen. It also provides us with the experience (usually after some time) that it has made our thinking easier, and we are better equipped to resolve issues.
+
+The careful construction is comparable to a quest: it takes time, multiple versions, and careful reflection. And it needs continuous validation of its parts, by throwing use-cases at it and verifying that the model can describe such cases, and do some reasoning with them.
+
+This careful construction must ensure that the mental model gets different properties. For starters, the model must be able to reason in (all) static situations, where things do not change, and the so-called ‘invariant’ rules/constraints must  hold. Also, the model must be able to cope with time-dependencies and changes, for which other kinds of rules apply.
+
+In the end, the mental model needs to be expressed in several, different ways, depending on whom we want to convey the ideas behind it to. Business people generally need simple models that allow them to (roughly) grasp its gist. Software architects need models with precise definitions that allow them to use its elements in (formal) reasonings. Software engineers (programmers) need all the details that allow them to create applications and databases that work according to the model’s intent. So the level of detail that an expression of the model provides, makes it useful or useless to different audiences.
+
+## Terminology and Definitions
+
+We attempt to create definitions that are both acceptable for business people yet are precise enough to serve as a basis for formal reasoning. We do this by using [intensional definitions](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions), i.e. by defining criteria that specify the  necessary and sufficient conditions for when a term should be used. We have tried to craft these definitions such that
+
+- readers are likely to make the same judgements when using them, and
+- these distinctions are relevant for our purposes. That’s the important stuff.
+
+The actual texts we choose as the name for a concept is of secondary importance; if in a particular context other names are more suitable, you can rename them there without loss of meaning or consistency.
+
+Together with these criteria, we provide a limited set of examples to help the reader to visualize the defined concepts, and to point out possibly unexpected consequences of the criteria. Also, we may motivate the need for having a concept by showing its relevance for the model.
+
+Here are some examples:
+
+:::note 
+**The following definitions will be moved to a separate eSSIF-Lab Terminology section**
+:::
+
+### Definition
+**Entity that comprises at a minimum**: