diff --git a/.gitignore b/.gitignore index 59acb63667469d25cbec77999c6b61e89039035e..e093ec31fa4442efa166ffbc919e187deeda78a7 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,5 @@ yarn-error.log* start_server.bat *.ffs_batch *.lnk +docs/vscode-%%-batch-replacer.txt +**/zzz-* diff --git a/docs/functional-architecture.md b/docs/functional-architecture.md index d4a4226c82a67c04b2f32b883e8a30a35b6c8d9e..062ce986a61c0f013d06eeae10361596bc8f1b57 100644 --- a/docs/functional-architecture.md +++ b/docs/functional-architecture.md @@ -5,30 +5,32 @@ sidebar_label: Functional Architecture scopeid: essifLab --- +import useBaseUrl from '@docusaurus/useBaseUrl' + ## Purpose It is the intention of the eSSIF-Lab project to develop this functional architecture into a generic, and common basis that parties from different backgrounds can use e.g. for: - thinking and arguing about SSI-related topics and how it contributes to business transactions; - creating technological components that provide functionalities that fit into the architecture and hence have a great chance to be, or quickly become, interoperable with tech components that other parties have developed; - discussing and resolving issues related to interfaces and protocols for tech components that provide such functionalities; -- designing and developing technical applications that support businesses, not only as they conduct business transactions, but also as the govern the %%policies|policy%% that are needed to make the technology work as intended by such businesses. +- designing and developing technical applications that support businesses, not only as they conduct business transactions, but also as the govern the policies that are needed to make the technology work as intended by such businesses. To this end, this document provides an overview of -- the functions (capabilities) that individual %%parties|party%% need in order to electronically support %%busines transactions|business-transaction%%; +- the functions (capabilities) that individual parties need in order to electronically support busines transactions; - the interactions between these functions that make such business transactions happen; -- the various %%policies|policy%% that parties have to govern, and put in place in order for the technical components that provide these capabilities to function in accordance with their (subjective) %%rules, working-instructions and other guidance|policy%%. +- the various policies that parties have to govern, and put in place in order for the technical components that provide these capabilities to function in accordance with their (subjective) rules, working-instructions and other guidance. ## 2. Functional Architecture Overview -Figure 1 shows the initial *functional* eSSIF-Lab architecture, and its scope, context and *functional* components each of which is a (*functional*) %%agent|agent%% for the same %%party|party%% (meaning that they are all part of the same %%organization|organization%% as defined above, and they are all %%(digital) ‘Colleagues’|digital-colleague%% of one another). +Figure 1 shows the initial *functional* eSSIF-Lab architecture, and its scope, context and *functional* components each of which is a (*functional*) agent for the same party (meaning that they are all part of the same organization as defined above, and they are all (digital) ‘Colleagues’ of one another). -Please be aware that *functional* capabilities, components, Agents, etc. do not necessarily coincide with *technical* capabilities, components, Agents, etc. The technical components can be deployed (downloaded, installed, run), whereas a functional component is a provider of a specified set of capabilities/functionalities an implementation of which can be made part of a technical component. So it is conceivable that a technical component contains an implementation of wallet, holder and verifier functional components as well as other functionalities that are not described here, e.g. related to UX, setting preferences, and more. In this functional architecture, the default type of components, Agents etc. are *functional*. +Please be aware that *functional* capabilities, components, agents, etc. do not necessarily coincide with *technical* capabilities, components, agents, etc. The technical components can be deployed (downloaded, installed, run), whereas a functional component is a provider of a specified set of capabilities/functionalities an implementation of which can be made part of a technical component. So it is conceivable that a technical component contains an implementation of issuer, wallet, holder and verifier functional components as well as other functionalities that are not described here, e.g. related to UX, setting preferences, and more. In this functional architecture, the default type of components, agents etc. are *functional*. -Since the participants of a business transaction are different Parties, the negotiation, commitment and execution of that transaction will be done by Agents of these different Parties. Assuming that a single transaction has two such Parties, we will use the term ‘%%Peer Party (of a specific Party, in the context of a single transaction)|peer-party%%’ to refer to the participating Party in that transaction that is not the specific Party itself. +Since the participants of a business transaction are different parties, the negotiation, commitment and execution of that transaction will be done by agents of these different parties. Assuming that a single transaction has two such parties, we will use the term ‘Peer Party (of a specific Party, in the context of a single transaction)’ to refer to the participating party in that transaction that is not the specific %%party|party%% itself. -When an Agent is involved in such a transaction, it will be communicating with a component that it assumes to be an Agent of the Peer Party of its Owner (the Agent may obtain further assurances for that, but that's outside the scope for now). We will use the term ‘%%Peer Agent (of a specific Agent, in the context of a single transaction)|peer-agent%%’ to refer to an Actor with which the specific Agent has a communication session. Note that establishing whether or not an Actor is a Peer Agent does not necessarily require knowing who the Peer Party actually is. +When an %%agent|agent%% is involved in such a transaction, it will be communicating with a component that it assumes to be an %%agent|agent%% of the %%Peer Party|peer-party%% of its %%principal|principal%% (the %%agent|agent%% may obtain further assurances for that, but that's outside the scope for now). We will use the term ‘%%Peer Agent (of a specific Agent, in the context of a single transaction)|peer-agent%%’ to refer to an %%actor|actor%% with which the specific %%agent|agent%% has a %%communication session|communication-session%%. Note that establishing whether or not an %%actor|actor%% is a %%Peer Agent|peer-agent%% does not necessarily require knowing who the %%Peer Party|peer-party%% actually is. -The figure below is an overview of the most important *functional* components that any Party needs to conduct electronic business transactions. +The figure below is an overview of the most important *functional* components that any %%party|party%% needs to conduct electronic %%business transactions|business-transaction%%. eSSIF-Lab Single Party Functional Architecture Overview @@ -49,39 +51,39 @@ The top layer (in the red rounded rectangle) has the functions of actual busines The lower business layer contains two functional components, one for initiating transactions and the other for stating transaction results (as per the [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations) method), each of which with an associated business policy that contains business-specific policies/preferences. -The task of the %%Data Collector|data-collector%% (or %%Data Collectordata-collector%%) is to handle and initiate requests from/to Peer Agents to engage in some kind of transaction, by negotiating and exchanging data (through one or more, physical or electronic communication channels), and to produce a transaction form whose contents are complete and valid, enabling an appropriate Colleague to decide whether or not to engage in the transaction. Note that negotiating a transaction has two parts: requesting a Peer Agent to provide data that its Owner needs, and providing data on behalf of its Owner that a Peer Agent requests. After all, a business transaction can only start after all Parties have decided to commit, which they can only do after each of them has obtained the information it (subjectively) needs to do so. Also note that data that the Data Collector must ensure that the transaction context is properly maintained if it chooses to exchange data through different communication channels. +The task of the Data Collector (or Data Collector) is to handle and initiate requests from/to peer agents to engage in some kind of transaction, by negotiating and exchanging data (through one or more, physical or electronic communication channels%), and to produce a transaction form whose contents are complete and valid, enabling an appropriate Colleague to decide whether or not to engage in the transaction. Note that negotiating a transaction has two parts: requesting a peer agent to provide data that its principal needs, and providing data on behalf of its principal that a peer agent requests. After all, a business transaction can only start after all %%parties|party%% have decided to commit, which they can only do after each of them has obtained the information it (subjectively) needs to do so. Also note that data that the %%data collector|data-collector%% must ensure that the transaction context is properly maintained if it chooses to exchange data through different %%communication channels|communication-channel%%. -The task of the %%Data Discloser|data-discloser%% (or %%Data Discloser|data-discloser%%) is to state the (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other Parties. Since such state-data may change, issuing data that supersedes an earlier state implies the revocation of such a state. +The task of the %%data discloser|data-discloser%% (or %%data discloser|data-discloser%%) 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|party%%. Since such state-data may change, issuing data that supersedes an earlier state implies the revocation of such a state. Note that both components are within scope of eSSIF-Lab architecture, but NOT in scope of the eSSIF-Lab infrastructure, as they are too business-specific. ### 2.2. SSI Roles Layer (Issuer, Verifier, Holder and Wallet) -The SSI Roles Layer contains functional components that provide the functionality associated with the well-known roles of issuer, holder, wallet and verifier. Technical components that provide such functionalities are part of the eSSIF-Lab (technical) infrastructure. +The SSI Roles Layer contains functional components that provide the functionality associated with the well-known roles of %%issuer|issuer%%, %%holder|holder%%, %%wallet|wallet%% and %%verifier|verifier%%. Technical components that provide such functionalities are part of the eSSIF-Lab (technical) infrastructure. -Apart from each having a specific task, as described below, implementations that are being deployed by one Party should be aligned in that they support the same (sub)set(s) of SSI Protocols and Crypto features, as described in the following section. +Apart from each having a specific task, as described below, implementations that are being deployed by one %%party|party%% should be aligned in that they support the same (sub)set(s) of SSI Protocols and Crypto features, as described in the following section. -The **issuer** functionality includes the issuing of what we will generically call ‘credentials’, i.e. sets of (related) statements/claims (e.g. as produced by the Data Discloser) that have metadata (e.g. date of issuing) and a digital signature by which third Parties can prove its provenance and integrity. Another function of the issuer is to handle revocation (and (un)suspension) of credentials that it has issued. For such tasks, it relies on functions that are made available by the SSI Protocols and Crypto Layer. +The **issuer** functionality includes the issuing of what we will generically call '%%credentials|credential%%', i.e. sets of (related) statements/claims (e.g. as produced by the %%data discloser|data-discloser%%) that have metadata (e.g. date of issuing) and a digital signature by which third %%parties|party%% can prove its provenance and integrity. Another function of the %%issuer|issuer%% is to handle revocation (and (un)suspension) of %%credentials|credential%% that it has issued. For such tasks, it relies on functions that are made available by the SSI Protocols and Crypto Layer. -The **wallet** functionality includes the (secure) storage of credentials - both those that have been issued by the issuer (i.e. self-signed credentials) and those that have been obtained from issuers of other Parties. Another task of the wallet is to (securely) store (private) keys that can be used to sign or seal data on behalf of its Owner. Perhaps the most important task of the Wallet is to ensure that credentials and keys can only become available to another component if they have the same (single) Owner, and will become available if such other component implements a functionality that needs it. +The **wallet** functionality includes the (secure) storage of %%credentials|credential%% - both those that have been issued by the %%issuer|issuer%% (i.e. self-signed %credentials) and those that have been obtained from %%issuers|issuer%% of other %%parties|party%%. Another task of the %%wallet|wallet%% is to (securely) store (private) keys that can be used to sign or seal data on behalf of its %%principal|principal%%. Perhaps the most important task of the %%wallet|wallet%% is to ensure that %%credentials|credential%% and keys can only become available to another component if they have the same (single) %%principal|principal%%, and will become available if such other component implements a functionality that needs it. -The **verifier** functionality is to support the Data Collector as it tries to acquire credentials from some other Party for the purpose of negotiating a business transaction. It does so by creating Presentation Requests (or Presentation Definition as it is called in the [draft DIF specfication for Presentation Exchange](https://identity.foundation/presentation-exchange)) that ask for such credentials, sending them to a holder component of another Party, receiving a response to such a request (which we call a ‘Presentation’), verifying the Presentation, i.e. checking the signature and other proofs of the veracity of both the construction of the Presentation as well as its contents, thus providing the Data Collector with verified data. +The **verifier** functionality is to support the %%data collector|data-collector%% as it tries to acquire %%credentials|credential%% from some other %%party|party%% for the purpose of negotiating a business transaction. It does so by creating %%Presentation Requests|presentation-request%% (or Presentation Definition as it is called in the [draft DIF specfication for Presentation Exchange](https://identity.foundation/presentation-exchange)) that ask for such %%credentials|credential%%, sending them to a %%holder|holder%% component of another %%party|party%%, receiving a response to such a request (which we call a ‘%Presentation’), verifying the %%Presentation|presentation%%, i.e. checking the signature and other proofs of the veracity of both the construction of the %%Presentation|presentation%% as well as its contents, thus providing the %%Data Collector|data-collector%% with verified data. -The task of the **holder** is to handle Presentation Requests that it receives from Verifier components (both of its Owner, and of other Parties). Typically, this means looking for the requested data in the Owner’s wallet, and using it to construct a Presentation (=response). However, if the wallet doesn’t have it, the holder may negotiate a transaction with a component of the designated issuer for the purpose of obtaining the needed credential, which - when obtained - it can subsequently store in the wallet and use in the Presentation. +The task of the **holder** is to handle %%Presentation|presentation%% Requests that it receives from %%verifier|verifier%% components (both of its %%principal|principal%%, and of other %parties). Typically, this means looking for the requested data in the %principal’s %%wallet|wallet%%, and using it to construct a %%Presentation|presentation%% (=response). However, if the %%wallet|wallet%% doesn’t have it, the %%holder|holder%% may negotiate a transaction with a component of the designated %%issuer|issuer%% for the purpose of obtaining the needed %%credential|credential%%, which - when obtained - it can subsequently store in the %%wallet|wallet%% and use in the %%presentation|presentation%%. ### 2.3. SSI Protocols and Crypto Layer -While represented as a layer, the SSI Protocols and Crypto Layer can be seen more as a set of libraries that can be used by Wallet, Holder, Issuer and Verifier (WHIV) components for the purpose of actually implementing some/all of the functionality that they need to provide. Each ‘Component’ in this layer implements a specific technology, and any implementation of any of the WHIV components may choose which of these to use. Of course, if one of the WHIV components implements a technology, it would seem that the others would need to do so, too. +While represented as a layer, the SSI Protocols and Crypto Layer can be seen more as a set of libraries that can be used by %%wallet|wallet%%, %%holder|holder%%, %%issuer|issuer%% and %%verifier|verifier%% (WHIV) components for the purpose of actually implementing some/all of the functionality that they need to provide. Each ‘Component’ in this layer implements a specific technology, and any implementation of any of the WHIV components may choose which of these to use. Of course, if one of the WHIV components implements a technology, it would seem that the others would need to do so, too. Technologies may come as a (proprietary or open source) library, as a service (offered by one or more Parties), or both. There are way too many to mention here, but to give you an idea, here is a classification of such underlying/supporting technologies that seems to be useful. While we do mention some technologies explicitly, this should in no way be interpreted as that this would be necessary to support, or that others are not to be considered. -First, we have **credential-related technologies**, most often in the form of libraries, basically for the creation, (storing,) and verification of specific kinds of credentials such as [*Verifiable Credentials*](https://www.w3.org/TR/vc-data-model/) (VCs), [*Attribute Based Credentials*](https://abc4trust.eu/index.php/pub)[ABC] (ABCs), [*X.509 Attribute Certificates*](https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.509-201210-S!!PDF-E), [*OIDC*](https://openid.net/developers/specs/) tokens, etc. Various projects/implementations can already be used here, such as [*Hyperledger Aries*](https://www.hyperledger.org/projects/aries), [*IRMA*](https://privacybydesign.foundation/irma-en/), [*OpenCerts*](https://opencerts.io/), [*BlockCerts*](https://www.blockcerts.org/), and more. +First, we have **credential-related technologies**, most often in the form of libraries, basically for the creation, (storing,) and verification of specific kinds of %%credentials|credential%% such as [*Verifiable Credentials*](https://www.w3.org/TR/vc-data-model/) (VCs), [*Attribute Based Credentials*](https://abc4trust.eu/index.php/pub)[ABC] (ABCs), [*X.509 Attribute Certificates*](https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.509-201210-S!!PDF-E), [*OIDC*](https://openid.net/developers/specs/) tokens, etc. Various projects/implementations can already be used here, such as [*Hyperledger Aries*](https://www.hyperledger.org/projects/aries), [*IRMA*](https://privacybydesign.foundation/irma-en/), [*OpenCerts*](https://opencerts.io/), [*BlockCerts*](https://www.blockcerts.org/), and more. -Then, there are **secure communications technologies**, for the purposes of (a) ensuring that a technical component owned by a specific Party can recognize that another component as one that it has had previous communications with and/or is owned by an identified Party, and (b) setting up a secure communication channel, i.e. one that guarantees message confidentiality (encryption) and integrity/authentication. A well-known way to do this is SSL, but new ones are being developed, such as [*DID Comm(unication)*](https://github.com/hyperledger/aries-rfcs/tree/master/concepts/0005-didcomm), that uses [*peer DIDs*](https://github.com/WebOfTrustInfo/rwot8-barcelona/blob/master/draft-documents/peer-DID-method-spec-report.md) (work in progress). +Then, there are **secure communications technologies**, for the purposes of (a) ensuring that a technical component owned by a specific %%party|party%% can recognize that another component as one that it has had previous communications with and/or is owned by an identified %%party|party%%, and (b) setting up a secure %%communication channel|communication-channel%%, i.e. one that guarantees message confidentiality (encryption) and integrity/authentication. A well-known way to do this is SSL, but new ones are being developed, such as [*DID Comm(unication)*](https://github.com/hyperledger/aries-rfcs/tree/master/concepts/0005-didcomm), that uses [*peer DIDs*](https://github.com/WebOfTrustInfo/rwot8-barcelona/blob/master/draft-documents/peer-DID-method-spec-report.md) (work in progress). Another important category is that of **crypto (related) technologies**, which are used for various purposes, such as creating/verifying digital signatures, zero-knowledge-proofs, etc. Such technologies may come as a library (e.g. [*Hyperledger/Ursa*](https://www.hyperledger.org/projects/hyperledger-ursa)), or as a service, e.g. an [*eIDAS*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32014R0910&from=EN)[eIDAS] trust service. -We conclude for now by mentioning **blockchain/distributed ledger technologies**, for secure logging of (e.g. registration) events, where such logs have the property that it is virtually impossible to change the order and/or contents of the logged events, and that the logs are highly available to those that are authorized. Both public and private blockchains are known to be used, and different SSI-solutions may use them for different purposes, e.g. the registration of schema’s, credential definitions, DIDs and associated DID documents, revocation accumulators, etc. Examples include [*EBSI*](https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/ebsi) ([*European Blockchain Partnership*](https://ec.europa.eu/digital-single-market/en/blockchain-technologies)), [*Hyperledger Indy*](https://www.hyperledger.org/projects/hyperledger-indy) (Alastria, Findy, Sovrin), Ethereum ([*OpenCerts*](https://opencerts.io/), [*BlockCerts*](https://www.blockcerts.org/)), bitcoin ([*BlockCerts*](https://www.blockcerts.org/)) and many more. +We conclude for now by mentioning **blockchain/distributed ledger technologies**, for secure logging of (e.g. registration) events, where such logs have the property that it is virtually impossible to change the order and/or contents of the logged events, and that the logs are highly available to those that are authorized. Both public and private blockchains are known to be used, and different SSI-solutions may use them for different purposes, e.g. the registration of schema’s, %%credential types|credential-type%%, DIDs and associated DID documents, revocation accumulators, etc. Examples include [*EBSI*](https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/ebsi) ([*European Blockchain Partnership*](https://ec.europa.eu/digital-single-market/en/blockchain-technologies)), [*Hyperledger Indy*](https://www.hyperledger.org/projects/hyperledger-indy) (Alastria, Findy, Sovrin), Ethereum ([*OpenCerts*](https://opencerts.io/), [*BlockCerts*](https://www.blockcerts.org/)), bitcoin ([*BlockCerts*](https://www.blockcerts.org/)) and many more. It is expected that there are already some interfaces out there that may turn out to be useful here (e.g. (unverified) [*FIWARE*](https://fiware-idm.readthedocs.io/en/7.4.0/eidas/), CEF) @@ -97,7 +99,7 @@ It is expected that there are already some interfaces out there that may turn ou There are two interface layers in this architecture -The '**ESSIF Glue**' interface layer consists of a [documented set of APIs](https://gitlab.grnet.gr/essif-lab/tno-ssi-service/developer-docs) between the Data Collector and Data Discloser on the one hand, and the WHIV components on the other hand. The purpose of these APIs is to make calling the WHIV functions as simple as possible, given the functions of the Data Discloser and Data Collector. Ultimately, we would like to see these APIs standardized. Having such APIs allows different Parties to create their own version of the WHIV components, supporting the SSI technologies as they see fit, and shrinking or expanding functionalities as they feel appropriate. Parties can then select such WHIV components as they see fit. +The '**ESSIF Glue**' interface layer consists of a [documented set of APIs](https://gitlab.grnet.gr/essif-lab/tno-ssi-service/developer-docs) between the %%Data Collector|data-collector%% and %%data discloser|data-discloser%% on the one hand, and the WHIV components on the other hand. The purpose of these APIs is to make calling the WHIV functions as simple as possible, given the functions of the %%data discloser|data-discloser%% and %%Data Collector|data-collector%%. Ultimately, we would like to see these APIs standardized. Having such APIs allows different %%parties|party%% to create their own version of the WHIV components, supporting the SSI technologies as they see fit, and shrinking or expanding functionalities as they feel appropriate. Parties can then select such WHIV components as they see fit. The **SSI Tech APIs** interface layer is the union of the interfaces of the components within it. Any standardization in there is outside the scope of eSSIF-Lab. @@ -116,55 +118,55 @@ This section details the functional specifications of the components that are in ### 3.1. Data Collector and Validation Policy -The purpose of the Data Collector (Data Collector) is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an Agent of) its Owner to decide whether or not to engage in a (new) transaction of the specified type. +The purpose of the %%data collector|data-collector%% 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 %%principal|principal%% to decide whether or not to engage in a (new) transaction of the specified type. -Typically, the Data Collector would start a transaction either +Typically, the %%data collector|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.[^DC.1] +- when it receives a request from some %%agent|agent%% of another %%party|party%% for engaging in a transaction of a specific kind. +- when it is instructed by, or on behalf of its %%principal|principal%%, to request a specific kind of transaction to some %%agent|agent%% of another %party.[^DC.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 communication channels. +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|agent%% that requested the transaction, but also with other %%agents|agent%% from the same %%principal|principal%% and/or using different %%communication channels|communication-channel%%. -Handling/managing the various communication channels through which data can be exchanged is also a task of the Data Collector[^DC.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). +Handling/managing the various %%communication channels|communication-channel%% through which data can be exchanged is also a task of the Data Collector[^DC.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 party|peer-party%%. Another reason is that the %%peer party|peer-party%% may use multiple %%agents|agent%% to provide such data, e.g. human %%agents|agent%% (that might use web-browsers, social-media apps, phones, or physical visits), %%SSI-agents|ssi-agent%% (that use the SSI infrastructure), or other %%electronic agents|digital-agent%% (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. +Thus, the %%Data Collector|data-collector%% is generally considered capable of obtaining data through different %%communication channels|communication-channel%%. However, the technical tracks of eSSIF-Lab will exclusively focus on the %%communication channel|communication-channel%% through which %%credentials|credential%% can be requested and obtained. Any extensions or business productization of %%Data Collector|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.[^DC.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.[^DC.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.[^DC.5] +In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the %%data collector|data-collector%% needs to know what kinds of %%credentials|credential%% it should ask for, which %%parties|party%% its %%principal|principal%% trusts to issue such %%credentials|credential%%, what kinds of verification proofs for such %%credentials|credential%% must hold and which may be disregarded.[^DC.3] Also, when the %%data collector|data-collector%% gets a %%credential|credential%% that satisfies the necessary verification proofs, it needs a way to map the contents of that %%credential|credential%% to the structure of the transaction context that is used internally by (other systems of) its %principal.[^DC.4] Also, as the %%data collector|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.[^DC.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: +In order to make the %%data collector|data-collector%% work, a %%Validation Policy|validation-policy%% (or %%data collector policy|data-collector-policy%%) is created by, or on behalf of the %%principal|principal%%, which specifies at least: -- the kinds of transactions the Owner is willing to (electronically) engage in, from both the requester and the provider perspectives; +- the kinds of transactions the %%principal|principal%% 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[^DC.6]. + - the kinds of %%credentials|credential%% and %%issuers|issuer%% that the %%principal|principal%% is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing %%parties|party%% do the actual %%credential|credential%% issuing may be specified[^DC.6]. - - for each kind of credential: the verification proofs that must hold to be accepted as a source for valid data. + - 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 mapping between fields in such %%credentials|credential%% 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 %%policy|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.[^DC.7] +The ability to create new transaction contexts and the availability of the %%data collector policy|data-collector-policy%% enable the %%data collector|data-collector%% to request the %%verifier|verifier%% component of its %%principal|principal%% to obtain %%credentials|credential%% of the types that it can use to fill in the transaction form when they satisfy the verification and validation requirements of its %principal.[^DC.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. +When the %%verifier|verifier%% returns such data (which comes with a list of proofs that the %%verifier|verifier%% has checked), the %%data collector|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|party%%-specific and hence come from the %%data collector policy|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|data-collector%% itself must make validation decisions, either electronically (according to the%%data collector policy|data-collector-policy%%) or by ‘outsourcing’ such decisions to human %%agents|agent%% of its %%principal|principal%% 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’. +As long as data is needed, the %%data collector|data-collector%% can intermittently request the %%verifier|verifier%% to produce it (or it can use other %%communication channels|communication-channel%%, which is outside scope for now). It does so until it times out, or the form has become ‘clean’. ----- -[^DC.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). +[^DC.1]: This feature ensures that the transaction is really two-way, and both %%parties|party%% can request %%credentials|credential%% from the other. For example, a web-shop can then ask for a (delivery) address %%credential|credential%%, and the customer can ask for a %%credential|credential%% issued e.g. by the chamber of commerce that the web-shop is a legitimate company (and not some maffia website). [^DC.2]: It may well be that this functionality can somehow be split off in the (near) future. -[^DC.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. +[^DC.3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the %%principal|principal%% of the %%data collector|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. -[^DC.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. +[^DC.4]: For example, a %%credential|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 %%principal|principal%% have implemented. Mapping allows such cases to be accommodated for. [^DC.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. -[^DC.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. +[^DC.6]: This enables the %%data collector|data-collector%% to pass the endpoint URI on to the %%verifier|verifier%% when it requests for such a %%credential|credential%%, which in turn can send it to the %%holder|holder%% of other %%parties|party%% enabling them to obtain the %%credential|credential%% from that %%issuer|issuer%% endpoint if that other %%party|party%% does not have that %%credential|credential%% in its %%wallet|wallet%%. The endpoint URI can in fact be put in the %%policy|policy%%, because the (human) %%agent|agent%% that creates/maintains the %%policy|policy%% would need to know that the issuing %%party|party%% is actually issuing such %%credentials|credential%%, what their contents means, etc., and hence is capable of tracking down the URI where that %%party|party%% issues the %%credentials|credential%%. [^DC.7]: A reference to this specification will be added when it becomes available (draft or otherwise). @@ -172,114 +174,113 @@ As long as data is needed, the Data Collector can intermittently request the ver ### 3.2. Verifier Component, and its Policy/Preferences -The purpose of the Verifier component is to support the Data Collector by providing it with a single, simple API that it can use to request and obtain data that it needs to produce a clean transaction form, as well as the results of checking verification proofs (this is also why it is called the ‘verifier’ component). +The purpose of the %%verifier|verifier%% component is to support the %%data collector|data-collector%% by providing it with a single, simple API that it can use to request and obtain data that it needs to produce a clean transaction form, as well as the results of checking verification proofs (this is also why it is called the ‘%verifier’ component). -Typically, the Data Collector would ask the Verifier to provide a credential that it can use to fill in a (coherent set of) field(s) in the transaction form. It is realistic to think that credentials from different issuers - trusted by the Verifier’s Owner - can be used for this purpose. However, it is also realistic that such credentials will not use the same credential definition - they might well use different schemes to provide such data. Therefore, the Data Collector should specify a list of pairs (credential-type, issuer) instances of which could all be used to provide the data it needs - which it can obtain from the Data Collector policy. +Typically, the %%data collector|data-collector%% would ask the %%verifier|verifier%% to provide a %%credential|credential%% that it can use to fill in a (coherent set of) field(s) in the transaction form. It is realistic to think that %%credentials|credential%% from different %%issuers|issuer%% - trusted by the %verifier’s %%principal|principal%% - can be used for this purpose. However, it is also realistic that such %%credentials|credential%% will not use the same %%credential type|credential-type%% - they might well use different schemes to provide such data. Therefore, the %%data collector|data-collector%% should specify a list of pairs (%credential-type%, %issuer) instances of which could all be used to provide the data it needs - which it can obtain from the %%data collector policy|data-collector-policy%%. -Then, the Verifier needs to know the address and protocol that it can use to reach a Holder component owned by the Party that its Owner is trying to negotiate the transaction with. The Data Collector specifies this as part of the request - and it can do so because it has received the original request, and does all communication channel handling. +Then, the %%verifier|verifier%% needs to know the address and protocol that it can use to reach a %%holder|holder%% component owned by the %%party|party%% that its %%principal|principal%% is trying to negotiate the transaction with. The %%data collector|data-collector%% specifies this as part of the request - and it can do so because it has received the original request, and does all %%communication channel|communication-channel%% handling. -Verifiers are not expected to handle every kind of credential (e.g. VC’s, ABC’s, etc.) that exists, but rather a specific subset. For (at least one of) the credential types, the Verifier can construct a so-called presentation request, i.e. a message that is specific for the credential type and/or associated protocol, which it can then send to the Holder’s address. +%%verifiers|verifier%% are not expected to handle every kind of %%credential|credential%% (e.g. VC’s, ABC’s, etc.) that exists, but rather a specific subset. For (at least one of) the %%credential types|credential-type%%, the %%verifier|verifier%% can construct a so-called %%presentation request|presentation-request%%, i.e. a message that is specific for the %%credential type|credential-type%% and/or associated protocol, which it can then send to the %holder’s address. This request message should contain at least - the transaction-id, so that when it is copied into the associated response message, the latter can be associated to the transaction it belongs to. Also, it should contain the -- the (credential type, issuer) pairs that may satisfy the request, and to each of these additional data, e.g. the URI of the endpoint where the issuer issues such credentials, the maximum age of the credential, etc. -- meta-data that may be useful for the holder (or its Owner), e.g. texts stating the purpose(s) for which the data will be used ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 5.1.b), or requesting consent ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 7.2) “in an intelligible and easily accessible form, using clear and plain language”. -- a signature of the Verifiers Owner, for the purpose of showing compliance with the [*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) (e.g. Art 28.3.h), and enabling the Holder’s Owner to obtain proof that the Verifiers Owner has violated the [*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN)’s minimization principle asked for data for a particular purpose, which can be used in an argument in disputes about data minimization ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 5.1.c). +- the (%credential type%, %issuer) pairs that may satisfy the request, and to each of these additional data, e.g. the URI of the endpoint where the %%issuer|issuer%% issues such %%credentials|credential%%, the maximum age of the %%credential|credential%%, etc. +- meta-data that may be useful for the %%holder|holder%% (or its %principal), e.g. texts stating the purpose(s) for which the data will be used ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 5.1.b), or requesting consent ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 7.2) “in an intelligible and easily accessible form, using clear and plain language”. +- a signature of the %%verifiers|verifier%% %%principal|principal%%, for the purpose of showing compliance with the [*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) (e.g. Art 28.3.h), and enabling the %holder’s %%principal|principal%% to obtain proof that the %%verifiers|verifier%% %%principal|principal%% has violated the [*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN)’s minimization principle asked for data for a particular purpose, which can be used in an argument in disputes about data minimization ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 5.1.c). The request message must be designed in such a way that it is extendable as new features will be called for in the future. -In order to make the Verifier component work, a Verifier Policy/Preferences object is created by, or on behalf of the Owner, which specifies at least: \[to be elaborated\] +In order to make the %%verifier|verifier%% component work, a %%Verifier|verifier%% Policy%/Preferences object is created by, or on behalf of the %%principal|principal%%, which specifies at least: \[to be elaborated\] -A response to this request (called a Presentation) will be obtained from a Holder component of the Peer Party. This response will contain a reference to the request, allowing the Verifier to combine them. The Verifier will then check that the data in the response is a credential that it has asked for (correct type/issuer), verify the proofs that are provided (predominantly the digital signature), and do some additional checks (e.g. whether or not the credential has expired, is revoked, and such). +A response to this request (called a %presentation) will be obtained from a %%holder|holder%% component of the %%peer party|peer-party%%. This response will contain a reference to the request, allowing the %%verifier|verifier%% to combine them. The %%verifier|verifier%% will then check that the data in the response is a %%credential|credential%% that it has asked for (correct type/%issuer), verify the proofs that are provided (predominantly the digital signature), and do some additional checks (e.g. whether or not the %%credential|credential%% has expired, is revoked, and such). -Then, the verifier will send a message to the Data Collector, containing the transaction-id, the data it has received, and the results of the various checks. +Then, the %%verifier|verifier%% will send a message to the %%data collector|data-collector%%, containing the transaction-id, the data it has received, and the results of the various checks. ### 3.3. Holder Component, and its Policy/Preferences -The purpose of the Holder component is to handle Presentation Requests that it receives from Verifier components (both of its own Owner, and of other Parties), and responding to such requests. +The purpose of the %%holder|holder%% component is to handle %%Presentation Requests|presentation-request%% that it receives from %%verifier|verifier%% components (both of its own %%principal|principal%%, and of other %parties), and responding to such requests. -Typically, a Holder component would access its Owner's Wallet to check if it has a credential that it can use to construct a Presentation (i.e. response) that satisfies the received request. +Typically, a %%holder|holder%% component would access its %%principal's|principal%% %%wallet|wallet%% to check if it has a %%credential|credential%% that it can use to construct a %%presentation|presentation%% (i.e. response) that satisfies the received request. -It may happen that the Wallet does not have such a credential. However, for every (credential, issuer) pair, the request should specify the URI that is capable of issuing such a credential. If or when the Holder Policy/Preferences permit this, the Holder then requests its Owner’s Data Collector to initiate a new transaction that will get the credential from that issuer, for which a clean transaction form would then consist of one that contains said credential. The Holder would then store it in its Owner’s Wallet, and then proceed to service the presentation request as if it had obtained that credential from its Owner’s Wallet. +It may happen that the %%wallet|wallet%% does not have such a %%credential|credential%%. However, for every (%credential, %issuer) pair, the request should specify the URI that is capable of issuing such a %%credential|credential%%. If or when the %%Holder|holder%% Policy%/Preferences permit this, the %%holder|holder%% then requests its %principal’s %%data collector|data-collector%% to initiate a new transaction that will get the %%credential|credential%% from that %%issuer|issuer%%, for which a clean transaction form would then consist of one that contains said %%credential|credential%%. The %%holder|holder%% would then store it in its %principal’s %%wallet|wallet%%, and then proceed to service the %%presentation|presentation%% request as if it had obtained that %%credential|credential%% from its %principal’s %%wallet|wallet%%. -It may also happen that the Wallet has multiple credentials that satisfy the request, in which case the Holder must choose the one to use for constructing the presentation. Again, the Holder Policy/Preferences will specify how this choice needs to be made, and whether or not this can be done automatically by the Holder. If not, the Holder will need to provide for an interaction with a human Colleague that will make such decisions. +It may also happen that the %%wallet|wallet%% has multiple %%credentials|credential%% that satisfy the request, in which case the %%holder|holder%% must choose the one to use for constructing the %%presentation|presentation%%. Again, the %%Holder|holder%% Policy%/Preferences will specify how this choice needs to be made, and whether or not this can be done automatically by the %%holder|holder%%. If not, the %%holder|holder%% will need to provide for an interaction with a human Colleague that will make such decisions. -In order to make the Holder component work, a Holder Policy/Preferences object is created by, or on behalf of the Owner, which specifies e.g.: +In order to make the %%holder|holder%% component work, a %%Holder|holder%% Policy%/Preferences object is created by, or on behalf of the %%principal|principal%%, which specifies e.g.: -- whether or not credentials may be collected ‘on the fly’; -- how to choose between credentials that all satisfy a presentation request (and whether the Holder can make such choices by itself, or whether or not human interaction is required); -- the kinds of events and data to write to a holder-audit-log. +- whether or not %%credentials|credential%% may be collected ‘on the fly’; +- how to choose between %%credentials|credential%% that all satisfy a %%presentation request|presentation-request%% (and whether the %%holder|holder%% can make such choices by itself, or whether or not human interaction is required); +- the kinds of events and data to write to a %%holder|holder%%-audit-log. ### 3.4. Data Discloser and Issuing Policy -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. +The purpose of the %%data discloser|data-discloser%% component is to state the (various, sometimes intermediary) results of %%transactions|business-transaction%%, by collecting data from the Business Data Stores, and creating a set of (related) %%statements/claims|assertion%% that can subsequently be issued to other %%parties|party%%. A special kind of result is the (provisioning of) a %%credential|credential%% that its %%principal|principal%% already has created. -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|party%% are capable of expressing %%statements|assertion%% about %%entities|entity%% that they know to exist. They could express %%statements|assertion%% about individuals, about themselves, the state of transactions, and so on. We will use the term ‘**subject (of a %%statement|assertion%% of a %party)**’ to refer to the %%entity|entity%% that this %%party|party%% knows to exist, and about whom/which the %%statement|assertion%% 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|assertion%% of a %party)**’ to refer to the representation that this %%party|party%% has chosen to use for referring to the subject in said %%statement|assertion%%. A subject-id must have the property of being an %%identifier|identifier%% within every administrative context that this %%party|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.[Data Discloser.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. +%%parties|party%% need to specify the kinds of %%credentials|credential%% they are willing to issue, the class of %%entities|entity%% (e.g. people, cars, %organizations) for which it will issue them, and the information schema (structure) that it will use in %%credentials|credential%% of such kinds.[Data Discloser.1] This allows the %%data discloser|data-discloser%% to construct data objects that conform to this information schema, and present it to the %%issuer|issuer%% component for actual issuing. -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. +The %%data discloser policy|data-discloser-policy%% specifies the kinds of (linked-)data-objects that %%credentials|credential%% may be created for. This allows the %%data discloser|data-discloser%% to construct such a (linked-)data-objects for every subject-id that identifies a subject of the class for which a %%credential|credential%% can be issued, which can subsequently be sent to the %%issuer|issuer%% component that can turn it into a %%credential|credential%% of a specific sort. -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. +You can think of the %%data discloser|data-discloser%% as the component that pulls all data together that can be put in a %%credential|credential%% (e.g. in a passport), and the %%issuer|issuer%% as the component that puts the data in an (empty) passport, and signing it so as to create the actual %%credential|credential%%. -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. +The %%data discloser|data-discloser%% may either push %%credential|credential%% data to the %%issuer|issuer%% component, so that the %%issuer|issuer%% always has up-to-date %%credentials|credential%%, or it can wait until the %%issuer|issuer%% requests %%credential|credential%% data for the creation of a %%credential|credential%% of a specific type for a specific subject. ----- -[Data Discloser.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. +[Data Discloser.1] We assume/stipulate that the %%party|party%% maintains a %%credential-catalogue|credential-catalogue%% that contains this, and other information about every kind of %%credential|credential%% that it issues, and that such catalogues are available to other %%parties|party%% that want or need to use such %%credentials|credential%%. ----- - ### 3.5. Issuer Component, and its Policy/Preferences -The purpose of the Issuer component is to issue ‘credentials’, i.e. digital constructs that contain +The purpose of the %%issuer|issuer%% component is to issue ‘%credentials’, i.e. digital constructs that contain -- sets of (related) statements or claims (e.g. as produced by the Data Discloser) -- metadata (e.g. type of credential, date of issuing and expiration, endpoints, e.g. for revocation checking, credential definition, credential advertisements, credential enforcement policy, etc.) -- proofs (e.g. a digital signature by which third Parties can prove its provenance and integrity. +- sets of (related) %%statements/claims|assertion%% (e.g. as produced by the %%data discloser|data-discloser%%) +- metadata (e.g. type of %%credential|credential%%, date of issuing and expiration, endpoints, e.g. for revocation checking, %%credential type|credential-type%%, credential advertisements, credential enforcement policy, etc.) +- proofs (e.g. a digital signature by which third %%parties|party%% can prove its provenance and integrity. -Another purpose that an Issuer might serve is to provide a means that allows any other Agent that somehow has obtained a copy or presentation of a credential, to verify whether or not the data therein is conformant to the business administration of its Owner. We will use the term ‘revocation service’ to refer to such means. Whether or not an Issuer provides such a service, and what kind of revocation service is provided (e.g. a revocation list, an online revocation status protocol, etc.), is a decision that its Owner should make, and specify in the Issuer Policies/Preferences. +Another purpose that an %%issuer|issuer%% might serve is to provide a means that allows any other %%agent|agent%% that somehow has obtained a copy or %%presentation|presentation%% of a %%credential|credential%%, to verify whether or not the data therein is conformant to the business administration of its %%principal|principal%%. We will use the term ‘revocation service’ to refer to such means. Whether or not an %%issuer|issuer%% provides such a service, and what kind of revocation service is provided (e.g. a revocation list, an online revocation status protocol, etc.), is a decision that its %%principal|principal%% should make, and specify in the %%issuer|issuer%% policies%/Preferences. -An Issuer component may issue credentials in various formats, e.g. as a Verifiable Credential (VC), an Attribute-Based Credential (ABC), an OpenID Connect/JWT token, etc. The issuing Party must specify credential-types in such a way that if the same credential is issued in different formats, it is possible for an arbitrary Verifier to determine whether or not two credentials that have different formats, are in fact the same. One way of doing this is that the Issuer generates an identifier for every credential that it constructs (before expressing it in a specific format). +An %%issuer|issuer%% component may issue %%credentials|credential%% in various formats, e.g. as a Verifiable Credential (VC), an Attribute-Based Credential (ABC), an OpenID Connect/JWT token, etc. The issuing %%party|party%% must specify %%credential types|credential-type%% in such a way that if the same %%credential|credential%% is issued in different formats, it is possible for an arbitrary %%verifier|verifier%% to determine whether or not two %%credentials|credential%% that have different formats, are in fact the same. One way of doing this is that the %%issuer|issuer%% generates an %%identifier|identifier%% for every %%credential|credential%% that it constructs (before expressing it in a specific format). -After the issuer has created a credential (in one or more formats), it checks the wallet to see if it contains a credential of the same type for the same subject. If (one or more formats) are there, and their contents are the same as the newly created credential, the existing ones are revoked, deleted and/or archived/tombstoned.[Issuer.1] Then, the newly created credential is added to the wallet (in one or more formats). Thus, at any point in time, the wallet will contain an actual set of all credentials that have been issued.[Issuer.2] +After the %%issuer|issuer%% has created a %%credential|credential%% (in one or more formats), it checks the %%wallet|wallet%% to see if it contains a %%credential|credential%% of the same type for the same subject. If (one or more formats) are there, and their contents are the same as the newly created %%credential|credential%%, the existing ones are revoked, deleted and/or archived/tombstoned.[Issuer.1] Then, the newly created %%credential|credential%% is added to the %%wallet|wallet%% (in one or more formats). Thus, at any point in time, the %%wallet|wallet%% will contain an actual set of all %%credentials|credential%% that have been issued.[Issuer.2] ----- [Issuer.1] Tombstoning is a mechanism that is used e.g. in (distributed) ledgers that do not allow for actual deletion, such as blockchains, by marking entries in the ledger as ‘being deleted’ (i.e. adding a ‘tombstone’ to such entries). -[Issuer.2] This allows e.g. individuals, that have an Issuer component in their SSI app, to issue self-signed credentials and provide them to verifiers that request them as usual for non-self-signed credentials. +[Issuer.2] This allows e.g. individuals, that have an %%issuer|issuer%% component in their SSI app, to issue self-signed %%credentials|credential%% and provide them to %%verifiers|verifier%% that request them as usual for non-self-signed %%credentials|credential%%. ----- ### 3.6. Wallet Component, and its Policy/Preferences -The primary purpose of the Wallet Component is to (securely) store data, and in particular: +The primary purpose of the %%wallet|wallet%% Component is to (securely) store data, and in particular: -- credentials - both those that have been issued by the issuer (i.e. self-signed credentials) and those that have been obtained from issuers of other Parties, and -- (private) keys e.g. for signing/sealing data on behalf of its Owner. +- %%credentials|credential%% - both those that have been issued by the %%issuer|issuer%% (i.e. self-signed %credentials) and those that have been obtained from %%issuers|issuer%% of other %%parties|party%%, and +- (private) keys e.g. for signing/sealing data on behalf of its %%principal|principal%%. -Other kinds of data may be stored by a wallet as well - we will have to see what is practical and makes sense. +Other kinds of data may be stored by a %%wallet|wallet%% as well - we will have to see what is practical and makes sense. By ‘securely storing data’ we mean that such data -- remains available until a request is received from an electronic Colleague that is entitled to request deletion of such data; +- remains available until a request is received from an %%digital colleague|digital-colleague%% that is entitled to request deletion of such data; - remains unchanged during the time in which it is stored; -- can only become available to electronic Colleagues that implement a functionality that requires such access (e.g. a Colleague Holder component); -- can only be stored by electronic Colleagues that implement a functionality that require such data to be stored (e.g. a Colleague Holder or Issuer component). +- can only become available to %%digital colleagues|digital-colleague%% that implement a functionality that requires such access (e.g. a %%colleague|colleague%% %%holder|holder%% component); +- can only be stored by %%digital colleagues|digital-colleague%% that implement a functionality that require such data to be stored (e.g. a %%colleague|colleague%% %%holder|holder%% or %%issuer|issuer%% component). -It is expected that components other than the Holder and Issuer will (arise and) need access. One example could be a component that is capable of securely signing data on behalf of the Owner. Another example could be a component that implements some kind of credential revocation functionality. +It is expected that components other than the %%holder|holder%% and %%issuer|issuer%% will (arise and) need access. One example could be a component that is capable of securely signing data on behalf of the %%principal|principal%%. Another example could be a component that implements some kind of credential revocation functionality. -Human beings cannot directly access any Wallet component, not even the ones they own. They need an electronic Agent that is capable of authenticating them as (an Agent of) the Party that owns the Wallet component, and upon successful authentication provides a User Interface through which the Human Being can instruct this electronic Agent to manage the Wallet’s contents. +Human beings cannot directly access any %%wallet|wallet%% component, not even the ones they own. They need an %%electronic agent|digital-agent%% that is capable of authenticating them as (an %%agent|agent%% of) the %%party|party%% that owns the %%wallet|wallet%% component, and upon successful authentication provides a User Interface through which the Human Being can instruct this %%electronic agent|digital-agent%% to manage the %wallet’s contents. -In order to make the Wallet component work, a Wallet Policy/Preferences object is created by, or on behalf of the Owner, the contents of which remains to be specified. +In order to make the %%wallet|wallet%% component work, a %%wallet|wallet%% policy%/Preferences object is created by, or on behalf of the %%principal|principal%%, the contents of which remains to be specified. ## 4. Initial SSI-Agent Network Architecture @@ -287,32 +288,32 @@ In order to make the Wallet component work, a Wallet Policy/Preferences object i *The eSSIF-Lab functional architecture is not final. This chapter is an example of how work that is currently being done may already be documented for the purpose of furthering discussions and providing inspiration to readers.* ::: -Parties need to deploy (technical) components that act as their Agents. Individuals would typically have a mobile app whose user interface allows them to fulfill any or all of the roles of holder, verifier and issuer. Wallet functionality may be included in this app, but it might equally well live in the cloud, as a second (technical) Agent. An individual might also have (cloud) servers that Agents of other parties may contact for conducting transactions without the need for the individual itself to do something. All of this holds equally well for larger Organizations. +%%parties|party%% need to deploy (technical) components that act as their %%agents|agent%%. Individuals would typically have a mobile app whose user interface allows them to fulfill any or all of the roles of %%holder|holder%%, %%verifier|verifier%% and %%issuer|issuer%%. Wallet functionality may be included in this app, but it might equally well live in the cloud, as a second %(digital) agent%. An individual might also have (cloud) servers that %%agents|agent%% of other %%parties|party%% may contact for conducting transactions without the need for the individual itself to do something. All of this holds equally well for larger %%organizations|organization%%. -It is conceivable that the set of SSI functions is spread over multiple (technical) Agents, in which case there is going to be a need for such Agents to contact one another, and conduct transactions in a way that may differ from doing that with Agents of other Parties. Basically, this can be seen as Colleagues interacting with one another to get things done within one Organization. Seen from the outside, it looks like every Organization has a (smaller or larger) network of Agents. This chapter provides more details on this topic. +It is conceivable that the set of SSI functions is spread over multiple %(digital) agents%, in which case there is going to be a need for such %%agents|agent%% to contact one another, and conduct transactions in a way that may differ from doing that with %%agents|agent%% of other %%parties|party%%. Basically, this can be seen as %%colleagues|colleague%% interacting with one another to get things done within one %%organization|organization%%. Seen from the outside, it looks like every %%organization|organization%% has a (smaller or larger) network of %%agents|agent%%. This chapter provides more details on this topic. The SSI-Agent Network Architecture has two viewpoints: -1. the **intra-Party or single-Party SSI viewpoint**, which focuses on the set of (human and/or electronic) Agents of a single, specific Party. -2. the **inter-Party or multi-Party SSI viewpoint**, which is about specific functional components (e.g. Verifier, Holder, etc.) that typically belong to different Parties. +1. the **intra-%party or single-%party SSI viewpoint**, which focuses on the set of (human and/or electronic) %%agents|agent%% of a single, specific %%party|party%%. +2. the **inter-%party or multi-%party SSI viewpoint**, which is about specific functional components (e.g. %%verifier|verifier%%, %%holder|holder%%, etc.) that typically belong to different %%parties|party%%. -An individual Party may use the single-Party SSI viewpoint to come to grips with concerns related to the creation and maintenance of its network of its electronic Agents. The set of concerns would include: +An individual %%party|party%% may use the single-%party SSI viewpoint to come to grips with concerns related to the creation and maintenance of its network of its %%electronic agent|digital-agent%%. The set of concerns would include: -- How can electronic components be onboarded as an Agents of this Party? -- How can the integrity of such electronic Agents be stated in a trustworthy manner (do such components need some kind of accreditation certificate, do we need to come up with a service that can remotely test the integrity of a component and have it issue ephemeral integrity-certificates/credentials, …)? -- How can the Party specify which of its Agents may talk with which other Agents, and for what purposes? -- How should a Party specify the policies for the various SSI functionalities - what kind of support would be useful here? +- How can electronic components be onboarded as an %%agents|agent%% of this %party? +- How can the integrity of such %%electronic agent|digital-agent%% be stated in a trustworthy manner (do such components need some kind of accreditation certificate, do we need to come up with a service that can remotely test the integrity of a component and have it issue ephemeral integrity-certificates/%credentials, …)? +- How can the %%party|party%% specify which of its %%agents|agent%% may talk with which other %%agents|agent%%, and for what purposes? +- How should a %%party|party%% specify the policies for the various SSI functionalities - what kind of support would be useful here? - … -Parties that want (their Agents) to interact with one another may use the multi-Party SSI viewpoint to come to grips with concerns related to the interoperability of the functionalities that their components implement. The set of concerns would include: +%%parties|party%% that want (their %agents) to interact with one another may use the multi-%party SSI viewpoint to come to grips with concerns related to the interoperability of the functionalities that their components implement. The set of concerns would include: -- How can Parties interact with one another at the information level (this includes decentralized semantic interoperability issues, advertising credentials, how a Party can find other Parties that issue credentials that are useful to him, etc.) -- What kinds of underlying technologies must Agents of a Party support so as to be(come) interoperable with Parties that it wants to interact with? +- How can %%parties|party%% interact with one another at the information level (this includes decentralized semantic interoperability issues, advertising %%credentials|credential%%, how a %%party|party%% can find other %%parties|party%% that issue %%credentials|credential%% that are useful to him, etc.) +- What kinds of underlying technologies must %%agents|agent%% of a %%party|party%% support so as to be(come) interoperable with %%parties|party%% that it wants to interact with? - … ## 5. High Level Transaction Flows -This chapter explains at a high level how electronic business transactions are being conducted. This is prerequisite to the explanations in chapter 4, that describe how the eSSIF-Lab architectural components are used in such transactions. For illustrative purposes, we stick to the example of getting a parking permit that we introduced in section 1.1. +This chapter explains at a high level how electronic %%business transactions|business-transaction%% are being conducted. This is prerequisite to the explanations in chapter 4, that describe how the eSSIF-Lab architectural components are used in such %%transactions|business-transaction%%. For illustrative purposes, we stick to the example of getting a parking permit that we introduced in section 1.1. ### 5.1. Overview @@ -325,19 +326,19 @@ This chapter explains at a high level how electronic business transactions are b *Figure 3: High-level transaction overview.* -The adjacent figure shows how a transaction is conducted at the highest abstraction level. One Party, called the ‘Requester’, sends a request for a product or service to another Party (that we will call the ‘Provider’). Then, they start to negotiate a ‘transaction agreement’, which means that they exchange data through various channels for the purpose of establishing the details of the product/service to be provided and the compensation, data needed to mitigate transaction risks, etc., all of which is necessary for the Parties to (individually/subjectively) decide whether or not to commit to the transaction. Section 3.2 provides more detail about this phase. +The adjacent figure shows how a transaction is conducted at the highest abstraction level. One %%party|party%%, called the ‘Requester’, sends a request for a product or service to another %%party|party%% (that we will call the ‘Provider’). Then, they start to negotiate a ‘transaction agreement’, which means that they exchange data through various channels for the purpose of establishing the details of the product/service to be provided and the compensation, data needed to mitigate transaction risks, etc., all of which is necessary for the %%parties|party%% to (individually/subjectively) decide whether or not to commit to the transaction. Section 3.2 provides more detail about this phase. After commitment, the producer works to provide the product or service, and the requester arranges the compensation. This phase is entirely up to the business, and hence out of scope of this document. -When all is done, Parties may issue a (signed) statement that specifies the results. Section 3.3. provides some more details about this phase. +When all is done, %%parties|party%% may issue a (signed) %%statement|assertion%% that specifies the results. Section 3.3. provides some more details about this phase. -In the example of the parking permit, a citizen (requester) sends a request to its municipality (provider) for obtaining a parking permit (the product/service). Then, the citizen fills in an online form (and uploads necessary PDFs) to enable the municipality to decide whether or not to produce the requested permit. The eSSIF-lab architecture adds a secondary, electronic channel that allows citizens to fill in the forms by using e.g. an SSI app on their phone. When the form is complete, the municipality decides whether or not to produce and issue the permit, which it can do as usual. It can also issue a credential that states the result of the transaction, i.e. contains the details of the parking permit. +In the example of the parking permit, a citizen (requester) sends a request to its municipality (provider) for obtaining a parking permit (the product/service). Then, the citizen fills in an online form (and uploads necessary PDFs) to enable the municipality to decide whether or not to produce the requested permit. The eSSIF-lab architecture adds a secondary, %%electronic communication channel|digital-communication-channel%% that allows citizens to fill in the forms by using e.g. an SSI app on their phone. When the form is complete, the municipality decides whether or not to produce and issue the permit, which it can do as usual. It can also issue a %%credential|credential%% that states the result of the %%transaction|business-transaction%%, i.e. contains the details of the parking permit. -Please note that while transactions are symmetrical in nature (i.e. both requester and provider need data from the other so as to decide whether or not to commit to the transaction), there is an implicit asymmetry in that activities that Parties perform are ordered in time, which implies e.g. that the commitment decisions of both Parties cannot be done at the same time. Also, in practice, it often happens that a Party requires the other Party to have executed (and stated) its part of the transaction before it actually commits to the transaction. For example, a provider may require the requester to have paid for the product before it is being shipped out. Consequently, the protocols for exchanging data/credentials will need to support such ‘asynchronous’ ways of working. +Please note that while %%transactions|business-transaction%% are symmetrical in nature (i.e. both requester and provider need data from the other so as to decide whether or not to commit to the transaction), there is an implicit asymmetry in that activities that %%parties|party%% perform are ordered in time, which implies e.g. that the commitment decisions of both %%parties|party%% cannot be done at the same time. Also, in practice, it often happens that a %%party|party%% requires the other %%party|party%% to have executed (and stated) its part of the transaction before it actually commits to the transaction. For example, a provider may require the requester to have paid for the product before it is being shipped out. Consequently, the protocols for exchanging data/%credentials will need to support such ‘asynchronous’ ways of working. ### 5.2. Transaction Negotiation Phase -This phase starts by the requester sending a transaction request to the provider, and ends whenever either one of the Parties quits, or both Parties commit. +This phase starts by the requester sending a transaction request to the provider, and ends whenever either one of the %%parties|party%% quits, or both %%parties|party%% commit. High-level transaction negotiation ` 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 ` ISA `. 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 **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 ` ` 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 ` ISA `. It means that SRC is a specialization of TGT (which in turn is a generalization of SRC). It means that SRC must satisfy all constraints that TGT must satisfy, and also that it has all attributes (including properties) that TGT has. +- A **solid line with a solid diamand** at one end is a composition; the element at the 'non-diamond-end' of the line is 'part of' (the 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' also cease to exist. +- A **solid line with a hollow diamand** at one end is an aggregation; the element at the 'non-diamond-end' of the line is 'part of' (the 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' usually do not cease to exist, but 'live on'. +- A **green name** at either end of a relation/association is what UML calls 'role'; this name may be used to refer to (an instance of) the concept at which the name is placed as it performs its/this role in this relation. +- A **dashed line** with a closed arrow (solid triangle) signifies that its intension is created by combination the intensions of other relations (it is a ‘shorthand’ for a path of other relations). +- A **dashed line** with a pointed arrow (`>`) represents a dependency, where the SRC concept somehow depends on the TGT concept. The kind of dependency is specified by `<>`, where `text` specifies the kind of dependency. Example: `<>` 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. diff --git a/docs/pattern-list.md b/docs/pattern-list.md index 6bcc69e8daac24ebc79ef7248cafb8e9e69e78d2..a9cf95b262c631d3d6ae2e7edec41664b186a2b6 100644 --- a/docs/pattern-list.md +++ b/docs/pattern-list.md @@ -1,10 +1,30 @@ --- id: essifLab-pattern-list -title: "eSSIF-Lab List of Patterns" +title: "eSSIF-Lab Ways of Thinking" sidebar_label: Mental Models --- -:::info Editor's note +:::note Editor's note TNO to write the introduction paragraph -Remainder of file to be generated (GRNET plugin/extension) +Remainder of file to be generated (GRNET plugin/extension) - currently, the file is maintained 'by hand' +::: + +Within eSSIF-Lab, we maintain a set of %%mental models|mental-model%%, i.e. casual and formal descriptions (patterns) of %%concepts|concept%%, relations between them, and constraints, that provide a specific 'viewpoint', or 'way of thinking' about a certain topic. + +:::info Editor's note +While some of the topics listed below are pretty much done, others are still need more work. ::: + +We currently have models for the following topics: + +- [Duties and Rights](./terms/pattern-duties-and-rights): The Duties and Rights pattern describes the relations between Jurisdictions, Legal Entities and the duties and rights they have within them. + +- [Guardianship relationships](./terms/pattern-guardianship): The Guardianships pattern captures the Concepts and relations that explain what a generic Guardianship consists of, and how it relates to Guardians, Dependents, Jurisdictions, etc. + +- [Jurisdictions](./terms/pattern-jurisdiction): The Jurisdictions pattern captures the Concepts and relations that explain what a generic Jurisdiction consists of, and relates it to Parties and Legal Entities. + +- [Mandates, Delegation and Hiring](./terms/pattern-mandates-delegation-hiring): The Mandates, Delegation and Hiring pattern (which remains to be documented) captures the ideas behind Mandating, Delegating, Hiring and their relations. This is a work-in-progress. + +- [Parties, Actors and Actions](./terms/pattern-party-actor-action): The Parties, Actors and Actions pattern captures the foundational concepts and relations that we need for thinking about how things get done. It answers questions such as: 'Who/what does things?', 'How are their actions being guided/controlled?', 'Who controls whom/what?', 'Who/what may be held accountable?'. + +- [Terminology:](./terms/pattern-terminology): The eSSIF-Lab Terminology Pattern describes the relations between Terminology Terms such as 'Concept', 'Term', 'Pattern', 'Mental Model', 'Glossary' etc. diff --git a/docs/terminology-maintenance-script.rieks b/docs/terminology-maintenance-script.rieks new file mode 100644 index 0000000000000000000000000000000000000000..c7ed67d6df2aea2fd1a511398021b063598e8e73 --- /dev/null +++ b/docs/terminology-maintenance-script.rieks @@ -0,0 +1,188 @@ +// Purpose: replace %-marked words (including some varieties such as plurals) with %%-syntax for those words. + +// This is a script that can be run by the Batch Replacer extension of VSCode . +// Press Ctrl-Shift-P as you are editing this script, then search for `Batch Replacer`, and execute it. + +// Executing the script will do the following replacements consecutively: +// 1. `%text with possibly spaces%` --> `%%text with possibly spaces%%` +// 2. `%text-without-spaces` --> `%%text-without-spaces%%` (some punctuation around it is allowed) +// 3. `%%Show Text%%` --> `%%Show Text|Show-Text%%` (sorry, we cannot make the reftext lowercase) +// Now, you have to manually execute /(?<=\|)([A-Z][^%]*)(?=%%)/\L$1/g/ +// 4. `|ref-text%% is being checked to see if modifications need to be made (e.g. plurals to singular etc.) +// 5. There is a cleanup phase that removes any %%...|...%% syntax from the docusaurus header, markdown headers, and constructs. + +// Complex regular expressions can be created using variables. Variables are applied to the entire script, and should be defined at the beginning of the script. Variables are defined as ... = "..." and are used as %{...}. Variables can only be used in the replace and replace-regex instructions. +// variables can reference themselves and be overwritten - see documentation of 'batch replacer' extension + +beg = "(?<=\W%%)" +mid = "(?<=\|)" +end = "(?=%%\W)" + +dutyright = "(?:dut(?:y|ies)|rights?)" +dutyright = "%{dutyright}(?:-*(?:/|and|or|and/or)-*%{dutyright})?" +dutyrighttype = "%{dutyright}-types?" + +// If you do not specify the files to work on, the replace will be global (throughout the workspace). +// `filter "document.txt"` - document.txt file in the root folder +// `filter "Documents/document.txt"` - document.txt file in the Documents folder in the root folder +// `filter "**/document.txt"` - document.txt files anywhere +// `filter "*.txt"` - any .txt file in the root folder +// `filter "**/*.txt"` - any .txt file + +filter "docs/terms/credential-type.md" + +// PREPROCESSING: convert single-%-notations into %%-notations. + +// We might want to 'undo' %%...|...%% markers in case some 'show text' needs to be associated wiht another 'reftext' +// replace-regex "(\W%)%([^\|\n\r]+)\|[^%\n\r]+%(%\W)" +// with "$1$2$3" + +// First, convert %show text% into %%show text%% +replace-regex "(?<=\s%)(([\w/-]|'|\s)*)(?=%([,.]?\s|-\w))" +with "%$1%" + +// Only thereafter can we convert %showtext (words without trailing `%`-char) into %%showtext%% +replace-regex "(?<=\s%)(([\w/-]|')*)(?=[,.]?\s)" +with "%$1%%" + +// Then, we can expand %%show text%% into %%show text|show text%% +replace-regex "(?<=\W%%)([^\|]*?)(?=%%\W)" +with "$1|$1" + +// Next, we convert the latter part into lowercase +replace-regex "(?<=\|)([^A-Z%]*?[A-Z].*?)(?=%%)" +with-case "lowercase" + +// Next, we replace whitespace in `lowercase show text` instances with `-` characters +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" + +// ACTUAL PROCESSING: now we need to convert well-known `lowercase-show-text`s to appropriate `reftexts` + +// [A] +replace-regex "%{mid}(action|actor|agent|assertion|author)'?s%{end}" +with "$1" + +// [B] +replace-regex "%{mid}(business-transaction)'?s?%{end}" +with "$1" + +// [C] +// for 'claim', see 'statement' +replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)'?s?%{end}" +with "$1" + +replace-regex "%{mid}communications?-(channel|session)'?s?%{end}" +with "communication-$1" + +// [D] +replace-regex "%{mid}(definition|dependent|dictionary-file|dictionary|documentation-interop)'?s?%{end}" +with "$1" +replace-regex "%{mid}(?:electronic-|digital-)(actor|agent|colleague|communication-channel|policy)'?s%{end}" +with "digital-$1" + +replace-regex "%{mid}(%{dutyrighttype}|%{dutyright})%{end}" +with "pattern-duties-and-rights" + +replace-regex "%{mid}data-(collector|discloser)-polic(y's|ies)%{end}" +with "data-$1-policy" +replace-regex "%{mid}data-(collector|discloser)'?s?%{end}" +with "data-$1" + +// [E] +replace-regex "%{mid}(employee|employer)'?s%{end}" +with "$1" +replace-regex "%{mid}(legal-)?entit(y's|ies)%{end}" +with "$1entity" + +// [G] +replace-regex "%{mid}(glossary-file|guardian(ship)?(-relationship)?(-type)?)'?s%{end}" +with "$1" +replace-regex "%{mid}glossar(y's|ies)%{end}" +with "glossary" +replace-regex "%{mid}guardianship(-relationship)?%{end}" +with "guardianship" +replace-regex "%{mid}guardianship(-relationship)?-type%{end}" +with "guardianship-type" +replace-regex "%{mid}govern(or)?s?%{end}" +with "governance" + +// [H-I-J-K] (all holder, issuer, verifier and wallet stuff, too) +// for associated policies, see [P] +replace-regex "%{mid}(holder|issuer|verifier|wallet|identifier|jurisdiction(-governor)?|knowledge(-governor)?)'?s%{end}" +with "$1" + +// [L-M] +replace-regex "%{mid}(legal-jurisdiction|legal-system|mental-model)'?s%{end}" +with "$1" +// for 'legal entities', see 'entities' + +// [O] +replace-regex "%{mid}(objective|organization|owned|owner|ownership)'?s%{end}" +with "$1" + +// [P] +replace-regex "%{mid}(participant|pattern-file|pattern|(peer-)(actor|agent)|policy-governor|presentation-request|presentation|principal)'?s%{end}" +with "$1" +replace-regex "%{mid}(|peer-)part(y's|ies)%{end}" +with "$1party" +replace-regex "%{mid}(|issuer-|holder-|verifier-|wallet-|transaction-data-(collector|discloser)-)polic(y's|ies)%{end}" +with "$1policy" + +// [R-S] +// For 'rights', see [D]uties +replace-regex "%{mid}(risk|scope-file|scope|ssi-agent)'?s%{end}" +with "$1" +replace-regex "%{mid}(statement|claim)'?s%{end}" +with "assertion" + +// [T] +// for transaction data collector/discloers policies, see [P] +replace-regex "%{mid}(term-file|term|transaction-(agreement|data-(collector|discloser)|form|proposal))'?s%{end}" +with "$1" +replace-regex "%{mid}transaction'?s?%{end}" +with "business-transaction" + +// [V] +// for verifier stuff - see holder +replace-regex "%{mid}(verifiable-credential|verifier)'?s%{end}" +with "$1" +replace-regex "%{mid}vocabular(y's|ies)%{end}" +with "vocabulary" + +// [W] +// for wallet stuff - see holder + +// CLEANING UP UNINTENDED CHANGES + +// Remove all `%%showtext|reftext%%` in docusaurus header. +replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)" +with "$1$2$4" +replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)" +with "$1$2$4" +replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)" +with "$1$2$4" +replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)" +with "$1$2$4" +replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)" +with "$1$2$4" + +// Remove all `%%showtext|reftext%%` occurrences in markdown headers +replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)" +with "$1$2$4" +replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)" +with "$1$2$4" + +// Remove all `%%showtext|reftext%%` occurrences in ``-constructs +replace-regex "()" +with "$1$2$4" +replace-regex "()" +with "$1$2$4" diff --git a/docs/terminology-plugin-instructions.md b/docs/terminology-plugin-instructions.md index 4377e59e884bc18889f42e0c6665464682c8c559..f37ff788e17670fbbcccd9c8eab4f9a6d4d61c0b 100644 --- a/docs/terminology-plugin-instructions.md +++ b/docs/terminology-plugin-instructions.md @@ -2,7 +2,7 @@ id: terminology-plugin-instructions title: Terminology & Glossary plugin docs --- -import useBaseUrl from '@docusaurus/useBaseUrl'; // All other .md files get this statement automatically added. +import useBaseUrl from '@docusaurus/useBaseUrl'; // All other .md files may get this statement automatically added. ### How it works diff --git a/docs/terms/assertion.md b/docs/terms/assertion.md index 027ffefc270e4fa1132efb9e706164b8017aaa0d..ff4aa35fd302fa1f21b1a1c0a736a7594a9355ca 100644 --- a/docs/terms/assertion.md +++ b/docs/terms/assertion.md @@ -24,5 +24,9 @@ The ability to distinguish between assertions and non-assertions, and particular ### Criterion An **Assertion** is any declaration/statement that is made by one specific %%party|party%%. +### Notes +- Assertions may be ambiguous (multi-interpretable), which may result in misundertandings. The authoritative meaning of an %%assertion|assertion%% is determined by (the %%semantics|semantics%% that was applied by) the %%party|party%% that has uttered/authored it. +- Assertions may or may not be true. That is not only because 'truth' is subjective (every %%party|party%% may decide whether or not something is true), but also because the %%party|party%% that uttered/authored the %%assertion|assertion%% cannot substantiate the assertion, or lie outright. + ----- [^1]: we postulate that 'Nature' is the %%jurisdiction|jurisdiction%% in which the associated %%ownership relation|ownership%% exists; so one might also call this 'natural ownership'. \ No newline at end of file diff --git a/docs/terms/business-transaction.md b/docs/terms/business-transaction.md index d7367fde6c8cf6d910819157c4bbc5b3a147340f..d25c3c4bcce38bc6ec4fbf43ffb402b61d80da88 100644 --- a/docs/terms/business-transaction.md +++ b/docs/terms/business-transaction.md @@ -8,6 +8,8 @@ stage: draft hoverText: "Business Transaction: the exchange of goods, services, funds, or data between some Parties (called ‘participants’ of the 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. diff --git a/docs/terms/credential-catalogue.md b/docs/terms/credential-catalogue.md new file mode 100644 index 0000000000000000000000000000000000000000..69d6ff63c6681438cf6e8359c919144fac9ecc08 --- /dev/null +++ b/docs/terms/credential-catalogue.md @@ -0,0 +1,13 @@ +--- +id: credential-catalogue +title: "Credential Catalogue" +scopeid: essifLab +type: concept +typeid: credential-catalogue +stage: draft +hoverText: "Credential Catalogue (functional component): the capability to register and advertise Credential Types and any related information that its governing Party decides to disclose for enabling other Parties to decide whether or not it is beneficial for them to request Credentials of such type for some kind(s) of decisions of theirs." +--- + +:::info Editor's note +TNO to provide further content +::: \ No newline at end of file diff --git a/docs/terms/credential-type.md b/docs/terms/credential-type.md new file mode 100644 index 0000000000000000000000000000000000000000..d9037e3397b1db7ef370612d768202eb1b3929b6 --- /dev/null +++ b/docs/terms/credential-type.md @@ -0,0 +1,15 @@ +--- +id: credential-type +title: "Credential Type" +scopeid: essifLab +type: concept +typeid: credential-type +stage: draft +hoverText: "Credential Type: a specification of the kinds of Assertions (claims, statements) that must, or may be, included in Credentials of that type." +--- + +### Short Description +A **credential-type** is a specification that states which kinds of %%assertions (claims, statements)|assertion%% can or may be found in any %%credential|credential%% of that kind. 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 +%%Parties|party%% advertise %%credential types|credential-type%% for credentials that they issue for the purpose of enabling other %%parties|party%% to determine whether or not they should be asking for such %%credentials|credential%% of this issuing %party. \ No newline at end of file diff --git a/docs/terms/credential.md b/docs/terms/credential.md index 1b533b7b3a65e2e98a88a4cc9d46e8a557439972..45d49fa45588059d77c6bc10d620de6cd603b94c 100644 --- a/docs/terms/credential.md +++ b/docs/terms/credential.md @@ -5,7 +5,7 @@ scopeid: essifLab type: concept typeid: credential stage: draft -hoverText: "Credential: data, representing a set of statements (claims, assertions), authored and signed by, or on behalf of, a specific Party." +hoverText: "Credential: data, representing a set of Assertions (claims, statements), authored and signed by, or on behalf of, a specific Party." --- ### Short Description diff --git a/docs/terms/dependent.md b/docs/terms/dependent.md new file mode 100644 index 0000000000000000000000000000000000000000..0717c181100eea57c852c476ea5024e602c19ce7 --- /dev/null +++ b/docs/terms/dependent.md @@ -0,0 +1,22 @@ +--- +id: dependent +title: "Dependent" +scopeid: essifLab +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." +--- + +:::info Editor's Note +TNO to revise all below texts. +::: + +### Short Description + +### Purpose + +### Criteria + +### Background +The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts. \ No newline at end of file diff --git a/docs/terms/guardian.md b/docs/terms/guardian.md new file mode 100644 index 0000000000000000000000000000000000000000..1f31731d60de499c5a7743ebe51a8a6fec4b2ff5 --- /dev/null +++ b/docs/terms/guardian.md @@ -0,0 +1,22 @@ +--- +id: guardian +title: "Guardian" +scopeid: essifLab +type: concept +typeid: guardian +stage: draft +hoverText: "Guardian (of an Entity in a Jurisdiction): the Party that is tasked to care for and/or protect/guard/defend that Entity, for the purpose of which a Guardianship relationship has been established within that Jurisdiction." +--- + +:::info Editor's Note +TNO to revise all below texts. +::: + +### Short Description + +### Purpose + +### Criteria + +### Background +The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts. \ No newline at end of file diff --git a/docs/terms/guardianship-type.md b/docs/terms/guardianship-type.md new file mode 100644 index 0000000000000000000000000000000000000000..74b2f0380490dea26d123245aa28b6d298761a62 --- /dev/null +++ b/docs/terms/guardianship-type.md @@ -0,0 +1,23 @@ +--- +id: guardianship-type +title: "Guardianship-type" +scopeid: essifLab +type: concept +typeid: guardianship-type +stage: draft +hoverText: "Guardianship-type (in a Jurisdiction): a class of Guardianships (relationships) within the Jurisdiction that has defined it." +--- + +### Short Description +A **Guardianship-type** is a class of %%guardianship relationships|guardianship%% within the %%jurisdiction|jurisdiction%% that has defined it. It comprises %%duty and right types|pattern-duties-and-rights%% that can be used as a template for instantiating %%duties and rights|pattern-duties-and-rights%% of %%guardianship relationships|guardianship%% that instantiate the %%guardianship-type|guardianship-type%%. + +A good way to think abouat a %%guardianship-type|guardianship-type%% is to see it as a template from which instances - i.e. actual %%guardianship relationships|guardianship%% can be derived. + +### Purpose +A **Guardianship-type** serves as a template from which instances - i.e. actual %%guardianship relationships|guardianship%% can be derived. It allows the %%jurisdiction|jurisdiction%% within which it is defined to specify generic %%duties and rights|pattern-duties-and-rights%%, both for the %%guardian|guardian%% and the %%dependent|dependent%% in (instantiated) %%guardianship relationships|guardianship%%, without knowing which %%entities|entity%% will be(come) the %%guardian|guardian%% or the %%dependent|dependent%%. + +### Criteria +An **guardianship-type** is a class of %%guardianship-relationships|guardianship%% that comprises a (non-empty) set of %%duty/right types|pattern-duties-and-rights%% for at least the %%guardian|guardian%% and/or the %%dependent|dependent%% (and perhaps other roles), the semantics of which are defined by the %%jurisdiction|jurisdiction%%. + +### Background +The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts. \ No newline at end of file diff --git a/docs/terms/guardianship.md b/docs/terms/guardianship.md new file mode 100644 index 0000000000000000000000000000000000000000..b295780cef37f3e2ae215e7b2d1fa12acc97e3c8 --- /dev/null +++ b/docs/terms/guardianship.md @@ -0,0 +1,36 @@ +--- +id: guardianship +title: "Guardianship" +scopeid: essifLab +type: concept +typeid: guardianship +stage: draft +hoverText: "Guardianship (of a one Party over an Entity in a Jurisdiction): the rights and duties of that Party, defined and enforced in that Jurisdiction, for the purpose of caring for and/or protecting/guarding/defending that Entity." +--- + +:::info Editor's Note +TNO to revise all below texts. +::: + +### Short Description +**Guardianship** is a relationship between a %%party|party%% (which we call the %%Guardian|guardian%%) and an %%entity|entity%% (which we call the %%Dependent|dependent%%) in which the %%guardian|guardian%% + +in which one of these %%entities|entity%% (called the %%owner|owner%%) is entitled to enjoy, dispose of, and control the other %%entity|entity%% in an pretty much absolute (sovereign) fashion. Any guardianship relationship is grounded in ((the rules of) the %%legal system|legal-system%% of) a specific %%jurisdiction|jurisdiction%%, that maintains and enforces these rules, and that has means to resolve any disputes arising from that. To do this, both %%entities|entity%% must be %%legal entities|legal-entity%% in that %%jurisdiction|jurisdiction%%. + +We may use the phrase %%natural guardianship%% to refer to an guardianship relation that exists in the %%jurisdiction|jurisdiction%% 'Nature' (see the notes of %%jurisdiction|jurisdiction%%). This enables us to talk about things as 'the (natural) guardianship of an %%assertion|assertion%%'. + +### Purpose +**Guardianship** is a means by which %%jurisdictions|jurisdiction%% provide assurances to %%parties|party%% (within its scope) that they can enjoy, dispose of and control in pretty much any way they like. The %%legal system|legal-system%% of the %%jurisdiction|jurisdiction%% specifies these rights, and provides ways in which the %%owner|owner%% can exercize them (that provides the assurance). + +### Criteria +An **guardianship** is a relationship between two %%legal entities|legal-entity%% (called the %%owner|owner%% and the %%owned|owned%%) within a single %%jurisdiction|jurisdiction%%, whose %%legal system|legal-system%% defines and enforces (a) rules that recognize the power of the %%owner|owner%% to enjoy, dispose of and control the %%owned|owned%% in an absolute (sovereign) fashion, and (b) rules that limit the absoluteness of that power. + +### Related Concepts +- %%Owner|owner%% +- %%Owned|owned%% + +### Notes +- Owning something does not imply posessing it (and vice versa). For example, if you find a coin that doesn't belong to you, you possess it but do not own it. Also, its rightful owner obviously owns it, but doesn't possess it at that point in time. + +### Background +The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts. \ No newline at end of file diff --git a/docs/terms/pattern-duties-and-rights.md b/docs/terms/pattern-duties-and-rights.md new file mode 100644 index 0000000000000000000000000000000000000000..cb1c219e4475b0498f0dbac585b8b3fcc16acc3f --- /dev/null +++ b/docs/terms/pattern-duties-and-rights.md @@ -0,0 +1,15 @@ +--- +id: pattern-duties-and-rights +title: "Duties and Rights" +scopeid: essifLab +type: concept +typeid: pattern-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." +--- + +:::info Editor's Note +TNO to provide content here +::: + +## \ No newline at end of file diff --git a/docs/terms/pattern-guardianship.md b/docs/terms/pattern-guardianship.md new file mode 100644 index 0000000000000000000000000000000000000000..65a0cff49472dab18e16732c3106b732b1291072 --- /dev/null +++ b/docs/terms/pattern-guardianship.md @@ -0,0 +1,130 @@ +--- +id: pattern-guardianship +title: "Guardianship (Relationships)" +scopeid: essifLab +type: pattern +typeid: guardianship +stage: draft +hoverText: "The Guardianships pattern captures the Concepts and relations that explain what a generic Guardianshipconsists of, and how it relates to Guardians, Dependents, Jurisdictions, etc." +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +:::info Editor's Note +TNO to revise all below texts. +::: + +### Purpose +The **Guardianship pattern** captures the concepts and relations that explain how generic %%guardianship relationships|guardianship%% work, and can be constructed. It shows that %%guardianships|guardianship%% are embedded in a %%jurisdiction|jurisdiction%% that govern such relationships. + +The contribution of this pattern is to establish a building block and terminology for constructing a consistent, coherent and sufficiently complete mental model that allows %%parties|party%% to convey %%guardianship|guardianship%%-related ideas to other %%parties|party%%, without running the risk of being misunderstood, by expressing any %%guardianship|guardianship%%-related use-case in terms of the model. This will enable us to draft requirements and specifications for infrastructural IT, and make a start with specifying standardizable data structures (schemas) for use in combination with VCs. + +### Introduction +The term ‘%%guardianship|guardianship%%’ has many definitions/descriptions. Examples are +- “The position of protecting or defending something” or “The position of being legally responsible for the care of someone who is unable to manage their own affairs.” (both from the [Oxford dictionary](https://www.lexico.com/en/definition/%%guardianship|guardianship%%)), +- “One who has the care of the person or property of another” or “One that guards” (both from [Merriam-Webster](https://www.merriam-webster.com/dictionary/%%guardianship|guardianship%%)), +- “The state or duty of being a guardian”, where ‘guardian’ is defined as “A person who has the legal right and responsibility of taking care of someone who cannot take care of himself or herself” or “Someone who protects something” ([Cambridge Dictionary](https://dictionary.cambridge.org/dictionary/english/)), or +- “The status of being a protector, advocate, or proxy for a person” ([Sovrin %%Guardianship|guardianship%% Task Force whitepaper](https://sovrin.org/wp-content/uploads/%%Guardianship|guardianship%%-Whitepaper.pdf)), which defines ‘guardian’ as “An organization or person protecting another person and possibly their property”. +- “The legal, social, or organizational responsibility of serving as a Guardian” ([Sovrin Glossary](https://docs.google.com/document/d/1gfIz5TT0cNp2kxGMLFXr19x1uoZsruUe_0glHst2fZ8/edit)), which also defines ‘guardian’ as “An Id%%entity|entity%% Owner who administers Id%%entity|entity%% Data, Wallets, and/or Agents on behalf of a %%Dependent|dependent%%”. + +So, it seems that most people will acknowledge that '%%guardianship|guardianship%%' is a relation between + +- someone (or an organization, collectively referred to as a '%%party|party%%') or something that is 'under %%guardianship|guardianship%%', i.e. being cared for, guarded, protected or defended - we call this the '%%dependent|dependent%%', and +- a %%party|party%% that does this caring, guarding, protecting or defending - we call this the '%%guardian|guardian%%'. + +Note that '%%dependent|dependent%%' and '%%guardian|guardian%%' are roles in a %%guardianship relationship|guardianship%%; they do not have an independent existence (as e.g. a human being does). A '%%dependent|dependent%%' (or '%%guardian|guardian%%') only exists if someone fulfills this role in a %%guardianship relationship|guardianship%%, which in turn can only exist if both the '%%guardian|guardian%%' and '%%dependent|dependent%%' roles are being assigned. + +_Example: in the [Mya](https://drive.google.com/file/d/10sfYKp6Ohi_rLsNqb1GBrhuE0IuoBX2k/view) use-case, a %%guardianship relationship|guardianship%% exists between Mya (as the %%dependent|dependent%%) and her grandmother Zo (as %%guardian|guardian%%). There is also a %%guardianship relationship|guardianship%% between Mya (%%dependent|dependent%%) and UNICEF (camp staff - as %%guardian|guardian%%)._ + + + +The actual activities that a %%guardian|guardian%% performs as (s)he cares for, guards, or … its %%dependent|dependent%% (in a specific %%guardianship relationship|guardianship%%) differ from case to case, and from situation to situation. Still, in general we can say that a %%guardianship relationship|guardianship%% comes with rights and duties that enable (or force) a %%guardian|guardian%% to execute specific actions - for the purpose of caring/guarding/… its %%dependent|dependent%%. + +_Example: in the Mya use-case, the camp staff and Zo have the right to a daily food ration from the camp shop. Zo has the right to accompany Mya outside the camp. Etcetera._ + +A %%guardianship relationship|guardianship%% is meaningful to the extent in which such rights and duties are actually upheld and/or enforced. + +_Example: if in the Mya use-case %%guardianship|guardianship%% is not properly enforced, human traffickers may pose as Mya's %%guardian|guardian%% to get her out of the camp so that she can be sold as a slave._ + +Defining and enforcing rights and duties, as well as resolving conflicts that may arise, are the very essence of a %%jurisdiction|jurisdiction%% - for details see the %%Jurisdictions pattern|pattern-jurisdiction%% + +The wealth in varieties in %%guardianship relationships|guardianship%% can now easily be explained by observing that the various %%Jurisdictions|jurisdiction%% all exercise their self-sovereignty as they operate their %%legal systems|legal-system%%. + +Example: in the Mya use-case, UNICEF sets the rules, enforces them and resolves related conflicts within its refugee camps, in its own, self-sovereign ways. This qualifies UNICEF as a %%jurisdiction|jurisdiction%%. + +For a %%guardianship relationship|guardianship%% to be meaningful and relevant, it must be associated to a (single) %%jurisdiction|jurisdiction%% that creates, modifies and dissolves the relation, specifies who the %%guardian|guardian%% and %%dependent|dependent%% are, and assigns each of them a set of rights and duties (including 'negative' rights and duties, i.e. what they may/must NOT do). A %%jurisdiction|jurisdiction%% is implicitly tasked to enforce such rights and duties, and provide for the resolution of conflicts, yet is (and remains) self-sovereign in determining the extent in which it does so. + +_Example: in the Mya use-case, UNICEF camp staff Sofia (is mandated to) determine whether or not a %%guardianship relationship|guardianship%% may be established between Mya and Zo, according to the rules that UNICEF has established for the camp. This kind of %%guardianship relationship|guardianship%% comes with some default rights and duties for Mya and Zo. For example, the %%guardian|guardian%% gets the right to daily obtain one additional food ration from the camp store for the %%dependent|dependent%%. Also, the %%guardian|guardian%% is allowed to take the %%dependent|dependent%% for a walk outside the camp. Depending on the rules UNICEF has put in place, Sofia might not issue all default rights/duties, or issue additional ones. If Zo dies, or Mya and Zo leave the camp, this %%guardianship relationship|guardianship%% becomes ineffective. In the meantime though, the rights/duties associated with the %%guardianship relationship|guardianship%% may change, to be determined by (qualified) UNICEF (personel)._ + +### Formalized model +Here is a visual representation of this pattern, using the following [notations and conventions](../notations-and-conventions#pattern-diagram-notations): + +Conceptual model of the 'Guardianship' pattern + +In the figure, concepts are placed in one of three areas: +- **Goverenance** is about the %%governance|governance%% of %%guardianships|guardianship%%. It shows that %%guardianship-types|guardianship-type%% are defined by a %%jurisdiction|jurisdiction%%, and that instances of %%guardianship types|guardianship-type%%, i.e. %%guardianship relationships|guardianship%%, are governed by the %%jurisdiction|jurisdiction%%, and that both the %%guardian|guardian%% and %%dependent|dependent%% are %%legal entities|legal-entity%% within that %%jurisdiction|jurisdiction%%. For the Mya use-case, let's call the %%jurisdiction|jurisdiction%% `UNICEF refugee camp`. +- **Define-time** is about the design of guardianships, or guardianship templates if you will. In the Mya use-case, `UNICEF refugee camp` (perhaps itself abiding by more general UNICEF rules) would have defined a guardianship type (template) for cases where both the guardian and dependendent are refugees. For the use-case, let's call it `Refugee-Refugee-guardianship`. Then `UNICEF refugee camp` defines it to have duty/right types, e.g. "`guardian` has the right to obtain 1 food ration per day on behalf of `dependent`". +- **Run-time** is about the actual guardianship relationships, the actual duties and rights, and the actual entities involved in such relationships. In the Mya use-case, a guardianship relationship would exist that + - is governed by `UNICEF refugee camp`; + - instantiates guardianship type `Refugee-Refugee-guardianship`; + - comprises the duty/right "`Zo` has the right to obtain 1 food ration per day on behalf of `Mya`"; + - specifies `Zo` as the guardian in the relationship; + - specifies `Mya` as the dependent in the relationship; + (note that Zo and Mya can only become guardian/dependent after having been registered within `UNICEF refugee camp`, or else they would not have been legal entities.) + + +An instance of such duty/right types are the actual duties and rights, e.g. + + +### Building Block: %%Guardianship Relationship|guardianship%% Pattern + +:::info Editor's note +TNO to revise this section +::: + +The figure shows that all (operational, or 'runtime') %%Guardianship Relationship|guardianship%% live within the context of a specific %%Jurisdiction|jurisdiction%%. A %%Guardianship Relationship|guardianship%% links two %%Legal Entities|legal-entity%% (LE's) within that %%Jurisdiction|jurisdiction%%, one which we will call the '%%guardian|guardian%%', the other the '%%Dependent|dependent%%'. The %%Guardianship Relationship|guardianship%% specifies rights and duties to each of them. + +Note that such rights and duties may refer to LE's other than the %%guardian|guardian%% or %%Dependent|dependent%%, e.g. a third party against whom a right or duty may or must be exercised. We emphasize that such references must identify these %%entities|entity%% within the scope of the Knowledge of the %%party|party%% of the %%Jurisdiction|jurisdiction%%, because however obvious this may seem, in practice people often do not realize that this must be the case for the %%Legal System|legal-system%% of the %%Jurisdiction|jurisdiction%% to work. + +The %%Legal System|legal-system%% of a %%Jurisdiction|jurisdiction%% may define (named) types of %%Guardianship Relationships|guardianship%%, e.g. 'Parenthood' or 'Curatorship', before any actual %%Guardianship Relationship|guardianship%% exists. Legal %%Jurisdictions|jurisdiction%% do that in their laws, while other %%Jurisdictions|jurisdiction%% may have other, perhaps more informal ways of defining them. A %%Guardianship Relationship|guardianship%% type definition will specify a set of generic rights and duties (which we call Duty/Right Types) for the %%entities|entity%% that will be assigned the roles of %%guardian|guardian%%, %%dependent|dependent%%, and perhaps others. + +It is typical of a Duty/Right Type to NOT refer to individual %%entities|entity%%, but rather use placeholders that are to be filled in when a Duty/Right is created that is an instance of the Duty/Right Type. + +So typically, a %%Jurisdiction|jurisdiction%% will define the set of %%Guardianship|guardianship%% Types that its %%Legal System|legal-system%% supports. For each of them, the %%Jurisdiction|jurisdiction%%: + +- specifies the rules/laws that govern the creation and management of their instances, +- ptionally specifying processes (and possibly providing some or all means) to monitor/police compliance, and +- providing a mechanism for resolving disputes related to them. + +Typically, the Task of creating a %%Guardianship Relationship|guardianship%% (GR) consists of: + +- associating the GR with LE's for the positions of '%%guardian|guardian%%' and '%%dependent|dependent%%'; +- associating the GR with an initial/default set of Hohfeldian Duties/Rights, the types of which are specified by the %%Guardianship|guardianship%% Type that the GR instantiates. +- assigning values for the placeholders that occur in the specifications of such Duties/Rights + +The Task of managing a GR consists of adding, (un)suspending, revoking/removing instances of Duty/Right types that are meaningful in the %%Jurisdiction|jurisdiction%% as appropriate, and assigning values for any placeholders therein. Also, (un)suspending and/or revoking/invalidating the GR itself is part of that Task. + +Note that an artefact that contains the specification of a GR may need to take various forms. For every kind of Actor that is envisaged to read and process such a specification, it must be represented in a language (syntax and semantics) that such an Actor knows how to read and process. This could mean that the artefact is only, or both human readable (in one or more languages) or machine readable (in one or more schemas). + +### Notes + +Having defined a mental model for %%guardianship|guardianship%%, and having applied it to the Mya use-case, we can make some generic observations. + +1. %%guardianships|guardianship%% are typed in the same way that roles can be typed. The rights and duties that are associated with Roles that are assigned to e.g. a %%party|party%% (e.g. a department) will be quite different from those that are associated with Roles that are assigned to employees, or customers. We see this also happening with %%guardianships|guardianship%%: the rights and duties that are associated with a %%guardianship relationship|guardianship%% where the %%guardian|guardian%% is the %%party|party%% that operates the %%legal system|legal-system%% of a %%Jurisdiction|jurisdiction%% and the %%dependent|dependent%% is a refugee is quite different from a %%guardianship relationship|guardianship%% where the %%guardian|guardian%% and %%dependent|dependent%% are both refugees. One such difference is that in the first case, certain rights and duties can be delegated whereas in the latter case that is prohibited. +2. the meaning of %%guardianship relationships|guardianship%% is defined by a %%Jurisdiction|jurisdiction%% in the same way as the meaning of roles are defined by a %%Jurisdiction|jurisdiction%%. This meaning is given by the set of rights and duties that are assigned to the role/%%guardianship|guardianship%%, which in turn depend on the %%objectives|objective%% that the %%Jurisdiction|jurisdiction%% aims to contribute to by assigning them, and the Transaction Types and Transaction Type Roles it specifies in relation to this. +3. perhaps %%guardianship|guardianship%% is not all that special: at a functional level, they work quite the same as roles do, the difference only lying in the fact that roles are an assignment of rights, duties etc. to a (semantically properly defined) single %%legal entity|legal-entity%% (e.g. a Refugee, an Employee, etc.), whereas a %%guardianship|guardianship%% is an assignment of rights, duties etc. to a (semantically properly defined) ordered pair of %%Legal Entities|legal-entity%% (the first of which is called '%%guardian|guardian%%' and the other is called '%%dependent|dependent%%'). +4. in a way, %%ownership|ownership%% may be considered a specialization of %%guardianship|guardianship%%. This is supported by the various definitions we find in different dictionaries - which all have a striking resemblance with definitions of '%%guardianship|guardianship%%'. Also, it is supported by the fact that: + +- a %%party|party%% that owns something (an %%entity|entity%%) is entitled to do transactions (with that %%entity|entity%%) that other Parties are not entitled to, e.g. selling it. +- a %%party|party%% that owns an %%entity|entity%% typically protects or defends such %%entities|entity%% (their property); the %%party|party%% may also take care of it. +- like %%guardianships|guardianship%%, duties, rights, privileges etc. are being assigned to %%ownership|ownership%% by a %%Jurisdiction|jurisdiction%%. +- in the same way that a %%Jurisdiction|jurisdiction%% may have different kinds of %%guardianship|guardianship%%, they may have different kinds of %%ownership|ownership%% - a property that is well-known e.g. for corporations - and each kind of %%ownership|ownership%% may serve its own purposes. + +One might argue that because of these similarities, '%%ownership|ownership%%' and '%%guardianship|guardianship%%' are the same. However, there is a difference, which is can be found in the kind of %%objectives|objective%% that (the %%party|party%% that governs) the %%jurisdiction|jurisdiction%%) pursues: +- %%ownership|ownership%% is about recognizing one's right to enjoy and (given some limitations) absolutely control something; +- %%guardianship|guardianship%% is more about a duty to care, defend and protect someone or something. + +Since the %%Jurisdiction|jurisdiction%% model claims that %%Jurisdictions|jurisdiction%% own %%Objectives|objective%%, %%Guardianship|guardianship%% Types, and other things, this means that there is recursion, implying that %%Jurisdictions|jurisdiction%% are guardians of these things they own. Indeed, %%Jurisdictions|jurisdiction%% do have (implicit or explicit) rules that govern their %%Objectives|objective%%, %%Guardianship|guardianship%% Types, and whatever else they may have (by the very definition of %%Jurisdiction|jurisdiction%%). diff --git a/docs/terms/pattern-jurisdiction.md b/docs/terms/pattern-jurisdiction.md index c5504d0aa8e4cd30d5b02be184f42ef2038a8ffd..03ea7cb5dc230768ccb0d2eb16b384d53d3735d0 100644 --- a/docs/terms/pattern-jurisdiction.md +++ b/docs/terms/pattern-jurisdiction.md @@ -8,6 +8,8 @@ stage: draft hoverText: "The Jurisdictions pattern captures the Concepts and relations that explain what a generic Jurisdiction consists of, and relates it to Parties and Legal Entities." --- +import useBaseUrl from '@docusaurus/useBaseUrl' + ### Purpose The **Jurisdiction pattern** captures the concepts and relations that explain how generic %%jurisdictions|jurisdiction%% work, and can be constructed. It shows that it can be seen as the composition of one %%scope|scope%%, one %%legal system|legal-system%% and one %%party|party%% that operates the legal system within that scope. diff --git a/docs/terms/pattern-party-actor-action.md b/docs/terms/pattern-party-actor-action.md index aa3c387435c8eb08781d45f275520f1c44c38123..69cb7594280601a5544aafb3f32b43144a68b3ee 100644 --- a/docs/terms/pattern-party-actor-action.md +++ b/docs/terms/pattern-party-actor-action.md @@ -8,6 +8,8 @@ stage: draft hoverText: "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?'." --- +import useBaseUrl from '@docusaurus/useBaseUrl' + ### Summary This 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?". It provides a way of looking at people (human beings), organizations, and how they interact with one another in a decentralized, self-sovereign way - which means that each of them decides for itself whether or not to interact with others, how to conduct such interactions, etc., thereby only taking external influences into account if they want, or have some need to do so. diff --git a/docs/terms/validation-policy.md b/docs/terms/validation-policy.md new file mode 100644 index 0000000000000000000000000000000000000000..0ed78a09acb4577f82c7c1f7b8961a18f95af623 --- /dev/null +++ b/docs/terms/validation-policy.md @@ -0,0 +1,18 @@ +--- +id: validation-policy +title: "Validation Policy" +scopeid: essifLab +type: concept +typeid: validation-policy +stage: draft +hoverText: "Validation Policy: a Digital Policy that contains the rules, working-instructions, preferences and other guidance for determining whether or not data is valid for a specific purpose/objective of its Governor." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +### Related Concepts +- %%Digital Policy|digital-policy%% +- %%Policy Governor|policy-governor%% +- %%Validation|validation%% diff --git a/docs/terms/validation.md b/docs/terms/validation.md new file mode 100644 index 0000000000000000000000000000000000000000..d259c748a02a7f814bf96e22b45d631cf52b63f0 --- /dev/null +++ b/docs/terms/validation.md @@ -0,0 +1,17 @@ +--- +id: validation +title: "Validation" +scopeid: essifLab +type: concept +typeid: validation +stage: draft +hoverText: "Validation (of data): the process that a Party uses to determine whether or not that data is valid to be used for some specific purpose(s) of that Party." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +Explain that validation is not verification: +- verification (of data) is the process of determining whether or not what the data represents is in fact true (veracity). +- validation (of data) is the process of determining whether or not data can be used to base a decision on. For example, a liquor selling party may determine that if someone simply says (s)he is 18+, that is valid data for deciding whether or not to sell the liquor, regardless of whether or not that statement is true. \ No newline at end of file diff --git a/docs/terms/verification.md b/docs/terms/verification.md new file mode 100644 index 0000000000000000000000000000000000000000..208c4be50d862bc2d99de84363bea482811f2a18 --- /dev/null +++ b/docs/terms/verification.md @@ -0,0 +1,17 @@ +--- +id: verification +title: "Verification" +scopeid: essifLab +type: concept +typeid: verification +stage: draft +hoverText: "Verification (of data): the process that a Party uses to determine whether or not what that data represents is in fact true (veracity)." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +Explain that verification is not validation: +- verification (of data) is the process of determining whether or not what the data represents is in fact true (veracity). +- validation (of data) is the process of determining whether or not data can be used to base a decision on. For example, a liquor selling party may determine that if someone simply says (s)he is 18+, that is valid data for deciding whether or not to sell the liquor, regardless of whether or not that statement is true. \ No newline at end of file diff --git a/plugins/terminology-parser/index.js b/plugins/terminology-parser/index.js index 541b40c3099c98fbf1f9f9e802e0af3191b5c485..0b7069ee3ca68e33a17405888ea765826533ed85 100644 --- a/plugins/terminology-parser/index.js +++ b/plugins/terminology-parser/index.js @@ -31,7 +31,7 @@ function getAutoIncludeStatements(filePath) { var absoluteTermPath = path.resolve('./src/components'); // Find the relative path between the file to be modified and the Term plugin var relativePath = path.relative(filePath, absoluteTermPath); - var importTerms = `\n\nimport useBaseUrl from '@docusaurus/useBaseUrl'\nimport { Term } from '${relativePath}'\n`; + var importTerms = `\n\nimport { Term } from '${relativePath}'\n`; return importTerms } diff --git a/static/images/patterns/pattern-guardianship-relation.png b/static/images/patterns/pattern-guardianship-relation.png deleted file mode 100644 index 48d026c087b069c1c0c6ca08ddf76dd30448932d..0000000000000000000000000000000000000000 Binary files a/static/images/patterns/pattern-guardianship-relation.png and /dev/null differ diff --git a/static/images/patterns/pattern-guardianship-relationship.png b/static/images/patterns/pattern-guardianship-relationship.png new file mode 100644 index 0000000000000000000000000000000000000000..d97f622f7471b5cf86e46a61840fc6dd7da0b6df Binary files /dev/null and b/static/images/patterns/pattern-guardianship-relationship.png differ