Merge branch 'terminology-rieks' into 'master'

Terminology updates (work-in-progress)

See merge request !11

.gitignore

@@ -15,3 +15,4 @@ start_server.bat
 *.lnk
 docs/vscode-%%-batch-replacer.txt
 **/zzz-*
+docs/test.md

docs/terminology-maintenance-script.rieks

@@ -17,6 +17,7 @@
 beg = "(?<=\W%%)"
 mid = "(?<=\|)"
 end = "(?=%%\W)"
+ss = "(?:['’]?s|\(s\))?"
 
 dutyright = "(?:dut(?:y|ies)|rights?)"
 dutyright = "%{dutyright}(?:-*(?:/|and|or|and/or)-*%{dutyright})?"
@@ -29,25 +30,34 @@ dutyrighttype = "%{dutyright}-types?"
 // `filter "*.txt"`                  - any .txt file in the root folder
 // `filter "**/*.txt"`               - any .txt file
 
-filter "docs/terms/credential-type.md"
+filter "docs/functional-architecture.md"
 
 // PREPROCESSING: convert single-%-notations into %%-notations.
 
+// Convert quotes so that only two types remain: ' an "For starte
+replace-regex "[‘’]"
+with "'"
+
 // We might want to 'undo' %%...|...%% markers in case some 'show text' needs to be associated wiht another 'reftext'
-// replace-regex "(\W%)%([^\|\n\r]+)\|[^%\n\r]+%(%\W)"
-// with "$1$2$3"
+// replace-regex "(?<=\W)%%([^\|\n\r]+)\|[^%\n\r]+%%(?=\W)"
+// with "%$1%"
 
 // First, convert %show text% into %%show text%%
-replace-regex "(?<=\s%)(([\w/-]|'|\s)*)(?=%([,.]?\s|-\w))"
+// Test set: none may match: %verif%er, %verif"ier%, "%verifier%", `%verifier%`
+// Test set: all must match:  %my verifier%, ('%verifiers%'), %verifier's%, %verifier’s%, (%(ver)/ifier%):., %(our) (vfyr)%, %verifier's%. %verifier’s%... single-%party%), '**subject (of a %party%)**' to 
+// replace-regex "(?<=\s\(?%)(\w|\s|\(|\)|[/-’'"])+(?=%([)":,.!?]*\s|-\w))"
+replace-regex "(?<=[-\s]\(?'?%)([^%]+)(?=%(([*_):;,.'!?]|\[[^\]]*\]){0,5}\s|-\w))"
 with "%$1%"
 
 // Only thereafter can we convert %showtext (words without trailing `%`-char) into %%showtext%%
-replace-regex "(?<=\s%)(([\w/-]|')*)(?=[,.]?\s)"
+// Test set: none may match: %verif%er, %(our) (verifier)%,
+// Test set: all must match: %verifier %verifiers, '%verifier'), %verifier's, %verifier’s, %verifier:, (%verifiers), %verifier's..... %verifier’s,?.!?  its %principal.[^DC.4] Also a %party)'
+replace-regex "(?<=(?:\s\(?'?|/)%)((\w+((/|-|’|')\w)?)+)(?='?\)?[:;,.!?]*(\[[^\]]*\])?\s)"
 with "%$1%%"
 
 // Then, we can expand %%show text%% into %%show text|show text%%
-replace-regex "(?<=\W%%)([^\|]*?)(?=%%\W)"
-with "$1|$1"
+replace-regex "(?<=\W)%%([^\|]*?)%%(?=\W)"
+with "%%$1|$1%%"
 
 // Next, we convert the latter part into lowercase
 replace-regex "(?<=\|)([^A-Z%]*?[A-Z].*?)(?=%%)"
@@ -68,25 +78,25 @@ with "$1-$2"
 // ACTUAL PROCESSING: now we need to convert well-known `lowercase-show-text`s to appropriate `reftexts`
 
 // [A]
