Commit 8bd7d725 authored by Rieks Joosten's avatar Rieks Joosten

documentation updates - wip

parent 8ab85441
Pipeline #16867 passed with stage
in 2 minutes and 49 seconds
This source diff could not be displayed because it is too large. You can view the blob instead.
......@@ -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.
......
// 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"
......@@ -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
......
......@@ -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.
......
---
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
---
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
......@@ -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
......
......@@ -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
---
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
......@@ -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.
:::
......
......@@ -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.
......
......@@ -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.
......
---
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%%
---
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
---
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
......@@ -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
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment