Commit 8d1c3b3d authored by Rieks Joosten's avatar Rieks Joosten

Merge branch 'terminology-rieks' into 'master'

Terminology rieks

See merge request !12
parents 1fa142c6 eb0936e6
Pipeline #17227 passed with stages
in 3 minutes and 19 seconds
......@@ -161,7 +161,7 @@ and it needs to consist of the following structure:
---
id: term
title: Term page
hoverText: This hover text will appear in the documentation page that you reference this term
hoverText: "This hover text will appear in the documentation page that you reference this term."
---
### Term explanation
......
This diff is collapsed.
// Purpose: resolve all merge conflicts by accepting the CURRENT changes (change $1 to $2 to accept INCOMING changese)
// 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.
// 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/**/*.md"
replace-regex "^<<<<<<<.*\n((?:.*\n)*)=======\n((?:.*\n)*)>>>>>>>.*\n"
// To accept CURRENT changes
with "$1"
// To accept INCOMING changes
// with "$2"
......@@ -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).
......@@ -21,12 +20,12 @@ 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 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 **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 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.
......@@ -17,14 +17,14 @@ While some of the topics listed below are pretty much done, others are still nee
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.
- [Duties and Rights](./terms/pattern-duties-and-rights): The Duties and Rights pattern describes the relations between %%jurisdictions|jurisdiction%%, %%legal entities|legal-entity%% 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.
- [Guardianship relationships](./terms/pattern-guardianship): The Guardianships pattern captures the %%concepts|concept%% and relations that explain what a generic %%guardianship|guardianship%% consists of, and how it relates to %%guardians|guardian%%, %%dependents|dependent%%, %%jurisdictions|jurisdiction%%, 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.
- [Jurisdictions](./terms/pattern-jurisdiction): The Jurisdictions pattern captures the %%concepts|concept%% and relations that explain what a generic %%jurisdiction|jurisdiction%% consists of, and relates it to %%parties|party%% and %%legal entities|legal-entity%%.
- [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?'.
- [Parties, Actors and Actions](./terms/pattern-party-actor-action): The %%Parties|party%%, %%Actors|actor%% and %%Actions|action%% pattern captures the foundational %%concepts|concept%% 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.
- [Terminology:](./terms/pattern-terminology): The eSSIF-Lab Terminology Pattern describes the relations between %%terminology|terminology%% artifacts such as '%%concept|concept%%', '%%term|term%%', '%%pattern|pattern%%', '%%mental model|mental-model%%', '%%glossary|glossary%%' etc.
......@@ -26,4 +26,4 @@ For interop purposes, we also maintain a page related to [SSI standards](ssi-sta
## Acknowledgement
This site is part of the eSSIF-Lab project that has received funding from the [European Union’s Horizon 2020 Research and Innovation Programme] under grant agreement Nº 871932.
\ No newline at end of file
This site is part of the eSSIF-Lab project that has received funding from the [European Union's Horizon 2020 Research and Innovation Programme] under grant agreement Nº 871932.
\ No newline at end of file
......@@ -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:
......
......@@ -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:
......
......@@ -10,7 +10,8 @@
// 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.
replace-regex "^<<<<<<<.*\n((?:.*\n)*)=======\n((?:.*\n)*)>>>>>>>.*\n"
with "$1"
// 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
......@@ -18,6 +19,7 @@ beg = "(?<=\W%%)"
mid = "(?<=\|)"
end = "(?=%%\W)"
ss = "(?:['’]?s|\(s\))?"
yies = "(y|y['’]s|ies)"
dutyright = "(?:dut(?:y|ies)|rights?)"
dutyright = "%{dutyright}(?:-*(?:/|and|or|and/or)-*%{dutyright})?"
......@@ -30,7 +32,7 @@ dutyrighttype = "%{dutyright}-types?"
// `filter "*.txt"` - any .txt file in the root folder
// `filter "**/*.txt"` - any .txt file
filter "docs/functional-architecture.md"
filter "docs/terms/*.md"
// PREPROCESSING: convert single-%-notations into %%-notations.
......@@ -82,12 +84,12 @@ replace-regex "%{mid}(action|actor|agent|assertion|author)%{ss}%{end}"
with "$1"
// [B]
replace-regex "%{mid}(business-transaction)%{ss}?%{end}"
with "$1"
-- for 'business-transaction' see 'transaction'
// [C]
// for 'claim', see 'statement'
replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)%{ss}?%{end}"
replace-regex "%{mid}(colleague)(?:-agent)?%{ss}?%{end}"
with "$1"
replace-regex "%{mid}communications?-(channel|session)%{ss}?%{end}"
......@@ -102,7 +104,7 @@ 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}"
replace-regex "%{mid}data-(collector|discloser)-polic%{yies}%{end}"
with "data-$1-policy"
replace-regex "%{mid}data-(collector|discloser)%{ss}?%{end}"
with "data-$1"
......@@ -110,13 +112,13 @@ with "data-$1"
// [E]
replace-regex "%{mid}(employee|employer)%{ss}%{end}"
with "$1"
replace-regex "%{mid}(legal-)?entit(y's|ies)%{end}"
replace-regex "%{mid}(legal-)?entit%{yies}%{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}"
replace-regex "%{mid}glossar%{yies}%{end}"
with "glossary"
replace-regex "%{mid}guardianship(-relationship)?%{end}"
with "guardianship"
......@@ -124,6 +126,8 @@ replace-regex "%{mid}guardianship(-relationship)?-type%{end}"
with "guardianship-type"
replace-regex "%{mid}govern(or)?s?%{end}"
with "governance"
replace-regex "%{mid}(governed(?: by)?|governing-party)?s?%{end}"
with "governor"
// [H-I-J-K] (all holder, issuer, verifier and wallet stuff, too)
// for associated policies, see [P]
......@@ -136,15 +140,15 @@ with "$1"
// for 'legal entities', see 'entities'
// [O]
replace-regex "%{mid}(objective|organization|owned|owner|ownership)%{ss}%{end}"
replace-regex "%{mid}(?:natural-)?(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}"
replace-regex "%{mid}(|peer-)part%{yies}%{end}"
with "$1party"
replace-regex "%{mid}(|issuer-|holder-|verifier-|wallet-|transaction-data-(collector|discloser)-)polic(y's|ies)%{end}"
replace-regex "%{mid}(|issuer-|holder-|verifier-|wallet-|transaction-data-(collector|discloser)-)polic%{yies}%{end}"
with "$1policy"
// [R-S]
......@@ -156,16 +160,16 @@ 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}"
replace-regex "%{mid}(?:business-)?(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}"
replace-regex "%{mid}(data-)?validat(e|ing|ion)(-data)%{end}"
with "validated-data"
replace-regex "%{mid}vocabular%{yies}%{end}"
with "vocabulary"
// [W]
......@@ -174,16 +178,17 @@ with "vocabulary"
// CLEANING UP UNINTENDED CHANGES
// Remove all `%%showtext|reftext%%` in docusaurus header.
replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
with "$1$2$4"
replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
with "$1$2$4"
replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
with "$1$2$4"
replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
with "$1$2$4"
replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
with "$1$2$4"
// This has been commented out because for one reason or another, it doesn't work and sometimes makes the script not terminate.
// 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+.*?)%%([^\|]*)\|([^%]*)%%(.*$)"
......@@ -192,7 +197,7 @@ replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)"
with "$1$2$4"
// Remove all `%%showtext|reftext%%` occurrences in `<img />`-constructs
replace-regex "(<img(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*)(?=/>)"
with "$1$2$4"
replace-regex "(<img(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*)(?=/>)"
with "$1$2$4"
replace-regex "(<img(?:(?:.|[\n])(?!/>))*?)%%([^\|]*)\|(?:[^%]*)%%"
with "$1$2"
replace-regex "(<img(?:(?:.|[\n])(?!/>))*?)%%([^\|]*)\|(?:[^%]*)%%"
with "$1$2"
......@@ -63,7 +63,7 @@ and it needs to consist of the following structure:
id: term
title: Term page
stage: draft
hoverText: This hover text will appear in the documentation page that you reference this term
hoverText: "This hover text will appear in the documentation page that you reference this term."
---
### Term explanation
......
......@@ -5,7 +5,8 @@ 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."
hoverText: "Action Type/Class: the specification of properties and characteristics that such Actions must have in order to qualify as instance of that class, or the set of Actions that actually have these properties and characteristics."
glossaryText: "the specification of properties and characteristics that that %%actions^action%% must have in order to qualify as instance of that class, or the set of %%actions^action%% that actually have these properties and characteristics."
---
:::info Editor's note
......
......@@ -6,6 +6,7 @@ type: concept
typeid: action
stage: draft
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^actor%% (on behalf of a given %%party^party%%), as a single operation in a specific context."
---
### Short Description
......
......@@ -6,6 +6,7 @@ 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^organization%%."
---
### Short Description
......
......@@ -6,6 +6,7 @@ type: concept
typeid: agent
stage: draft
hoverText: "Agent (of a Party): an Actor that is executing an Action on behalf of a Party (called the Principal of that Actor)."
glossaryText: "an %%actor^actor%% that is executing an %%action^action%% on behalf of a %%party^party%% (called the %%principal^principal%% of that %%actor^actor%%)."
---
### Short Description
......
......@@ -6,6 +6,7 @@ type: concept
typeid: assertion
stage: draft
hoverText: "Assertion: a declaration/statement, made by a specific Party, that something is the case."
glossaryText: "a declaration/statement, made by a specific %%party^party%%, that something is the case."
---
:::info Editor's note
......
......@@ -6,6 +6,7 @@ type: concept
typeid: author
stage: draft
hoverText: "Author (of data/document/file/...): a Party, on whose behalf that data/document/file/... has been created and/or updated."
glossaryText: "a %%party^party%%, on whose behalf that data/document/file/... has been created and/or updated."
---
:::info Editor's note
......
......@@ -5,45 +5,8 @@ scopeid: essifLab
type: concept
typeid: business-transaction
stage: draft
hoverText: "Business Transaction: the exchange of goods, services, funds, or data between some Parties (called Participants of the Transaction)."
hoverText: "Business Transaction: a Transaction that constitutes business of its participating Parties."
glossaryText: "See: %%transaction^transaction%%."
---
import useBaseUrl from '@docusaurus/useBaseUrl'
### Short Description
A **business transaction** is an exchange of goods, services, funds, or data between some %%parties|party%%. These %%parties|party%% are called the %%participants of the transaction|participant%%. A typical %%business transaction|business-transaction%% consists of three phases. In the first phase, a %%transaction agreement|transaction-agreement%% is negotiated between the participants. That phase ends when either participant quits the negotiation, or all participants commit to the transaction, which basically is a promise to the other participants that it will keep up its end of the %%transaction agreement|transaction-agreement%%. In the second phase, the participants work to fulfill their promise. That phase ends when they deliver the results, and inform their peers of that they're done. In the final phase, participants check whether or not they have received what was promised, and that it conforms the criteria in the transaction agreement. This may lead to some discussion and possible rectifications. The final phase ends either when one of the participants escalates (e.g. goes to court), or all results are accepted. This way of looking at %%business transactions|business-transaction%% has been described extensively in the [DEMO](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations) transaction model.
:::info Editor's note
TNO (or others) to provide further content/revisions.
:::
:::info Editor's note
Explanation required about '%%commitment decision|commitment-decision%%' (i.e. 'promise' decisions in [DEMO](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations)).
:::
### High Level Example
In its simplest form, this may be envisaged as one %%party|party%% (requestor) that requests another %%party|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|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 %%communication channel|communication-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 %%communication channel|communication-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[^1]. *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]: 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. However, the [eSSIF-Lab functional architecture](../functional-architecture) does take this into account.
\ No newline at end of file
See: %%transaction^transaction%%
......@@ -6,6 +6,7 @@ type: concept
typeid: colleague
stage: draft
hoverText: "Colleagues: two or more (digital or non-digital) Agents that have the same Principal (i.e. Party on whose behalf they exeucte Actions)."
glossaryText: "two or more (digital or non-digital) %%agents^agent%% that have the same %%principal^principal%% (i.e. %%party^party%% on whose behalf they exeucte %%actions^action%%)."
---
:::info Editor's note
......@@ -13,6 +14,6 @@ TNO (or others) to provide the content of this file.
:::
### Purpose
The ability to distinguish between (non) colleagues allows us to reason and communicate about the set of (digital and non-digital) %%actors|actor%% that are %%agents|agent%% for a **principal|principal%%. This is relevant in situations where different %%agents|agent%% excute %%actions|action%% in a single %%business transaction|business-transaction%% on behalf of the same %%principal|principal%%
The ability to distinguish between (non) colleagues allows us to reason and communicate about the set of (digital and non-digital) %%actors|actor%% that are %%agents|agent%% for a **principal|principal%%. This is relevant in situations where different %%agents|agent%% excute %%actions|action%% in a single %%business transaction|transaction%% on behalf of the same %%principal|principal%%
See also: %%digital colleague|digital-colleague%%.
......@@ -6,6 +6,7 @@ type: concept
typeid: commitment-decision
stage: draft
hoverText: "Commitment Decision (of a Party in a Business Transaction): the decision of that Party whether or not to commit to that Business Transaction, i.e. (promise) to fulfill the obligations that the associated Business Transaction Agreement Proposal would impose on that Party once it were signed."
glossaryText: "the decision of that %%party^party%% whether or not to commit to that %%business transaction^transaction%%, i.e. (promise) to fulfill the obligations that the associated %%transaction agreement proposal^transaction-proposal%% would impose on that %%party^party%% once it were signed."
---
:::info Editor's note
......
......@@ -6,6 +6,7 @@ type: concept
typeid: communication-channel
stage: draft
hoverText: "Communication Channel: a (digital or non-digital) means by which two Actors can exchange messages with one another."
glossaryText: "a (digital or non-digital) means by which two %%actors^actor%% can exchange messages with one another."
---
:::info Editor's note
......
......@@ -6,6 +6,7 @@ type: concept
typeid: communication-session
stage: draft
hoverText: "Communication Session: a time interval during which two Actors have an established Communication Channel that does not exist outside of that time interval."
glossaryText: "a time interval during which two %%actors^actor%% have an established %%communication channel^communication-channel%% that does not exist outside of that time interval."
---
:::info Editor's note
......
......@@ -6,6 +6,7 @@ type: concept
typeid: concept-file
stage: draft
hoverText: "Concept-file: a file whose contents defines/specifies a Concept."
glossaryText: "a file whose contents defines/specifies a %%concept^concept%%."
---
### Short Description
......
......@@ -6,6 +6,7 @@ type: concept
typeid: concept
stage: draft
hoverText: "Concept: the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same')."
glossaryText: "the ideas/thoughts behind a classification of %%entities^entity%% (what makes %%entities^entity%% in that class 'the same')."
---
### Short Description
......
......@@ -6,6 +6,7 @@ type: concept
typeid: corpus
stage: draft
hoverText: "Corpus (of Terminology): the documentation that describes the Knowledge around a set of Terms and Concepts."
glossaryText: "the documentation that describes the %%knowledge^knowledge%% around a set of %%terms^term%% and %%concepts^concept%%."
---
:::info Editor's note
......
......@@ -5,7 +5,8 @@ scopeid: essifLab
type: concept
typeid: credential-catalogue
stage: draft
hoverText: "Credential Catalogue (functional component): the capability to register and advertise the information about Credential Types that their respective Governing Parties have decided to disclose so as to enable other Parties to decide whether or not it is beneficial for them to use Credentials of such types."
hoverText: "Credential Catalogue: a functional component that has the capability to register and advertise the information about Credential Types that their respective Governing Parties have decided to disclose so as to enable other Parties to decide whether or not it is beneficial for them to use Credentials of such types."
glossaryText: "a functional component that has the capability to register and advertise the information about %%credential types^credential-type%% that their respective %%governing parties^governor%% have decided to disclose so as to enable other %%parties^party%% to decide whether or not it is beneficial for them to use %%credentials^credential%% of such types."
---
:::info Editor's note
......
......@@ -6,11 +6,12 @@ type: concept
typeid: credential-type
stage: draft
hoverText: "Credential Type: the specification of the contents, properties, constraints etc. that Credentials of this type must have/comply with."
glossaryText: "the specification of the contents, properties, constraints etc. that %%credentials^credential%% of this type must have/comply with."
---
### Short Description
A **credential-type** is a specification that states
- the contents that %credentials of that kind must or may have; this includes of which kinds of %%assertions (claims, statements)|assertion%% as well as meta-data.
- the contents that %%credentials|credential%% of that kind must or may have; this includes of which kinds of %%assertions (claims, statements)|assertion%% as well as meta-data.
- properties Typically, %%parties|party%% that issue %%credentials|credential%% of some %%kind|credential-type%% will advertise the %%credential types|credential-type%% of the %%credentials|credential%% that it may issue.
### Purpose
......
......@@ -6,6 +6,7 @@ type: concept
typeid: credential
stage: draft
hoverText: "Credential: data, representing a set of Assertions (claims, statements), authored and signed by, or on behalf of, a specific Party."
glossaryText: "data, representing a set of %%assertions^assertion%% (claims, statements), authored and signed by, or on behalf of, a specific %%party^party%%."
---
### Short Description
......@@ -15,7 +16,7 @@ In physical credentials, such as drivers licenses and passports, proofs of integ
In digital credentials, such as (digital) certificates or %%verifiable credentials|verifiable-credential%%, the basic proofs (of provenance and integrity) usually consist of a digital signature of some kind. It therefor only 'works' for as long as the associated private/secret key actually remains a secret of the issuing %%party|party%%.
Credentials whose %%assertions|assertion%% refer to some %%entity|entity%%, e.g. a person, an organization, an animal, a shipment, etc. In such cases, it must be possible for arbitrary %%parties|party%% to identify that %%entity|entity%%, and/or verify an %%assertion|assertion%% by some other %%party|party%% that identifies that %%entity%%. To this end, credentials may contain %%assertions|assertion%% about characteristics of that %%entity|entity%%, the idea being that if a %%party|party%% establishes that some %%entity|entity%% has (a sufficient number of) these characteristics, that %%entity|entity%% is the one bound to the credential. Attributes typically include one or more names, various dates, a photograph, etc. Other attributes might include biometrics, RFID-codes, bar-codes, etc.
Credentials whose %%assertions|assertion%% refer to some %%entity|entity%%, e.g. a person, an organization, an animal, a shipment, etc. In such cases, it must be possible for arbitrary %%parties|party%% to identify that %%entity|entity%%, and/or verify an %%assertion|assertion%% by some other %%party|party%% that identifies that %%entity|entity%%. To this end, credentials may contain %%assertions|assertion%% about characteristics of that %%entity|entity%%, the idea being that if a %%party|party%% establishes that some %%entity|entity%% has (a sufficient number of) these characteristics, that %%entity|entity%% is the one bound to the credential. Attributes typically include one or more names, various dates, a photograph, etc. Other attributes might include biometrics, RFID-codes, bar-codes, etc.
The signature on a credential may have other meanings. For example, a %%party|party%% may choose to only sign the credential data if it is convinced of the truth of the statements, in which case the credential 'payload' can be seen as an excerpt of the %%knowledge|knowledge%% of that %%party|party%%.
......
......@@ -6,6 +6,7 @@ type: concept
typeid: data-collector-policy
stage: draft
hoverText: "Data Collector Policy: a Digital Policy that enables an operational Data Collector component to function according to the rules of its Policy Governor."
glossaryText: "a %%digital policy^digital-policy%% that enables an operational %%data collector^data-collector%% component to function according to the rules of its %%policy governor^policy-governor%%."
---
### Short Description
......
This diff is collapsed.
......@@ -6,6 +6,7 @@ type: concept
typeid: data-discloser-policy
stage: draft
hoverText: "Data Discloser Policy: a Digital Policy that enables an operational Data Discloser component to function according to the rules of its Policy Governor."
glossaryText: "a %%digital policy^digital-policy%% that enables an operational %%data discloser^data-discloser%% component to function according to the rules of its %%policy governor^policy-governor%%."
---
### Short Description
......
......@@ -6,6 +6,7 @@ type: concept
typeid: data-discloser
stage: draft
hoverText: "Data Discloser: a functional component that is capable of disclosing data to (Agents of) other Parties, e.g. in the form of Credentials."
glossaryText: "a functional component that is capable of disclosing data to (Agents of) other %%parties^party%%, e.g. in the form of %%credentials^credential%%."
---
### Short Description
......@@ -25,9 +26,9 @@ The purpose of the Data Discloser component is to state the (various, sometimes
A **Data Discloser** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) that is capable of stating (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|party%%.
### Functionality
Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term **subject (of a statement of a Party)** to refer to the entity that this Party knows to exist, and about whom/which the statement has been made.
Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term '**subject (of a statement of a Party)**' to refer to the entity that this Party knows to exist, and about whom/which the statement has been made.
We will use the term **subject-id (of a statement of a Party)** to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not).
We will use the term '**subject-id (of a statement of a Party)**' to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not).
Parties need to specify the kinds of credentials they are willing to issue, the class of entities (e.g. people, cars, Organizations) for which it will issue them, and the information schema (structure) that it will use in credentials of such kinds.[^1] This allows the Data Discloser to construct data objects that conform to this information schema, and present it to the Issuer component for actual issuing.
......
......@@ -6,6 +6,7 @@ type: concept
typeid: definition
stage: draft
hoverText: "Definition: a text that helps Parties to understand the meaning of (and Concepts behind) a Term, ideally in such a way that these Parties can determine whether or not they make the same distinction."
glossaryText: "a text that helps %%parties^party%% to understand the meaning of (and %%concepts^concept%% behind) a %%term^term%%, ideally in such a way that these %%parties^party%% can determine whether or not they make the same distinction."
---
### Short Description
......
......@@ -6,6 +6,7 @@ type: concept
typeid: dependent
stage: draft
hoverText: "Dependent (of an Party in a Jurisdiction): the Entity for the caring for and/or protecting/guarding/defending of which a Guardianship Relationship has been established with that Entity within that Jurisdiction."
glossaryText: "the %%entity^entity%% for the caring for and/or protecting/guarding/defending of which a %%guardianship relationship^guardianship%% has been established with that %%entity^entity%% within that %%jurisdiction^jurisdiction%%."
---
:::info Editor's Note
......
......@@ -6,6 +6,7 @@ type: dictionary
typeid: dictionary-file
stage: draft