Merge branch 'terminology-rieks' into 'master'

Terminology update (Rieks)

See merge request !4

README.md

 # eSSIF-Lab Framework
 
-This repo contains the source documents of the [eSSIF-Lab framework](https://essif-lab.pages.grnet.gr/framework/), such as its vision, architecture and other relevant topics.
+This repo contains files that are used to generate the the [eSSIF-Lab framework](https://essif-lab.pages.grnet.gr/framework/) website, which includes the eSSIF-Lab vision, functional architecture, terminology and other relevant topics.
 
-## Writing docs
+This website is generated using [Docusaurus 2](https://v2.docusaurus.io/) (and a custom plugin developed by [GRNET](https://grnet.gr/en/) for handling terminology).
 
-This website is built using [Docusaurus 2](https://v2.docusaurus.io/).
+## Writing Docusaurus Documents
 
-Documentation content must appear in `.md` files inside the `docs` folder.
+Docusaurs requires documentation content to appear in `.md` files inside the `docs` folder.
 Each file defines the following attributes at its very beginning:
 
 - `id`, by which the file is referred to across the project
 - `title`, appearing at the top of the file's display
 - `sidebar_label`, the file's name appearing in the sidebar
 
-The `sidebars.js` file contains the basic mechanism for distributing content
-among sections and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/introduction)). Subsections within the `.md` file
-(that is, tagged with `##`) will appear at the right part of the page
-(see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)).
+Documentation on these and other header fields can be found [here](https://v2.docusaurus.io/docs/markdown-features#markdown-headers). 
 
-Images must be put inside the directory `static/images` and developers must refer to them using _relative_ urls.
+The Terminology Engine plugin of GRNET uses additional header fields. These are (or will be) defined [here](./docs/terminology-contributions).
+
+The `sidebars.js` file contains the basic mechanism for [distributing content among sections](https://v2.docusaurus.io/docs/docs-introduction#sidebar) and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/introduction)). Subsections within the `.md` file (that is, tagged with `##`) will appear at the right part of the page (see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)).
+
+## Inserting Images in docs
+<!-- **DEPRECATED** Images must be put inside the directory `static/images` and developers must refer to them using _relative_ urls.
 Example: ![eSSIF-Lab logo](../images/eSSIF-Lab%20logo.png)
 Docusaurus knows that the `../images` directory is inside the `static` directory, and thus process correctly.
 The deployment pipe will convert `../images/` in such links to their _*absolute*_ urls.
-Of course, if you want to link to images on the web, you can still use absolute urls.
+Of course, if you want to link to images on the web, you can still use absolute urls. -->
+
+If you want to add an image, say `example.png`, here is what you do:
+- first, add the image to the `/static/images` directory (or `/static/images/subdir-path/`)
+- then, in your document, add a line behind the docusaurus header that says: `import useBaseUrl from '@docusaurus/useBaseUrl';`
+- next, in your document, at the place where you want the image to be presented, insert the following snippet:
+```html
+<img
+  alt="text-that-shows-if-the-image-cannot-be-found"
+  src={useBaseUrl('images/example.png')}
+/>
+```
+(or `src={useBaseUrl('images/subdir-path/example.png')}` if you added the image file there).
 
 ### Installation
 

docs/essif-lab-functional-architecture.md

@@ -14,7 +14,11 @@ The purpose of the functional architecture and its views is to
 
 ## 1.  Basic Terminology
 
-In order to serve such purposes, we have found out that it is necessary that to make a strict and consequent distinction between people and Organizations that are capable of making decisions and bearing responsibility/accountability (we will use the term ‘%%Party|party%%’ for that) and people and ‘things’ that are capable of acting/doing things (we will use the term ‘%%Actor|actor%%’ for that). This means that an Organization is always a Party, whereas we consider a person to be a Party at one time and an Actor at another time, and computers/robots (and SSI components) are always an Actor.
+In order to serve such purposes, we have found out that it is necessary that to make a strict and consequent distinction between people and Organizations that are capable of making decisions and bearing responsibility/accountability (we will use the term ‘%%Party|party%%’ for that) and people and ‘things’ that are capable of acting/doing things (we will use the term ‘%%Actor|actor%%’ for that). All %%Organizations|organization%% are %%Parties|party%%, whereas we consider a person (human being) to be both a %%Party|party%% (in cases where reasoning, decision making and bearing responsibility are in order), and an %%actor|actor%% (in cases where the person is actually doing things). More details backgrounds are given in the %%mental model|mental-model%% '%%Parties, Actors and Actions|pattern-party-actor-action%%' and the documentation of the concepts used therin.
+
+:::note Editor's note
+TNO to edit remainder of this section (make it shorter), because users can click on the various terms if they want to know more. 
+:::
 
 This distinction is necessary because Actors do things that Parties are accountable for. In order to know which Party is accountable for what actions, we need the ability to link Parties and Actors. When an Actor acts and a (single) specific Party is accountable for that, we say that the Actor is an ‘%%Agent|agent%%’ for or of that Party (at that particular point in time). We say that this Actor acts ‘**on behalf of**’ that Party. Note that both humans and (running) applications may serve as Agents (human Agent or digital/electronic Agent respectively). A digital Agent that has one or more of the SSI functionalities we describe further down will be called an '%%SSI-Agent|ssi-agent%%', and we say that the Party on whose behalf it operates is the ‘%%Owner|owner%%’ of that Agent. Also, we use the term '**(digital/electronic or human) Colleague (of an Agent)**' to refer to any other (electronic or human) Agent that acts on behalf of the same Party as this Agent.
 
@@ -26,7 +30,7 @@ Also, to serve the aforementioned purposes, we cannot fix the architecture (and
 
 ## 2.  Functional Architecture Overview
 
-Figure 1 shows the initial *functional* eSSIF-Lab architecture, and its scope, context and *functional* components each of which is a (*functional*) Agent for the same Party (meaning that they are all part of the same Organization as defined above, and they are all (digital) ‘Colleagues’ of one another).
+Figure 1 shows the initial *functional* eSSIF-Lab architecture, and its scope, context and *functional* components each of which is a (*functional*) %%agent|agent%% for the same %%party|party%% (meaning that they are all part of the same %%organization|organization%% as defined above, and they are all %%(digital) ‘Colleagues’|digital-colleague%% of one another).
 
 Please be aware that *functional* capabilities, components, Agents, etc. do not necessarily coincide with *technical* capabilities, components, Agents, etc. The technical components can be deployed (downloaded, installed, run), whereas a functional component is a provider of a specified set of capabilities/functionalities an implementation of which can be made part of a technical component. So it is conceivable that a technical component contains an implementation of wallet, holder and verifier functional components as well as other functionalities that are not described here, e.g. related to UX, setting preferences, and more. In this functional architecture, the default type of components, Agents etc. are *functional*.
 

docs/essif-lab-vision-and-purpose.md

@@ -4,24 +4,23 @@ title: eSSIF-Lab Vision and Purpose
 sidebar_label: Vision and Purpose
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 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.
+The situation we would like to see is one in which we have SSI-enabled, interoperable, scalable and business/information agnostic technologies, that form an infrastructure that every application for every party can use to serve its own objectives. This infrastructure, that enables the electronic exchange of verified (personal and non-personal) data, must be so easy to access and use for such parties that they will no longer need to be concerned about actual (SSI) technologies that have empowered them to make this happen. Rather, they will only need to think about, and decide which kinds of information they want to obtain for conducting specific business transactions and which parties they trust for providing such information. Also, they will need to think about, and decide which kinds of information they themselves are willing to provide to others in this new SSI world.
 
 :::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>.
+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[^1].
 
-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.
+In the context of these rights and freedoms, we seek to support %%electronic business transactions|business-transaction%%, i.e. the electronic exchange of goods, services, funds, or data between parties, which we call ‘participants’ to the transaction[^2].
 
+An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic %%(digital) agent|digital-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.
 
 ## High-Level Example of a Business Transaction
 
@@ -33,18 +32,23 @@ Perhaps the most important contribution that the eSSIF-Lab project aims to make,
 
 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.*
+<img
+  alt="High-level visualization of the filling in and validation of a form."
+  src={useBaseUrl('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.
+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[^3]. *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.
+[^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).
+[^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. 
+[^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. 

docs/glossary.md

@@ -4,7 +4,7 @@ title: "eSSIF-Lab Glossary"
 sidebar_label: Glossary
 ---
 
-:::note Editor's note
+:::info Editor's note
 TNO to write the introduction paragraph
 Remainder of file to be generated (GRNET plugin/extension)
 :::

docs/pattern-list.md

@@ -4,7 +4,7 @@ title: "eSSIF-Lab List of Patterns"
 sidebar_label: Mental Models
 ---
 
-:::note Editor's note
+:::info Editor's note
 TNO to write the introduction paragraph
 Remainder of file to be generated (GRNET plugin/extension)
 :::

docs/terminology/README.md

-# README for terminology-related files.
-
-:::info
-under construction
-:::
-
-This document states the requirements for files in this directory, such that they can properly processed into useful and usable Docusaurus documentation.
-
-## Filenames
-
-All file MUST have the structure: `<scopeid>-<type>-<instanceid>.mdx`, where
-
-- `<scopeid>` is the (all lowercase) identifier of an existing scope, i.e. the file `<scopeid>-1-scope.mdx` must exist.
-- `<type>` MUST be any of the following:
-  - `scope`
-  - `pattern`
-  - `concept`
-  - `term`
-  - `glossary`
-- `<instanceid>` MUST be a lowercase identifier that only uses characters `a`-`z` and `-`.
-
-## Templates
-
-The `terminology/templates` directory contains templates for each of the types. A template file has comments that hold, amongst others, requirements for the contents of instances of that template.
-
-## Referring to terms in documentation files
-
-Any term can be referred to in any documentation file, using the syntax `%%<termref>%%`, where `<termref>` is either the `<conceptid>` of a concept
-
-- `<sometext>` is a text that will be displayed as if it were a term

docs/terminology/essifLab-concept-party.mdx

----
-id: essifLab-concept-party
-title: "Concept: Party (Scope: eSSIF-Lab)"
-scopeid: essifLab
-termid: party
-hoverText: "Entity that has knowledge about what exists, ways to reason with that knowledge, and ways for making decisions in a Self-Sovereign fashion."
----
-
-## Criterion:
-Entity that has knowledge about what exists, ways to reason[^1] with that knowledge, and ways for making decisions in a Self-Sovereign[^2] fashion.
-
-## Examples:
-People obviously qualify. Enterprises, governments, and other organizations also qualify as they can be seen as having their own knowledge (e.g. in their registrations, databases etc.), ways to reason with that knowledge (business rules, exercised by their employees or IT systems), and making decision.
-
-Stones, pictures, ideas, etc. do not qualify. Also, electronic components do not qualify[^3].
-
-### xxx:
-to be elaborated
-
----
-[^1]: Reasoning means: inferring conclusions from data, regardless of the kind of logic that is being used, or whether the reasoning is coherent, or consistent.
-
-[^2]: This means that the party can do this all by itself. For humans, the rights for this are laid down e.g. in the [ECHR](https://www.echr.coe.int "European Convention of Human Rights") ([ECHR articles 9-11](https://www.echr.coe.int/Documents/Convention_ENG.pdf))
-
-[^3]: While the case can be made that (some) electronic components can reason, they do not do so in a self-sovereign fashion as intended by this definition. We do not want to discuss AI-equipment here.

docs/terminology/essifLab-glossary.mdx

----
-id: glossary-essiflab
-title: Glossary eSSIF-Lab (Scope essiflab)
----
-<!--A glossary is a list of terms with (short) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s).-->
-
-## Purpose
-<!--State the purpose(s) that this glossary aims to fulfill, in such a way that readers can easily determine whether or not it is useful for them to use it.-->
-This glossary lists the basic concepts that are needed by the various stakeholders within the eSSIF-Lab project, ranging from governance, business, process, technology etc. The idea is that it defines at least the set of concepts that are often used in these varied domains, allowing a reader with a specific background to learn how the concept is used from other (valid) perspectives that may be alien to him/her.
-
-## Sources
-<!--Here, the sources should be identified from which the glossary entries (and their descriptions) are to be collected-->
-
-### Include
-<!--Specify the %%scope-files|scope-file%% that are to serve as a source for this glossary-->
-* eSSIF-Lab
-
-### Terms
-<!--Specify the %%term-files|term-file%% that are to serve as a source for this glossary. If a term is defined in a scope as well as in a %%term-file%%, the latter takes precedence.-->
-
-### Patterns
-<!--Specify the %%pattern-files|pattern-file%% that are to serve as a source for this glossary. If a term is defined in a scope or as a term as well as in a %%pattern-file%%, the latter takes precedence.-->
-
-### Concepts
-<!--Specify the %%concept-files|concept-file%% that are to serve as a source for this glossary. If a term is defined in a scope, or as a term, or in a pattern as well as in a %%concept-file%%, the latter takes precedence.-->
-
-<!--
----
-## Footnotes
-
-[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
-
-[^1]: the text for footnote [^1] goes here.
-
--->

docs/terminology/essifLabTerminology-concept-glossary.mdx

----
-id: glossary
-title: "Glossary (Concept)"
-scopeid: essifLabTerminology
-type: concept
-typeid: glossary
-hoverText: "an alphabetically sorted list of terms explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s)."
----
-
-## Short Description
-<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
-A glossary is an alphabetically sorted list of terms and explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s). However, a glossary may also be created for the purpose of being included in other glossaries (as a construction aid to such glossaries), or for still other purposes.
-
-## Purpose
-<!--Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this conceptevant within its scope of definition?-->
-A glossary may serve various purposes, the most important one of which would be to help people understand texts around a certain (set of) topic(s) in some context(s).
-
-## Criteria
-<!--REQUIRED--How is this concept different from related ideas? What are essential characteristics that must be true? This is where you specify the [intensional definition](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions) of the concept, i.e. the necessary and sufficient conditions for when the term should be used. This makes that the conceptomes crystal clear. In the case of nouns, this is equivalent to specifying the properties that an object needs to have in order to be counted as a referent of the term.-->
-an alphabetical list of words or phrases with (short) explanations, that exists for the purpose of helping people to get a first understanding of the meaning of each word in the scope/context for which the glossary is created.
-
-## Examples
-<!--This (optional) section contains examples, both of what satisfies the definition (and hence qualifies as an instance of Glossary), ans what does not. If you can think of examples for which the criterion may not (always) work, then describe them, too, and inform the reader why this hasn't affected the definition (yet) - e.g. because such cases are irrelevant to the scope within which the term is defined.-->
-Examples include the [eSSIF-Lab Glossary](essifLab-glossary), the [Sovrin Glossary](https://sovrin.org/library/glossary/), the [Glossary of Internet Terms](https://www.internetsociety.org/internet/glossary-internet-terms/), and glossaries for Legal Terms, e.g. of the [US](https://www.uscourts.gov/glossary), [Singapore](https://www.supremecourt.gov.sg/services/self-help-services/glossary-of-terms), the [UK](https://www.copfs.gov.uk/involved-in-a-case/glossary-of-legal-terms).
-
-## Related Concepts
-<!--This (optional) section lists words/phrases that are encountered in other contexts that have the same or a sufficiently similar meaning as Glossary. In this section you may point out the (subtle) differences between Glossary and this related terminology. This helps readers better/deeper understand Glossary, and how it may be used to relate to existing texts. Ideally, such references are accompanied with links to (preferredly authoritative) sources.-->
-- Dictionary - this is more extensive; it usually includes multiple meanings of words, and may include additional information e.g. on pronunciation, etymology, usage, example sentences,synonyms, etc. See [askdifference.com](https://www.askdifference.com/dictionary-vs-glossary/)
-- Vocabulary - this is a body of words used in a particular language or field of expertise. A Glossary can provide the meaning of each word for use within the scope(s) for which the Glossary is created.
-
-## Notes
-<!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
-The [eSSIF-Lab Glossary](essifLab-glossary) contains the words that are defined within the scope of the [eSSIF-Lab framework](introduction).
-
-<!--
----
-## Footnotes
-
-[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
-
-[^1]: the text for footnote [^1] goes here.
-
--->

docs/terminology/essifLabTerminology-concept-term.mdx

----
-id: term
-title: "Term (Scope: essifLabTerminology)"
-scopeid: essifLabTerminology
-type: concept
-typeid: term
-hoverText: "a word or phrase that is used in at least one scope/context to refer to a specific concept."
----
-
-## Short Description
-<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
-A Term is a word or phrase that is used in at least one context (and/or for specific purposes) to refer to a specific %%concept|concept%%. As a concequence:
-
-- the meaning of a Term may vary across contexts. For example, in the context of a buty-salon, the term 'nail' has a different meaning than in the context of constructing buildings.
-- different terms (in different contexts) may refer to the same concept ([synonymity](https://en.wikipedia.org/wiki/Synonym)).
-
-## Purpose
-<!--Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this conceptevant within its scope of definition?-->
-Understanding words or phrases uttered by others requires that we are able to 'translate' them terms into terms that we habitually use. While this is mostly an automatism, and it often is not necessary to be all that precise, this may be different when they relate to stuff we find important. The ability to refer to a specific concept with a specific text or phrase, where this 'linking' is limited to a specific (or several) context(s) helps us to better interpret the intentsion of what others convey in spoken or written language.
-
-## Criteria
-<!--How is this concept different from related ideas? What are essential characteristics that must be true? This is where you specify the [intensional definition](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions) of the concept, i.e. the necessary and sufficient conditions for when the term should be used. This makes that the conceptomes crystal clear. In the case of nouns, this is equivalent to specifying the properties that an object needs to have in order to be counted as a referent of the term.-->
-A Term MUST be a word or phrase that is linked to at least one %%context|scope%% and refers to precisely one %%concept|concept%%. 
-
-## Examples
-<!--Provide a few sentences in which you give examples that obviously qualify as instances of `Term`, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.-->
-
-## Related Concepts
-<!--Link to any %%concepts|concept%% that are similar but distinct, with a note about the relationship.-->
-
-
-## Domains
-<!--In which general knowledge ecosystems or mental model families does this concepty a role?-->
-* eSSIF-Lab
-* ToIP
-* Sovrin
-* DIF
-* NIST
-* ...
-
-## Tags
-<!--Add hash tags here that allow us to group concepts in useful ways.-->
-* Terminology
-
-## Use-cases
-<!--This (optional) section specifies an (optional) introductory paragraph, and a level-3 (i.e. `###`) subsection for every use case it describes. Every such use-case SHOULD
-- describe the situation/context of the use-case;
-- show how to apply ``Term`` to/in that situation;
-- shows the relevance of having ``Term`` for the use-case as opposed to not having it.-->
-
-## Notes
-<!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
-There is an important [distinction](https://simple.wikipedia.org/wiki/Concept) between concepts and the (multitude of) terms (names, labels) that we need to be able to talk and reason (argue) about them. Please consider that
-
-* different terms are used in different contexts for the same concept
-* in different contexts, a single term may refer to different concepts
-* to resolve terminological disputes, which usually are about the 'correct' meaning of a term, try to establish the criteria that the different participants use for the concept behind the term. That helps participants understand each others (different) positions, and provides a better basis for resolving the conflict.
-
----
-## Footnotes
-<!--This (optional) section contains any footnotes that may have been specified in the text above.-->
-
-[^1]: WikiPedia has a concise [explanation of concepts](https://en.wikipedia.org/wiki/Concept). We use the term 'concept' as a [mental representation](https://en.wikipedia.org/wiki/Mental_representation).
-
-[^2]: For the difference between 'Concept' and 'Term', see https://simple.wikipedia.org/wiki/Concept.

docs/terminology/essifLabTerminology-pattern-mental-model.mdx

----
-id: pattern-mental-model
-title: "Pattern: Mental Models (Scope: essifLabTerminology)"
-scopeid: essifLabTerminology
-type: pattern
-typeid: mental-model
-hoverText: "This pattern captures the foundational concepts and relations that we need for creating, maintaining and using  (decentralized) vocabularies (terminologies) that groups of people can use for the specific purposes they pursue."
----
-
-## Purpose
-<!--Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it.-->
-This pattern captures the foundational concepts and relations that we need for creating, maintaining and using  vocabularies (terminologies) that groups of people can use for the specific purposes they pursue. Alternatively, we need these concepts to allow people to use 'decentralized vocabularies' that %%parties|party%% may create, maintain and use in a self-sovereign fashion - which means that each of them decides for itself what terms to use in what meaning, yet be able to communicate with other such %%parties|party%% in such a way that a correct understanding of what the other means, can more or less be guaranteed.
-
-## Introduction
-<!--Gently introduce the pattern, by referring to real-world situations and using colloquial terms, so that when someone has read the text, (s)he knows what it is about, and is ready to delve into the specifics of the pattern-->
-TL;DR: .
-
-A concept is an idea that is applied to all objects in a group. It is the way people see and understand something. The name used to identify a concept (the concept's label) is a "term". For example, the word "Dog" is the term to identify the concept of what a dog is. Everything that a person knows about a dog is the concept of the term dog.
-
-Different terms can be used to identify the same concept. Car and Automobile are synonyms for the same concept. Different languages have different terms for the same concept. This is what makes translation possible. The terms may be different in each language, but the concept is the same. The concept of jumping is the same to a person from England and a person from Italy, but one person uses the term "Jump" to mean the concept and the other person uses "Salto".
-
-## Notations
-<!--This (optional) section specifies the notations that are used, or refers to such a specification.-->
-
-## <!-- any number of other sections, as is fit for describing the pattern -->
-<!--text as appropriate for such a section -->
-
-<!--
----
-## Footnotes
-
-[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
-
-[^1]: the text for footnote [^1] goes here.
-
--->

docs/terminology/essifLabTerminology-scope.mdx

----
-id: scope-essifLabTerminology
-title: Scope eSSIF-Lab Terminology
----
-
-## Governance
-<!--This section identifies the organizational body (Jurisdiction) that governs the scope. Optionally, a reference to the governance framework/procedures may be made.-->
-The [eSSIF-Lab project](https://essif-lab.eu/) governs the terminology within this scope, according to the procedures mentioned in the [eSSIF-Lab Framework](https://essif-lab.pages.grnet.gr/framework/docs/terminology/).
-
-## Objectives/Issues
-<!--State the purpose for having the scope in terms of objectives that are aimed for and/or issues that are to be addressed.-->
-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.
-
-The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community participants understand one another at whatever level of precision they need.
-
-## Scope URI
-<!--Optionally specify the URI by which this scope may be identified-->
-
-## Inclusions
-<!--This scope may include other scopes, which means that everything in that other scope is also considered part of this scope. In case of collisions, this scope MUST provide a means to resolve such conflicts without modifying anything in included scopes. For eSSIF-Lab, we include `essifLabTerminology`-->
-
-## Notes
-<!--Anything els that's worth mentioning.-->
-
-## Tags
-<!--Add hash tags here that allow us to group concepts in useful ways.-->
-
-<!--
----
-## Footnotes
-
-[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
-
-[^1]: the text for footnote [^1] goes here.
-
--->

docs/terminology/templates/template-concept-proposal.mdx

----
-id: ExistingScopeID-conceptproposal-NewTermID
-title: "Concept proposal for: <NewTermID> (Scope: <Existing Scope>)"
-scopeid: <ExistingScopeID>
-term: <NewTerm>
-hoverText: "<Text that pops up when the user hovers over a reference to this concept>"
----
-<!--A concept tries to capture the idea behind a classification of entities, allowing us to reason about everything in the class as if it were one thing. This file specifies the idea(s) that, within the scope of `<ExistingScopeID>` will be referred to using <New Term>.
-Please fill in the placeholders in this file as follows:
-- `<ExistingScopeID>`: identifier of the scope in which the term is defined;
-- `<Existing Scope>`: human readable text that identifies the scope in which this item is defined;
-- `<NewTerm>`: term that will identify the concept within <ExisingScopeID>;
-- `<ExistingTerm>`: term by which the concept is concept is known in that scope
--->
-
-## One-line Summary
-A single sentence that describe the concept to a layperson with reasonable accuracy. This line may be used to explain `Concept` in a glossary, or as a popover text when it is referred to in other documentation.
-
-For example: "A warm-blooded animal, often having fur or hair, that produces milk to feed its young."
-
-## Short Description
-in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.
-
-For example, the concept of a "mammal" in biology might be described as: "A warm-blooded animal, often having fur or hair, that produces milk to feed its young. Examples include rats, whales, and bats." A diagram could be included, if appropriate. The goal here is not perfect clarity; that's the focus of the 'Criteria' section.
-
-## Purpose
-Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this concept relevant within its scope of definition?
-
-## Criteria
-How is this concept different from related ideas? What are essential characteristics that must be true? This is where you specify the [intensional definition](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions) of the concept, i.e. the necessary and sufficient conditions for when the term should be used. This makes that the concept becomes crystal clear. In the case of nouns, this is equivalent to specifying the properties that an object needs to have in order to be counted as a referent of the term.
-
-a vertibrate that has mammary glands, a neocortex in the brain and 3 middle ear bones.
-
-## Examples
-Provide a few sentences in which you give examples that obviously qualify as instances of NewTerm, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.
-
-Primates (humans, monkeys), rodents (mice, rats), bats, and others qualify. Birds and reptiles do not (they lack mammary glands). [Platypus](https://en.wikipedia.org/wiki/Platypus)[^1] is also a mammal, even though it lays eggs.
-
-## Related Concepts
-Link to any concepts that are similar but distinct, with a note about the relationship. For example:
-
-* offspring (of a mammal) is the set of mammals that are born from that mammal.
-* mate (of a mammal) is any mammal of the same species with which the mammal has created ofspring.
-
-## Domains
-In which general knowledge ecosystems or mental model families does this concept play a role? For example:
-
-* Biology
-
-## Tags
-Add hash tags here that allow us to group concepts in useful ways.
-
-## Use-cases
-<!--This (optional) section specifies an (optional) introductory paragraph, and a level-3 (i.e. `###`) subsection for every use case it describes. Every such use-case SHOULD
-- describe the situation/context of the use-case;
-- show how to apply `NewTerm` to/in that situation;
-- shows the relevance of having `NewTerm` for the use-case as opposed to not having it. -->
-
-## Notes
-<!--This (optional) section is the place to put anything for which there is no other good place to put it. -->
-
-<!--
----
-## Footnotes
-
-[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
-
-[^1]: the text for footnote [^1] goes here.
-
--->

docs/terms/business-transaction.md

+---
+id: business-transaction
+title: "Business Transaction"
+scopeid: essifLab
+type: concept
+typeid: business-transaction
+stage: draft
+hoverText: "Business Transaction: the electronic exchange of goods, services, funds, or data between parties (called‘participants’ to the transaction)"
+---
+
+:::info Editor's note
+TNO to provide the content of this file.
+:::
+
+
+### Notes
+
+1. A good mental model for describing and designing business transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations).
\ No newline at end of file

docs/terms/colleague.md

+---
+id: colleague
+title: "Colleague"
+scopeid: essifLab
+type: concept
+typeid: colleague
+stage: draft
+hoverText: "Colleague (of an Agent): An actor that is an Agent for the same Principal."
+---
+
+:::info Editor's note
+TNO to provide the content of this file.
+:::
+

docs/terms/corpus.md

@@ -7,3 +7,7 @@ typeid: corpus
 stage: draft
 hoverText: "Corpus (of Terminology): the documentation that describes the knowledge around a set of terms and concepts."
 ---
+
+:::info Editor's note
+TNO to provide the content of this file.
+:::

docs/terms/credential.md

+---
+id: credential
+title: "Credential"
+scopeid: essifLab
+type: concept
+typeid: credential
+stage: draft
+hoverText: "Credential: data, representing a set of statements made by one party (the author of the credential)."
+---
+
+:::info Editor's note
+TNO to provide the content of this file.
+:::
+
+### Related Concepts
+- %%verifiable credential|verifiable-credential%%
+- %%verified data|verified-data%%
+- %%validated data|validated-data%%
+

docs/terms/digital-colleague.md

+---
+id: digital-colleague
+title: "Digital Colleague"
+scopeid: essifLab
+type: term
+typeid: digital-colleague
+conceptref: ":Colleague"
+stage: draft
+hoverText: "Digital Colleague (of an Agent): a digital actor that is an agent of the same principal."
+---
+
+### Purpose
+<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
+The ability to distinguish between (non)digital colleagues allows us to reason and communicate about the set of %%digital actors|digital-actor%% that are %%agents|agent%% for a single **principal|principal%%.
+
+See also: %%colleague|colleague%%.

docs/terms/digital-policy.md

@@ -2,27 +2,18 @@
 id: digital-policy
 title: "Digital Policy"
 scopeid: essifLab
-type: term
+type: concept
 typeid: digital-policy
 conceptref: ":Policy"
 stage: draft
-hoverText: "Digital Policy: a (set of) machine readable rules, working instructions or other guidance for the execution of one or more kinds of actions, that digital agents have access to and must use when executing such actions."
+hoverText: "Digital Policy: a machine-readable document that contains rules, working instructions or other guidance for digital agents so as to enable them to execute actions on behalf of the author of that policy."