-replace-regex "%{mid}(action|actor|agent|assertion|author)'?s%{end}"
+replace-regex "%{mid}(action|actor|agent|assertion|author)%{ss}%{end}"
 with "$1"
 
 // [B]
-replace-regex "%{mid}(business-transaction)'?s?%{end}"
+replace-regex "%{mid}(business-transaction)%{ss}?%{end}"
 with "$1"
 
 // [C]
 // for 'claim', see 'statement'
-replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)'?s?%{end}"
+replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)%{ss}?%{end}"
 with "$1"
 
-replace-regex "%{mid}communications?-(channel|session)'?s?%{end}"
+replace-regex "%{mid}communications?-(channel|session)%{ss}?%{end}"
 with "communication-$1"
 
 // [D]
-replace-regex "%{mid}(definition|dependent|dictionary-file|dictionary|documentation-interop)'?s?%{end}"
+replace-regex "%{mid}(definition|dependent|dictionary-file|dictionary|documentation-interop)%{ss}?%{end}"
 with "$1"
-replace-regex "%{mid}(?:electronic-|digital-)(actor|agent|colleague|communication-channel|policy)'?s%{end}"
+replace-regex "%{mid}\(?(?:electronic|digital)\)?-(actor|agent|colleague|communication-channel|policy)%{ss}%{end}"
 with "digital-$1"
 
 replace-regex "%{mid}(%{dutyrighttype}|%{dutyright})%{end}"
@@ -94,17 +104,17 @@ with "pattern-duties-and-rights"
 
 replace-regex "%{mid}data-(collector|discloser)-polic(y's|ies)%{end}"
 with "data-$1-policy"
-replace-regex "%{mid}data-(collector|discloser)'?s?%{end}"
+replace-regex "%{mid}data-(collector|discloser)%{ss}?%{end}"
 with "data-$1"
 
 // [E]
-replace-regex "%{mid}(employee|employer)'?s%{end}"
+replace-regex "%{mid}(employee|employer)%{ss}%{end}"
 with "$1"
 replace-regex "%{mid}(legal-)?entit(y's|ies)%{end}"
 with "$1entity"
 
 // [G]
-replace-regex "%{mid}(glossary-file|guardian(ship)?(-relationship)?(-type)?)'?s%{end}"
+replace-regex "%{mid}(glossary-file|guardian(ship)?(-relationship)?(-type)?)%{ss}%{end}"
 with "$1"
 replace-regex "%{mid}glossar(y's|ies)%{end}"
 with "glossary"
@@ -117,20 +127,20 @@ with "governance"
 
 // [H-I-J-K] (all holder, issuer, verifier and wallet stuff, too)
 // for associated policies, see [P]
-replace-regex "%{mid}(holder|issuer|verifier|wallet|identifier|jurisdiction(-governor)?|knowledge(-governor)?)'?s%{end}"
+replace-regex "%{mid}(holder|issuer|verifier|wallet|identifier|jurisdiction(-governor)?|knowledge(-governor)?)%{ss}%{end}"
 with "$1"
 
 // [L-M]
-replace-regex "%{mid}(legal-jurisdiction|legal-system|mental-model)'?s%{end}"
+replace-regex "%{mid}(legal-jurisdiction|legal-system|mental-model)%{ss}%{end}"
 with "$1"
 // for 'legal entities', see 'entities'
 
 // [O]
-replace-regex "%{mid}(objective|organization|owned|owner|ownership)'?s%{end}"
+replace-regex "%{mid}(objective|organization|owned|owner|ownership)%{ss}%{end}"
 with "$1"
 
 // [P]
-replace-regex "%{mid}(participant|pattern-file|pattern|(peer-)(actor|agent)|policy-governor|presentation-request|presentation|principal)'?s%{end}"
+replace-regex "%{mid}(participant|pattern-file|pattern|(peer-)(actor|agent)|policy-governor|presentation-request|presentation|principal)%{ss}%{end}"
 with "$1"
 replace-regex "%{mid}(|peer-)part(y's|ies)%{end}"
 with "$1party"
