documentation updates - wip

docs/pattern-list.md

@@ -17,6 +17,8 @@ While some of the topics listed below are pretty much done, others are still nee
 
 We currently have models for the following topics:
 
+- [Duties and Rights](./terms/pattern-duties-and-rights): The Duties and Rights pattern describes the relations between Jurisdictions, Legal Entities and the duties and rights they have within them.
+
 - [Guardianship relationships](./terms/pattern-guardianship): The Guardianships pattern captures the Concepts and relations that explain what a generic Guardianship consists of, and how it relates to Guardians, Dependents, Jurisdictions, etc.
 
 - [Jurisdictions](./terms/pattern-jurisdiction): The Jurisdictions pattern captures the Concepts and relations that explain what a generic Jurisdiction consists of, and relates it to Parties and Legal Entities.

docs/terminology-maintenance-script.rieks

+// Purpose: replace %-marked words (including some varieties such as plurals) with %%-syntax for those words.
+
+// This is a script that can be run by the Batch Replacer extension of VSCode .
+// Press Ctrl-Shift-P as you are editing this script, then search for `Batch Replacer`, and execute it.
+
+// Executing the script will do the following replacements consecutively:
+// 1. `%text with possibly spaces%` --> `%%text with possibly spaces%%`
+// 2. `%text-without-spaces` --> `%%text-without-spaces%%` (some punctuation around it is allowed)
+// 3. `%%Show Text%%` --> `%%Show Text|Show-Text%%` (sorry, we cannot make the reftext lowercase)
+// Now, you have to manually execute /(?<=\|)([A-Z][^%]*)(?=%%)/\L$1/g/
+// 4. `|ref-text%% is being checked to see if modifications need to be made (e.g. plurals to singular etc.)
+// 5. There is a cleanup phase that removes any %%...|...%% syntax from the docusaurus header, markdown headers, and <img /> constructs.
+
+// Complex regular expressions can be created using variables. Variables are applied to the entire script, and should be defined at the beginning of the script. Variables are defined as ... = "..." and are used as %{...}. Variables can only be used in the replace and replace-regex instructions.
+// variables can reference themselves and be overwritten - see documentation of 'batch replacer' extension
+
+beg = "(?<=\W%%)"
+mid = "(?<=\|)"
+end = "(?=%%\W)"
+
+dutyright = "(?:dut(?:y|ies)|rights?)"
+dutyright = "%{dutyright}(?:-*(?:/|and|or|and/or)-*%{dutyright})?"
+dutyrighttype = "%{dutyright}-types?"
+
+// If you do not specify the files to work on, the replace will be global (throughout the workspace).
+// `filter "document.txt"`           - document.txt file in the root folder
+// `filter "Documents/document.txt"` - document.txt file in the Documents folder in the root folder
+// `filter "**/document.txt"`        - document.txt files anywhere
+// `filter "*.txt"`                  - any .txt file in the root folder
+// `filter "**/*.txt"`               - any .txt file
+
+filter "docs/terms/credential-type.md"
+
+// PREPROCESSING: convert single-%-notations into %%-notations.
+
+// We might want to 'undo' %%...|...%% markers in case some 'show text' needs to be associated wiht another 'reftext'
+// replace-regex "(\W%)%([^\|\n\r]+)\|[^%\n\r]+%(%\W)"
+// with "$1$2$3"
+
+// First, convert %show text% into %%show text%%
+replace-regex "(?<=\s%)(([\w/-]|'|\s)*)(?=%([,.]?\s|-\w))"
+with "%$1%"
+
+// Only thereafter can we convert %showtext (words without trailing `%`-char) into %%showtext%%
+replace-regex "(?<=\s%)(([\w/-]|')*)(?=[,.]?\s)"
+with "%$1%%"
+
+// Then, we can expand %%show text%% into %%show text|show text%%
+replace-regex "(?<=\W%%)([^\|]*?)(?=%%\W)"
+with "$1|$1"
+
+// Next, we convert the latter part into lowercase
+replace-regex "(?<=\|)([^A-Z%]*?[A-Z].*?)(?=%%)"
+with-case "lowercase"
+
+// Next, we replace whitespace in `lowercase show text` instances with `-` characters
+replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
+with "$1-$2"
+replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
+with "$1-$2"
+replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
+with "$1-$2"
+replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
+with "$1-$2"
+replace-regex "(?<=\|)([^%\|\n\r\s]+)\s+([^%]+)(?=%%)"
+with "$1-$2"
+
+// ACTUAL PROCESSING: now we need to convert well-known `lowercase-show-text`s to appropriate `reftexts`
+
+// [A]
+replace-regex "%{mid}(action|actor|agent|assertion|author)'?s%{end}"
+with "$1"
+
+// [B]
+replace-regex "%{mid}(business-transaction)'?s?%{end}"
+with "$1"
+
+// [C]
+// for 'claim', see 'statement'
+replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)'?s?%{end}"
+with "$1"
+
+replace-regex "%{mid}communications?-(channel|session)'?s?%{end}"
+with "communication-$1"
+
+// [D]
+replace-regex "%{mid}(definition|dependent|dictionary-file|dictionary|documentation-interop)'?s?%{end}"
+with "$1"
+replace-regex "%{mid}(?:electronic-|digital-)(actor|agent|colleague|communication-channel|policy)'?s%{end}"
+with "digital-$1"
+
+replace-regex "%{mid}(%{dutyrighttype}|%{dutyright})%{end}"
+with "pattern-duties-and-rights"
+
+replace-regex "%{mid}data-(collector|discloser)-polic(y's|ies)%{end}"
+with "data-$1-policy"
+replace-regex "%{mid}data-(collector|discloser)'?s?%{end}"
+with "data-$1"
+
+// [E]
+replace-regex "%{mid}(employee|employer)'?s%{end}"
+with "$1"
+replace-regex "%{mid}(legal-)?entit(y's|ies)%{end}"
+with "$1entity"
+
+// [G]
+replace-regex "%{mid}(glossary-file|guardian(ship)?(-relationship)?(-type)?)'?s%{end}"
+with "$1"
+replace-regex "%{mid}glossar(y's|ies)%{end}"
+with "glossary"
+replace-regex "%{mid}guardianship(-relationship)?%{end}"
+with "guardianship"
+replace-regex "%{mid}guardianship(-relationship)?-type%{end}"
+with "guardianship-type"
+replace-regex "%{mid}govern(or)?s?%{end}"
+with "governance"
+
+// [H-I-J-K] (all holder, issuer, verifier and wallet stuff, too)
+// for associated policies, see [P]
+replace-regex "%{mid}(holder|issuer|verifier|wallet|identifier|jurisdiction(-governor)?|knowledge(-governor)?)'?s%{end}"
+with "$1"
+
+// [L-M]
+replace-regex "%{mid}(legal-jurisdiction|legal-system|mental-model)'?s%{end}"
+with "$1"
+// for 'legal entities', see 'entities'
+
+// [O]
+replace-regex "%{mid}(objective|organization|owned|owner|ownership)'?s%{end}"
+with "$1"
+
+// [P]
+replace-regex "%{mid}(participant|pattern-file|pattern|(peer-)(actor|agent)|policy-governor|presentation-request|presentation|principal)'?s%{end}"
+with "$1"
+replace-regex "%{mid}(|peer-)part(y's|ies)%{end}"
+with "$1party"
+replace-regex "%{mid}(|issuer-|holder-|verifier-|wallet-|transaction-data-(collector|discloser)-)polic(y's|ies)%{end}"
+with "$1policy"
+
+// [R-S]
+// For 'rights', see [D]uties
+replace-regex "%{mid}(risk|scope-file|scope|ssi-agent)'?s%{end}"
+with "$1"
+replace-regex "%{mid}(statement|claim)'?s%{end}"
+with "assertion"
+
+// [T]
+// for transaction data collector/discloers policies, see [P]
+replace-regex "%{mid}(term-file|term|transaction-(agreement|data-(collector|discloser)|form|proposal))'?s%{end}"
+with "$1"
+replace-regex "%{mid}transaction'?s?%{end}"
+with "business-transaction"
+
+// [V]
+// for verifier stuff - see holder
+replace-regex "%{mid}(verifiable-credential|verifier)'?s%{end}"
+with "$1"
+replace-regex "%{mid}vocabular(y's|ies)%{end}"
+with "vocabulary"
+
+// [W]
+// for wallet stuff - see holder
+
+// CLEANING UP UNINTENDED CHANGES
+
+// Remove all `%%showtext|reftext%%` in docusaurus header.
+replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+with "$1$2$4"
+replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+with "$1$2$4"
+replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+with "$1$2$4"
+replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+with "$1$2$4"
+replace-regex "(^---\s*\nid:(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*\n---)"
+with "$1$2$4"
+
+// Remove all `%%showtext|reftext%%` occurrences in markdown headers
+replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)"
+with "$1$2$4"
+replace-regex "(^#+\s+.*?)%%([^\|]*)\|([^%]*)%%(.*$)"
+with "$1$2$4"
+
+// Remove all `%%showtext|reftext%%` occurrences in `<img />`-constructs
+replace-regex "(<img(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*)(?=/>)"
+with "$1$2$4"
+replace-regex "(<img(?:.|[\n\r])*?)%%([^\|]*)\|([^%]*)%%((?:.|[\n\r])*)(?=/>)"
+with "$1$2$4"

