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/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."
 ---
 
 ### Short Description
-A **digital policy** is a (set of) machine readable rules, working instructions or other guidance for the execution of one or more kinds of %%actions|action%%. A %%digital agent|digital-agent%% must have access to the digital policy that its %%principal|principal%% has established for the kind of action that the agent is executing on the principal's behalf. 
-
-It should be part of the principal's governance processes to establish, maintain and evaluate digital policies for every kind of action that its agents may execute.
-
-The principal must ensure that its %%digital actors|digital-actor%% can access the appropriate policies when needed.
+A **digital policy** is an artifact that is derived from, and represents, a %%policy|policy%% for the purpose of being useable in the digital realm.
 
 ### Purpose
-The purpose of **digital policies** is to enable %%parties|party%% to provide its %%digial agents|digital-agent%% with the rules and other guidance that they need to automaticallly execute %%actions|action%% that comply with such rules. 
-
-### Criterion
-A **digital policy** is 
-- a (set of) machine readable rules, working instructions or other guidance for the execution of one or more kinds of %%actions|action%%;
-- is authored by a single %%Party|party%% (the author or %%owner|owner%% of the digital policy);
-- is accessable to, and must be complied with by a %%digital agent|digital-agent%% of that policy's author when it executes an action of the kind to which the digital policy applies.
-
+<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
+The ability to distinguish between (non)digital policies allows us to exclusively talk about machine-readable policies, i.e. policies that are to be used by harsoftware/hardware %%actors|actor%%.
 
+See also: %%Policy|policy%%.
\ No newline at end of file

docs/terms/holder.md

@@ -9,13 +9,13 @@ hoverText: "Holder: a functional component that is capable of "
 ---
 
 ## Short Description
-A **Holder** is an (architectural) function that handles Presentation Requests that it receives from %%verifier|verifier%% components (both of its %%owner|owner%%, and of other %%parties|party%%). Typically, this means looking for the requested data in the Owner’s %%wallet|wallet%%, and using it to construct a Presentation (=response). However, if the Wallet doesn’t have it, the Holder may negotiate a transaction with a component of the designated %%issuer|issuer%% for the purpose of obtaining the needed credential, which - when obtained - it can subsequently store in the wallet and use in the Presentation.
+A **Holder** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that handles %%Presentation Requests|presentation-request%% that it receives from %%verifier|verifier%% components (of other %%parties|party%%, but also of its own %%owner|owner%%). Typically, this means looking for the requested data in the Owner’s %%wallet|wallet%%, and using it to construct a Presentation (=response). However, if the Wallet doesn’t have it, the Holder may negotiate a transaction with a component of the designated %%issuer|issuer%% for the purpose of obtaining the needed credential, which - when obtained - it can subsequently store in the wallet and use in the Presentation.
 
 ## Purpose
 The purpose of the Holder component is to handle Presentation Requests that it receives from %%verifier|verifier%% components (both of its own %%owner|owner%%, and of other %%parties|party%%), and responding to such requests.
 
 ## Criteria
-A **Holder** is a component in the [eSSIF-Lab functional architecture](..\functional-architecture\) whose function is to handle Presentation Requests that it receives from %%verifier|verifier%% components (both of its %%owner|owner%%, and of other %%Parties|party%%).
+A **Holder** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whose function is to handle Presentation Requests that it receives from %%verifier|verifier%% components (both of its %%owner|owner%%, and of other %%Parties|party%%).
 
 ## Functionality
 

docs/terms/issuer.md

@@ -9,14 +9,14 @@ hoverText: "Issuer: a functional component that is capable of "
 ---
 
 ## Short Description
-The **issuer** is an (architectural) function that structures sets of (related) statements/claims (e.g. as produced by the %%TRD|trd%%) in a packate, adds metadata which includes e.g. a timestamp at which this was done, ensures that it is digitally signed on behalf of its %%owner|owner%%,  signature by which third Parties can prove its provenance and integrity. Another function of the issuer is to handle revocation (and (un)suspension) of credentials that it has issued. For such tasks, it relies on functions that are made available by the SSI Protocols and Crypto Layer.
+An **issuer** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that structures sets of (related) statements/claims (e.g. as produced by the %%TRD|trd%%) in a packate, adds metadata which includes e.g. a timestamp at which this was done, ensures that it is digitally signed on behalf of its %%owner|owner%%,  signature by which third Parties can prove its provenance and integrity. Another function of the issuer is to handle revocation (and (un)suspension) of credentials that it has issued. For such tasks, it relies on functions that are made available by the SSI Protocols and Crypto Layer.
 
 
 ## Purpose
 The purpose of the Issuer function is.
 
 ## Criteria
-A **Issuer** is a component in the [eSSIF-Lab functional architecture](..\functional-architecture\) whose function is to ... (tbd).
+A **Issuer** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whose function is to ... (tbd).
 
 ## Functionality
 

docs/terms/mental-model.md

@@ -9,4 +9,8 @@ stage: draft
 hoverText: "Mental Model: a casual and formal description (pattern) of a set of concepts, relations between them, and constraints, that provide a specific 'viewpoint', or 'way of thinking' about a certain topic."
 ---
 
-see: %%pattern|pattern%%.
\ No newline at end of file
+:::info Editor's note
+TNO to provide the content of this file.
+:::
+
+See also: %%pattern|pattern%%.
\ No newline at end of file

docs/terms/pattern-mandates-delegation-hiring.md

@@ -10,6 +10,7 @@ hoverText: "The Mandates, Delegation and Hiring pattern (which remains to be doc
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-:::info Editors Note
-TNO is expected to produce the first draft of this document
+:::info Editor's note
+TNO to provide the content of this file.
 :::
+

docs/terms/pattern-terminology.md

@@ -10,24 +10,6 @@ hoverText: "The eSSIF-Lab Terminology Pattern describes the relations between te
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-### Purpose
-<!-- Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it. -->
-
-### Introduction