From 96eeb12740237aeca084c3398620ee7c47a52421 Mon Sep 17 00:00:00 2001 From: RieksJ Date: Tue, 27 Oct 2020 16:59:53 +0100 Subject: [PATCH] added glossaryTexts --- docs/ssi-standards.md | 4 ---- docs/terminology-maintenance-script.rieks | 21 ++++++++++--------- docs/terms/action-type.md | 4 ++-- docs/terms/action.md | 2 +- docs/terms/actor.md | 2 +- docs/terms/agent.md | 2 +- docs/terms/assertion.md | 2 +- docs/terms/author.md | 2 +- docs/terms/business-transaction.md | 10 ++++----- docs/terms/colleague.md | 2 +- docs/terms/commitment-decision.md | 2 +- docs/terms/communication-channel.md | 2 +- docs/terms/communication-session.md | 2 +- docs/terms/concept-file.md | 2 +- docs/terms/concept.md | 2 +- docs/terms/corpus.md | 2 +- docs/terms/credential-catalogue.md | 2 +- docs/terms/credential-type.md | 4 ++-- docs/terms/credential.md | 4 ++-- docs/terms/data-collector-policy.md | 2 +- docs/terms/data-collector.md | 18 ++++++++-------- docs/terms/data-discloser-policy.md | 2 +- docs/terms/data-discloser.md | 6 +++--- docs/terms/definition.md | 2 +- docs/terms/dependent.md | 2 +- docs/terms/dictionary-file.md | 2 +- docs/terms/dictionary.md | 2 +- docs/terms/digital-actor.md | 2 +- docs/terms/digital-agent.md | 2 +- docs/terms/digital-colleague.md | 2 +- docs/terms/digital-communication-channel.md | 2 +- docs/terms/digital-policy.md | 2 +- docs/terms/employee.md | 2 +- docs/terms/employer.md | 2 +- docs/terms/essif-glue.md | 2 +- docs/terms/glossary-file.md | 2 +- docs/terms/glossary.md | 2 +- docs/terms/governor.md | 2 +- docs/terms/guardian.md | 2 +- docs/terms/guardianship-type.md | 2 +- docs/terms/guardianship.md | 4 ++-- docs/terms/holder-policy.md | 2 +- docs/terms/holder.md | 8 +++---- docs/terms/identifier.md | 4 ++-- docs/terms/issuer-policy.md | 2 +- docs/terms/issuer.md | 8 +++---- docs/terms/jurisdiction-governor.md | 2 +- docs/terms/jurisdiction.md | 2 +- docs/terms/knowledge-governor.md | 2 +- docs/terms/knowledge.md | 4 ++-- docs/terms/legal-entity.md | 2 +- docs/terms/legal-jurisdiction.md | 2 +- docs/terms/legal-system.md | 2 +- docs/terms/mental-model.md | 2 +- docs/terms/objective.md | 2 +- docs/terms/organization.md | 2 +- docs/terms/owned.md | 2 +- docs/terms/owner.md | 2 +- docs/terms/ownership.md | 4 ++-- docs/terms/participant.md | 2 +- docs/terms/party.md | 2 +- docs/terms/pattern-file.md | 2 +- docs/terms/pattern-guardianship.md | 8 +++---- docs/terms/pattern-party-actor-action.md | 8 +++---- docs/terms/pattern.md | 8 +++---- docs/terms/peer-actor.md | 2 +- docs/terms/peer-agent.md | 2 +- docs/terms/peer-party.md | 2 +- docs/terms/policy-governor.md | 2 +- docs/terms/policy.md | 2 +- docs/terms/presentation-request.md | 2 +- docs/terms/presentation.md | 2 +- docs/terms/principal.md | 4 ++-- docs/terms/risk.md | 2 +- docs/terms/scope-file.md | 2 +- docs/terms/scope.md | 2 +- docs/terms/semantics.md | 2 +- docs/terms/ssi-agent.md | 2 +- docs/terms/term-file.md | 2 +- docs/terms/term.md | 2 +- docs/terms/terminology.md | 2 +- docs/terms/transaction-agreement.md | 2 +- .../transaction-data-collector-policy.md | 2 +- docs/terms/transaction-data-collector.md | 14 ++++++------- .../transaction-data-discloser-policy.md | 2 +- docs/terms/transaction-data-discloser.md | 4 ++-- docs/terms/transaction-form.md | 2 +- docs/terms/transaction-id.md | 2 +- docs/terms/transaction-proposal.md | 2 +- docs/terms/transaction-request.md | 2 +- docs/terms/transaction-result-dispatcher.md | 4 ++-- docs/terms/transaction-type.md | 2 +- docs/terms/trd-policy.md | 12 +++++------ docs/terms/tve-policy.md | 12 +++++------ docs/terms/validated-data.md | 2 +- docs/terms/validation-policy.md | 2 +- docs/terms/validation.md | 2 +- docs/terms/verifiable-credential.md | 2 +- docs/terms/verifiable-data.md | 2 +- docs/terms/verification.md | 2 +- docs/terms/verified-data.md | 2 +- docs/terms/verifier-policy.md | 2 +- docs/terms/verifier.md | 10 ++++----- docs/terms/wallet-policy.md | 2 +- docs/terms/wallet.md | 6 +++--- 105 files changed, 175 insertions(+), 178 deletions(-) diff --git a/docs/ssi-standards.md b/docs/ssi-standards.md index 3e36c7e..ab28404 100644 --- a/docs/ssi-standards.md +++ b/docs/ssi-standards.md @@ -3,10 +3,6 @@ id: ssi-standards title: SSI Standards --- - - The purpose of this document is to provide an overview of standards activities for self-sovereign identity (SSI) and their relevance to eSSIF-Lab. ## 1. Introduction diff --git a/docs/terminology-maintenance-script.rieks b/docs/terminology-maintenance-script.rieks index e548121..2e0fc8f 100644 --- a/docs/terminology-maintenance-script.rieks +++ b/docs/terminology-maintenance-script.rieks @@ -174,16 +174,17 @@ with "vocabulary" // 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" +// This has been commented out because for one reason or another, it doesn't work and sometimes makes the script not terminate. +// replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +// with "$1$2" +// replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +// with "$1$2" +// replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +// with "$1$2" +// replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +// with "$1$2" +// replace-regex "^(---\s*\nid:(?:[^%]*\n|(?:glossaryText):.*\n){1,10}[^%]*)%%([^\|]*)\|(?:[^%]*)%%(?=(?:.*[\n\r]){1,10}---)" +// with "$1$2" // Remove all `%%showtext|reftext%%` occurrences in markdown headers replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)" diff --git a/docs/terms/action-type.md b/docs/terms/action-type.md index e97a005..a836583 100644 --- a/docs/terms/action-type.md +++ b/docs/terms/action-type.md @@ -5,8 +5,8 @@ scopeid: essifLab type: concept typeid: action-type stage: draft -hoverText: "Action Type/Class: the specification of properties and characteristics that that Actions must have to qualify as instance of that class; also: the set of Actions that actually have these properties and characteristics." -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." +hoverText: "Action Type/Class: the specification of properties and characteristics that such Actions must have in order to qualify as instance of that class, or the set of Actions that actually have these properties and characteristics." +glossaryText: "the specification of properties and characteristics that that %%actions|action%% must have in order to qualify as instance of that class, or the set of %%actions|action%% that actually have these properties and characteristics." --- :::info Editor's note diff --git a/docs/terms/action.md b/docs/terms/action.md index 9fd9971..e19118f 100644 --- a/docs/terms/action.md +++ b/docs/terms/action.md @@ -6,7 +6,7 @@ type: concept typeid: action stage: draft hoverText: "Action: something that is actually done/executed - by a single Actor (on behalf of a given Party), as a single operation in a specific context." -glossaryText: "something that is actually done/executed - by a single %Actor% (on behalf of a given %Party%), as a single operation in a specific context." +glossaryText: "something that is actually done/executed - by a single %%actor|actor%% (on behalf of a given %%party|party%%), as a single operation in a specific context." --- ### Short Description diff --git a/docs/terms/actor.md b/docs/terms/actor.md index 27d9f7e..158cba7 100644 --- a/docs/terms/actor.md +++ b/docs/terms/actor.md @@ -6,7 +6,7 @@ type: concept typeid: actor stage: draft hoverText: "Actor: Entity that can act (do things), e.g. people, machines, but not Organizations." -glossaryText: "Entity that can act (do things), e.g. people, machines, but not %Organizations%." +glossaryText: "Entity that can act (do things), e.g. people, machines, but not %%organizations|organization%%." --- ### Short Description diff --git a/docs/terms/agent.md b/docs/terms/agent.md index 3f31853..50ea384 100644 --- a/docs/terms/agent.md +++ b/docs/terms/agent.md @@ -6,7 +6,7 @@ type: concept typeid: agent stage: draft hoverText: "Agent (of a Party): an Actor that is executing an Action on behalf of a Party (called the Principal of that Actor)." -glossaryText: "an %Actor% that is executing an %Action% on behalf of a %Party% (called the %Principal% of that %Actor%)." +glossaryText: "an %%actor|actor%% that is executing an %%action|action%% on behalf of a %%party|party%% (called the %%principal|principal%% of that %%actor|actor%%)." --- ### Short Description diff --git a/docs/terms/assertion.md b/docs/terms/assertion.md index f0c404b..7479620 100644 --- a/docs/terms/assertion.md +++ b/docs/terms/assertion.md @@ -6,7 +6,7 @@ type: concept typeid: assertion stage: draft hoverText: "Assertion: a declaration/statement, made by a specific Party, that something is the case." -glossaryText: "a declaration/statement, made by a specific %Party%, that something is the case." +glossaryText: "a declaration/statement, made by a specific %%party|party%%, that something is the case." --- :::info Editor's note diff --git a/docs/terms/author.md b/docs/terms/author.md index 467b273..5e1d2ef 100644 --- a/docs/terms/author.md +++ b/docs/terms/author.md @@ -6,7 +6,7 @@ type: concept typeid: author stage: draft hoverText: "Author (of data/document/file/...): a Party, on whose behalf that data/document/file/... has been created and/or updated." -glossaryText: "a %Party%, on whose behalf that data/document/file/... has been created and/or updated." +glossaryText: "a %%party|party%%, on whose behalf that data/document/file/... has been created and/or updated." --- :::info Editor's note diff --git a/docs/terms/business-transaction.md b/docs/terms/business-transaction.md index 3b80ca3..9842a52 100644 --- a/docs/terms/business-transaction.md +++ b/docs/terms/business-transaction.md @@ -6,7 +6,7 @@ type: concept typeid: business-transaction stage: draft hoverText: "Business Transaction: the exchange of goods, services, funds, or data between some Parties (called Participants of the Transaction)." -glossaryText: "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|party%% (called %%participants|participant%% of the %%transaction|business-transaction%%)." --- import useBaseUrl from '@docusaurus/useBaseUrl' @@ -26,9 +26,9 @@ Explanation required about '%%commitment decision|commitment-decision%%' (i.e. ' 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. +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. +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: @@ -39,9 +39,9 @@ The figure below is a high-level visualization of the filling in and validation *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. +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. +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. diff --git a/docs/terms/colleague.md b/docs/terms/colleague.md index a5a47a1..be506a3 100644 --- a/docs/terms/colleague.md +++ b/docs/terms/colleague.md @@ -6,7 +6,7 @@ type: concept typeid: colleague stage: draft hoverText: "Colleagues: two or more (digital or non-digital) Agents that have the same Principal (i.e. Party on whose behalf they exeucte Actions)." -glossaryText: "two or more (digital or non-digital) %Agents% that have the same %Principal% (i.e. %Party% on whose behalf they exeucte %Actions%)." +glossaryText: "two or more (digital or non-digital) %%agents|agent%% that have the same %%principal|principal%% (i.e. %%party|party%% on whose behalf they exeucte %%actions|action%%)." --- :::info Editor's note diff --git a/docs/terms/commitment-decision.md b/docs/terms/commitment-decision.md index a5bab7e..068efd5 100644 --- a/docs/terms/commitment-decision.md +++ b/docs/terms/commitment-decision.md @@ -6,7 +6,7 @@ type: concept typeid: commitment-decision stage: draft hoverText: "Commitment Decision (of a Party in a Business Transaction): the decision of that Party whether or not to commit to that Business Transaction, i.e. (promise) to fulfill the obligations that the associated Business Transaction Agreement Proposal would impose on that Party once it were signed." -glossaryText: "the decision of that %Party% whether or not to commit to that %Business Transaction%, i.e. (promise) to fulfill the obligations that the associated %Business Transaction Agreement Proposal% would impose on that %Party% once it were signed." +glossaryText: "the decision of that %%party|party%% whether or not to commit to that %%business transaction|business-transaction%%, i.e. (promise) to fulfill the obligations that the associated %%business transaction agreement proposal|business-transaction-agreement-proposal%% would impose on that %%party|party%% once it were signed." --- :::info Editor's note diff --git a/docs/terms/communication-channel.md b/docs/terms/communication-channel.md index 7af9696..d354758 100644 --- a/docs/terms/communication-channel.md +++ b/docs/terms/communication-channel.md @@ -6,7 +6,7 @@ type: concept typeid: communication-channel stage: draft hoverText: "Communication Channel: a (digital or non-digital) means by which two Actors can exchange messages with one another." -glossaryText: "a (digital or non-digital) means by which two %Actors% can exchange messages with one another." +glossaryText: "a (digital or non-digital) means by which two %%actors|actor%% can exchange messages with one another." --- :::info Editor's note diff --git a/docs/terms/communication-session.md b/docs/terms/communication-session.md index f10b306..26181aa 100644 --- a/docs/terms/communication-session.md +++ b/docs/terms/communication-session.md @@ -6,7 +6,7 @@ type: concept typeid: communication-session stage: draft hoverText: "Communication Session: a time interval during which two Actors have an established Communication Channel that does not exist outside of that time interval." -glossaryText: "a time interval during which two %Actors% have an established %Communication Channel% that does not exist outside of that time interval." +glossaryText: "a time interval during which two %%actors|actor%% have an established %%communication channel|communication-channel%% that does not exist outside of that time interval." --- :::info Editor's note diff --git a/docs/terms/concept-file.md b/docs/terms/concept-file.md index 455d1fe..1344f46 100644 --- a/docs/terms/concept-file.md +++ b/docs/terms/concept-file.md @@ -6,7 +6,7 @@ type: concept typeid: concept-file stage: draft hoverText: "Concept-file: a file whose contents defines/specifies a Concept." -glossaryText: "a file whose contents defines/specifies a %Concept%." +glossaryText: "a file whose contents defines/specifies a %%concept|concept%%." --- ### Short Description diff --git a/docs/terms/concept.md b/docs/terms/concept.md index 6359433..8ebc982 100644 --- a/docs/terms/concept.md +++ b/docs/terms/concept.md @@ -6,7 +6,7 @@ type: concept typeid: concept stage: draft hoverText: "Concept: the ideas/thoughts behind a classification of Entities (what makes Entities in that class 'the same')." -glossaryText: "the ideas/thoughts behind a classification of %Entities% (what makes %Entities% in that class 'the same')." +glossaryText: "the ideas/thoughts behind a classification of %%entities|entity%% (what makes %%entities|entity%% in that class 'the same')." --- ### Short Description diff --git a/docs/terms/corpus.md b/docs/terms/corpus.md index a145d41..9834d17 100644 --- a/docs/terms/corpus.md +++ b/docs/terms/corpus.md @@ -6,7 +6,7 @@ type: concept typeid: corpus stage: draft hoverText: "Corpus (of Terminology): the documentation that describes the Knowledge around a set of Terms and Concepts." -glossaryText: "the documentation that describes the %Knowledge% around a set of %Terms% and %Concepts%." +glossaryText: "the documentation that describes the %%knowledge|knowledge%% around a set of %%terms|term%% and %%concepts|concept%%." --- :::info Editor's note diff --git a/docs/terms/credential-catalogue.md b/docs/terms/credential-catalogue.md index 28d2557..2409b90 100644 --- a/docs/terms/credential-catalogue.md +++ b/docs/terms/credential-catalogue.md @@ -6,7 +6,7 @@ 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." +glossaryText: "the capability to register and advertise the information about %%credential types|credential-type%% that their respective %%governing parties|governing-parties%% have decided to disclose so as to enable other %%parties|party%% to decide whether or not it is beneficial for them to use %%credentials|credential%% of such types." --- :::info Editor's note diff --git a/docs/terms/credential-type.md b/docs/terms/credential-type.md index ec75b40..9d10465 100644 --- a/docs/terms/credential-type.md +++ b/docs/terms/credential-type.md @@ -6,12 +6,12 @@ type: concept typeid: credential-type stage: draft hoverText: "Credential Type: the specification of the contents, properties, constraints etc. that Credentials of this type must have/comply with." -glossaryText: "the specification of the contents, properties, constraints etc. that %Credentials% of this type must have/comply with." +glossaryText: "the specification of the contents, properties, constraints etc. that %%credentials|credential%% of this type must have/comply with." --- ### Short Description A **credential-type** is a specification that states -- the contents that %credentials of that kind must or may have; this includes of which kinds of %%assertions (claims, statements)|assertion%% as well as meta-data. +- the contents that %%credentials|credential%% of that kind must or may have; this includes of which kinds of %%assertions (claims, statements)|assertion%% as well as meta-data. - properties Typically, %%parties|party%% that issue %%credentials|credential%% of some %%kind|credential-type%% will advertise the %%credential types|credential-type%% of the %%credentials|credential%% that it may issue. ### Purpose diff --git a/docs/terms/credential.md b/docs/terms/credential.md index c1a5335..a7f1b6b 100644 --- a/docs/terms/credential.md +++ b/docs/terms/credential.md @@ -6,7 +6,7 @@ type: concept typeid: credential stage: draft hoverText: "Credential: data, representing a set of Assertions (claims, statements), authored and signed by, or on behalf of, a specific Party." -glossaryText: "data, representing a set of %Assertions% (claims, statements), authored and signed by, or on behalf of, a specific %Party%." +glossaryText: "data, representing a set of %%assertions|assertion%% (claims, statements), authored and signed by, or on behalf of, a specific %%party|party%%." --- ### Short Description @@ -16,7 +16,7 @@ In physical credentials, such as drivers licenses and passports, proofs of integ In digital credentials, such as (digital) certificates or %%verifiable credentials|verifiable-credential%%, the basic proofs (of provenance and integrity) usually consist of a digital signature of some kind. It therefor only 'works' for as long as the associated private/secret key actually remains a secret of the issuing %%party|party%%. -Credentials whose %%assertions|assertion%% refer to some %%entity|entity%%, e.g. a person, an organization, an animal, a shipment, etc. In such cases, it must be possible for arbitrary %%parties|party%% to identify that %%entity|entity%%, and/or verify an %%assertion|assertion%% by some other %%party|party%% that identifies that %%entity%%. To this end, credentials may contain %%assertions|assertion%% about characteristics of that %%entity|entity%%, the idea being that if a %%party|party%% establishes that some %%entity|entity%% has (a sufficient number of) these characteristics, that %%entity|entity%% is the one bound to the credential. Attributes typically include one or more names, various dates, a photograph, etc. Other attributes might include biometrics, RFID-codes, bar-codes, etc. +Credentials whose %%assertions|assertion%% refer to some %%entity|entity%%, e.g. a person, an organization, an animal, a shipment, etc. In such cases, it must be possible for arbitrary %%parties|party%% to identify that %%entity|entity%%, and/or verify an %%assertion|assertion%% by some other %%party|party%% that identifies that %%entity|entity%%. To this end, credentials may contain %%assertions|assertion%% about characteristics of that %%entity|entity%%, the idea being that if a %%party|party%% establishes that some %%entity|entity%% has (a sufficient number of) these characteristics, that %%entity|entity%% is the one bound to the credential. Attributes typically include one or more names, various dates, a photograph, etc. Other attributes might include biometrics, RFID-codes, bar-codes, etc. The signature on a credential may have other meanings. For example, a %%party|party%% may choose to only sign the credential data if it is convinced of the truth of the statements, in which case the credential 'payload' can be seen as an excerpt of the %%knowledge|knowledge%% of that %%party|party%%. diff --git a/docs/terms/data-collector-policy.md b/docs/terms/data-collector-policy.md index 25b7d55..06aecd6 100644 --- a/docs/terms/data-collector-policy.md +++ b/docs/terms/data-collector-policy.md @@ -6,7 +6,7 @@ type: concept typeid: data-collector-policy stage: draft hoverText: "Data Collector Policy: a Digital Policy that enables an operational Data Collector component to function according to the rules of its Policy Governor." -glossaryText: "a %Digital Policy% that enables an operational %Data Collector% component to function according to the rules of its %Policy Governor%." +glossaryText: "a %%digital policy|digital-policy%% that enables an operational %%data collector|data-collector%% component to function according to the rules of its %%policy governor|policy-governor%%." --- ### Short Description diff --git a/docs/terms/data-collector.md b/docs/terms/data-collector.md index ffdb8a1..7f76821 100644 --- a/docs/terms/data-collector.md +++ b/docs/terms/data-collector.md @@ -6,7 +6,7 @@ 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)." +glossaryText: "a functional component that is capable of collecting data from various %%parties|party%% in the context of some %%business transaction|business-transaction%%, and %%validating|validating%% this data for the purpose of making one (or more) decision(s)." --- ### Short Description @@ -37,7 +37,7 @@ A **Data Collector** is a functional component in the [eSSIF-Lab functional arch - 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%%; + - receive similar requests from its %%peer-party|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 @@ -53,7 +53,7 @@ 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. +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). @@ -66,7 +66,7 @@ In order to make the Data Collector work, a Validation Policy (or Data Collector - 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 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]. @@ -78,9 +78,9 @@ The Policy must be designed in such a way that it is extendable as new features 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. +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’. +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: @@ -89,7 +89,7 @@ As long as data is needed, the Data Collector can intermittently request the ver 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%%. +[^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|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. @@ -101,9 +101,9 @@ TNO to revise the footnote markers [^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. +[^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. +[^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. diff --git a/docs/terms/data-discloser-policy.md b/docs/terms/data-discloser-policy.md index 7733a88..a933445 100644 --- a/docs/terms/data-discloser-policy.md +++ b/docs/terms/data-discloser-policy.md @@ -6,7 +6,7 @@ type: concept typeid: data-discloser-policy stage: draft hoverText: "Data Discloser Policy: a Digital Policy that enables an operational Data Discloser component to function according to the rules of its Policy Governor." -glossaryText: "a %Digital Policy% that enables an operational %Data Discloser% component to function according to the rules of its %Policy Governor%." +glossaryText: "a %%digital policy|digital-policy%% that enables an operational %%data discloser|data-discloser%% component to function according to the rules of its %%policy governor|policy-governor%%." --- ### Short Description diff --git a/docs/terms/data-discloser.md b/docs/terms/data-discloser.md index dae37b5..9efc1ab 100644 --- a/docs/terms/data-discloser.md +++ b/docs/terms/data-discloser.md @@ -6,7 +6,7 @@ type: concept typeid: data-discloser stage: draft hoverText: "Data Discloser: a functional component that is capable of disclosing data to (Agents of) other Parties, e.g. in the form of Credentials." -glossaryText: "a functional component that is capable of disclosing data to (Agents of) other %Parties%, e.g. in the form of %Credentials%." +glossaryText: "a functional component that is capable of disclosing data to (Agents of) other %%parties|party%%, e.g. in the form of %%credentials|credential%%." --- ### Short Description @@ -26,9 +26,9 @@ The purpose of the Data Discloser component is to state the (various, sometimes A **Data Discloser** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) that is capable of stating (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other %%Parties|party%%. ### Functionality -Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term ‘**subject (of a statement of a Party)**’ to refer to the entity that this Party knows to exist, and about whom/which the statement has been made. +Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term '**subject (of a statement of a Party)**' to refer to the entity that this Party knows to exist, and about whom/which the statement has been made. -We will use the term ‘**subject-id (of a statement of a Party)**’ to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not). +We will use the term '**subject-id (of a statement of a Party)**' to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not). Parties need to specify the kinds of credentials they are willing to issue, the class of entities (e.g. people, cars, Organizations) for which it will issue them, and the information schema (structure) that it will use in credentials of such kinds.[^1] This allows the Data Discloser to construct data objects that conform to this information schema, and present it to the Issuer component for actual issuing. diff --git a/docs/terms/definition.md b/docs/terms/definition.md index ca2ae50..1f478a5 100644 --- a/docs/terms/definition.md +++ b/docs/terms/definition.md @@ -6,7 +6,7 @@ type: concept typeid: definition stage: draft hoverText: "Definition: a text that helps Parties to understand the meaning of (and Concepts behind) a Term, ideally in such a way that these Parties can determine whether or not they make the same distinction." -glossaryText: "a text that helps %Parties% to understand the meaning of (and %Concepts% behind) a %Term%, ideally in such a way that these %Parties% can determine whether or not they make the same distinction." +glossaryText: "a text that helps %%parties|party%% to understand the meaning of (and %%concepts|concept%% behind) a %%term|term%%, ideally in such a way that these %%parties|party%% can determine whether or not they make the same distinction." --- ### Short Description diff --git a/docs/terms/dependent.md b/docs/terms/dependent.md index 79edb6d..b49061b 100644 --- a/docs/terms/dependent.md +++ b/docs/terms/dependent.md @@ -6,7 +6,7 @@ type: concept typeid: dependent stage: draft hoverText: "Dependent (of an Party in a Jurisdiction): the Entity for the caring for and/or protecting/guarding/defending of which a Guardianship Relationship has been established with that Entity within that Jurisdiction." -glossaryText: "the %Entity% for the caring for and/or protecting/guarding/defending of which a %Guardianship Relationship% has been established with that %Entity% within that %Jurisdiction%." +glossaryText: "the %%entity|entity%% for the caring for and/or protecting/guarding/defending of which a %%guardianship relationship|guardianship%% has been established with that %%entity|entity%% within that %%jurisdiction|jurisdiction%%." --- :::info Editor's Note diff --git a/docs/terms/dictionary-file.md b/docs/terms/dictionary-file.md index 3332c90..9e6d2a7 100644 --- a/docs/terms/dictionary-file.md +++ b/docs/terms/dictionary-file.md @@ -6,7 +6,7 @@ type: dictionary typeid: dictionary-file stage: draft hoverText: "Dictionary-file: a file whose contents specifies the contents of a Dictionary." -glossaryText: "a file whose contents specifies the contents of a %Dictionary%." +glossaryText: "a file whose contents specifies the contents of a %%dictionary|dictionary%%." --- ### Short Description diff --git a/docs/terms/dictionary.md b/docs/terms/dictionary.md index 5524a39..02e695c 100644 --- a/docs/terms/dictionary.md +++ b/docs/terms/dictionary.md @@ -6,7 +6,7 @@ type: concept typeid: dictionary stage: draft hoverText: "Dictionary: an alphabetically sorted list of Terms with various meanings they may have in different contexts." -glossaryText: "an alphabetically sorted list of %Terms% with various meanings they may have in different contexts." +glossaryText: "an alphabetically sorted list of %%terms|term%% with various meanings they may have in different contexts." --- ### Short Description diff --git a/docs/terms/digital-actor.md b/docs/terms/digital-actor.md index ecdbffc..bd514a0 100644 --- a/docs/terms/digital-actor.md +++ b/docs/terms/digital-actor.md @@ -7,7 +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)." +glossaryText: "an %%actor|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 6acf5c6..2ac45d9 100644 --- a/docs/terms/digital-agent.md +++ b/docs/terms/digital-agent.md @@ -7,7 +7,7 @@ typeid: digital-agent conceptref: ":Agent" stage: draft 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%))." +glossaryText: "an %%agent|agent%% in the digital world (e.g. a running app, or a web-server that is executing an %%action|action%% for a specific %%party|party%% (its %%principal|principal%%))." --- ### Purpose diff --git a/docs/terms/digital-colleague.md b/docs/terms/digital-colleague.md index d8b56f7..d07662d 100644 --- a/docs/terms/digital-colleague.md +++ b/docs/terms/digital-colleague.md @@ -7,7 +7,7 @@ typeid: digital-colleague conceptref: ":Colleague" stage: draft 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%)." +glossaryText: "two or more %%digital agents|digital-agent%% that all have the same %%principal|principal%% (i.e. %%party|party%% on whose behalf they exeucte %%actions|action%%)." --- ### Purpose diff --git a/docs/terms/digital-communication-channel.md b/docs/terms/digital-communication-channel.md index 1fa6702..8fe7aba 100644 --- a/docs/terms/digital-communication-channel.md +++ b/docs/terms/digital-communication-channel.md @@ -6,7 +6,7 @@ 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" +glossaryText: "a digital means by which two %%digital actors|digital-actor%% can exchange messages with one another" --- :::info Editor's note diff --git a/docs/terms/digital-policy.md b/docs/terms/digital-policy.md index 0a4bd06..410a598 100644 --- a/docs/terms/digital-policy.md +++ b/docs/terms/digital-policy.md @@ -7,7 +7,7 @@ typeid: digital-policy conceptref: ":Policy" stage: draft 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)." +glossaryText: "a machine-readable %%policy|policy%% that enables %%digital agents|digital-agent%% whose %%principal|principal%% is the %%policy|policy%%'s %%governor|governance%%, to execute %%actions|action%% of such types in compliance with that %%policy|policy%% (i.e.: according to the rules, working-instructions, preferences and other guidance specified therein)." --- :::info Editor's note diff --git a/docs/terms/employee.md b/docs/terms/employee.md index 1faae2b..384bd29 100644 --- a/docs/terms/employee.md +++ b/docs/terms/employee.md @@ -6,7 +6,7 @@ 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 (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%)." +glossaryText: "an %%actor|actor%% for whom/which it is realistic that it might execute %%actions|action%% on behalf of that %%party|party%% (called the %%employer|employer%% of that %%actor|actor%%)." --- :::info Editor's note diff --git a/docs/terms/employer.md b/docs/terms/employer.md index f14403b..3b99bd6 100644 --- a/docs/terms/employer.md +++ b/docs/terms/employer.md @@ -6,7 +6,7 @@ type: concept typeid: employer stage: draft 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%." +glossaryText: "a %%party|party%% on whose behalf this %%actor|actor%% (called an %%employee|employee%% of that %%party|party%%) might execute %%actions|action%%." --- :::info Editor's note diff --git a/docs/terms/essif-glue.md b/docs/terms/essif-glue.md index 1d3b48a..5229d39 100644 --- a/docs/terms/essif-glue.md +++ b/docs/terms/essif-glue.md @@ -6,7 +6,7 @@ type: concept typeid: essif-glue stage: draft 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." +glossaryText: "interface layer that allows components with %%transaction data collector|transaction-data-collector%% and/or %%transaction data discloser|transaction-data-discloser%% functionality to use the %%wallet|wallet%%, %%holder|holder%%, %%issuer|issuer%% and %%verifier|verifier%% functionalities." --- ### Short Description diff --git a/docs/terms/glossary-file.md b/docs/terms/glossary-file.md index 74799b0..42485ac 100644 --- a/docs/terms/glossary-file.md +++ b/docs/terms/glossary-file.md @@ -6,7 +6,7 @@ type: glossary typeid: glossary-file stage: draft hoverText: "Glossary-file: a file whose contents defines/specifies a Glossary." -glossaryText: "a file whose contents defines/specifies a %Glossary%." +glossaryText: "a file whose contents defines/specifies a %%glossary|glossary%%." --- ### Short Description diff --git a/docs/terms/glossary.md b/docs/terms/glossary.md index e344821..89494b3 100644 --- a/docs/terms/glossary.md +++ b/docs/terms/glossary.md @@ -6,7 +6,7 @@ type: concept typeid: glossary stage: draft 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." +glossaryText: "an alphabetically sorted list of %%terms|term%% with the (single) meaning it has in (at least) one context." --- ### Short Description diff --git a/docs/terms/governor.md b/docs/terms/governor.md index df398b1..46a2099 100644 --- a/docs/terms/governor.md +++ b/docs/terms/governor.md @@ -6,7 +6,7 @@ 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." +glossaryText: "the role that a %%party|party%% assumes as it is governing or overseeing the control and direction of something." --- ### Short Description diff --git a/docs/terms/guardian.md b/docs/terms/guardian.md index baa0cd2..95be281 100644 --- a/docs/terms/guardian.md +++ b/docs/terms/guardian.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "the %%party|party%% that is tasked to care for and/or protect/guard/defend that %%entity|entity%%, for the purpose of which a %%guardianship relationship|guardianship%% has been established within that %%jurisdiction|jurisdiction%%." --- :::info Editor's Note diff --git a/docs/terms/guardianship-type.md b/docs/terms/guardianship-type.md index 731b7c5..08314fa 100644 --- a/docs/terms/guardianship-type.md +++ b/docs/terms/guardianship-type.md @@ -6,7 +6,7 @@ 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." +glossaryText: "a class of %%guardianships|guardianship%% (relationships) within the %%jurisdiction|jurisdiction%% that has defined it." --- ### Short Description diff --git a/docs/terms/guardianship.md b/docs/terms/guardianship.md index 0815682..66583f5 100644 --- a/docs/terms/guardianship.md +++ b/docs/terms/guardianship.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "the rights and duties of that %%party|party%%, defined and enforced in that %%jurisdiction|jurisdiction%%, for the purpose of caring for and/or protecting/guarding/defending that %%entity|entity%%." --- :::info Editor's Note @@ -18,7 +18,7 @@ TNO to revise all below texts. 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%%'. +We may use the phrase %%natural guardianship|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. diff --git a/docs/terms/holder-policy.md b/docs/terms/holder-policy.md index 58bd580..5215392 100644 --- a/docs/terms/holder-policy.md +++ b/docs/terms/holder-policy.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "a %%digital policy|digital-policy%% that enables an operational %%holder|holder%% component to function according to the rules of its %%policy governor|policy-governor%%." --- :::info Editor's note diff --git a/docs/terms/holder.md b/docs/terms/holder.md index 2f773f7..a7f6c30 100644 --- a/docs/terms/holder.md +++ b/docs/terms/holder.md @@ -6,11 +6,11 @@ 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." +glossaryText: "the capability to handle presentation requests from a %%peer agent|peer-agent%%, produce the requested data (a presentation) according to its %%principal|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 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. +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. :::info Editor's note TNO (or others) to provide additional content of this file. @@ -26,12 +26,12 @@ A **Holder** is a component in the [eSSIF-Lab functional architecture](../functi 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 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 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 its Principal, which specifies e.g.: -- whether or not credentials may be collected ‘on the fly’; +- 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. \ No newline at end of file diff --git a/docs/terms/identifier.md b/docs/terms/identifier.md index bbac987..571f924 100644 --- a/docs/terms/identifier.md +++ b/docs/terms/identifier.md @@ -6,7 +6,7 @@ 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)." +glossaryText: "a character string that is being used for the identification of some %%entity|entity%% (yet may refer to 0, 1, or more %%entities|entity%%, depending on the context within which it is being used)." --- ### Short Description @@ -35,7 +35,7 @@ The lack of (identifying) scopes of identification becomes an issue when a %%par 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). +[^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. diff --git a/docs/terms/issuer-policy.md b/docs/terms/issuer-policy.md index 4d1ae83..694d32a 100644 --- a/docs/terms/issuer-policy.md +++ b/docs/terms/issuer-policy.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "a %%digital policy|digital-policy%% that enables an operational %%issuer|issuer%% component to function according to the rules of its %%policy governor|policy-governor%%." --- :::info Editor's note diff --git a/docs/terms/issuer.md b/docs/terms/issuer.md index 865c480..b97f41b 100644 --- a/docs/terms/issuer.md +++ b/docs/terms/issuer.md @@ -6,7 +6,7 @@ type: concept typeid: issuer stage: draft 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." +glossaryText: "the capability to construct %%credentials|credential%% from data objects, according to the content of its %%principal|principal%%'s %%issuer|issuer%%-Policy (specifically regarding the way in which the %%credential|credential%% is to be digitally signed), and pass it to the %%wallet|wallet%%-component of its %%principal|principal%% allowing it to be issued." --- :::info Editor's note @@ -24,13 +24,13 @@ A **Issuer** is a component in the [eSSIF-Lab functional architecture](../functi ### Functionality -The purpose of the Issuer component is to issue ‘credentials’, i.e. digital constructs that contain +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 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|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 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. +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|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). @@ -38,6 +38,6 @@ After the issuer has created a credential (in one or more formats), it checks th ----- -[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.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. diff --git a/docs/terms/jurisdiction-governor.md b/docs/terms/jurisdiction-governor.md index 2ecdfc7..cda5869 100644 --- a/docs/terms/jurisdiction-governor.md +++ b/docs/terms/jurisdiction-governor.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "the %%party|party%% that operates the %%legal system|legal-system%% of that %%jurisdiction|jurisdiction%%." --- :::info Editor's note diff --git a/docs/terms/jurisdiction.md b/docs/terms/jurisdiction.md index 94b1112..9727874 100644 --- a/docs/terms/jurisdiction.md +++ b/docs/terms/jurisdiction.md @@ -6,7 +6,7 @@ type: concept typeid: jurisdiction stage: draft 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." +glossaryText: "the composition of a %%legal system|legal-system%% (legislation, enforcement thereof, and conflict resolution), a %%party|party%% that governs that %%legal system|legal-system%%, a scope within which that %%legal system|legal-system%% is operational, and one or more %%objectives|objective%% for the purpose of which the %%legal system|legal-system%% is operated." --- ### Short Description diff --git a/docs/terms/knowledge-governor.md b/docs/terms/knowledge-governor.md index 3186411..821c378 100644 --- a/docs/terms/knowledge-governor.md +++ b/docs/terms/knowledge-governor.md @@ -6,7 +6,7 @@ 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." +glossaryText: "the %%party|party%% that is 1-1 associated with that knowledge." --- :::info Editor's note diff --git a/docs/terms/knowledge.md b/docs/terms/knowledge.md index fac2939..299e4bc 100644 --- a/docs/terms/knowledge.md +++ b/docs/terms/knowledge.md @@ -6,7 +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%." +glossaryText: "The (intangible) sum of what is known by a specific %%party|party%%, as well as the familiarity, awareness or understanding of someone or something by that %%party|party%%." --- ### Short Description @@ -23,4 +23,4 @@ The intangible sum of what is known to some %%party|party%%, as well as the fami ### Notes - '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. +- 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 2d56007..f55de71 100644 --- a/docs/terms/legal-entity.md +++ b/docs/terms/legal-entity.md @@ -6,7 +6,7 @@ type: term typeid: legal-entity stage: draft 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%." +glossaryText: "an %%entity|entity%% that is known by, recognized to exist, and registered in that %%jurisdiction|jurisdiction%%." --- ### Short Description diff --git a/docs/terms/legal-jurisdiction.md b/docs/terms/legal-jurisdiction.md index 451daa6..a31ff28 100644 --- a/docs/terms/legal-jurisdiction.md +++ b/docs/terms/legal-jurisdiction.md @@ -7,7 +7,7 @@ typeid: legal-jurisdiction conceptref: essifLab:jurisdiction stage: draft hoverText: "Legal Jurisdiction: a Jurisdiction that is governed/operated by a governmental body." -glossaryText: "a %Jurisdiction% that is governed/operated by a governmental body." +glossaryText: "a %%jurisdiction|jurisdiction%% that is governed/operated by a governmental body." --- ### Short Description diff --git a/docs/terms/legal-system.md b/docs/terms/legal-system.md index 3fdbe36..c46b734 100644 --- a/docs/terms/legal-system.md +++ b/docs/terms/legal-system.md @@ -10,7 +10,7 @@ glossaryText: "a system in which rules are defined, and mechanisms for their enf --- ### 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|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. +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. diff --git a/docs/terms/mental-model.md b/docs/terms/mental-model.md index 23ee1f9..b7492b0 100644 --- a/docs/terms/mental-model.md +++ b/docs/terms/mental-model.md @@ -7,7 +7,7 @@ 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." +glossaryText: "a casual and formal description (Pattern) of a set 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 diff --git a/docs/terms/objective.md b/docs/terms/objective.md index 3f1970f..86a0b24 100644 --- a/docs/terms/objective.md +++ b/docs/terms/objective.md @@ -6,7 +6,7 @@ type: concept typeid: objective stage: draft 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)." +glossaryText: "Something toward which a %%party|party%% directs effort (an aim, goal, or end of action)." --- ### Short Description diff --git a/docs/terms/organization.md b/docs/terms/organization.md index be8ac53..03ddd43 100644 --- a/docs/terms/organization.md +++ b/docs/terms/organization.md @@ -6,7 +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%." +glossaryText: "a group of people that work to realize one or more %%objectives|objective%%." --- ### Short Description diff --git a/docs/terms/owned.md b/docs/terms/owned.md index e2622b9..fec8afe 100644 --- a/docs/terms/owned.md +++ b/docs/terms/owned.md @@ -6,7 +6,7 @@ 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." +glossaryText: "an %%entity|entity%% over which another %%entity|entity%% (its %%owner|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|jurisdiction%%, and by its rules." --- see: %%ownership|ownership%% diff --git a/docs/terms/owner.md b/docs/terms/owner.md index ded97cd..a10cbf3 100644 --- a/docs/terms/owner.md +++ b/docs/terms/owner.md @@ -6,7 +6,7 @@ type: concept typeid: owner stage: draft 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%." +glossaryText: "the role that a %%party|party%% performs when it is exercizing its legal, rightful or natural title to control that %%entity|entity%%." --- ### Short Description diff --git a/docs/terms/ownership.md b/docs/terms/ownership.md index d06590b..3373966 100644 --- a/docs/terms/ownership.md +++ b/docs/terms/ownership.md @@ -6,14 +6,14 @@ 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%." +glossaryText: "the rights and duties, as defined and enforced in that %%jurisdiction|jurisdiction%%, of that %%entity|entity%% to enjoy, dispose of, and control the other %%entity|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%%'. +We may use the phrase %%natural ownership|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). diff --git a/docs/terms/participant.md b/docs/terms/participant.md index a903584..d0d1c5f 100644 --- a/docs/terms/participant.md +++ b/docs/terms/participant.md @@ -7,7 +7,7 @@ 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%." +glossaryText: "a %%party|party%% is negotiating (or has negotiated) a %%business transaction agreement|business-transaction-agreement%%." --- ### Purpose diff --git a/docs/terms/party.md b/docs/terms/party.md index 4042eaf..4032424 100644 --- a/docs/terms/party.md +++ b/docs/terms/party.md @@ -6,7 +6,7 @@ type: concept typeid: Party stage: draft 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." +glossaryText: "an %%entity|entity%% that has %%objectives|objective%%, %%knowledge|knowledge%% about what exists, rules that (should) apply, and some capability that allows it to reason, make decisions, generate and maintain %%knowledge|knowledge%% etc. in a %%self|self%%-Sovereign fashion; %%humans|humans%% and %%organizations|organization%% ar the typical examples." --- ### Short Description diff --git a/docs/terms/pattern-file.md b/docs/terms/pattern-file.md index ed32f4b..2fa21e6 100644 --- a/docs/terms/pattern-file.md +++ b/docs/terms/pattern-file.md @@ -6,7 +6,7 @@ type: pattern typeid: pattern-file stage: draft hoverText: "Pattern-file: a file whose contents describes/documents a Pattern." -glossaryText: "a file whose contents describes/documents a %Pattern%." +glossaryText: "a file whose contents describes/documents a %%pattern|pattern%%." --- ### Short Description diff --git a/docs/terms/pattern-guardianship.md b/docs/terms/pattern-guardianship.md index 5e80877..fd51439 100644 --- a/docs/terms/pattern-guardianship.md +++ b/docs/terms/pattern-guardianship.md @@ -20,12 +20,12 @@ The **Guardianship pattern** captures the concepts and relations that explain ho 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 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%%”. +- “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 diff --git a/docs/terms/pattern-party-actor-action.md b/docs/terms/pattern-party-actor-action.md index 9eaaef7..c4c081c 100644 --- a/docs/terms/pattern-party-actor-action.md +++ b/docs/terms/pattern-party-actor-action.md @@ -59,19 +59,19 @@ Here is a visual representation of this pattern, using the following [notations src={useBaseUrl('images/patterns/pattern-party-actor-action.png')} /> -It shows that %%Parties|party%% (humans, organizations) perform %%Actions|action%% for the purpose of realizing their %%Objectives|objective%%. %%Parties|party%% are not considered to actually execute such %%Actions|action%%; they have (human and non-human) %%Actors|actor%% that work for them, execute such %%Actions|action%%, using the %%party|party%%’s %%Knowledge|knowledge%% as the (authoritative) guidance for executing the %%Actions|action%% (as well as any other relevant %%Knowledge|knowledge%% they can access). +It shows that %%Parties|party%% (humans, organizations) perform %%Actions|action%% for the purpose of realizing their %%Objectives|objective%%. %%Parties|party%% are not considered to actually execute such %%Actions|action%%; they have (human and non-human) %%Actors|actor%% that work for them, execute such %%Actions|action%%, using the %%party|party%%'s %%Knowledge|knowledge%% as the (authoritative) guidance for executing the %%Actions|action%% (as well as any other relevant %%Knowledge|knowledge%% they can access). The essential characteristic of %%Parties|party%% is their 1-1 link with %%Knowledge|knowledge%%, which they continually update and use e.g. for reasoning, decision making, and determining e.g. what to do, when, and with whom. %%Knowledge|knowledge%% not only includes (observable) facts, but also opinions, e.g. regarding the %%Entities|entity%% it knows to exist, relations between them, and rules (constraints, [logic](https://en.wikipedia.org/wiki/Logic)[^1]) that can be used to classify and reasoning about them, and for making decisions. -Perhaps the most important idea in this pattern is that our %%party|party%% concept is not considered to (be able to) act, and they need %%Actors|actor%% (i.e. %%Entities|entity%% that _can_ act) to act on their behalf and thus make them perform. This does, however, not preclude having %%Entities|entity%% that are both %%party|party%% and %%Actor|actor%% - e.g. humans - and that such %%Entities|entity%% can act on their ‘own’ behalf. And we can continue to use the commonly used form of speech in which a %%party|party%% performs some Action by realizing that this means that there is (at least) one %%Actor|actor%% that is actually executing that %%Action|action%%. +Perhaps the most important idea in this pattern is that our %%party|party%% concept is not considered to (be able to) act, and they need %%Actors|actor%% (i.e. %%Entities|entity%% that _can_ act) to act on their behalf and thus make them perform. This does, however, not preclude having %%Entities|entity%% that are both %%party|party%% and %%Actor|actor%% - e.g. humans - and that such %%Entities|entity%% can act on their 'own' behalf. And we can continue to use the commonly used form of speech in which a %%party|party%% performs some Action by realizing that this means that there is (at least) one %%Actor|actor%% that is actually executing that %%Action|action%%. In this pattern, %%Knowledge|knowledge%% takes center stage. %%Knowledge|knowledge%% contains %%Objectives|objective%% to be realized and managed. This not only triggers all sorts of %%Actions|action%% to be performed, but also guides their execution in terms of when an Action should start, when it terminates, which %%Actors|actor%% qualify for executing it, etc. Everything that is specific for a %%party|party%% is reflected in its %%Knowledge|knowledge%%. This works well for human beings, which are both a %%party|party%% and an %%Actor|actor%%. So a human being can act, implying itself as an %%Actor|actor%%, and using its personal %%Knowledge|knowledge%% as guidance. The model also works when a human being (as a %%party|party%%) may hire someone else (as an %%Actor|actor%%), e.g. to fill in his tax return form. This other is guided by the %%Knowledge|knowledge%% of the human being that hired him, and uses its own %%Knowledge|knowledge%% for the details of filling in the tax form. -It also works well for organizations, which are typically companies, enterprises, governments or parts thereof, i.e. groups of human beings and possibly other %%Actors|actor%% that, as a group, fit the criteria for being a %%party|party%%. This group of %%Actors|actor%% would typically work to realize the organization’s %%Objectives|objective%%, being guided by the organization’s %%Knowledge|knowledge%% (registrations, policies, etc.). Like human beings, an organization may (have an appropriate %%Actor|actor%%) decide to hire or fire %%Actors|actor%% for longer or shorter periods. +It also works well for organizations, which are typically companies, enterprises, governments or parts thereof, i.e. groups of human beings and possibly other %%Actors|actor%% that, as a group, fit the criteria for being a %%party|party%%. This group of %%Actors|actor%% would typically work to realize the organization's %%Objectives|objective%%, being guided by the organization's %%Knowledge|knowledge%% (registrations, policies, etc.). Like human beings, an organization may (have an appropriate %%Actor|actor%%) decide to hire or fire %%Actors|actor%% for longer or shorter periods. -%%Parties|party%% set %%Objectives|objective%% that they seek to achieve, the most basic of which perhaps is its mission, or its ‘raison d'être’, to the realization of which all of its %%Actions|action%% are (ultimately) aimed. Every Objective is owned by a single %%party|party%% (we do not consider ‘shared objectives’[^2]). +%%Parties|party%% set %%Objectives|objective%% that they seek to achieve, the most basic of which perhaps is its mission, or its 'raison d'être', to the realization of which all of its %%Actions|action%% are (ultimately) aimed. Every Objective is owned by a single %%party|party%% (we do not consider 'shared objectives'[^2]). --- ### Footnotes diff --git a/docs/terms/pattern.md b/docs/terms/pattern.md index 354a21c..4b15447 100644 --- a/docs/terms/pattern.md +++ b/docs/terms/pattern.md @@ -6,7 +6,7 @@ type: concept typeid: pattern stage: draft hoverText: "Pattern: A limited set of Concepts (ideas), relations between them, and constraints, such that together they form a coherent and consistent whole." -glossaryText: "A limited set of %Concepts% (ideas), relations between them, and constraints, such that together they form a coherent and consistent whole." +glossaryText: "A limited set of %%concepts|concept%% (ideas), relations between them, and constraints, such that together they form a coherent and consistent whole." --- ### Short Description @@ -26,12 +26,12 @@ a limited set of %%concepts|concept%% (preferably not exceeding 7+/-2)[^1], rela ### 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. +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. So a pattern requires careful construction, that allows the choices for its elements to be validated against many use-cases. Such validation instills trust that our model elements (concepts, relations, rules) are well-chosen. It also provides us with the experience (usually after some time) that it has made our thinking easier, and we are better equipped to resolve issues. The careful construction is comparable to a quest: it takes time, multiple versions, and careful reflection. And it needs continuous validation of its parts, by throwing use-cases at it and verifying that the model can describe such cases, and do some reasoning with them. -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. +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. +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. diff --git a/docs/terms/peer-actor.md b/docs/terms/peer-actor.md index 87916cf..26744df 100644 --- a/docs/terms/peer-actor.md +++ b/docs/terms/peer-actor.md @@ -7,7 +7,7 @@ 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%." +glossaryText: "the %%actor|actor%% with whom/which this other %%actor|actor%% is communicating in that %%communication session|communication-session%%." --- :::info Editors' note diff --git a/docs/terms/peer-agent.md b/docs/terms/peer-agent.md index 75c3a01..9b0bfdf 100644 --- a/docs/terms/peer-agent.md +++ b/docs/terms/peer-agent.md @@ -7,7 +7,7 @@ typeid: peer-agent conceptref: essifLab:Agent stage: draft 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%." +glossaryText: "the %%agent|agent%% with whom/which this other %%agent|agent%% is communicating in that %%communication session|communication-session%%." --- :::info Editors' note diff --git a/docs/terms/peer-party.md b/docs/terms/peer-party.md index 7fd6ebd..73adf12 100644 --- a/docs/terms/peer-party.md +++ b/docs/terms/peer-party.md @@ -7,7 +7,7 @@ typeid: peer-party conceptref: essifLab:party stage: draft 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%." +glossaryText: "a %%party|party%% that also participates in that %%business transaction|business-transaction%%." --- ### Purpose diff --git a/docs/terms/policy-governor.md b/docs/terms/policy-governor.md index 8d103d8..25daa00 100644 --- a/docs/terms/policy-governor.md +++ b/docs/terms/policy-governor.md @@ -6,7 +6,7 @@ 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." +glossaryText: "the %%party|party%% that is the %%owner|owner%% of the %%policy|policy%% and hence decides what goes in it and what not." --- :::info Editor's note diff --git a/docs/terms/policy.md b/docs/terms/policy.md index 0fc8a4d..742f9d0 100644 --- a/docs/terms/policy.md +++ b/docs/terms/policy.md @@ -6,7 +6,7 @@ type: concept typeid: policy stage: draft 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%." +glossaryText: "a (set of) rules, working-instructions, preferences and other guidance for the execution of one or more kinds of %%actions|action%%, that %%agents|agent%% (a) have access to, (b) can interpret as intended by their %%principal|principal%% (i.e. policy %%owner|owner%%) and (c) must use when executing such %%actions|action%%." --- ### Short Description diff --git a/docs/terms/presentation-request.md b/docs/terms/presentation-request.md index 1f4bfd2..c0f0827 100644 --- a/docs/terms/presentation-request.md +++ b/docs/terms/presentation-request.md @@ -6,7 +6,7 @@ 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 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." +glossaryText: "a (signed) digital message that a %%verifier|verifier%% component sends to a %%holder|holder%% component asking for specific data from one or more %%verifiable credentials|verifiable-credential%% that are issued by specific Parties." --- :::info Editor's note diff --git a/docs/terms/presentation.md b/docs/terms/presentation.md index 34374e0..9dc4fc6 100644 --- a/docs/terms/presentation.md +++ b/docs/terms/presentation.md @@ -6,7 +6,7 @@ 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." +glossaryText: "a (signed) digital message that a %%holder|holder%% component may send to a %%verifier|verifier%% component that contains data derived from one or more %%verifiable credentials|verifiable-credential%% (that (a %%colleague|colleague%% component of) the %%holder|holder%% component has received from %%issuer|issuer%% components of one or more %%parties|party%%), as a response to a specific %%presentation request|presentation-request%% of a %%Verifier|verifier%% component." --- ### Short Description diff --git a/docs/terms/principal.md b/docs/terms/principal.md index 8aa6f76..9d16140 100644 --- a/docs/terms/principal.md +++ b/docs/terms/principal.md @@ -6,7 +6,7 @@ type: concept typeid: principal stage: draft 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%)." +glossaryText: "the %%party|party%% for whom, or on behalf of whom, the %%actor|actor%% is executing an %%action|action%% (this %%actor|actor%% is then called an %%agent|agent%% of that %%party|party%%)." --- :::info Editor's noet @@ -14,7 +14,7 @@ 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 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%%, +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. diff --git a/docs/terms/risk.md b/docs/terms/risk.md index 27d11e4..d484840 100644 --- a/docs/terms/risk.md +++ b/docs/terms/risk.md @@ -6,7 +6,7 @@ type: concept typeid: risk stage: draft 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%." +glossaryText: "the deviation of the expected realization (e.g. results) of that %%party|party%%'s %%objective|objective%%." --- :::info Editor's note diff --git a/docs/terms/scope-file.md b/docs/terms/scope-file.md index 5a7a04c..122e00f 100644 --- a/docs/terms/scope-file.md +++ b/docs/terms/scope-file.md @@ -6,7 +6,7 @@ type: concept typeid: scope-file stage: draft hoverText: "Scope-file: a file whose contents defines/specifies a Scope." -glossaryText: "a file whose contents defines/specifies a %Scope%." +glossaryText: "a file whose contents defines/specifies a %%scope|scope%%." --- ### Short Description diff --git a/docs/terms/scope.md b/docs/terms/scope.md index 8506455..8337829 100644 --- a/docs/terms/scope.md +++ b/docs/terms/scope.md @@ -6,7 +6,7 @@ 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)." +glossaryText: "the extent of the area or subject matter (which we use to define %%patterns|pattern%%, %%concepts|concept%%, %%terms|term%% and %%glossaries|glossary%% in)." --- ### Short Description diff --git a/docs/terms/semantics.md b/docs/terms/semantics.md index 67cbd76..1d6f2aa 100644 --- a/docs/terms/semantics.md +++ b/docs/terms/semantics.md @@ -6,7 +6,7 @@ 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." +glossaryText: "a mapping between the (tangible/textual) %%terms|term%% and (intangible) ideas/Concepts - their meaning." --- ### Short Description diff --git a/docs/terms/ssi-agent.md b/docs/terms/ssi-agent.md index 03bc366..252b6be 100644 --- a/docs/terms/ssi-agent.md +++ b/docs/terms/ssi-agent.md @@ -7,7 +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%." +glossaryText: "a %%digital agent|digital-agent%% that provides one or more of the %%ssi|ssi%% functionalities (Issuer, %%holder|holder%%, %%verifier|verifier%%, %%wallet|wallet%%) to its %%principal|principal%%." --- ### Short Description diff --git a/docs/terms/term-file.md b/docs/terms/term-file.md index 76379bd..8516075 100644 --- a/docs/terms/term-file.md +++ b/docs/terms/term-file.md @@ -6,7 +6,7 @@ type: concept typeid: term-file stage: draft hoverText: "Term-file: a file whose contents defines/specifies a Term." -glossaryText: "a file whose contents defines/specifies a %Term%." +glossaryText: "a file whose contents defines/specifies a %%term|term%%." --- ### Short Description diff --git a/docs/terms/term.md b/docs/terms/term.md index 2b42176..27b44ae 100644 --- a/docs/terms/term.md +++ b/docs/terms/term.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "a word or phrase that is used in at least one %%scope|scope%%/context to refer to a specific %%concept|concept%%." --- ### Short Description diff --git a/docs/terms/terminology.md b/docs/terms/terminology.md index 9ad97ad..8ed5957 100644 --- a/docs/terms/terminology.md +++ b/docs/terms/terminology.md @@ -6,7 +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)." +glossaryText: "the set of %%terms|term%% 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 index ca6fde7..4c47155 100644 --- a/docs/terms/transaction-agreement.md +++ b/docs/terms/transaction-agreement.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "the set of rules that specify the rights (expectations) and duties (obligations) of %%participants|participant%% towards one another in the context of a specific %%business transaction|business-transaction%%." --- :::info Editor's note diff --git a/docs/terms/transaction-data-collector-policy.md b/docs/terms/transaction-data-collector-policy.md index 7ee3c14..03fd7e4 100644 --- a/docs/terms/transaction-data-collector-policy.md +++ b/docs/terms/transaction-data-collector-policy.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "a %%digital policy|digital-policy%% that enables an operational %%transaction data collector|transaction-data-collector%% component to function according to the rules of its %%policy governor|policy-governor%%." --- ### Short Description diff --git a/docs/terms/transaction-data-collector.md b/docs/terms/transaction-data-collector.md index afcbc81..7ea7032 100644 --- a/docs/terms/transaction-data-collector.md +++ b/docs/terms/transaction-data-collector.md @@ -6,7 +6,7 @@ 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." +glossaryText: "a functional component that collects sufficient and %%validated data|validated-data%% for deciding whether or not a request (typically for a product or a service) is to be serviced." --- ### Short Description @@ -53,7 +53,7 @@ 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%%. +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). @@ -66,7 +66,7 @@ In order to make the Transaction Data Collector work, a Validation Policy (or Tr - 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 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]. @@ -78,9 +78,9 @@ The Policy must be designed in such a way that it is extendable as new features 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. +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’. +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: @@ -101,9 +101,9 @@ TNO to revise the footnote markers [^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. +[^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. +[^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. diff --git a/docs/terms/transaction-data-discloser-policy.md b/docs/terms/transaction-data-discloser-policy.md index 7726b16..28ccae7 100644 --- a/docs/terms/transaction-data-discloser-policy.md +++ b/docs/terms/transaction-data-discloser-policy.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "a %%digital policy|digital-policy%% that enables an operational %%transaction data discloser|transaction-data-discloser%% component to function according to the rules of its %%policy governor|policy-governor%%." --- ### Short Description diff --git a/docs/terms/transaction-data-discloser.md b/docs/terms/transaction-data-discloser.md index fd4f3d4..96f6a8b 100644 --- a/docs/terms/transaction-data-discloser.md +++ b/docs/terms/transaction-data-discloser.md @@ -26,9 +26,9 @@ The purpose of the Transaction Data Discloser component is to state the (various 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. +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). +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. diff --git a/docs/terms/transaction-form.md b/docs/terms/transaction-form.md index 438615e..a7c1e9b 100644 --- a/docs/terms/transaction-form.md +++ b/docs/terms/transaction-form.md @@ -6,7 +6,7 @@ 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." +glossaryText: "the specification of the set of data that this %%party|party%% needs to (a) commit to a (proposed) %%business transaction|business-transaction%% of that kind, (b) fulfill its duties/obligations and (c) escalate if necessary." --- :::info Editor's note diff --git a/docs/terms/transaction-id.md b/docs/terms/transaction-id.md index d5adebd..c59137f 100644 --- a/docs/terms/transaction-id.md +++ b/docs/terms/transaction-id.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "character string that this %%participant|participant%% uses to identify, and refer to, that %%business transaction|business-transaction%%." --- :::info Editor's note diff --git a/docs/terms/transaction-proposal.md b/docs/terms/transaction-proposal.md index 0c2760d..81b9bdd 100644 --- a/docs/terms/transaction-proposal.md +++ b/docs/terms/transaction-proposal.md @@ -6,7 +6,7 @@ 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%)" +glossaryText: "a %%transaction agreement|transaction-agreement%% that is 'in-the-making' (ranging from an empty document to a document that would be a %%transaction agreement|transaction-agreement%% if it were signed by all %%participants|participant%%)" --- :::info Editor's note diff --git a/docs/terms/transaction-request.md b/docs/terms/transaction-request.md index 8f36890..40323ae 100644 --- a/docs/terms/transaction-request.md +++ b/docs/terms/transaction-request.md @@ -6,7 +6,7 @@ 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." +glossaryText: "a message, send by a requesting %%party|party%% to a providing %%party|party%%, that initiates the negotiation of a new %%transaction agreement|transaction-agreement%% between these %%parties|party%% for the provisioning of a specific product or service." --- :::info Editor's note diff --git a/docs/terms/transaction-result-dispatcher.md b/docs/terms/transaction-result-dispatcher.md index 516be7d..43a20a8 100644 --- a/docs/terms/transaction-result-dispatcher.md +++ b/docs/terms/transaction-result-dispatcher.md @@ -25,9 +25,9 @@ The purpose of the TRD component is to state the (various, sometimes intermediar A **Transaction Result Dispatcher (TRD)** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) that is capable of stating (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other %%Parties|party%%. ## Functionality -Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term ‘**subject (of a statement of a Party)**’ to refer to the entity that this Party knows to exist, and about whom/which the statement has been made. +Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term '**subject (of a statement of a Party)**' to refer to the entity that this Party knows to exist, and about whom/which the statement has been made. -We will use the term ‘**subject-id (of a statement of a Party)**’ to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not). +We will use the term '**subject-id (of a statement of a Party)**' to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not). Parties need to specify the kinds of credentials they are willing to issue, the class of entities (e.g. people, cars, Organizations) for which it will issue them, and the information schema (structure) that it will use in credentials of such kinds.[^1] This allows the TRD to construct data objects that conform to this information schema, and present it to the Issuer component for actual issuing. diff --git a/docs/terms/transaction-type.md b/docs/terms/transaction-type.md index b9f7a1f..2cd1aff 100644 --- a/docs/terms/transaction-type.md +++ b/docs/terms/transaction-type.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "the %%policy|policy%%, %%governed|governed%% by that %%party|party%%, and other necessary artifacts (e.g. a %%transaction form|transaction-form%%) that provide an %%actor|actor%% with all necessary means to conduct a %%transaction|business-transaction%% of this type on behalf of that %%party|party%%." --- :::info Editor's note diff --git a/docs/terms/trd-policy.md b/docs/terms/trd-policy.md index b51312e..043f44f 100644 --- a/docs/terms/trd-policy.md +++ b/docs/terms/trd-policy.md @@ -24,7 +24,7 @@ Typically, the TRD would start a transaction either - when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind. - when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.[^1] -In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Owner and/or using different communications channels. +In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a '**transaction-id**' must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Owner and/or using different communications channels. Handling/managing the various communications channels through which data can be exchanged is also a task of the TRD[^2]. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens). @@ -37,7 +37,7 @@ In order to make the TRD work, a Validation Policy (or TRD Policy) is created by - 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 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]. @@ -49,9 +49,9 @@ The Policy must be designed in such a way that it is extendable as new features The ability to create new transaction contexts and the availability of the TRD Policy enable the TRD to request the Verifier component of its Owner to obtain credentials of the types that it can use to fill in the transaction form when they satisfy the verification and validation requirements of its Owner.[^7] -When the Verifier returns such data (which comes with a list of proofs that the Verifier has checked), the TRD must then validate that data, i.e. determine whether or not it is valid for the specific transaction it is assembling the data for. The validation rules are Party-specific and hence come from the TRD policy. For simple cases, validation can simply consist of checking whether or not all verification proofs succeeded. At the other end of the validation spectrum, the TRD itself must make validation decisions, either electronically (according to the TRD policy) or by ‘outsourcing’ such decisions to human Agents of its Owner by providing an appropriate validation user interface. +When the Verifier returns such data (which comes with a list of proofs that the Verifier has checked), the TRD must then validate that data, i.e. determine whether or not it is valid for the specific transaction it is assembling the data for. The validation rules are Party-specific and hence come from the TRD policy. For simple cases, validation can simply consist of checking whether or not all verification proofs succeeded. At the other end of the validation spectrum, the TRD itself must make validation decisions, either electronically (according to the TRD policy) or by 'outsourcing' such decisions to human Agents of its Owner by providing an appropriate validation user interface. -As long as data is needed, the TRD can intermittently request the verifier to produce it (or it can use other communications channels, which is outside scope for now). It does so until it times out, or the form has become ‘clean’. +As long as data is needed, the TRD can intermittently request the verifier to produce it (or it can use other communications channels, which is outside scope for now). It does so until it times out, or the form has become 'clean'. ----- @@ -61,9 +61,9 @@ As long as data is needed, the TRD can intermittently request the verifier to pr [^3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Owner of the TRD. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years. -[^4]: For example, a credential that contains an address uses a specific schema to specify addresses, e.g. the ‘PostalAddress’ as defined by schema.org. This schema differs quite a bit from that of Dutch addresses as [*defined*](https://bag.basisregistraties.overheid.nl/def/bag) by the official (authentic) Dutch Registration of Addresses and Buildings (BAG). It may also well differ from the structure of addresses that databases of the Owner have implemented. Mapping allows such cases to be accommodated for. +[^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. +[^5]: Inconsistent or incoherent data is necessary for various purposes. First, it allows for correct further processing of the transaction. A non-existent postal code, or one that doesn't match the delivery address, may hinder a fluent transaction processing, resulting in additional costs and processing times. Another purpose is the early warning or detection of possible fraud/abuse. Remember that part of the data is being asked for reducing transaction risk, and checking consistency/coherence of such data is part of the risk mitigation process. [^6]: This enables the TRD to pass the endpoint URI on to the Verifier when it requests for such a credential, which in turn can send it to the holder of other Parties enabling them to obtain the credential from that issuer endpoint if that other Party does not have that credential in its wallet. The endpoint URI can in fact be put in the policy, because the (human) Agent that creates/maintains the policy would need to know that the issuing Party is actually issuing such credentials, what their contents means, etc., and hence is capable of tracking down the URI where that Party issues the credentials. diff --git a/docs/terms/tve-policy.md b/docs/terms/tve-policy.md index ac772f5..5223434 100644 --- a/docs/terms/tve-policy.md +++ b/docs/terms/tve-policy.md @@ -24,7 +24,7 @@ Typically, the TVE would start a transaction either - when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind. - when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.[^1] -In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Owner and/or using different communications channels. +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). @@ -37,7 +37,7 @@ In order to make the TVE work, a Validation Policy (or TVE Policy) is created by - 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 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]. @@ -49,9 +49,9 @@ The Policy must be designed in such a way that it is extendable as new features 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. +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’. +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'. ----- @@ -61,9 +61,9 @@ As long as data is needed, the TVE can intermittently request the verifier to pr [^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. +[^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. +[^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. diff --git a/docs/terms/validated-data.md b/docs/terms/validated-data.md index 7bebed1..4bcf01f 100644 --- a/docs/terms/validated-data.md +++ b/docs/terms/validated-data.md @@ -6,7 +6,7 @@ type: concept typeid: validated-data stage: draft 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)." +glossaryText: "data of which some %%party|party%% has established that it is valid, and hence suitahble to be used for some specific purpose(s)." --- :::info Editor's note diff --git a/docs/terms/validation-policy.md b/docs/terms/validation-policy.md index d04ad94..01d43b1 100644 --- a/docs/terms/validation-policy.md +++ b/docs/terms/validation-policy.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "a %%digital policy|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|governance%%." --- :::info Editor's note diff --git a/docs/terms/validation.md b/docs/terms/validation.md index 5148fb3..eac1133 100644 --- a/docs/terms/validation.md +++ b/docs/terms/validation.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "the process that a %%party|party%% uses to determine whether or not that data is valid to be used for some specific purpose(s) of that %%party|party%%." --- :::info Editor's note diff --git a/docs/terms/verifiable-credential.md b/docs/terms/verifiable-credential.md index 6a169d7..daa59d4 100644 --- a/docs/terms/verifiable-credential.md +++ b/docs/terms/verifiable-credential.md @@ -6,7 +6,7 @@ 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)." +glossaryText: "Credential that comes with assurances regarding its provenance (the %%party|party%% that issued it) and its integrity (the property that the %%credential|credential%% data has not been tampered with in transit, i.e. is the same as when issued)." --- :::info Editor's note diff --git a/docs/terms/verifiable-data.md b/docs/terms/verifiable-data.md index 2afc83f..918fb5c 100644 --- a/docs/terms/verifiable-data.md +++ b/docs/terms/verifiable-data.md @@ -6,7 +6,7 @@ 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)." +glossaryText: "data that comes with assurances regarding its provenance (the %%party|party%% that issued it) and its integrity (the property that the %%credential|credential%% data has not been tampered with in transit, i.e. is the same as when created)." --- :::info Editor's note diff --git a/docs/terms/verification.md b/docs/terms/verification.md index b9fd5cf..890d7d3 100644 --- a/docs/terms/verification.md +++ b/docs/terms/verification.md @@ -6,7 +6,7 @@ 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)." +glossaryText: "the process that a %%party|party%% uses to determine whether or not what that data represents is in fact true (veracity)." --- :::info Editor's note diff --git a/docs/terms/verified-data.md b/docs/terms/verified-data.md index b5b0808..ad02fc2 100644 --- a/docs/terms/verified-data.md +++ b/docs/terms/verified-data.md @@ -6,7 +6,7 @@ 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 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." +glossaryText: "data of which some %%party|party%% has established that it is a truthful representation of what its %%author|author%% intended it to mean when the data was last created/updated." --- :::info Editor's note diff --git a/docs/terms/verifier-policy.md b/docs/terms/verifier-policy.md index 6fe87d3..e8e88e5 100644 --- a/docs/terms/verifier-policy.md +++ b/docs/terms/verifier-policy.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "a %%digital policy|digital-policy%% that enables an operational %%verifier|verifier%% component to function according to the rules of its %%policy governor|policy-governor%%." --- :::info Editor's note diff --git a/docs/terms/verifier.md b/docs/terms/verifier.md index 1dfcb28..3af4549 100644 --- a/docs/terms/verifier.md +++ b/docs/terms/verifier.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "the capability to request %%peer agents|peer-agent%% to present (provide) data from credentials (of a specified kind, issued by specified %%parties|party%%), and to verify such responses (check structure, signatures, dates), according to its %%principal|principal%%'s %%verifier policy|verifier-policy%%." --- ### Short Description @@ -31,20 +31,20 @@ A **Verifier** is a component in the [eSSIF-Lab functional architecture](../func ### Functionality -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). +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 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. +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|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. +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 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). +- 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. diff --git a/docs/terms/wallet-policy.md b/docs/terms/wallet-policy.md index 79dc2b9..72c1ed0 100644 --- a/docs/terms/wallet-policy.md +++ b/docs/terms/wallet-policy.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "a %%digital policy|digital-policy%% that enables an operational %%wallet|wallet%% component to function according to the rules of its %%policy governor|policy-governor%%." --- :::info Editor's note diff --git a/docs/terms/wallet.md b/docs/terms/wallet.md index 58d9b20..5ba16ef 100644 --- a/docs/terms/wallet.md +++ b/docs/terms/wallet.md @@ -6,7 +6,7 @@ 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%." +glossaryText: "the capability to securely store data as requested by %%colleague agents|colleague-agents%%, and to provide stored data to %%colleague agents|colleague-agents%% or %%peer agents|peer-agent%%, all in compliance with the rules of its %%principal|principal%%'s %%wallet policy|wallet-policy%%." --- ### Short Description @@ -31,7 +31,7 @@ The primary purpose of the Wallet Component is to (securely) store data, and in 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 +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; @@ -41,7 +41,7 @@ By ‘securely storing data’ we mean that such data 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|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 Principal, the contents of which remains to be specified. -- GitLab