Commit 7aba486f authored by Rieks Joosten's avatar Rieks Joosten
Browse files

terminology updates (still WIP)

parent 0a5dea05
Pipeline #15703 passed with stage
in 1 minute and 33 seconds
---
id: TBD
title: "TO BE DONE"
---
:::info **UNDER CONSTRUCTION**
This page is a placeholder for pages that need to be authored.
:::
---
id: functional-architecture
title: eSSIF-Lab Functional Architecture
sidebar_label: Functional Architecture
scopeid: essifLab
---
......@@ -10,13 +11,14 @@ The purpose of the functional architecture and its views is to
- 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.
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 %%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.
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 '%%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.
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.
......@@ -28,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|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 %%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.
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|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 %%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.
The figure below is an overview of the most important *functional* components that any Party needs to conduct electronic business transactions.
......@@ -50,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|transaction-validation-engine%%) 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 (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 %%Transaction Result Dispatcher|transaction-result-dispatcher%% (or %%TRE|transaction-result-dispatcher%%) 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 %%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.
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.
......@@ -98,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|eSSIFGlue%% 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 '**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 **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.
......
---
id: notations-and-conventions
title: Notations and Conventions Used in this Documentation
sidebar_label: Notations
title: Notations and Conventions
---
Here, we provide an overview of the notations and conventions being used within eSSIF-Lab.
This document provides an overview of the notations and conventions being used within eSSIF-Lab.
## RFC 2119
### RFC 2119
We shall use keywords such as “shall”, “should”, “may” etc. as defined by [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
## Capitalization of words in mid-sentence
Also, we capitalize words in mid-sentence whenever it is used in the meaning as provided by a corresponding Definition. This allows us to also use the more colloquial meanings of words (by not capitalizing them). We appreciate any feedback regarding our (im)proper use of this kind of capitalization of words.
### Capitalization of words in mid-sentence
A word in mid-sentence that is capitalized is a %%term|term%% that has a %%definition|definition%% in the %%Corpus of Terminology|corpus%%. This allows readers to distinguish between the more colloquial meanings of words (by not capitalizing them) and those that are actually defined. We appreciate any feedback regarding our (im)proper use of this kind of capitalization of words.
We are working towards deprecating this convention, as we now have better ways to refer to %%definitions|definition%%.
:::note
We are working towards deprecating this convention, as we now have better ways of referring to words that are defined in the eSSIF-Lab Corpus..
## Pattern diagram notations
### Pattern diagram notations
%%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation, as follows:
......
---
id: terminology-contributions
title: "How To Contribute to the eSSIF-Lab Terminology Effort"
sidebar_label: Contributing to the Terminology Effort
scopeid: essifLab
---
import useBaseUrl from '@docusaurus/useBaseUrl';
:::info **UNDER CONSTRUCTION**
TNO to provide further contents
:::
......@@ -15,42 +15,42 @@ Please fill in the placeholders in this file as follows:
- `<New Term>`: human readable text that identifies this term within `<Existing Scope>`;
-->
## Short Description
### Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
## Purpose
### 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
### 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
### 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
### Related Concepts
<!--Link to any concepts that are similar but distinct, with a note about the relationship.-->
## Background:
### Background
<!--Mention and link to the patterns in which this concept plays a (significant) role (possibly explaining the reason/purpose if appropriate), e.g.: The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.-->
## Domains
### Domains
<!--In which general knowledge ecosystems or mental model families does this concept play a role?-->
## Tags
### Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
## Use-cases
### 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
### Notes
<!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
......
......@@ -11,8 +11,8 @@ hoverText: "DictionaryID: popuptext for 'dictionaryID' (tbd)."
This template lets you define the specifications according to which a specific dictionary is generated.
-->
## Purpose
### Purpose
<!--State the purpose(s) that this dictionary aims to fulfill, in such a way that readers can easily determine whether or not it is useful for them to use it. This text appears as the introduction of the (generated) dictionary.-->
## Scopes
### Scopes
<!--This section specifies the various scopes from which terms are included in the dictionary-->
......@@ -14,10 +14,10 @@ Please fill in the placeholders in this file as follows:
- `<new-glossaryID>`: identifier by which the glossary can be identified within <existing-scopeID>;
-->
## Purpose
### 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.-->
## Sources
### Sources
<!--This section specifies the sources from which the glossary entries (and their descriptions) are to be collected. All terms from all sources are included in the glossary. If that is too much, then you should revert to stating individual terms, patterns or concepts (see below).-->
### Terms
......@@ -34,7 +34,7 @@ Please fill in the placeholders in this file as follows:
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
......
......@@ -15,13 +15,13 @@ Please fill in the placeholders in this file as follows:
- `<New Pattern>`: human readable text that identifies this pattern within <Existing Scope>;
-->
## Purpose
### Purpose
<!-- Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it. -->
## Introduction
### 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. -->
## Notations
### 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 -->
......@@ -29,10 +29,10 @@ Please fill in the placeholders in this file as follows:
<!--
---
## Footnotes
### 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
......@@ -14,27 +14,27 @@ Please fill in the placeholders in this file as follows:
- `<New Scope>`: human readable text that identifies the new subscope;
-->
## Governance
### Governance
<!--This section identifies the organizational body (Jurisdiction) that governs the scope. Optionally, a reference to the governance framework/procedures may be made.-->
## Objectives/Issues
### 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.-->
## Scope URI
### Scope URI
<!--Optionally specify the URI by which this scope may be identified-->
## Inclusions
### 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
### Notes
<!--Anything els that's worth mentioning.-->
## Tags
### Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
......
......@@ -18,15 +18,15 @@ Please fill in the placeholders in this file as follows:
- `<ExistingtermID>`: machine readable identifier that identifies a concept within <ExistingConceptScopeID>
-->
## Purpose
### Purpose
<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
## Notes
### Notes
<!--Usually, the meaning of a term will not be _exactly_ the same as that of the concept to which it refers. Often, there are slight differences in meaning, or the term may emphasize specific characteristics of the concept, so as to accommodate specific needs of the scope in which it is defined. Please describe such deviations/emphasized characteristics in this section, and which needs that helps accommodate.-->
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
......
---
id: terminology
title: "eSSIF-Lab Concepts and Terminology"
sidebar_label: Terminology
sidebar_label: Purpose and Vision
scopeid: essifLab
---
:::info **UNDER CONSTRUCTION**
*This (initial version of the) terminology chapter is currently under construction. If you feel like making a contribution, please contact [the editor](mailto:rieks.joosten@tno.nl)*
:::
When people from various backgrounds (and cultures) work together, it is inevitable that misunderstandings occur, i.e. texts (written or spoken) are easily interpreted in ways that the author hadn't intended. It is not self-evident that such events will be detected, but even when they are identified, resolving them takes a lot of effort, a large part of which might perhaps better be spent on other things.
The eSSIF-Lab Terminology and Concepts effort is directed at providing tools, terminologies and (mental/conceptual) models, the purpose of which is to enable/facilitate its stakeholders in understanding one another as they communicate about topics that concern eSSIF-Lab (specifically: its arechitecture and components), and also to write document(ation)s in such a way that the other stakeholders have less trouble with understanding.
Within eSSIF-Lab, we would like to provide tools, methods and other means to help minimize the amount of misunderstandings, (i.e. to quickly identify any possible misunderstanding and to reduce the effort of resolving them), perhaps even preventing them.
## Motivation
## Vision
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.
[Many cultures](https://en.wikipedia.org/wiki/Tower_of_Babel#Comparable_myths) have stories, similar to that of the [Tower of Babel](https://en.wikipedia.org/wiki/Tower_of_Babel), that observe that the big feats, such as building a "tower, whose top may reach unto heaven", cannot be achieved unless there is linguistic unity. While is generally recognized (the [EU parliament building](https://images-wixmp-ed30a86b8c4ca887773594c2.wixmp.com/f/e3de7793-c11c-4246-81aa-401be9b09384/d5ttx0w-7bcf343b-2114-46cd-8c30-d722a9725ee9.jpg/v1/fill/w_1054,h_758,q_70,strp/european_union_parliament_02__tower_of_babel__by_nixseraph_d5ttx0w-pre.jpg?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1cm46YXBwOiIsImlzcyI6InVybjphcHA6Iiwib2JqIjpbW3siaGVpZ2h0IjoiPD0xNTk2IiwicGF0aCI6IlwvZlwvZTNkZTc3OTMtYzExYy00MjQ2LTgxYWEtNDAxYmU5YjA5Mzg0XC9kNXR0eDB3LTdiY2YzNDNiLTIxMTQtNDZjZC04YzMwLWQ3MjJhOTcyNWVlOS5qcGciLCJ3aWR0aCI6Ijw9MjIxNyJ9XV0sImF1ZCI6WyJ1cm46c2VydmljZTppbWFnZS5vcGVyYXRpb25zIl19.db-z1OueDUGbAWMhnIbxcDioaFh1zJVlBnUTNAd5y5Y) in Strasbourg [resembles](https://jdreport.com/wp-content/uploads/2014/05/tower-painting-parliament-e14176743284401.jpg.webp) the Tower of Babel as [depicted by the painter Brueghel](https://mattbell.org/wp-content/uploads/Tower-of-Babel-Peter-Breughel.jpg)), one can also observe that the part of the people that care about this and want to achieve a workable 'linguistic unity' lack means and tools that are easy to use.
We expect to see situations of "language confusion", i.e. in which people use words or phrases, the intension (not: intention) of which differs from the interpretation of some listeners/readers. Sometimes a casual glance at a dictionary or glossary is the solution. In other cases, deeper understanding matters, e.g. in when drafting specifications or contracts. Then [we need more than a set of definitions](https://www.sfu.ca/~swartz/definitions.htm).
The traditional tool for fostering common understanding is using %%glossaries|glossary%% or dictionaries, such as the ([Oxford English Dictionary (OED)](https://www.lexico.com/definition/glossary)), the [Sovrin Glossary](https://sovrin.org/library/glossary/) and the [NIST Glossary](https://csrc.nist.gov/glossary). Other initiatives produce documents with explanations, e.g. the [terminology for talking about privacy by data minimization](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) by Pfitzmann and Hansen (2010), or the [EBSI Terminology](https://ec.europa.eu/cefdigital/wiki/display/EBP/EBSI+Terminology) (login required).
The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community participants understand one another at whatever level of precision they need.
Traditional tools usually come with drawbacks that reduce their practical usefulness in this electronic era: dictionaries leave their user to decide which of the various meanings a term may have was intended, glossaries typically provide a single meaning, but lack a specification of the scope/context in which they are applied or authoritative, and documents rarely explain the ideas (concepts) behind terms they use.
## Terminological Artifacts
the eSSIF-Lab Concepts and Terminology effort aims to produce artifacts that help stakeholders for the purposes mentioned above. Currently, this comprises:
- A set of (documented/defined) terms that can be easily referred to by document authors, according to [these instructions](./terminology-plugin-instructions).
- A [Glossary](./essifLab-glossary) that lists these terms, and is automagically updated as contributions to the eSSIF-Lab Terminology Corpus are being made.
- A set of %%mental models|mental-model%% that provide backgrounds about how specific %%concepts|concept%% relate to one another.
Depending on the needs of stakeholders, additional artifacts may be created/generated.
## Glossaries are useful, but do not solve all problems
The eSSIF-Lab terminology effort is an attempt to improve on this, by
- creating and using tools that help authors and readers to understand the texts the create/read;
- creating and maintaining a %%Terminology Corpus|corpus%% that documents such understanding;
- automatically regenerate terminological artifacts (e.g. %%glossaries|glossary%% or %%dictionaries|dictionary%%) as the corpus is being updated.
The traditional tool for fostering common understanding is using glossaries, i.e. alphabetical lists of words relating to a specific subject, text, or dialect, with explanations; a brief dictionary ([OED](https://www.lexico.com/definition/glossary)). Examples include the [Sovrin Glossary](https://sovrin.org/library/glossary/) and the [NIST Glossary](https://csrc.nist.gov/glossary). Other initiatives attempt to provide more background, e.g. the [terminology for talking about privacy by data minimization](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) by Pfitzmann and Hansen (2010), or the [EBSI Terminology (login required)](https://ec.europa.eu/cefdigital/wiki/display/EBP/EBSI+Terminology).
As the corpus is being used, we expect ideas for improvement
- of the tools (both for authors and readers alike). Please create an [issue in the eSSIF-Lab framework repo](https://gitlab.grnet.gr/essif-lab/framework/-/issues);
- of the terminology, patterns, etc. Please create a pull-request for the changes on the [eSSIF-Lab framework repo](https://gitlab.grnet.gr/essif-lab/framework/-/merge_requests).
[Here](terminology-contributions) is how you may contribute to this terminology effort.
A Mental Model, or Conceptual Model, is a set of of concepts (i.e. entity classes), relations between such concepts (i.e. sets of pairs of members of classes that a relation connects), and rules/constraints expressed in terms of these relations and concepts.
The first purpose of a Mental Model is to help us think and reason about a certain topic or issue.
One signal that indicates the need of such a model is when we’re running circles in our thoughts, and we have this feeling of not understanding, of the topic being (too) complex. Often, we are thinking in terms of concepts that are not fit for the objectives we pursue.
So a mental model requires careful construction, that allows the choices for its elements to be validated against many use-cases. Such validation instills trust that our model elements (concepts, relations, rules) are well-chosen. It also provides us with the experience (usually after some time) that it has made our thinking easier, and we are better equipped to resolve issues.
The careful construction is comparable to a quest: it takes time, multiple versions, and careful reflection. And it needs continuous validation of its parts, by throwing use-cases at it and verifying that the model can describe such cases, and do some reasoning with them.
This careful construction must ensure that the mental model gets different properties. For starters, the model must be able to reason in (all) static situations, where things do not change, and the so-called ‘invariant’ rules/constraints must hold. Also, the model must be able to cope with time-dependencies and changes, for which other kinds of rules apply.
## Terminological Artifacts
In the end, the mental model needs to be expressed in several, different ways, depending on whom we want to convey the ideas behind it to. Business people generally need simple models that allow them to (roughly) grasp its gist. Software architects need models with precise definitions that allow them to use its elements in (formal) reasonings. Software engineers (programmers) need all the details that allow them to create applications and databases that work according to the model’s intent. So the level of detail that an expression of the model provides, makes it useful or useless to different audiences.
The terminological artifacts that the eSSIF-Lab Concepts and Terminology effort aims to produce include:
## Terminology and Definitions
- A set of (documented/defined) terms that are designed to serve the purposes as specified above.
- A [Glossary](./essifLab-glossary) that lists these terms
- A set of %%mental models|mental-model%% that provide backgrounds about how specific %%concepts|concept%% relate to one another.
We attempt to create definitions that are both acceptable for business people yet are precise enough to serve as a basis for formal reasoning. We do this by using [intensional definitions](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions), i.e. by defining criteria that specify the necessary and sufficient conditions for when a term should be used. We have tried to craft these definitions such that
Depending on the needs of stakeholders, additional artifacts may be created/generated.
- readers are likely to make the same judgements when using them, and
- these distinctions are relevant for our purposes. That’s the important stuff.
## Notes:
The actual texts we choose as the name for a concept is of secondary importance; if in a particular context other names are more suitable, you can rename them there without loss of meaning or consistency.
Here are some characteristics of the tools being supplied:
- When a reader sees a highlighted term (meaning that it is documented), (s)he will see a short description when hovering over the term, and the complete description by clicking onit.
- When an author writes a text in which he wants to tag a term with its definition, (s)he simply writes `\%\%text-to-be-tagged|referenceid\%\%`, where `referenceid` is usually the term name. For details, please refer to the [instruction for authors](TBD)
- Author wants to contribute to the Corpus of Terminology, i.e. modify existing documents or creating new ones, are supported by [templates](TBD) and [guidance for authoring terminology documents](TBD).
- The glossary will be automatically updated as contributions to the terminology orpus are being made merged into the master branch.
Together with these criteria, we provide a limited set of examples to help the reader to visualize the defined concepts, and to point out possibly unexpected consequences of the criteria. Also, we may motivate the need for having a concept by showing its relevance for the model.
# 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
......@@ -8,22 +8,22 @@ stage: draft
hoverText: "Action: something that is actually done/executed by a single actor (as a single operation) for some party within a specific context."
---
## Short Description
### Short Description
An **Action** is something that is actually done/executed by a %%actor|actor%% in some context (i.e. in a specific place, at a specific time). During the time interval in which the action is executed, the actor may still execute other actions in other execution-contexts (multi-tasking). An action is executed for, or on behalf of, a specific %%party|party%%, which means that the primary guidance for executing the action, e.g. how to execute it, boundary conditions within which the execution must take place, etc., comes from the %%knowledge|knowledge%% of that party. The actor is assumed to have appropriate access to the knowledge of that party. In order to properly execute the action, the executing actor may also use additional knowledge(s) to which it has access.
## Purpose
### Purpose
The ability to distinguish between (non)actions allows one to determine which (kinds of) %%actors|actor%% are capable of executing actions (e.g. by establishing that they have the competences required by the party), and as a consequence may be permitted and/or required to execute them. Also, this ability enables parties to determine the execution-policy, i.e. the set of rules and other guidance that actors should obey or comply with when exeucting an action on its behalf.
## Criterion:
### Criterion
An **Action** is something that is done by an actor, can be considered a single operation, and is performed in a specific context, for or on behalf of a specific party, i.e. in accordance with the policy rules that this party has established for such actions.
## Examples:
### Examples
- filling in a form and submitting it.
- cleaning a car.
## Related Concepts
### Related Concepts
<!--Link to any concepts that are similar but distinct, with a note about the relationship.-->
- OED defines Action as the fact or process of doing something, typically to achieve an aim ([OED](https://www.lexico.com/definition/action)), which is too generic for our purposes.
## Background:
### Background
The %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
\ No newline at end of file
......@@ -8,21 +8,21 @@ stage: draft
hoverText: "Actor: Entity that can act (do things), e.g. people, machines, but not organizations."
---
## Short Description
### Short Description
An **Actor** is someone or something that can actually do things, such as people or machines. Actors will generally do things, i.e. execute %%actions|action%% in different ways, depending on the context, or the %%party|party%% for whom they do this.
## Purpose
### Purpose
The ability to distinguish between (non)actors allows one to determine which (kinds of) actors are capable of executing which (kinds of) %%actions|action%%, specifically since %%organizations|organization%% do not qualify as an actor (they need actors to get things done).
## Criterion:
### Criterion
Entity that is capable of actually executing %%actions|action%% (acting, doing things).
## Examples:
### Examples
- People (human beings) obviously qualify, as do robots and other machines.
- Stones, pictures, ideas, etc. do not qualify.
- Software applications qualify, provided they are actually running on hardware. An app that is just sitting e.g. on a mobile phone but isn't executed does not qualify.
- Enterprises, governments, and other %%organizations|organization%% do not qualify.
## Background:
### Background
The %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
......@@ -5,20 +5,20 @@ scopeid: essifLab
type: concept
typeid: agent
stage: draft
hoverText: "Agent: An actor that is (at that point in time) executing an action for, or on behalf of a Party."
hoverText: "Agent: An actor that is (at that point in time) executing an action for, or on behalf of a Party (the Principal of that actor)."
---
## Short Description
%%Actors|actor%% execute %%actions|action%% for, or on behalf of some %%party|party%%, because parties are not considered to be capable of acting.[^1] Agents must act in accordance with the party for which they execute such actions, which means that for every kind of action, such parties must provide the proper guidance for their agents, e.g. in terms of policies (rules), working instructions, programs etc. We use the term %%digital agent|digital-agent%%
### Short Description
%%Actors|actor%% execute %%actions|action%% for, or on behalf of some %%party|party%% (the %%principal|principal%% of that agent), because parties are not considered to be capable of acting.[^1] Agents must act in accordance with their %%principal|principal%%, which means that for every kind of action, the principal must provide the proper guidance for their agents, e.g. in terms of policies (rules), working instructions, programs etc. We use the term %%digital agent|digital-agent%% to refer to agents that operate in a digital domain.
## Purpose
### Purpose
The ability to distinguish between (non)agents is relevant in many situations, including:
- electronic communication: the agent
## Criterion:
a property that is attributed to an %%Actor|actor%% whenever it is executing an action for, or on behalf of some %%party|party%%.
### Criterion
a property that is attributed to an %%Actor|actor%% whenever it is executing an action for, or on behalf of some %%party|party%% (its %%principal|principal%%).
## Examples:
### 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.
......@@ -28,5 +28,5 @@ a property that is attributed to an %%Actor|actor%% whenever it is executing an
- 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.
## Background:
### Background
The %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
......@@ -8,14 +8,14 @@ stage: draft
hoverText: "Concept-file: a file that defines/specifies a concept."
---
## Short Description
### Short Description
A **concept-file** is a file that contains documentation about a specific %%concept|concept%%. To faciliate authors, a self-explanatory [template file](/terminology-engine-v1-templates/concept-file.md) is available.
## Purpose
### Purpose
The ability for people to determine whether or not they are talking about the same 'thing' (idea, concept), is prerequisite for knowing that they (correctly) understand one another - which doesn't imply they agree with each other. Concept files provide the documentation of such %%things|concept%% that contribute to this ability.
## Criterion:
### Criterion
a file that defines/specifies a concept.
## Examples:
### Examples
the file that contains this text is an example of a concept-file.
......@@ -8,33 +8,33 @@ stage: draft
hoverText: "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."
---
## Short Description
### Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
A Concept tries to capture the idea behind a classification of entities[^1], allowing us to reason about everything in the class as if it were one thing. For example, the ideas ([mental representations](https://en.wikipedia.org/wiki/Mental_representation)) you have when processing the sentences "I can drink beer from a beer glass' and 'I can drink beer from a coffee mug' shows that the concepts that are behind 'beer glass' and 'coffee mug' differ. Note that in order to communicate about this idea, we also need a word or phrase (i.e.: a termat we can use to refer to (instances of) this idea.
## Purpose
### 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?-->
Working together is easier when you and your peers share the same ideas. We need a way to test and ensure, that you and your peers _actually_ have the same understanding, for the purpose of making cooperation easier. Doing so is expected to not only reduce the number of terminological discussions, but also improve the efficiency and effectiveness of the remaining discussions.
## Criteria
### 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.-->
A (description/specification of a) Concept MUST be [intensionally defined](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions), i.e. associated with a criterion that can be used to determine whether or not someone or something qualifies as (an instance of) that Concept, and that has the property that it has been shown that the vast majority of contributors and other users apply it in the same manner in different situations (i.e. they arrive at the same conclusion as to whether or not someone or something qualifies under that criterion in any given situation).
## Examples
### Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `Concept`, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.-->
## Related Concepts
### Related Concepts
<!--Link to any %%concepts|concept%% that are similar but distinct, with a note about the relationship.-->
* Term is a label that is used in some context to refer to a %%Concept|concept%%[^2], the set of entities that satisfy the concept's criteria, or an arbitrary element of that set. Different contexts may use different terms to refer to a single concept. In a single context, a single term should be used to refer to an individual concept.
* %%Term|term%% is a label that is used in some context to refer to a %%Concept|concept%%[^2], the set of entities that satisfy the concept's criteria, or an arbitrary element of that set. Different contexts may use different terms to refer to a single concept. In a single context, a single term should be used to refer to an individual concept.
* Concept ... ("Scope") is related in several ways. First, there is (precisely, or at most one) Scope that governs the definition/specification of the Concept. Second, there may be (any number of) Scopes that use the Concept, i.e. within which Terms are defined that refer to the Concept
* %%Scope|scope%% is related in several ways. First, there is (precisely, or at most one) Scope that governs the definition/specification of the Concept. Second, there may be (any number of) Scopes that use the Concept, i.e. within which Terms are defined that refer to the Concept
* Concept ... ("Conceptual Model") is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents.
* %%Mental(or Conceptual) Model|pattern%% is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents.
## Background:
### Background
The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
## Domains
### Domains
<!--In which general knowledge ecosystems or mental model families does this concepty a role?-->
* essifLab
* ToIP
......@@ -43,17 +43,17 @@ The %%terminology pattern|pattern-terminology%% provides an overview of how this
* NIST
* ...
## Tags
### Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
* Terminology
## Use-cases
### 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 ``Concept`` to/in that situation;
- shows the relevance of having ``Concept`` for the use-case as opposed to not having it.-->
## Notes
### 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 between concepts and the (multitude of) terms](https://simple.wikipedia.org/wiki/Concept) (names, labels) that we need to be able to talk and reason (argue) about them. Please consider that
......@@ -62,7 +62,7 @@ There is an important [distinction between concepts and the (multitude of) terms
* 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.
---