docs/terminology-plugin-instructions.md

@@ -2,7 +2,7 @@
 id: terminology-plugin-instructions
 title: Terminology & Glossary plugin docs
 ---
-import useBaseUrl from '@docusaurus/useBaseUrl'; // All other .md files get this statement automatically added.
+import useBaseUrl from '@docusaurus/useBaseUrl'; // All other .md files may get this statement automatically added.
 
 ### How it works
 

docs/terms/business-transaction.md

@@ -8,6 +8,8 @@ stage: draft
 hoverText: "Business Transaction: the exchange of goods, services, funds, or data between some Parties (called ‘participants’ of the transaction)."
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl'
+
 ### Short Description
 A **business transaction** is an exchange of goods, services, funds, or data between some %%parties|party%%. These %%parties|party%% are called the %%participants of the transaction|participant%%. A typical %%business transaction|business-transaction%% consists of three phases. In the first phase, a %%transaction agreement|transaction-agreement%% is negotiated between the participants. That phase ends when either participant quits the negotiation, or all participants commit to the transaction, which basically is a promise to the other participants that it will keep up its end of the %%transaction agreement|transaction-agreement%%. In the second phase, the participants work to fulfill their promise. That phase ends when they deliver the results, and inform their peers of that they're done. In the final phase, participants check whether or not they have received what was promised, and that it conforms the criteria in the transaction agreement. This may lead to some discussion and possible rectifications. The final phase ends either when one of the participants escalates (e.g. goes to court), or all results are accepted. This way of looking at %%business transactions|business-transaction%% has been described extensively in the [DEMO](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations) transaction model.
 