@@ -139,21 +149,21 @@ with "$1policy"
 
 // [R-S]
 // For 'rights', see [D]uties
-replace-regex "%{mid}(risk|scope-file|scope|ssi-agent)'?s%{end}"
+replace-regex "%{mid}(risk|scope-file|scope|ssi-agent)%{ss}%{end}"
 with "$1"
-replace-regex "%{mid}(statement|claim)'?s%{end}"
+replace-regex "%{mid}(statement|claim|statement%{ss}/claim)%{ss}%{end}"
 with "assertion"
 
 // [T]
 // for transaction data collector/discloers policies, see [P]
-replace-regex "%{mid}(term-file|term|transaction-(agreement|data-(collector|discloser)|form|proposal))'?s%{end}"
+replace-regex "%{mid}(term-file|term|transaction-(agreement|data-(collector|discloser)|form|proposal))%{ss}%{end}"
 with "$1"
-replace-regex "%{mid}transaction'?s?%{end}"
+replace-regex "%{mid}transaction%{ss}?%{end}"
 with "business-transaction"
 
 // [V]
 // for verifier stuff - see holder
-replace-regex "%{mid}(verifiable-credential|verifier)'?s%{end}"
+replace-regex "%{mid}(verifiable-credential|verifier)%{ss}%{end}"
 with "$1"
 replace-regex "%{mid}vocabular(y's|ies)%{end}"
 with "vocabulary"
@@ -164,15 +174,15 @@ with "vocabulary"
 // CLEANING UP UNINTENDED CHANGES
 
 // Remove all `%%showtext|reftext%%` in docusaurus header.
-replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
 with "$1$2$4"
-replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
 with "$1$2$4"
-replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
 with "$1$2$4"
-replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
 with "$1$2$4"
-replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+replace-regex "(^---\s*\nid:(?:[^%]*[\n\r]){0,8})[^%]*%%([^\|]*)\|([^%]*)%%(?:[^%]*[\n\r]){0,8}---"
 with "$1$2$4"
 
 // Remove all `%%showtext|reftext%%` occurrences in markdown headers

docs/terms/action-type.md

+---
+id: action-type
+title: "Action Type"
+scopeid: essifLab
+type: concept
+typeid: action-type
+stage: draft
+hoverText: "Action Type/Class: the specification of properties and characteristics that that Actions must have to qualify as instance of that class; also: the set of Actions that actually have these properties and characteristics."
+---
+
+:::info Editor's note
+TNO (or others) to provide further content of this file.
+:::

docs/terms/action.md

@@ -5,11 +5,13 @@ scopeid: essifLab
 type: concept
 typeid: action
 stage: draft
-hoverText: "Action: something that is actually done/executed - by a single Actor, as a single operation, for a given party within a specific context."
+hoverText: "Action: something that is actually done/executed - by a single Actor (on behalf of a given Party), as a single operation in a specific context."
 ---
 
 ### Short Description
-An **Action** is something that is actually done/executed by a %%actor|actor%% in some context (i.e. in a specific place, at a specific time). During the time interval in which the action is executed, the actor may still execute other actions in other execution-contexts (multi-tasking). An action is executed for, or on behalf of, a specific %%party|party%%, which means that the primary guidance for executing the action, e.g. how to execute it, boundary conditions within which the execution must take place, etc., comes from a %%policy|policy%% that this %%party|party%% has established for actions of that kind. The actor is assumed to have appropriate access to that policy.
+An **Action** is something that is actually done/executed by a %%actor|actor%% in some context (i.e. in a specific place, at a specific time). During the time interval in which the action is executed, the actor may still execute other actions in other execution-contexts (multi-tasking). An action is executed on behalf of a specific %%party|party%%, which means that the primary guidance for executing the action, e.g. how to execute it, boundary conditions within which the execution must take place, etc., comes from a %%policy|policy%% that this %%party|party%% has established for actions of that kind. The actor is assumed to have appropriate access to that policy.
+
+The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
 
 ### Purpose
 The ability to distinguish between (non)actions allows one to determine which (kinds of) %%actors|actor%% are capable of executing actions (e.g. by establishing that they have the competences required by the %%party|party%%), and as a consequence may be permitted and/or required to execute them. Also, this ability enables %%parties|party%% to determine the execution-policy, i.e. the set of rules, working-instructions, preferences and other guidance that actors should obey or comply with when exeucting an action on its behalf.
