diff --git a/.gitignore b/.gitignore index 59acb63667469d25cbec77999c6b61e89039035e..a5da0c1e28503b7f1b96bd362a895a7b54d975d4 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,6 @@ yarn-error.log* start_server.bat *.ffs_batch *.lnk +docs/vscode-%%-batch-replacer.txt +**/zzz-* +docs/test.md diff --git a/README.md b/README.md index 622d646f1c82edc918947f5aefeef3240e470bb5..cd7a4c73129402e77958c0b0403fa14ba6b3c2a1 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Documentation on these and other header fields can be found [here](https://v2.do The Terminology Engine plugin of GRNET uses additional header fields. These are (or will be) defined [here](./docs/terminology-contributions). -The `sidebars.js` file contains the basic mechanism for [distributing content among sections](https://v2.docusaurus.io/docs/docs-introduction#sidebar) and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/introduction)). Subsections within the `.md` file (that is, tagged with `##`) will appear at the right part of the page (see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)). +The `sidebars.js` file contains the basic mechanism for [distributing content among sections](https://v2.docusaurus.io/docs/docs-introduction#sidebar) and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/project)). Subsections within the `.md` file (that is, tagged with `##`) will appear at the right part of the page (see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)). ## Inserting Images in docs - -### 2.1. Business Transaction Layers - -At the top of the figure are two business-related layers. Both are within the scope of the eSSIF-Lab project/architecture, yet they are outside the scope of the eSSIF-Lab infrastructure/architecture - that is because they are too business-specific. - -The top layer (in the red rounded rectangle) has the functions of actual business transactions: it starts with a transaction form, the data of which is valid, consistent and complete, from which the (business) decision can be made whether or not to engage in a business transaction, and that has everything necessary to actually execute that business transaction. The (administrative) results of such a business transaction are then stored in business data stores. We have put this layer in the eSSIF-Lab architecture for the single purpose of showing how the components of the bottom layer contribute to conduct business transactions. - -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 %%Transaction (Validation) Engine|transaction-validation-engine%% (or %%TVE|tve%%) 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 TVE must ensure that the transaction context is properly maintained if it chooses to exchange data through different communication channels. - -The task of the %%Transaction Result Dispatcher|transaction-result-dispatcher%% (or %%TRD|trd%%) 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. - -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. - -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. - -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 TRD) 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 **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 **verifier** functionality is to support the TVE 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 TVE 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. - -### 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. - -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. - -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 communications 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. - -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) - ------- - -[ABC] Its origins lie with the [*ABC4Trust project*](https://abc4trust.eu/). Extensive [*documentation*](https://abc4trust.eu/index.php/pub) is available, e.g. an [*Architecture for Attribute-based Credential Technologies*](https://abc4trust.eu/download/Deliverable_D2.2.pdf) (also one [*for developers*](https://abc4trust.eu/download/ABC4Trust-H2.2_ABC4Trust_Architecture_for_Developers.pdf)). - -[eIDAS5] [*"Regulation (EU) No 910/2014 of the European Parliament and of the Council of 23 July 2014 on electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/EC"*](http://eur-lex.europa.eu/legal-content/EN/TXT/?uri=uriserv:OJ.L_.2014.257.01.0073.01.ENG). *EUR-Lex*. The European Parliament and the Council of the European Union. - ------- - -### 2.4. API Layers (‘ESSIF Glue’ and ‘SSI Tech APIs’) - -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 TVE and TRD 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 Transaction Result Dispatcher and Transaction (Validation) Engine. 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 **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. - -------- - -## 3. eSSIF-Lab Infrastructure Functional Components - -This section details the functional specifications of the components that are in scope of the eSSIF-Lab infrastructure, i.e. in the green (rounded) rectangle as shown in the figure below: - -![eSSIF-Lab functional components that are part of the eSSIF-Lab infrastructure](https://essif-lab.pages.grnet.gr/framework//images/functional-architecture-infra.png) - -*Figure 2: eSSIF-Lab infrastructural (functional) components.* - -### 3.1. Transaction (Validation) Engine and Validation Policy - -The purpose of the Transaction (Validation) Engine (TVE) is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an Agent of) its Owner to decide whether or not to engage in a (new) transaction of the specified type. - -Typically, the TVE would start a transaction either - -- when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind. -- when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.[TVE.1] - -In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Owner and/or using different communications channels. - -Handling/managing the various communications channels through which data can be exchanged is also a task of the TVE[TVE.2]. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens). - -Thus, the TVE is generally considered capable of obtaining data through different communications channels. However, the technical tracks of eSSIF-Lab will exclusively focus on the communications channel through which credentials can be requested and obtained. Any extensions or business productization of TVE designs may be considered in the business tracks of eSSIF-Lab. The latter is not considered any further in this section. - -In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the TVE needs to know what kinds of credentials it should ask for, which Parties its Owner trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.[TVE.3] Also, when the TVE gets a credential that satisfies the necessary verification proofs, it needs a way to map the contents of that credential to the structure of the transaction context that is used internally by (other systems of) its Owner.[TVE.4] Also, as the TVE gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.[TVE.5] - -In order to make the TVE work, a Validation Policy (or TVE Policy) is created by, or on behalf of the Owner, which specifies at least: - -- the kinds of transactions the Owner is willing to (electronically) engage in, from both the requester and the provider perspectives; -- for each such transaction type: - - - the criteria (business rules) that should be used to determine that the form is ‘clean’, i.e. that the necessary and sufficient data have been obtained and that they are consistent, coherent, and suitable for making a transaction commitment decision. - - - the kinds of credentials and issuers that the Owner is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing Parties do the actual credential issuing may be specified[TVE.6]. - - - for each kind of credential: the verification proofs that must hold to be accepted as a source for valid data. - - - the mapping between fields in such credentials and fields in the form to be filled in. - -The Policy must be designed in such a way that it is extendable as new features will be called for in the future. - -The ability to create new transaction contexts and the availability of the TVE Policy enable the TVE to request the Verifier component of its Owner to obtain credentials of the types that it can use to fill in the transaction form when they satisfy the verification and validation requirements of its Owner.[TVE.7] - -When the Verifier returns such data (which comes with a list of proofs that the Verifier has checked), the TVE must then validate that data, i.e. determine whether or not it is valid for the specific transaction it is assembling the data for. The validation rules are Party-specific and hence come from the TVE policy. For simple cases, validation can simply consist of checking whether or not all verification proofs succeeded. At the other end of the validation spectrum, the TVE itself must make validation decisions, either electronically (according to the TVE policy) or by ‘outsourcing’ such decisions to human Agents of its Owner by providing an appropriate validation user interface. - -As long as data is needed, the TVE can intermittently request the verifier to produce it (or it can use other communications channels, which is outside scope for now). It does so until it times out, or the form has become ‘clean’. - ------ - -[TVE.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). - -[TVE.2] It may well be that this functionality can somehow be split off in the (near) future. - -[TVE.3] For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Owner of the TVE. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years. - -[TVE.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. - -[TVE.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. - -[TVE.6] This enables the TVE to pass the endpoint URI on to the Verifier when it requests for such a credential, which in turn can send it to the holder of other Parties enabling them to obtain the credential from that issuer endpoint if that other Party does not have that credential in its wallet. The endpoint URI can in fact be put in the policy, because the (human) Agent that creates/maintains the policy would need to know that the issuing Party is actually issuing such credentials, what their contents means, etc., and hence is capable of tracking down the URI where that Party issues the credentials. - -[TVE.7] A reference to this specification will be added when it becomes available (draft or otherwise). - ------ - -### 3.2. Verifier Component, and its Policy/Preferences - -The purpose of the Verifier component is to support the Transaction (Validation) Engine 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 TVE 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 TVE 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 TVE 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 TVE specifies this as part of the request - and it can do so because it has received the original request, and does all communications 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. - -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 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\] - -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). - -Then, the verifier will send a message to the TVE, 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. - -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. - -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 TVE 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 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. - -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.: - -- 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. - -### 3.4. Transaction Result Dispatcher and Issuing Policy - -The purpose of the TRD component is to state the (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other Parties. A special kind of result is the (provisioning of) a credential that its Owner already has created. - -Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term ‘**subject (of a statement of a Party)**’ to refer to the entity that this Party knows to exist, and about whom/which the statement has been made. - -We will use the term ‘**subject-id (of a statement of a Party)**’ to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not). - -Parties need to specify the kinds of credentials they are willing to issue, the class of entities (e.g. people, cars, Organizations) for which it will issue them, and the information schema (structure) that it will use in credentials of such kinds.[TRD.1] This allows the TRD to construct data objects that conform to this information schema, and present it to the Issuer component for actual issuing. - -The TRD Issuing Policy specifies the kinds of (linked-)data-objects that credentials may be created for. This allows the TRD to construct such a (linked-)data-objects for every subject-id that identifies a subject of the class for which a credential can be issued, which can subsequently be sent to the Issuer component that can turn it into a credential of a specific sort. - -You can think of the TRD as the component that pulls all data together that can be put in a credential (e.g. in a passport), and the Issuer as the component that puts the data in an (empty) passport, and signing it so as to create the actual credential. - -The TRD may either push credential data to the Issuer component, so that the Issuer always has up-to-date credentials, or it can wait until the Issuer requests credential data for the creation of a credential of a specific type for a specific subject. - ------ - -[TRD.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. - ------ - - - -### 3.5. Issuer Component, and its Policy/Preferences - -The purpose of the Issuer component is to issue ‘credentials’, i.e. digital constructs that contain - -- sets of (related) statements or claims (e.g. as produced by the TRD) -- 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. - -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. - -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). - -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] - ------ - -[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. - ------ - - -### 3.6. Wallet Component, and its Policy/Preferences - -The primary purpose of the 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. - -Other kinds of data may be stored by a 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 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). - -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. - -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. - -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. - -## 4. Initial SSI-Agent Network Architecture - -:::info -*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. - -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. - -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. - -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: - -- 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? -- … - -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: - -- 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? -- … - -## 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. - -### 5.1. Overview - -
- -![eSSIF-Lab - high level trx overview](https://essif-lab.pages.grnet.gr/framework//images/high-level-trx-overview.png) - -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. - -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. - -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. - -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. - -### 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. - -![eSSIF-Lab - high level trx negotiation](https://essif-lab.pages.grnet.gr/framework//images/high-level-trx-negotiation.png) -The adjacent figure shows the high-level interactions during this phase. It starts by the requester sending a request for a product or service to the provider. Typically, this would lead to the provider presenting a (web) form the requester must fill in. In the eSSIF-Lab context, the form will also provide a means for setting up a SSI communications channel, i.e. a secure communications channel through which provider and requester can both request and obtain (presentations of) credentials, the contents of which they can use to fill in the form. Then, after the form is ‘clean’, i.e. contains sufficient information for deciding whether or not to commit to the transaction, this phase ends. - -Note that forms may contain fields that are required only in specific circumstances. It may only be possible to assess whether or not such circumstances apply after some (other) fields have been filled in. This means that the phase for requesting credential presentations and responding to such requests may very well consist of multiple requests and associated responses. - -In the example of the parking permit, the municipality might ask for a credential that proves the requester is a citizen that is a registered inhabitant of said municipality, a credential stating its residential address, a credential stating the make and license plate of the vehicle for which a parking permit is requested, etc. All this is subject to the policy that the municipality has established for issuing such permits, and hence, it must be expected to differ between municipalities. - -An example of conditionally required fields would be when the requester wants the municipality to customize the parking lot, e.g. because the requester has disabilities. Assessing such circumstances depends on the (optional) field where the requester must state any disabilities they have, and when that is the case, the requester may be asked to fill in fields such as whether or not a parking lot has to be customized (painted blue, with a sign stating that it is reserved for the provided license-place, or the kind of charging device if they have an electric vehicle). - -Conversely, the citizen might request the (alleged) municipality to provide credentials, e.g. to prove that it is actually an official municipality of the country it is part of. This would provide assurance to the citizen that it would actually be paying the fees to that municipality rather than to e.g. a rogue Organization that might have spoofed the website of the municipality. - -### 5.3. Stating Transactions - Issuing Credentials - -In the eSSIF-Lab context, we take ‘credential’ to mean any (set of coherent) statement(s) about any (one or more) subject(s) that a single Party has issued with proof of provenance (i.e. anyone else can determine the identity of that issuer) and a proof of integrity (i.e. anyone can determine whether or not the content of the credential has been changed/tampered with since it was issued). From this, it follows that any Party can issue any kind of credential for any entity that it knows to exist. A credential does not need to be about a person or an Organization, but it can also refer to an order, a delivery, a seat-reservation, a prescription, etc. - -We foresee two ways in which credentials can be issued: - -1. both the requester and provider may issue credentials to the other Party in the process flow that they are in. They can do so for the purpose of stating any (lack of) progress and/or results of the administrative process flow they are in. - In the example of the parking permit, the municipality may need some time to do some manual checks before it can issue the permit; in this case, it could issue a credential that states that the citizen has requested the parking permit and any other details that might be appropriate. Also, if it can issue the parking permit straight away, it can issue a credential that contains the details of that permit. The requester may issue a credential to the municipality stating the date/time and kind of transaction, judgements or comments about the service that the municipality has provided. -2. any Party may issue a credential upon request. Basically, this means that a Party (in the role of requester) issues a request to that other Party (in the role of provider) asking for the particular credential. This is just another case of doing transactions, that can be handled just as any other kind of transaction. - In the example of the parking permit, when a citizen requests a permit, the provider might look for an existing permit prior to issuing a new one (it would have to do such a check during the process anyway), and depending on its business logic it would be providing the credential without further ado, or start the process of issuing a new one. - -## 6. Detailed Transaction Flows - -:::info -*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.* -::: - -This chapter explains the details of how electronic business transactions are being conducted using the eSSIF-Lab architectural components as described in chapter 2. We keep on using the parking permit example that we introduced in section 1.1. for illustrative purposes. - -Note that both Parties, requester and provider, each have components as described in chapter 2. Also note that whenever we introduce another Party, it too has such components. Thus, every Party can play any of the traditional SSI roles ‘verifier’, ‘holder’ and ‘issuer’, and each has its own ‘wallet’ functionality. Also, they all have TVE and TRD functionality that connect these aforementioned infrastructural components with the business applications. - -When reading the next sections, please be aware that when a component of one of these Parties communicates with another component, this other component may be of the same Party, as well as of the other Party. Figure 2 only shows components that belong to a single Party. - -### 6.1. Starting a Transaction - -:::info -*The eSSIF-Lab functional architecture is not final. This section 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.* -::: - -The requester starts the transaction by pointing his web-browser to a web-page of the provider that (a) explains how to get a parking permit, and (b) provides a parking-permit application form that needs to be filled in. Technically, this means that the browser does a GET request to an endpoint that is serviced by the providers TVE component. - -The TVE services this request by creating an empty form of a type appropriate for the request. Then, it continues with requesting data to fill in the form (and providing data as requested by the other Party). It starts this by providing a web page that includes the form to be filled in, as well as a deep-link, QR-code or something similar that allows the requester’s browser (plug-in) or SSI-app to contact the provider-endpoint and set up a secure communications channel through which both can communicate electronically. From then on there are two channels between the requester and the provider: one is a traditional (manual) web-browser - web-server channel, the other is one within which the SSI-Agents of various Parties will be communicating. - -It is a task of the TVE to orchestrate the inputs: different parts of the form may be filled in and subsequently changed in different ways. Some parts - -- are required only after a certain condition is met (which is to be evaluated whenever the data that is entered into the form is changed) -- must or may initially be filled in manually (i.e.: through the browser); -- must or may initially be filled in with data from a credential; -- may be changed manually; -- may be changed with data from a newly supplied credential. - -Because of this orchestration, the interface to the verifier component can be quite simple; it is shown in the image below: - -![Generic Verification with SSI service](https://essif-lab.pages.grnet.gr/framework//images/generic-verification-with-ssi-service.png) - -The request identifier is included in messages between the TVE and verifier so as to allow them to handle different transactions at the same time. - -We assume that the provider has specified the form and the associated validation- and issuing policies that make the following description work. We refer the reader to section \[tbd\] for an explanation of how the provider can do this. - -### 6.2. Stating a Transaction - -:::info -*The eSSIF-Lab functional architecture is not final. This section 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.* -::: - -![Generic Issuing with SSI service](https://essif-lab.pages.grnet.gr/framework//images/generic-issuing-with-ssi-service.png) diff --git a/docs/essif-lab-vision-and-purpose.md b/docs/essif-lab-vision-and-purpose.md deleted file mode 100644 index c7cbb6db3caf79f0110cfc530dbba7ed71a2c5d0..0000000000000000000000000000000000000000 --- a/docs/essif-lab-vision-and-purpose.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -id: vision-and-purpose -title: eSSIF-Lab Vision and Purpose -sidebar_label: Vision and Purpose ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -The eSSIF-Lab vision is that Self-sovereign Identity (SSI) will *empower European and other citizens* by providing new means to manage privacy by eliminating logins and making electronic transactions fast and safe both in the Internet and in physical life. SSI will *empower European organisations and governments* by providing new means to speed up, secure and automate transactions with citizens, customers, suppliers and partners, resulting in tens of billions of euros savings annually on administrative costs in Europe. SSI will be *a new business ecosystem paradigm* with thousands of new jobs, many new job categories and new business opportunities for existing and new European companies. And last, but certainly not least, SSI fosters *inclusiveness* and supports organizations and citizens to exercise their rights and fulfil their duties under the GDPR. - -The current situation is that SSI solutions that are being created and brought to the market either target specific applications for which they provide a vertical solution (‘stovepipes’), many need some kind of centralized governance/control, others have privacy issues, and none that we know of are interoperable with other such solutions. - -The situation we would like to see is one in which we have SSI-enabled, interoperable, scalable and business/information agnostic technologies, that form an infrastructure that every application for every party can use to serve its own objectives. This infrastructure, that enables the electronic exchange of verified (personal and non-personal) data, must be so easy to access and use for such parties that they will no longer need to be concerned about actual (SSI) technologies that have empowered them to make this happen. Rather, they will only need to think about, and decide which kinds of information they want to obtain for conducting specific business transactions and which parties they trust for providing such information. Also, they will need to think about, and decide which kinds of information they themselves are willing to provide to others in this new SSI world. - -:::tip **The purpose of the eSSIF-Lab...** -... is to specify, develop and validate technological and non-technological means that support people, businesses and governments to think about, design and operate their (information) processes and (electronically) conduct business transactions with one another. -::: - -The context of the eSSIF-Lab vision can be found in articles 8-10 of the [*European Convention on Human Rights (ECHR)*](https://www.echr.coe.int/Pages/home.aspx?p=basictexts/convention), that state the rights of individuals regarding their privacy, and their freedoms to collect, process, store, and express information in a self-sovereign fashion, i.e. in a way that they can decide for themselves. This is without prejudice to Member States’ laws that exist to protect their national security, public safety, the economic well-being of the country, health or morals or the rights and freedoms of others, or to prevent disorder or crime. The eSSIF-Lab vision extends these rights and freedoms - within the limits of the law - to public and private organizations. Thus, we say that individuals as well as public and private organizations (that we collectively refer to as ‘parties’) are self-sovereign[^1]. - -In the context of these rights and freedoms, we seek to support %%electronic business transactions|business-transaction%%, i.e. the electronic exchange of goods, services, funds, or data between parties, which we call ‘participants’ to the transaction[^2]. - -An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic %%(digital) agent|digital-agent%%, i.e. equipment (e.g. an app on a mobile phone, a webserver, a browser, …) that acts on behalf of its owner in the transaction. - -## High-Level Example of a Business Transaction - -In its simplest form, this may be envisaged as one party (requestor) that requests another party (provider) to provide some product, e.g. a parking permit, by using his web-browser to navigate to the web-server of the provider (e.g. his municipality) where he is prompted to fill in a form to provide the details of his request (such as name, address, plate number, etc.). When the form is submitted, the provider decides whether or not to service the request (provide the parking permit) based on the data in the form, and take actions accordingly. - -In order for this to work, the provider must design the form such that when a requestor submits a completed form, it can actually decide whether or not to service the request. This has two parts: first, the provider must specify the argument (i.e. the way of reasoning) that it uses to reach this decision - i.e. provide the parking permit. Doing so implicitly specifies the kinds of data that the form will ask for. Secondly, the provider must decide for each of the data it receives, whether or not it is valid to be used in that argument - the process of deciding this is called ‘validation’. Common criteria that help to make this distinction include whether or not the data is presented in the expected format, whether or not it is true (not so easy), whether it is not outdated, or whether or not it satisfies validation rules (in the example, the municipality may require that the specified license plate belongs to a car owned by the person that requests the permit). Validation is important, because reasoning with invalid data may result in wrong conclusions and cause damage. - -Perhaps the most important contribution that the eSSIF-Lab project aims to make, is to create a ubiquitously used infrastructure for designing, filling in, and validating forms (not just web-forms, but also for ‘forms’ - e.g. JSON objects - in API requests). The benefits this will bring are enormous, but outside the scope of this document to list. - -The figure below is a high-level visualization of the filling in and validation parts: - -High-level visualization of the filling in and validation of a form. - -*Figure 1. High-level visualization of the filling in and validation of a form.* - -The transaction that is envisaged here is the issuing of a parking permit. Participants are a person (requestor) that requests such a permit, and an organization (provider) that can issue such a permit. The requestor has one electronic agent, *the Requestor Agent (RA)*, i.e. an SSI-aware app on their mobile phone that can access a secure storage that contains ‘credentials’, i.e. data that is digitally signed by some third party, thus attesting to the truth of that data. The provider has two agents: one is an SSI-aware component *Provider Agent (PA_* that works with the web-server that presents the form, and the other is a person *P* whose task is to validate any data (on behalf of the provider) that is not validated electronically. The form itself contains a means, e.g. a QR-code or a deep-link, that allows *RA* and *PA* to set up a secure communications channel (e.g. SSL, [DIDComm](https://openssi.github.io/peer-did-method-spec/)) and agree on the specific form that needs to be filled in. - -After the *RA* and *PA* have established a communications channel and agree on the form to be filled in, *PA* informs *RA* about the information it needs to fill in the form, and the requirements that this information should satisfy[^3]. *RA* then checks its data store to see whether or not such data is available, sends such data to *PA*, which subsequently validates it and uses it to fill in (appropriate parts of) the form. Finally, *P* validates the remaining data, which either results in a ‘clean’ form, i.e. a form that contains valid data that can subsequently be used to decide whether or not to provide the parking permit, or a message to the requester informing him about missing and/or invalid data. - -When the transaction has been completed, both participants can issue a credential that attests to the results of the transaction. For example, the provider could issue a credential stating that the requestor has obtained a parking permit for a car with a specific plate number (and other attributes). The requestor can store this credential and from that moment on use it in new electronic transactions. - --------- - -[^1]: We realize that by doing this we have a different definition of what self-sovereignty entails than many others. We are open to suggestions for a better phrase. - -[^2]: A good mental model for describing and designing transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations). - -[^3]: Since transactions are symmetric, the requestor could also have a form that the provider needs to fill in so as to provide the requestor with the data it needs to commit to that transaction. We have left that out of this description for the sake of simplicity. diff --git a/docs/functional-architecture.md b/docs/functional-architecture.md new file mode 100644 index 0000000000000000000000000000000000000000..27b116dc0999460506c3acedddf5c1d846b33ebf --- /dev/null +++ b/docs/functional-architecture.md @@ -0,0 +1,425 @@ +--- +id: functional-architecture +title: eSSIF-Lab Functional Architecture +sidebar_label: Functional Architecture +scopeid: essifLab +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +## 1. Purpose + +It is the intention of the eSSIF-Lab project to develop this functional architecture into a generic, and common basis that %%parties|party%% from different backgrounds can use e.g. for: +- thinking and arguing about SSI-related topics and how it contributes to %%business transactions|business-transaction%%; +- 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|party%% 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|business-transaction%%, but also as the govern the %%policies|policy%% 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 %%business transactions|business-transaction%%; +- the interactions between these functions that make such %%business transactions|business-transaction%% happen; +- the various %%policies|policy%% that %%parties|party%% 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 (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|agent%%, etc. do not necessarily coincide with *technical* capabilities, components, %%agents|agent%%, 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|issuer%%, %%wallet|wallet%%, %%holder|holder%% and %%verifier|verifier%% functional components as well as other functionalities that are not described here, e.g. related to UX, setting %%preferences|policy%%, and more. In this functional architecture, the default type of components, %%agents|agent%% etc. are *functional*. + +Since the %%participants|participant%% of a %%business transaction|business-transaction%% are different %%parties|party%%, the negotiation, commitment and execution of that %%transaction|business-transaction%% will be done by %%agents|agent%% of these %%parties|party%%. Assuming that a single %%transaction|business-transaction%% has two such %%parties|party%%, we will use the term '%%Peer Party|peer-party%% (of a specific %%party|party%%, in the context of a single %transaction)' to refer to the participating %%party|party%% in that %%transaction|business-transaction%% that is not the specific %%party|party%% itself. + +When an %%agent|agent%% is involved in such a %%transaction|business-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|peer-agent%% (of a specific %%agent|agent%%, in the context of a single %%transaction|business-transaction%%)' to refer to an %%actor|actor%% with which the specific %%agent|agent%% has a 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|party%% needs to conduct electronic %%business transactions|business-transaction%%. + +eSSIF-Lab Single Party Functional Architecture Overview + +*Figure 1. eSSIF-Lab Single Party Functional Architecture Overview.* + +We use the following coloring conventions in this figure: red is business related, which means that we do not consider this to be part of the SSI Infrastructure. Brown is used for policies, which are defined by (or on behalf) of the principal of the component that uses them to configure themselves, and/or act according to the %%principal's|principal%% preferences and %%policies|policy%%. Green is used for generic SSI infrastructure related functions, and blue represents functions that may be implemented as 'plug-ins' for specific SSI-related technologies. + +The remainder of this chapter describes the layers and their components at a high abstraction level. + +### 2.1. Business Transaction Layers + +At the top of the figure are two business-related layers. Both are within the scope of the eSSIF-Lab project/architecture, yet they are outside the scope of the eSSIF-Lab infrastructure/architecture - that is because they are too business-specific. + +The top layer (in the red rounded rectangle) has the functions of actual %%business transactions|business-transaction%%: it starts with a %%transaction form|transaction-form%%, the data of which is valid, consistent and complete, from which the (business) decision can be made whether or not to engage in a %%business transaction|business-transaction%%, and that has everything necessary to actually execute that %%business transaction|business-transaction%%. The (administrative) results of such a %%business transaction|business-transaction%% are then stored in business data stores. We have put this layer in the eSSIF-Lab architecture for the single purpose of showing how the components of the bottom layer contribute to conduct %%business transactions|business-transaction%%. + +The lower business layer contains two functional components, one for initiating %%transactions|business-transaction%% and the other for stating %%transaction|business-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|policy%% that contains business-specific %%policies|policy%%. + +The task of the Data Collector (or Data Collector) is to handle and initiate requests from/to %%peer agents|peer-agent%% to engage in some kind of %%transaction|business-transaction%%, by negotiating and exchanging data (through one or more, physical or electronic communication channels), and to produce a %%transaction|business-transaction%% form whose contents are complete and valid, enabling an appropriate Colleague to decide whether or not to engage in the %%transaction|business-transaction%%. Note that negotiating a %%transaction|business-transaction%% has two parts: requesting a %%peer agent|peer-agent%% to provide data that its %%principal|principal%% needs, and providing data on behalf of its %%principal|principal%% that a %%peer agent|peer-agent%% requests. After all, a %%business transaction|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 must ensure that the %%transaction|business-transaction%% context is properly maintained if it chooses to exchange data through different communication channels. + +The task of the data discloser (or data discloser) 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 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. + +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. + +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|party%% 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 **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|party%%. Another task of the 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 is to ensure that credentials 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|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, sending them to a holder component of another party, receiving a response to such a request (which we call a '%%presentation|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 with verified data. + +The task of the **holder** is to handle %%presentation requests|presentation-request%% that it receives from verifier components (both of its %%principal|principal%%, and of other %%parties|party%%). Typically, this means looking for the requested data in the %%principal's|principal%% wallet, and using it to construct a %%presentation|presentation%% (=response). However, if the wallet doesn't have it, the holder may negotiate a %%transaction|business-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|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|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|party%%), 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|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|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 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) + +------ + +[ABC] Its origins lie with the [*ABC4Trust project*](https://abc4trust.eu/). Extensive [*documentation*](https://abc4trust.eu/index.php/pub) is available, e.g. an [*Architecture for Attribute-based Credential Technologies*](https://abc4trust.eu/download/Deliverable_D2.2.pdf) (also one [*for developers*](https://abc4trust.eu/download/ABC4Trust-H2.2_ABC4Trust_Architecture_for_Developers.pdf)). + +[eIDAS5] [*"Regulation (EU) No 910/2014 of the European Parliament and of the Council of 23 July 2014 on electronic identification and trust services for electronic %%transactions|business-transaction%% in the internal market and repealing Directive 1999/93/EC"*](http://eur-lex.europa.eu/legal-content/EN/TXT/?uri=uriserv:OJ.L_.2014.257.01.0073.01.ENG). *EUR-Lex*. The European Parliament and the Council of the European Union. + +------ + +### 2.4. API Layers ('ESSIF Glue' and 'SSI Tech APIs') + +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|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|party%% 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. + +------- + +## 3. eSSIF-Lab Infrastructure Functional Components + +This section details the functional specifications of the components that are in scope of the eSSIF-Lab infrastructure, i.e. in the green (rounded) rectangle as shown in the figure below: + +eSSIF-Lab infrastructural (functional) components + +*Figure 2: eSSIF-Lab infrastructural (functional) components.* + +### 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|agent%% of) its %%principal|principal%% to decide whether or not to engage in a (new) %%transaction|business-transaction%% of the specified type. + +Typically, the %%data collector|data-collector%% would start a %%transaction|business-transaction%% either + +- when it receives a request from some %%agent|agent%% of another %%party|party%% for engaging in a %%transaction|business-transaction%% of a specific kind. +- when it is instructed by, or on behalf of its %%principal|principal%%, to request a specific kind of %%transaction|business-transaction%% to some %%agent|agent%% of another %%party|party%%.[^DC.1] + +In either case, a %%transaction|business-transaction%% form (object, context) has to be created that matches the kind of %%transaction|business-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|business-transaction%%, enabling communications to remain congruent, not only with the %%agent|agent%% that requested the %%transaction|business-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|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|business-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|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|business-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|business-transaction%% context that is used internally by (other systems of) its %%principal|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|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|business-transaction%% the %%principal|principal%% is willing to (electronically) engage in, from both the requester and the provider perspectives; +- for each such %%transaction type|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|business-transaction%% commitment decision. + + - 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|credential%%: the verification proofs that must hold to be accepted as a source for valid data. + + - the mapping between fields in such %%credentials|credential%% and fields in the form to be filled in. + +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|business-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|transaction-form%% when they satisfy the verification and validation requirements of its %%principal|principal%%.[^DC.7] + +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|business-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|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|business-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|business-transaction%%, verification proofs are more important than for low-value %%transactions|business-transaction%%. 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|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|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|business-transaction%%. A non-existent postal code, or one that doesn't match the delivery address, may hinder a fluent %%transaction|business-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|business-transaction%% %%risk|risk%%, and checking consistency/coherence of such data is part of the risk mitigation process. + +[^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). + +----- + +### 3.2. Verifier Component, and its Policy/Preferences + +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|transaction-form%%, as well as the results of checking verification proofs (this is also why it is called the '%%verifier|verifier%%' component). + +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|transaction-form%%. It is realistic to think that %%credentials|credential%% from different %%issuers|issuer%% - trusted by the %%verifier's|verifier%% %%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|credential-type%%, %%issuer|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|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|business-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|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|holder%% address. + +This request message should contain at least + +- the %%transaction-id|transaction-id%%, so that when it is copied into the associated response message, the latter can be associated to the %%transaction|business-transaction%% it belongs to. Also, it should contain the +- the (%%credential type|credential-type%%, %%issuer|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|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|holder%% %%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|verifier%% component work, a %%verifier policy|verifier-policy%% 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|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|verifier%% will send a message to the %%data collector|data-collector%%, containing the %%transaction-id|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|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|party%%), and responding to such requests. + +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|wallet%% does not have such a %%credential|credential%%. However, for every (%%credential|credential%%, %%issuer|issuer%%) pair, the request should specify the URI that is capable of issuing such a %%credential|credential%%. If or when the %%holder policy|holder-policy%% permit this, the %%holder|holder%% then requests its %%principal's|principal%% %%data collector|data-collector%% to initiate a new %%transaction|business-transaction%% that will get the %%credential|credential%% from that %%issuer|issuer%%, for which a clean %%transaction form|transaction-form%% would then consist of one that contains said %%credential|credential%%. The %%holder|holder%% would then store it in its %%principal's|principal%% %%wallet|wallet%%, and then proceed to service the %%presentation|presentation%% request as if it had obtained that %%credential|credential%% from its %%principal's|principal%% %%wallet|wallet%%. + +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 policy|holder-policy%% 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|holder%% component work, a %%holder policy|holder-policy%% object is created by, or on behalf of the %%principal|principal%%, which specifies e.g.: + +- 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|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|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|business-transaction%%, and so on. We will use the term '**subject (of a %%statement|assertion%% of a %%party|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|assertion%% of a %%party|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|party%% need to specify the kinds of %%credentials|credential%% they are willing to issue, the class of %%entities|entity%% (e.g. people, cars, %%organizations|organization%%) 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 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|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|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|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|issuer%% component is to issue '%%credentials|credential%%', i.e. digital constructs that contain + +- 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|policy%%, etc.) +- proofs (e.g. a digital signature by which third %%parties|party%% can prove its provenance and integrity. + +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 policy|issuer-policy%%. + +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|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|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|wallet%% Component is to (securely) store data, and in particular: + +- %%credentials|credential%% - both those that have been issued by the %%issuer|issuer%% (i.e. self-signed %%credentials|credential%%) 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|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 %%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 %%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|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|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|wallet%% contents. + +In order to make the %%wallet|wallet%% component work, a %%wallet policy|wallet-policy%% 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 + +:::info Editor's note +*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|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|digital-agent%%. An individual might also have (cloud) servers that %%agents|agent%% of other %%parties|party%% may contact for conducting %%transactions|business-transaction%% 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 %%(digital) agents|digital-agent%%, in which case there is going to be a need for such %%agents|agent%% to contact one another, and conduct %%transactions|business-transaction%% 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|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|party%% may use the single-%%party|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|agent%% of this %%party|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|policy%% for the various SSI functionalities - what kind of support would be useful here? +- … + +%%parties|party%% that want (their %%agents|agent%%) to interact with one another may use the multi-%%party|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|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|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 + +
+ +High-level transaction overview + +*Figure 3: High-level transaction overview.* + +The adjacent figure shows how a %%transaction|business-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|business-transaction%% %%risks|risk%%, etc., all of which is necessary for the %%parties|party%% to (individually/subjectively) decide whether or not to commit to the %%transaction|business-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|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 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|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|business-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|business-transaction%% before it actually commits to the %%transaction|business-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|transaction-request%% to the provider, and ends whenever either one of the %%parties|party%% quits, or both %%parties|party%% commit. + +High-level transaction negotiation + +*Figure 4: High-level transaction negotiation.* + +This figure shows the high-level interactions during this phase. It starts by the requester sending a request for a product or service to the provider. Typically, this would lead to the provider presenting a (web) form the requester must fill in. In the eSSIF-Lab context, the form will also provide a means for setting up a SSI %%communication channel|communication-channel%%, i.e. a secure %%communication channel|communication-channel%% through which provider and requester can both request and obtain (%%presentations|presentation%% of) %%credentials|credential%%, the contents of which they can use to fill in the form. Then, after the form is 'clean', i.e. contains sufficient information for deciding whether or not to commit to the %%transaction|business-transaction%%, this phase ends. + +Note that forms may contain fields that are required only in specific circumstances. It may only be possible to assess whether or not such circumstances apply after some (other) fields have been filled in. This means that the phase for requesting %%presentations|presentation%% and responding to such requests may very well consist of multiple requests and associated responses. + +In the example of the parking permit, the municipality might ask for a %%credential|credential%% that proves the requester is a citizen that is a registered inhabitant of said municipality, a %%credential|credential%% stating its residential address, a %%credential|credential%% stating the make and license plate of the vehicle for which a parking permit is requested, etc. All this is subject to the %%policy|policy%% that the municipality has established for issuing such permits, and hence, it must be expected to differ between municipalities. + +An example of conditionally required fields would be when the requester wants the municipality to customize the parking lot, e.g. because the requester has disabilities. Assessing such circumstances depends on the (optional) field where the requester must state any disabilities they have, and when that is the case, the requester may be asked to fill in fields such as whether or not a parking lot has to be customized (painted blue, with a sign stating that it is reserved for the provided license-place, or the kind of charging device if they have an electric vehicle). + +Conversely, the citizen might request the (alleged) municipality to provide %%credentials|credential%%, e.g. to prove that it is actually an official municipality of the country it is part of. This would provide assurance to the citizen that it would actually be paying the fees to that municipality rather than to e.g. a rogue %%organization|organization%% that might have spoofed the website of the municipality. + +### 5.3. Stating Transactions - Issuing Credentials + +In the eSSIF-Lab context, we take '%%credential|credential%%' to mean any (set of coherent) %%statement(s)|assertion%% about any (one or more) subject(s) that a single %%party|party%% has issued with proof of provenance (i.e. anyone else can determine the identity of that %%issuer|issuer%%) and a proof of integrity (i.e. anyone can determine whether or not the content of the %%credential|credential%% has been changed/tampered with since it was issued). From this, it follows that any %%party|party%% can issue any kind of %%credential|credential%% for any %%entity|entity%% that it knows to exist. A %%credential|credential%% does not need to be about a person or an %%organization|organization%%, but it can also refer to an order, a delivery, a seat-reservation, a prescription, etc. + +We foresee two ways in which %%credentials|credential%% can be issued: + +1. both the requester and provider may issue %%credentials|credential%% to the other %%party|party%% in the process flow that they are in. They can do so for the purpose of stating any (lack of) progress and/or results of the administrative process flow they are in. + In the example of the parking permit, the municipality may need some time to do some manual checks before it can issue the permit; in this case, it could issue a %%credential|credential%% that states that the citizen has requested the parking permit and any other details that might be appropriate. Also, if it can issue the parking permit straight away, it can issue a %%credential|credential%% that contains the details of that permit. The requester may issue a %%credential|credential%% to the municipality stating the date/time and kind of %%transaction|business-transaction%%, judgements or comments about the service that the municipality has provided. +2. any %%party|party%% may issue a %%credential|credential%% upon request. Basically, this means that a %%party|party%% (in the role of requester) issues a request to that other %%party|party%% (in the role of provider) asking for the particular %%credential|credential%%. This is just another case of doing %%transactions|business-transaction%%, that can be handled just as any other kind of %%transaction|business-transaction%%. + In the example of the parking permit, when a citizen requests a permit, the provider might look for an existing permit prior to issuing a new one (it would have to do such a check during the process anyway), and depending on its business logic it would be providing the %%credential|credential%% without further ado, or start the process of issuing a new one. + +## 6. Detailed Transaction Flows + +:::info Editor's note +*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.* +::: + +This chapter explains the details of how electronic %%business transactions|business-transaction%% are being conducted using the eSSIF-Lab architectural components as described in chapter 2. We keep on using the parking permit example that we introduced in section 1.1. for illustrative purposes. + +Note that both %%parties|party%%, requester and provider, each have components as described in chapter 2. Also note that whenever we introduce another %%party|party%%, it too has such components. Thus, every %%party|party%% can play any of the traditional SSI roles '%%verifier|verifier%%', '%%holder|holder%%' and '%%issuer|issuer%%', and each has its own '%%wallet|wallet%%' functionality. Also, they all have %%data collector|data-collector%% and %%data discloser|data-discloser%% functionality that connect these aforementioned infrastructural components with the business applications. + +When reading the next sections, please be aware that when a component of one of these %%parties|party%% communicates with another component, this other component may be of the same %%party|party%%, as well as of the other %%party|party%%. Figure 2 only shows components that belong to a single %%party|party%%. + +### 6.1. Starting a Transaction + +:::info Editor's note +*The eSSIF-Lab functional architecture is not final. This section 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.* +::: + +The requester starts the %%transaction|business-transaction%% by pointing his web-browser to a web-page of the provider that (a) explains how to get a parking permit, and (b) provides a parking-permit application form that needs to be filled in. Technically, this means that the browser does a GET request to an endpoint that is serviced by the providers %%data collector|data-collector%% component. + +The %%data collector|data-collector%% services this request by creating an empty form of a type appropriate for the request. Then, it continues with requesting data to fill in the form (and providing data as requested by the other Party). It starts this by providing a web page that includes the form to be filled in, as well as a deep-link, QR-code or something similar that allows the requester's browser (plug-in) or SSI-app to contact the provider-endpoint and set up a secure %%communication channel|communication-channel%% through which both can communicate electronically. From then on there are two channels between the requester and the provider: one is a traditional (manual) web-browser - web-server channel, the other is one within which the %%SSI-Agents|ssi-agent%% of various %%parties|party%% will be communicating. + +It is a task of the %%data collector|data-collector%% to orchestrate the inputs: different parts of the form may be filled in and subsequently changed in different ways. Some parts + +- are required only after a certain condition is met (which is to be evaluated whenever the data that is entered into the form is changed) +- must or may initially be filled in manually (i.e.: through the browser); +- must or may initially be filled in with data from a %%credential|credential%%; +- may be changed manually; +- may be changed with data from a newly supplied %%credential|credential%%. + +Because of this orchestration, the interface to the %%verifier|verifier%% component can be quite simple; it is shown in the image below: + +Generic Verification with SSI service + +*Figure 5: Generic Verification with SSI service.* + +The request %%identifier|identifier%% is included in messages between the %%data collector|data-collector%% and %%verifier|verifier%% so as to allow them to handle different %%transactions|business-transaction%% at the same time. + +We assume that the provider has specified the form and the associated validation- and issuing %%policies|policy%% that make the following description work. We refer the reader to section \[tbd\] for an explanation of how the provider can do this. + +### 6.2. Stating a Transaction + +:::info Editor's note +*The eSSIF-Lab functional architecture is not final. This section 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.* +::: + +Generic Issuing with SSI service + +*Figure 6: Generic Issuing with SSI service.* diff --git a/docs/governance.md b/docs/governance.md new file mode 100644 index 0000000000000000000000000000000000000000..024faa2b8f053c8e006b672d99598de0d772bd2a --- /dev/null +++ b/docs/governance.md @@ -0,0 +1,18 @@ +--- +id: governance +title: eSSIF-Lab Governance +sidebar_label: Governance +scopeid: essifLab +--- + +## Purpose +The [eSSIF-Lab functional architecture](functional-architecture) identifies and describes a variety of generic SSI functions (capabilities), such as %%holder|holder%%, %%verifier|verifier%%, %%issuer|issuer%%, %%wallet|wallet%%, and more. An %%actor|actor%% that can provide such (generic) capabilities can only _actually_ provide them for a %%party|party%% if it knows how to to comply with the %%rules, working-instructions, preferences and other guidance|policy%% of that %%party|party%%. + +**Governance** is the process by which %%parties|party%% decide how to make decisions, how %%actors|actor%% that work on their behalf are to behave and operate, and ensure this guidance ends up in some document which we will call a %%policy|policy%%. + +## Governance processes and Policies +Within the context of eSSIF-lab, pretty much every function/capability that is defined also mentions a corresponding %%(digital) policy|digital-policy%% that is the place where rules, working-instructions, preferences and other guidance (e.g. preferences) are expected to be specified for the correct functioning of a technical component that may provide such a capability. + +The structure of these %%digital policies|digital-policy%% depends on the design of the technical component, as different kinds of technical components that (still) implement the same capability may have limitations or additional features regarding that capability. + +It is the intention of eSSIF-Lab, however, to at least state some minimal requirements for the policies of various functionalities. \ No newline at end of file diff --git a/docs/notations-and-conventions.md b/docs/notations-and-conventions.md index b9ee6f6acb3f815fecab2f67b907ea3b07bc392e..33f3ded052791d4e642a4e84e5bafa2543007cdf 100644 --- a/docs/notations-and-conventions.md +++ b/docs/notations-and-conventions.md @@ -5,7 +5,6 @@ title: Notations and Conventions This document provides an overview of the notations and conventions being used within eSSIF-Lab. - ### RFC 2119 We shall use keywords such as “shall”, “should”, “may” etc. as defined by [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). @@ -20,10 +19,13 @@ We are working towards deprecating this convention, as we now have better ways o %%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation, as follows: -- a **rectangle** represents a (named) concept. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct. -- a **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. We may refer to the concept at the arrowhead as the ‘target concept’ (TGT) for that relation. Similarly, the concept at the other end will be referred to as the ‘source concept’ (SRC) for that relation. Names are chosen such that ` ` 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 is a generalization of SRC). Thus, SRC must satisfy all constraints that TGT must satisfy, and has all attributes (including properties) that TGT has. -- **Multiplicities** use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended. -- A **concept that is coloured red(dish)** represents a notion that is commonly used ‘in the wild’ (and hence needs not be defined here), relates to one or more concepts we need for the pattern, yet is not the same. We include such ‘red concepts’ to help readers identify and subsequently bridge gaps between commonly held thoughts and the (sometimes subtly) different meanings we need in our model. \ No newline at end of file +- A **rectangle** represents a (named) concept that is explicitly defined. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct. +- A **rectangle that is coloured red(dish)** represents a (named) concept that is commonly used ‘in the wild’ (and hence needs not be defined here), relates to one or more concepts that are explicitly defined yet is not the same. We include such ‘red concepts’ to help readers identify and subsequently bridge gaps between commonly held thoughts and the (sometimes subtly) different meanings we need in our model. +- A **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. We may refer to the concept at the arrowhead as the ‘target concept’ (TGT) for that relation. Similarly, the concept at the other end will be referred to as the ‘source concept’ (SRC) for that relation. Names are chosen such that ` ` 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/introduction.md b/docs/project.md similarity index 92% rename from docs/introduction.md rename to docs/project.md index 328bf5bff458a797c3de5c6cb79f030fe0637d9c..156779efd1635f4b9b4308a740f30216a7f46456 100644 --- a/docs/introduction.md +++ b/docs/project.md @@ -1,10 +1,10 @@ --- -id: introduction -title: Introduction -sidebar_label: eSSIF-Lab +id: project +title: The eSSIF-Lab Project +sidebar_label: eSSIF-Lab Project --- -The European Self-Sovereign Identity Lab ([eSSIF-Lab](https://essif-lab.eu/)) views itself as an ecosystem of parties +The European Self-Sovereign Identity Lab ([eSSIF-Lab](https://essif-lab.eu/)) views itself as an ecosystem of %%parties|party%% that work together to make existing (and new) Self-Sovereign Identity (SSI) technology into a scalable and interoperable infrastructure that businesses can use very easily for conducting (business) transactions with other businesses and individuals alike. @@ -20,7 +20,7 @@ One of the overarching activities in eSSIF-Lab is the design, maintenance and va - [Vision and purpose](vision-and-purpose) - [Functional architecture](functional-architecture) -- [Concepts & Terminology](terminology) +- [Terminology](terminology) For interop purposes, we also maintain a page related to [SSI standards](ssi-standards). diff --git a/docs/terminology-contributions.md b/docs/terminology-contributions.md index 56b0a32690e1384553dc8a0c59984afb98b279f1..94424f5443bc05f50ae82474ce2a62855fa7bda7 100644 --- a/docs/terminology-contributions.md +++ b/docs/terminology-contributions.md @@ -5,8 +5,6 @@ sidebar_label: Contributing to the Terminology Effort scopeid: essifLab --- -import useBaseUrl from '@docusaurus/useBaseUrl'; - :::info **UNDER CONSTRUCTION** TNO to provide further contents ::: diff --git a/docs/terminology-engine-v1-templates/concept-file.md b/docs/terminology-engine-v1-templates/concept-file.md index 9d2318a34f4cf1a79fabd82083d4945917892ec4..040ce8dffbc89f7e664feb133b47476ab0685b5c 100644 --- a/docs/terminology-engine-v1-templates/concept-file.md +++ b/docs/terminology-engine-v1-templates/concept-file.md @@ -6,6 +6,7 @@ type: concept typeid: conceptID stage: draft hoverText: "ConceptID: popuptext for 'conceptID' (tbd)." +glossaryText: "popuptext for 'conceptID' (tbd)." --- -## +### `%%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)" +ss = "(?:['’]?s|\(s\))?" + +dutyright = "(?:dut(?:y|ies)|rights?)" +dutyright = "%{dutyright}(?:-*(?:/|and|or|and/or)-*%{dutyright})?" +dutyrighttype = "%{dutyright}-types?" + +// If you do not specify the files to work on, the replace will be global (throughout the workspace). +// `filter "document.txt"` - document.txt file in the root folder +// `filter "Documents/document.txt"` - document.txt file in the Documents folder in the root folder +// `filter "**/document.txt"` - document.txt files anywhere +// `filter "*.txt"` - any .txt file in the root folder +// `filter "**/*.txt"` - any .txt file + +filter "docs/functional-architecture.md" + +// PREPROCESSING: convert single-%-notations into %%-notations. + +// Convert quotes so that only two types remain: ' an "For starte +replace-regex "[‘’]" +with "'" + +// We might want to 'undo' %%...|...%% markers in case some 'show text' needs to be associated wiht another 'reftext' +// replace-regex "(?<=\W)%%([^\|\n\r]+)\|[^%\n\r]+%%(?=\W)" +// with "%$1%" + +// First, convert %show text% into %%show text%% +// Test set: none may match: %verif%er, %verif"ier%, "%verifier%", `%verifier%` +// Test set: all must match: %my verifier%, ('%verifiers%'), %verifier's%, %verifier’s%, (%(ver)/ifier%):., %(our) (vfyr)%, %verifier's%. %verifier’s%... single-%party%), '**subject (of a %party%)**' to +// replace-regex "(?<=\s\(?%)(\w|\s|\(|\)|[/-’'"])+(?=%([)":,.!?]*\s|-\w))" +replace-regex "(?<=[-\s]\(?'?%)([^%]+)(?=%(([*_):;,.'!?]|\[[^\]]*\]){0,5}\s|-\w))" +with "%$1%" + +// Only thereafter can we convert %showtext (words without trailing `%`-char) into %%showtext%% +// Test set: none may match: %verif%er, %(our) (verifier)%, +// Test set: all must match: %verifier %verifiers, '%verifier'), %verifier's, %verifier’s, %verifier:, (%verifiers), %verifier's..... %verifier’s,?.!? its %principal.[^DC.4] Also a %party)' +replace-regex "(?<=(?:\s\(?'?|/)%)((\w+((/|-|’|')\w)?)+)(?='?\)?[:;,.!?]*(\[[^\]]*\])?\s)" +with "%$1%%" + +// Then, we can expand %%show text%% into %%show text|show text%% +replace-regex "(?<=\W)%%([^\|]*?)%%(?=\W)" +with "%%$1|$1%%" + +// Next, we convert the latter part into lowercase +replace-regex "(?<=\|)([^A-Z%]*?[A-Z].*?)(?=%%)" +with-case "lowercase" + +// Next, we replace whitespace in `lowercase show text` instances with `-` characters +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" +replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)" +with "$1-$2" + +// ACTUAL PROCESSING: now we need to convert well-known `lowercase-show-text`s to appropriate `reftexts` + +// [A] +replace-regex "%{mid}(action|actor|agent|assertion|author)%{ss}%{end}" +with "$1" + +// [B] +replace-regex "%{mid}(business-transaction)%{ss}?%{end}" +with "$1" + +// [C] +// for 'claim', see 'statement' +replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)%{ss}?%{end}" +with "$1" + +replace-regex "%{mid}communications?-(channel|session)%{ss}?%{end}" +with "communication-$1" + +// [D] +replace-regex "%{mid}(definition|dependent|dictionary-file|dictionary|documentation-interop)%{ss}?%{end}" +with "$1" +replace-regex "%{mid}\(?(?:electronic|digital)\)?-(actor|agent|colleague|communication-channel|policy)%{ss}%{end}" +with "digital-$1" + +replace-regex "%{mid}(%{dutyrighttype}|%{dutyright})%{end}" +with "pattern-duties-and-rights" + +replace-regex "%{mid}data-(collector|discloser)-polic(y's|ies)%{end}" +with "data-$1-policy" +replace-regex "%{mid}data-(collector|discloser)%{ss}?%{end}" +with "data-$1" + +// [E] +replace-regex "%{mid}(employee|employer)%{ss}%{end}" +with "$1" +replace-regex "%{mid}(legal-)?entit(y's|ies)%{end}" +with "$1entity" + +// [G] +replace-regex "%{mid}(glossary-file|guardian(ship)?(-relationship)?(-type)?)%{ss}%{end}" +with "$1" +replace-regex "%{mid}glossar(y's|ies)%{end}" +with "glossary" +replace-regex "%{mid}guardianship(-relationship)?%{end}" +with "guardianship" +replace-regex "%{mid}guardianship(-relationship)?-type%{end}" +with "guardianship-type" +replace-regex "%{mid}govern(or)?s?%{end}" +with "governance" + +// [H-I-J-K] (all holder, issuer, verifier and wallet stuff, too) +// for associated policies, see [P] +replace-regex "%{mid}(holder|issuer|verifier|wallet|identifier|jurisdiction(-governor)?|knowledge(-governor)?)%{ss}%{end}" +with "$1" + +// [L-M] +replace-regex "%{mid}(legal-jurisdiction|legal-system|mental-model)%{ss}%{end}" +with "$1" +// for 'legal entities', see 'entities' + +// [O] +replace-regex "%{mid}(objective|organization|owned|owner|ownership)%{ss}%{end}" +with "$1" + +// [P] +replace-regex "%{mid}(participant|pattern-file|pattern|(peer-)(actor|agent)|policy-governor|presentation-request|presentation|principal)%{ss}%{end}" +with "$1" +replace-regex "%{mid}(|peer-)part(y's|ies)%{end}" +with "$1party" +replace-regex "%{mid}(|issuer-|holder-|verifier-|wallet-|transaction-data-(collector|discloser)-)polic(y's|ies)%{end}" +with "$1policy" + +// [R-S] +// For 'rights', see [D]uties +replace-regex "%{mid}(risk|scope-file|scope|ssi-agent)%{ss}%{end}" +with "$1" +replace-regex "%{mid}(statement|claim|statement%{ss}/claim)%{ss}%{end}" +with "assertion" + +// [T] +// for transaction data collector/discloers policies, see [P] +replace-regex "%{mid}(term-file|term|transaction-(agreement|data-(collector|discloser)|form|proposal))%{ss}%{end}" +with "$1" +replace-regex "%{mid}transaction%{ss}?%{end}" +with "business-transaction" + +// [V] +// for verifier stuff - see holder +replace-regex "%{mid}(verifiable-credential|verifier)%{ss}%{end}" +with "$1" +replace-regex "%{mid}vocabular(y's|ies)%{end}" +with "vocabulary" + +// [W] +// for wallet stuff - see holder + +// CLEANING UP UNINTENDED CHANGES + +// Remove all `%%showtext|reftext%%` in docusaurus header. +replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +with "$1$2" +replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +with "$1$2" +replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +with "$1$2" +replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +with "$1$2" +replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +with "$1$2" + +// Remove all `%%showtext|reftext%%` occurrences in markdown headers +replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)" +with "$1$2$4" +replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)" +with "$1$2$4" + +// Remove all `%%showtext|reftext%%` occurrences in ``-constructs +replace-regex "())*?)%%([^\|]*)\|(?:[^%]*)%%" +with "$1$2" +replace-regex "())*?)%%([^\|]*)\|(?:[^%]*)%%" +with "$1$2" diff --git a/docs/terminology-plugin-instructions.md b/docs/terminology-plugin-instructions.md index 8731afefe30b3b27cf2b5bddc8b681dbece92f2b..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'; +import useBaseUrl from '@docusaurus/useBaseUrl'; // All other .md files may get this statement automatically added. ### How it works @@ -40,7 +40,7 @@ e.g. `./docs/terms/party.md`. You can use the following syntax to reference this term in your documentation page: ``` -Some content that wants to reference the %%Party|party%% term +Some content that wants to reference the %%party|party%% term ``` When the script runs, this will be replaced as follows: @@ -96,7 +96,6 @@ and running, you can visit the test example on the `/docs/replacement-test` page replacement-test - ## Generate the glossary page If everything works well with the above procedure, you can then generate a @@ -115,4 +114,4 @@ mentioned above, will be populated in the `glossary.md` page. When the project is up and running, you can visit the glossary on the `/docs/essifLab-glossary` page: - glossary-page + glossary-page diff --git a/docs/terminology.md b/docs/terminology.md index ce020d32dfcc02d9f4da7404fce54e769934cc78..770b03e59f393a12528d689e19e32000420b86b0 100644 --- a/docs/terminology.md +++ b/docs/terminology.md @@ -9,7 +9,7 @@ When people from various backgrounds (and cultures) work together, it is inevita Within eSSIF-Lab, we would like to provide tools, methods and other means to help minimize the amount of misunderstandings, (i.e. to quickly identify any possible misunderstanding and to reduce the effort of resolving them), perhaps even preventing them. -## Vision +### Vision [Many cultures](https://en.wikipedia.org/wiki/Tower_of_Babel#Comparable_myths) have stories, similar to that of the [Tower of Babel](https://en.wikipedia.org/wiki/Tower_of_Babel), that observe that the big feats, such as building a "tower, whose top may reach unto heaven", cannot be achieved unless there is linguistic unity. While is generally recognized (the [EU parliament building](https://images-wixmp-ed30a86b8c4ca887773594c2.wixmp.com/f/e3de7793-c11c-4246-81aa-401be9b09384/d5ttx0w-7bcf343b-2114-46cd-8c30-d722a9725ee9.jpg/v1/fill/w_1054,h_758,q_70,strp/european_union_parliament_02__tower_of_babel__by_nixseraph_d5ttx0w-pre.jpg?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1cm46YXBwOiIsImlzcyI6InVybjphcHA6Iiwib2JqIjpbW3siaGVpZ2h0IjoiPD0xNTk2IiwicGF0aCI6IlwvZlwvZTNkZTc3OTMtYzExYy00MjQ2LTgxYWEtNDAxYmU5YjA5Mzg0XC9kNXR0eDB3LTdiY2YzNDNiLTIxMTQtNDZjZC04YzMwLWQ3MjJhOTcyNWVlOS5qcGciLCJ3aWR0aCI6Ijw9MjIxNyJ9XV0sImF1ZCI6WyJ1cm46c2VydmljZTppbWFnZS5vcGVyYXRpb25zIl19.db-z1OueDUGbAWMhnIbxcDioaFh1zJVlBnUTNAd5y5Y) in Strasbourg [resembles](https://jdreport.com/wp-content/uploads/2014/05/tower-painting-parliament-e14176743284401.jpg.webp) the Tower of Babel as [depicted by the painter Brueghel](https://mattbell.org/wp-content/uploads/Tower-of-Babel-Peter-Breughel.jpg)), one can also observe that the part of the people that care about this and want to achieve a workable 'linguistic unity' lack means and tools that are easy to use. @@ -29,17 +29,17 @@ As the corpus is being used, we expect ideas for improvement [Here](terminology-contributions) is how you may contribute to this terminology effort. -## Terminological Artifacts +### Terminological Artifacts The terminological artifacts that the eSSIF-Lab Concepts and Terminology effort aims to produce include: - A set of (documented/defined) terms that are designed to serve the purposes as specified above. -- A [Glossary](./essifLab-glossary) that lists these terms +- A [Glossary](./essifLab-glossary) that lists these terms. - A set of %%mental models|mental-model%% that provide backgrounds about how specific %%concepts|concept%% relate to one another. Depending on the needs of stakeholders, additional artifacts may be created/generated. -## Notes: +### Notes: Here are some characteristics of the tools being supplied: - When a reader sees a highlighted term (meaning that it is documented), (s)he will see a short description when hovering over the term, and the complete description by clicking onit. diff --git a/docs/terms/action-type.md b/docs/terms/action-type.md new file mode 100644 index 0000000000000000000000000000000000000000..e97a0059560f7a0368dbca4b7413568cb539d5a8 --- /dev/null +++ b/docs/terms/action-type.md @@ -0,0 +1,14 @@ +--- +id: action-type +title: "Action Type" +scopeid: essifLab +type: concept +typeid: action-type +stage: draft +hoverText: "Action Type/Class: the specification of properties and characteristics that that Actions must have to qualify as instance of that class; also: the set of Actions that actually have these properties and characteristics." +glossaryText: "the specification of properties and characteristics that that %Actions% must have to qualify as instance of that class; also: the set of %Actions% that actually have these properties and characteristics." +--- + +:::info Editor's note +TNO (or others) to provide further content of this file. +::: diff --git a/docs/terms/action.md b/docs/terms/action.md index 59e196120c5b3048a90366e7a5a79e2b3476c628..9fd9971a3b99f855e753b584f7176033816d4b83 100644 --- a/docs/terms/action.md +++ b/docs/terms/action.md @@ -5,17 +5,20 @@ scopeid: essifLab type: concept typeid: action stage: draft -hoverText: "Action: something that is actually done/executed by a single Actor (as a single operation) for some Party within a specific context." +hoverText: "Action: something that is actually done/executed - by a single Actor (on behalf of a given Party), as a single operation in a specific context." +glossaryText: "something that is actually done/executed - by a single %Actor% (on behalf of a given %Party%), as a single operation in a specific context." --- ### Short Description -An **Action** is something that is actually done/executed by a %%actor|actor%% in some context (i.e. in a specific place, at a specific time). During the time interval in which the action is executed, the actor may still execute other actions in other execution-contexts (multi-tasking). An action is executed for, or on behalf of, a specific %%party|party%%, which means that the primary guidance for executing the action, e.g. how to execute it, boundary conditions within which the execution must take place, etc., comes from the %%knowledge|knowledge%% of that party. The actor is assumed to have appropriate access to the knowledge of that party. In order to properly execute the action, the executing actor may also use additional knowledge(s) to which it has access. +An **Action** is something that is actually done/executed by a %%actor|actor%% in some context (i.e. in a specific place, at a specific time). During the time interval in which the action is executed, the actor may still execute other actions in other execution-contexts (multi-tasking). An action is executed on behalf of a specific %%party|party%%, which means that the primary guidance for executing the action, e.g. how to execute it, boundary conditions within which the execution must take place, etc., comes from a %%policy|policy%% that this %%party|party%% has established for actions of that kind. The actor is assumed to have appropriate access to that policy. + +The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. ### Purpose -The ability to distinguish between (non)actions allows one to determine which (kinds of) %%actors|actor%% are capable of executing actions (e.g. by establishing that they have the competences required by the party), and as a consequence may be permitted and/or required to execute them. Also, this ability enables parties to determine the execution-policy, i.e. the set of rules and other guidance that actors should obey or comply with when exeucting an action on its behalf. +The ability to distinguish between (non)actions allows one to determine which (kinds of) %%actors|actor%% are capable of executing actions (e.g. by establishing that they have the competences required by the %%party|party%%), and as a consequence may be permitted and/or required to execute them. Also, this ability enables %%parties|party%% to determine the execution-policy, i.e. the set of rules, working-instructions, preferences and other guidance that actors should obey or comply with when exeucting an action on its behalf. ### Criterion -An **Action** is something that is done by an actor, can be considered a single operation, and is performed in a specific context, for or on behalf of a specific party, i.e. in accordance with the policy rules that this party has established for such actions. +An **Action** is something that is done by an actor, can be considered a single operation, and is performed in a specific context, for or on behalf of a specific %%party|party%%, i.e. in accordance with the policy rules that this %%party|party%% has established for such actions. ### Examples - filling in a form and submitting it. @@ -24,6 +27,6 @@ An **Action** is something that is done by an actor, can be considered a single ### Related Concepts - OED defines Action as the fact or process of doing something, typically to achieve an aim ([OED](https://www.lexico.com/definition/action)), which is too generic for our purposes. +- %%actor|actor%% +- %%agent|agent%% -### Background -The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. \ No newline at end of file diff --git a/docs/terms/actor.md b/docs/terms/actor.md index eed27b71ca40f71ff076fd34ecc501b787e0d672..27d9f7e829d1dec80021a442470b16889bd6fb98 100644 --- a/docs/terms/actor.md +++ b/docs/terms/actor.md @@ -6,11 +6,14 @@ type: concept typeid: actor stage: draft hoverText: "Actor: Entity that can act (do things), e.g. people, machines, but not Organizations." +glossaryText: "Entity that can act (do things), e.g. people, machines, but not %Organizations%." --- ### Short Description An **Actor** is someone or something that can actually do things, such as people or machines. Actors will generally do things, i.e. execute %%actions|action%% in different ways, depending on the context, or the %%party|party%% for whom they do this. +The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. + ### Purpose The ability to distinguish between (non)actors allows one to determine which (kinds of) actors are capable of executing which (kinds of) %%actions|action%%, specifically since %%organizations|organization%% do not qualify as an actor (they need actors to get things done). @@ -24,5 +27,8 @@ Entity that is capable of actually executing %%actions|action%% (acting, doing t - Software applications qualify, provided they are actually running on hardware. An app that is just sitting e.g. on a mobile phone but isn't executed does not qualify. - Enterprises, governments, and other %%organizations|organization%% do not qualify. -### Background -The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. +### Related concepts +- %%digital actor|digital-actor%% +- %%peer actor|peer-actor%% +- %%agent|agent%% +- %%principal|principal%% diff --git a/docs/terms/agent.md b/docs/terms/agent.md index f582ee60714035c78d9ab9dd395f86e53ab7d6a5..3f3185385f14c6a1c5af83f9d130b5d3c7dcfcb8 100644 --- a/docs/terms/agent.md +++ b/docs/terms/agent.md @@ -5,18 +5,21 @@ scopeid: essifLab type: concept typeid: agent stage: draft -hoverText: "Agent (of a Party): an Actor that is (at that point in time) executing an Action for, or on behalf of a Party (the Principal of that Actor)." +hoverText: "Agent (of a Party): an Actor that is executing an Action on behalf of a Party (called the Principal of that Actor)." +glossaryText: "an %Actor% that is executing an %Action% on behalf of a %Party% (called the %Principal% of that %Actor%)." --- ### Short Description -%%Actors|actor%% execute %%actions|action%% for, or on behalf of some %%party|party%% (the %%principal|principal%% of that agent), because parties are not considered to be capable of acting. Agents must act in accordance with their %%principal|principal%%, which means that for every kind of action, the principal must provide the proper guidance for their agents, e.g. in terms of policies (rules), working instructions, programs etc. We use the term %%digital agent|digital-agent%% to refer to agents that operate in a digital domain. +An **Agent** is an %%actor|actor%% that is executing an action %%action|action%% on behalf of some %%party|party%% (which we call the %%principal|principal%% of that agent). During the time interval in which the action is executed, the actor may execute other actions in other execution-contexts, on behalf of the same or another %%party|party%%. However, for the execution of a single %%action|action%%, the actor is an agent for precisely one principal. It is assumed that the principal provides its agents with the %%policies|policy%% that provide the agents with the rules, working-instructions, preferences and other guidance that they need to comply with when exeucting the action. + +The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. ### Purpose The ability to distinguish between (non)agents is relevant in many situations, including: - electronic communication: the agent ### Criterion -a property that is attributed to an %%Actor|actor%% whenever it is executing an action for, or on behalf of some %%party|party%% (its %%principal|principal%%). +An **Agent** is a role that an %%actor|actor%% fulfills with respect to some %%party|party%% when that actor is executing some %%action|action%% on behalf of that %%party|party%%. ### Examples @@ -27,6 +30,3 @@ a property that is attributed to an %%Actor|actor%% whenever it is executing an - A company that makes cars may use robots that weld parts of a car together; these robots acts as Agents for that company. - A (running) webserver that accepts product orders for a retailer acts as a (digital) Agent for that retailer. - A wallet app that runs on a phone and that is exclusively used by a single person acts as a (digital) Agent for that person. - -### Background -The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. diff --git a/docs/terms/assertion.md b/docs/terms/assertion.md new file mode 100644 index 0000000000000000000000000000000000000000..f0c404b47f75d0bf877fc294bcd568b6b5c68a19 --- /dev/null +++ b/docs/terms/assertion.md @@ -0,0 +1,33 @@ +--- +id: assertion +title: "Assertion" +scopeid: essifLab +type: concept +typeid: assertion +stage: draft +hoverText: "Assertion: a declaration/statement, made by a specific Party, that something is the case." +glossaryText: "a declaration/statement, made by a specific %Party%, that something is the case." +--- + +:::info Editor's note +TNO (or others) to provide further content of this file. +The content should describe that the Party is the (only) authority to dereference any identifiers used in the Assertion. +::: + +### Short Description +An **Assertion** is a declaration/statement that is made by one specific %%party|party%% (which we refer to as its %%owner|owner%%)[^1]. Such a statement may or may not reflect what that %%party|party%% holds or %%knows|knowledge%% to be true - %%parties|party%% may lie. + +The simplest kind of assertions come in the form ('subject', 'predicate', 'object'). For example, the triple ('John', 'is married to', 'Jill') says 'John is married to Jill'. Note that 'subject', 'predicate' and 'object' are all %%identifiers|identifier%% or other representations of the %%knowledge|knowledge%% to the assertion's %%owner|owner%%, and may not be dereferenceable in other contexts. + +### Purpose +The ability to distinguish between assertions and non-assertions, and particularly to know its %%owner|owner%%, is prerequisite for properly interpreting it (to establish its meaning), determining its trustworthiness, deciding whether or not to (re)act, and if so, what that reaction would be. + +### 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/author.md b/docs/terms/author.md new file mode 100644 index 0000000000000000000000000000000000000000..467b2734d922dbfe220023c83d8abb0f4be41261 --- /dev/null +++ b/docs/terms/author.md @@ -0,0 +1,15 @@ +--- +id: author +title: "Author" +scopeid: essifLab +type: concept +typeid: author +stage: draft +hoverText: "Author (of data/document/file/...): a Party, on whose behalf that data/document/file/... has been created and/or updated." +glossaryText: "a %Party%, on whose behalf that data/document/file/... has been created and/or updated." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + diff --git a/docs/terms/business-transaction.md b/docs/terms/business-transaction.md index 452f4fc4838768b72d1a505c2e4bd547705a1748..3b80ca3b935694312e55b350f28ec35040c321e8 100644 --- a/docs/terms/business-transaction.md +++ b/docs/terms/business-transaction.md @@ -5,14 +5,46 @@ scopeid: essifLab type: concept typeid: business-transaction stage: draft -hoverText: "Business Transaction: the electronic exchange of goods, services, funds, or data between parties (called‘participants’ to the transaction)" +hoverText: "Business Transaction: the exchange of goods, services, funds, or data between some Parties (called Participants of the Transaction)." +glossaryText: "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. + :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide further content/revisions. ::: +:::info Editor's note +Explanation required about '%%commitment decision|commitment-decision%%' (i.e. 'promise' decisions in [DEMO](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations)). +::: + +### High Level Example + +In its simplest form, this may be envisaged as one %%party|party%% (requestor) that requests another %%party|party%% (provider) to provide some product, e.g. a parking permit, by using his web-browser to navigate to the web-server of the provider (e.g. his municipality) where he is prompted to fill in a form to provide the details of his request (such as name, address, plate number, etc.). When the form is submitted, the provider decides whether or not to service the request (provide the parking permit) based on the data in the form, and take actions accordingly. + +In order for this to work, the provider must design the form such that when a requestor submits a completed form, it can actually decide whether or not to service the request. This has two parts: first, the provider must specify the argument (i.e. the way of reasoning) that it uses to reach this decision - i.e. provide the parking permit. Doing so implicitly specifies the kinds of data that the form will ask for. Secondly, the provider must decide for each of the data it receives, whether or not it is valid to be used in that argument - the process of deciding this is called ‘validation’. Common criteria that help to make this distinction include whether or not the data is presented in the expected format, whether or not it is true (not so easy), whether it is not outdated, or whether or not it satisfies validation rules (in the example, the municipality may require that the specified license plate belongs to a car owned by the person that requests the permit). Validation is important, because reasoning with invalid data may result in wrong conclusions and cause damage. + +Perhaps the most important contribution that the eSSIF-Lab project aims to make, is to create a ubiquitously used infrastructure for designing, filling in, and validating forms (not just web-forms, but also for ‘forms’ - e.g. JSON objects - in API requests). The benefits this will bring are enormous, but outside the scope of this document to list. + +The figure below is a high-level visualization of the filling in and validation parts: + +High-level visualization of the filling in and validation of a form. + +*Figure 1. High-level visualization of the filling in and validation of a form.* + +The transaction that is envisaged here is the issuing of a parking permit. Participants are a person (requestor) that requests such a permit, and an organization (provider) that can issue such a permit. The requestor has one electronic agent, *the Requestor Agent (RA)*, i.e. an SSI-aware app on their mobile phone that can access a secure storage that contains ‘credentials’, i.e. data that is digitally signed by some third %%party|party%%, thus attesting to the truth of that data. The provider has two agents: one is an SSI-aware component *Provider Agent (PA_* that works with the web-server that presents the form, and the other is a person *P* whose task is to validate any data (on behalf of the provider) that is not validated electronically. The form itself contains a means, e.g. a QR-code or a deep-link, that allows *RA* and *PA* to set up a secure %%communication channel|communication-channel%% (e.g. SSL, [DIDComm](https://openssi.github.io/peer-did-method-spec/)) and agree on the specific form that needs to be filled in. + +After the *RA* and *PA* have established a %%communication channel|communication-channel%% and agree on the form to be filled in, *PA* informs *RA* about the information it needs to fill in the form, and the requirements that this information should satisfy[^1]. *RA* then checks its data store to see whether or not such data is available, sends such data to *PA*, which subsequently validates it and uses it to fill in (appropriate parts of) the form. Finally, *P* validates the remaining data, which either results in a ‘clean’ form, i.e. a form that contains valid data that can subsequently be used to decide whether or not to provide the parking permit, or a message to the requester informing him about missing and/or invalid data. + +When the transaction has been completed, both participants can issue a credential that attests to the results of the transaction. For example, the provider could issue a credential stating that the requestor has obtained a parking permit for a car with a specific plate number (and other attributes). The requestor can store this credential and from that moment on use it in new electronic transactions. -### Notes +-------- -1. A good mental model for describing and designing business transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations). \ No newline at end of file +[^1]: Since transactions are symmetric, the requestor could also have a form that the provider needs to fill in so as to provide the requestor with the data it needs to commit to that transaction. We have left that out of this description for the sake of simplicity. However, the [eSSIF-Lab functional architecture](../functional-architecture) does take this into account. \ No newline at end of file diff --git a/docs/terms/colleague.md b/docs/terms/colleague.md index 9a71d8da974bff675d2c666438f338094586c4b4..a5a47a19388ffe2d991274bf10287f321c4bd8a5 100644 --- a/docs/terms/colleague.md +++ b/docs/terms/colleague.md @@ -5,10 +5,15 @@ scopeid: essifLab type: concept typeid: colleague stage: draft -hoverText: "Colleague (of an Agent): any other Agent that has the same Principal (i.e. Party on whose behalf they exeucte Actions)." +hoverText: "Colleagues: two or more (digital or non-digital) Agents that have the same Principal (i.e. Party on whose behalf they exeucte Actions)." +glossaryText: "two or more (digital or non-digital) %Agents% that have the same %Principal% (i.e. %Party% on whose behalf they exeucte %Actions%)." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: +### Purpose +The ability to distinguish between (non) colleagues allows us to reason and communicate about the set of (digital and non-digital) %%actors|actor%% that are %%agents|agent%% for a **principal|principal%%. This is relevant in situations where different %%agents|agent%% excute %%actions|action%% in a single %%business transaction|business-transaction%% on behalf of the same %%principal|principal%% + +See also: %%digital colleague|digital-colleague%%. diff --git a/docs/terms/commitment-decision.md b/docs/terms/commitment-decision.md new file mode 100644 index 0000000000000000000000000000000000000000..a5bab7e3e71cdacda087c18c2f5272ff829f292b --- /dev/null +++ b/docs/terms/commitment-decision.md @@ -0,0 +1,14 @@ +--- +id: commitment-decision +title: "Commitment Decision" +scopeid: essifLab +type: concept +typeid: commitment-decision +stage: draft +hoverText: "Commitment Decision (of a Party in a Business Transaction): the decision of that Party whether or not to commit to that Business Transaction, i.e. (promise) to fulfill the obligations that the associated Business Transaction Agreement Proposal would impose on that Party once it were signed." +glossaryText: "the decision of that %Party% whether or not to commit to that %Business Transaction%, i.e. (promise) to fulfill the obligations that the associated %Business Transaction Agreement Proposal% would impose on that %Party% once it were signed." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: diff --git a/docs/terms/communication-channel.md b/docs/terms/communication-channel.md new file mode 100644 index 0000000000000000000000000000000000000000..7af9696e39d97e5acccaa2507a415684da000dd5 --- /dev/null +++ b/docs/terms/communication-channel.md @@ -0,0 +1,28 @@ +--- +id: communication-channel +title: "Communication Channel" +scopeid: essifLab +type: concept +typeid: communication-channel +stage: draft +hoverText: "Communication Channel: a (digital or non-digital) means by which two Actors can exchange messages with one another." +glossaryText: "a (digital or non-digital) means by which two %Actors% can exchange messages with one another." +--- + +:::info Editor's note +TNO (or others) to provide further content of this file. +::: + +### Notes + +A %%Communication Channel|communication-channel%% is said to be **digital** if it uses a digital means to exchange (digital) messages between two %%digital actors|digital-actor%%. + +A %%Communication Channel|communication-channel%% is said to be **secure** if it provides the following guarantees: +- every of its endpoint is being used by precisely one %%actor|actor%%; +- during its entire lifetime, each endpoint will only be used by this %%actor|actor%% (endpoint authentication; note that identification of the %%actor|actor%% that uses an endpoint, or its %%principal|principal%% is NOT required); +- only the %%actors|actor%% that use an endpoint are capable of transmitting and reading messages through that channel (message secrecy - typically obtained by encrypting the messages); +- the receiver of a message can determine whether or not the message has been received as it was transmitted (message integrity). + +### Related Concepts +- %%Communication Session|communication-session%% + diff --git a/docs/terms/communication-session.md b/docs/terms/communication-session.md new file mode 100644 index 0000000000000000000000000000000000000000..f10b30636cad7bacbda26c0dc9cc9791d1b46229 --- /dev/null +++ b/docs/terms/communication-session.md @@ -0,0 +1,15 @@ +--- +id: communication-session +title: "Communication Session" +scopeid: essifLab +type: concept +typeid: communication-session +stage: draft +hoverText: "Communication Session: a time interval during which two Actors have an established Communication Channel that does not exist outside of that time interval." +glossaryText: "a time interval during which two %Actors% have an established %Communication Channel% that does not exist outside of that time interval." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + diff --git a/docs/terms/concept-file.md b/docs/terms/concept-file.md index 4c6917d715d28e53f896641185ff8743c9132b6d..455d1feaedec70f1d27d462b4a15d25a66bda02f 100644 --- a/docs/terms/concept-file.md +++ b/docs/terms/concept-file.md @@ -5,7 +5,8 @@ scopeid: essifLab type: concept typeid: concept-file stage: draft -hoverText: "Concept-file: a file that defines/specifies a Concept." +hoverText: "Concept-file: a file whose contents defines/specifies a Concept." +glossaryText: "a file whose contents defines/specifies a %Concept%." --- ### Short Description diff --git a/docs/terms/concept.md b/docs/terms/concept.md index 53dbd345f53948bbecbd6584c5bc8d36c2c31ec7..6359433d8f47861b27f8f168dee8f56bb3d00f7e 100644 --- a/docs/terms/concept.md +++ b/docs/terms/concept.md @@ -5,13 +5,16 @@ scopeid: essifLabTerminology type: concept typeid: concept stage: draft -hoverText: "Concept: A Concept tries to capture the idea behind a classification of entities, allowing us to reason about everything in the class as if it were one thing." +hoverText: "Concept: the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same')." +glossaryText: "the ideas/thoughts behind a classification of %Entities% (what makes %Entities% in that class 'the same')." --- ### Short Description A Concept tries to capture the idea behind a classification of entities[^1], allowing us to reason about everything in the class as if it were one thing. For example, the ideas ([mental representations](https://en.wikipedia.org/wiki/Mental_representation)) you have when processing the sentences "I can drink beer from a beer glass' and 'I can drink beer from a coffee mug' shows that the concepts that are behind 'beer glass' and 'coffee mug' differ. Note that in order to communicate about this idea, we also need a word or phrase (i.e.: a termat we can use to refer to (instances of) this idea. +The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. + ### Purpose Working together is easier when you and your peers share the same ideas. We need a way to test and ensure, that you and your peers _actually_ have the same understanding, for the purpose of making cooperation easier. Doing so is expected to not only reduce the number of terminological discussions, but also improve the efficiency and effectiveness of the remaining discussions. @@ -31,9 +34,6 @@ A (description/specification of a) Concept MUST be [intensionally defined](https * %%Mental(or Conceptual) Model|pattern%% is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents. -### Background -The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. - ### Domains * essifLab diff --git a/docs/terms/corpus.md b/docs/terms/corpus.md index 44579be8cf04f488f3f6c7729600e82aee1fd6d1..a145d41cb4f01c9b71af5efe7209bf202bbc95ba 100644 --- a/docs/terms/corpus.md +++ b/docs/terms/corpus.md @@ -6,8 +6,9 @@ type: concept typeid: corpus stage: draft hoverText: "Corpus (of Terminology): the documentation that describes the Knowledge around a set of Terms and Concepts." +glossaryText: "the documentation that describes the %Knowledge% around a set of %Terms% and %Concepts%." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: diff --git a/docs/terms/credential-catalogue.md b/docs/terms/credential-catalogue.md new file mode 100644 index 0000000000000000000000000000000000000000..28d25571138a3ef8a4e859df66a44e8477a8f5e9 --- /dev/null +++ b/docs/terms/credential-catalogue.md @@ -0,0 +1,14 @@ +--- +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 the information about Credential Types that their respective Governing Parties have decided to disclose so as to enable other Parties to decide whether or not it is beneficial for them to use Credentials of such types." +glossaryText: "the capability to register and advertise the information about %Credential Types% that their respective %Governing Parties% have decided to disclose so as to enable other %Parties% to decide whether or not it is beneficial for them to use %Credentials% of such types." +--- + +:::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..ec75b40dd10d6eae46962ebc0c2e663587516928 --- /dev/null +++ b/docs/terms/credential-type.md @@ -0,0 +1,18 @@ +--- +id: credential-type +title: "Credential Type" +scopeid: essifLab +type: concept +typeid: credential-type +stage: draft +hoverText: "Credential Type: the specification of the contents, properties, constraints etc. that Credentials of this type must have/comply with." +glossaryText: "the specification of the contents, properties, constraints etc. that %Credentials% of this type must have/comply with." +--- + +### Short Description +A **credential-type** is a specification that states +- the contents that %credentials of that kind must or may have; this includes of which kinds of %%assertions (claims, statements)|assertion%% as well as meta-data. +- properties Typically, %%parties|party%% that issue %%credentials|credential%% of some %%kind|credential-type%% will advertise the %%credential types|credential-type%% of the %%credentials|credential%% that it may issue. + +### Purpose +%%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 57699d741060e741adfe07f11e1f2b2b7051ba15..c1a53351e421f98dc2007068dd1d358449170e99 100644 --- a/docs/terms/credential.md +++ b/docs/terms/credential.md @@ -5,15 +5,39 @@ scopeid: essifLab type: concept typeid: credential stage: draft -hoverText: "Credential: data, representing a set of statements made by one Party (the author of the credential)." +hoverText: "Credential: data, representing a set of Assertions (claims, statements), authored and signed by, or on behalf of, a specific Party." +glossaryText: "data, representing a set of %Assertions% (claims, statements), authored and signed by, or on behalf of, a specific %Party%." --- -:::info Editor's note -TNO to provide the content of this file. -::: +### Short Description +A **credential** is a set of (related) %%assertions|assertion%% (also referred to as claims, or statements), to which metadata is added (e.g. date of issuing), and a number of proofs, which typically include a proof of provenance (i.e. proof that it was created on behalf of a specific %%party|party%%), and a proof of integrity (i.e. proof that the data hasn't changed since it was issued). + +In physical credentials, such as drivers licenses and passports, proofs of integrity usually apply to the physical document itself. They come in a variety of forms, such as the structure of the paper, holograms, watermarks, or (embedded) chips. The proof of provenance usually consists of the form-format of the credential and %%assertions|assertion%% about the document issuer. + +In digital credentials, such as (digital) certificates or %%verifiable credentials|verifiable-credential%%, the basic proofs (of provenance and integrity) usually consist of a digital signature of some kind. It therefor only 'works' for as long as the associated private/secret key actually remains a secret of the issuing %%party|party%%. + +Credentials whose %%assertions|assertion%% refer to some %%entity|entity%%, e.g. a person, an organization, an animal, a shipment, etc. In such cases, it must be possible for arbitrary %%parties|party%% to identify that %%entity|entity%%, and/or verify an %%assertion|assertion%% by some other %%party|party%% that identifies that %%entity%%. To this end, credentials may contain %%assertions|assertion%% about characteristics of that %%entity|entity%%, the idea being that if a %%party|party%% establishes that some %%entity|entity%% has (a sufficient number of) these characteristics, that %%entity|entity%% is the one bound to the credential. Attributes typically include one or more names, various dates, a photograph, etc. Other attributes might include biometrics, RFID-codes, bar-codes, etc. + + +The signature on a credential may have other meanings. For example, a %%party|party%% may choose to only sign the credential data if it is convinced of the truth of the statements, in which case the credential 'payload' can be seen as an excerpt of the %%knowledge|knowledge%% of that %%party|party%%. + +Anyone can create any kind of credential containing any statement about anyone or anything. The mere fact that a statement comes in the form of a credential (i.e. with a signature) doesn't imply that it is true. + +### Purpose +A **credential** serves to provide assurances regarding the provenance and integrity of data as it is being transferred between %%parties|party%%. Specializations of the generic credential concept may be created for the purpose of providing additional assurances. + +### Criteria +A **credential** is the composition of +- a non-empty set of arbitrary statements (claims, %%assertions|assertion%%) that originate from a single %%party|party%%; +- a set of metadata (data about the credential itself); +- a set of proofs, which includes at least proofs of provenance and integrity. ### Related Concepts - %%verifiable credential|verifiable-credential%% - %%verified data|verified-data%% - %%validated data|validated-data%% +### References: +- W3C VC [definition of 'credential'](https://www.w3.org/TR/vc-data-model/#dfn-credential) +- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) + diff --git a/docs/terms/data-collector-policy.md b/docs/terms/data-collector-policy.md new file mode 100644 index 0000000000000000000000000000000000000000..25b7d55c9ac195f53891ed0ea99f5ebf7615dc91 --- /dev/null +++ b/docs/terms/data-collector-policy.md @@ -0,0 +1,21 @@ +--- +id: data-collector-policy +title: "Data Collector Policy" +scopeid: essifLab +type: concept +typeid: data-collector-policy +stage: draft +hoverText: "Data Collector Policy: a Digital Policy that enables an operational Data Collector component to function according to the rules of its Policy Governor." +glossaryText: "a %Digital Policy% that enables an operational %Data Collector% component to function according to the rules of its %Policy Governor%." +--- + +### Short Description +A **Data Collector Policy** is a %%digital policy|digital-policy%% that enables an operational %%Data Collector component|data-collector%% to function according to the rules of its %%Policy Governor|policy-governor%%. + +Such a policy includes e.g. the kinds of data (and meta-data) required to make these kinds of decisions, criteria to distinguish between %%data that is valid|validated-data%% and data that is not, any data conversions that may be needed, etc. + +### Purpose +The purpose of a **Data Collector Policy** is to enable the creation of (technical) components that implement the generic %%data collector|data-collector%% functionality that will subsequently use such policies to guide their behaviour. + +### Criteria +A **Data Collector Policy** is a %%digital policy|digital-policy%% that enables an operational %%Data Collector component|data-collector%% to function according to the rules, working-instructions and other guidance of its %%Policy Governor|policy-governor%%. diff --git a/docs/terms/data-collector.md b/docs/terms/data-collector.md new file mode 100644 index 0000000000000000000000000000000000000000..ffdb8a15723c0e9b44e7f46837daf2c6183927e6 --- /dev/null +++ b/docs/terms/data-collector.md @@ -0,0 +1,110 @@ +--- +id: data-collector +title: "Data Collector" +scopeid: essifLab +type: concept +typeid: data-collector +stage: draft +hoverText: "Data Collector: a functional component that is capable of collecting data from various Parties in the context of some Business Transaction, and Validating this data for the purpose of making one (or more) decision(s)." +glossaryText: "a functional component that is capable of collecting data from various %Parties% in the context of some %Business Transaction%, and %Validating% this data for the purpose of making one (or more) decision(s)." +--- + +### Short Description +A **Data Collector** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that a %%party|party%% may use to collect sufficient and %%validated data|validated-data%% for deciding whether or not a request (typically for a product or a service) is to be serviced. + +### Purpose +The purpose of a Data Collector is to collect sufficient and %%validated data|validated-data%% that eneables (an %%agent|agent%% of) its %%principal|principal%% to decide whether or not some request (typically for a product or a service) is to be serviced. + +### Functionality +A data collector typically starts to collect data when it receives a request (e.g. to provide a product or service). The reception of such a request triggers the creation of a new %%business transaction|business-transaction%%. The task of the data collector is to collect %%validated data|validated-data%% that is sufficient for making a commitment decision (or, as [DEMO](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations) calls it: a 'promise' or 'quit' decision.) + +Starting the data collection for a transaction does NOT imply that the identity of the %%actors|actor%% from whom/which the request originated, is established (or authenticated). It also does NOT imply that the identity of the %%peer party|peer-party%% is established (or authenticated). The data collector simply proceeds to collect a sufficient amount of data such that the associated decision can be made, according to the rules, working-instructions and other guidance provided by its %%principal's|principal%% %%data collector policy|data-collector-policy%%. Such data may include identity data, but it also may not. + +Starting the data collection for a transaction implies that the data collector informs the %%data discloser component|data-discloser%% about the %%transaction|business-transaction%% that has just started, and the kind of that transaction. This allows the %%data discloser component|data-discloser%% to process requests for data from %%peer agents|peer-agent%%[^1x] + +All guidance that the data collector needs to collect the necessary and %%validated data|validated-data%% to make that decision is provided by the %%data collector policy|data-collector-policy%% that has been established by the data collector's %%principal|principal%%. Such a policy includes e.g. the kinds of data (and meta-data) required to make these kinds of decisions, criteria to distinguish between %%data that is valid|validated-data%% and data that is not, any data conversions that may be needed, etc. + +A data collector may multi-task, i.e. simultaneously/asynchronously collect data for multiple %%transactions|business-transaction%%. To organize this, messages that are exchanged with %%peer agents|peer-agent%% must contain an identifier that allows the data collector and its peer agents to identify the transaction to which each message belongs. + +During the time in which a data collector is collecting data for a specific %%transaction|business-transaction%%, it may choose to setup, accept, and tear down %%communication sessions|communication-session%% with any %%actors|actor%%, if that is appropriate. This allows requests for data to be sent to different kinds of %%peer party|peer-party%%-%%agents|agent%%, e.g. human or %%digital|digital-agent%% agents. However, the data collector then must ensure that every of these %%agents|agent%% are all %%colleagues|colleague%%, i.e. have the %%peer party|peer-party%% as their %%principal|principal%%. + +A data collector benefits from generic APIs or (G)UIs that allow it to simply ask for the data that it requires. Specifically for SSI, the data collector uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Verifier|verifier%% functionalities. + +### Criteria +A **Data Collector** is a functional component in the [eSSIF-Lab functional architecture](../functional-architecture) that +- services requests by %%digital|digital-agent%% and non-digital %%agents|agent%%, for providing a product or service, thereby starting a %%transaction|business-transaction%%; +- can setup, accept and tear-down communication channels of various kinds, with %%digital|digital-colleague%% and/or non-digital %%colleagues|colleague%% of that %%requesting agent|agent%%,[^peer-agents] as appropriate for the data exchanges that are needed to conduct the transactions; +- can use any appropriate communication channel with a %%peer-agent|peer-agent%% to: + - request for data that, according to the %%Data Collector Policy|data-collector-policy%% is needed to decide whether or not to commit to the transaction; + - process the responses to such requests, in an orchestrated way, thereby complying with the rules of its %%principal's|principal%% %%Data Collector Policy|data-collector-policy%%, the result of which (in the end) is a set of %%validated data|validated-data%% that can serve the purpose of deciding whether or not to commit to the transaction; + - receive similar requests from its %%peer-party%%, and respond to such requests in compliance with the rules of its %%principal's|principal%% %%Data Collector Policy|data-collector-policy%%; +- has a mechanism to ensure that within a %%transaction|business-transaction%%, it uses the latest (most receent) %%Data Collector Policy|data-collector-policy%% of its %%principal|principal%%. + +### Deprecated - TVE Functionality + +:::info Editor's note +TNO to revise the text below. +This section is the old text of what was called the Transaction Validation Engine. +It will be deleted in the (near?) future. +::: + +Typically, the Data Collector would start a transaction either + +- when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind. +- when it is instructed by, or on behalf of its Principal, to request a specific kind of transaction to some Agent of another Party.[^one] + +In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Principal and/or using different communication channels. + +Handling/managing the various communication channels through which data can be exchanged is also a task of the Data Collector[^2]. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens). + +Thus, the Data Collector is generally considered capable of obtaining data through different communication channels. However, the technical tracks of eSSIF-Lab will exclusively focus on the communication channel through which credentials can be requested and obtained. Any extensions or business productization of Data Collector designs may be considered in the business tracks of eSSIF-Lab. The latter is not considered any further in this section. + +In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the Data Collector needs to know what kinds of credentials it should ask for, which Parties its Principal trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.[^3] Also, when the Data Collector gets a credential that satisfies the necessary verification proofs, it needs a way to map the contents of that credential to the structure of the transaction context that is used internally by (other systems of) its Principal.[^4] Also, as the Data Collector gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.[^5] + +In order to make the Data Collector work, a Validation Policy (or Data Collector Policy) is created by, or on behalf of its Principal, which specifies at least: + +- the kinds of transactions the 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 Principal is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing Parties do the actual credential issuing may be specified[^6]. + + - for each kind of credential: the verification proofs that must hold to be accepted as a source for valid data. + + - the mapping between fields in such credentials and fields in the form to be filled in. + +The Policy must be designed in such a way that it is extendable as new features will be called for in the future. + +The ability to create new transaction contexts and the availability of the Data Collector Policy enable the Data Collector to request the Verifier component of its Principal 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 Principal.[^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 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’. + +----- +### Notes: + +:::info Editor's note +TNO to revise the footnote markers +::: + +[^1x]: In the same way that the data collector needs to collect data in order to be able to decide whether or not to commit, %%agents|agent%% of the %%peer party|peer-party%% need to collect data for making a similar commitment decision. Requests for such data are to be processed by the %%data discloser component|data-discloser%% under guidance of its %%data-discloser-policy%%. + +[^1a]: If the %%data collector policy|data-collector-policy%% specifies that data is to be collected for other purposes, the %%data collector|data-collector%% should then be provided a means to inform its %%peer party|peer-party%% of such purposes, and the policy should not specify that such data is required to make the commitment decision. + +[^1 (peer-agents)]: Note that such agents have then become so-called %%peer-agents|peer-agent%% (of the Data Collector) for that specific transaction. Also, the (single!) %%principal|principal%% of these %%peer-agents|peer-agent%% is the %%peer-party|peer-party%% of the %%principal|principal%% of the Data Collector (again, for that specific transaction). + +[^1]: This feature ensures that the transaction is really two-way, and both Parties can request credentials from the other. For example, a web-shop can then ask for a (delivery) address credential, and the customer can ask for a credential issued e.g. by the chamber of commerce that the web-shop is a legitimate company (and not some maffia website). + +[^2]: It may well be that this functionality can somehow be split off in the (near) future. + +[^3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Principal of the Data Collector. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years. + +[^4]: For example, a credential that contains an address uses a specific schema to specify addresses, e.g. the ‘PostalAddress’ as defined by schema.org. This schema differs quite a bit from that of Dutch addresses as [*defined*](https://bag.basisregistraties.overheid.nl/def/bag) by the official (authentic) Dutch Registration of Addresses and Buildings (BAG). It may also well differ from the structure of addresses that databases of the Principal have implemented. Mapping allows such cases to be accommodated for. + +[^5]: Inconsistent or incoherent data is necessary for various purposes. First, it allows for correct further processing of the transaction. A non-existent postal code, or one that doesn’t match the delivery address, may hinder a fluent transaction processing, resulting in additional costs and processing times. Another purpose is the early warning or detection of possible fraud/abuse. Remember that part of the data is being asked for reducing transaction risk, and checking consistency/coherence of such data is part of the risk mitigation process. + +[^6]: This enables the Data Collector to pass the endpoint URI on to the Verifier when it requests for such a credential, which in turn can send it to the holder of other Parties enabling them to obtain the credential from that issuer endpoint if that other Party does not have that credential in its wallet. The endpoint URI can in fact be put in the policy, because the (human) Agent that creates/maintains the policy would need to know that the issuing Party is actually issuing such credentials, what their contents means, etc., and hence is capable of tracking down the URI where that Party issues the credentials. + +[^7]: A reference to this specification will be added when it becomes available (draft or otherwise). diff --git a/docs/terms/data-discloser-policy.md b/docs/terms/data-discloser-policy.md new file mode 100644 index 0000000000000000000000000000000000000000..7733a887134e7a6d9f838b13b19f662b134ad893 --- /dev/null +++ b/docs/terms/data-discloser-policy.md @@ -0,0 +1,21 @@ +--- +id: data-discloser-policy +title: "Data Discloser Policy" +scopeid: essifLab +type: concept +typeid: data-discloser-policy +stage: draft +hoverText: "Data Discloser Policy: a Digital Policy that enables an operational Data Discloser component to function according to the rules of its Policy Governor." +glossaryText: "a %Digital Policy% that enables an operational %Data Discloser% component to function according to the rules of its %Policy Governor%." +--- + +### Short Description +A **Data Discloser Policy** is a %%digital policy|digital-policy%% that enables an operational %%Data Discloser component|data-discloser%% to function according to the rules of its %%Policy Governor|policy-governor%%. + +Such a policy includes e.g. the kinds of data (and meta-data) that may be disclosed, the conditions that need to be satisfied for actually disclosing such kinds of data, any meta-data (assurances) that maybe added to data being disclosed, etc. + +### Purpose +The purpose of a **Data Discloser Policy** is to enable the creation of (technical) components that implement the generic %%data discloser|data-discloser%% functionality that will subsequently use such policies to guide their behaviour. + +### Criteria +A **Data Discloser Policy** is a %%digital policy|digital-policy%% that enables an operational %%Data Discloser component|data-discloser%% to function according to the rules, working-instructions and other guidance of its %%Policy Governor|policy-governor%%. diff --git a/docs/terms/data-discloser.md b/docs/terms/data-discloser.md new file mode 100644 index 0000000000000000000000000000000000000000..dae37b5dac0410f40b324ce316f0b19047103270 --- /dev/null +++ b/docs/terms/data-discloser.md @@ -0,0 +1,43 @@ +--- +id: data-discloser +title: "Data Discloser" +scopeid: essifLab +type: concept +typeid: data-discloser +stage: draft +hoverText: "Data Discloser: a functional component that is capable of disclosing data to (Agents of) other Parties, e.g. in the form of Credentials." +glossaryText: "a functional component that is capable of disclosing data to (Agents of) other %Parties%, e.g. in the form of %Credentials%." +--- + +### Short Description +A **Data Discloser** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that applications (that work for some %%Party|party%%) can call to communicate things such as: +- the results of a business transaction (e.g. statements to confirm that a transaction happened, thereby supplying appropriate details) +- the status of a business transaction (e.g. that an order has been received in good order, that delivery of an order is dealyed or otherwise changed) +- knowledge (including judgements) that this Party has about %%Entities|entity%% (people, organizations, things, orders, deliveries, etc.) + +The Data Discloser uses a %%data-collector-policy|data-collector-policy%% to learn about the applicable (business) rules of its %%principal|principal%%. Such a policy may specify e.g. which types of credentials its principal is willing to (have) issue(d), to whom such credentials may be issued and the kinds of assurances that must be obtained before doing so, etcetera. + +The Data Discloser uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities. + +### Purpose +The purpose of the 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 Principal already has created. + +### Criteria +A **Data Discloser** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) that is capable of stating (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other %%Parties|party%%. + +### Functionality +Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term ‘**subject (of a statement of a Party)**’ to refer to the entity that this Party knows to exist, and about whom/which the statement has been made. + +We will use the term ‘**subject-id (of a statement of a Party)**’ to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not). + +Parties need to specify the kinds of credentials they are willing to issue, the class of entities (e.g. people, cars, Organizations) for which it will issue them, and the information schema (structure) that it will use in credentials of such kinds.[^1] This allows the Data Discloser to construct data objects that conform to this information schema, and present it to the 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. + +You can think of the Data Discloser as the component that pulls all data together that can be put in a credential (e.g. in a passport), and the Issuer as the component that puts the data in an (empty) passport, and signing it so as to create the actual credential. + +The 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. + +----- + +[^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. diff --git a/docs/terms/definition.md b/docs/terms/definition.md index da51aa8351ed2d4e5d6eef9c19e58aa397b31d92..ca2ae50a7dd632b04ff7c5adfd2604cec22170e2 100644 --- a/docs/terms/definition.md +++ b/docs/terms/definition.md @@ -5,12 +5,15 @@ scopeid: essifLabTerminology type: concept typeid: definition stage: draft -hoverText: "Definition: a text that helps Parties deeply/truly understand the meaning of a Term." +hoverText: "Definition: a text that helps Parties to understand the meaning of (and Concepts behind) a Term, ideally in such a way that these Parties can determine whether or not they make the same distinction." +glossaryText: "a text that helps %Parties% to understand the meaning of (and %Concepts% behind) a %Term%, ideally in such a way that these %Parties% can determine whether or not they make the same distinction." --- ### Short Description -A **Definition** is a text that helps parties truly understand the meaning of a %%term|term%% as it is used in a communication. Because [terms are scoped](terminology), this 'truly understanding' of one another isn't trivial. Therefore, we insist that the explanatory text be a criterion that parties are expected to use in the same way in some %%scope(s)|scope%%, allowing them to establish whether or not they make the same determination as to whether or not something qualifies to be refered to by that term in a way that is independent of whether or not the (alledged) meaning is relevant for the purposes they pursue within that scope. +A **Definition** is a text that helps %%parties|party%% truly understand the meaning of a %%term|term%% as it is used in a communication. Because [terms are scoped](terminology), this 'truly understanding' of one another isn't trivial. Therefore, we insist that the explanatory text be a criterion that %%parties|party%% are expected to use in the same way in some %%scope(s)|scope%%, allowing them to establish whether or not they make the same determination as to whether or not something qualifies to be refered to by that term in a way that is independent of whether or not the (alledged) meaning is relevant for the purposes they pursue within that scope. + +The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. ### Purpose @@ -37,9 +40,6 @@ Entity that comprises at a minimum: * %%Mental(or Conceptual) Model|pattern%% is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents. -### Background -The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. - ### Use-cases A Dictionary is an alphabetically sorted list of terms and explanations. Each term may have multiple such explanations, which come from different %%scopes/contexts|scope%%. +The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. + ### Purpose A dictionary helps people to get introduced in the domain for which the dictionary is created. Usually, this is a larger domain e.g. of some language, or about computer security. @@ -29,9 +32,6 @@ Examples include the [NIST Computer Security Resource Center](https://csrc.nist. - %%Glossary|glossary%% - this is a list of words with a single meaning, that serves more specific purposes than a dictionary. - [Vocabulary](https://en.wikipedia.org/wiki/Vocabulary) - this is a set of familiar words witin a particular/persons's language or field of expertise. A Dictionary can provide the various meanings of each such words. -### Background -The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. - ### Notes diff --git a/docs/terms/digital-actor.md b/docs/terms/digital-actor.md index 63d62898b8410f713421401a791809d4d3470eaa..ecdbffc320075e6933bc460bf4e496283edb0f39 100644 --- a/docs/terms/digital-actor.md +++ b/docs/terms/digital-actor.md @@ -7,6 +7,7 @@ typeid: digital-actor conceptref: ":Actor" stage: draft hoverText: "Digital Actor: an Actor in the digital world (e.g. a running app, or a web-server)." +glossaryText: "an %Actor% in the digital world (e.g. a running app, or a web-server)." --- ### Purpose diff --git a/docs/terms/digital-agent.md b/docs/terms/digital-agent.md index 08cabd2e48e29eb16498fc2259ad5c187fd3adc4..6acf5c6e3fbcfe3aab2310778625c06988ad5003 100644 --- a/docs/terms/digital-agent.md +++ b/docs/terms/digital-agent.md @@ -6,7 +6,8 @@ type: term typeid: digital-agent conceptref: ":Agent" stage: draft -hoverText: "Digital Agent: an Actor in the digital world (e.g. a running app, or a web-server) that is executing an Action for a specific Party (its Principal)." +hoverText: "Digital Agent: an Agent in the digital world (e.g. a running app, or a web-server that is executing an Action for a specific Party (its Principal))." +glossaryText: "an %Agent% in the digital world (e.g. a running app, or a web-server that is executing an %Action% for a specific %Party% (its %Principal%))." --- ### Purpose diff --git a/docs/terms/digital-colleague.md b/docs/terms/digital-colleague.md index 2ddee490e6cd2e372ec2935ab32ce228447d0af7..d8b56f7a77ae41dc9b722308d49a5c7d26f3e499 100644 --- a/docs/terms/digital-colleague.md +++ b/docs/terms/digital-colleague.md @@ -6,7 +6,8 @@ type: term typeid: digital-colleague conceptref: ":Colleague" stage: draft -hoverText: "Digital Colleague (of an Agent): any (other) Digital Agent that has the same Principal (i.e. Party on whose behalf they exeucte Actions)." +hoverText: "Digital Colleagues: two or more Digital Agents that all have the same Principal (i.e. Party on whose behalf they exeucte Actions)." +glossaryText: "two or more %Digital Agents% that all have the same %Principal% (i.e. %Party% on whose behalf they exeucte %Actions%)." --- ### Purpose diff --git a/docs/terms/digital-communication-channel.md b/docs/terms/digital-communication-channel.md new file mode 100644 index 0000000000000000000000000000000000000000..1fa6702c392c371e4f6fd06ebfccdc8216792553 --- /dev/null +++ b/docs/terms/digital-communication-channel.md @@ -0,0 +1,19 @@ +--- +id: digital-communication-channel +title: "Digital Communication Channel" +scopeid: essifLab +type: concept +typeid: digital-communication-channel +stage: draft +hoverText: "Digital Communication Channel: a digital means by which two Digital Actors can exchange messages with one another" +glossaryText: "a digital means by which two %Digital Actors% can exchange messages with one another" +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +See: %%Communication Channel|communication-channel%%. + +### Related Concepts +- %%Communication Session|communication-session%% \ No newline at end of file diff --git a/docs/terms/digital-policy.md b/docs/terms/digital-policy.md index 8bbc06992e22bb6a3836f713709a67dbccc4d94f..0a4bd064f3d53d1f46e738031c5a3bb7bcdd020a 100644 --- a/docs/terms/digital-policy.md +++ b/docs/terms/digital-policy.md @@ -6,9 +6,14 @@ type: concept typeid: digital-policy conceptref: ":Policy" stage: draft -hoverText: "Digital Policy: a machine-readable Policy (i.e. document that contains rules, working instructions or other guidance for Agents that can interpret such documents, so as to enable them to execute Actions on behalf of the Policy's author)." +hoverText: "Digital Policy (of a Party, for Action types): a machine-readable Policy that enables Digital Agents whose Principal is the Policy's Governor, to execute Actions of such types in compliance with that Policy (i.e.: according to the rules, working-instructions, preferences and other guidance specified therein)." +glossaryText: "a machine-readable %Policy% that enables %Digital Agents% whose %Principal% is the %Policy%'s %Governor%, to execute %Actions% of such types in compliance with that %Policy% (i.e.: according to the rules, working-instructions, preferences and other guidance specified therein)." --- +:::info Editor's note +TNO (or others) to provide further content of this file. +::: + ### Short Description A **digital policy** is an artifact that is derived from, and represents, a %%policy|policy%% for the purpose of being useable in the digital realm. diff --git a/docs/terms/documentation-interop.md b/docs/terms/documentation-interop.md new file mode 100644 index 0000000000000000000000000000000000000000..bc547494507b5acda870b08278b6b553fd123e71 --- /dev/null +++ b/docs/terms/documentation-interop.md @@ -0,0 +1,16 @@ +--- +id: documentation-interop +title: "Documentation Interoperability" +scopeid: essifLab +type: concept +typeid: documentation-interop +stage: draft +hoverText: "Documentation Interoperability: the property that a documentation system of making its content comprehensible for a variety of people that come from different backgrounds." +glossaryText: "the property that a documentation system of making its content comprehensible for a variety of people that come from different backgrounds." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +### Related Concepts diff --git a/docs/terms/eSSIFLab-scope.md b/docs/terms/eSSIFLab-scope.md index d06c08c802f6b823dbb234ac58d9fa81f57b3bba..410755e03aaea2cd6d05ac4a6fbcd8447c394d6d 100644 --- a/docs/terms/eSSIFLab-scope.md +++ b/docs/terms/eSSIFLab-scope.md @@ -6,6 +6,7 @@ type: scope typeid: eSSIFLab stage: draft hoverText: "ESSIFLab: specification of the eSSIF-Lab scope." +glossaryText: "specification of the eSSIF-Lab scope." --- ### Governance @@ -28,19 +29,3 @@ The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community pa ### Background The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. - -### Notes - - -### Tags - - - diff --git a/docs/terms/employee.md b/docs/terms/employee.md index f4763661a81231bb13e09e012471450d06f2cc7b..1faae2b016fee28267dd75e99cbdd59c7c839528 100644 --- a/docs/terms/employee.md +++ b/docs/terms/employee.md @@ -5,14 +5,18 @@ scopeid: essifLab type: concept typeid: employee stage: draft -hoverText: "Employee (of a Party): an Actor for whom/which it is realistic that it might execute Actions on behalf of that Party." +hoverText: "Employee (of a Party): an Actor for whom/which it is realistic that it might execute Actions on behalf of that Party (called the Employer of that Actor)." +glossaryText: "an %Actor% for whom/which it is realistic that it might execute %Actions% on behalf of that %Party% (called the %Employer% of that %Actor%)." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: -### Background +### Short Description + The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. -### Related Concepts +### Purpose + +### Criteria diff --git a/docs/terms/employer.md b/docs/terms/employer.md index 1f40d06ff7406dfa06f85afa5a480e8ba48540b4..f14403b3f196144276c06c4135822d096170e049 100644 --- a/docs/terms/employer.md +++ b/docs/terms/employer.md @@ -5,14 +5,18 @@ scopeid: essifLab type: concept typeid: employer stage: draft -hoverText: "Employer (of an Actor): a Party on whose behalf this Actor might execute Ations." +hoverText: "Employer (of an Actor): a Party on whose behalf this Actor (called an Employee of that Party) might execute Actions." +glossaryText: "a %Party% on whose behalf this %Actor% (called an %Employee% of that %Party%) might execute %Actions%." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: -### Background +### Short Description + The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. -### Related Concepts +### Purpose + +### Criteria diff --git a/docs/terms/entity.md b/docs/terms/entity.md index 21afc3d26d17b256010a865ac955b9a61bd0c6c2..fa7ceb028cf67d8d65cbb5562136b5565177a226 100644 --- a/docs/terms/entity.md +++ b/docs/terms/entity.md @@ -6,11 +6,14 @@ type: concept typeid: entity stage: draft hoverText: "Entity: something that is known to exist." +glossaryText: "something that is known to exist." --- ### Short Description Whenever you know that somethings exists, be it another person, yourself, some computer, an extinct animal, a thought, an idea, a JSON-object, ..., _anything_ you can think of, is what the term **Entity** refers to. +The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. + ### Purpose This term enables us to refer to anything, or to postulate the existence of something, without further specifying what it is, or how it might be named. @@ -18,7 +21,4 @@ This term enables us to refer to anything, or to postulate the existence of some Something, anything, that some %%party|party%% knows to exist ### Related Concepts -- a %%legal entity|legal-entity%% is an entity that is known by (i.e. registered in the %%knowledge|knowledge%% of) a %%party|party%% that operates the %%legal-system|legal-system%% of a %%jurisdiction|jurisdiction%%. (Details are in the %%jurisdiction pattern|pattern-jurisdiction%%) - -### Background -The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. +- a %%legal entity|legal-entity%% is an entity that is known by (i.e. registered in the %%knowledge|knowledge%% of) a %%party|party%% that operates the %%legal system|legal-system%% of a %%jurisdiction|jurisdiction%%. (Details are in the %%Jurisdictions pattern|pattern-jurisdiction%%) diff --git a/docs/terms/essif-glue.md b/docs/terms/essif-glue.md index 1ce38a8490b24afb2ad57e9f0bcafdcd58383aff..1d3b48a1434889bb7167998598d172a94a8c9c07 100644 --- a/docs/terms/essif-glue.md +++ b/docs/terms/essif-glue.md @@ -5,16 +5,17 @@ scopeid: essifLab type: concept typeid: essif-glue stage: draft -hoverText: "eSSIF-Glue: interface layer that allows components with TVE and/or TRD functionality to use the Wallet, Holder, Issuer and Verifier functionalities." +hoverText: "eSSIF-Glue: interface layer that allows components with Transaction Data Collector and/or Transaction Data Discloser functionality to use the Wallet, Holder, Issuer and Verifier functionalities." +glossaryText: "interface layer that allows components with %Transaction Data Collector% and/or %Transaction Data Discloser% functionality to use the %Wallet%, %Holder%, %Issuer% and %Verifier% functionalities." --- ### Short Description -The **eSSIF-Glue** is an interface layer that consists of a documented set of APIs between the %%TVE|tve%% and %%TRD|trd%% on the one hand, and the Wallet, Holder, Issuer and Verifier (WHIV) components on the other hand. +The **eSSIF-Glue** is an interface layer that consists of a documented set of APIs between the %%Transaction Data Collector|transaction-data-collector%% and %%Transaction Data Discloser|transaction-data-discloser%% on the one hand, and the Wallet, Holder, Issuer and Verifier (WHIV) components on the other hand. - 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. + 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|party%% can then select such WHIV components as they see fit. ### Purpose -The purpose of the essif-Glue APIs is to make calling the WHIV functions as simple as possible, given the functions of the %%TVE|tve%% and %%TRD|trd%% +The purpose of the essif-Glue APIs is to make calling the WHIV functions as simple as possible, given the functions of the %%Transaction Data Collector|transaction-data-collector%% and %%Transaction Data Discloser|transaction-data-discloser%% ### Criterion The set of API's described at https://gitlab.grnet.gr/essif-lab/tno-ssi-service/developer-docs. diff --git a/docs/terms/glossary-file.md b/docs/terms/glossary-file.md index 3fde8a92911523808262a0d9fc3c377391c6109f..74799b0e1e2b09ac62f37cb79ded9fb2f801b500 100644 --- a/docs/terms/glossary-file.md +++ b/docs/terms/glossary-file.md @@ -5,7 +5,8 @@ scopeid: essifLab type: glossary typeid: glossary-file stage: draft -hoverText: "Glossary-file: a file that defines/specifies a Glossary." +hoverText: "Glossary-file: a file whose contents defines/specifies a Glossary." +glossaryText: "a file whose contents defines/specifies a %Glossary%." --- ### Short Description diff --git a/docs/terms/glossary.md b/docs/terms/glossary.md index 21f11dd43eca423eac02a693212121565fda886d..e344821575621b4e82e52b6187e49779d7cfae91 100644 --- a/docs/terms/glossary.md +++ b/docs/terms/glossary.md @@ -5,43 +5,27 @@ scopeid: essifLabTerminology type: concept typeid: glossary stage: draft -hoverText: "Glossary: an alphabetically sorted list of Terms with explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s)." +hoverText: "Glossary: an alphabetically sorted list of Terms with the (single) meaning it has in (at least) one context." +glossaryText: "an alphabetically sorted list of %Terms% with the (single) meaning it has in (at least) one context." --- ### Short Description - -A **glossary** is an alphabetically sorted list of %%terms|term%% with explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s). However, a glossary may also be created for the purpose of being included in other glossaries (as a construction aid to such glossaries), or for still other purposes. +A **glossary** is an alphabetically sorted list of %%terms|term%% with explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in (at least) one context. A glossary may also be created for the purpose of being included in other glossaries (as a construction aid to such glossaries), or for still other purposes. + +The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. ### Purpose - A glossary may serve various purposes, the most important one of which would be to help people understand texts around a certain (set of) topic(s) in some context(s). ### Criteria - A **glossary** is an alphabetical list of words or phrases with (short) explanations, that exists for the purpose of helping people to get a first understanding of the meaning of each word in the scope/context for which the glossary is created. ### Examples - Examples include the [eSSIF-Lab Glossary](../essifLab-glossary), the [Sovrin Glossary](https://sovrin.org/library/glossary/), the [Glossary of Internet Terms](https://www.internetsociety.org/internet/glossary-internet-terms/), and glossaries for Legal Terms, e.g. of the [US](https://www.uscourts.gov/glossary), [Singapore](https://www.supremecourt.gov.sg/services/self-help-services/glossary-of-terms), the [UK](https://www.copfs.gov.uk/involved-in-a-case/glossary-of-legal-terms). ### Related Concepts - - %%Dictionary|dictionary%% - this is more extensive; it usually includes multiple meanings of words, and may include additional information e.g. on pronunciation, etymology, usage, example sentences,synonyms, etc. See [askdifference.com](https://www.askdifference.com/dictionary-vs-glossary/) - [Vocabulary](https://en.wikipedia.org/wiki/Vocabulary) - this is a set of familiar words witin a particular/persons's language or field of expertise. A Dictionary can provide the various meanings of each such words. -### Background -The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. - ### Notes - -The [eSSIF-Lab Glossary](../essifLab-glossary) contains the words that are defined within the scope of the [eSSIF-Lab framework](../introduction). - - \ No newline at end of file +The [eSSIF-Lab Glossary](../essifLab-glossary) contains the words that are defined within the scope of the [eSSIF-Lab framework](../project). \ No newline at end of file diff --git a/docs/terms/governance.md b/docs/terms/governance.md new file mode 100644 index 0000000000000000000000000000000000000000..a003857d9b8fcf5c9c77744071395ce99b5051a1 --- /dev/null +++ b/docs/terms/governance.md @@ -0,0 +1,39 @@ +--- +id: governance +title: "Governance" +scopeid: essifLab +type: concept +typeid: governance +stage: draft +hoverText: "Governance: the act or process of governing or overseeing the control and direction of something (Merriam-Webster)." +glossaryText: "the act or process of governing or overseeing the control and direction of something (Merriam-Webster)." +--- + +### Short Description +**Governance** is the act (executed by, or behalf of some %%party|party%%) or process (of some %%party|party%%) of governing or overseeing the control and direction of something ([Merriam-Webster](https://www.merriam-webster.com/dictionary/governance)). The governance of a %%party|party%% is embodied by the set of processes by which it decides how to make (other) decisions, how %%actors|actor%% that it %%employs|employee%% are to behave and operate, and ensure this guidance ends up in documents (which we will call %%policies|policy%%). + +As %%parties|party%% interact with one another, i.e. conduct %%business transactions|business-transaction%%, they need to decide whether or not to commit to a transaction proposal. Deciding about how to make such a decision is one of the subjects of the governance process of that %%party|party%%: it is establishing the kind of argument that may be used to make this decision. + +Within eSSIF-Lab, governance is pretty much limited to the governance of various %%policies|policy%%. + +The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. + +### Purpose +The purpose for a %%party|party%% of having a **governance** process is that it enables him to reflect on the ways that it makes decisions. A typical topic for governance is the maintenance of the set of rules, working-instructions, preferences and other guidance that %%actors|actor%% are supposed, or required to use when executing specific %%actions|action%% on behalf of that %%party|party%%. + +For %%digital-actors|digital-actor%% such guidance consists of %%digital policies|digital-policy%%. A %%party|party%% whose governance process maintains a %%policy|policy%% will be called the %%governor|policy-governor%% of that policy. + +### Related Concepts +- %%Governance|governance%% +- %%Governor|policy-governor%% +- %%Policy|policy%% +- %%Digital Policy|digital-policy%% +- %%Transaction Data Discloser Policy|transaction-data-collector-policy%% +- %%Transaction Data Collector Policy|transaction-data-collector-policy%% +- %%Verifier Policy|verifier-policy%% +- %%Issuer Policy|issuer-policy%% +- %%Holder Policy|holder-policy%% +- %%Wallet Policy|wallet-policy%% +:::info Editor's note +TNO (or others) to provide additional content of this file. +::: diff --git a/docs/terms/governor.md b/docs/terms/governor.md new file mode 100644 index 0000000000000000000000000000000000000000..df398b16ac411d683ad55ea2a5c2065730000453 --- /dev/null +++ b/docs/terms/governor.md @@ -0,0 +1,15 @@ +--- +id: governor +title: "Governor" +scopeid: essifLab +type: concept +typeid: governor +stage: draft +hoverText: "Governor: the role that a Party assumes as it is governing or overseeing the control and direction of something." +glossaryText: "the role that a %Party% assumes as it is governing or overseeing the control and direction of something." +--- + +### Short Description +A **Governor** is a name used to refer to a Party that is governing or overseeing the control and direction of something. + +See %%governance|governance%% \ No newline at end of file diff --git a/docs/terms/guardian.md b/docs/terms/guardian.md new file mode 100644 index 0000000000000000000000000000000000000000..baa0cd230a5a64c1c696bd68db04f7596979fef5 --- /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." +glossaryText: "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 + +The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts. + +### Purpose + +### Criteria diff --git a/docs/terms/guardianship-type.md b/docs/terms/guardianship-type.md new file mode 100644 index 0000000000000000000000000000000000000000..731b7c5702c7ee688c4e79d2c94efe711f100129 --- /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." +glossaryText: "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. + +The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts. + +### 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%%. diff --git a/docs/terms/guardianship.md b/docs/terms/guardianship.md new file mode 100644 index 0000000000000000000000000000000000000000..0815682e1d178a74543c1a63a2728398538f1603 --- /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 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." +glossaryText: "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%%'. + +The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts. + +### 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. \ No newline at end of file diff --git a/docs/terms/holder-policy.md b/docs/terms/holder-policy.md index df02f7c0b6f59873adcc2064e20ea8b39d6a5ff1..58bd5809a027273b7726accc49b7a9ff5235f960 100644 --- a/docs/terms/holder-policy.md +++ b/docs/terms/holder-policy.md @@ -6,10 +6,11 @@ type: concept typeid: holder-policy stage: draft hoverText: "Holder Policy: a Digital Policy that enables an operational Holder component to function according to the rules of its Policy Governor." +glossaryText: "a %Digital Policy% that enables an operational %Holder% component to function according to the rules of its %Policy Governor%." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: ### Related Concepts diff --git a/docs/terms/holder.md b/docs/terms/holder.md index 529ab71cd9b9665b7e92c4741e20426087bc233d..2f773f75268bec5e9e6189161adfde2f5e2c1a7c 100644 --- a/docs/terms/holder.md +++ b/docs/terms/holder.md @@ -6,26 +6,31 @@ type: concept typeid: holder stage: draft hoverText: "Holder (functional component): the capability to handle presentation requests from a Peer Agent, produce the requested data (a presentation) according to its Principal's holder-policy, and send that in response to the request." +glossaryText: "the capability to handle presentation requests from a %Peer Agent%, produce the requested data (a presentation) according to its %Principal%'s holder-policy, and send that in response to the request." --- -## Short Description -A **Holder** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that handles %%Presentation Requests|presentation-request%% that it receives from %%verifier|verifier%% components (of other %%parties|party%%, but also of its own %%owner|owner%%). Typically, this means looking for the requested data in the Owner’s %%wallet|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|issuer%% for the purpose of obtaining the needed credential, which - when obtained - it can subsequently store in the wallet and use in the Presentation. +### Short Description +A **Holder** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that handles %%Presentation Requests|presentation-request%% that it receives from %%verifier|verifier%% components (of other %%parties|party%%, but also of its own %%owner|owner%%). Typically, this means looking for the requested data in the Principal’s %%wallet|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|issuer%% for the purpose of obtaining the needed credential, which - when obtained - it can subsequently store in the wallet and use in the Presentation. -## Purpose +:::info Editor's note +TNO (or others) to provide additional content of this file. +::: + +### Purpose The purpose of the Holder component is to handle Presentation Requests that it receives from %%verifier|verifier%% components (both of its own %%owner|owner%%, and of other %%parties|party%%), and responding to such requests. -## Criteria +### Criteria A **Holder** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whose function is to handle Presentation Requests that it receives from %%verifier|verifier%% components (both of its %%owner|owner%%, and of other %%Parties|party%%). -## Functionality +### Functionality Typically, a Holder component would access its %%owner|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. -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 TVE 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 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 Principal’s Transaction 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 Principal’s Wallet, and then proceed to service the presentation request as if it had obtained that credential from its Principal’s 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. -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 component work, a Holder Policy/Preferences object is created by, or on behalf of its 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); diff --git a/docs/terms/identifier.md b/docs/terms/identifier.md new file mode 100644 index 0000000000000000000000000000000000000000..bbac987832b336ca0d5e2ddf2293554a882f09cf --- /dev/null +++ b/docs/terms/identifier.md @@ -0,0 +1,42 @@ +--- +id: identifier +title: "Identifier" +scopeid: essifLab +type: concept +typeid: identifier +stage: draft +hoverText: "Identifier: a character string that is being used for the identification of some Entity (yet may refer to 0, 1, or more Entities, depending on the context within which it is being used)." +glossaryText: "a character string that is being used for the identification of some %Entity% (yet may refer to 0, 1, or more %Entities%, depending on the context within which it is being used)." +--- + +### Short Description +An **Identifier** is a character string that is being used for identification purposes (by a specific %%party|party%%).[^1] This includes names and labels, as they are (obviously) used for such purposes. + +Note that while an identifier is used for identification purposes, this does not automatically imply that it actually identifies (singles out) anything. It also depends on what [RFC 3986](https://tools.ietf.org/html/rfc3986) calls the 'scope of identification', or what [Pfitzmann and Hansen](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) refer to as an 'identifiability set', which are relevant for explaining whether or not (and if so: what) an identifier actually identifies (singles out) in a given context. See the [Discussion](./identifier#discussion---scope-of-identification) below. + +### Purpose +%%Parties|party%% have a need to reason about %%things|entity%% they %%know|knowledge%% to exist, which requires them to have a conscious representation of such things, as well as the ability to identify (single) out individual entities. One way to do that is to tag an entity with a character string (label, name), that would then qualify as an identifier. + +Also, identifiers may serve identification purpose in communications between different %%parties|party%%, the idea being that when one %%party|party%% mentions an identifier (that identifies some %%entity|entity%% for this %%party|party%% ) to another %%party|party%%, the latter would be able to determine the %%entity|entity%% that the first is talking about. See the [Discussion](./identifier#discussion---scope-of-identification) below. + +### Criterion +An **Identifier** is a character string that is being used for identification purposes by a specific %%party|party%%. + +### Examples +The following strings are examples: 'localhost', 'https://localhost/', 'Trust over IP community', 'the mayor of New York', 'guardianship', 'my mother', 'did:sov:2wJPyULfLLnYTEFYzByfUR', 'did:sov:2wJ', 'issue #24', etc., etc. + +### Discussion - Scope of Identification +[RFC 3986, Section 1.1.](https://tools.ietf.org/html/rfc3986#section-1.1) states _"an identifier embodies the information required to distinguish what is being identified from all other things within its **scope of identification"**_. This statement suggests that identifiers (URIs) have a single scope, supposedly specified by "_the URI schemes and naming authority (if any)_". However, there is no such requirement, and there is nothing in place to guarantee this (apart from IANA, many other (sometimes even very commonly used) URI schemes exist). [Pfitzmann and Hansen](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) (section 13.2) use the term 'identifiability sets' rather than 'scope of identification', and describe how 'attackers' - but that could equally well have been regular users - each have, or construct their own scope, and use contextual information to do so. + +The criterion that makes a text string qualify as an identifier doesn't seem to cut it, as only _using_ a text for identification purposes doesn't make it have (what we will call) the 'identification property', i.e. the property that it _actually_ identifies something. It may only have that property in combination with an associated (single) scope of identification, which may depend on the context in which it is being used. [RFC 2986, page 6](https://tools.ietf.org/html/rfc3986#page-6) illustrates this using the identifier "http://lcoalhost/". + +The lack of (identifying) scopes of identification becomes an issue when a %%party|party%% (say Alice) sends the identifier (e.g. `my car`) to another %%party|party%% (say Bob), expecting that Bob will then be able to identify the same %%entity|entity%% that she identifies with it (presumably some specific car). + +If Bob had just met Alice for the first time, and hadn't seen her coming in a car, then Alice must acquaint Bob with the existence of the %%entity|entity%% that she refers to with `my car`, e.g. by pointing her finger to it, or describing the make, brand and license plate or some other characteristic that allows Bob to single out her car (in the context of their meeting one another). Then, Bob can 'register' the existence of that car in his %%knowledge|knowledge%% (optionally tagging it with an identifier of his own, e.g. `Alice's car`), and associate it with the attribute (party='Alice', identifier='`my car`'). It is important to have the "party='Alice'" part in there, because other parties, (e.g. Carol) may also use an identifier `my car`, which would and should then refer to another car. This shows that the scope of interpretation for an identifier has to do with the (%%knowledge|knowledge%% of) %%parties|party%% that use it, and that understanding the intended meaning requires a proper identification of that scope. + +----- +[^1]: This is the definition of [RFC 3986, Section 1.1.](https://tools.ietf.org/html/rfc3986#section-1.1) but without the requirement of complying with URI syntax constraints. Note that there is consensus in the literature about this. For example, [(Allen, 2016)](http://www.lifewithalacrity.com/2016/04/the-path-to-self-soverereign-identity.html) defines ‘Identifier’ as “A name or other label that uniquely identifies an identity.”. [Pfitzmann and Hansen, 2010](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) say (in footnote 57): “A name or another bit string”. The [DID-core specification](https://www.w3.org/TR/did-core/) of W3C [defines ‘decentralized identifiers’ as specializations of URIs](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers). + +[^2]: While Pfitzmann and Hansen talk about 'attackers', it is trivial to also include 'non-attackers', i.e. your average user. + +[^3]: diff --git a/docs/terms/issuer-policy.md b/docs/terms/issuer-policy.md index 620d1f3615732df7598904e4b7bf73f361ab8dd4..4d1ae8387bf2be17a9a7dd53859e4b0a57c19116 100644 --- a/docs/terms/issuer-policy.md +++ b/docs/terms/issuer-policy.md @@ -6,10 +6,11 @@ type: concept typeid: issuer-policy stage: draft hoverText: "Issuer Policy: a Digital Policy that enables an operational Issuer component to function according to the rules of its Policy Governor." +glossaryText: "a %Digital Policy% that enables an operational %Issuer% component to function according to the rules of its %Policy Governor%." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: ### Related Concepts diff --git a/docs/terms/issuer.md b/docs/terms/issuer.md index 366f7f221ef249eb7e4b6571d3ee97915dca92a6..865c480f1c2ca097056ed21c51a88b7112d6eedb 100644 --- a/docs/terms/issuer.md +++ b/docs/terms/issuer.md @@ -5,30 +5,34 @@ scopeid: essifLab type: concept typeid: issuer stage: draft -hoverText: "Issuer (functional component): the capability to construct Credentials from data objects, according to the rules of its Principal's issuer-policy (specifically regarding the way in which the Credential is to be digitally signed), and pass it to the Wallet-component of its Principal allowing it to be issued." +hoverText: "Issuer (functional component): the capability to construct Credentials from data objects, according to the content of its Principal's Issuer-Policy (specifically regarding the way in which the Credential is to be digitally signed), and pass it to the Wallet-component of its Principal allowing it to be issued." +glossaryText: "the capability to construct %Credentials% from data objects, according to the content of its %Principal%'s %Issuer%-Policy (specifically regarding the way in which the %Credential% is to be digitally signed), and pass it to the %Wallet%-component of its %Principal% allowing it to be issued." --- -## Short Description -An **issuer** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that structures sets of (related) statements/claims (e.g. as produced by the %%TRD|trd%%) in a packate, adds metadata which includes e.g. a timestamp at which this was done, ensures that it is digitally signed on behalf of its %%owner|owner%%, 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. +:::info Editor's note +TNO (or others) to provide additional content of this file. +::: +### Short Description +An **issuer** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that structures sets of (related) statements/claims (e.g. as produced by the %%Transaction Data Discloser|transaction-data-discloser%%) in a package, adds metadata which includes e.g. a timestamp at which this was done, ensures that it is digitally signed on behalf of its %%owner|owner%% (so that third %%parties|party%% 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. -## Purpose +### Purpose The purpose of the Issuer function is. -## Criteria +### Criteria A **Issuer** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whose function is to ... (tbd). -## Functionality +### Functionality The purpose of the Issuer component is to issue ‘credentials’, i.e. digital constructs that contain -- sets of (related) statements or claims (e.g. as produced by the TRD) +- sets of (related) statements or claims (e.g. as produced by the Transaction 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. +- 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 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 Principal. 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 Principal should make, and specify in the 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|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 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|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|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). 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] diff --git a/docs/terms/jurisdiction-governor.md b/docs/terms/jurisdiction-governor.md new file mode 100644 index 0000000000000000000000000000000000000000..2ecdfc7214bed7348553be01c1ed58165ac98543 --- /dev/null +++ b/docs/terms/jurisdiction-governor.md @@ -0,0 +1,15 @@ +--- +id: jurisdiction-governor +title: "Governor (of a Jurisdiction)" +scopeid: essifLab +type: concept +typeid: jurisdiction-governor +stage: draft +hoverText: "Governor (of a Jurisdiction): the Party that operates the Legal System of that Jurisdiction." +glossaryText: "the %Party% that operates the %Legal System% of that %Jurisdiction%." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + diff --git a/docs/terms/jurisdiction.md b/docs/terms/jurisdiction.md index 24cf498e0f3dd4b9705bfca85d0e8696183a87d7..94b1112f288a7cdb278cf4d31fc23fc660825050 100644 --- a/docs/terms/jurisdiction.md +++ b/docs/terms/jurisdiction.md @@ -5,39 +5,20 @@ scopeid: essifLab type: concept typeid: jurisdiction stage: draft -hoverText: "Jurisdiction: a Legal System (legislation, enforcement thereof, and conflict resolution) that is operated by a Party in a certain Scope." +hoverText: "Jurisdiction: the composition of a Legal System (legislation, enforcement thereof, and conflict resolution), a Party that governs that Legal System, a scope within which that Legal System is operational, and one or more Objectives for the purpose of which the Legal System is operated." +glossaryText: "the composition of a %Legal System% (legislation, enforcement thereof, and conflict resolution), a %Party% that governs that %Legal System%, a scope within which that %Legal System% is operational, and one or more %Objectives% for the purpose of which the %Legal System% is operated." --- ### Short Description - -A **Jurisdiction** is the composition of one %%scope|scope%%, one %%legal system|legal-system%% and one %%party|party%% that operates the legal system within that scope. While most people are familiar with what we call %%legal jurisdictions|legal-jurisdiction%%, please observe that %%organizations|organization%% habitually will have rules (business policies) in place, enforce them (to some extent), and have ways of resolving conflicts, and therefore qualify as a jurisdiction. Specifically, multi-national organizations are known to operate multiple jurisdictions, aliging the scopes with the scopes of other (often legal) jurisdictions for the purpose of preventing situations in which conflicting rules apply, which would lead to many effort-intensive conflict-resolution cases. +A **Jurisdiction** is the composition of a (non-empty) set of %%objectives|objective%%, one %%scope|scope%%, one %%legal system|legal-system%% and one %%party|party%% (called the %%Governor of the Jurisdiction|jurisdiction-governor%%) that operates the legal system within that scope. While most people are familiar with what we call %%legal jurisdictions|legal-jurisdiction%%, please observe that %%organizations|organization%% habitually will have rules (business policies) in place, enforce them (to some extent), and have ways of resolving conflicts, and therefore qualify as a jurisdiction. Specifically, multi-national organizations are known to govern multiple jurisdictions, aliging the scopes with the scopes of other (often legal) jurisdictions for the purpose of preventing situations in which conflicting rules apply, which would lead to many effort-intensive conflict-resolution cases. + +The %%Jurisdictions pattern|pattern-jurisdiction%% provides an overview of how this concept fits in with related concepts. ### Purpose - The ability to distinguish between (non)jurisdictions is a very generic enabler for us to tell which rules (laws, policies, guidelines, etc.) will apply in which situations, which %%party|party%% governs and enforces these rules, and where we should look to resolve any conflicts. ### Criteria the composition of one %%scope|scope%%, one %%legal system|legal-system%% and one %%party|party%% that operates the legal system within that scope. -### Examples - - -### Related Concepts - - -### Background - -The %%jurisdiction pattern|pattern-jurisdiction%% provides an overview of how this concept fits in with related concepts. - ### Notes - - - +The case can be made for Nature to qualify as a jurisdiction, postulating that this jurisdiction has a universal scope, its %%party|party%% would be 'Nature' itself (which can be argued to qualify as a %%party|party%%), and the %%legal system|legal-system%% that Nature operates are the 'laws of nature' (which Nature defines, enforces and settles disputes in). If one adopts this view, then people become (natural) %%owners|owner%% of e.g. %%assertions|assertion%%, their %%knowledge|knowledge%% etc. Also, natural resources (e.g. rivers) would be %%legal entities|legal-entity%% in that jurisdiction, since they are 'known, and recognized to exist' by Nature. diff --git a/docs/terms/knowledge-governor.md b/docs/terms/knowledge-governor.md new file mode 100644 index 0000000000000000000000000000000000000000..3186411ada80ddba8940ff42d367758549aa6d88 --- /dev/null +++ b/docs/terms/knowledge-governor.md @@ -0,0 +1,15 @@ +--- +id: knowledge-governor +title: "Governor (of a Knowledge)" +scopeid: essifLab +type: concept +typeid: knowledge-governor +stage: draft +hoverText: "Governor (of a Knowledge): the Party that is 1-1 associated with that knowledge." +glossaryText: "the %Party% that is 1-1 associated with that knowledge." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + diff --git a/docs/terms/knowledge.md b/docs/terms/knowledge.md index 86a15ef8be41c4ca74df605d911ad59ebc89174b..fac293929f29caee78c72bb6e9462e486cf5e871 100644 --- a/docs/terms/knowledge.md +++ b/docs/terms/knowledge.md @@ -6,6 +6,7 @@ type: concept typeid: knowledge stage: draft hoverText: "Knowledge: The (intangible) sum of what is known by a specific Party, as well as the familiarity, awareness or understanding of someone or something by that Party." +glossaryText: "The (intangible) sum of what is known by a specific %Party%, as well as the familiarity, awareness or understanding of someone or something by that %Party%." --- ### Short Description @@ -14,12 +15,12 @@ hoverText: "Knowledge: The (intangible) sum of what is known by a specific Party We limit the scope of a Knowledge to a %%party|party%% so as to allow for the existence of multiple such Knowledges, where each of them is internally consistent, yet may be inconsistent with other Knowledges. ### Purpose -We need a term to refer to the (intangible) sum of what is known, the familiarity, awareness or understanding of someone or something of a %%party|party%%, because this is what allows the party to reason, and make decisions. When a party can successfully share (parts of) its knowledge, i.e. communicate it such that when another party interpret it, the intension is preserved, mutual understanding is achieved, which is prerequisite for doing business transactions and/or collaborating. +We need a term to refer to the (intangible) sum of what is known, the familiarity, awareness or understanding of someone or something of a %%party|party%%, because this is what allows the %%party|party%% to reason, and make decisions. When a %%party|party%% can successfully share (parts of) its knowledge, i.e. communicate it such that when another %%party|party%% interpret it, the intension is preserved, mutual understanding is achieved, which is prerequisite for doing %%business transactions|business-transaction%% and/or collaborating. ### Criterion -The intangible sum of what is known to some %%party|party%%, as well as the familiarity, awareness or understanding of someone or something by that party. +The intangible sum of what is known to some %%party|party%%, as well as the familiarity, awareness or understanding of someone or something by that %%party|party%%. ### Notes -- 'A knowledge' is 1-1 associated with a %%party|party%% (in a way, each knowledge defines that party). -- a knowledge includes the rules that its party has decided constitutes valid [Logics](https://en.wikipedia.org/wiki/Logic) (i.e. rules for reasoning). Such logics are usually not [formal](https://en.wikipedia.org/wiki/Formal_system), or [mathematical logics](https://en.wikipedia.org/wiki/Mathematical_logic). +- 'A knowledge' is 1-1 associated with a %%party|party%% (in a way, each knowledge defines that %%party|party%%). +- a knowledge includes the rules that its %%party|party%% has decided constitutes valid [Logics](https://en.wikipedia.org/wiki/Logic) (i.e. rules for reasoning). Such logics are usually not [formal](https://en.wikipedia.org/wiki/Formal_system), or [mathematical logics](https://en.wikipedia.org/wiki/Mathematical_logic). - In order for reasoning with, or transferring Knowledge, it must be made explicit, e.g. in writing, speech, digitally or otherwise. The mapping of knowledge onto such representations is called ‘[semantics](https://en.wikipedia.org/wiki/Semantics)’. Every %%party|party%% determines which semantics it chooses to use. diff --git a/docs/terms/legal-entity.md b/docs/terms/legal-entity.md index f08680cc2b5291770f16b4a20974a7727881169f..2d56007189f2bbfd523349dd75298eb8265d5cd9 100644 --- a/docs/terms/legal-entity.md +++ b/docs/terms/legal-entity.md @@ -5,13 +5,16 @@ scopeid: essifLab type: term typeid: legal-entity stage: draft -hoverText: "Legal-entity: an Entity that is known by and recognized to exist in a Jurisdiction." +hoverText: "Legal Entity (of a Jurisdiction): an Entity that is known by, recognized to exist, and registered in that Jurisdiction." +glossaryText: "an %Entity% that is known by, recognized to exist, and registered in that %Jurisdiction%." --- ### Short Description A **Legal Entity** is an %%entity|entity%% that is known by and recognized to exist in a %%jurisdiction|jurisdiction%%. For %%legal jurisdictions|legal-jurisdiction%%, this usually means that the entity is registered. Legal jurisdictions usually have a registration for its citizens, foreigners, enterprises, fellonies, etc. Non-legal jurisdictions (e.g. a soccer club) register their members, donators, staff, properties, etc., either on the record, or off the record. +The %%Jurisdictions pattern|pattern-jurisdiction%% provides an overview of how this concept fits in with related concepts. + ### Purpose It is important to recognize that the term 'legal entity' does not refer to something that has an existence of its own, but that it is a property of en %%entity|entity%% that is linked to a %%jurisdiction|jurisdiction%%. This enables us to query for the applicable jurisdiction when someone uses the term, and get the right understanding of what (s)he means. @@ -24,7 +27,3 @@ A **Legal Entity** is an %%entity|entity%% that is known by and recognized to ex - citizens (organizations, etc.) that are registered in the citizens registration of some government, are legal entities in its jurisdiction. - a refugee that is screaming before a civil servant person (i.e. (s)he is alive and kicking, and really exists), yet is not registered in the governmental administration, does not exist for that administration, i.e. is not a legal entity in that jurisdiction. - whether or not some special stone qualifies as legal entity depends on whether or not it is known to exist in some jurisdiction. - -### Background - -The %%jurisdiction pattern|pattern-jurisdiction%% provides an overview of how this concept fits in with related concepts. diff --git a/docs/terms/legal-jurisdiction.md b/docs/terms/legal-jurisdiction.md index 95beb53120db497d70a48bc01ac291d61acbd2ee..451daa6bed288313ea558e60901a52283814345d 100644 --- a/docs/terms/legal-jurisdiction.md +++ b/docs/terms/legal-jurisdiction.md @@ -6,13 +6,18 @@ type: term typeid: legal-jurisdiction conceptref: essifLab:jurisdiction stage: draft -hoverText: "Legal Jurisdiction: a Jurisdiction that is operated by a governmental body." +hoverText: "Legal Jurisdiction: a Jurisdiction that is governed/operated by a governmental body." +glossaryText: "a %Jurisdiction% that is governed/operated by a governmental body." --- +### Short Description + +::: Editor's note +TNO to provide further context +::: + +The %%Jurisdictions pattern|pattern-jurisdiction%% provides an overview of how this concept fits in with related concepts. + ### Purpose -We need the term **legal jurisdiction** because it is common practice for people and organizations to explicitly want to comply with applicable laws and regulations, where it is explicitly implied that these are the rules of a legal system that is governed by a governmental body. Introducing this term allows us to both generically reason about %%jurisdictions|jurisdiction%% (which is helpful to design e.g. SSI infrastructure) and also communicate about jurisdictions that have a governmental (legal) status. - -### Background - -The %%jurisdiction pattern|pattern-jurisdiction%% provides an overview of how this concept fits in with related concepts. +We need the term **legal jurisdiction** because it is common practice for people and organizations to explicitly want to comply with applicable laws and regulations, where it is explicitly implied that these are the rules of a legal system that is governed by a governmental body. Introducing this term allows us to both generically reason about %%jurisdictions|jurisdiction%% (which is helpful to design e.g. SSI infrastructure) and also communicate about jurisdictions that have a governmental (legal) status. \ No newline at end of file diff --git a/docs/terms/legal-system.md b/docs/terms/legal-system.md index 8b78580f09de08d9b3268ca553cbd40c74617308..3fdbe365883d79f011e1c112e76c622e0b8c90e0 100644 --- a/docs/terms/legal-system.md +++ b/docs/terms/legal-system.md @@ -6,28 +6,24 @@ type: concept typeid: legal-system stage: draft hoverText: "Legal-system: a system in which rules are defined, and mechanisms for their enforcement and conflict resolution are (implicitly or explicitly) specified." +glossaryText: "a system in which rules are defined, and mechanisms for their enforcement and conflict resolution are (implicitly or explicitly) specified." --- ### Short Description - -A **Legal System** is a system in which rules are defined ([legislature](https://en.wikipedia.org/wiki/Legislature)) and a mechanism for their enforcement is implicitly or explicitly defined ([executive](https://en.wikipedia.org/wiki/Executive_(government))), as well as a mechanism for conflict resolution ([judiciary](https://en.wikipedia.org/wiki/Judiciary)). A legal system is designed and governed by a single %%party|party%%. A legal system can be operationalized by assigning it a scope within which enforcement and conflict resolution are implemented. The associated operational tasks may be mandated or delegated to other parties. Depending on the individual legal system, ‘rules’ may be called ‘laws’, ‘regulations’, ‘directives’, ‘policies’, ‘working instructions’, etc. Other terms exist for specializations of these terms, e.g. ‘order’, ‘mandate’, and others. +A **Legal System** is a system in which rules are defined ([legislature](https://en.wikipedia.org/wiki/Legislature)) and a mechanism for their enforcement is implicitly or explicitly defined ([executive](https://en.wikipedia.org/wiki/Executive_(government))), as well as a mechanism for conflict resolution ([judiciary](https://en.wikipedia.org/wiki/Judiciary)). A legal system is designed and governed by a single %%party|party%%. A legal system can be operationalized by assigning it a scope within which enforcement and conflict resolution are implemented. The associated operational tasks may be mandated or delegated to other %%parties|party%%. Depending on the individual legal system, ‘rules’ may be called ‘laws’, ‘regulations’, ‘directives’, ‘policies’, ‘working instructions’, etc. Other terms exist for specializations of these terms, e.g. ‘order’, ‘mandate’, and others. + +The %%Jurisdictions pattern|pattern-jurisdiction%% provides an overview of how this concept fits in with related concepts. ### Purpose - The ability to distinguish between (non)legal-systems is a very generic enabler to tell which rules (laws, policies, guidelines, etc.) will apply within its %%scope|scope%%, as well as to evaluate the risks that we run when not complying with the rules. Conversely, the %%party|party%% that operates a legal system may provide additional rules to help mitigate such risks. ### Criteria A system in which rules are defined ([legislature](https://en.wikipedia.org/wiki/Legislature)), can be enforced ([executive](https://en.wikipedia.org/wiki/Executive_(government))), and a mechanism is defined to resolve conflicts ([judiciary](https://en.wikipedia.org/wiki/Judiciary)). ### Examples - - many nations have their own legal system (see e.g. [WikiPedia](https://en.wikipedia.org/wiki/List_of_national_legal_systems)) - enterprises typically have at least one legal system, with policies or working instructions as their rules. - multi-nationals, NGO's etc. typically have multiple legal systems that are to be operated in different %%scopes|jurisdiction%% where such operations are subject to other, often %%legal jurisdictions|jurisdiction%%. - all sorts of associations, societies, clubs, unions would qualify as a jurisdiction. - families have a legal system, where the rules may or may not change regularly, enforcement may not always be consistent, and conflict resolution may be ad-hoc. - individual people can be said to have a legal system of their own, containing e.g. rules for ethics and morals. - -### Background - -The %%jurisdiction pattern|pattern-jurisdiction%% provides an overview of how this concept fits in with related concepts. \ No newline at end of file diff --git a/docs/terms/mental-model.md b/docs/terms/mental-model.md index 2829304fa9a43de5c4ee2322a272b11ce9234f3a..23ee1f9cdf798dcda0f3a95745ac379225c3abc8 100644 --- a/docs/terms/mental-model.md +++ b/docs/terms/mental-model.md @@ -7,10 +7,11 @@ typeid: mental-model conceptref: essifLab:pattern stage: draft hoverText: "Mental Model: a casual and formal description (Pattern) of a set of Concepts, relations between them, and constraints, that provide a specific 'viewpoint', or 'way of thinking' about a certain topic." +glossaryText: "a casual and formal description (Pattern) of a set of %Concepts%, relations between them, and constraints, that provide a specific 'viewpoint', or 'way of thinking' about a certain topic." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: See also: %%pattern|pattern%%. \ No newline at end of file diff --git a/docs/terms/objective.md b/docs/terms/objective.md index 433575870415867002619f833016bd19835862ae..3f1970f2548a83a71f2001118d0829bd2ad3c2ae 100644 --- a/docs/terms/objective.md +++ b/docs/terms/objective.md @@ -5,20 +5,21 @@ scopeid: essifLab type: concept typeid: objective stage: draft -hoverText: "Objective: Something toward which effort is directed: an aim, goal, or end of action (Merriam-Webster)." +hoverText: "Objective: Something toward which a Party directs effort (an aim, goal, or end of action)." +glossaryText: "Something toward which a %Party% directs effort (an aim, goal, or end of action)." --- ### Short Description -**Objectives** drive %%parties|party%% as they make their goals explicit, the primary one of which is also referred to as the **mission** of that party. A party's objectives are part of its %%knowledge|knowledge%%. When made available to %%agents|agent%% of that party, these agents can do the work that is needed to reach these goals (realize the party's objectives). +**Objectives** drive %%parties|party%% as they make their goals explicit, the primary one of which is also referred to as the **mission** of that %%party|party%%. A %%party's|party%% objectives are part of its %%knowledge|knowledge%%. When made available to %%agents|agent%% of that %%party|party%%, these agents can do the work that is needed to reach these goals (realize the %%party's|party%% objectives). ### Purpose -The ability to distinguish between (non)objectives is relevant as objectives are the drivers behind the reasoning and decisions that %%parties|party%% make, the policies and working instructions that they specify so that its %%agents|agent%% know what to do, when to do it, and how to do it. Moreover, objectives are 1-1 associated with risks (i.e. the level of uncertainty that the party experiences regarding whether a specific objective is going to be appropriately realized). Finally, objectives must be known in order to obtain (personal) data according to the [GDPR](https://eur-lex.europa.eu/eli/reg/2016/679/oj). +The ability to distinguish between (non)objectives is relevant as objectives are the drivers behind the reasoning and decisions that %%parties|party%% make, the policies and working instructions that they specify so that its %%agents|agent%% know what to do, when to do it, and how to do it. Moreover, objectives are 1-1 associated with risks (i.e. the level of uncertainty that the %%party|party%% experiences regarding whether a specific objective is going to be appropriately realized). Finally, objectives must be known in order to obtain (personal) data according to the [GDPR](https://eur-lex.europa.eu/eli/reg/2016/679/oj). ### Criterion A text representing something toward which a %%party|party%% directs its efforts: an aim, goal, or end of action. ### Examples -- generically: anything that, according to a %%Party|party%% c.q. its way of thinking, is important to be realized, qualifies as an Objective (and identifies its owner as that %%Party|party%%). +- generically: anything that, according to a %%party|party%% c.q. its way of thinking, is important to be realized, qualifies as an Objective (and identifies its owner as that %%party|party%%). - most people have the objective 'stay alive'. - the equivalent in organizations is 'continuation of its existence' (many operate 'business-continuity processes' to realize this, and to identify and mitigate any associated risks). diff --git a/docs/terms/organization.md b/docs/terms/organization.md index 989a86b841a17a56c8292e64b4629ff5311f376c..be8ac5306fd19e6cb52ec181e69234d3cd280c57 100644 --- a/docs/terms/organization.md +++ b/docs/terms/organization.md @@ -6,6 +6,7 @@ type: concept typeid: organization stage: draft hoverText: "Organization: a group of people that work to realize one or more Objectives." +glossaryText: "a group of people that work to realize one or more %Objectives%." --- ### Short Description diff --git a/docs/terms/owned.md b/docs/terms/owned.md new file mode 100644 index 0000000000000000000000000000000000000000..e2622b9f4d3de0d7c8a71da9c86f12ffa2c2744e --- /dev/null +++ b/docs/terms/owned.md @@ -0,0 +1,18 @@ +--- +id: owned +title: "Owned" +scopeid: essifLab +type: concept +typeid: owned +stage: draft +hoverText: "Owned (by an Owner, in some Jurisdiction): an Entity over which another Entity (its Owner) has the power (duty, right) to enjoy it, dispose of it and control it; that power is limited to (the scope of) that Jurisdiction, and by its rules." +glossaryText: "an %Entity% over which another %Entity% (its %Owner%) has the power (duty, right) to enjoy it, dispose of it and control it; that power is limited to (the scope of) that %Jurisdiction%, and by its rules." +--- + +see: %%ownership|ownership%% + +Explain that the fact that the description does not preclude arbitrary Entities to be owners doesn't mean that arbitrary Entities can in fact be owners; that is up to (the Legal System of) the Jurisdiction to provide guidance for. + +### Related Concepts +- %%Ownership relation|ownership%% +- %%Owner|owner%% \ No newline at end of file diff --git a/docs/terms/owner.md b/docs/terms/owner.md index edb9570c341e7c1a403273e7cfb9d09daff54804..ded97cdc96ebf0207edc399ffdc96c5a844b6738 100644 --- a/docs/terms/owner.md +++ b/docs/terms/owner.md @@ -5,37 +5,26 @@ scopeid: essifLab type: concept typeid: owner stage: draft -hoverText: "Owner (of an Entity): the role that a Party performs when it is exercizing its legal or rightful title to control that Entity." +hoverText: "Owner (of an Entity): the role that a Party performs when it is exercizing its legal, rightful or natural title to control that Entity." +glossaryText: "the role that a %Party% performs when it is exercizing its legal, rightful or natural title to control that %Entity%." --- ### Short Description -An **Owner** is a role that a %%Party|party%% performs when it is exercizing its legal or rightful title to control some %%entity|entity%%. We interpret 'legal' and 'rightful' as terms that apply to _any_ %%Jurisdiction|jurisdiction%% (that is: not just %%legal/national jurisdictions|legal-jurisdiction%%, but also those of other %%organizations|organization%% (%%parties|party%%). +An **Owner** is a role that a %%party|party%% performs when it is exercizing its legal, rightful or natural title to control some %%entity|entity%%. -### Purpose - - -### Criteria - -A %%Party|party%% is said to be the **owner** of some %%entity|entity%% if and only if the party and the entity are %%legal entities|legal-entity%% in some %%jurisdiction|jurisdiction%%, within the scope of which that party has the legal or rightful title to control the entity. - -### Examples - +We interpret 'legal' and 'rightful' as terms that apply to _any_ %%jurisdiction|jurisdiction%% (that is: not just %%legal/national jurisdictions|legal-jurisdiction%%, but also those of other %%organizations|organization%% (%%parties|party%%). -### Related Concepts - +We take 'natural' as a title that is provided by nature, as in 'the owner of an %%assertion|assertion%%'. -### Domains - +For futher details, see %%ownership|ownership%%. -### Tags - +### Purpose +The ability to distinguish between (non)owners of an %%entity|entity%% enables one to identify the %%party|party%% and the duties (and rights) it has regarding the %%owned|owned%%. One may want to do so either to establish whether or not the %%owned|owned%% %%entity|entity%%, e.g. if it is an %%actor|actor%%, can be trusted to behave according to its %%owner's|owner%% %%policies|policy%%. Or, one may want to do this in order to settle a dispute it has. -### Use-cases - +### Criteria +A %%party|party%% is said to be the **owner** of some %%(legal) entity|legal-entity%% in some %%jurisdiction|jurisdiction%% if and only if an %%ownership relation|ownership%% exists with that %%jurisdiction|jurisdiction%%. -### Notes - \ No newline at end of file +### Related Concepts +- %%Ownership relation|ownership%% +- %%Owned|owned%% diff --git a/docs/terms/ownership.md b/docs/terms/ownership.md new file mode 100644 index 0000000000000000000000000000000000000000..d06590bba5221b93b8e3893846cae75a044a0f2a --- /dev/null +++ b/docs/terms/ownership.md @@ -0,0 +1,30 @@ +--- +id: ownership +title: "Ownership" +scopeid: essifLab +type: concept +typeid: ownership +stage: draft +hoverText: "Ownership (of an Entity over another in a Jurisdiction): the rights and duties, as defined and enforced in that Jurisdiction, of that Entity to enjoy, dispose of, and control the other Entity." +glossaryText: "the rights and duties, as defined and enforced in that %Jurisdiction%, of that %Entity% to enjoy, dispose of, and control the other %Entity%." +--- + +### Short Description + +**Ownership** is a relationship between two %%entities|entity%% 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 ownership 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 ownership%% to refer to an ownership relation that exists in the %%jurisdiction|jurisdiction%% 'Nature' (see the notes of %%jurisdiction|jurisdiction%%). This enables us to talk about things as 'the (natural) ownership of an %%assertion|assertion%%'. + +### Purpose +**Ownership** 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 **ownership** 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. +- \ No newline at end of file diff --git a/docs/terms/participant.md b/docs/terms/participant.md new file mode 100644 index 0000000000000000000000000000000000000000..a903584546f4d546b8b6199035de970872032b7f --- /dev/null +++ b/docs/terms/participant.md @@ -0,0 +1,22 @@ +--- +id: participant +title: "Participant" +scopeid: essifLab +type: term +typeid: participant +conceptref: essifLab:party +stage: draft +hoverText: "Participant (in/of a Business Transaction): a Party is negotiating (or has negotiated) a Business Transaction Agreement." +glossaryText: "a %Party% is negotiating (or has negotiated) a %Business Transaction Agreement%." +--- + +### Purpose + +Within the context of a %%(business) transaction|business-transaction%%, at least two %%Parties|party%% participate. From the perspective of such a transaction, we need the ability to refer to any such %%party|party%%. + +### Notes + +The term 'participant' is specifically used in the context of a (business) transaction. + +### Related Terms +- %%Peer %%party|party%%|peer-party%% \ No newline at end of file diff --git a/docs/terms/party.md b/docs/terms/party.md index 392994721b73b65ab1b1c11eb4847c21a20e9d0d..4042eaf58b8bc01700d87858a391701be7e7df90 100644 --- a/docs/terms/party.md +++ b/docs/terms/party.md @@ -1,35 +1,45 @@ --- -id: party +id: Party title: "Party" scopeid: essifLab type: concept -typeid: party +typeid: Party stage: draft -hoverText: "Party: Entity that has Knowledge about what exists, ways to reason with that knowledge, and ways for making decisions in a Self-Sovereign fashion." +hoverText: "Party: an Entity that has Objectives, Knowledge about what exists, rules that (should) apply, and some capability that allows it to reason, make decisions, generate and maintain Knowledge etc. in a Self-Sovereign fashion; Humans and Organizations ar the typical examples." +glossaryText: "an %Entity% that has %Objectives%, %Knowledge% about what exists, rules that (should) apply, and some capability that allows it to reason, make decisions, generate and maintain %Knowledge% etc. in a %Self%-Sovereign fashion; %Humans% and %Organizations% ar the typical examples." --- ### Short Description +A **party** is an %%entity|entity%% that pursues %%objectives|objective%%, and has his own, subjective, 'Self-Sovereign' %%knowledge|knowledge%% to help it realize these objectives. Perhaps one might also say: that have a mind of their own. Typical examples are individual people and %%organizations|organization%%. Their minds (subjective knowledge) are what distinguishes one %%party|party%% from another, so every %%party|party%% is 1-1 related to its knowledge (mind). + +The concept we know as 'party' serves a central role, and therefore occurs in various patterns, such as: +- The %%Parties, Actors and Actions pattern|pattern-party-actor-action%%, which provides an overview of how this concept fits in with related concepts. +- the %%Jurisdictions pattern|pattern-jurisdiction%%, which shows that a %%party|party%% can operate the %%legal system|legal-system%% of a %%jurisdiction|jurisdiction%%, enforcing the rules in some scopes to the %%(legal) entities|legal-entity%% that it knows to exist and to which these rules apply. ### Purpose +It is in one's mind - with one's knowledge - that objectives are being set, strategies are being devised, decisions are being made and so on. Specifically, conducting %%business transactions|business-transaction%% requires making numerous decisions, each of which is based on a subjective argument. The evaluation of such an argument requires the acquisition and processing of data, which implies additional decisions (that provide assurances that evaluation will arrive at the right conclusion), such as establishing: +- which data is required, +- what conditions such data should satisfy in order to be %%valid|validated-data%% for performing in the evaluation, +- what sources may be trusted to provide data that is (sufficiently) true, +etcetera. For all of this, it is beneficial to introduce a concept that captures this idea of %%knowledge|knowledge%% or mind in terms of _the_ entity that has it at its disposition, governs it, and has it used to realize its %%objectoves|objective%%. ### Criterion -Entity that has knowledge about what exists, ways to reason[^1] with that knowledge, and ways for making decisions in a Self-Sovereign[^2] fashion. +%%Entity|entity%% that has %%knowledge|knowledge%% about what exists, ways to reason[^1] with that knowledge, and ways for making decisions in a Self-Sovereign[^2] fashion. ### Examples People obviously qualify. Enterprises, governments, and other organizations also qualify as they can be seen as having their own knowledge (e.g. in their registrations, databases etc.), ways to reason with that knowledge (business rules, exercised by their employees or IT systems), and making decision. Stones, pictures, ideas, etc. do not qualify. Also, electronic components do not qualify[^3]. -to be elaborated -### Background - -The concept we know as 'party' serves a central role, and therefore occurs in various patterns, suc as: -- The %%party-actor-action|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. -- the %%jurisdiction pattern|pattern-jurisdiction%%, which shows that a party can operate the %%legal-system|legal-system%% of a %%jurisdiction|jurisdiction%%, enforcing the rules in some scopes to the %%(legal) entities|legal-entity%% that it knows to exist and to which these rules apply. +### Related Terms +The term '[Identity Owner](https://docs.google.com/document/d/1gfIz5TT0cNp2kxGMLFXr19x1uoZsruUe_0glHst2fZ8/edit#heading=h.2e5lma3u6c9g)' (from the [Sovrin Glossary](https://sovrin.org/library/glossary/)) is quite similar for this term, as becomes apparent from its [Taxonomy of Entities](https://docs.google.com/document/d/1gfIz5TT0cNp2kxGMLFXr19x1uoZsruUe_0glHst2fZ8/edit#heading=h.mq7pzglc1j96). However, there it is defined as "_the subclassifications of Sovrin Entity that may be held legally accountable_", which does not fit in our model because: +- it is a subclass of Sovrin Entity, and Parties need not necessarily be Sovrin Entities; +- legal accountability can only be meaningful for %%legal entities|legal-entity%% within a %%jurisdiction|jurisdiction%% that has established criteria for determining which of their %%legal entities|legal-entity%% can be accountable for what. +- The Sovrin definition does not associate an Identity Owner with %%knowledge|knowledge%%. --- [^1]: Reasoning means: inferring conclusions from data, regardless of the kind of logic that is being used, or whether the reasoning is coherent, or consistent. -[^2]: This means that the party can do this all by itself. For humans, the rights for this are laid down e.g. in the [ECHR](https://www.echr.coe.int "European Convention of Human Rights") ([ECHR articles 9-11](https://www.echr.coe.int/Documents/Convention_ENG.pdf)) +[^2]: This means that the %%party|party%% can do this all by itself. For humans, the rights for this are laid down e.g. in the [ECHR](https://www.echr.coe.int "European Convention of Human Rights") ([ECHR articles 9-11](https://www.echr.coe.int/Documents/Convention_ENG.pdf)) [^3]: While the case can be made that (some) electronic components can reason, they do not do so in a self-sovereign fashion as intended by this definition. We do not want to discuss AI-equipment here. 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-file.md b/docs/terms/pattern-file.md index 233dd297e2e44aba22f7336f535fa21b630e9a36..ed32f4bc61dba0166195f37027e867e2fde654cc 100644 --- a/docs/terms/pattern-file.md +++ b/docs/terms/pattern-file.md @@ -5,7 +5,8 @@ scopeid: essifLab type: pattern typeid: pattern-file stage: draft -hoverText: "Pattern-file: a file that defines/specifies a Pattern." +hoverText: "Pattern-file: a file whose contents describes/documents a Pattern." +glossaryText: "a file whose contents describes/documents a %Pattern%." --- ### Short Description diff --git a/docs/terms/pattern-guardianship.md b/docs/terms/pattern-guardianship.md new file mode 100644 index 0000000000000000000000000000000000000000..5e80877d700eaa48ec32b1c0f3f461a892240df6 --- /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 Identity Owner who administers identity 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 1f381c323968d765b6d6b121138da947891059eb..03ea7cb5dc230768ccb0d2eb16b384d53d3735d0 100644 --- a/docs/terms/pattern-jurisdiction.md +++ b/docs/terms/pattern-jurisdiction.md @@ -8,7 +8,7 @@ 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'; +import useBaseUrl from '@docusaurus/useBaseUrl' ### Purpose @@ -16,7 +16,7 @@ The **Jurisdiction pattern** captures the concepts and relations that explain ho ### Introduction -While most people are familiar with what we call %%legal jurisdictions|legal-jurisdiction%%, one readily observes that the characteristics of a jurisdiction - i.e. a %%scope|scope%% within which some party organizes that rules/laws/policies are being made, enforced and conflicts resolved - can be found outside of jurisdictions in numerous other contexts. For example, +While most people are familiar with what we call %%legal jurisdictions|legal-jurisdiction%%, one readily observes that the characteristics of a jurisdiction - i.e. a %%scope|scope%% within which some %%party|party%% organizes that rules/laws/policies are being made, enforced and conflicts resolved - can be found outside of jurisdictions in numerous other contexts. For example, - %%organizations|organization%% habitually will have rules (business policies) in place, enforce them (to some extent), and have ways of resolving conflicts, and therefore qualify. Specifically, multi-nationals are known to operate multiple jurisdictions, aliging the rules and scopes with those of other (often legal) jurisdictions for the purpose of preventing situations in which conflicting rules apply, which would lead to many effort-intensive conflict-resolution cases. - NGO's, may run aid-projects, refugee-camps etc., ensure that a set of rules apply within the scopes of such projects and camps, and arrange for (internal) conflicts to be resolved. Hence they qualify @@ -24,11 +24,11 @@ While most people are familiar with what we call %%legal jurisdictions|legal-jur - Families qualify as well: the parents make the rules, enforce them, and resolve conflicts. - Even individual persons (which qualify as %%parties|party%%), have their own 'scope of control', within which they work according to their own rules (e.g. morals, ethics, preferred ways of working), enforce them (pretty much automatically), and resolve any conflicts (e.g. personal problems that may arise when their rules/habits conflict with what their spouse, employer, any else requires them to do). Saying that an individual operates a (personal) 'legal system' within its scope of control is aligned with the ideas human rights that say humans are 'self sovereign'. -Still, jurisdictions have a lot of variety. The obvious (and self-evident) variety is in the parties that operate its legal system. However, there are also differences in scopes. %%Legal jurisdictions|legal-jurisdiction%% for example may align their scopes with different territories. %%Organizations|organization%% may align their scopes with physical locations as well, possibly aligning them (also) with scopes from legal jurisdictions. Smaller clubs, e.g. a bingo club that weekly hires a cafe for a few hours to do its things, will have its scope determined by location and time. Families and individuals have scopes that are limited by their ability to control (enforce rules). +Still, jurisdictions have a lot of variety. The obvious (and self-evident) variety is in the %%parties|party%% that operate its legal system. However, there are also differences in scopes. %%Legal jurisdictions|legal-jurisdiction%% for example may align their scopes with different territories. %%Organizations|organization%% may align their scopes with physical locations as well, possibly aligning them (also) with scopes from legal jurisdictions. Smaller clubs, e.g. a bingo club that weekly hires a cafe for a few hours to do its things, will have its scope determined by location and time. Families and individuals have scopes that are limited by their ability to control (enforce rules). -Jurisdictions also in terms of the legal system they apply. Different jurisdictions have different (kinds of) rules, which are there to ensure and facilitate that its party realizes the %%objectives|objective%% it has set (for that scope). Often, such rules include specifications of the processes for maintaining the rules themselves, for enforcing them, and for resolving conflicts. Depending on the specific jurisdiction, the specification and maintentance of rules can be anywhere from being very informal to very formal, enforcement ranges from being almost absent to very strict, and resolution of conflicts is anywhere between ad-hoc and tedious litigation. +Jurisdictions also in terms of the legal system they apply. Different jurisdictions have different (kinds of) rules, which are there to ensure and facilitate that its %%party|party%% realizes the %%objectives|objective%% it has set (for that scope). Often, such rules include specifications of the processes for maintaining the rules themselves, for enforcing them, and for resolving conflicts. Depending on the specific jurisdiction, the specification and maintentance of rules can be anywhere from being very informal to very formal, enforcement ranges from being almost absent to very strict, and resolution of conflicts is anywhere between ad-hoc and tedious litigation. -Note that all the rules, processes and decisions must be part of the %%knowledge|knowledge%% of the party that runs the jurisdiction. +Note that all the rules, processes and decisions must be part of the %%knowledge|knowledge%% of the %%party|party%% that runs the jurisdiction. ### Formalized model Here is a visual representation of this pattern, using the following [notations and conventions](../notations-and-conventions#pattern-diagram-notations): @@ -38,4 +38,4 @@ Here is a visual representation of this pattern, using the following [notations src={useBaseUrl('images/patterns/pattern-jurisdiction.png')} /> -The figure shows that a %%jurisdiction|jurisdiction%% comprises a single %%scope|scope%%, a (single) %%legal system|legal-system%% system and a %%party|party%% that operates this Legal System within the Scope (which it controls). The Legal System applies to %%Entities|entity%% that are known in the jurisdiction (e.g. registered with the party as per the rules of the legal system, leading to their being registered/represented in the %%knowledge|knowledge%% of that party). These are what, specifically for %%legal jurisdictions|legal-jurisdiction%% are called %%legal entities|legal-entity%%. \ No newline at end of file +The figure shows that a %%jurisdiction|jurisdiction%% comprises a single %%scope|scope%%, a (single) %%legal system|legal-system%% system and a %%party|party%% that operates this Legal System within the Scope (which it controls). The Legal System applies to %%Entities|entity%% that are known in the jurisdiction (e.g. registered with the %%party|party%% as per the rules of the legal system, leading to their being registered/represented in the %%knowledge|knowledge%% of that %%party|party%%). These are what, specifically for %%legal jurisdictions|legal-jurisdiction%% are called %%legal entities|legal-entity%%. \ No newline at end of file diff --git a/docs/terms/pattern-mandates-delegation-hiring.md b/docs/terms/pattern-mandates-delegation-hiring.md index a8929e1e65ca3e7d4e7c8074a6db08a5b6ced084..7319527e5abff9a7c8d4fb9ab721fdb8f7d95092 100644 --- a/docs/terms/pattern-mandates-delegation-hiring.md +++ b/docs/terms/pattern-mandates-delegation-hiring.md @@ -8,9 +8,7 @@ stage: draft hoverText: "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." --- -import useBaseUrl from '@docusaurus/useBaseUrl'; - :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: diff --git a/docs/terms/pattern-mental-model.md b/docs/terms/pattern-mental-model.md index a7777af45a1ef77d6cb867fc6237cfdcab72c455..0abed00a6605300fbfd00280863d556cac614c53 100644 --- a/docs/terms/pattern-mental-model.md +++ b/docs/terms/pattern-mental-model.md @@ -23,7 +23,7 @@ Different terms can be used to identify the same concept. Car and Automobile are ### Notations -## +### A **pattern** (also called **mental model** or **conceptual model**) captures a limited set of %%concepts|concept%% (ideas), relations between them, and constraints, such that together they form a coherent and consistent whole. Patterns use (tangible) %%terms|term%% to refer to these (intangible) concepts and relations, so in order to be consistent, a pattern must reside in the scope that defines these concepts and relations. A pattern may also 'connect' concepts of different scopes (preferably no more than two), which you might call an 'interconnection pattern' between these scopes. +The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. + ### Purpose - A (good) pattern can be used - to facilitate one's thinking and reasoning about a specific subject/topic, and/or deepen one's understanding of it. - to effectively explain backgrounds of one's reasoning/understanding of the pattern's subject. @@ -21,11 +22,9 @@ A (good) pattern can be used - to write texts using precisely defined language. ### Criteria - a limited set of %%concepts|concept%% (preferably not exceeding 7+/-2)[^1], relations between such concepts, and constraints, such that together they form a coherent and consistent whole that can be used to explain one's thinking about a specific topic within a specific %%scope|scope%%. ### Notes - The first purpose of a pattern is to help us think and reason about a certain topic or issue. One signal that indicates the need of such a model is when we’re running circles in our thoughts, and we have this feeling of not understanding, of the topic being (too) complex. Often, we are thinking in terms of concepts that are not fit for the objectives we pursue. @@ -36,16 +35,3 @@ The careful construction is comparable to a quest: it takes time, multiple versi This careful construction must ensure that the mental model gets different properties. For starters, the pattern must be able to reason in (all) static situations, where things do not change, and the so-called ‘invariant’ rules/constraints must hold. Also, the model must be able to cope with time-dependencies and changes, for which other kinds of rules apply. In the end, the pattern needs to be expressed in several, different ways, depending on whom we want to convey the ideas behind it to. Business people generally need simple models that allow them to (roughly) grasp its gist. Software architects need models with precise definitions that allow them to use its elements in (formal) reasonings. Software engineers (programmers) need all the details that allow them to create applications and databases that work according to the model’s intent. So the level of detail that an expression of the model provides, makes it useful or useless to different audiences. - -### Background -The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. - - \ No newline at end of file diff --git a/docs/terms/peer-actor.md b/docs/terms/peer-actor.md new file mode 100644 index 0000000000000000000000000000000000000000..87916cf35c189246925ddc2df8bd0515930f07eb --- /dev/null +++ b/docs/terms/peer-actor.md @@ -0,0 +1,22 @@ +--- +id: peer-actor +title: "Peer Actor" +scopeid: essifLab +type: term +typeid: peer-actor +conceptref: essifLab:Actor +stage: draft +hoverText: "Peer Actor (of some other Actor in a Communication Session): the Actor with whom/which this other Actor is communicating in that Communication Session." +glossaryText: "the %Actor% with whom/which this other %Actor% is communicating in that %Communication Session%." +--- + +:::info Editors' note +TNO (or others) to revise the contents of this file. +::: + +### Short Description +The **peer actor** of some other %%actor|actor%% in a %%communication session|communication-session%% is the actor with whom/which this other actor is communicating in that session. In other words: it is the actor 'at the other side' of the %%communication channel|communication-channel%% that these actors use to exchange messages in. + +### Purpose +From the perspective of an %%actor|actor%% that has a %%communication session|communication-session%% with antother actor, we need a term to refer to this other actor that is being communicated with. + diff --git a/docs/terms/peer-agent.md b/docs/terms/peer-agent.md index ed1d3595f079448ce7fd7d84b522adfb58e56300..75c3a01ed8395ebaa72bb0ea9058c86227add0bc 100644 --- a/docs/terms/peer-agent.md +++ b/docs/terms/peer-agent.md @@ -6,13 +6,18 @@ type: term typeid: peer-agent conceptref: essifLab:Agent stage: draft -hoverText: "Peer Agent (of another Agent): the Agent with whom this other Agent is communicating in the context of a Business Transaction." +hoverText: "Peer Agent (of some other Agent in a Communication Session): the Agent with whom/which this other Agent is communicating in that Communication Session." +glossaryText: "the %Agent% with whom/which this other %Agent% is communicating in that %Communication Session%." --- +:::info Editors' note +TNO (or others) to revise the contents of this file. +::: + ### Purpose -%%Parties|party%% that participate in a (business) transaction may use %%Agents|agent%%, e.g. for conducting communications, exchanging information, etc. We need a term that can be used in the context of an Agent of such a Party to refer to an Actor with which that Agent communicates, and of which it has been established that it is actually an Agent of a %%Peer Party|peer-party%% of the Party for which it is communicating. +%%Parties|party%% that participate in a (business) transaction may use %%Agents|agent%%, e.g. for conducting communications, exchanging information, etc. We need a term that can be used in the context of an Agent of such a %%party|party%% to refer to an Actor with which that Agent communicates, and of which it has been established that it is actually an Agent of a %%Peer %%party|party%%|peer-party%% of the %%party|party%% for which it is communicating. ### Notes -The term 'peer agent' is specifically used in the context of a (digital) Actor that communicates with another (digital) Actor on behalf of a party that is conducting a (business) transaction with some other party. +The term 'peer agent' is specifically used in the context of a (digital) Actor that communicates with another (digital) Actor on behalf of a %%party|party%% that is conducting a (business) transaction with some other %%party|party%%. diff --git a/docs/terms/peer-party.md b/docs/terms/peer-party.md index 26808772c21741d38a45b99e25f075e4792ee05a..7fd6ebdbc644df6ed6b7cf33481096eee49fcffe 100644 --- a/docs/terms/peer-party.md +++ b/docs/terms/peer-party.md @@ -6,13 +6,17 @@ type: term typeid: peer-party conceptref: essifLab:party stage: draft -hoverText: "Peer Party (of some other Party): the Party that is a participant in a Business Transaction of that other Party." +hoverText: "Peer Party (of another Party that is a participant in a Business Transaction): a Party that also participates in that Business Transaction." +glossaryText: "a %Party% that also participates in that %Business Transaction%." --- ### Purpose -Within the context of a (business) transaction, at least two %%Parties|party%% participate. From the perspective of any such party, we need the ability to refer to (any of) the other party/parties. +Within the context of a %%(business) transaction|business-transaction%%, at least two %%parties|party%% participate. From the perspective of any such %%party|party%%, we need the ability to refer to (any of) the other %%party|party%%/parties. ### Notes -The term 'peer party' is specifically used in the context of a (business) transaction. +The term 'peer %%party|party%%' is specifically used in the context of a (business) transaction. + +### Related Terms +- %%Participant (of a Business Transaction)|participant%% diff --git a/docs/terms/policy-governor.md b/docs/terms/policy-governor.md index 7bef488f90a81097523c411d464f395b07744686..8d103d8f3ef18edb7d08ada82ddcc4b0d0db7a7f 100644 --- a/docs/terms/policy-governor.md +++ b/docs/terms/policy-governor.md @@ -6,16 +6,28 @@ type: concept typeid: policy-governor stage: draft hoverText: "Policy Governor (of a Policy): the Party that is the Owner of the Policy and hence decides what goes in it and what not." +glossaryText: "the %Party% that is the %Owner% of the %Policy% and hence decides what goes in it and what not." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: +### Short Description + +The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. + +### Purpose + +### Criteria + ### Related Concepts +- %%Governance|governance%% +- %%Governor|policy-governor%% +- %%Policy|policy%% - %%Digital Policy|digital-policy%% -- %%TRD Policy|trd-policy%% -- %%TVE Policy|tve-policy%% +- %%Transaction Data Discloser Policy|transaction-data-collector-policy%% +- %%Transaction Data Collector Policy|transaction-data-collector-policy%% - %%Verifier Policy|verifier-policy%% - %%Issuer Policy|issuer-policy%% - %%Holder Policy|holder-policy%% diff --git a/docs/terms/policy.md b/docs/terms/policy.md index 2db8ad9ac32e514f56c6447907fc4dc36a2dccb9..0fc8a4dcc9e3d1768a6b5e002d280565a3e21153 100644 --- a/docs/terms/policy.md +++ b/docs/terms/policy.md @@ -5,7 +5,8 @@ scopeid: essifLab type: concept typeid: policy stage: draft -hoverText: "Policy: a (set of) rules, working instructions or other guidance for the execution of one or more kinds of Actions, that Agents (a) have access to, (b) can interpret as intended by their Principal (i.e. policy Owner) and (c) must use when executing such Actions." +hoverText: "Policy: a (set of) rules, working-instructions, preferences and other guidance for the execution of one or more kinds of Actions, that Agents (a) have access to, (b) can interpret as intended by their Principal (i.e. policy Owner) and (c) must use when executing such Actions." +glossaryText: "a (set of) rules, working-instructions, preferences and other guidance for the execution of one or more kinds of %Actions%, that %Agents% (a) have access to, (b) can interpret as intended by their %Principal% (i.e. policy %Owner%) and (c) must use when executing such %Actions%." --- ### Short Description @@ -16,16 +17,30 @@ An %%agent|agent%% must have access to the policy that its %%principal|principal It should be part of the %%principal's|principal%% governance processes - to establish, maintain and evaluate policies for every kind of action that its agents may execute, -- to derive artifacts from such policies that are useable by the various %%agents|agent%% (digital, human, or otherwise) that have a right or duty to execute actions for the %%principal|principal%% to which such policies apply. So, machine-readable policies should be derived for %%digital-agents|digital-agent%%, and human-readable policies (in different languages if that is appropriate) for non-digital agents. +- to derive artifacts from such policies that are useable by the various %%agents|agent%% (digital, human, or otherwise) that have a right or duty to execute actions for the %%principal|principal%% to which such policies apply. So, machine-readable policies should be derived for %%digital agents|digital-agent%%, and human-readable policies (in different languages if that is appropriate) for non-digital agents. - to publish such artifacts such that at least every of its %%agents|agent%% that may need to access them, can find and access them as needed. - to inform its %%agents|agent%% whenever updates have been made that they need to be aware of (specifically if agents are allowed to keep local copies of such artifacts). +The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. + ### Purpose The purpose of **policies** is to enable %%parties|party%% to provide its %%agents|agent%% with the rules and other guidance that they need to execute %%actions|action%% that comply with such rules. ### Criterion A **policy** is -- a (set of) rules, working instructions and/or other guidance for the execution of one or more kinds of %%actions|action%%; -- is authored by a single %%Party|party%% (the author or %%owner|owner%% of the policy); -- may have multiple representations of the rules, working instructions and/or other guidance, which are derived from the policy itself, in such a way that that any %%actor|actor%% that has a right or duty to execute an %%action|action%% on behalf of the policy's author can do so according to its intentions; -- is accessable to, and must be complied with by an %%agent|agent%% of that policy's author when it executes an action of the kind to which the policy applies. +- a (set of) rules, working-instructions, preferences and other guidance for the execution of one or more kinds of %%actions|action%%; +- governed by a single %%party|party%% (the %%Governor|policy-governor%% of the policy) that decides what goes in the policy and what does not; +- may have multiple representations of the rules, working-instructions, preferences and other guidance, which are derived from the policy itself, in such a way that that any %%actor|actor%% that has a right or duty to execute an %%action|action%% on behalf of the %%policy's governor|policy-governor%% can do so according to its intentions; +- is accessable to, and must be complied with by an %%agent|agent%% of that %%policy's governor|policy-governor%% when it executes an action of the kind to which the policy applies. + +### Related Concepts +- %%Governance|governance%% +- %%Governor|policy-governor%% +- %%Policy|policy%% +- %%Digital Policy|digital-policy%% +- %%Transaction Data Discloser Policy|transaction-data-collector-policy%% +- %%Transaction Data Collector Policy|transaction-data-collector-policy%% +- %%Verifier Policy|verifier-policy%% +- %%Issuer Policy|issuer-policy%% +- %%Holder Policy|holder-policy%% +- %%Wallet Policy|wallet-policy%% \ No newline at end of file diff --git a/docs/terms/presentation-request.md b/docs/terms/presentation-request.md index 82996c92c81127679a6c5ccd29c9836d1e7fe525..1f4bfd2e367bfa867ac1ba1b9c9d5ec4d338660c 100644 --- a/docs/terms/presentation-request.md +++ b/docs/terms/presentation-request.md @@ -5,9 +5,10 @@ scopeid: essifLab type: concept typeid: presentation-request stage: draft -hoverText: "Presentation Request: a (signed) digital message that a Verifier component sends to a Holder component asking for data from one or more Verifiable Credentials." +hoverText: "Presentation Request: a (signed) digital message that a Verifier component sends to a Holder component asking for specific data from one or more Verifiable Credentials that are issued by specific Parties." +glossaryText: "a (signed) digital message that a %Verifier% component sends to a %Holder% component asking for specific data from one or more %Verifiable Credentials% that are issued by specific Parties." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: diff --git a/docs/terms/presentation.md b/docs/terms/presentation.md new file mode 100644 index 0000000000000000000000000000000000000000..34374e0a4ed25fde11be64560ab9fa137f59370a --- /dev/null +++ b/docs/terms/presentation.md @@ -0,0 +1,20 @@ +--- +id: presentation +title: "Presentation" +scopeid: essifLab +type: concept +typeid: presentation +stage: draft +hoverText: "Presentation: a (signed) digital message that a Holder component may send to a Verifier component that contains data derived from one or more Verifiable Credentials (that (a Colleague component of) the Holder component has received from Issuer components of one or more Parties), as a response to a specific Presentation Request of a Verifier component." +glossaryText: "a (signed) digital message that a %Holder% component may send to a %Verifier% component that contains data derived from one or more %Verifiable Credentials% (that (a %Colleague% component of) the %Holder% component has received from %Issuer% components of one or more %Parties%), as a response to a specific %Presentation Request% of a %Verifier% component." +--- + +### Short Description + +### Purpose + +### Criteria + + +### References +- W3C has a [definition of verifiable presentation](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-presentations). \ No newline at end of file diff --git a/docs/terms/principal.md b/docs/terms/principal.md index 01b1b0aafbfb215c3ece34fe7d93927c078e99a0..8aa6f769ad03c265dd583b0d35461dfb7319b1c9 100644 --- a/docs/terms/principal.md +++ b/docs/terms/principal.md @@ -5,11 +5,18 @@ scopeid: essifLab type: concept typeid: principal stage: draft -hoverText: "Principal (of an Actor): A Party for whom, or on behalf of whom, the Actor works (the latter is then an Agent for that Party)." +hoverText: "Principal (of an Actor): the Party for whom, or on behalf of whom, the Actor is executing an Action (this Actor is then called an Agent of that Party)." +glossaryText: "the %Party% for whom, or on behalf of whom, the %Actor% is executing an %Action% (this %Actor% is then called an %Agent% of that %Party%)." --- +:::info Editor's noet +TNO to revise this text +::: + ### Short Description -A **principal** is the term we use to refer to the %%party|party%% for which (on whose behalf) an %%agent|agent%% is acting. The Agent-Principal relation is an %%Actor|actor%%-%%Party|party%% relation where the actor is executing an action on behalf of that party, and for the execution of which the principle has established rules, guidelines, working-instructions, or other relevant matters that the agent must follow (and hence have access to). For %%digital agents|digital-agent%%, +A **principal** is the term we use to refer to the %%party|party%% for which (on whose behalf) an %%agent|agent%% is executing an %%action|action%%. The Agent-Principal relation is an %%actor|actor%%-%%party|party%% relation where the %actor|actor% is executing an %%action|action%% on behalf of that %%party|party%%, and for the execution of which that %%party|party%% has established a %%policy|policy%% that the %%agent|agent%% must (or may) follow, and hence must have access to). For %%digital agents|digital-agent%%, + +The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. ### Purpose The ability to distinguish between (non)principals is relevant in many situations, including: @@ -20,8 +27,5 @@ The **principal** (of an %%actor|actor%%) is the %%party|party%% for whom the ac ### Examples -- A person that is 'doing its own things' is the Principal for himself (as an Actor); the person is also an Agent for himself (as a Party). +- A person that is 'doing its own things' is the Principal for himself (as an Actor); the person is also an Agent for himself (as a %%party|party%%). - When a person is doing things for his employer, the latter is his Principal. - -### Background -The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts. diff --git a/docs/terms/risk.md b/docs/terms/risk.md index 58114f25ae107de7c9fca575cb91c489e0e87656..27d11e41bba89beb2c16b9118ed4e102cb8a5db0 100644 --- a/docs/terms/risk.md +++ b/docs/terms/risk.md @@ -5,11 +5,12 @@ scopeid: essifLab type: concept typeid: risk stage: draft -hoverText: "Risk: the deviation of the expected realization (e.g. results) of an Objective of a Party." +hoverText: "Risk (of a Party's Objective): the deviation of the expected realization (e.g. results) of that Party's Objective." +glossaryText: "the deviation of the expected realization (e.g. results) of that %Party%'s %Objective%." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: ### References diff --git a/docs/terms/scope-file.md b/docs/terms/scope-file.md index 1d890fe8c83290a705a3a570b362b8814d9aff59..5a7a04c0e4b565e491a46f342962d2bcf0c7f90f 100644 --- a/docs/terms/scope-file.md +++ b/docs/terms/scope-file.md @@ -5,7 +5,8 @@ scopeid: essifLab type: concept typeid: scope-file stage: draft -hoverText: "Scope-file: a file that defines/specifies a Scope." +hoverText: "Scope-file: a file whose contents defines/specifies a Scope." +glossaryText: "a file whose contents defines/specifies a %Scope%." --- ### Short Description diff --git a/docs/terms/scope.md b/docs/terms/scope.md index 3a1477064684b9a8bff98b37ac9e3bd32bbe9a3e..850645567fe21082011d4da22b8abfd8da2acbd9 100644 --- a/docs/terms/scope.md +++ b/docs/terms/scope.md @@ -6,46 +6,19 @@ type: concept typeid: scope stage: draft hoverText: "Scope: the extent of the area or subject matter (which we use to define Patterns, Concepts, Terms and Glossaries in)." +glossaryText: "the extent of the area or subject matter (which we use to define %Patterns%, %Concepts%, %Terms% and %Glossaries% in)." --- ### Short Description - A **scope** (in the eSSIFLab context) is the extent of the area or subject matter (as in [OED](https://www.lexico.com/definition/scope). We use it to define patterns, concepts, terms and glossaries in, but a scope may serve other (additional) purposes. Scopes may overlap, or be nested. It is comparable to [Namespeces](https://en.wikipedia.org/wiki/Namespace), were it not that entities other than names (signs that are used to identify/refer to objects of various kinds) can reside in a scope as it is defined here. +The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. + ### Purpose - This allows each %%term|term%% (words, phrases) to be used in a limited scope, for specific purposes. The fact that terms are 'scoped' implies that a term may have _different_ meanings, depending on the scope within which it is used. Also, it allows us to author documentation in a 'scoped' fashion, allowing different groups of people to author, use and disseminate their documentation (including documentation about their ideas (%%patterns|pattern%%), %%concepts|concept%%, and %%terms|term%%.) ### Criteria - a (virtual) demarcation that serves particular purposes. -### Examples - - -### Related Concepts - - -### Background - -The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. - -### Use-cases - - ### Notes - - Scopes within which a certain %%concept|concept%% is known, may still use different terms to refer to the concept. That's the reason for having %%definitions|definition%% that specify criteria for determining whether or not something qualifies as (an instance of) some concept: we cannot rely on different scopes necessarily using the same terms for that. - - \ No newline at end of file diff --git a/docs/terms/semantics.md b/docs/terms/semantics.md index 5a4e1b044ec068c0e18002b2b094920b6b000b4d..67cbd760314d7ff03762510d1dee13495431f468 100644 --- a/docs/terms/semantics.md +++ b/docs/terms/semantics.md @@ -1,20 +1,21 @@ --- id: semantics -title: "Concept" +title: "Semantics" scopeid: essifLabTerminology type: concept typeid: semantics stage: draft hoverText: "Semantics: a mapping between the (tangible/textual) Terms and (intangible) ideas/Concepts - their meaning." +glossaryText: "a mapping between the (tangible/textual) %Terms% and (intangible) ideas/Concepts - their meaning." --- ### Short Description -We use the term **semantics** to refer to the mapping between (tangible) %%terms|term%% and (intangible) %%concepts|concept%% (their meaning, the ideas behind it). Semantics are scoped, i.e. every %%scope|scope%% has its own semantic mapping. This implies that every %%party|party%% has - and maintains - its own (subjective) semantics, which is its subjective mapping of a set of terms onto the concepts/ideas in its %%knowledge|knowledge%%. The (erroneous) assumption that parties would (automagically) share a semantics is the cause of many misunderstandings, and hence should be identified and deleted as soon as possible. +We use the term **semantics** to refer to the mapping between (tangible) %%terms|term%% and (intangible) %%concepts|concept%% (their meaning, the ideas behind it). Semantics are scoped, i.e. every %%scope|scope%% has its own semantic mapping. This implies that every %%party|party%% has - and maintains - its own (subjective) semantics, which is its subjective mapping of a set of terms onto the concepts/ideas in its %%knowledge|knowledge%%. The (erroneous) assumption that %%parties|party%% would (automagically) share a semantics is the cause of many misunderstandings, and hence should be identified and deleted as soon as possible. ### Purpose -The ability to distinguish between (non)semantics helps us to better understand one another, because it makes one aware of the fact that semantics is subjective, and its owner can update it. This allows such an owner to (temporarily) use terms in the same meaning as another party, specifically if they agree to use %%good definitions|definition%%. +The ability to distinguish between (non)semantics helps us to better understand one another, because it makes one aware of the fact that semantics is subjective, and its owner can update it. This allows such an owner to (temporarily) use terms in the same meaning as another %%party|party%%, specifically if they agree to use %%good definitions|definition%%. ### Criteria diff --git a/docs/terms/ssi-agent.md b/docs/terms/ssi-agent.md index a4e4fbd44dc8080882ae23d6f3e7632faa85f2f4..03bc366a1777758508d3912c5b15618405c51ef6 100644 --- a/docs/terms/ssi-agent.md +++ b/docs/terms/ssi-agent.md @@ -7,6 +7,7 @@ typeid: ssi-agent conceptref: essifLab:Agent stage: draft hoverText: "SSI-Agent: a Digital Agent that provides one or more of the SSI functionalities (Issuer, Holder, Verifier, Wallet) to its Principal." +glossaryText: "a %Digital Agent% that provides one or more of the %SSI% functionalities (Issuer, %Holder%, %Verifier%, %Wallet%) to its %Principal%." --- ### Short Description diff --git a/docs/terms/term-file.md b/docs/terms/term-file.md index 5bcee45aa2c3f660a3683448e1e7e70f3682d9b2..76379bd3b3452c4ddb501deb9a9793a7c19d8122 100644 --- a/docs/terms/term-file.md +++ b/docs/terms/term-file.md @@ -5,7 +5,8 @@ scopeid: essifLab type: concept typeid: term-file stage: draft -hoverText: "Term-file: a file that defines/specifies a Term." +hoverText: "Term-file: a file whose contents defines/specifies a Term." +glossaryText: "a file whose contents defines/specifies a %Term%." --- ### Short Description diff --git a/docs/terms/term.md b/docs/terms/term.md index 68027d9186796ce7e008a63da823f9af4dcccad5..2b421762cd88d5c42d1ae68d2aef79f2e415851b 100644 --- a/docs/terms/term.md +++ b/docs/terms/term.md @@ -6,31 +6,22 @@ type: concept typeid: term stage: draft hoverText: "Term: a word or phrase that is used in at least one Scope/context to refer to a specific Concept." +glossaryText: "a word or phrase that is used in at least one %Scope%/context to refer to a specific %Concept%." --- ### Short Description - A Term is a word or phrase that is used in at least one context (and/or for specific purposes) to refer to a specific %%concept|concept%%. As a concequence: - the meaning of a Term may vary across contexts. For example, in the context of a buty-salon, the term 'nail' has a different meaning than in the context of constructing buildings. - different terms (in different contexts) may refer to the same concept ([synonymity](https://en.wikipedia.org/wiki/Synonym)). +The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. + ### Purpose - Understanding words or phrases uttered by others requires that we are able to 'translate' them terms into terms that we habitually use. While this is mostly an automatism, and it often is not necessary to be all that precise, this may be different when they relate to stuff we find important. The ability to refer to a specific %%concept|concept%% with a specific text or phrase, where this 'linking' is limited to a specific (or several) context(s) helps us to better interpret the intentsion of what others convey in spoken or written language. ### Criteria - A Term MUST be a word or phrase that is linked to at least one %%context|scope%% and refers to precisely one %%concept|concept%%. -### Examples - - -### Related Concepts - - -### Background -The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts. - ### Domains * eSSIF-Lab @@ -44,14 +35,7 @@ The %%terminology pattern|pattern-terminology%% provides an overview of how this * Terminology -### Use-cases - - ### Notes - There is an important [distinction](https://simple.wikipedia.org/wiki/Concept) between concepts and the (multitude of) terms (names, labels) that we need to be able to talk and reason (argue) about them. Please consider that * different terms are used in different contexts for the same concept @@ -60,7 +44,6 @@ There is an important [distinction](https://simple.wikipedia.org/wiki/Concept) b --- ### Footnotes - [^1]: WikiPedia has a concise [explanation of concepts](https://en.wikipedia.org/wiki/Concept). We use the term 'concept' as a [mental representation](https://en.wikipedia.org/wiki/Mental_representation). diff --git a/docs/terms/terminology.md b/docs/terms/terminology.md index a851ad30860e029eed57f68699b0a3a95aaf74b6..9ad97adaf90bffc007d36fc0155c758f7d2091c0 100644 --- a/docs/terms/terminology.md +++ b/docs/terms/terminology.md @@ -6,6 +6,7 @@ type: concept typeid: terminology stage: draft hoverText: "Terminology: the set of Terms that are used for communicating about a some specific topic(s)." +glossaryText: "the set of %Terms% that are used for communicating about a some specific topic(s)." --- ### Short Description diff --git a/docs/terms/transaction-agreement.md b/docs/terms/transaction-agreement.md new file mode 100644 index 0000000000000000000000000000000000000000..ca6fde76ff7e9345a603ab2de845a3c6c5a77d5c --- /dev/null +++ b/docs/terms/transaction-agreement.md @@ -0,0 +1,18 @@ +--- +id: transaction-agreement +title: "Transaction Agreement" +scopeid: essifLab +type: concept +typeid: transaction-agreement +stage: draft +hoverText: "Transaction Agreement (for a specific Business Transaction): the set of rules that specify the rights (expectations) and duties (obligations) of Participants towards one another in the context of a specific Business Transaction." +glossaryText: "the set of rules that specify the rights (expectations) and duties (obligations) of %Participants% towards one another in the context of a specific %Business Transaction%." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +### Related Concepts +- %%Transaction Proposal|transaction-proposal%% +- %%Transaction Form|transaction-form%% \ No newline at end of file diff --git a/docs/terms/transaction-data-collector-policy.md b/docs/terms/transaction-data-collector-policy.md new file mode 100644 index 0000000000000000000000000000000000000000..7ee3c1486b69f9885857f68fb5272ff13ece5413 --- /dev/null +++ b/docs/terms/transaction-data-collector-policy.md @@ -0,0 +1,21 @@ +--- +id: transaction-data-collector-policy +title: "Transaction Data Collector Policy" +scopeid: essifLab +type: concept +typeid: transaction-data-collector-policy +stage: draft +hoverText: "Transaction Data Collector Policy: a Digital Policy that enables an operational Transaction Data Collector component to function according to the rules of its Policy Governor." +glossaryText: "a %Digital Policy% that enables an operational %Transaction Data Collector% component to function according to the rules of its %Policy Governor%." +--- + +### Short Description +A **Transaction Data Collector Policy** is a %%digital policy|digital-policy%% that enables an operational %%Transaction Data Collector component|transaction-data-collector%% to function according to the rules of its %%Policy Governor|policy-governor%%. + +Such a policy includes e.g. the kinds of data (and meta-data) required to make these kinds of decisions, criteria to distinguish between %%data that is valid|validated-data%% and data that is not, any data conversions that may be needed, etc. + +### Purpose +The purpose of a **Transaction Data Collector Policy** is to enable the creation of (technical) components that implement the generic %%Transaction Data Collector|transaction-data-collector%% functionality that will subsequently use such policies to guide their behaviour. + +### Criteria +A **Transaction Data Collector Policy** is a %%digital policy|digital-policy%% that enables an operational %%Transaction Data Collector component|transaction-data-collector%% to function according to the rules, working-instructions, preferences and other guidance of its %%Policy Governor|policy-governor%%. diff --git a/docs/terms/transaction-data-collector.md b/docs/terms/transaction-data-collector.md new file mode 100644 index 0000000000000000000000000000000000000000..afcbc817a9964207ef7124235eb4a69f572e4254 --- /dev/null +++ b/docs/terms/transaction-data-collector.md @@ -0,0 +1,110 @@ +--- +id: transaction-data-collector +title: "Transaction Data Collector" +scopeid: essifLab +type: concept +typeid: transaction-data-collector +stage: draft +hoverText: "Transaction Data Collector: a functional component that collects sufficient and Validated Data for deciding whether or not a request (typically for a product or a service) is to be serviced." +glossaryText: "a functional component that collects sufficient and %Validated Data% for deciding whether or not a request (typically for a product or a service) is to be serviced." +--- + +### Short Description +A **Transaction Data Collector** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that a %%party|party%% may use to collect sufficient and %%validated data|validated-data%% for deciding whether or not a request (typically for a product or a service) is to be serviced. + +### Purpose +The purpose of a Transaction Data Collector is to collect sufficient and %%validated data|validated-data%% that eneables (an %%agent|agent%% of) its %%principal|principal%% to decide whether or not some request (typically for a product or a service) is to be serviced. + +### Functionality +A Transaction Data Collector typically starts to collect data when it receives a request (e.g. to provide a product or service). The reception of such a request triggers the creation of a new %%business transaction|business-transaction%%. The task of the Transaction Data Collector is to collect %%validated data|validated-data%% that is sufficient for making a %%commitment decision|commitment-decision%% (or, as [DEMO](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations) calls it: a 'promise' or 'quit' decision.) + +Starting the data collection for a transaction does NOT imply that the identity of the %%actors|actor%% from whom/which the request originated, is established (or authenticated). It also does NOT imply that the identity of the %%peer %%party|party%%|peer-party%% is established (or authenticated). The Transaction Data Collector simply proceeds to collect a sufficient amount of data such that the associated decision can be made, according to the rules, working-instructions, preferences and other guidance provided by its %%principal's|principal%% %%Transaction Data Collector policy|transaction-data-collector-policy%%. Such data may include identity data, but it also may not. + +Starting the data collection for a transaction implies that the Transaction Data Collector informs the %%Transaction Data Discloser component|transaction-data-discloser%% about the %%transaction|business-transaction%% that has just started, and the kind of that transaction. This allows the %%Transaction Data Discloser component|transaction-data-discloser%% to process requests for data from %%peer agents|peer-agent%%[^1x] + +All guidance that the Transaction Data Collector needs to collect the necessary and %%validated data|validated-data%% to make that decision is provided by the %%Transaction Data Collector policy|transaction-data-collector-policy%% that has been established by the Transaction Data Collector's %%principal|principal%%. Such a policy includes e.g. the kinds of data (and meta-data) required to make these kinds of decisions, criteria to distinguish between %%data that is valid|validated-data%% and data that is not, any data conversions that may be needed, etc. + +A Transaction Data Collector may multi-task, i.e. simultaneously/asynchronously collect data for multiple %%transactions|business-transaction%%. To organize this, messages that are exchanged with %%peer agents|peer-agent%% must contain an identifier that allows the Transaction Data Collector and its %%peer agents|peer-agent%% to identify the transaction to which each message belongs. + +During the time in which a Transaction Data Collector is collecting data for a specific %%transaction|business-transaction%%, it may choose to setup, accept, and tear down %%communication sessions|communication-session%% with any %%actors|actor%%, if that is appropriate. This allows requests for data to be sent to different kinds of %%peer %%party|party%%|peer-party%%-%%agents|agent%%, e.g. human or %%digital|digital-agent%% agents. However, the Transaction Data Collector then must ensure that every of these %%agents|agent%% are all %%colleagues|colleague%%, i.e. have the %%peer %%party|party%%|peer-party%% as their %%principal|principal%%. + +A Transaction Data Collector benefits from generic APIs or (G)UIs that allow it to simply ask for the data that it requires. Specifically for SSI, the Transaction Data Collector uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Verifier|verifier%% functionalities. + +### Criteria +A **Transaction Data Collector** is a functional component in the [eSSIF-Lab functional architecture](../functional-architecture) that +- services requests by %%digital|digital-agent%% and non-digital %%agents|agent%%, for providing a product or service, thereby starting a %%transaction|business-transaction%%; +- can setup, accept and tear-down %%communication channels|communication-channel%% of various kinds, with %%digital|digital-colleague%% and/or non-digital %%colleagues|colleague%% of that %%requesting agent|agent%%,[^peer-agents] as appropriate for the data exchanges that are needed to conduct the transactions; +- can use any appropriate %%communication channel|communication-channel%% with a %%peer agent|peer-agent%% to: + - request for data that, according to the %%Transaction Data Collector Policy|transaction-data-collector-policy%% is needed to decide whether or not to commit to the transaction; + - process the responses to such requests, in an orchestrated way, thereby complying with the rules of its %%principal's|principal%% %%Transaction Data Collector Policy|transaction-data-collector-policy%%, the result of which (in the end) is a set of %%validated data|validated-data%% that can serve the purpose of deciding whether or not to commit to the transaction; + - receive similar requests from its %%peer %%party|party%%|peer-party%%, and respond to such requests in compliance with the rules of its %%principal's|principal%% %%Transaction Data Collector Policy|transaction-data-collector-policy%%; +- has a mechanism to ensure that within a %%transaction|business-transaction%%, it uses the latest (most receent) %%Transaction Data Collector Policy|transaction-data-collector-policy%% of its %%principal|principal%%. + +### Deprecated - TVE Functionality + +:::info Editor's note +TNO to revise the text below. +This section is the old text of what was called the Transaction Validation Engine. +It will be deleted in the (near?) future. +::: + +Typically, the Transaction Data Collector would start a transaction either + +- when it receives a request from some 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, to request a specific kind of transaction to some Agent of another %%party|party%%.[^one] + +In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Principal and/or using different %%communication channels|communication-channel%%. + +Handling/managing the various %%communication channels|communication-channel%% through which data can be exchanged is also a task of the Transaction Data Collector[^2]. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens). + +Thus, the Transaction 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 can be requested and obtained. Any extensions or business productization of Transaction 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 Transaction Data Collector needs to know what kinds of credentials it should ask for, which %%parties|party%% its Principal trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.[^3] Also, when the Transaction 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 Principal.[^4] Also, as the Transaction Data Collector gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.[^5] + +In order to make the Transaction Data Collector work, a Validation Policy (or Transaction Data Collector Policy) is created by, or on behalf of the Principal, which specifies at least: + +- the kinds of transactions its 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|commitment-decision%%. + + - the kinds of credentials and issuers that its Principal is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing %%parties|party%% do the actual credential issuing may be specified[^6]. + + - for each kind of credential: the verification proofs that must hold to be accepted as a source for valid data. + + - the mapping between fields in such credentials and fields in the form to be filled in. + +The Policy must be designed in such a way that it is extendable as new features will be called for in the future. + +The ability to create new transaction contexts and the availability of the Transaction Data Collector Policy enable the Transaction Data Collector to request the Verifier component of its Principal 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 Principal.[^7] + +When the Verifier returns such data (which comes with a list of proofs that the Verifier has checked), the Transaction 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 Transaction 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 Transaction Data Collector itself must make validation decisions, either electronically (according to the Transaction Data Collector policy) or by ‘outsourcing’ such decisions to human Agents of its Principal by providing an appropriate validation user interface. + +As long as data is needed, the Transaction Data Collector can intermittently request the 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’. + +----- +### Notes: + +:::info Editor's note +TNO to revise the footnote markers +::: + +[^1x]: In the same way that the Transaction Data Collector needs to collect data in order to be able to decide whether or not to commit, %%agents|agent%% of the %%peer %%party|party%%|peer-party%% need to collect data for making a similar %%commitment decision|commitment-decision%%. Requests for such data are to be processed by the %%Transaction Data Discloser component|transaction-data-discloser%% under guidance of its %%Transaction Data Discloser Policy|transaction-data-discloser-policy%%. + +[^1a]: If the %%Transaction Data Collector policy|transaction-data-collector-policy%% specifies that data is to be collected for other purposes, the %%Transaction Data Collector|transaction-data-collector%% should then be provided a means to inform its %%peer %%party|party%%|peer-party%% of such purposes, and the policy should not specify that such data is required to make the commitment decision. + +[^1 (peer-agents)]: Note that such agents have then become so-called %%peer agents|peer-agent%% (of the Transaction Data Collector) for that specific transaction. Also, the (single!) %%principal|principal%% of these %%peer agents|peer-agent%% is the %%peer %%party|party%%|peer-party%% of the %%principal|principal%% of the Transaction Data Collector (again, for that specific transaction). + +[^1]: This feature ensures that the transaction is really two-way, and both %%parties|party%% can request credentials from the other. For example, a web-shop can then ask for a (delivery) address credential, and the customer can ask for a credential issued e.g. by the chamber of commerce that the web-shop is a legitimate company (and not some maffia website). + +[^2]: It may well be that this functionality can somehow be split off in the (near) future. + +[^3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Principal of the Transaction Data Collector. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years. + +[^4]: For example, a credential that contains an address uses a specific schema to specify addresses, e.g. the ‘PostalAddress’ as defined by schema.org. This schema differs quite a bit from that of Dutch addresses as [*defined*](https://bag.basisregistraties.overheid.nl/def/bag) by the official (authentic) Dutch Registration of Addresses and Buildings (BAG). It may also well differ from the structure of addresses that databases of the Principal have implemented. Mapping allows such cases to be accommodated for. + +[^5]: Inconsistent or incoherent data is necessary for various purposes. First, it allows for correct further processing of the transaction. A non-existent postal code, or one that doesn’t match the delivery address, may hinder a fluent transaction processing, resulting in additional costs and processing times. Another purpose is the early warning or detection of possible fraud/abuse. Remember that part of the data is being asked for reducing transaction risk, and checking consistency/coherence of such data is part of the risk mitigation process. + +[^6]: This enables the Transaction 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|party%% enabling them to obtain the credential from that issuer endpoint if that other %%party|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|party%% is actually issuing such credentials, what their contents means, etc., and hence is capable of tracking down the URI where that %%party|party%% issues the credentials. + +[^7]: A reference to this specification will be added when it becomes available (draft or otherwise). diff --git a/docs/terms/transaction-data-discloser-policy.md b/docs/terms/transaction-data-discloser-policy.md new file mode 100644 index 0000000000000000000000000000000000000000..7726b16663ae259b09dd75e830b0e863753be8e9 --- /dev/null +++ b/docs/terms/transaction-data-discloser-policy.md @@ -0,0 +1,21 @@ +--- +id: transaction-data-discloser-policy +title: "Transaction Data Discloser Policy" +scopeid: essifLab +type: concept +typeid: transaction-data-discloser-policy +stage: draft +hoverText: "Transaction Data Discloser Policy: a Digital Policy that enables an operational Transaction Data Discloser component to function according to the rules of its Policy Governor." +glossaryText: "a %Digital Policy% that enables an operational %Transaction Data Discloser% component to function according to the rules of its %Policy Governor%." +--- + +### Short Description +A **Transaction Data Discloser Policy** is a %%digital policy|digital-policy%% that enables an operational %%Transaction Data Discloser component|transaction-data-discloser%% to function according to the rules of its %%Policy Governor|policy-governor%%. + +Such a policy includes e.g. the kinds of data (and meta-data) that may be disclosed, the conditions that need to be satisfied for actually disclosing such kinds of data, any meta-data (assurances) that maybe added to data being disclosed, etc. + +### Purpose +The purpose of a **Transaction Data Discloser Policy** is to enable the creation of (technical) components that implement the generic %%Transaction Data Discloser|transaction-data-discloser%% functionality that will subsequently use such policies to guide their behaviour. + +### Criteria +A **Transaction Data Discloser Policy** is a %%digital policy|digital-policy%% that enables an operational %%Transaction Data Discloser component|transaction-data-discloser%% to function according to the rules, working-instructions, preferences and other guidance of its %%Policy Governor|policy-governor%%. diff --git a/docs/terms/transaction-data-discloser.md b/docs/terms/transaction-data-discloser.md new file mode 100644 index 0000000000000000000000000000000000000000..fd4f3d4b5d02d7b123c06dc145be420f2483f050 --- /dev/null +++ b/docs/terms/transaction-data-discloser.md @@ -0,0 +1,43 @@ +--- +id: transaction-data-discloser +title: "Transaction Data Discloser" +scopeid: essifLab +type: concept +typeid: transaction-data-discloser +stage: draft +hoverText: "Transaction Data Discloser: a functional component that is capable of disclosing data." +glossaryText: "a functional component that is capable of disclosing data." +--- + +### Short Description +A **Transaction Data Discloser** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that applications (that work for some %%party|party%%) can call to communicate things such as: +- the results of a %%business transaction|business-transaction%% (e.g. statements to confirm that a transaction happened, thereby supplying appropriate details) +- the status of a %%business transaction|business-transaction%% (e.g. that an order has been received in good order, that delivery of an order is dealyed or otherwise changed) +- knowledge (including judgements) that this %%party|party%% has about %%Entities|entity%% (people, organizations, things, orders, deliveries, etc.) + +The Transaction Data Discloser uses a %%Transaction Data Discloser policy|transaction-data-discloser-policy%% to learn about the applicable (business) rules of its %%principal|principal%%. Such a policy may specify e.g. which types of credentials its principal is willing to (have) issue(d), to whom such credentials may be issued and the kinds of assurances that must be obtained before doing so, etcetera. + +The Transaction Data Discloser uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities. + +### Purpose +The purpose of the Transaction 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|party%%. A special kind of result is the (provisioning of) a credential that its Principal already has created. + +### Criteria +A **Transaction Data Discloser** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) that is capable of stating (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other %%Parties|party%%. + +### Functionality +Typically, and at any point in time, %%parties|party%% 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|party%%)**’ to refer to the entity that this %%party|party%% knows to exist, and about whom/which the statement has been made. + +We will use the term ‘**subject-id (of a statement of a %%party|party%%)**’ to refer to the representation that this %%party|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|party%% uses. It need not be humanly interpretable (and preferably is not). + +Parties need to specify the kinds of credentials they are willing to issue, the class of entities (e.g. people, cars, Organizations) for which it will issue them, and the information schema (structure) that it will use in credentials of such kinds.[^1] This allows the Transaction Data Discloser to construct data objects that conform to this information schema, and present it to the Issuer component for actual issuing. + +The Transaction Data Discloser Issuing Policy specifies the kinds of (linked-)data-objects that credentials may be created for. This allows the Transaction Data Discloser to construct such a (linked-)data-objects for every subject-id that identifies a subject of the class for which a credential can be issued, which can subsequently be sent to the Issuer component that can turn it into a credential of a specific sort. + +You can think of the Transaction Data Discloser as the component that pulls all data together that can be put in a credential (e.g. in a passport), and the Issuer as the component that puts the data in an (empty) passport, and signing it so as to create the actual credential. + +The Transaction 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. + +----- + +[^1]: We assume/stipulate that the %%party|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|party%% that want or need to use such credentials. diff --git a/docs/terms/transaction-form.md b/docs/terms/transaction-form.md new file mode 100644 index 0000000000000000000000000000000000000000..438615e050c761050275be33fe362ed78121dae7 --- /dev/null +++ b/docs/terms/transaction-form.md @@ -0,0 +1,15 @@ +--- +id: transaction-form +title: "Transaction Form" +scopeid: essifLab +type: concept +typeid: transaction-form +stage: draft +hoverText: "Transaction Form (for some kind of Business Transaction and some Party): the specification of the set of data that this Party needs to (a) commit to a (proposed) Business Transaction of that kind, (b) fulfill its duties/obligations and (c) escalate if necessary." +glossaryText: "the specification of the set of data that this %Party% needs to (a) commit to a (proposed) %Business Transaction% of that kind, (b) fulfill its duties/obligations and (c) escalate if necessary." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + diff --git a/docs/terms/transaction-id.md b/docs/terms/transaction-id.md new file mode 100644 index 0000000000000000000000000000000000000000..d5adebda2c55298d270c5ec04a56ee9f0e7dcb14 --- /dev/null +++ b/docs/terms/transaction-id.md @@ -0,0 +1,19 @@ +--- +id: transaction-id +title: "Transaction Id" +scopeid: essifLab +type: concept +typeid: transaction-id +stage: draft +hoverText: "Transaction Id (for a specific Business Transaction and a Participant): character string that this Participant uses to identify, and refer to, that Business Transaction." +glossaryText: "character string that this %Participant% uses to identify, and refer to, that %Business Transaction%." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +Explain that different %%transaction|business-transaction%% %%participants|participant%% are each likely to use their own %%identifiers|identifier%% for identifying, and referring to, the various %%transactions|business-transaction%% that they participate in. A %%participant|participant%% should communicate its %%transaction id|transaction-id%% to another %%participant|participant%% if it expects that other %%participant|participant%% to refer to the %%transaction|business-transaction%% in a way that it can dereference (i.e.: can use to identify the %%transaction|business-transaction%% with. + +### Related Concepts +- %%Identifier|identifier%% diff --git a/docs/terms/transaction-proposal.md b/docs/terms/transaction-proposal.md new file mode 100644 index 0000000000000000000000000000000000000000..0c2760d35a22db4d07939c4d59f2f9aa86be1b72 --- /dev/null +++ b/docs/terms/transaction-proposal.md @@ -0,0 +1,18 @@ +--- +id: transaction-proposal +title: "Transaction Proposal" +scopeid: essifLab +type: concept +typeid: transaction-proposal +stage: draft +hoverText: "Transaction Proposal (for a specific Business Transaction): a Transaction Agreement that is 'in-the-making' (ranging from an empty document to a document that would be a Transaction Agreement if it were signed by all Participants)" +glossaryText: "a %Transaction Agreement% that is 'in-the-making' (ranging from an empty document to a document that would be a %Transaction Agreement% if it were signed by all %Participants%)" +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +### Related Concepts +- %%Transaction Agreement|transaction-agreement%% +- %%Transaction Form|transaction-form%% \ No newline at end of file diff --git a/docs/terms/transaction-request.md b/docs/terms/transaction-request.md new file mode 100644 index 0000000000000000000000000000000000000000..8f368908b6eeeda1bcae9cf2e123729cb4b3bc78 --- /dev/null +++ b/docs/terms/transaction-request.md @@ -0,0 +1,18 @@ +--- +id: transaction-request +title: "Transaction Request" +scopeid: essifLab +type: concept +typeid: transaction-request +stage: draft +hoverText: "Transaction Request: a message, send by a requesting Party to a providing Party, that initiates the negotiation of a new Transaction Agreement between these Parties for the provisioning of a specific product or service." +glossaryText: "a message, send by a requesting %Party% to a providing %Party%, that initiates the negotiation of a new %Transaction Agreement% between these %Parties% for the provisioning of a specific product or service." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +### Related Concepts +- %%Transaction Agreement|transaction-agreement%% +- %%Transaction Form|transaction-form%% \ No newline at end of file diff --git a/docs/terms/transaction-type.md b/docs/terms/transaction-type.md new file mode 100644 index 0000000000000000000000000000000000000000..b9f7a1f8b850ca03691dd6abd186cc78e07d262d --- /dev/null +++ b/docs/terms/transaction-type.md @@ -0,0 +1,15 @@ +--- +id: transaction-type +title: "Transaction Type" +scopeid: essifLab +type: concept +typeid: transaction-type +stage: draft +hoverText: "Transaction Type (of some kind of Business Transaction and some Party): the Policy, Governed by that Party, and other necessary artifacts (e.g. a Transaction Form) that provide an Actor with all necessary means to conduct a Transaction of this type on behalf of that Party." +glossaryText: "the %Policy%, %Governed% by that %Party%, and other necessary artifacts (e.g. a %Transaction Form%) that provide an %Actor% with all necessary means to conduct a %Transaction% of this type on behalf of that %Party%." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + diff --git a/docs/terms/transaction-validation-engine.md b/docs/terms/transaction-validation-engine.md deleted file mode 100644 index 3abd7f08bad0023244f24c02c5c15ce34524cbde..0000000000000000000000000000000000000000 --- a/docs/terms/transaction-validation-engine.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: transaction-validation-engine -title: "Transaction Validation Engine (TVE)" -scopeid: essifLab -type: concept -typeid: transaction-validation-engine -stage: draft -hoverText: "Transaction Validation Engine (TVE): a functional component that provides business applications with forms that users have filled in, and where the content of such forms is valid for making decision(s) by this application." ---- - -## Short Description -A **Transaction Validation Engine (TVE)** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that provides business applications with forms that users have filled in, and where the content of such forms is valid for making decision(s) by this application. The TVE uses a %%TVE-policy|tve-policy%% to learn about the applicable (business) rules of the %%Party|party%% on whose behalf the TVE works. - -The TVE uses a %%TVE-policy|tve-policy%% to learn about the applicable (business) rules of its %%principal|principal%%. Such policy may specify which parties can be trusted to issue credentials of a specific kind, how the contents of such credentials map onto data elements as the %%principal|principal%% needs them, etcetera. - -The TVE uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities. - -## Purpose -The purpose of the Transaction Validation Engine (TVE) is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type. - -## Criteria -A **Transaction Validation Engine (TVE)** is a functional component in the [eSSIF-Lab functional architecture](../functional-architecture) that -- services requests by %%digital|digital-agent%% and non-digital %%agents|agent%%, for providing a product or service, thereby starting a %%transaction|business-transaction%%; -- can set-up and tear-down communications channels of various kinds, with %%digital|digital-colleague%% and/or non-digital %%colleagues|colleague%% of that %%requesting agent|agent%%,[^peer-agents] as appropriate for the data exchanges that are needed to conduct the transactions; -- can use any appropriate communications channel with a %%peer-agent|peer-agent%% to: - - request for data that, according to the %%tve-policy|tve-policy%% is needed to decide whether or not to commit to the transaction; - - process the responses to such requests, in an orchestrated way, thereby complying with the rules of its %%principal's|principal%% %%tve-policy|tve-policy%%, the result of which (in the end) is a set of %%validated data|validated-data%% that can serve the purpose of deciding whether or not to commit to the transaction; - - receive similar requests from its %%peer-party%%, and respond to such requests in compliance with the rules of its %%principal's|principal%% %%tve-policy|tve-policy%%; -- has a mechanism to ensure that within a %%transaction|business-transaction%%, it uses the latest (most receent) %%tve-policy|tve-policy%% of its %%principal|principal%%. - -## Functionality - -:::info Editor's note -TNO to revise the text below. -::: - -Typically, the TVE would start a transaction either - -- when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind. -- when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.[^one] - -In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Owner and/or using different communications channels. - -Handling/managing the various communications channels through which data can be exchanged is also a task of the TVE[^2]. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens). - -Thus, the TVE is generally considered capable of obtaining data through different communications channels. However, the technical tracks of eSSIF-Lab will exclusively focus on the communications channel through which credentials can be requested and obtained. Any extensions or business productization of TVE designs may be considered in the business tracks of eSSIF-Lab. The latter is not considered any further in this section. - -In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the TVE needs to know what kinds of credentials it should ask for, which Parties its Owner trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.[^3] Also, when the TVE gets a credential that satisfies the necessary verification proofs, it needs a way to map the contents of that credential to the structure of the transaction context that is used internally by (other systems of) its Owner.[^4] Also, as the TVE gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.[^5] - -In order to make the TVE work, a Validation Policy (or TVE Policy) is created by, or on behalf of the Owner, which specifies at least: - -- the kinds of transactions the Owner is willing to (electronically) engage in, from both the requester and the provider perspectives; -- for each such transaction type: - - - the criteria (business rules) that should be used to determine that the form is ‘clean’, i.e. that the necessary and sufficient data have been obtained and that they are consistent, coherent, and suitable for making a transaction commitment decision. - - - the kinds of credentials and issuers that the Owner is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing Parties do the actual credential issuing may be specified[^6]. - - - for each kind of credential: the verification proofs that must hold to be accepted as a source for valid data. - - - the mapping between fields in such credentials and fields in the form to be filled in. - -The Policy must be designed in such a way that it is extendable as new features will be called for in the future. - -The ability to create new transaction contexts and the availability of the TVE Policy enable the TVE to request the Verifier component of its Owner to obtain credentials of the types that it can use to fill in the transaction form when they satisfy the verification and validation requirements of its Owner.[^7] - -When the Verifier returns such data (which comes with a list of proofs that the Verifier has checked), the TVE must then validate that data, i.e. determine whether or not it is valid for the specific transaction it is assembling the data for. The validation rules are Party-specific and hence come from the TVE policy. For simple cases, validation can simply consist of checking whether or not all verification proofs succeeded. At the other end of the validation spectrum, the TVE itself must make validation decisions, either electronically (according to the TVE policy) or by ‘outsourcing’ such decisions to human Agents of its Owner by providing an appropriate validation user interface. - -As long as data is needed, the TVE can intermittently request the verifier to produce it (or it can use other communications channels, which is outside scope for now). It does so until it times out, or the form has become ‘clean’. - ------ -### Notes: - -[^1 (peer-agents)]: Note that such agents have then become so-called %%peer-agents|peer-agent%% (of the TVE) for that specific transaction. Also, the (single!) %%principal|principal%% of these %%peer-agents|peer-agent%% is the %%peer-party|peer-party%% of the %%principal|principal%% of the TVE (again, for that specific transaction). - -[^1]: This feature ensures that the transaction is really two-way, and both Parties can request credentials from the other. For example, a web-shop can then ask for a (delivery) address credential, and the customer can ask for a credential issued e.g. by the chamber of commerce that the web-shop is a legitimate company (and not some maffia website). - -[^2]: It may well be that this functionality can somehow be split off in the (near) future. - -[^3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Owner of the TVE. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years. - -[^4]: For example, a credential that contains an address uses a specific schema to specify addresses, e.g. the ‘PostalAddress’ as defined by schema.org. This schema differs quite a bit from that of Dutch addresses as [*defined*](https://bag.basisregistraties.overheid.nl/def/bag) by the official (authentic) Dutch Registration of Addresses and Buildings (BAG). It may also well differ from the structure of addresses that databases of the Owner have implemented. Mapping allows such cases to be accommodated for. - -[^5]: Inconsistent or incoherent data is necessary for various purposes. First, it allows for correct further processing of the transaction. A non-existent postal code, or one that doesn’t match the delivery address, may hinder a fluent transaction processing, resulting in additional costs and processing times. Another purpose is the early warning or detection of possible fraud/abuse. Remember that part of the data is being asked for reducing transaction risk, and checking consistency/coherence of such data is part of the risk mitigation process. - -[^6]: This enables the TVE to pass the endpoint URI on to the Verifier when it requests for such a credential, which in turn can send it to the holder of other Parties enabling them to obtain the credential from that issuer endpoint if that other Party does not have that credential in its wallet. The endpoint URI can in fact be put in the policy, because the (human) Agent that creates/maintains the policy would need to know that the issuing Party is actually issuing such credentials, what their contents means, etc., and hence is capable of tracking down the URI where that Party issues the credentials. - -[^7]: A reference to this specification will be added when it becomes available (draft or otherwise). diff --git a/docs/terms/trd.md b/docs/terms/trd.md deleted file mode 100644 index 619619371921494f7c6677a86a2696fa01ff1218..0000000000000000000000000000000000000000 --- a/docs/terms/trd.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -id: trd -title: "TRD" -scopeid: essifLab -type: concept -typeid: trd -stage: draft -hoverText: "TRD = Transaction Result Dispatcher." ---- - -see: %%Transaction Result Dispatcher|transaction-result-dispatcher%%. \ No newline at end of file diff --git a/docs/terms/tve.md b/docs/terms/tve.md deleted file mode 100644 index 6362baae86d908bbfa2e0c2a8993997b02443164..0000000000000000000000000000000000000000 --- a/docs/terms/tve.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -id: tve -title: "TVE" -scopeid: essifLab -type: concept -typeid: tve -stage: draft -hoverText: "TVE = Transaction Validation Engine." ---- - -see %%Transaction Validation Engine|transaction-validation-engine%%. \ No newline at end of file diff --git a/docs/terms/validated-data.md b/docs/terms/validated-data.md index 8b3c7454afc3ff177e7a6156a280eaf872803f9e..7bebed1ed7a1fa44b9ad671d97d559e0b176f71b 100644 --- a/docs/terms/validated-data.md +++ b/docs/terms/validated-data.md @@ -5,10 +5,11 @@ scopeid: essifLab type: concept typeid: validated-data stage: draft -hoverText: "Validated Data: data of which some Party has established that it is valid, and hence can be used, for some specific purpose(s)." +hoverText: "Validated Data: data of which some Party has established that it is valid, and hence suitahble to be used for some specific purpose(s)." +glossaryText: "data of which some %Party% has established that it is valid, and hence suitahble to be used for some specific purpose(s)." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: diff --git a/docs/terms/validation-policy.md b/docs/terms/validation-policy.md new file mode 100644 index 0000000000000000000000000000000000000000..d04ad94c9e04f41ee749addcbe408b7c7d0df39f --- /dev/null +++ b/docs/terms/validation-policy.md @@ -0,0 +1,19 @@ +--- +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." +glossaryText: "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..5148fb3bbe32307c36054f75262cbf56e5717ec5 --- /dev/null +++ b/docs/terms/validation.md @@ -0,0 +1,18 @@ +--- +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." +glossaryText: "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/verifiable-credential.md b/docs/terms/verifiable-credential.md index e134c945e86171c22ba58118915373924dd46b32..6a169d711e971533976c76261f230034225c7b02 100644 --- a/docs/terms/verifiable-credential.md +++ b/docs/terms/verifiable-credential.md @@ -6,14 +6,20 @@ type: concept typeid: verifiable-credential stage: draft hoverText: "Verifiable Credential: Credential that comes with assurances regarding its provenance (the Party that issued it) and its integrity (the property that the Credential data has not been tampered with in transit, i.e. is the same as when issued)." +glossaryText: "Credential that comes with assurances regarding its provenance (the %Party% that issued it) and its integrity (the property that the %Credential% data has not been tampered with in transit, i.e. is the same as when issued)." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: ### Related Concepts - %%credential|credential%% +- %%verifiable data|verifiable-data%% - %%verified data|verified-data%% - %%validated data|validated-data%% +### References: +- W3C VC [definition of 'verificable credential'](https://www.w3.org/TR/vc-data-model/#dfn-credential) +- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) + diff --git a/docs/terms/verifiable-data.md b/docs/terms/verifiable-data.md new file mode 100644 index 0000000000000000000000000000000000000000..2afc83fb42dbdee8d4199fc305ec631efeffcfaf --- /dev/null +++ b/docs/terms/verifiable-data.md @@ -0,0 +1,25 @@ +--- +id: verifiable-data +title: "Verfiable Data" +scopeid: essifLab +type: concept +typeid: verfiable-data +stage: draft +hoverText: "Verifiable Data: data that comes with assurances regarding its provenance (the Party that issued it) and its integrity (the property that the Credential data has not been tampered with in transit, i.e. is the same as when created)." +glossaryText: "data that comes with assurances regarding its provenance (the %Party% that issued it) and its integrity (the property that the %Credential% data has not been tampered with in transit, i.e. is the same as when created)." +--- + +:::info Editor's note +TNO (or others) to provide the content of this file. +::: + +### Related Concepts +- %%credential|credential%% +- %%verified data|verified-data%% +- %%validated data|validated-data%% + +### References: +- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) +- W3C VC [definition of 'verification'](https://www.w3.org/TR/vc-data-model/#dfn-verification) +- W3C VC [definition of 'validation'](https://www.w3.org/TR/vc-data-model/#dfn-validation) + diff --git a/docs/terms/verification.md b/docs/terms/verification.md new file mode 100644 index 0000000000000000000000000000000000000000..b9fd5cf1f129b347a461fb94b2f4f2df7883b0dd --- /dev/null +++ b/docs/terms/verification.md @@ -0,0 +1,18 @@ +--- +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)." +glossaryText: "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/docs/terms/verified-data.md b/docs/terms/verified-data.md index c228fb578dc4a1a6888eea584abb3ad5a777e842..b5b08082248fdbcd5e49d910af51626878908f9d 100644 --- a/docs/terms/verified-data.md +++ b/docs/terms/verified-data.md @@ -5,10 +5,11 @@ scopeid: essifLab type: concept typeid: verified-data stage: draft -hoverText: "Verified Data: data of which some Party has established that it is a truthful representation of what its author intended it to mean when the data was created." +hoverText: "Verified Data: data of which some Party has established that it is a truthful representation of what its Author intended it to mean when the data was last created/updated." +glossaryText: "data of which some %Party% has established that it is a truthful representation of what its %Author% intended it to mean when the data was last created/updated." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: diff --git a/docs/terms/verifier-policy.md b/docs/terms/verifier-policy.md index df8eba6516f3f678f14dc26ebc35d06919dfda75..6fe87d38507f7faa58845f9458f93a6cd94e30a4 100644 --- a/docs/terms/verifier-policy.md +++ b/docs/terms/verifier-policy.md @@ -6,10 +6,11 @@ type: concept typeid: verifier-policy stage: draft hoverText: "Verifier Policy: a Digital Policy that enables an operational Verifier component to function according to the rules of its Policy Governor." +glossaryText: "a %Digital Policy% that enables an operational %Verifier% component to function according to the rules of its %Policy Governor%." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: ### Related Concepts diff --git a/docs/terms/verifier.md b/docs/terms/verifier.md index 8ed186c28ceb58eadf1d48119c79d345bccf515b..1dfcb2860784c88c6cfb4bc3093d5616c906462c 100644 --- a/docs/terms/verifier.md +++ b/docs/terms/verifier.md @@ -6,27 +6,36 @@ type: concept typeid: verifier stage: draft hoverText: "Verifier (functional component): the capability to request Peer Agents to present (provide) data from credentials (of a specified kind, issued by specified Parties), and to verify such responses (check structure, signatures, dates), according to its Principal's Verifier Policy." +glossaryText: "the capability to request %Peer Agents% to present (provide) data from credentials (of a specified kind, issued by specified %Parties%), and to verify such responses (check structure, signatures, dates), according to its %Principal%'s %Verifier Policy%." --- -## Short Description -A **Verifier** is is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that +### Short Description +A **Verifier** is is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that supports the %%Transaction Data Collector|transaction-data-collector%% as it tries to acquire %%(verifiable) credentials|credential%% from (an %%agent|agent%% of) some other %%party|party%%, for the purpose of negotiating a %%business transaction|business-transaction%%. -The **verifier** functionality is to support the TVE 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 TVE with verified data. +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, +- sending them to an %%agent|agent%% of that other %%party|party%% that provides %%holder|holder%% functionality, +- receiving a response from that %%agent|agent%% to the %%presentation request|presentation-request%% (i.e. a '%%Presentation|presentation%%'), +- verifying that %%presentation|presentation%%, i.e. checking the signature and other proofs of the veracity of both the construction of the presentation and its contents +- returning the data that the %%Transaction Data Collector|transaction-data-collector%% requested, optionally with a report about which verification checks succeeded and/or which failed. +:::info Editor's note +TNO (or others) to provide additional content of this file. +::: -## Purpose +### Purpose The purpose of the Verifier function is. -## Criteria +### Criteria A **Verifier** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whose function is to ... (tbd). -## Functionality +### Functionality -The purpose of the Verifier component is to support the Transaction (Validation) Engine 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 component is to support the Transaction 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 TVE 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 TVE 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 TVE policy. +Typically, the Transaction 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 Principal - 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 Transaction 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 Transaction 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 TVE specifies this as part of the request - and it can do so because it has received the original request, and does all communications channel handling. +Then, the Verifier needs to know the address and protocol that it can use to reach a Holder component owned by the %%party|party%% that its Principal is trying to negotiate the transaction with. The Transaction 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. @@ -34,13 +43,13 @@ 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). +- meta-data that may be useful for the 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 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 to obtain proof that the Verifiers 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 component work, a Verifier Policy/Preferences object is created by, or on behalf of the 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 component of the Peer %%party|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). -Then, the verifier will send a message to the TVE, containing the transaction-id, the data it has received, and the results of the various checks. \ No newline at end of file +Then, the verifier will send a message to the Transaction Data Collector, containing the transaction-id, the data it has received, and the results of the various checks. diff --git a/docs/terms/vocabulary.md b/docs/terms/vocabulary.md index 757989d0003ffb5227228c3c627171da974adaac..9155dc7842b404da429249f94e7c5c6aca6151d6 100644 --- a/docs/terms/vocabulary.md +++ b/docs/terms/vocabulary.md @@ -6,6 +6,7 @@ type: concept typeid: vocabulary stage: draft hoverText: "Vocabulary: the sum or stock of words employed by a language, group, individual, or work or in a field of knowledge." +glossaryText: "the sum or stock of words employed by a language, group, individual, or work or in a field of knowledge." --- ### Short Description diff --git a/docs/terms/wallet-policy.md b/docs/terms/wallet-policy.md index 5be069ff72dd0cdaa971b529f0ca12f82971c373..79dc2b97cd22ef99eaa6c679adfbaef12c8199f0 100644 --- a/docs/terms/wallet-policy.md +++ b/docs/terms/wallet-policy.md @@ -6,10 +6,11 @@ type: concept typeid: wallet-policy stage: draft hoverText: "Wallet Policy: a Digital Policy that enables an operational Wallet component to function according to the rules of its Policy Governor." +glossaryText: "a %Digital Policy% that enables an operational %Wallet% component to function according to the rules of its %Policy Governor%." --- :::info Editor's note -TNO to provide the content of this file. +TNO (or others) to provide the content of this file. ::: ### Related Concepts diff --git a/docs/terms/wallet.md b/docs/terms/wallet.md index b1d16a29bef2209a9385f30d5ea642ac0bd35966..58d9b20beb0091b9070d4a79e6da8c0783807047 100644 --- a/docs/terms/wallet.md +++ b/docs/terms/wallet.md @@ -6,28 +6,28 @@ type: concept typeid: wallet stage: draft hoverText: "Wallet (functional component): the capability to securely store data as requested by Colleague Agents, and to provide stored data to Colleague Agents or Peer Agents, all in compliance with the rules of its Principal's Wallet Policy." +glossaryText: "the capability to securely store data as requested by %Colleague Agents%, and to provide stored data to %Colleague Agents% or %Peer Agents%, all in compliance with the rules of its %Principal%'s %Wallet Policy%." --- -## Short Description -A **Wallet** is is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that +### Short Description +A **Wallet** is is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that provides (secure) storage of credentials - regardless of the %%party|party%% that has issued them (i.e. so-called self-signed credentials may be stored there, too). Another task of the wallet is to (securely) store (private) keys that can be used to sign or seal data on behalf of its Principal. 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) Principal, and will become available if such other component implements a functionality that needs it. +:::info Editor's note +TNO (or others) to provide additional content of this file. +::: -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. - - - -## Purpose +### Purpose The purpose of the Wallet function is. -## Criteria +### Criteria A **Wallet** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whose function is to ... (tbd). -## Functionality +### Functionality The primary purpose of the 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 - 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|party%%, and +- (private) keys e.g. for signing/sealing data on behalf of its Principal. Other kinds of data may be stored by a wallet as well - we will have to see what is practical and makes sense. @@ -39,9 +39,9 @@ By ‘securely storing data’ we mean that such data - 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). -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 and Issuer will (arise and) need access. One example could be a component that is capable of securely signing data on behalf of the 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 component, not even the ones they own. They need an electronic Agent that is capable of authenticating them as (an Agent of) the %%party|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. -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 component work, a Wallet Policy/Preferences object is created by, or on behalf of the Principal, the contents of which remains to be specified. diff --git a/docs/vision-and-purpose.md b/docs/vision-and-purpose.md new file mode 100644 index 0000000000000000000000000000000000000000..f97a98c6cc9e3f2038c0c04b3b11bdcf90b5b362 --- /dev/null +++ b/docs/vision-and-purpose.md @@ -0,0 +1,43 @@ +--- +id: vision-and-purpose +title: eSSIF-Lab Vision and Purpose +sidebar_label: Vision and Purpose +--- + +## Vision + +The eSSIF-Lab vision is that Self-sovereign Identity (SSI) will *empower European and other citizens* by providing new means to manage privacy by eliminating logins and making electronic transactions fast and safe both in the Internet and in physical life. SSI will *empower European organisations and governments* by providing new means to speed up, secure and automate transactions with citizens, customers, suppliers and partners, resulting in tens of billions of euros savings annually on administrative costs in Europe. SSI will be *a new business ecosystem paradigm* with thousands of new jobs, many new job categories and new business opportunities for existing and new European companies. And last, but certainly not least, SSI fosters *inclusiveness* and supports organizations and citizens to exercise their rights and fulfil their duties under the GDPR. + +The current situation is that SSI solutions that are being created and brought to the market either target specific applications for which they provide a vertical solution (‘stovepipes’), many need some kind of centralized governance/control, others have privacy issues, and none that we know of are interoperable with other such solutions. + +The situation we would like to see is one in which we have SSI-enabled, interoperable, scalable and business/information agnostic technologies, that form an infrastructure that every application for every %%party|party%% can use to serve its own objectives. This infrastructure, that enables the electronic exchange of verified (personal and non-personal) data, must be so easy to access and use for such %%parties|party%% that they will no longer need to be concerned about actual (SSI) technologies that have empowered them to make this happen. Rather, they will only need to think about, and decide which kinds of information they want to obtain for conducting specific %%business transactions|business-transaction%% and which %%parties|party%% they trust for providing such information. Also, they will need to think about, and decide which kinds of information they themselves are willing to provide to others in this new SSI world. + +## Purpose + +:::tip **The purpose of the eSSIF-Lab...** +... is to specify, develop and validate technological and non-technological (e.g. governance) means that support people, businesses and governments to think about, design and operate their (information) processes and conduct %%business transactions|business-transaction%% with one another that are electronically supported using SSI technology. +::: + +## Context + +The context of the eSSIF-Lab vision can be found in articles 8-10 of the [*European Convention on Human Rights (ECHR)*](https://www.echr.coe.int/Pages/home.aspx?p=basictexts/convention), that state the rights of individuals regarding their privacy, and their freedoms to collect, process, store, and express information in a self-sovereign fashion, i.e. in a way that they can decide for themselves. This is without prejudice to Member States’ laws that exist to protect their national security, public safety, the economic well-being of the country, health or morals or the rights and freedoms of others, or to prevent disorder or crime. The eSSIF-Lab vision extends these rights and freedoms - within the limits of the law - to public and private organizations. Thus, we say that individuals as well as public and private organizations (that we collectively refer to as ‘parties’) are self-sovereign[^1]. + +In the context of these rights and freedoms, we seek to electronically support %%business transactions|business-transaction%%, i.e. the exchange of goods, services, funds, or data between %%parties|party%%, which we call ‘participants’ to the transaction[^2]. + +Supporting such transactions requires each participant to have one or more %%electronic (digital) agents|digital-agent%%, i.e. equipment (e.g. an app on a mobile phone, a webserver, a browser, …) that provides such support and that (provably) acts on behalf of that participant. + +## Work-In-Progress: Where We Want To Go + +This functional architecture is a work-in-progress that is currently being conducted by %%parties|party%% that are funded by the [eSSIF-Lab project](https://essif-lab.eu/). Working with %%parties|party%% that have different backgrounds presents the challenge of resolving the issues that arise from such differences e.g. as technical interoperability or semantic interoperability. The eSSIF-Lab project adds '%%documentation interoperability|documentation-interop%%' to this. + +In order to achieve '%%documentation interoperability|documentation-interop%%', we think that contributing %%parties|party%% +- should develop (learn, actively use and continually improve upon) a small set of %%terms|term%% that can be used as a basis for exchanging ideas (%%concepts|concept%%), discussions, etc. We suggest to start with the terms used (and defined) by the %%"Parties, Actors and Actions" pattern|pattern-party-actor-action%%, and to extend on that as we go. +- should develop their documentation using these terms, and adding additional terminology if they think this helps others to understand their documentation. The eSSIF-Lab project is developing tooling (a '[Terminology Engine](terminology-contributions)') that allows for this. +- ideally help to improve this tooling. + +-------- + +[^1]: We realize that by doing this we have a different definition of what self-sovereignty entails than many others. We are open to suggestions for a better phrase. + +[^2]: A good model for describing and designing %%business transactions|business-transaction%% and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations). + diff --git a/docusaurus.config.js b/docusaurus.config.js index ec711bff16e76ba4ce0d0d33723956673fb85916..d506255279336a3c0d5222295ab53da9bb6999cc 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -22,9 +22,10 @@ module.exports = { src: 'images/eSSIF-Lab logo.png', }, items: [ - {to: 'docs/introduction', label: 'Introduction', position: 'left'}, + {to: 'docs/project', label: 'Project', position: 'left'}, {to: 'docs/vision-and-purpose', label: 'Vision', position: 'left'}, {to: 'docs/functional-architecture', label: 'Functional Architecture', position: 'left'}, + {to: 'docs/governance', label: 'Governance', position: 'left'}, {to: 'docs/terminology', label: 'Terminology', position: 'left'}, {to: 'docs/ssi-standards', label: 'SSI Standardization', position: 'right'}, { @@ -66,8 +67,8 @@ module.exports = { title: 'eSSIF-lab Framework', items: [ { - label: 'Introduction', - to: 'docs/introduction' + label: 'Project', + to: 'docs/project' }, { label: 'Functional Architecture', diff --git a/plugins/terminology-parser/index.js b/plugins/terminology-parser/index.js index 3371a4329a7a3d4f79826720b5734654dae7b696..0b7069ee3ca68e33a17405888ea765826533ed85 100644 --- a/plugins/terminology-parser/index.js +++ b/plugins/terminology-parser/index.js @@ -26,14 +26,14 @@ function getRelativePath(source,target) { return relative_url === '' ? '.' + target.substr(target.lastIndexOf("/")) : relative_url + target.substr(target.lastIndexOf("/")); } -function getImportStatement(filePath) { +function getAutoIncludeStatements(filePath) { var filePath = path.dirname(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 importTerm = `\n\nimport { Term } from '${relativePath}'\n`; + var importTerms = `\n\nimport { Term } from '${relativePath}'\n`; - return importTerm + return importTerms } async function getHoverText(filePath) { @@ -96,8 +96,8 @@ async function parser(err, files) { // Find the index of the 2nd occurrence of '---' var indexOfSecond = content.indexOf(searchTerm, 1); // Add the import statement - var importStatement = getImportStatement(filepath); - content = content.insert(indexOfSecond + 3, importStatement); + var autoIncludeStatements = getAutoIncludeStatements(filepath); + content = content.insert(indexOfSecond + 3, autoIncludeStatements); // Write the file with the updated content fs.writeFile(filepath, content, 'utf8', function (err) { diff --git a/src/pages/index.js b/src/pages/index.js index 74b8957be33f4bd48c243c4cb7502434a5d7da29..73cc0af4172bd7d7447c318e23de39ecd31a66a7 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -22,7 +22,7 @@ function CustomFeature() { )}>
Horizon 2020 - eSSIF Lab logo + eSSIF-Lab logo

{title}

{description}

@@ -47,7 +47,7 @@ function Home() { 'button button--outline button--secondary button--lg', styles.getStarted, )} - to={useBaseUrl('docs/introduction')}> + to={useBaseUrl('docs/project')}> Get Started diff --git a/static/images/eSSIF-Lab-functional-architecture-infra.png b/static/images/eSSIF-Lab-functional-architecture-infra.png new file mode 100644 index 0000000000000000000000000000000000000000..acfc1ba7fcda5453aefddc700a6b3bf4e21f273f Binary files /dev/null and b/static/images/eSSIF-Lab-functional-architecture-infra.png differ diff --git a/static/images/eSSIF-Lab-functional-architecture.png b/static/images/eSSIF-Lab-functional-architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..84c42f04dadc5e10054a78a40b22b82d600fa643 Binary files /dev/null and b/static/images/eSSIF-Lab-functional-architecture.png differ diff --git a/static/images/eSSIF-Lab-high-level-trx-negotiation.png b/static/images/eSSIF-Lab-high-level-trx-negotiation.png new file mode 100644 index 0000000000000000000000000000000000000000..7bc5b92741ae78e2ec8fa6c482d5572085c9dea7 Binary files /dev/null and b/static/images/eSSIF-Lab-high-level-trx-negotiation.png differ diff --git a/static/images/eSSIF-Lab-high-level-trx-overview.png b/static/images/eSSIF-Lab-high-level-trx-overview.png new file mode 100644 index 0000000000000000000000000000000000000000..f5a9a98d2201c16d7e5a2001b8b0343ccbb99559 Binary files /dev/null and b/static/images/eSSIF-Lab-high-level-trx-overview.png differ diff --git a/static/images/vision-context.png b/static/images/eSSIF-Lab-vision-context.png similarity index 100% rename from static/images/vision-context.png rename to static/images/eSSIF-Lab-vision-context.png diff --git a/static/images/functional-architecture-infra.png b/static/images/functional-architecture-infra.png deleted file mode 100644 index fd8139df4d076d0ef7cee5f7e3db0a4ae6fe817c..0000000000000000000000000000000000000000 Binary files a/static/images/functional-architecture-infra.png and /dev/null differ diff --git a/static/images/functional-architecture.png b/static/images/functional-architecture.png deleted file mode 100644 index 06c902e72fc035575876e60d1f84128d79b0a559..0000000000000000000000000000000000000000 Binary files a/static/images/functional-architecture.png and /dev/null differ 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 diff --git a/static/images/patterns/pattern-jurisdiction.png b/static/images/patterns/pattern-jurisdiction.png index 02181d9dc3feca8d8f67d92e95d1da43b3b4f6d5..ba378a7798fe457b460d1b16eb917b0e117f8c52 100644 Binary files a/static/images/patterns/pattern-jurisdiction.png and b/static/images/patterns/pattern-jurisdiction.png differ