docs/terms/credential-catalogue.md

+---
+id: credential-catalogue
+title: "Credential Catalogue"
+scopeid: essifLab
+type: concept
+typeid: credential-catalogue
+stage: draft
+hoverText: "Credential Catalogue (functional component): the capability to register and advertise Credential Types and any related information that its governing Party decides to disclose for enabling other Parties to decide whether or not it is beneficial for them to request Credentials of such type for some kind(s) of decisions of theirs."
+---
+
+:::info Editor's note
+TNO to provide further content
+:::
\ No newline at end of file

docs/terms/credential-type.md

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

docs/terms/credential.md

@@ -5,7 +5,7 @@ scopeid: essifLab
 type: concept
 typeid: credential
 stage: draft
-hoverText: "Credential: data, representing a set of statements (claims, assertions), authored and signed by, or on behalf of, a specific Party."
+hoverText: "Credential: data, representing a set of Assertions (claims, statements), authored and signed by, or on behalf of, a specific Party."
 ---
 
 ### Short Description

docs/terms/guardianship-type.md

@@ -9,15 +9,15 @@ hoverText: "Guardianship-type (in a Jurisdiction): a class of Guardianships (rel
 ---
 
 ### Short Description
-A **Guardianship-type** is a class of %%guardianship relationships|guardianship%% within the %%jurisdiction|jurisdiction%% that has defined it. It comprises %%duty and right types|duties-and-rights%% that can be used as a template for instantiating %%duties and rights|duties-and-rights%% of %%guardianship relationships|guardianship%% that instantiate the %%guardianship-type|guardianship-type%%.
+A **Guardianship-type** is a class of %%guardianship relationships|guardianship%% within the %%jurisdiction|jurisdiction%% that has defined it. It comprises %%duty and right types|pattern-duties-and-rights%% that can be used as a template for instantiating %%duties and rights|pattern-duties-and-rights%% of %%guardianship relationships|guardianship%% that instantiate the %%guardianship-type|guardianship-type%%.
 
 A good way to think abouat a %%guardianship-type|guardianship-type%% is to see it as a template from which instances - i.e. actual %%guardianship relationships|guardianship%% can be derived.
 
 ### Purpose
