Commit 683897fc authored by Rieks Joosten's avatar Rieks Joosten

Merge branch 'terminology-rieks' into 'master'

updates on framework

See merge request !7
parents be6540b0 b6b794a1
Pipeline #16239 passed with stages
in 4 minutes and 2 seconds
......@@ -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.
......
---
id: governance
title: eSSIF-Lab Governance
sidebar_label: Governance
scopeid: essifLab
---
import useBaseUrl from '@docusaurus/useBaseUrl';
## 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 and other guidance|policy%% of that 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 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
......@@ -20,10 +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. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct.
- 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 **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.
- 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 in turn is a generalization of SRC). This implies 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'.
- **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
---
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
......@@ -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).
......
......@@ -24,7 +24,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 -->
<!--
......
......@@ -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.
......
......@@ -5,11 +5,11 @@ 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, as a single operation, for a given Party within 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 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 a %%policy|policy%% that this party has established for actions of that kind. The actor is assumed to have appropriate access to that policy.
### 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.
......@@ -24,6 +24,8 @@ 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
......@@ -24,5 +24,11 @@ Entity that is capable of actually executing %%actions|action%% (acting, doing t
- 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.
### Related concepts
- %%digital actor|digital-actor%%
- %%peer actor|peer-actor%%
- %%agent|agent%%
- %%principal|principal%%
### Background
The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
......@@ -5,18 +5,18 @@ scopeid: essifLab
type: concept
typeid: agent
stage: draft
hoverText: "Agent (of a Party): an Actor that is (at that point in time) executing an Action for, or on behalf of a Party (the Principal of that Actor)."
hoverText: "Agent (of a Party): an Actor that is executing an Action for, or on behalf of a Party (called the Principal of that Actor)."
---
### 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. 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.
An **Agent** is an %%actor|actor%% that is executing an action %%action|action%% for, or on behalf of some %%party|party%% (which we call the %%principal|principal%% of that agent). During the time interval in which the action is executed, the actor may execute other actions in other execution-contexts, on behalf of the same or another party. However, for the execution of a single %%action|action%%, the actor is an agent for precisely one principal. It is assumed that the principal provides its agents with the %%policies|policy%% that provide the agents with the rules, working-instructions and/or other guidance that they need to comply with when exeucting the action.
### 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%% (its %%principal|principal%%).
An **Agent** is a role that an %%actor|actor%% fulfills with respect to some %%party|party%% when that actor is executing some %%action|action%% for, or on behalf of that party.
### Examples
......
---
id: author
title: "Author"
scopeid: essifLab
type: concept
typeid: author
stage: draft
hoverText: "Author (of data/document/file/...): the Party, on whose behalf that data/document/file/... has been created or updated."
---
:::info Editor's note
TNO (or others) to provide the content of this file.
:::
......@@ -5,14 +5,42 @@ scopeid: essifLab
type: concept
typeid: business-transaction
stage: draft
hoverText: "Business Transaction: the electronic exchange of goods, services, funds, or data between parties (called‘participants’ to the transaction)"
hoverText: "Business Transaction: the exchange of goods, services, funds, or data between some Parties (called ‘participants’ of the transaction)"
---
import useBaseUrl from '@docusaurus/useBaseUrl';
:::info Editor's note
TNO (or others) to provide the content of this file.
:::
:::info Editor's note
TNO to provide the content of this file.
Explanation required about 'commitment decisions' (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 (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 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 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.
### Notes
--------
1. A good mental model for describing and designing business transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations).
\ No newline at end of file
[^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
......@@ -5,10 +5,10 @@ scopeid: essifLab
type: concept
typeid: colleague
stage: draft
hoverText: "Colleague (of an Agent): any other Agent that has the same Principal (i.e. Party on whose behalf they exeucte Actions)."
hoverText: "Colleagues: two or more Digital Agents that all have the same Principal (i.e. Party on whose behalf they exeucte Actions)."
---
:::info Editor's note
TNO to provide the content of this file.
TNO (or others) to provide the content of this file.
:::
---
id: communication-channel
title: "Communication Channel"
scopeid: essifLab
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."
---
:::info Editor's note
TNO (or others) to provide further content of this file.
:::
### Notes
A %%Communication Channel|communication-channel%% is said to be **digital** if it uses a digital means to exchange (digital) messages between two %%digital actors|digital-actor%%.
A %%Communication Channel|communication-channel%% is said to be **secure** if it provides the following guarantees:
- every of its endpoint is being used by precisely one %%actor|actor%%;
- during its entire lifetime, each endpoint will only be used by this %%actor|actor%% (endpoint authentication; note that identification of the %%actor|actor%% that uses an endpoint, or its %%principal|principal%% is NOT required);
- only the %%actors|actor%% that use an endpoint are capable of transmitting and reading messages through that channel (message secrecy - typically obtained by encrypting the messages);
- the receiver of a message can determine whether or not the message has been received as it was transmitted (message integrity).
### Related Concepts
- %%Communication Session|communication-session%%
---
id: communication-session
title: "Communication Session"
scopeid: essifLab
type: concept
typeid: communication-session
stage: draft
hoverText: "Communication Session: the time interval during which two Actors have an established Communication Channel."
---
:::info Editor's note
TNO (or others) to provide the content of this file.
:::
......@@ -5,7 +5,7 @@ scopeid: essifLabTerminology
type: concept
typeid: concept
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."
hoverText: "Concept: the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same')."
---
### Short Description
......
......@@ -9,5 +9,5 @@ hoverText: "Corpus (of Terminology): the documentation that describes the Knowle
---
:::info Editor's note
TNO to provide the content of this file.
TNO (or others) to provide the content of this file.
:::
......@@ -5,11 +5,11 @@ scopeid: essifLab
type: concept
typeid: credential
stage: draft
hoverText: "Credential: data, representing a set of statements made by one Party (the author of the credential)."
hoverText: "Credential: data, representing a set of statements (claims, assertions) made by one Party (the author of the credential)."
---
:::info Editor's note
TNO to provide the content of this file.
TNO (or others) to provide the content of this file.
:::
### Related Concepts
......@@ -17,3 +17,7 @@ TNO to provide the content of this file.
- %%verified data|verified-data%%
- %%validated data|validated-data%%
### References:
- W3C VC [definition of 'credential'](https://www.w3.org/TR/vc-data-model/#dfn-credential)
- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/)
---
id: data-collector-policy
title: "Data Collector Policy"
scopeid: essifLab
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."
---
### Short Description
A **Data Collector Policy** is a %%digital policy|digital-policy%% that enables an operational %%Data Collector component|data-collector%% to function according to the rules of its %%Policy Governor|policy-governor%%.
Such a policy includes e.g. the kinds of data (and meta-data) required to make these kinds of decisions, criteria to distinguish between %%data that is valid|validated-data%% and data that is not, any data conversions that may be needed, etc.
### Purpose
The purpose of a **Data Collector Policy** is to enable the creation of (technical) components that implement the generic %%data collector|data-collector%% functionality that will subsequently use such policies to guide their behaviour.
### Criteria
A **Data Collector Policy** is a %%digital policy|digital-policy%% that enables an operational %%Data Collector component|data-collector%% to function according to the rules, working-instructions and other guidance of its %%Policy Governor|policy-governor%%.
---
id: data-collector
title: "Data Collector"
scopeid: essifLab
type: concept
typeid: data-collector
stage: draft
hoverText: "Data Collector: a functional component that collects sufficient and Validated Data for deciding whether or not a request (typically for a product or a service) is to be serviced."
---
### Short Description
A **Data Collector** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that a %%party|party%% may use to collect sufficient and %%validated data|validated-data%% for deciding whether or not a request (typically for a product or a service) is to be serviced.
### Purpose
The purpose of a Data Collector is to collect sufficient and %%validated data|validated-data%% that eneables (an %%agent|agent%% of) its %%principal|principal%% to decide whether or not some request (typically for a product or a service) is to be serviced.
### Functionality
A data collector typically starts to collect data when it receives a request (e.g. to provide a product or service). The reception of such a request triggers the creation of a new %%business transaction|business-transaction%%. The task of the data collector is to collect %%validated data|validated-data%% that is sufficient for making a commitment decision (or, as [DEMO](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations) calls it: a 'promise' or 'quit' decision.)
Starting the data collection for a transaction does NOT imply that the identity of the %%actors|actor%% from whom/which the request originated, is established (or authenticated). It also does NOT imply that the identity of the %%peer party|peer-party%% is established (or authenticated). The data collector simply proceeds to collect a sufficient amount of data such that the associated decision can be made, according to the rules, working-instructions and other guidance provided by its %%principal's|principal%% %%data collector policy|data-collector-policy%%. Such data may include identity data, but it also may not.
Starting the data collection for a transaction implies that the data collector informs the %%data discloser component|data-discloser%% about the %%transaction|business-transaction%% that has just started, and the kind of that transaction. This allows the %%data discloser component|data-discloser%% to process requests for data from %%peer agents|peer-agent%%[^1x]
All guidance that the data collector needs to collect the necessary and %%validated data|validated-data%% to make that decision is provided by the %%data collector policy|data-collector-policy%% that has been established by the data collector's %%principal|principal%%. Such a policy includes e.g. the kinds of data (and meta-data) required to make these kinds of decisions, criteria to distinguish between %%data that is valid|validated-data%% and data that is not, any data conversions that may be needed, etc.
A data collector may multi-task, i.e. simultaneously/asynchronously collect data for multiple %%transactions|business-transaction%%. To organize this, messages that are exchanged with %%peer agents|peer-agent%% must contain an identifier that allows the data collector and its peer agents to identify the transaction to which each message belongs.
During the time in which a data collector is collecting data for a specific %%transaction|business-transaction%%, it may choose to setup, accept, and tear down %%communication sessions|communication-session%% with any %%actors|actor%%, if that is appropriate. This allows requests for data to be sent to different kinds of %%peer party|peer-party%%-%%agents|agent%%, e.g. human or %%digital|digital-agent%% agents. However, the data collector then must ensure that every of these %%agents|agent%% are all %%colleagues|colleague%%, i.e. have the %%peer party|peer-party%% as their %%principal|principal%%.
A data collector benefits from generic APIs or (G)UIs that allow it to simply ask for the data that it requires. Specifically for SSI, the data collector uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Verifier|verifier%% functionalities.
### Criteria
A **Data Collector** is a functional component in the [eSSIF-Lab functional architecture](../functional-architecture) that
- services requests by %%digital|digital-agent%% and non-digital %%agents|agent%%, for providing a product or service, thereby starting a %%transaction|business-transaction%%;
- can setup, accept and tear-down communication channels of various kinds, with %%digital|digital-colleague%% and/or non-digital %%colleagues|colleague%% of that %%requesting agent|agent%%,[^peer-agents] as appropriate for the data exchanges that are needed to conduct the transactions;
- can use any appropriate communication channel with a %%peer-agent|peer-agent%% to:
- request for data that, according to the %%Data Collector Policy|data-collector-policy%% is needed to decide whether or not to commit to the transaction;
- process the responses to such requests, in an orchestrated way, thereby complying with the rules of its %%principal's|principal%% %%Data Collector Policy|data-collector-policy%%, the result of which (in the end) is a set of %%validated data|validated-data%% that can serve the purpose of deciding whether or not to commit to the transaction;
- receive similar requests from its %%peer-party%%, and respond to such requests in compliance with the rules of its %%principal's|principal%% %%Data Collector Policy|data-collector-policy%%;
- has a mechanism to ensure that within a %%transaction|business-transaction%%, it uses the latest (most receent) %%Data Collector Policy|data-collector-policy%% of its %%principal|principal%%.
### Deprecated - TVE Functionality
:::info Editor's note
TNO to revise the text below.
This section is the old text of what was called the Transaction Validation Engine.
It will be deleted in the (near?) future.
:::
Typically, the Data Collector would start a transaction either
- when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind.
- when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.[^one]
In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Owner and/or using different communication channels.
Handling/managing the various communication channels through which data can be exchanged is also a task of the Data Collector[^2]. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens).
Thus, the Data Collector is generally considered capable of obtaining data through different communication channels. However, the technical tracks of eSSIF-Lab will exclusively focus on the communication channel through which credentials can be requested and obtained. Any extensions or business productization of Data Collector designs may be considered in the business tracks of eSSIF-Lab. The latter is not considered any further in this section.
In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the Data Collector needs to know what kinds of credentials it should ask for, which Parties its Owner trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.[^3] Also, when the Data Collector gets a credential that satisfies the necessary verification proofs, it needs a way to map the contents of that credential to the structure of the transaction context that is used internally by (other systems of) its Owner.[^4] Also, as the Data Collector gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.[^5]
In order to make the Data Collector work, a Validation Policy (or Data Collector Policy) is created by, or on behalf of the Owner, which specifies at least:
- the kinds of transactions the Owner is willing to (electronically) engage in, from both the requester and the provider perspectives;
- for each such transaction type:
- the criteria (business rules) that should be used to determine that the form is ‘clean’, i.e. that the necessary and sufficient data have been obtained and that they are consistent, coherent, and suitable for making a transaction commitment decision.
- the kinds of credentials and issuers that the Owner is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing Parties do the actual credential issuing may be specified[^6].
- for each kind of credential: the verification proofs that must hold to be accepted as a source for valid data.
- the mapping between fields in such credentials and fields in the form to be filled in.
The Policy must be designed in such a way that it is extendable as new features will be called for in the future.
The ability to create new transaction contexts and the availability of the Data Collector Policy enable the Data Collector to request the Verifier component of its Owner to obtain credentials of the types that it can use to fill in the transaction form when they satisfy the verification and validation requirements of its Owner.[^7]
When the Verifier returns such data (which comes with a list of proofs that the Verifier has checked), the Data Collector must then validate that data, i.e. determine whether or not it is valid for the specific transaction it is assembling the data for. The validation rules are Party-specific and hence come from the Data Collector policy. For simple cases, validation can simply consist of checking whether or not all verification proofs succeeded. At the other end of the validation spectrum, the Data Collector itself must make validation decisions, either electronically (according to the Data Collector policy) or by ‘outsourcing’ such decisions to human Agents of its Owner by providing an appropriate validation user interface.
As long as data is needed, the Data Collector can intermittently request the verifier to produce it (or it can use other communication channels, which is outside scope for now). It does so until it times out, or the form has become ‘clean’.
-----
### Notes:
:::info Editor's note
TNO to revise the footnote markers
:::
[^1x]: In the same way that the data collector needs to collect data in order to be able to decide whether or not to commit, %%agents|agent%% of the %%peer party|peer-party%% need to collect data for making a similar commitment decision. Requests for such data are to be processed by the %%data discloser component|data-discloser%% under guidance of its %%data-discloser-policy%%.
[^1a]: If the %%data collector policy|data-collector-policy%% specifies that data is to be collected for other purposes, the %%data collector|data-collector%% should then be provided a means to inform its %%peer party|peer-party%% of such purposes, and the policy should not specify that such data is required to make the commitment decision.
[^1 (peer-agents)]: Note that such agents have then become so-called %%peer-agents|peer-agent%% (of the Data Collector) for that specific transaction. Also, the (single!) %%principal|principal%% of these %%peer-agents|peer-agent%% is the %%peer-party|peer-party%% of the %%principal|principal%% of the Data Collector (again, for that specific transaction).
[^1]: This feature ensures that the transaction is really two-way, and both Parties can request credentials from the other. For example, a web-shop can then ask for a (delivery) address credential, and the customer can ask for a credential issued e.g. by the chamber of commerce that the web-shop is a legitimate company (and not some maffia website).
[^2]: It may well be that this functionality can somehow be split off in the (near) future.
[^3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Owner of the Data Collector. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years.
[^4]: For example, a credential that contains an address uses a specific schema to specify addresses, e.g. the ‘PostalAddress’ as defined by schema.org. This schema differs quite a bit from that of Dutch addresses as [*defined*](https://bag.basisregistraties.overheid.nl/def/bag) by the official (authentic) Dutch Registration of Addresses and Buildings (BAG). It may also well differ from the structure of addresses that databases of the Owner have implemented. Mapping allows such cases to be accommodated for.
[^5]: Inconsistent or incoherent data is necessary for various purposes. First, it allows for correct further processing of the transaction. A non-existent postal code, or one that doesn’t match the delivery address, may hinder a fluent transaction processing, resulting in additional costs and processing times. Another purpose is the early warning or detection of possible fraud/abuse. Remember that part of the data is being asked for reducing transaction risk, and checking consistency/coherence of such data is part of the risk mitigation process.
[^6]: This enables the Data Collector to pass the endpoint URI on to the Verifier when it requests for such a credential, which in turn can send it to the holder of other Parties enabling them to obtain the credential from that issuer endpoint if that other Party does not have that credential in its wallet. The endpoint URI can in fact be put in the policy, because the (human) Agent that creates/maintains the policy would need to know that the issuing Party is actually issuing such credentials, what their contents means, etc., and hence is capable of tracking down the URI where that Party issues the credentials.
[^7]: A reference to this specification will be added when it becomes available (draft or otherwise).
---
id: data-discloser-policy
title: "Data Discloser Policy"
scopeid: essifLab
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."
---
### Short Description
A **Data Discloser Policy** is a %%digital policy|digital-policy%% that enables an operational %%Data Discloser component|data-discloser%% to function according to the rules of its %%Policy Governor|policy-governor%%.
Such a policy includes e.g. the kinds of data (and meta-data) that may be disclosed, the conditions that need to be satisfied for actually disclosing such kinds of data, any meta-data (assurances) that maybe added to data being disclosed, etc.
### Purpose
The purpose of a **Data Discloser Policy** is to enable the creation of (technical) components that implement the generic %%data discloser|data-discloser%% functionality that will subsequently use such policies to guide their behaviour.
### Criteria
A **Data Discloser Policy** is a %%digital policy|digital-policy%% that enables an operational %%Data Discloser component|data-discloser%% to function according to the rules, working-instructions and other guidance of its %%Policy Governor|policy-governor%%.
---
id: transaction-result-dispatcher
title: "Transaction Result Dispatcher"
id: data-discloser
title: "Data Discloser"
scopeid: essifLab
type: concept
typeid: transaction-result-dispatcher
typeid: data-discloser
stage: draft
hoverText: "Transaction Result Dispatcher (TRD): a functional component that is capable of stating (various, sometimes intermediary) results of Business 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."
hoverText: "Data Discloser: a functional component that is capable of disclosing data."
---
## Short Description
A **Transaction Result Dispatcher (TRD)** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that applications (that work for some %%Party|party%%) can call to communicate things such as:
### Short Description
A **Data Discloser** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that applications (that work for some %%Party|party%%) can call to communicate things such as:
- the results of a business transaction (e.g. statements to confirm that a transaction happened, thereby supplying appropriate details)
- the status of a business transaction (e.g. that an order has been received in good order, that delivery of an order is dealyed or otherwise changed)
- knowledge (including judgements) that this Party has about %%Entities|entity%% (people, organizations, things, orders, deliveries, etc.)
The TRD uses a %%TRD-policy|trd-policy%% to learn about the applicable (business) rules of its %%principal|principal%%. Such a policy may specify e.g. which types of credentials its principal is willing to (have) issue(d), to whom such credentials may be issued and the kinds of assurances that must be obtained before doing so, etcetera.
The Data Discloser uses a %%data-collector-policy|data-collector-policy%% to learn about the applicable (business) rules of its %%principal|principal%%. Such a policy may specify e.g. which types of credentials its principal is willing to (have) issue(d), to whom such credentials may be issued and the kinds of assurances that must be obtained before doing so, etcetera.
The TRD uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities.
The Data Discloser uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities.
## Purpose
The purpose of the TRD component 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. A special kind of result is the (provisioning of) a credential that its Owner already has created.
### Purpose
The purpose of the Data Discloser component 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. A special kind of result is the (provisioning of) a credential that its Owner already has created.
## Criteria
A **Transaction Result Dispatcher (TRD)** 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%%.
### Criteria
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
### 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.
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 TRD to construct data objects that conform to this information schema, and present it to the Issuer component for actual issuing.
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.
The TRD Issuing Policy specifies the kinds of (linked-)data-objects that credentials may be created for. This allows the TRD to construct such a (linked-)data-objects for every subject-id that identifies a subject of the class for which a credential can be issued, which can subsequently be sent to the Issuer component that can turn it into a credential of a specific sort.
The Data Discloser Issuing Policy specifies the kinds of (linked-)data-objects that credentials may be created for. This allows the Data Discloser to construct such a (linked-)data-objects for every subject-id that identifies a subject of the class for which a credential can be issued, which can subsequently be sent to the Issuer component that can turn it into a credential of a specific sort.
You can think of the TRD as the component that pulls all data together that can be put in a credential (e.g. in a passport), and the Issuer as the component that puts the data in an (empty) passport, and signing it so as to create the actual credential.
You can think of the Data Discloser as the component that pulls all data together that can be put in a credential (e.g. in a passport), and the Issuer as the component that puts the data in an (empty) passport, and signing it so as to create the actual credential.
The TRD may either push credential data to the Issuer component, so that the Issuer always has up-to-date credentials, or it can wait until the Issuer requests credential data for the creation of a credential of a specific type for a specific subject.
The Data Discloser may either push credential data to the Issuer component, so that the Issuer always has up-to-date credentials, or it can wait until the Issuer requests credential data for the creation of a credential of a specific type for a specific subject.
-----
......
......@@ -5,7 +5,7 @@ scopeid: essifLabTerminology
type: concept
typeid: definition
stage: draft
hoverText: "Definition: a text that helps Parties deeply/truly understand the meaning of a Term."
hoverText: "Definition: a text that helps Parties deeply/truly understand the meaning of, or Concepts behind, a Term."
---
### Short Description
......
......@@ -5,7 +5,7 @@ scopeid: essifLabTerminology
type: concept
typeid: dictionary
stage: draft
hoverText: "Dictionary: an alphabetically sorted list of Terms and explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s)."
hoverText: "Dictionary: an alphabetically sorted list of Terms with various meanings they may have in different contexts."
---
### Short Description
......