Commit b56eec81 authored by Rieks Joosten's avatar Rieks Joosten

Merge branch 'terminology-rieks' of...

Merge branch 'terminology-rieks' of https://gitlab.grnet.gr/essif-lab/framework into terminology-rieks

# Conflicts:
#	docs/notations-and-conventions.md
#	docs/terms/action.md
#	docs/terms/actor.md
#	docs/terms/agent.md
#	docs/terms/colleague.md
#	docs/terms/concept-file.md
#	docs/terms/corpus.md
#	docs/terms/credential.md
#	docs/terms/definition.md
#	docs/terms/dictionary-file.md
#	docs/terms/dictionary.md
#	docs/terms/digital-actor.md
#	docs/terms/digital-agent.md
#	docs/terms/digital-colleague.md
#	docs/terms/digital-policy.md
#	docs/terms/employee.md
#	docs/terms/employer.md
#	docs/terms/glossary-file.md
#	docs/terms/glossary.md
#	docs/terms/holder-policy.md
#	docs/terms/holder.md
#	docs/terms/issuer-policy.md
#	docs/terms/issuer.md
#	docs/terms/jurisdiction.md
#	docs/terms/knowledge.md
#	docs/terms/legal-entity.md
#	docs/terms/legal-jurisdiction.md
#	docs/terms/mental-model.md
#	docs/terms/organization.md
#	docs/terms/owner.md
#	docs/terms/party.md
#	docs/terms/pattern-file.md
#	docs/terms/pattern-party-actor-action.md
#	docs/terms/pattern.md
#	docs/terms/peer-agent.md
#	docs/terms/peer-party.md
#	docs/terms/policy-governor.md
#	docs/terms/policy.md
#	docs/terms/presentation-request.md
#	docs/terms/principal.md
#	docs/terms/risk.md
#	docs/terms/scope-file.md
#	docs/terms/scope.md
#	docs/terms/semantics.md
#	docs/terms/ssi-agent.md
#	docs/terms/term-file.md
#	docs/terms/term.md
#	docs/terms/terminology.md
#	docs/terms/transaction-result-dispatcher.md
#	docs/terms/trd-policy.md
#	docs/terms/tve-policy.md
#	docs/terms/validated-data.md
#	docs/terms/verifiable-credential.md
#	docs/terms/verified-data.md
#	docs/terms/verifier-policy.md
#	docs/terms/verifier.md
#	docs/terms/wallet-policy.md
#	docs/terms/wallet.md
#	static/images/patterns/pattern-party-actor-action.png
parents 74cae6a6 7694ff8b
Pipeline #17085 passed with stage
in 2 minutes and 1 second
......@@ -13,3 +13,6 @@ yarn-error.log*
start_server.bat
*.ffs_batch
*.lnk
docs/vscode-%%-batch-replacer.txt
**/zzz-*
docs/test.md
......@@ -17,7 +17,7 @@ Documentation on these and other header fields can be found [here](https://v2.do
The Terminology Engine plugin of GRNET uses additional header fields. These are (or will be) defined [here](./docs/terminology-contributions).
The `sidebars.js` file contains the basic mechanism for [distributing content among sections](https://v2.docusaurus.io/docs/docs-introduction#sidebar) and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/introduction)). Subsections within the `.md` file (that is, tagged with `##`) will appear at the right part of the page (see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)).
The `sidebars.js` file contains the basic mechanism for [distributing content among sections](https://v2.docusaurus.io/docs/docs-introduction#sidebar) and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/project)). Subsections within the `.md` file (that is, tagged with `##`) will appear at the right part of the page (see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)).
## Inserting Images in docs
<!-- **DEPRECATED** Images must be put inside the directory `static/images` and developers must refer to them using _relative_ urls.
......@@ -139,7 +139,7 @@ e.g. `./docs/terms/party.md`. You can use the following syntax to reference
this term in your documentation page:
```
Some content that wants to reference the %%Party|party%% term
Some content that wants to reference the %%party|party%% term
```
When the script runs, this will be replaced as follows:
......
This diff is collapsed.
---
id: vision-and-purpose
title: eSSIF-Lab Vision and Purpose
sidebar_label: Vision and Purpose
---
import useBaseUrl from '@docusaurus/useBaseUrl';
The eSSIF-Lab vision is that Self-sovereign Identity (SSI) will *empower European and other citizens* by providing new means to manage privacy by eliminating logins and making electronic transactions fast and safe both in the Internet and in physical life. SSI will *empower European organisations and governments* by providing new means to speed up, secure and automate transactions with citizens, customers, suppliers and partners, resulting in tens of billions of euros savings annually on administrative costs in Europe. SSI will be *a new business ecosystem paradigm* with thousands of new jobs, many new job categories and new business opportunities for existing and new European companies. And last, but certainly not least, SSI fosters *inclusiveness* and supports organizations and citizens to exercise their rights and fulfil their duties under the GDPR.
The current situation is that SSI solutions that are being created and brought to the market either target specific applications for which they provide a vertical solution (‘stovepipes’), many need some kind of centralized governance/control, others have privacy issues, and none that we know of are interoperable with other such solutions.
The situation we would like to see is one in which we have SSI-enabled, interoperable, scalable and business/information agnostic technologies, that form an infrastructure that every application for every party can use to serve its own objectives. This infrastructure, that enables the electronic exchange of verified (personal and non-personal) data, must be so easy to access and use for such parties that they will no longer need to be concerned about actual (SSI) technologies that have empowered them to make this happen. Rather, they will only need to think about, and decide which kinds of information they want to obtain for conducting specific business transactions and which parties they trust for providing such information. Also, they will need to think about, and decide which kinds of information they themselves are willing to provide to others in this new SSI world.
:::tip **The purpose of the eSSIF-Lab...**
... is to specify, develop and validate technological and non-technological means that support people, businesses and governments to think about, design and operate their (information) processes and (electronically) conduct business transactions with one another.
:::
The context of the eSSIF-Lab vision can be found in articles 8-10 of the [*European Convention on Human Rights (ECHR)*](https://www.echr.coe.int/Pages/home.aspx?p=basictexts/convention), that state the rights of individuals regarding their privacy, and their freedoms to collect, process, store, and express information in a self-sovereign fashion, i.e. in a way that they can decide for themselves. This is without prejudice to Member States’ laws that exist to protect their national security, public safety, the economic well-being of the country, health or morals or the rights and freedoms of others, or to prevent disorder or crime. The eSSIF-Lab vision extends these rights and freedoms - within the limits of the law - to public and private organizations. Thus, we say that individuals as well as public and private organizations (that we collectively refer to as ‘parties’) are self-sovereign[^1].
In the context of these rights and freedoms, we seek to support %%electronic business transactions|business-transaction%%, i.e. the electronic exchange of goods, services, funds, or data between parties, which we call ‘participants’ to the transaction[^2].
An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic %%(digital) agent|digital-agent%%, i.e. equipment (e.g. an app on a mobile phone, a webserver, a browser, …) that acts on behalf of its owner in the transaction.
## High-Level Example of a Business Transaction
In its simplest form, this may be envisaged as one party (requestor) that requests another party (provider) to provide some product, e.g. a parking permit, by using his web-browser to navigate to the web-server of the provider (e.g. his municipality) where he is prompted to fill in a form to provide the details of his request (such as name, address, plate number, etc.). When the form is submitted, the provider decides whether or not to service the request (provide the parking permit) based on the data in the form, and take actions accordingly.
In order for this to work, the provider must design the form such that when a requestor submits a completed form, it can actually decide whether or not to service the request. This has two parts: first, the provider must specify the argument (i.e. the way of reasoning) that it uses to reach this decision - i.e. provide the parking permit. Doing so implicitly specifies the kinds of data that the form will ask for. Secondly, the provider must decide for each of the data it receives, whether or not it is valid to be used in that argument - the process of deciding this is called ‘validation’. Common criteria that help to make this distinction include whether or not the data is presented in the expected format, whether or not it is true (not so easy), whether it is not outdated, or whether or not it satisfies validation rules (in the example, the municipality may require that the specified license plate belongs to a car owned by the person that requests the permit). Validation is important, because reasoning with invalid data may result in wrong conclusions and cause damage.
Perhaps the most important contribution that the eSSIF-Lab project aims to make, is to create a ubiquitously used infrastructure for designing, filling in, and validating forms (not just web-forms, but also for ‘forms’ - e.g. JSON objects - in API requests). The benefits this will bring are enormous, but outside the scope of this document to list.
The figure below is a high-level visualization of the filling in and validation parts:
<img
alt="High-level visualization of the filling in and validation of a form."
src={useBaseUrl('images/vision-context.png')}
/>
*Figure 1. High-level visualization of the filling in and validation of a form.*
The transaction that is envisaged here is the issuing of a parking permit. Participants are a person (requestor) that requests such a permit, and an organization (provider) that can issue such a permit. The requestor has one electronic agent, *the Requestor Agent (RA)*, i.e. an SSI-aware app on their mobile phone that can access a secure storage that contains ‘credentials’, i.e. data that is digitally signed by some third party, thus attesting to the truth of that data. The provider has two agents: one is an SSI-aware component *Provider Agent (PA_* that works with the web-server that presents the form, and the other is a person *P* whose task is to validate any data (on behalf of the provider) that is not validated electronically. The form itself contains a means, e.g. a QR-code or a deep-link, that allows *RA* and *PA* to set up a secure communications channel (e.g. SSL, [DIDComm](https://openssi.github.io/peer-did-method-spec/)) and agree on the specific form that needs to be filled in.
After the *RA* and *PA* have established a communications channel and agree on the form to be filled in, *PA* informs *RA* about the information it needs to fill in the form, and the requirements that this information should satisfy[^3]. *RA* then checks its data store to see whether or not such data is available, sends such data to *PA*, which subsequently validates it and uses it to fill in (appropriate parts of) the form. Finally, *P* validates the remaining data, which either results in a ‘clean’ form, i.e. a form that contains valid data that can subsequently be used to decide whether or not to provide the parking permit, or a message to the requester informing him about missing and/or invalid data.
When the transaction has been completed, both participants can issue a credential that attests to the results of the transaction. For example, the provider could issue a credential stating that the requestor has obtained a parking permit for a car with a specific plate number (and other attributes). The requestor can store this credential and from that moment on use it in new electronic transactions.
--------
[^1]: We realize that by doing this we have a different definition of what self-sovereignty entails than many others. We are open to suggestions for a better phrase.
[^2]: A good mental model for describing and designing transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations).
[^3]: Since transactions are symmetric, the requestor could also have a form that the provider needs to fill in so as to provide the requestor with the data it needs to commit to that transaction. We have left that out of this description for the sake of simplicity.
This diff is collapsed.
---
id: governance
title: eSSIF-Lab Governance
sidebar_label: Governance
scopeid: essifLab
---
## Purpose
The [eSSIF-Lab functional architecture](functional-architecture) identifies and describes a variety of generic SSI functions (capabilities), such as %%holder|holder%%, %%verifier|verifier%%, %%issuer|issuer%%, %%wallet|wallet%%, and more. An %%actor|actor%% that can provide such (generic) capabilities can only _actually_ provide them for a %%party|party%% if it knows how to to comply with the %%rules, working-instructions, preferences and other guidance|policy%% of that %%party|party%%.
**Governance** is the process by which %%parties|party%% decide how to make decisions, how %%actors|actor%% that work on their behalf are to behave and operate, and ensure this guidance ends up in some document which we will call a %%policy|policy%%.
## Governance processes and Policies
Within the context of eSSIF-lab, pretty much every function/capability that is defined also mentions a corresponding %%(digital) policy|digital-policy%% that is the place where rules, working-instructions, preferences and other guidance (e.g. preferences) are expected to be specified for the correct functioning of a technical component that may provide such a capability.
The structure of these %%digital policies|digital-policy%% depends on the design of the technical component, as different kinds of technical components that (still) implement the same capability may have limitations or additional features regarding that capability.
It is the intention of eSSIF-Lab, however, to at least state some minimal requirements for the policies of various functionalities.
\ No newline at end of file
......@@ -5,7 +5,6 @@ title: Notations and Conventions
This document provides an overview of the notations and conventions being used within eSSIF-Lab.
### RFC 2119
We shall use keywords such as “shall”, “should”, “may” etc. as defined by [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
......@@ -20,10 +19,13 @@ We are working towards deprecating this convention, as we now have better ways o
%%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation, as follows:
- a **rectangle** represents a (named) concept. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct.
- a **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. We may refer to the concept at the arrowhead as the ‘target concept’ (TGT) for that relation. Similarly, the concept at the other end will be referred to as the ‘source concept’ (SRC) for that relation. Names are chosen such that `<SRC> <relation name> <TGT>` is a phrase that suggests the intension(al definition) of that relation.
- a **green name** at either end of a relation/association is what UML calls 'role'; this name may be used to refer to (an instance of) the concept at which the name is placed as it performs its/this role in this relation.
- a **dashed line** signifies that its intension is created by combination the intensions of other relations (it is a ‘shorthand’ for a path of other relations).
- an **open-ended arrow** is an ‘ISA’ relation, which can be read as `<SRC> ISA <TGT>`. It means that SRC is a specialization of TGT (which is a generalization of SRC). Thus, SRC must satisfy all constraints that TGT must satisfy, and has all attributes (including properties) that TGT has.
- **Multiplicities** use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended.
- A **concept that is coloured red(dish)** represents a notion that is commonly used ‘in the wild’ (and hence needs not be defined here), relates to one or more concepts we need for the pattern, yet is not the same. We include such ‘red concepts’ to help readers identify and subsequently bridge gaps between commonly held thoughts and the (sometimes subtly) different meanings we need in our model.
\ No newline at end of file
- A **rectangle** represents a (named) concept that is explicitly defined. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct.
- A **rectangle that is coloured red(dish)** represents a (named) concept that is commonly used ‘in the wild’ (and hence needs not be defined here), relates to one or more concepts that are explicitly defined yet is not the same. We include such ‘red concepts’ to help readers identify and subsequently bridge gaps between commonly held thoughts and the (sometimes subtly) different meanings we need in our model.
- A **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. We may refer to the concept at the arrowhead as the ‘target concept’ (TGT) for that relation. Similarly, the concept at the other end will be referred to as the ‘source concept’ (SRC) for that relation. Names are chosen such that `<SRC> <relation name> <TGT>` is a phrase that suggests the intension(al definition) of that relation.
- A **solid line with an open arrowhead** represents an ‘ISA’ relation, which can be read as `<SRC> ISA <TGT>`. It means that SRC is a specialization of TGT (which in turn is a generalization of SRC). It means that SRC must satisfy all constraints that TGT must satisfy, and also that it has all attributes (including properties) that TGT has.
- A **solid line with a solid diamand** at one end is a composition; the element at the 'non-diamond-end' of the line is 'part of' (the 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' also cease to exist.
- A **solid line with a hollow diamand** at one end is an aggregation; the element at the 'non-diamond-end' of the line is 'part of' (the 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' usually do not cease to exist, but 'live on'.
- A **green name** at either end of a relation/association is what UML calls 'role'; this name may be used to refer to (an instance of) the concept at which the name is placed as it performs its/this role in this relation.
- A **dashed line** with a closed arrow (solid triangle) signifies that its intension is created by combination the intensions of other relations (it is a ‘shorthand’ for a path of other relations).
- A **dashed line** with a pointed arrow (`>`) represents a dependency, where the SRC concept somehow depends on the TGT concept. The kind of dependency is specified by `<<text>>`, where `text` specifies the kind of dependency. Example: `<<instance>>` says that SRC is an instance (or: instantiates) TGT.
- **Multiplicities** (or: **cardinalities**) use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended.
---
id: essifLab-pattern-list
title: "eSSIF-Lab List of Patterns"
title: "eSSIF-Lab Ways of Thinking"
sidebar_label: Mental Models
---
:::info Editor's note
:::note Editor's note
TNO to write the introduction paragraph
Remainder of file to be generated (GRNET plugin/extension)
Remainder of file to be generated (GRNET plugin/extension) - currently, the file is maintained 'by hand'
:::
Within eSSIF-Lab, we maintain a set of %%mental models|mental-model%%, i.e. casual and formal descriptions (patterns) of %%concepts|concept%%, relations between them, and constraints, that provide a specific 'viewpoint', or 'way of thinking' about a certain topic.
:::info Editor's note
While some of the topics listed below are pretty much done, others are still need more work.
:::
We currently have models for the following topics:
- [Duties and Rights](./terms/pattern-duties-and-rights): The Duties and Rights pattern describes the relations between Jurisdictions, Legal Entities and the duties and rights they have within them.
- [Guardianship relationships](./terms/pattern-guardianship): The Guardianships pattern captures the Concepts and relations that explain what a generic Guardianship consists of, and how it relates to Guardians, Dependents, Jurisdictions, etc.
- [Jurisdictions](./terms/pattern-jurisdiction): The Jurisdictions pattern captures the Concepts and relations that explain what a generic Jurisdiction consists of, and relates it to Parties and Legal Entities.
- [Mandates, Delegation and Hiring](./terms/pattern-mandates-delegation-hiring): The Mandates, Delegation and Hiring pattern (which remains to be documented) captures the ideas behind Mandating, Delegating, Hiring and their relations. This is a work-in-progress.
- [Parties, Actors and Actions](./terms/pattern-party-actor-action): The Parties, Actors and Actions pattern captures the foundational concepts and relations that we need for thinking about how things get done. It answers questions such as: 'Who/what does things?', 'How are their actions being guided/controlled?', 'Who controls whom/what?', 'Who/what may be held accountable?'.
- [Terminology:](./terms/pattern-terminology): The eSSIF-Lab Terminology Pattern describes the relations between Terminology Terms such as 'Concept', 'Term', 'Pattern', 'Mental Model', 'Glossary' etc.
---
id: introduction
title: Introduction
sidebar_label: eSSIF-Lab
id: project
title: The eSSIF-Lab Project
sidebar_label: eSSIF-Lab Project
---
The European Self-Sovereign Identity Lab ([eSSIF-Lab](https://essif-lab.eu/)) views itself as an ecosystem of parties
The European Self-Sovereign Identity Lab ([eSSIF-Lab](https://essif-lab.eu/)) views itself as an ecosystem of %%parties|party%%
that work together to make existing (and new) Self-Sovereign Identity (SSI) technology into
a scalable and interoperable infrastructure that businesses can use very easily
for conducting (business) transactions with other businesses and individuals alike.
......@@ -20,7 +20,7 @@ One of the overarching activities in eSSIF-Lab is the design, maintenance and va
- [Vision and purpose](vision-and-purpose)
- [Functional architecture](functional-architecture)
- [Concepts & Terminology](terminology)
- [Terminology](terminology)
For interop purposes, we also maintain a page related to [SSI standards](ssi-standards).
......
......@@ -5,8 +5,6 @@ sidebar_label: Contributing to the Terminology Effort
scopeid: essifLab
---
import useBaseUrl from '@docusaurus/useBaseUrl';
:::info **UNDER CONSTRUCTION**
TNO to provide further contents
:::
......
......@@ -6,6 +6,7 @@ type: concept
typeid: conceptID
stage: draft
hoverText: "ConceptID: popuptext for 'conceptID' (tbd)."
glossaryText: "popuptext for 'conceptID' (tbd)."
---
<!--A concept tries to capture the idea behind a classification of entities, allowing us to reason about everything in the class as if it were one thing. This file specifies the idea(s) that, within the scope of `<existing-scopeID>` will be referred to using `<New Term>`.
Please fill in the placeholders in this file as follows:
......
......@@ -6,6 +6,7 @@ type: dictionary
typeid: dictionaryID
stage: draft
hoverText: "DictionaryID: popuptext for 'dictionaryID' (tbd)."
glossaryText: "popuptext for 'dictionaryID' (tbd)."
---
<!--A dictionary is an alphabetically sorted list of terms with associated meanings that originate from multiple scopes.
This template lets you define the specifications according to which a specific dictionary is generated.
......
......@@ -6,6 +6,7 @@ type: glossary
typeid: glossaryID
stage: draft
hoverText: "GlossaryID: popuptext for 'glossaryID' (tbd)."
glossaryText: "popuptext for 'glossaryID' (tbd)."
---
<!--A glossary is an alphabetically sorted list of terms with (short) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s).
Please fill in the placeholders in this file as follows:
......
......@@ -6,6 +6,7 @@ type: pattern
typeid: patternID
stage: draft
hoverText: "PatternID: popuptext for 'patternID' (tbd)."
glossaryText: "popuptext for 'patternID' (tbd)."
---
<!-- 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:
......@@ -24,7 +25,7 @@ Please fill in the placeholders in this file as follows:
### 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 -->
### <!-- any number of other sections, as is fit for describing the pattern -->
<!-- text as appropriate for such a section -->
<!--
......
......@@ -6,6 +6,7 @@ type: scope
typeid: scopeID
stage: draft
hoverText: "ScopeID: popuptext for 'scopeID' (tbd)."
glossaryText: "popuptext for 'scopeID' (tbd)."
---
<!--A scope is something within which concepts can be associated with terms, thereby creating a vocabulary that can be used to meaningfully express ideas, arguments, etc.
Please fill in the placeholders in this file as follows:
......
......@@ -6,6 +6,7 @@ type: type
typeid: typeID
stage: draft
hoverText: "TypeID: popuptext for 'typeID' (tbd)."
glossaryText: "popuptext for 'typeID' (tbd)."
---
<!--This template specifies the docusaurus attribtues that must be in place for the terminology-plugin to function properly. For specific generators, additional content may be required. That should be specified in the individual templates that specify the artifacts that such generators create.
The header-attributes contain the following placeholdes:
......
// Purpose: replace %-marked words (including some varieties such as plurals) with %%-syntax for those words.
// This is a script that can be run by the Batch Replacer extension of VSCode .
// Press Ctrl-Shift-P as you are editing this script, then search for `Batch Replacer`, and execute it.
// Executing the script will do the following replacements consecutively:
// 1. `%text with possibly spaces%` --> `%%text with possibly spaces%%`
// 2. `%text-without-spaces` --> `%%text-without-spaces%%` (some punctuation around it is allowed)
// 3. `%%Show Text%%` --> `%%Show Text|Show-Text%%` (sorry, we cannot make the reftext lowercase)
// Now, you have to manually execute /(?<=\|)([A-Z][^%]*)(?=%%)/\L$1/g/
// 4. `|ref-text%% is being checked to see if modifications need to be made (e.g. plurals to singular etc.)
// 5. There is a cleanup phase that removes any %%...|...%% syntax from the docusaurus header, markdown headers, and <img /> constructs.
// Complex regular expressions can be created using variables. Variables are applied to the entire script, and should be defined at the beginning of the script. Variables are defined as ... = "..." and are used as %{...}. Variables can only be used in the replace and replace-regex instructions.
// variables can reference themselves and be overwritten - see documentation of 'batch replacer' extension
beg = "(?<=\W%%)"
mid = "(?<=\|)"
end = "(?=%%\W)"
ss = "(?:['’]?s|\(s\))?"
dutyright = "(?:dut(?:y|ies)|rights?)"
dutyright = "%{dutyright}(?:-*(?:/|and|or|and/or)-*%{dutyright})?"
dutyrighttype = "%{dutyright}-types?"
// If you do not specify the files to work on, the replace will be global (throughout the workspace).
// `filter "document.txt"` - document.txt file in the root folder
// `filter "Documents/document.txt"` - document.txt file in the Documents folder in the root folder
// `filter "**/document.txt"` - document.txt files anywhere
// `filter "*.txt"` - any .txt file in the root folder
// `filter "**/*.txt"` - any .txt file
filter "docs/functional-architecture.md"
// PREPROCESSING: convert single-%-notations into %%-notations.
// Convert quotes so that only two types remain: ' an "For starte
replace-regex "[‘’]"
with "'"
// We might want to 'undo' %%...|...%% markers in case some 'show text' needs to be associated wiht another 'reftext'
// replace-regex "(?<=\W)%%([^\|\n\r]+)\|[^%\n\r]+%%(?=\W)"
// with "%$1%"
// First, convert %show text% into %%show text%%
// Test set: none may match: %verif%er, %verif"ier%, "%verifier%", `%verifier%`
// Test set: all must match: %my verifier%, ('%verifiers%'), %verifier's%, %verifier’s%, (%(ver)/ifier%):., %(our) (vfyr)%, %verifier's%. %verifier’s%... single-%party%), '**subject (of a %party%)**' to
// replace-regex "(?<=\s\(?%)(\w|\s|\(|\)|[/-’'"])+(?=%([)":,.!?]*\s|-\w))"
replace-regex "(?<=[-\s]\(?'?%)([^%]+)(?=%(([*_):;,.'!?]|\[[^\]]*\]){0,5}\s|-\w))"
with "%$1%"
// Only thereafter can we convert %showtext (words without trailing `%`-char) into %%showtext%%
// Test set: none may match: %verif%er, %(our) (verifier)%,
// Test set: all must match: %verifier %verifiers, '%verifier'), %verifier's, %verifier’s, %verifier:, (%verifiers), %verifier's..... %verifier’s,?.!? its %principal.[^DC.4] Also a %party)'
replace-regex "(?<=(?:\s\(?'?|/)%)((\w+((/|-|’|')\w)?)+)(?='?\)?[:;,.!?]*(\[[^\]]*\])?\s)"
with "%$1%%"
// Then, we can expand %%show text%% into %%show text|show text%%
replace-regex "(?<=\W)%%([^\|]*?)%%(?=\W)"
with "%%$1|$1%%"
// Next, we convert the latter part into lowercase
replace-regex "(?<=\|)([^A-Z%]*?[A-Z].*?)(?=%%)"
with-case "lowercase"
// Next, we replace whitespace in `lowercase show text` instances with `-` characters
replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
with "$1-$2"
replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
with "$1-$2"
replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
with "$1-$2"
replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
with "$1-$2"
replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
with "$1-$2"
// ACTUAL PROCESSING: now we need to convert well-known `lowercase-show-text`s to appropriate `reftexts`
// [A]
replace-regex "%{mid}(action|actor|agent|assertion|author)%{ss}%{end}"
with "$1"
// [B]
replace-regex "%{mid}(business-transaction)%{ss}?%{end}"
with "$1"
// [C]
// for 'claim', see 'statement'
replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)%{ss}?%{end}"
with "$1"
replace-regex "%{mid}communications?-(channel|session)%{ss}?%{end}"
with "communication-$1"
// [D]
replace-regex "%{mid}(definition|dependent|dictionary-file|dictionary|documentation-interop)%{ss}?%{end}"
with "$1"
replace-regex "%{mid}\(?(?:electronic|digital)\)?-(actor|agent|colleague|communication-channel|policy)%{ss}%{end}"
with "digital-$1"
replace-regex "%{mid}(%{dutyrighttype}|%{dutyright})%{end}"
with "pattern-duties-and-rights"
replace-regex "%{mid}data-(collector|discloser)-polic(y's|ies)%{end}"
with "data-$1-policy"
replace-regex "%{mid}data-(collector|discloser)%{ss}?%{end}"
with "data-$1"
// [E]
replace-regex "%{mid}(employee|employer)%{ss}%{end}"
with "$1"
replace-regex "%{mid}(legal-)?entit(y's|ies)%{end}"
with "$1entity"
// [G]
replace-regex "%{mid}(glossary-file|guardian(ship)?(-relationship)?(-type)?)%{ss}%{end}"
with "$1"
replace-regex "%{mid}glossar(y's|ies)%{end}"
with "glossary"
replace-regex "%{mid}guardianship(-relationship)?%{end}"
with "guardianship"
replace-regex "%{mid}guardianship(-relationship)?-type%{end}"
with "guardianship-type"
replace-regex "%{mid}govern(or)?s?%{end}"
with "governance"
// [H-I-J-K] (all holder, issuer, verifier and wallet stuff, too)
// for associated policies, see [P]
replace-regex "%{mid}(holder|issuer|verifier|wallet|identifier|jurisdiction(-governor)?|knowledge(-governor)?)%{ss}%{end}"
with "$1"
// [L-M]
replace-regex "%{mid}(legal-jurisdiction|legal-system|mental-model)%{ss}%{end}"
with "$1"
// for 'legal entities', see 'entities'
// [O]
replace-regex "%{mid}(objective|organization|owned|owner|ownership)%{ss}%{end}"
with "$1"
// [P]
replace-regex "%{mid}(participant|pattern-file|pattern|(peer-)(actor|agent)|policy-governor|presentation-request|presentation|principal)%{ss}%{end}"
with "$1"
replace-regex "%{mid}(|peer-)part(y's|ies)%{end}"
with "$1party"
replace-regex "%{mid}(|issuer-|holder-|verifier-|wallet-|transaction-data-(collector|discloser)-)polic(y's|ies)%{end}"
with "$1policy"
// [R-S]
// For 'rights', see [D]uties
replace-regex "%{mid}(risk|scope-file|scope|ssi-agent)%{ss}%{end}"
with "$1"
replace-regex "%{mid}(statement|claim|statement%{ss}/claim)%{ss}%{end}"
with "assertion"
// [T]
// for transaction data collector/discloers policies, see [P]
replace-regex "%{mid}(term-file|term|transaction-(agreement|data-(collector|discloser)|form|proposal))%{ss}%{end}"
with "$1"
replace-regex "%{mid}transaction%{ss}?%{end}"
with "business-transaction"
// [V]
// for verifier stuff - see holder
replace-regex "%{mid}(verifiable-credential|verifier)%{ss}%{end}"
with "$1"
replace-regex "%{mid}vocabular(y's|ies)%{end}"
with "vocabulary"
// [W]
// for wallet stuff - see holder
// CLEANING UP UNINTENDED CHANGES
// Remove all `%%showtext|reftext%%` in docusaurus header.
replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)"
with "$1$2"
replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)"
with "$1$2"
replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)"
with "$1$2"
replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)"
with "$1$2"
replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)"
with "$1$2"
// Remove all `%%showtext|reftext%%` occurrences in markdown headers
replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)"
with "$1$2$4"
replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)"
with "$1$2$4"
// Remove all `%%showtext|reftext%%` occurrences in `<img />`-constructs
replace-regex "(<img(?:(?:.|[\n])(?!/>))*?)%%([^\|]*)\|(?:[^%]*)%%"
with "$1$2"
replace-regex "(<img(?:(?:.|[\n])(?!/>))*?)%%([^\|]*)\|(?:[^%]*)%%"
with "$1$2"
......@@ -2,7 +2,7 @@
id: terminology-plugin-instructions
title: Terminology & Glossary plugin docs
---
import useBaseUrl from '@docusaurus/useBaseUrl';
import useBaseUrl from '@docusaurus/useBaseUrl'; // All other .md files may get this statement automatically added.
### How it works
......@@ -40,7 +40,7 @@ e.g. `./docs/terms/party.md`. You can use the following syntax to reference
this term in your documentation page:
```
Some content that wants to reference the %%Party|party%% term
Some content that wants to reference the %%party|party%% term
```
When the script runs, this will be replaced as follows:
......@@ -96,7 +96,6 @@ and running, you can visit the test example on the `/docs/replacement-test` page
<img alt="replacement-test" src={useBaseUrl('images/replacement-test.png')}/>
## Generate the glossary page
If everything works well with the above procedure, you can then generate a
......@@ -115,4 +114,4 @@ mentioned above, will be populated in the `glossary.md` page.
When the project is up and running, you can visit the glossary on the `/docs/essifLab-glossary` page:
<img alt="glossary-page" src={useBaseUrl('images/glossary-page.png')}/>
<img alt="glossary-page" src={useBaseUrl('docs/essifLab-glossary.md')}/>
......@@ -9,7 +9,7 @@ When people from various backgrounds (and cultures) work together, it is inevita
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.
## Vision
### Vision
[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.
......@@ -29,17 +29,17 @@ As the corpus is being used, we expect ideas for improvement
[Here](terminology-contributions) is how you may contribute to this terminology effort.
## Terminological Artifacts
### Terminological Artifacts
The terminological artifacts that the eSSIF-Lab Concepts and Terminology effort aims to produce include:
- 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 [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.
Depending on the needs of stakeholders, additional artifacts may be created/generated.
## Notes:
### Notes:
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.
......
---
id: action-type
title: "Action Type"
scopeid: essifLab
type: concept
typeid: action-type
stage: draft
hoverText: "Action Type/Class: the specification of properties and characteristics that that Actions must have to qualify as instance of that class; also: the set of Actions that actually have these properties and characteristics."
glossaryText: "the specification of properties and characteristics that that %Actions% must have to qualify as instance of that class; also: the set of %Actions% that actually have these properties and characteristics."
---
:::info Editor's note
TNO (or others) to provide further content of this file.
:::
......@@ -5,17 +5,20 @@ scopeid: essifLab
type: concept
typeid: action
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."
hoverText: "Action: something that is actually done/executed - by a single Actor (on behalf of a given Party), as a single operation in a specific context."
glossaryText: "something that is actually done/executed - by a single %Actor% (on behalf of a given %Party%), as a single operation in a specific context."
---
### 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.
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 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 a %%policy|policy%% that this %%party|party%% has established for actions of that kind. The actor is assumed to have appropriate access to that policy.
The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
### 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.
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|party%%), and as a consequence may be permitted and/or required to execute them. Also, this ability enables %%parties|party%% to determine the execution-policy, i.e. the set of rules, working-instructions, preferences and other guidance that actors should obey or comply with when exeucting an action on its behalf.
### 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.
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|party%%, i.e. in accordance with the policy rules that this %%party|party%% has established for such actions.
### Examples
- filling in a form and submitting it.
......@@ -24,6 +27,6 @@ An **Action** is something that is done by an actor, can be considered a single
### 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.
- %%actor|actor%%
- %%agent|agent%%
### Background
The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
\ No newline at end of file
......@@ -6,11 +6,14 @@ type: concept
typeid: actor
stage: draft
hoverText: "Actor: Entity that can act (do things), e.g. people, machines, but not Organizations."
glossaryText: "Entity that can act (do things), e.g. people, machines, but not %Organizations%."
---
### 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.
The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
### Purpose