-A **Guardianship-type** serves as a template from which instances - i.e. actual %%guardianship relationships|guardianship%% can be derived. It allows the %%jurisdiction|jurisdiction%% within which it is defined to specify generic %%duties and rights|duties-and-rights%%, both for the %%guardian|guardian%% and the %%dependent|dependent%% in (instantiated) %%guardianship relationships|guardianship%%, without knowing which %%entities|entity%% will be(come) the %%guardian|guardian%% or the %%dependent|dependent%%.
+A **Guardianship-type** serves as a template from which instances - i.e. actual %%guardianship relationships|guardianship%% can be derived. It allows the %%jurisdiction|jurisdiction%% within which it is defined to specify generic %%duties and rights|pattern-duties-and-rights%%, both for the %%guardian|guardian%% and the %%dependent|dependent%% in (instantiated) %%guardianship relationships|guardianship%%, without knowing which %%entities|entity%% will be(come) the %%guardian|guardian%% or the %%dependent|dependent%%.
 
 ### Criteria
-An **guardianship-type** is a class of %%guardianship-relationships|guardianship%% that comprises a (non-empty) set of %%duty/right types|duties-and-rights%% for at least the %%guardian|guardian%% and/or the %%dependent|dependent%% (and perhaps other roles), the semantics of which are defined by the %%jurisdiction|jurisdiction%%.
+An **guardianship-type** is a class of %%guardianship-relationships|guardianship%% that comprises a (non-empty) set of %%duty/right types|pattern-duties-and-rights%% for at least the %%guardian|guardian%% and/or the %%dependent|dependent%% (and perhaps other roles), the semantics of which are defined by the %%jurisdiction|jurisdiction%%.
 
 ### Background
 The %%Guardianship pattern|pattern-guardianship%% provides an overview of how this concept fits in with related concepts.
\ No newline at end of file

docs/terms/duties-and-rights.md → docs/terms/pattern-duties-and-rights.md

 ---
-id: duties-and-rights
+id: pattern-duties-and-rights
 title: "Duties and Rights"
 scopeid: essifLab
 type: concept
-typeid: duties-and-rights
+typeid: pattern-duties-and-rights
 stage: draft
-hoverText: "Duties and Rights: this pattern describes the relations between Jurisdictions, Legal Entities and the duties and rights they have within them."
+hoverText: "The Duties and Rights pattern describes the relations between Jurisdictions, Legal Entities and the duties and rights they have within them."
 ---
 
 :::info Editor's Note
 TNO to provide content here
-:::
\ No newline at end of file
+:::
+
+##
\ No newline at end of file

docs/terms/pattern-guardianship.md

@@ -8,6 +8,8 @@ stage: draft
 hoverText: "The Guardianships pattern captures the Concepts and relations that explain what a generic Guardianshipconsists of, and how it relates to Guardians, Dependents, Jurisdictions, etc."
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl'
+
 :::info Editor's Note
 TNO to revise all below texts.
 :::

docs/terms/pattern-jurisdiction.md