@@ -27,5 +29,3 @@ An **Action** is something that is done by an actor, can be considered a single
 - %%actor|actor%%
 - %%agent|agent%%
 
-### Background
-The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
\ No newline at end of file

docs/terms/actor.md

@@ -11,6 +11,8 @@ hoverText: "Actor: Entity that can act (do things), e.g. people, machines, but n
 ### Short Description
 An **Actor** is someone or something that can actually do things, such as people or machines. Actors will generally do things, i.e. execute %%actions|action%% in different ways, depending on the context, or the %%party|party%% for whom they do this.
 
+The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
+
 ### Purpose
 The ability to distinguish between (non)actors allows one to determine which (kinds of) actors are capable of executing which (kinds of) %%actions|action%%, specifically since %%organizations|organization%% do not qualify as an actor (they need actors to get things done).
 
@@ -29,6 +31,3 @@ Entity that is capable of actually executing %%actions|action%% (acting, doing t
 - %%peer actor|peer-actor%%
 - %%agent|agent%%
 - %%principal|principal%%
-
-### Background
-The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.

docs/terms/agent.md

@@ -5,18 +5,20 @@ scopeid: essifLab
 type: concept
 typeid: agent
 stage: draft
-hoverText: "Agent (of a Party): an Actor that is executing an Action for, or on behalf of a Party (called the Principal of that Actor)."
+hoverText: "Agent (of a Party): an Actor that is executing an Action on behalf of a Party (called the Principal of that Actor)."
 ---
 
 ### Short Description
-An **Agent** is an %%actor|actor%% that is executing an action %%action|action%% for, or on behalf of some %%party|party%% (which we call the %%principal|principal%% of that agent). During the time interval in which the action is executed, the actor may execute other actions in other execution-contexts, on behalf of the same or another %%party|party%%. However, for the execution of a single %%action|action%%, the actor is an agent for precisely one principal. It is assumed that the principal provides its agents with the %%policies|policy%% that provide the agents with the rules, working-instructions, preferences and other guidance that they need to comply with when exeucting the action.
+An **Agent** is an %%actor|actor%% that is executing an action %%action|action%% on behalf of some %%party|party%% (which we call the %%principal|principal%% of that agent). During the time interval in which the action is executed, the actor may execute other actions in other execution-contexts, on behalf of the same or another %%party|party%%. However, for the execution of a single %%action|action%%, the actor is an agent for precisely one principal. It is assumed that the principal provides its agents with the %%policies|policy%% that provide the agents with the rules, working-instructions, preferences and other guidance that they need to comply with when exeucting the action.
+
+The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
 
 ### Purpose
 The ability to distinguish between (non)agents is relevant in many situations, including:
 - electronic communication: the agent 
 
 ### Criterion
-An **Agent** is a role that an %%actor|actor%% fulfills with respect to some %%party|party%% when that actor is executing some %%action|action%% for, or on behalf of that %%party|party%%.
+An **Agent** is a role that an %%actor|actor%% fulfills with respect to some %%party|party%% when that actor is executing some %%action|action%% on behalf of that %%party|party%%.
 
 ### Examples
 
@@ -27,6 +29,3 @@ An **Agent** is a role that an %%actor|actor%% fulfills with respect to some %%p
 - A company that makes cars may use robots that weld parts of a car together; these robots acts as Agents for that company.
 - A (running) webserver that accepts product orders for a retailer acts as a (digital) Agent for that retailer.
 - A wallet app that runs on a phone and that is exclusively used by a single person acts as a (digital) Agent for that person.
-
-### Background
-The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.

docs/terms/author.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: author
 stage: draft
-hoverText: "Author (of data/document/file/...): the Party, on whose behalf that data/document/file/... has been created or updated."
+hoverText: "Author (of data/document/file/...): a Party, on whose behalf that data/document/file/... has been created and/or updated."
 ---
 
 :::info Editor's note

docs/terms/business-transaction.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 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)."
+hoverText: "Business Transaction: the exchange of goods, services, funds, or data between some Parties (called Participants of the Transaction)."
 ---
 
 import useBaseUrl from '@docusaurus/useBaseUrl'

