Commit 71c03ff8 authored by Rieks Joosten's avatar Rieks Joosten
Browse files

popup texts revised; added a few terms - all for the purpose of making readers...

popup texts revised; added a few terms - all for the purpose of making readers better understand texts.
parent 617cbb66
......@@ -13,3 +13,5 @@ yarn-error.log*
start_server.bat
*.ffs_batch
*.lnk
docs/vscode-%%-batch-replacer.txt
**/zzz-*
This diff is collapsed.
......@@ -20,12 +20,13 @@ We are working towards deprecating this convention, as we now have better ways o
%%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation, as follows:
- a **rectangle** represents a (named) concept that is explicitly defined. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct.
- A **rectangle** represents a (named) concept that is explicitly defined. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct.
- A **rectangle that is coloured red(dish)** represents a (named) concept that is commonly used ‘in the wild’ (and hence needs not be defined here), relates to one or more concepts that are explicitly defined yet is not the same. We include such ‘red concepts’ to help readers identify and subsequently bridge gaps between commonly held thoughts and the (sometimes subtly) different meanings we need in our model.
- a **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. We may refer to the concept at the arrowhead as the ‘target concept’ (TGT) for that relation. Similarly, the concept at the other end will be referred to as the ‘source concept’ (SRC) for that relation. Names are chosen such that `<SRC> <relation name> <TGT>` is a phrase that suggests the intension(al definition) of that relation.
- a **green name** at either end of a relation/association is what UML calls 'role'; this name may be used to refer to (an instance of) the concept at which the name is placed as it performs its/this role in this relation.
- a **dashed line** signifies that its intension is created by combination the intensions of other relations (it is a ‘shorthand’ for a path of other relations).
- an **open-ended arrow** is an ‘ISA’ relation, which can be read as `<SRC> ISA <TGT>`. It means that SRC is a specialization of TGT (which in turn is a generalization of SRC). This implies that SRC must satisfy all constraints that TGT must satisfy, and also that it has all attributes (including properties) that TGT has.
- a **solid line with a solid diamand** at one end is a composition; the element at the 'non-diamond-end' of the line is 'part of' (the 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' also cease to exist.
- a **solid line with a hollow diamand** at one end is an aggregation; the element at the 'non-diamond-end' of the line is 'part of' (the 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' usually do not cease to exist, but 'live on'.
- **Multiplicities** use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended.
- A **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. We may refer to the concept at the arrowhead as the ‘target concept’ (TGT) for that relation. Similarly, the concept at the other end will be referred to as the ‘source concept’ (SRC) for that relation. Names are chosen such that `<SRC> <relation name> <TGT>` is a phrase that suggests the intension(al definition) of that relation.
- A **solid line with an open arrowhead** represents an ‘ISA’ relation, which can be read as `<SRC> ISA <TGT>`. It means that SRC is a specialization of TGT (which in turn is a generalization of SRC). It means that SRC must satisfy all constraints that TGT must satisfy, and also that it has all attributes (including properties) that TGT has.
- A **solid line with a solid diamand** at one end is a composition; the element at the 'non-diamond-end' of the line is 'part of' (the 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' also cease to exist.
- A **solid line with a hollow diamand** at one end is an aggregation; the element at the 'non-diamond-end' of the line is 'part of' (the 'part') the element at the 'diamond-end' of the line (the 'whole'); if the 'whole' ceases to exist, then its 'parts' usually do not cease to exist, but 'live on'.
- A **green name** at either end of a relation/association is what UML calls 'role'; this name may be used to refer to (an instance of) the concept at which the name is placed as it performs its/this role in this relation.
- A **dashed line** with a closed arrow (solid triangle) signifies that its intension is created by combination the intensions of other relations (it is a ‘shorthand’ for a path of other relations).
- A **dashed line** with a pointed arrow (`>`) represents a dependency, where the SRC concept somehow depends on the TGT concept. The kind of dependency is specified by `<<text>>`, where `text` specifies the kind of dependency. Example: `<<instance>>` says that SRC is an instance (or: instantiates) TGT.
- **Multiplicities** (or: **cardinalities**) use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended.
---
id: essifLab-pattern-list
title: "eSSIF-Lab List of Patterns"
title: "eSSIF-Lab Ways of Thinking"
sidebar_label: Mental Models
---
:::info Editor's note
:::note Editor's note
TNO to write the introduction paragraph
Remainder of file to be generated (GRNET plugin/extension)
Remainder of file to be generated (GRNET plugin/extension) - currently, the file is maintained 'by hand'
:::
Within eSSIF-Lab, we maintain a set of %%mental models|mental-model%%, i.e. casual and formal descriptions (patterns) of %%concepts|concept%%, relations between them, and constraints, that provide a specific 'viewpoint', or 'way of thinking' about a certain topic.
:::info Editor's note
While some of the topics listed below are pretty much done, others are still need more work.
:::
We currently have models for the following topics:
- [Duties and Rights](./terms/pattern-duties-and-rights): The Duties and Rights pattern describes the relations between Jurisdictions, Legal Entities and the duties and rights they have within them.
- [Guardianship relationships](./terms/pattern-guardianship): The Guardianships pattern captures the Concepts and relations that explain what a generic Guardianship consists of, and how it relates to Guardians, Dependents, Jurisdictions, etc.
- [Jurisdictions](./terms/pattern-jurisdiction): The Jurisdictions pattern captures the Concepts and relations that explain what a generic Jurisdiction consists of, and relates it to Parties and Legal Entities.
- [Mandates, Delegation and Hiring](./terms/pattern-mandates-delegation-hiring): The Mandates, Delegation and Hiring pattern (which remains to be documented) captures the ideas behind Mandating, Delegating, Hiring and their relations. This is a work-in-progress.
- [Parties, Actors and Actions](./terms/pattern-party-actor-action): The Parties, Actors and Actions pattern captures the foundational concepts and relations that we need for thinking about how things get done. It answers questions such as: 'Who/what does things?', 'How are their actions being guided/controlled?', 'Who controls whom/what?', 'Who/what may be held accountable?'.
- [Terminology:](./terms/pattern-terminology): The eSSIF-Lab Terminology Pattern describes the relations between Terminology Terms such as 'Concept', 'Term', 'Pattern', 'Mental Model', 'Glossary' etc.
// 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
......
......@@ -24,5 +24,9 @@ The ability to distinguish between assertions and non-assertions, and particular
### Criterion
An **Assertion** is any declaration/statement that is made by one specific %%party|party%%.
### Notes
- Assertions may be ambiguous (multi-interpretable), which may result in misundertandings. The authoritative meaning of an %%assertion|assertion%% is determined by (the %%semantics|semantics%% that was applied by) the %%party|party%% that has uttered/authored it.
- Assertions may or may not be true. That is not only because 'truth' is subjective (every %%party|party%% may decide whether or not something is true), but also because the %%party|party%% that uttered/authored the %%assertion|assertion%% cannot substantiate the assertion, or lie outright.
-----
[^1]: we postulate that 'Nature' is the %%jurisdiction|jurisdiction%% in which the associated %%ownership relation|ownership%% exists; so one might also call this 'natural ownership'.
\ No newline at end of file
......@@ -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
......
---
id: dependent
title: "Dependent"
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."
---
:::info Editor's Note
TNO to revise all below texts.
:::
### Short Description
### 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
---
id: guardian
title: "Guardian"
scopeid: essifLab
type: concept
typeid: guardian
stage: draft
hoverText: "Guardian (of an Entity in a Jurisdiction): the Party that is tasked to care for and/or protect/guard/defend that Entity, for the purpose of which a Guardianship relationship has been established within that Jurisdiction."
---
:::info Editor's Note
TNO to revise all below texts.
:::
### Short Description
### 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
---
id: guardianship-type
title: "Guardianship-type"
scopeid: essifLab
type: concept
typeid: guardianship-type
stage: draft
hoverText: "Guardianship-type (in a Jurisdiction): a class of Guardianships (relationships) within the Jurisdiction that has defined it."
---
### Short Description
A **Guardianship-type** is a class of %%guardianship relationships|guardianship%% within the %%jurisdiction|jurisdiction%% that has defined it. It comprises %%duty and right types|pattern-duties-and-rights%% that can be used as a template for instantiating %%duties and rights|pattern-duties-and-rights%% of %%guardianship relationships|guardianship%% that instantiate the %%guardianship-type|guardianship-type%%.
A good way to think abouat a %%guardianship-type|guardianship-type%% is to see it as a template from which instances - i.e. actual %%guardianship relationships|guardianship%% can be derived.
### Purpose
A **Guardianship-type** serves as a template from which instances - i.e. actual %%guardianship relationships|guardianship%% can be derived. It allows the %%jurisdiction|jurisdiction%% within which it is defined to specify generic %%duties and rights|pattern-duties-and-rights%%, both for the %%guardian|guardian%% and the %%dependent|dependent%% in (instantiated) %%guardianship relationships|guardianship%%, without knowing which %%entities|entity%% will be(come) the %%guardian|guardian%% or the %%dependent|dependent%%.
### Criteria
An **guardianship-type** is a class of %%guardianship-relationships|guardianship%% that comprises a (non-empty) set of %%duty/right types|pattern-duties-and-rights%% for at least the %%guardian|guardian%% and/or the %%dependent|dependent%% (and perhaps other roles), the semantics of which are defined by the %%jurisdiction|jurisdiction%%.
### 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: guardianship
title: "Guardianship"
scopeid: essifLab
type: concept
typeid: guardianship
stage: draft
hoverText: "Guardianship (of a one 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."
---
:::info Editor's Note
TNO to revise all below texts.
:::
### Short Description
**Guardianship** is a relationship between a %%party|party%% (which we call the %%Guardian|guardian%%) and an %%entity|entity%% (which we call the %%Dependent|dependent%%) in which the %%guardian|guardian%%
in which one of these %%entities|entity%% (called the %%owner|owner%%) is entitled to enjoy, dispose of, and control the other %%entity|entity%% in an pretty much absolute (sovereign) fashion. Any guardianship relationship is grounded in ((the rules of) the %%legal system|legal-system%% of) a specific %%jurisdiction|jurisdiction%%, that maintains and enforces these rules, and that has means to resolve any disputes arising from that. To do this, both %%entities|entity%% must be %%legal entities|legal-entity%% in that %%jurisdiction|jurisdiction%%.
We may use the phrase %%natural guardianship%% to refer to an guardianship relation that exists in the %%jurisdiction|jurisdiction%% 'Nature' (see the notes of %%jurisdiction|jurisdiction%%). This enables us to talk about things as 'the (natural) guardianship of an %%assertion|assertion%%'.
### Purpose
**Guardianship** is a means by which %%jurisdictions|jurisdiction%% provide assurances to %%parties|party%% (within its scope) that they can enjoy, dispose of and control in pretty much any way they like. The %%legal system|legal-system%% of the %%jurisdiction|jurisdiction%% specifies these rights, and provides ways in which the %%owner|owner%% can exercize them (that provides the assurance).
### Criteria
An **guardianship** is a relationship between two %%legal entities|legal-entity%% (called the %%owner|owner%% and the %%owned|owned%%) within a single %%jurisdiction|jurisdiction%%, whose %%legal system|legal-system%% defines and enforces (a) rules that recognize the power of the %%owner|owner%% to enjoy, dispose of and control the %%owned|owned%% in an absolute (sovereign) fashion, and (b) rules that limit the absoluteness of that power.
### Related Concepts
- %%Owner|owner%%
- %%Owned|owned%%
### Notes
- Owning something does not imply posessing it (and vice versa). For example, if you find a coin that doesn't belong to you, you possess it but do not own it. Also, its rightful owner obviously owns it, but doesn't possess it at that point in time.
### 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: pattern-duties-and-rights
title: "Duties and Rights"
scopeid: essifLab
type: concept
typeid: pattern-duties-and-rights
stage: draft
hoverText: "The Duties and Rights pattern describes the relations between Jurisdictions, Legal Entities and the duties and rights they have within them."
---
:::info Editor's Note
TNO to provide content here
:::
##
\ No newline at end of file
---
id: pattern-guardianship
title: "Guardianship (Relationships)"
scopeid: essifLab
type: pattern
typeid: guardianship
stage: draft
hoverText: "The Guardianships pattern captures the Concepts and relations that explain what a generic Guardianshipconsists of, and how it relates to Guardians, Dependents, Jurisdictions, etc."
---
import useBaseUrl from '@docusaurus/useBaseUrl'
:::info Editor's Note
TNO to revise all below texts.
:::
### Purpose
The **Guardianship pattern** captures the concepts and relations that explain how generic %%guardianship relationships|guardianship%% work, and can be constructed. It shows that %%guardianships|guardianship%% are embedded in a %%jurisdiction|jurisdiction%% that govern such relationships.
The contribution of this pattern is to establish a building block and terminology for constructing a consistent, coherent and sufficiently complete mental model that allows %%parties|party%% to convey %%guardianship|guardianship%%-related ideas to other %%parties|party%%, without running the risk of being misunderstood, by expressing any %%guardianship|guardianship%%-related use-case in terms of the model. This will enable us to draft requirements and specifications for infrastructural IT, and make a start with specifying standardizable data structures (schemas) for use in combination with VCs.
### Introduction
The term ‘%%guardianship|guardianship%%’ has many definitions/descriptions. Examples are
- “The position of protecting or defending something” or “The position of being legally responsible for the care of someone who is unable to manage their own affairs.” (both from the [Oxford dictionary](https://www.lexico.com/en/definition/%%guardianship|guardianship%%)),
- “One who has the care of the person or property of another” or “One that guards” (both from [Merriam-Webster](https://www.merriam-webster.com/dictionary/%%guardianship|guardianship%%)),
- “The state or duty of being a guardian”, where ‘guardian’ is defined as “A person who has the legal right and responsibility of taking care of someone who cannot take care of himself or herself” or “Someone who protects something” ([Cambridge Dictionary](https://dictionary.cambridge.org/dictionary/english/)), or
- “The status of being a protector, advocate, or proxy for a person” ([Sovrin %%Guardianship|guardianship%% Task Force whitepaper](https://sovrin.org/wp-content/uploads/%%Guardianship|guardianship%%-Whitepaper.pdf)), which defines ‘guardian’ as “An organization or person protecting another person and possibly their property”.
- “The legal, social, or organizational responsibility of serving as a Guardian” ([Sovrin Glossary](https://docs.google.com/document/d/1gfIz5TT0cNp2kxGMLFXr19x1uoZsruUe_0glHst2fZ8/edit)), which also defines ‘guardian’ as “An Id%%entity|entity%% Owner who administers Id%%entity|entity%% Data, Wallets, and/or Agents on behalf of a %%Dependent|dependent%%”.
So, it seems that most people will acknowledge that '%%guardianship|guardianship%%' is a relation between
- someone (or an organization, collectively referred to as a '%%party|party%%') or something that is 'under %%guardianship|guardianship%%', i.e. being cared for, guarded, protected or defended - we call this the '%%dependent|dependent%%', and
- a %%party|party%% that does this caring, guarding, protecting or defending - we call this the '%%guardian|guardian%%'.
Note that '%%dependent|dependent%%' and '%%guardian|guardian%%' are roles in a %%guardianship relationship|guardianship%%; they do not have an independent existence (as e.g. a human being does). A '%%dependent|dependent%%' (or '%%guardian|guardian%%') only exists if someone fulfills this role in a %%guardianship relationship|guardianship%%, which in turn can only exist if both the '%%guardian|guardian%%' and '%%dependent|dependent%%' roles are being assigned.
_Example: in the [Mya](https://drive.google.com/file/d/10sfYKp6Ohi_rLsNqb1GBrhuE0IuoBX2k/view) use-case, a %%guardianship relationship|guardianship%% exists between Mya (as the %%dependent|dependent%%) and her grandmother Zo (as %%guardian|guardian%%). There is also a %%guardianship relationship|guardianship%% between Mya (%%dependent|dependent%%) and UNICEF (camp staff - as %%guardian|guardian%%)._
<!--_Example: In the [Jamie](https://drive.google.com/file/d/1bxE1DNxN80gkQrCbkJzBRzUsOf7KcjH2/view) use-case, … (text to be provided by @JohnPhillips)_-->
The actual activities that a %%guardian|guardian%% performs as (s)he cares for, guards, or … its %%dependent|dependent%% (in a specific %%guardianship relationship|guardianship%%) differ from case to case, and from situation to situation. Still, in general we can say that a %%guardianship relationship|guardianship%% comes with rights and duties that enable (or force) a %%guardian|guardian%% to execute specific actions - for the purpose of caring/guarding/… its %%dependent|dependent%%.
_Example: in the Mya use-case, the camp staff and Zo have the right to a daily food ration from the camp shop. Zo has the right to accompany Mya outside the camp. Etcetera._
A %%guardianship relationship|guardianship%% is meaningful to the extent in which such rights and duties are actually upheld and/or enforced.
_Example: if in the Mya use-case %%guardianship|guardianship%% is not properly enforced, human traffickers may pose as Mya's %%guardian|guardian%% to get her out of the camp so that she can be sold as a slave._
Defining and enforcing rights and duties, as well as resolving conflicts that may arise, are the very essence of a %%jurisdiction|jurisdiction%% - for details see the %%Jurisdictions pattern|pattern-jurisdiction%%
The wealth in varieties in %%guardianship relationships|guardianship%% can now easily be explained by observing that the various %%Jurisdictions|jurisdiction%% all exercise their self-sovereignty as they operate their %%legal systems|legal-system%%.
Example: in the Mya use-case, UNICEF sets the rules, enforces them and resolves related conflicts within its refugee camps, in its own, self-sovereign ways. This qualifies UNICEF as a %%jurisdiction|jurisdiction%%.
For a %%guardianship relationship|guardianship%% to be meaningful and relevant, it must be associated to a (single) %%jurisdiction|jurisdiction%% that creates, modifies and dissolves the relation, specifies who the %%guardian|guardian%% and %%dependent|dependent%% are, and assigns each of them a set of rights and duties (including 'negative' rights and duties, i.e. what they may/must NOT do). A %%jurisdiction|jurisdiction%% is implicitly tasked to enforce such rights and duties, and provide for the resolution of conflicts, yet is (and remains) self-sovereign in determining the extent in which it does so.
_Example: in the Mya use-case, UNICEF camp staff Sofia (is mandated to) determine whether or not a %%guardianship relationship|guardianship%% may be established between Mya and Zo, according to the rules that UNICEF has established for the camp. This kind of %%guardianship relationship|guardianship%% comes with some default rights and duties for Mya and Zo. For example, the %%guardian|guardian%% gets the right to daily obtain one additional food ration from the camp store for the %%dependent|dependent%%. Also, the %%guardian|guardian%% is allowed to take the %%dependent|dependent%% for a walk outside the camp. Depending on the rules UNICEF has put in place, Sofia might not issue all default rights/duties, or issue additional ones. If Zo dies, or Mya and Zo leave the camp, this %%guardianship relationship|guardianship%% becomes ineffective. In the meantime though, the rights/duties associated with the %%guardianship relationship|guardianship%% may change, to be determined by (qualified) UNICEF (personel)._
### Formalized model
Here is a visual representation of this pattern, using the following [notations and conventions](../notations-and-conventions#pattern-diagram-notations):
<img
alt="Conceptual model of the 'Guardianship' pattern"
src={useBaseUrl('images/patterns/pattern-guardianship-relationship.png')}
/>
In the figure, concepts are placed in one of three areas:
- **Goverenance** is about the %%governance|governance%% of %%guardianships|guardianship%%. It shows that %%guardianship-types|guardianship-type%% are defined by a %%jurisdiction|jurisdiction%%, and that instances of %%guardianship types|guardianship-type%%, i.e. %%guardianship relationships|guardianship%%, are governed by the %%jurisdiction|jurisdiction%%, and that both the %%guardian|guardian%% and %%dependent|dependent%% are %%legal entities|legal-entity%% within that %%jurisdiction|jurisdiction%%. For the Mya use-case, let's call the %%jurisdiction|jurisdiction%% `UNICEF refugee camp`.
- **Define-time** is about the design of guardianships, or guardianship templates if you will. In the Mya use-case, `UNICEF refugee camp` (perhaps itself abiding by more general UNICEF rules) would have defined a guardianship type (template) for cases where both the guardian and dependendent are refugees. For the use-case, let's call it `Refugee-Refugee-guardianship`. Then `UNICEF refugee camp` defines it to have duty/right types, e.g. "`guardian` has the right to obtain 1 food ration per day on behalf of `dependent`".
- **Run-time** is about the actual guardianship relationships, the actual duties and rights, and the actual entities involved in such relationships. In the Mya use-case, a guardianship relationship would exist that
- is governed by `UNICEF refugee camp`;
- instantiates guardianship type `Refugee-Refugee-guardianship`;
- comprises the duty/right "`Zo` has the right to obtain 1 food ration per day on behalf of `Mya`";
- specifies `Zo` as the guardian in the relationship;
- specifies `Mya` as the dependent in the relationship;
(note that Zo and Mya can only become guardian/dependent after having been registered within `UNICEF refugee camp`, or else they would not have been legal entities.)
An instance of such duty/right types are the actual duties and rights, e.g.
### Building Block: %%Guardianship Relationship|guardianship%% Pattern
:::info Editor's note
TNO to revise this section
:::
The figure shows that all (operational, or 'runtime') %%Guardianship Relationship|guardianship%% live within the context of a specific %%Jurisdiction|jurisdiction%%. A %%Guardianship Relationship|guardianship%% links two %%Legal Entities|legal-entity%% (LE's) within that %%Jurisdiction|jurisdiction%%, one which we will call the '%%guardian|guardian%%', the other the '%%Dependent|dependent%%'. The %%Guardianship Relationship|guardianship%% specifies rights and duties to each of them.
Note that such rights and duties may refer to LE's other than the %%guardian|guardian%% or %%Dependent|dependent%%, e.g. a third party against whom a right or duty may or must be exercised. We emphasize that such references must identify these %%entities|entity%% within the scope of the Knowledge of the %%party|party%% of the %%Jurisdiction|jurisdiction%%, because however obvious this may seem, in practice people often do not realize that this must be the case for the %%Legal System|legal-system%% of the %%Jurisdiction|jurisdiction%% to work.
The %%Legal System|legal-system%% of a %%Jurisdiction|jurisdiction%% may define (named) types of %%Guardianship Relationships|guardianship%%, e.g. 'Parenthood' or 'Curatorship', before any actual %%Guardianship Relationship|guardianship%% exists. Legal %%Jurisdictions|jurisdiction%% do that in their laws, while other %%Jurisdictions|jurisdiction%% may have other, perhaps more informal ways of defining them. A %%Guardianship Relationship|guardianship%% type definition will specify a set of generic rights and duties (which we call Duty/Right Types) for the %%entities|entity%% that will be assigned the roles of %%guardian|guardian%%, %%dependent|dependent%%, and perhaps others.
It is typical of a Duty/Right Type to NOT refer to individual %%entities|entity%%, but rather use placeholders that are to be filled in when a Duty/Right is created that is an instance of the Duty/Right Type.
So typically, a %%Jurisdiction|jurisdiction%% will define the set of %%Guardianship|guardianship%% Types that its %%Legal System|legal-system%% supports. For each of them, the %%Jurisdiction|jurisdiction%%:
- specifies the rules/laws that govern the creation and management of their instances,
- ptionally specifying processes (and possibly providing some or all means) to monitor/police compliance, and
- providing a mechanism for resolving disputes related to them.
Typically, the Task of creating a %%Guardianship Relationship|guardianship%% (GR) consists of:
- associating the GR with LE's for the positions of '%%guardian|guardian%%' and '%%dependent|dependent%%';
- associating the GR with an initial/default set of Hohfeldian Duties/Rights, the types of which are specified by the %%Guardianship|guardianship%% Type that the GR instantiates.
- assigning values for the placeholders that occur in the specifications of such Duties/Rights
The Task of managing a GR consists of adding, (un)suspending, revoking/removing instances of Duty/Right types that are meaningful in the %%Jurisdiction|jurisdiction%% as appropriate, and assigning values for any placeholders therein. Also, (un)suspending and/or revoking/invalidating the GR itself is part of that Task.
Note that an artefact that contains the specification of a GR may need to take various forms. For every kind of Actor that is envisaged to read and process such a specification, it must be represented in a language (syntax and semantics) that such an Actor knows how to read and process. This could mean that the artefact is only, or both human readable (in one or more languages) or machine readable (in one or more schemas).
### Notes
Having defined a mental model for %%guardianship|guardianship%%, and having applied it to the Mya use-case, we can make some generic observations.
1. %%guardianships|guardianship%% are typed in the same way that roles can be typed. The rights and duties that are associated with Roles that are assigned to e.g. a %%party|party%% (e.g. a department) will be quite different from those that are associated with Roles that are assigned to employees, or customers. We see this also happening with %%guardianships|guardianship%%: the rights and duties that are associated with a %%guardianship relationship|guardianship%% where the %%guardian|guardian%% is the %%party|party%% that operates the %%legal system|legal-system%% of a %%Jurisdiction|jurisdiction%% and the %%dependent|dependent%% is a refugee is quite different from a %%guardianship relationship|guardianship%% where the %%guardian|guardian%% and %%dependent|dependent%% are both refugees. One such difference is that in the first case, certain rights and duties can be delegated whereas in the latter case that is prohibited.
2. the meaning of %%guardianship relationships|guardianship%% is defined by a %%Jurisdiction|jurisdiction%% in the same way as the meaning of roles are defined by a %%Jurisdiction|jurisdiction%%. This meaning is given by the set of rights and duties that are assigned to the role/%%guardianship|guardianship%%, which in turn depend on the %%objectives|objective%% that the %%Jurisdiction|jurisdiction%% aims to contribute to by assigning them, and the Transaction Types and Transaction Type Roles it specifies in relation to this.
3. perhaps %%guardianship|guardianship%% is not all that special: at a functional level, they work quite the same as roles do, the difference only lying in the fact that roles are an assignment of rights, duties etc. to a (semantically properly defined) single %%legal entity|legal-entity%% (e.g. a Refugee, an Employee, etc.), whereas a %%guardianship|guardianship%% is an assignment of rights, duties etc. to a (semantically properly defined) ordered pair of %%Legal Entities|legal-entity%% (the first of which is called '%%guardian|guardian%%' and the other is called '%%dependent|dependent%%').
4. in a way, %%ownership|ownership%% may be considered a specialization of %%guardianship|guardianship%%. This is supported by the various definitions we find in different dictionaries - which all have a striking resemblance with definitions of '%%guardianship|guardianship%%'. Also, it is supported by the fact that:
- a %%party|party%% that owns something (an %%entity|entity%%) is entitled to do transactions (with that %%entity|entity%%) that other Parties are not entitled to, e.g. selling it.
- a %%party|party%% that owns an %%entity|entity%% typically protects or defends such %%entities|entity%% (their property); the %%party|party%% may also take care of it.
- like %%guardianships|guardianship%%, duties, rights, privileges etc. are being assigned to %%ownership|ownership%% by a %%Jurisdiction|jurisdiction%%.
- in the same way that a %%Jurisdiction|jurisdiction%% may have different kinds of %%guardianship|guardianship%%, they may have different kinds of %%ownership|ownership%% - a property that is well-known e.g. for corporations - and each kind of %%ownership|ownership%% may serve its own purposes.
One might argue that because of these similarities, '%%ownership|ownership%%' and '%%guardianship|guardianship%%' are the same. However, there is a difference, which is can be found in the kind of %%objectives|objective%% that (the %%party|party%% that governs) the %%jurisdiction|jurisdiction%%) pursues:
- %%ownership|ownership%% is about recognizing one's right to enjoy and (given some limitations) absolutely control something;
- %%guardianship|guardianship%% is more about a duty to care, defend and protect someone or something.
Since the %%Jurisdiction|jurisdiction%% model claims that %%Jurisdictions|jurisdiction%% own %%Objectives|objective%%, %%Guardianship|guardianship%% Types, and other things, this means that there is recursion, implying that %%Jurisdictions|jurisdiction%% are guardians of these things they own. Indeed, %%Jurisdictions|jurisdiction%% do have (implicit or explicit) rules that govern their %%Objectives|objective%%, %%Guardianship|guardianship%% Types, and whatever else they may have (by the very definition of %%Jurisdiction|jurisdiction%%).
......@@ -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