@@ -8,6 +8,8 @@ stage: draft
 hoverText: "The Jurisdictions pattern captures the Concepts and relations that explain what a generic Jurisdiction consists of, and relates it to Parties and Legal Entities."
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl'
+
 ### Purpose
 <!-- Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it. -->
 The **Jurisdiction pattern** captures the concepts and relations that explain how generic %%jurisdictions|jurisdiction%%  work, and can be constructed. It shows that it can be seen as the composition of one %%scope|scope%%, one %%legal system|legal-system%% and one %%party|party%% that operates the legal system within that scope.

docs/terms/pattern-party-actor-action.md

@@ -8,6 +8,8 @@ stage: draft
 hoverText: "The Parties, Actors and Actions pattern captures the foundational concepts and relations that we need for thinking about how things get done. It answers questions such as: 'Who/what does things?', 'How are their actions being guided/controlled?', 'Who controls whom/what?', 'Who/what may be held accountable?'."
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl'
+
 ### Summary
 This pattern captures the foundational concepts and relations that we need for thinking about how things get done. It answers questions such as: "Who/what does things?", "How are their actions being guided/controlled?", "Who controls whom/what?", "Who/what may be held accountable?". It provides a way of looking at people (human beings), organizations, and how they interact with one another in a decentralized, self-sovereign way - which means that each of them decides for itself whether or not to interact with others, how to conduct such interactions, etc., thereby only taking external influences into account if they want, or have some need to do so.
 

docs/terms/validation-policy.md

+---
+id: validation-policy
+title: "Validation Policy"
+scopeid: essifLab
+type: concept
+typeid: validation-policy
+stage: draft
+hoverText: "Validation Policy: a Digital Policy that contains the rules, working-instructions, preferences and other guidance for determining whether or not data is valid for a specific purpose/objective of its Governor."
+---
+
+:::info Editor's note
+TNO (or others) to provide the content of this file.
+:::
+
+### Related Concepts
+- %%Digital Policy|digital-policy%%
+- %%Policy Governor|policy-governor%%
+- %%Validation|validation%%

docs/terms/validation.md

+---
+id: validation
+title: "Validation"
+scopeid: essifLab
+type: concept
+typeid: validation
+stage: draft
+hoverText: "Validation (of data): the process that a Party uses to determine whether or not that data is valid to be used for some specific purpose(s) of that Party."
+---
+
+:::info Editor's note
+TNO (or others) to provide the content of this file.
+:::
+
+Explain that validation is not verification:
+- verification (of data) is the process of determining whether or not what the data represents is in fact true (veracity).
+- validation (of data) is the process of determining whether or not data can be used to base a decision on. For example, a liquor selling party may determine that if someone simply says (s)he is 18+, that is valid data for deciding whether or not to sell the liquor, regardless of whether or not that statement is true.
\ No newline at end of file

docs/terms/verification.md

+---
+id: verification
+title: "Verification"
+scopeid: essifLab
+type: concept
+typeid: verification
+stage: draft
+hoverText: "Verification (of data): the process that a Party uses to determine whether or not what that data represents is in fact true (veracity)."
+---
+
+:::info Editor's note
+TNO (or others) to provide the content of this file.
+:::
+
+Explain that verification is not validation:
+- verification (of data) is the process of determining whether or not what the data represents is in fact true (veracity).
+- validation (of data) is the process of determining whether or not data can be used to base a decision on. For example, a liquor selling party may determine that if someone simply says (s)he is 18+, that is valid data for deciding whether or not to sell the liquor, regardless of whether or not that statement is true.
\ No newline at end of file

plugins/terminology-parser/index.js

@@ -31,7 +31,7 @@ function getAutoIncludeStatements(filePath) {
   var absoluteTermPath = path.resolve('./src/components');
   // Find the relative path between the file to be modified and the Term plugin
   var relativePath = path.relative(filePath, absoluteTermPath);
-  var importTerms = `\n\nimport useBaseUrl from '@docusaurus/useBaseUrl'\nimport { Term } from '${relativePath}'\n`;
+  var importTerms = `\n\nimport { Term } from '${relativePath}'\n`;
 
   return importTerms
 }