docs/terms/colleague.md

@@ -5,10 +5,14 @@ scopeid: essifLab
 type: concept
 typeid: colleague
 stage: draft
-hoverText: "Colleagues: two or more Digital Agents that all have the same Principal (i.e. Party on whose behalf they exeucte Actions)."
+hoverText: "Colleagues: two or more (digital or non-digital) Agents that have the same Principal (i.e. Party on whose behalf they exeucte Actions)."
 ---
 
 :::info Editor's note
 TNO (or others) to provide the content of this file.
 :::
 
+### Purpose
+The ability to distinguish between (non) colleagues allows us to reason and communicate about the set of (digital and non-digital) %%actors|actor%% that are %%agents|agent%% for a **principal|principal%%. This is relevant in situations where different %%agents|agent%% excute %%actions|action%% in a single %%business transaction|business-transaction%% on behalf of the same %%principal|principal%%
+
+See also: %%digital colleague|digital-colleague%%.

docs/terms/commitment-decision.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: commitment-decision
 stage: draft
-hoverText: "Commitment Decision (of a Party regarding a Business Transaction): the decision of that Party regarding whether or not to commit to that Business Transaction, i.e. (promise) to fulfill the obligations that the associated Business Transaction Agreement assigns to that Party."
+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."
 ---
 
 :::info Editor's note

docs/terms/communication-session.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: communication-session
 stage: draft
-hoverText: "Communication Session: the time interval during which two Actors have an established Communication Channel."
+hoverText: "Communication Session: a time interval during which two Actors have an established Communication Channel that does not exist outside of that time interval."
 ---
 
 :::info Editor's note

docs/terms/concept-file.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: concept-file
 stage: draft
-hoverText: "Concept-file: a file that defines/specifies a Concept."
+hoverText: "Concept-file: a file whose contents defines/specifies a Concept."
 ---
 
 ### Short Description

docs/terms/concept.md

@@ -12,6 +12,8 @@ hoverText: "Concept: the ideas/thoughts behind a classification of Entities (wha
 <!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
 A Concept tries to capture the idea behind a classification of entities[^1], allowing us to reason about everything in the class as if it were one thing. For example, the ideas ([mental representations](https://en.wikipedia.org/wiki/Mental_representation)) you have when processing the sentences "I can drink beer from a beer glass' and 'I can drink beer from a coffee mug' shows that the concepts that are behind 'beer glass' and 'coffee mug' differ. Note that in order to communicate about this idea, we also need a word or phrase (i.e.: a termat we can use to refer to (instances of) this idea.
 
+The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
+
 ### Purpose
 <!--Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this conceptevant within its scope of definition?-->
 Working together is easier when you and your peers share the same ideas. We need a way to test and ensure, that you and your peers _actually_ have the same understanding, for the purpose of making cooperation easier. Doing so is expected to not only reduce the number of terminological discussions, but also improve the efficiency and effectiveness of the remaining discussions.
@@ -31,9 +33,6 @@ A (description/specification of a) Concept MUST be [intensionally defined](https
 
 * %%Mental(or Conceptual) Model|pattern%% is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents.
 
-### Background
-The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
-
 ### Domains
 <!--In which general knowledge ecosystems or mental model families does this concepty a role?-->
 * essifLab

docs/terms/credential-catalogue.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: credential-catalogue
 stage: draft
-hoverText: "Credential Catalogue (functional component): the capability to register and advertise Credential Types and any related information that its governing Party decides to disclose for enabling other Parties to decide whether or not it is beneficial for them to request Credentials of such type for some kind(s) of decisions of theirs."
+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."
 ---
 
 :::info Editor's note

docs/terms/credential-type.md

@@ -5,11 +5,13 @@ scopeid: essifLab
 type: concept
 typeid: credential-type
 stage: draft
-hoverText: "Credential Type: a specification of the kinds of Assertions (claims, statements) that must, or may be, included in Credentials of that type."
+hoverText: "Credential Type: the specification of the contents, properties, constraints etc. that Credentials of this type must have/comply with."
 ---
 
 ### Short Description
-A **credential-type** is a specification that states which kinds of %%assertions (claims, statements)|assertion%% can or may be found in any %%credential|credential%% of that kind. Typically, %%parties|party%% that issue %%credentials|credential%% of some %%kind|credential-type%% will advertise the %%credential types|credential-type%% of the %%credentials|credential%% that it may issue. 
+A **credential-type** is a specification that states 
+- the contents that %credentials of that kind must or may have; this includes of which kinds of %%assertions (claims, statements)|assertion%% as well as meta-data.
+- properties Typically, %%parties|party%% that issue %%credentials|credential%% of some %%kind|credential-type%% will advertise the %%credential types|credential-type%% of the %%credentials|credential%% that it may issue. 
 
 ### Purpose
 %%Parties|party%% advertise %%credential types|credential-type%% for credentials that they issue for the purpose of enabling other %%parties|party%% to determine whether or not they should be asking for such %%credentials|credential%% of this issuing %party.
\ No newline at end of file

docs/terms/credential.md

@@ -9,7 +9,7 @@ hoverText: "Credential: data, representing a set of Assertions (claims, statemen
 ---
 
 ### Short Description
-A **credential** is a set of (related) %%assertions|assertion%% (also referred to as claims, or statements), to which metadata is added (e.g. date of issuing), and a number of proofs, which typically include a  proof of provenance (i.e. proof that it was created by, or on behalf of, a specific %%party|party%%), and a proof of integrity (i.e. proof that the data hasn't changed since it was issued). 
+A **credential** is a set of (related) %%assertions|assertion%% (also referred to as claims, or statements), to which metadata is added (e.g. date of issuing), and a number of proofs, which typically include a  proof of provenance (i.e. proof that it was created on behalf of a specific %%party|party%%), and a proof of integrity (i.e. proof that the data hasn't changed since it was issued). 
 
 In physical credentials, such as drivers licenses and passports, proofs of integrity usually apply to the physical document itself. They come in a variety of forms, such as the structure of the paper, holograms, watermarks, or (embedded) chips. The proof of provenance usually consists of the form-format of the credential and %%assertions|assertion%% about the document issuer.
 

docs/terms/data-collector.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: data-collector
 stage: draft
-hoverText: "Data Collector: a functional component that collects sufficient and Validated Data for deciding whether or not a request (typically for a product or a service) is to be serviced."
+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)."
 ---
 
 ### Short Description
@@ -50,24 +50,24 @@ It will be deleted in the (near?) future.
 Typically, the Data Collector would start a transaction either
 
 -   when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind.
--   when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.[^one]
+-   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 Owner and/or using different communication channels.
+In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Principal and/or using different communication channels.
 
 Handling/managing the various communication channels through which data can be exchanged is also a task of the Data Collector[^2]. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens).
 
 Thus, the Data Collector is generally considered capable of obtaining data through different communication channels. However, the technical tracks of eSSIF-Lab will exclusively focus on the communication channel through which credentials can be requested and obtained. Any extensions or business productization of Data Collector designs may be considered in the business tracks of eSSIF-Lab. The latter is not considered any further in this section.
 
-In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the Data Collector needs to know what kinds of credentials it should ask for, which Parties its Owner trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.[^3] Also, when the Data Collector gets a credential that satisfies the necessary verification proofs, it needs a way to map the contents of that credential to the structure of the transaction context that is used internally by (other systems of) its Owner.[^4] Also, as the Data Collector gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.[^5]
+In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the Data Collector needs to know what kinds of credentials it should ask for, which Parties its Principal trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.[^3] Also, when the Data Collector gets a credential that satisfies the necessary verification proofs, it needs a way to map the contents of that credential to the structure of the transaction context that is used internally by (other systems of) its Principal.[^4] Also, as the Data Collector gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.[^5]
 
-In order to make the Data Collector work, a Validation Policy (or Data Collector Policy) is created by, or on behalf of the Owner, which specifies at least:
+In order to make the Data Collector work, a Validation Policy (or Data Collector Policy) is created by, or on behalf of its Principal, which specifies at least:
 
--   the kinds of transactions the Owner is willing to (electronically) engage in, from both the requester and the provider perspectives;
+-   the kinds of transactions the Principal is willing to (electronically) engage in, from both the requester and the provider perspectives;
 -   for each such transaction type:
 
     -   the criteria (business rules) that should be used to determine that the form is ‘clean’, i.e. that the necessary and sufficient data have been obtained and that they are consistent, coherent, and suitable for making a transaction commitment decision.
 
-    -   the kinds of credentials and issuers that the 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].
+    -   the kinds of credentials and issuers that the Principal is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing Parties do the actual credential issuing may be specified[^6].
 
     -   for each kind of credential: the verification proofs that must hold to be accepted as a source for valid data.
 
@@ -75,9 +75,9 @@ In order to make the Data Collector work, a Validation Policy (or Data Collector
 
 The Policy must be designed in such a way that it is extendable as new features will be called for in the future.
 
-The ability to create new transaction contexts and the availability of the Data Collector Policy enable the Data Collector to request the Verifier component of its Owner to obtain credentials of the types that it can use to fill in the transaction form when they satisfy the verification and validation requirements of its Owner.[^7]
+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 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 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’.
 
@@ -98,9 +98,9 @@ TNO to revise the footnote markers
 
 [^2]: It may well be that this functionality can somehow be split off in the (near) future.
 
-[^3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Owner of the Data Collector. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years.
+[^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 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 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.
 

docs/terms/data-discloser.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: data-discloser
 stage: draft
-hoverText: "Data Discloser: a functional component that is capable of disclosing data."
+hoverText: "Data Discloser: a functional component that is capable of disclosing data to (Agents of) other Parties, e.g. in the form of Credentials."
 ---
 
 ### Short Description
@@ -19,7 +19,7 @@ The Data Discloser uses a %%data-collector-policy|data-collector-policy%% to lea
 The Data Discloser uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities.
 
 ### Purpose
-The purpose of the Data Discloser component is to state the (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other Parties. A special kind of result is the (provisioning of) a credential that its Owner already has created.
+The purpose of the Data Discloser component is to state the (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other Parties. A special kind of result is the (provisioning of) a credential that its Principal already has created.
 
 ### Criteria
 A **Data Discloser** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) that is capable of stating (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other %%Parties|party%%.

docs/terms/definition.md

@@ -5,13 +5,15 @@ scopeid: essifLabTerminology
 type: concept
 typeid: definition
 stage: draft
-hoverText: "Definition: a text that helps Parties deeply/truly understand the meaning of, or Concepts behind, a Term."
+hoverText: "Definition: a text that helps Parties to understand the meaning of (and Concepts behind) a Term, ideally in such a way that these Parties can determine whether or not they make the same distinction."
 ---
 
 ### Short Description
 <!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
 A **Definition** is a text that helps %%parties|party%% truly understand the meaning of a %%term|term%% as it is used in a communication. Because [terms are scoped](terminology), this 'truly understanding' of one another isn't trivial. Therefore, we insist that the explanatory text be a criterion that %%parties|party%% are expected to use in the same way in some %%scope(s)|scope%%, allowing them to establish whether or not they make the same determination as to whether or not something qualifies to be refered to by that term in a way that is independent of whether or not the (alledged) meaning is relevant for the purposes they pursue within that scope.
 
+The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
+
 ### Purpose
 <!--Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this conceptevant within its scope of definition?-->
 Working together is easier when you and your peers share the same ideas. We need a way to test and ensure, that you and your peers _actually_ have the same understanding, for the purpose of making cooperation easier. Doing so is expected to not only reduce the number of terminological discussions, but also improve the efficiency and effectiveness of the remaining discussions.
@@ -37,9 +39,6 @@ Entity that comprises at a minimum:
 
 * %%Mental(or Conceptual) Model|pattern%% is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents.
 
-### Background
-The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
-
 ### Use-cases
 <!--This (optional) section specifies an (optional) introductory paragraph, and a level-3 (i.e. `###`) subsection for every use case it describes. Every such use-case SHOULD
 - describe the situation/context of the use-case;

docs/terms/dependent.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: dependent
 stage: draft
-hoverText: "Dependent (of an Party in a Jurisdiction): the Entity for the caring for and/or protecting/guarding/defending of which a guardianship relationship has been established with that Entity within that Jurisdiction."
+hoverText: "Dependent (of an Party in a Jurisdiction): the Entity for the caring for and/or protecting/guarding/defending of which a Guardianship Relationship has been established with that Entity within that Jurisdiction."
 ---
 
 :::info Editor's Note
@@ -14,9 +14,8 @@ TNO to revise all below texts.
 
 ### Short Description
 
+The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts.
+
 ### Purpose
 
 ### Criteria
-
-### Background
-The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts.
\ No newline at end of file

docs/terms/dictionary-file.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: dictionary
 typeid: dictionary-file
 stage: draft
-hoverText: "Dictionary-file: a file that specifies the contents of a Dictionary."
+hoverText: "Dictionary-file: a file whose contents specifies the contents of a Dictionary."
 ---
 
 ### Short Description

docs/terms/dictionary.md

@@ -12,6 +12,8 @@ hoverText: "Dictionary: an alphabetically sorted list of Terms with various mean
 <!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
 A Dictionary is an alphabetically sorted list of terms and explanations. Each term may have multiple such explanations, which come from different %%scopes/contexts|scope%%. 
 
+The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
+
 ### Purpose
 <!--Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this conceptevant within its scope of definition?-->
 A dictionary helps people to get introduced in the domain for which the dictionary is created. Usually, this is a larger domain e.g. of some language, or about computer security.
@@ -29,9 +31,6 @@ Examples include the [NIST Computer Security Resource Center](https://csrc.nist.
 - %%Glossary|glossary%% - this is a list of words with a single meaning, that serves more specific purposes than a dictionary.
 - [Vocabulary](https://en.wikipedia.org/wiki/Vocabulary) - this is a set of familiar words witin a particular/persons's language or field of expertise. A Dictionary can provide the various meanings of each such words.
 
-### Background
-The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
-
 ### Notes
 <!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
 

docs/terms/digital-policy.md

@@ -6,9 +6,13 @@ type: concept
 typeid: digital-policy
 conceptref: ":Policy"
 stage: draft
-hoverText: "Digital Policy: a machine-readable Policy (i.e. a file that contains rules, working-instructions, preferences and other guidance for Agents that can interpret such documents, so as to enable them to execute Actions on behalf of the Policy's Governor)."
+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)."
 ---
 
+:::info Editor's note
+TNO (or others) to provide further content of this file.
+:::
+
 ### Short Description
 A **digital policy** is an artifact that is derived from, and represents, a %%policy|policy%% for the purpose of being useable in the digital realm.
 

docs/terms/eSSIFLab-scope.md

@@ -28,19 +28,3 @@ The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community pa
 
 ### Background
 The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
-
-### Notes
-<!--Anything els that's worth mentioning.-->
-