Commit 248e9941 authored by Rieks Joosten's avatar Rieks Joosten Committed by fmerg
Browse files

attempt to make the first part of architecture use 'terms-v1'

parent 15dc2485
......@@ -4,20 +4,21 @@ title: eSSIF-Lab Functional Architecture
scopeid: essifLab
---
import { Term } from '..\src\components'
The purpose of the functional architecture and its views 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;
- help **inventory and subsequently address any (other) concerns and issues** of every one of its stakeholders;
- help **achieve interoperability** both at the technical and at the business levels.
## 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 ‘<Term popup="Entity that has knowledge about what exists, ways to reason with that knowledge, and ways for making decisions in a Self-Sovereign fashion." reference="party">_Party_</Term>’ for that) and people and ‘things’ that are capable of acting/doing things (we will use the term ‘<Term popup="Entity that can act (do things), e.g. people, machines, but not organizations." reference="actor">_Actor_</Term>’ 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.
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.
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 ‘<Term popup="Agent (of a Party): Actor that is currently working on behalf of a Party." reference="agent">_Agent_</Term>’ 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 \`<Term popup="Agent that provides SSI services." reference="ssi-agent">_SSI-Agent_</Term>\`, and we say that the Party on whose behalf it operates is the ‘<Term popup="a Party that has the legal or rightful title to control something." reference="owner">_Owner_</Term>’ 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.
Given these definitions, it is obvious that Parties are not necessarily capable of acting. However, we also would like to be able to generically use phrases such as ‘Party X does Y’. To this end we introduce the term \`%%_Organization_|organization%%\` as the collection of one specific Party and its Agents. When we say ‘Party X does Y’, this should be understood as that there is an Agent that does Y, where that Agent belongs to the same Organization as the specified Party.
Given these definitions, it is obvious that Parties are not necessarily capable of acting. However, we also would like to be able to generically use phrases such as ‘Party X does Y’. To this end we introduce the term \`<Term popup="popuptext for Organization tbd" reference="organization">_Organization_</Term>\` as the collection of one specific Party and its Agents. When we say ‘Party X does Y’, this should be understood as that there is an Agent that does Y, where that Agent belongs to the same Organization as the specified Party.
We caution that the notions of being an ‘Agent’, ‘Owner’, ‘Colleague’, and being part of an ‘Organization’ are dynamic; they may frequently change over time and are never self-evident.
......@@ -29,9 +30,9 @@ Figure 1 shows the initial *functional* eSSIF-Lab architecture, and its scope, c
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*.
Since the participants of a business transaction are different Parties, the negotiation, commitment and execution of that transaction will be done by Agents of these different Parties. Assuming that a single transaction has two such Parties, we will use the term ‘%%_Peer Party (of a specific Party, in the context of a single transaction)_|peer-party%%’ to refer to the participating Party in that transaction that is not the specific Party itself.
Since the participants of a business transaction are different Parties, the negotiation, commitment and execution of that transaction will be done by Agents of these different Parties. Assuming that a single transaction has two such Parties, we will use the term ‘<Term popup="(Peer Party of a Party): the other Party that is a participant in a transaction of that Party." reference="peer-party">_Peer Party (of a specific Party, in the context of a single transaction)_</Term>’ to refer to the participating Party in that transaction that is not the specific Party itself.
When an Agent is involved in such a transaction, it will be communicating with a component that it assumes to be an Agent of the Peer Party of its Owner (the Agent may obtain further assurances for that, but that's outside the scope for now). We will use the term ‘%%_Peer Agent (of a specific Agent, in the context of a single transaction)_|peer-agent%%’ to refer to an Actor with which the specific Agent has a communications session. Note that establishing whether or not an Actor is a Peer Agent does not necessarily require knowing who the Peer Party actually is.
When an Agent is involved in such a transaction, it will be communicating with a component that it assumes to be an Agent of the Peer Party of its Owner (the Agent may obtain further assurances for that, but that's outside the scope for now). We will use the term ‘<Term popup="(Peer Agent of a Agent): the other Agent with whom this Agent is communicating in the context of a transaction." reference="peer-agent">_Peer Agent (of a specific Agent, in the context of a single transaction)_</Term>’ to refer to an Actor with which the specific Agent has a communications session. Note that establishing whether or not an Actor is a Peer Agent does not necessarily require knowing who the Peer Party actually is.
The figure below is an overview of the most important *functional* components that any Party needs to conduct electronic business transactions.
......@@ -51,9 +52,9 @@ The top layer (in the red rounded rectangle) has the functions of actual busines
The lower business layer contains two functional components, one for initiating transactions and the other for stating transaction results (as per the [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations) method), each of which with an associated business policy that contains business-specific policies/preferences.
The task of the %%_Transaction Validation Engine_|transaction-validation-engine%% (or %%_TVE_|tve%%) is to handle and initiate requests from/to Peer Agents to engage in some kind of transaction, by negotiating and exchanging data (through one or more, physical or electronic communication channels), and to produce a transaction form whose contents are complete and valid, enabling an appropriate Colleague to decide whether or not to engage in the transaction. Note that negotiating a transaction has two parts: requesting a Peer Agent to provide data that its Owner needs, and providing data on behalf of its Owner that a Peer Agent requests. After all, a business transaction can only start after all Parties have decided to commit, which they can only do after each of them has obtained the information it (subjectively) needs to do so. Also note that data that the TVE must ensure that the transaction context is properly maintained if it chooses to exchange data through different communication channels.
The task of the <Term popup="transaction-validation-engine" reference="transaction-validation-engine">_Transaction Validation Engine_</Term> (or <Term popup="<Text that pops up when the user hovers over a reference to this concept>" reference="tve">_TVE_</Term>) is to handle and initiate requests from/to Peer Agents to engage in some kind of transaction, by negotiating and exchanging data (through one or more, physical or electronic communication channels), and to produce a transaction form whose contents are complete and valid, enabling an appropriate Colleague to decide whether or not to engage in the transaction. Note that negotiating a transaction has two parts: requesting a Peer Agent to provide data that its Owner needs, and providing data on behalf of its Owner that a Peer Agent requests. After all, a business transaction can only start after all Parties have decided to commit, which they can only do after each of them has obtained the information it (subjectively) needs to do so. Also note that data that the TVE must ensure that the transaction context is properly maintained if it chooses to exchange data through different communication channels.
The task of the %%_Transaction Result Dispatcher_|transaction-result-dispatcher%% (or %%_TRD_|trd%%) is to state the (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other Parties. Since such state-data may change, issuing data that supersedes an earlier state implies the revocation of such a state.
The task of the <Term popup="hovertext for transaction-result-dispatcher" reference="transaction-result-dispatcher">_Transaction Result Dispatcher_</Term> (or <Term popup="<Text that pops up when the user hovers over a reference to this concept>" reference="trd">_TRD_</Term>) is to state the (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other Parties. Since such state-data may change, issuing data that supersedes an earlier state implies the revocation of such a state.
Note that both components are within scope of eSSIF-Lab architecture, but NOT in scope of the eSSIF-Lab infrastructure, as they are too business-specific.
......@@ -99,7 +100,7 @@ It is expected that there are already some interfaces out there that may turn ou
There are two interface layers in this architecture
The \`%%_ESSIF Glue_|eSSIF Glue%%\` interface layer consists of a [documented set of APIs](https://gitlab.grnet.gr/essif-lab/tno-ssi-service/developer-docs) between the TVE and TRD on the one hand, and the WHIV components on the other hand. The purpose of these APIs is to make calling the WHIV functions as simple as possible, given the functions of the Transaction Result Dispatcher and Transaction (Validation) Engine. Ultimately, we would like to see these APIs standardized. Having such APIs allows different Parties to create their own version of the WHIV components, supporting the SSI technologies as they see fit, and shrinking or expanding functionalities as they feel appropriate. Parties can then select such WHIV components as they see fit.
The \`<Term popup="eSSIFGlue" reference="eSSIFGlue">_ESSIF Glue_</Term>\` interface layer consists of a [documented set of APIs](https://gitlab.grnet.gr/essif-lab/tno-ssi-service/developer-docs) between the TVE and TRD on the one hand, and the WHIV components on the other hand. The purpose of these APIs is to make calling the WHIV functions as simple as possible, given the functions of the Transaction Result Dispatcher and Transaction (Validation) Engine. Ultimately, we would like to see these APIs standardized. Having such APIs allows different Parties to create their own version of the WHIV components, supporting the SSI technologies as they see fit, and shrinking or expanding functionalities as they feel appropriate. Parties can then select such WHIV components as they see fit.
The **SSI Tech APIs** interface layer is the union of the interfaces of the components within it. Any standardization in there is outside the scope of eSSIF-Lab.
......@@ -321,7 +322,7 @@ This chapter explains at a high level how electronic business transactions are b
The adjacent figure shows how a transaction is conducted at the highest abstraction level. One Party, called the ‘Requester’, sends a request for a product or service to another Party (that we will call the ‘Provider’). Then, they start to negotiate a ‘transaction agreement’, which means that they exchange data through various channels for the purpose of establishing the details of the product/service to be provided and the compensation, data needed to mitigate transaction risks, etc., all of which is necessary for the Parties to (individually/subjectively) decide whether or not to commit to the transaction. Section 3.2 provides more detail about this phase.
After commitment, the producer works to provide the %%product|essiflab-concept-product%% or service, and the requester arranges the compensation. This phase is entirely up to the business, and hence out of scope of this document.
After commitment, the producer works to provide the <Term popup="hovertext for pattern concept-product" reference="essiflab-concept-product">product</Term> or service, and the requester arranges the compensation. This phase is entirely up to the business, and hence out of scope of this document.
When all is done, Parties may issue a (signed) statement that specifies the results. Section 3.3. provides some more details about this phase.
......
This diff is collapsed.
......@@ -2,3 +2,119 @@
id: essif-lab-glossary
title: eSSIF-Lab Glossary
---
- **[Concept: Action (Scope: eSSIF-Lab)](/docs/terms/action)**: something that is done by an actor
- **[Concept: Actor (Scope: eSSIF-Lab)](/docs/terms/actor)**: Entity that can act (do things), e.g. people, machines, but not organizations.
- **[Concept: Agent (Scope: eSSIF-Lab)](/docs/terms/agent)**: Agent (of a Party): Actor that is currently working on behalf of a Party.
- **[Concept: Concept (Scope: essifLabTerminology)](/docs/terms/semantics)**: semantics popover
- **[Concept: Concept (Scope: essifLabTerminology)](/docs/terms/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.
- **[Concept: Concept (Scope: essifLabTerminology)](/docs/terms/concepts)**: 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.
- **[Concept: Concept-file (Scope: eSSIF-Lab)](/docs/terms/pattern-file)**: concept-file popover
- **[Concept: Dictionary (Scope: essifLabTerminology)](/docs/terms/dictionary)**: an alphabetically sorted list of termsort) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s).
- **[Concept: Entity (Scope: eSSIF-Lab)](/docs/terms/entity)**: something that is done by an actor
- **[Concept: Jurisdiction (Scope: eSSIF-Lab)](/docs/terms/jurisdiction)**: <Text that pops up when the user hovers over a reference to this concept>
- **[Concept: Knowledge (Scope: eSSIF-Lab)](/docs/terms/knowledge)**: knowledge popover text
- **[Concept: Objective (Scope: eSSIF-Lab)](/docs/terms/objective)**: Something toward which effort is directed: an aim, goal, or end of action
- **[undefined](/docs/terms/README)**: undefined
- **[Concept: Organization (Scope: eSSIF-Lab)](/docs/terms/organization)**: popuptext for Organization tbd
- **[undefined](/docs/terms/CONTRIBUTIONS)**: undefined
- **[Concept: Owner (Scope: eSSIF-Lab)](/docs/terms/owner)**: a Party that has the legal or rightful title to control something.
- **[Concept: Party (Scope: eSSIF-Lab)](/docs/terms/party)**: Entity that has knowledge about what exists, ways to reason with that knowledge, and ways for making decisions in a Self-Sovereign fashion.
- **[Concept: Pattern (Scope: eSSIF-Lab)](/docs/terms/pattern)**: pattern popover text
- **[Concept: Pattern-file (Scope: eSSIF-Lab)](/docs/terms/concept-file)**: pattern-file popover
- **[Concept: Scope-file (Scope: eSSIF-Lab)](/docs/terms/scope-file)**: scope-file popover
- **[Concept: TRD - Transaction Result Dispatcher (Scope: eSSIF-Lab)](/docs/terms/trd)**: <Text that pops up when the user hovers over a reference to this concept>
- **[Concept: TVE - Transaction Validation Engine (Scope: eSSIF-Lab)](/docs/terms/tve)**: <Text that pops up when the user hovers over a reference to this concept>
- **[Concept: Term-file (Scope: eSSIF-Lab)](/docs/terms/term-file)**: term-file popover
- **[Concept: Transaction Result Dispatcher (Scope: eSSIF-Lab)](/docs/terms/transaction-result-dispatcher)**: hovertext for transaction-result-dispatcher
- **[Concept: eSSIF-Glue (Scope: eSSIF-Lab)](/docs/terms/eSSIFGlue)**: eSSIFGlue
- **[Concept: transaction-validation-engine (Scope: eSSIF-Lab)](/docs/terms/transaction-validation-engine)**: transaction-validation-engine
- **[Glossary of eSSIF-Lab](/docs/terms/essifLab-glossary)**: <Text that pops up when the user hovers over a reference to this eSSIF-Lab glossary>
- **[Glossary of eSSIF-Lab Terminology](/docs/terms/glossary)**: <Text that pops up when the user hovers over a reference to this eSSIF-Lab Terminology glossary>
- **[Pattern: Jurisdictions (Scope: eSSIF-Lab)](/docs/terms/jurisdictions)**: <Text that pops up when the user hovers over a reference to this pattern>
- **[Pattern: Mental Models (Scope: essifLabTerminology)](/docs/terms/mental-model)**: 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.
- **[Pattern: Party-Action (Scope: eSSIF-Lab)](/docs/terms/party-action)**: This pattern captures the foundational concepts and relations that we need for thinking about people (human beings), organizations, and how they interact with one another in a decentralized, self-sovereign way - which means that each of them decides for itself whether or not to interact with others, how to conduct such interactions, etc., thereby only taking external influences into account if they want, or have some need to do so.
- **[Pattern: Party-Action (Scope: eSSIF-Lab)](/docs/terms/essiflab-concept-product)**: hovertext for pattern concept-product
- **[Scope: eSSIF-Lab](/docs/terms/essifLab-scope)**: <essifLab-scope hovertext>
- **[Term (Scope: essifLabTerminology)](/docs/terms/term)**: a word or phrase that is used in at least one scope/context to refer to a specific concept.
- **[Term: Peer Agent (Scope: eSSIF-Lab)](/docs/terms/peer-agent)**: (Peer Agent of a Agent): the other Agent with whom this Agent is communicating in the context of a transaction.
- **[Term: Peer Party (Scope: eSSIF-Lab)](/docs/terms/peer-party)**: (Peer Party of a Party): the other Party that is a participant in a transaction of that Party.
- **[Term: SSI Agent (Scope: eSSIF-Lab)](/docs/terms/ssi-agent)**: Agent that provides SSI services.
- **[eSSIF-Lab Terminology](/docs/terms/scope)**: <essifLabTerminology-scope hovertext>
- **[eSSIF-Lab: Concepts and Terminology](/docs/terms/terminology)**: undefined
......@@ -4,6 +4,8 @@ title: "eSSIF-Lab: Concepts and Terminology"
scopeid: essifLab
---
import { Term } from '..\src\components'
:::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)*
:::
......@@ -20,31 +22,31 @@ This is far from trivial, and hence we expect to see situations of "language con
This chapter reflects the learnings of eSSIf-Lab with respect to what such additional needs are, and provides the backgrounds of the methods, means and/or tools that may help to accommodate such needs. Here is a summary:
1. People that read a text may need help in understanding various words or phrases, particularly if they are not very familiar with the subject matter (they may be learning, and/or the text doesn't have an associated glossary), or come from another society. For such purposes, it helps to have an alphabetically sorted lists of words and phrases, each of which associated with one or more meanings or explanations that such words/phrases may have. We call this list a %%dictionary|dictionary%%. The eSSIF-Lab project intends to look into the possibility and necessity of generating a dictionary of SSI-related words and phrases based on the materials that are readily available; if it turns out this is beneficial, the eSSIF-Lab will contribute to the extent that is allowed by the project constraints.
2. Authors (e.g. of programming code, or articles of various kinds) that produce text on a particular topic, will want the words and phrases they use to be associated with a single meaning. This also holds for people that want to discuss a particular topic. For purposes such as these, it helps to have an alphabetically sorted lists of words and phrases, each of which associated with a single meaning or explanation that they can refer to. We call such lists %%glossaries|glossary%%. The eSSIF-Lab project intends to allow for the automated generation of such glossaries whenever a specific need for that exists.
1. People that read a text may need help in understanding various words or phrases, particularly if they are not very familiar with the subject matter (they may be learning, and/or the text doesn't have an associated glossary), or come from another society. For such purposes, it helps to have an alphabetically sorted lists of words and phrases, each of which associated with one or more meanings or explanations that such words/phrases may have. We call this list a <Term popup="an alphabetically sorted list of termsort) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s)." reference="dictionary">dictionary</Term>. The eSSIF-Lab project intends to look into the possibility and necessity of generating a dictionary of SSI-related words and phrases based on the materials that are readily available; if it turns out this is beneficial, the eSSIF-Lab will contribute to the extent that is allowed by the project constraints.
2. Authors (e.g. of programming code, or articles of various kinds) that produce text on a particular topic, will want the words and phrases they use to be associated with a single meaning. This also holds for people that want to discuss a particular topic. For purposes such as these, it helps to have an alphabetically sorted lists of words and phrases, each of which associated with a single meaning or explanation that they can refer to. We call such lists <Term popup="<Text that pops up when the user hovers over a reference to this eSSIF-Lab Terminology glossary>" reference="glossary">glossaries</Term>. The eSSIF-Lab project intends to allow for the automated generation of such glossaries whenever a specific need for that exists.
3. People may find they need to better understand the ideas/concepts that terms refer to, e.g. because their thoughts keep running around in circles, they cannot get software to work in a generic fashion, etc. The eSSIF-Lab project intends to provide a (structured) repository where people can store texts that
- describe what we call a %%pattern|pattern%% or %%mental model|pattern%%, i.e. a coherent set of %%concepts|concepts%%, relations between these concepts, and rules/constraints that apply. A pattern also motivates its existence, and provides examples of when and how it can be used in a purposeful way;
- specify individual %%concepts|concept%% in a precise and in-depth manner, beyond what is possible by the texts used in patterns;
- specify how specific words or phrases (%%terms|term%%) are mapped onto such %%concepts|concept%% within specific scopes/contexts;
- specify a %%scope (or context)|scope%%, i.e. the extent of the area or subject matter within which we define patterns, concepts, terms and glossaries, allowing patterns to be used in a limited scope, terms to be have different meanings in different scopes, etc.
- describe what we call a <Term popup="pattern popover text" reference="pattern">pattern</Term> or <Term popup="pattern popover text" reference="pattern">mental model</Term>, i.e. a coherent set of <Term popup="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." reference="concepts">concepts</Term>, relations between these concepts, and rules/constraints that apply. A pattern also motivates its existence, and provides examples of when and how it can be used in a purposeful way;
- specify individual <Term popup="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." reference="concept">concepts</Term> in a precise and in-depth manner, beyond what is possible by the texts used in patterns;
- specify how specific words or phrases (<Term popup="undefined" reference="term">terms</Term>) are mapped onto such <Term popup="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." reference="concept">concepts</Term> within specific scopes/contexts;
- specify a <Term popup="<essifLabTerminology-scope hovertext>" reference="scope">scope (or context)</Term>, i.e. the extent of the area or subject matter within which we define patterns, concepts, terms and glossaries, allowing patterns to be used in a limited scope, terms to be have different meanings in different scopes, etc.
## Context
People use %%words and phrases (terms)|term%% to (tangibly) refer to the (intangible) %%ideas and thoughts (concepts)|concept%% they have, e.g. about what exists in the world, judgements they have, etc.<sup>[semantics]</sup> This mapping of terms and concepts, which we call '[semantics](wikipedia/semantics)', that is unique for each %%person or organization|party%%, enables them to reflect on their thoughts, and to convey such thoughts to others. Good communication however requires that the semantics of the communicating parties is sufficiently the same, so that the recipient of a communication will interpret it such that it means (sufficiently) the same to him as the communication means to its sender.
People use <Term popup="undefined" reference="term">words and phrases (terms)</Term> to (tangibly) refer to the (intangible) <Term popup="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." reference="concept">ideas and thoughts (concepts)</Term> they have, e.g. about what exists in the world, judgements they have, etc.<sup>[semantics]</sup> This mapping of terms and concepts, which we call '[semantics](wikipedia/semantics)', that is unique for each <Term popup="Entity that has knowledge about what exists, ways to reason with that knowledge, and ways for making decisions in a Self-Sovereign fashion." reference="party">person or organization</Term>, enables them to reflect on their thoughts, and to convey such thoughts to others. Good communication however requires that the semantics of the communicating parties is sufficiently the same, so that the recipient of a communication will interpret it such that it means (sufficiently) the same to him as the communication means to its sender.
The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community participants understand one another at whatever level of precision they need. This chapter presents a number of aids we will develop/maintain to serve that purpose.
[semantics]: we use the term %%semantics|semantics%% to refer to the mapping between %%terms|term%% and %%concepts|concept%%. We use the term %%scope|scope%% ([OED](https://www.lexico.com/definition/scope)) to refer to the extent of the area or subject matter that a semantics is relevant and/or being used. From this definition, it seems obvious that every %%party|party%% has - and maintains - its own (subjective) semantics. The (erroneous) assumption that people (automatically) share a semantics is the cause of many misunderstandings.
[semantics]: we use the term <Term popup="semantics popover" reference="semantics">semantics</Term> to refer to the mapping between <Term popup="undefined" reference="term">terms</Term> and <Term popup="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." reference="concept">concepts</Term>. We use the term <Term popup="<essifLabTerminology-scope hovertext>" reference="scope">scope</Term> ([OED](https://www.lexico.com/definition/scope)) to refer to the extent of the area or subject matter that a semantics is relevant and/or being used. From this definition, it seems obvious that every <Term popup="Entity that has knowledge about what exists, ways to reason with that knowledge, and ways for making decisions in a Self-Sovereign fashion." reference="party">party</Term> has - and maintains - its own (subjective) semantics. The (erroneous) assumption that people (automatically) share a semantics is the cause of many misunderstandings.
## Concepts, Terminologies, Glossaries, Dictionaries, etc.
Conveying one's thoughts is deciding which words or phrases to use for referring to the ideas or %%concepts|concept%% that one is thinking about. We will use the word %%Term%|term%% to refer to a word or phrase, that is used in some %%context (or: scope)|scope%% to refer to a specific concept. Hence, a Term can mean different things in different contexts. Examples are "localhost", or "mommy". Also, different Terms that are used in different contexts may still refer to the same concept. For example, the person referred to as "Rieks" in some contexts is known as "Mr. Joosten" in other contexts.
Conveying one's thoughts is deciding which words or phrases to use for referring to the ideas or <Term popup="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." reference="concept">concepts</Term> that one is thinking about. We will use the word <Term popup="undefined" reference="term">Term</Term> to refer to a word or phrase, that is used in some <Term popup="<essifLabTerminology-scope hovertext>" reference="scope">context (or: scope)</Term> to refer to a specific concept. Hence, a Term can mean different things in different contexts. Examples are "localhost", or "mommy". Also, different Terms that are used in different contexts may still refer to the same concept. For example, the person referred to as "Rieks" in some contexts is known as "Mr. Joosten" in other contexts.
Because of this, generally dealing with terminologies, i.e. sets of words or phrases with a presumed meaning, is a difficult topic, demonstrated e.g. by the work of Pfitzmann and Hansen who created a [terminology for talking about privacy by data minimization](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) (2010), the development of which took over a decade, and has seen over 30 revisions.
A commonly used tool for fostering common understanding are %%glossaries|glossary%%, i.e. an alphabetically sorted lists of words and phrases that relate to a specific subject (or text, dialect, ...) with explanations ([OED](https://www.lexico.com/definition/glossary)).
A commonly used tool for fostering common understanding are <Term popup="<Text that pops up when the user hovers over a reference to this eSSIF-Lab Terminology glossary>" reference="glossary">glossaries</Term>, i.e. an alphabetically sorted lists of words and phrases that relate to a specific subject (or text, dialect, ...) with explanations ([OED](https://www.lexico.com/definition/glossary)).
Glossaries come in two basic flavors. One flavor, which we will call %%dictionary|dictionary%%, is a glossary where each term is associated with multiple meanings. An example is the [NIST Glossary](https://csrc.nist.gov/glossary). It allows people that hear or read about something to search for a meaning that is appropriate for the context of that communication.
Glossaries come in two basic flavors. One flavor, which we will call <Term popup="an alphabetically sorted list of termsort) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s)." reference="dictionary">dictionary</Term>, is a glossary where each term is associated with multiple meanings. An example is the [NIST Glossary](https://csrc.nist.gov/glossary). It allows people that hear or read about something to search for a meaning that is appropriate for the context of that communication.
The other flavor (for which we do not yet have a term to distinguish it from dictionaries), is a glossary that is about one specific topic/subject, and lists a set of terms that have a single meaning, that together form a coherent and consistent terminology, and serves one or more specific purposes regarding this topic/subject. An example is the [Sovrin Glossary](https://sovrin.org/library/glossary/). Such glossaries allow people e.g. to write code, or an article about the topic.
......
# README for terminology-related files.
This directory contains the artefacts that can be used to generate Pages that explain concepts and terms, as well for generating a Glossary. These artefacts are expected to provide a rigorous underpinning of the decisions that have led to the specification of the semantics of the various terms.
This document states the requirements for files in this directory, such that they can properly processed into useful and useable Docusaurus documentation.
[Other text to be added, e.g.: 'How to contribute']
## Filenames
All file MUST have the structure: `<termid>.mdx`, where `<termid>` is the (all lowercase) identifier of a term (including the term that is used when defining a concept). They MUST be a lowercase identifier that only uses charancters `a`-`z` and `-`.
## Templates
The `terms/templates` directory contains templates for each of the `<type>`s. 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
---
id: essifLab-concept-actor
title: "Concept: Actor (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: actor
hoverText: "Entity that can act (do things), e.g. people, machines, but not organizations."
---
## Criterion:
Entity that is capable of acting (doing things).
## Examples:
People obviously qualify, as do robots and other machines. Stones, pictures, ideas, etc. do not qualify.
We specifically note that enterprises, governments, and other organizations do not qualify.
### Background:
further background on this concept is provided by the ['Party-Action' pattern|essifLab-pattern-party-action]
---
[^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.
\ No newline at end of file
---
id: essifLab-concept-agent
title: "Concept: Agent (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: agent
hoverText: "Agent (of a Party): Actor that is currently working on behalf of a Party."
---
## Short Description
An %%Actor|actor%% that is executing on action on behalf of some %%Party|party%%, which means that the execution of that action is subject to the conditions and other guidance set by that Party, then we say the Actor acts as an Agent of that Party. A Person, that is both an Actor and a Party can hence be seen as its own Agent. Agency is further detailed in the ['Party-Action' pattern|essifLab-pattern-party-action].
## Criterion:
%%Actor|actor%% that is momentarily executing an action on behalf of a %%Party|party%%.
## Examples:
- A person that is 'doing its own things' acts as an Agent for himself.
- A person that does things for his employer acts as an Agent for that employer.
- An ambassador, when (s)he is 'in function', acts as an Agent for the country for which (s)he is ambassador.
- A person that fills in the tax return form for someone else acts as an Agent for this someone else.
- A company that makes cars may use robots that weld parts of a car together; these robots acts as Agents for that company.
- A (running) webserver that accepts product orders for a retailer acts as a (digital) Agent for that retailer.
- A wallet app that runs on a phone and that is exclusively used by a single person acts as a (digital) Agent for that person.
---
id: essifLab-concept-jurisdiction
title: "Concept: Jurisdiction (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: jurisdiction
hoverText: "<Text that pops up when the user hovers over a reference to this concept>"
---
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
## 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
<!--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 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.-->
## Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `<New 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 that are similar but distinct, with a note about the relationship.-->
## Domains
<!--In which general knowledge ecosystems or mental model families does this concept play a role?-->
## 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 `<New Term>` to/in that situation;
- shows the relevance of having `<New 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.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
id: essifLab-concept-objective
title: "Concept: Objective (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: objective
hoverText: "Something toward which effort is directed: an aim, goal, or end of action"
---
## Criterion:
Something toward which effort is directed: an aim, goal, or end of action ([Merriam-Webster](https://www.merriam-webster.com/dictionary/objective))
## Examples:
Anything that, according to a %%Party|party%% c.q. its way of thinking, is important to be realized, qualifies as an Objective (and identifies its owner as that %%Party|party%%)
### Xxx:
The %%Knowledge|knowledge%%/judgements of a %%Party|party%% are what makes something an %%Objectiv%%e (owned by that %%Party|party%%).
---
id: essifLab-concept-organization
title: "Concept: Organization (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: organization
hoverText: "popuptext for Organization tbd"
---
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
## 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
<!--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 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.-->
## Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `<New 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 that are similar but distinct, with a note about the relationship.-->
## Domains
<!--In which general knowledge ecosystems or mental model families does this concept play a role?-->
## 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 `<New Term>` to/in that situation;
- shows the relevance of having `<New 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.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
id: essifLab-concept-owner
title: "Concept: Owner (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: owner
hoverText: "a Party that has the legal or rightful title to control something."
---
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
The property of a %%Party|party%% that has the legal or rightful title to control something. We interpret 'legal' and 'rightful' as terms that apply to _any_ %%Jurisdiction|jurisdiction%% (that is: not just legal/national jurisdictions, but also those of other organizations/parties).
## 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
<!--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 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.-->
## Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `<New 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 that are similar but distinct, with a note about the relationship.-->
## Domains
<!--In which general knowledge ecosystems or mental model families does this concept play a role?-->
## 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 `<New Term>` to/in that situation;
- shows the relevance of having `<New 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.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
id: essifLab-concept-trd
title: "Concept: TRD - Transaction Result Dispatcher (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: trd
hoverText: "<Text that pops up when the user hovers over a reference to this concept>"
---
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
## 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
<!--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 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.-->
## Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `<New 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 that are similar but distinct, with a note about the relationship.-->
## Domains
<!--In which general knowledge ecosystems or mental model families does this concept play a role?-->
## 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 `<New Term>` to/in that situation;
- shows the relevance of having `<New 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.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
id: essifLab-concept-tve
title: "Concept: TVE - Transaction Validation Engine (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: tve
hoverText: "<Text that pops up when the user hovers over a reference to this concept>"
---
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
## 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
<!--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 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.-->
## Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `<New 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 that are similar but distinct, with a note about the relationship.-->
## Domains
<!--In which general knowledge ecosystems or mental model families does this concept play a role?-->
## 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 `<New Term>` to/in that situation;
- shows the relevance of having `<New 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.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
id: essifLab-pattern-jurisdictions
title: "Pattern: Jurisdictions (Scope: eSSIF-Lab)"
scopeid: essifLab
patternid: jurisdictions
hoverText: "<Text that pops up when the user hovers over a reference to this pattern>"
---
<!-- A pattern captures/describes a set of concepts, relations between them, and rules or constraints that (instances) thereof comply with. As such, it is a concise and possibly formal description of a coherent set of ideas, a mental model if you will, that can be used to facilitate one's thinking about/with these concepts.
Please fill in the placeholders in this file as follows:
- `<ExistingScopeID>`: machine readable text that identifies the scope in which this pattern is defined;
- `<Existing Scope>`: human readable text that identifies the scope in which this pattern is defined;
- `<NewPatternID>`: machine readable text that identifies this pattern within <ExistingScopeID>;
- `<New Pattern>`: human readable text that identifies this pattern within <Existing Scope>;
-->
## Purpose
<!-- Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it. -->