Commit baecca75 authored by Rieks Joosten's avatar Rieks Joosten

cleaning up and bugfixing

parent 67ac20f5
Pipeline #17205 passed with stage
in 1 minute and 41 seconds
......@@ -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.
......@@ -2,14 +2,33 @@
id: pattern-duties-and-rights
title: "Duties and Rights"
scopeid: essifLab
type: concept
typeid: pattern-duties-and-rights
type: pattern
typeid: duties-and-rights
stage: draft
hoverText: "The Duties and Rights pattern describes the relations between Jurisdictions, Legal Entities and the duties and rights they have within them."
hoverText: "The Duties and Rights pattern captures the Concepts and relations that explain what a generic duties and rights consists of (based on Hofeld's theories), and relates it to Jurisdictions, Parties and Legal Entities."
---
:::info Editor's Note
TNO to provide content here
import useBaseUrl from '@docusaurus/useBaseUrl'
### Purpose
<!-- Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it. -->
The **Duties-and-rights pattern** captures the concepts and relations that explain what (generic) duties and rights are, thereby following the [theory of Hohfeld](https://plato.stanford.edu/entries/rights/#FormRighHohfAnalSyst), which is not only the basis of %%legal systems|legal-system%% (in %%jurisdictions|jurisdiction%%), but can be used to generically model duties and rights.
### Introduction
<!-- Gently introduce the pattern, by referring to real-world situations and using colloquial terms, so that when someone has read the text, (s)he knows what it is about, and is ready to delve into the specifics of the pattern. -->
:::info Editor's note
TNO to provide further introductorty texts
:::
##
\ No newline at end of file
### Formalized model
Here is a visual representation of this pattern, using the following [notations and conventions](../notations-and-conventions#pattern-diagram-notations):
<img
alt="Conceptual model of the 'Duties-and-rights' pattern"
src={useBaseUrl('images/patterns/pattern-hohfeldian-duty-right.png')}
/>
:::info Editor's note
TNO to provide further introductorty texts
:::
......@@ -2,7 +2,7 @@
id: pattern-file
title: "Pattern-file"
scopeid: essifLab
type: pattern
type: concept
typeid: pattern-file
stage: draft
hoverText: "Pattern-file: a file whose contents describes/documents a Pattern."
......
---
id: transaction-result-dispatcher
title: "Transaction Result Dispatcher"
scopeid: essifLab
type: concept
typeid: transaction-result-dispatcher
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."
---
## 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:
- 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 TRD 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.
## 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%%.
## 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.
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.
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.
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.
-----
[^1]: We assume/stipulate that the Party maintains a credential catalogue that contains this, and other information about every kind of credential that it issues, and that such catalogues are available to other Parties that want or need to use such credentials.
---
id: trd-policy
title: "TRD Policy"
scopeid: essifLab
type: concept
typeid: trd-policy
stage: draft
hoverText: "TRD Policy: a Digital Policy that enables an operational TRD component to function according to the rules of its Policy Governor."
---
## Short Description
A **Transaction (Validation) Engine** or **TRD** is a functional component that provides business applications with forms that users have filled in, and where the content of such forms is valid for making decision(s) by this application. The TRD uses a machine readable TRD-policy
## Purpose
The purpose of the Transaction (Validation) Engine (TRD) is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
## Criteria
A **Transaction (Validation) Engine** or **TRD** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whos function is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
## Functionality
Typically, the TRD 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.[^1]
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 communications channels.
Handling/managing the various communications channels through which data can be exchanged is also a task of the TRD[^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 TRD is generally considered capable of obtaining data through different communications channels. However, the technical tracks of eSSIF-Lab will exclusively focus on the communications channel through which credentials can be requested and obtained. Any extensions or business productization of TRD 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 TRD 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 TRD 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 TRD 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 TRD work, a Validation Policy (or TRD 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 TRD Policy enable the TRD 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 TRD 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 TRD 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 TRD itself must make validation decisions, either electronically (according to the TRD 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 TRD can intermittently request the verifier to produce it (or it can use other communications channels, which is outside scope for now). It does so until it times out, or the form has become 'clean'.
-----
[^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 TRD. 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 TRD 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: tve-policy
title: "TVE Policy"
scopeid: essifLab
type: concept
typeid: tve-policy
stage: draft
hoverText: "TVE Policy: a Digital Policy that enables an operational TVE component to function according to the rules of its Policy Governor."
---
## Short Description
A **Transaction Validation Engine (TVE)** is a functional component that provides business applications with forms that users have filled in, and where the content of such forms is valid for making decision(s) by this application. The TVE uses a machine readable TVE-policy
## Purpose
The purpose of the Transaction Validation Engine (TVE) is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
## Criteria
A **Transaction Validation Engine (TVE)** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whos function is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
## Functionality
Typically, the TVE 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.[^1]
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 communications channels.
Handling/managing the various communications channels through which data can be exchanged is also a task of the TVE[^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 TVE is generally considered capable of obtaining data through different communications channels. However, the technical tracks of eSSIF-Lab will exclusively focus on the communications channel through which credentials can be requested and obtained. Any extensions or business productization of TVE 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 TVE 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 TVE 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 TVE 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 TVE work, a Validation Policy (or TVE 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 TVE Policy enable the TVE 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 TVE 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 TVE 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 TVE itself must make validation decisions, either electronically (according to the TVE 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 TVE can intermittently request the verifier to produce it (or it can use other communications channels, which is outside scope for now). It does so until it times out, or the form has become 'clean'.
-----
[^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 TVE. 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 TVE 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: zzz
title: "zzz"
scopeid: essifLab
type: concept
typeid: zzz
stage: draft
hoverText: "zzz: popuptext remains to be done"
---
:::info Editor's note
TNO to provide the content of this file.
:::
### Related Concepts
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment