Skip to content

GitLab

Commit 1eadbe13 authored by Rieks Joosten's avatar Rieks Joosten
Browse files

Merge branch 'terminology-rieks' into 'master' 

updates of popover texts of 'verifier' .... 'wallet'

See merge request !5
parents 1907afd3 b9580ab6
Pipeline #15732 passed with stages
in 2 minutes and 57 seconds
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 0 additions and 1834 deletions
doc-sources/essif-lab-functional-architecture.md deleted 100644 → 0
View file @ 1907afd3
This diff is collapsed.
doc-sources/essif-lab-vision-and-purpose.md deleted 100644 → 0
View file @ 1907afd3
---
id: vision-and-purpose
title: eSSIF-Lab Vision and Purpose
---
The eSSIF-Lab vision is that Self-sovereign Identity (SSI) will *empower European and other citizens* by providing new means to manage privacy by eliminating logins and making electronic transactions fast and safe both in the Internet and in physical life. SSI will *empower European organisations and governments* by providing new means to speed up, secure and automate transactions with citizens, customers, suppliers and partners, resulting in tens of billions of euros savings annually on administrative costs in Europe. SSI will be *a new business ecosystem paradigm* with thousands of new jobs, many new job categories and new business opportunities for existing and new European companies. And last, but certainly not least, SSI fosters *inclusiveness* and supports organizations and citizens to exercise their rights and fulfil their duties under the GDPR.
The current situation is that SSI solutions that are being created and brought to the market either target specific applications for which they provide a vertical solution (‘stovepipes’), many need some kind of centralized governance/control, others have privacy issues, and none that we know of are interoperable with other such solutions.
The situation we would like to see is one in which we have SSI-enabled, interoperable and scalable technologies, that form an infrastructure that every application in any vertical can use in a very easy manner, for the exchange of verified (personal and non-personal) data. In that situation people, businesses and governments think more about the information they need and/or provide as they conduct business transactions. They no longer need to be concerned about the SSI technologies that have empowered them to make this happen.
:::tip **The purpose of the eSSIF-Lab...**
... is to specify, develop and validate technological and non-technological means that support people, businesses and governments to think about, design and operate their (information) processes and (electronically) conduct business transactions with one another.
:::
The context of the eSSIF-Lab vision can be found in articles 8-10 of the [*European Convention on Human Rights (ECHR)*](https://www.echr.coe.int/Pages/home.aspx?p=basictexts/convention), that state the rights of individuals regarding their privacy, and their freedoms to collect, process, store, and express information in a self-sovereign fashion, i.e. in a way that they can decide for themselves. This is without prejudice to Member States’ laws that exist to protect their national security, public safety, the economic well-being of the country, health or morals or the rights and freedoms of others, or to prevent disorder or crime. The eSSIF-Lab vision extends these rights and freedoms - within the limits of the law - to public and private organizations. Thus, we say that individuals as well as public and private organizations (that we collectively refer to as ‘parties’) are self-sovereign<sup>[1]</sup>.
In the context of these rights and freedoms, we seek to support electronic business transactions, i.e. the electronic exchange of goods, services, funds, or data between parties, which we call ‘participants’ to the transaction<sup>[2]</sup>.
An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic agent, i.e. equipment (e.g. an app on a mobile phone, a webserver, a browser, …) that acts on behalf of its owner in the transaction.
An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic agent, i.e. equipment (e.g. an app on a mobile phone, a web server, a browser, …) that acts on behalf of its owner in the transaction.
## High-Level Example of a Business Transaction
In its simplest form, this may be envisaged as one party (requestor) that requests another party (provider) to provide some product, e.g. a parking permit, by using his web-browser to navigate to the web-server of the provider (e.g. his municipality) where he is prompted to fill in a form to provide the details of his request (such as name, address, plate number, etc.). When the form is submitted, the provider decides whether or not to service the request (provide the parking permit) based on the data in the form, and take actions accordingly.
In order for this to work, the provider must design the form such that when a requestor submits a completed form, it can actually decide whether or not to service the request. This has two parts: first, the provider must specify the argument (i.e. the way of reasoning) that it uses to reach this decision - i.e. provide the parking permit. Doing so implicitly specifies the kinds of data that the form will ask for. Secondly, the provider must decide for each of the data it receives, whether or not it is valid to be used in that argument - the process of deciding this is called ‘validation’. Common criteria that help to make this distinction include whether or not the data is presented in the expected format, whether or not it is true (not so easy), whether it is not outdated, or whether or not it satisfies validation rules (in the example, the municipality may require that the specified license plate belongs to a car owned by the person that requests the permit). Validation is important, because reasoning with invalid data may result in wrong conclusions and cause damage.
Perhaps the most important contribution that the eSSIF-Lab project aims to make, is to create a ubiquitously used infrastructure for designing, filling in, and validating forms (not just web-forms, but also for ‘forms’ - e.g. JSON objects - in API requests). The benefits this will bring are enormous, but outside the scope of this document to list.
The figure below is a high-level visualization of the filling in and validation parts:
![eSSIF-Lab - vision context](https://essif-lab.pages.grnet.gr/framework//images/vision-context.png) *Figure 1. High-level visualization of the filling in and validation of a form.*
The transaction that is envisaged here is the issuing of a parking permit. Participants are a person (requestor) that requests such a permit, and an organization (provider) that can issue such a permit. The requestor has one electronic agent, *the Requestor Agent (RA)*, i.e. an SSI-aware app on their mobile phone that can access a secure storage that contains ‘credentials’, i.e. data that is digitally signed by some third party, thus attesting to the truth of that data. The provider has two agents: one is an SSI-aware component *Provider Agent (PA_* that works with the web-server that presents the form, and the other is a person *P* whose task is to validate any data (on behalf of the provider) that is not validated electronically. The form itself contains a means, e.g. a QR-code or a deep-link, that allows *RA* and *PA* to set up a secure communications channel (e.g. SSL, [DIDComm](https://openssi.github.io/peer-did-method-spec/)) and agree on the specific form that needs to be filled in.
After the *RA* and *PA* have established a communications channel and agree on the form to be filled in, *PA* informs *RA* about the information it needs to fill in the form, and the requirements that this information should satisfy<sup>[3]</sup>. *RA* then checks its data store to see whether or not such data is available, sends such data to *PA*, which subsequently validates it and uses it to fill in (appropriate parts of) the form. Finally, *P* validates the remaining data, which either results in a ‘clean’ form, i.e. a form that contains valid data that can subsequently be used to decide whether or not to provide the parking permit, or a message to the requester informing him about missing and/or invalid data.
When the transaction has been completed, both participants can issue a credential that attests to the results of the transaction. For example, the provider could issue a credential stating that the requestor has obtained a parking permit for a car with a specific plate number (and other attributes). The requestor can store this credential and from that moment on use it in new electronic transactions.
--------
[1] We realize that by doing this we have a different definition of what self-sovereignty entails than many others. We are open to suggestions for a better phrase.
[2] A good mental model for describing and designing transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations).
[3] Since transactions are symmetric, the requestor could also have a form that the provider needs to fill in so as to provide the requestor with the data it needs to commit to that transaction. We have left that out of this description for the sake of simplicity.
doc-sources/glossary.md deleted 100644 → 0
View file @ 1907afd3
---
id: essifLab-glossary
title: "eSSIF-Lab Glossary"
---
:::note Editor's note
TNO to write the introduction paragraph
:::
doc-sources/introduction.md deleted 100644 → 0
View file @ 1907afd3
---
id: introduction
title: Introduction
---
The European Self-Sovereign Identity Lab ([eSSIF-Lab](https://essif-lab.eu/)) views itself as an ecosystem of parties
that work together to make existing (and new) Self-Sovereign Identity (SSI) technology into
a scalable and interoperable infrastructure that businesses can use very easily
for conducting (business) transactions with other businesses and individuals alike.
Typically, the libraries, code or components for the infrastructure should be open source.
In order to support the use of such an infrastructure by businesses and individuals,
eSSIF-Lab parties also create applications and other tooling to support such actual use
on top of the interoperable infrastructure, which may or may not be open source,
and are expected to be used as/in products of organizations that want to make this their business.
At the start, eSSIF-Lab is one of the European [NGI projects](https://www.ngi.eu/ngi-projects/)
and helps (EU) parties that want to contribute by publishing [open calls](https://essif-lab.eu/?page_id=134)
to which such parties can submit work proposals that eSSIF-Lab will then consider for funding.
## eSSIF-Lab Framework Repository
This repo contains the documents that describe the vision, architecture and other
topics that are relevant to the eSSIF-Lab Framework. Currently, it contains:
- [Vision and purpose](vision-and-purpose)
- [Functional architecture](functional-architecture)
- [SSI standards](ssi-standards)
## Acknowledgement
This site is part of the eSSIF-Lab project that has received funding from the [European Union’s Horizon 2020 Research and Innovation Programme] under grant agreement Nº 871932.
\ No newline at end of file
doc-sources/notations-and-conventions.md deleted 100644 → 0
View file @ 1907afd3
---
id: notations-and-conventions
title: Notations and Conventions Used in this Documentation
---
Here, we provide an overview of the notations and conventions being used within eSSIF-Lab.
## RFC 2119
We shall use keywords such as “shall”, “should”, “may” etc. as defined by [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
## Capitalization of words in mid-sentence
Also, we capitalize words in mid-sentence whenever it is used in the meaning as provided by a corresponding Definition. This allows us to also use the more colloquial meanings of words (by not capitalizing them). We appreciate any feedback regarding our (im)proper use of this kind of capitalization of words.
We are working towards deprecating this convention, as we now have better ways to refer to %%definitions|definition%%.
## Pattern diagram notations
%%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation, as follows:
- a **rectangle** represents a (named) concept. Concepts serve as entity-classes. Their (operational) extensions, i.e. the respective sets of (runtime) instances, are disjunct.
- a **solid line with a closed arrowhead** represent a (named) relation/association between the two concepts it connects. The concept at the arrowhead is called the ‘target concept’ (TGT) for that relation. The concept at the other end is called 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 **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 is a generalization of SRC). Thus, SRC must satisfy all constraints that TGT must satisfy, and has all attributes (including properties) that TGT has.
- **Multiplicities** use the [n..m] notation. When a multiplicity is omitted, [0..n] is intended.
- A **concept that is coloured red(dish)** represents a notion that is commonly used ‘in the wild’ (and hence needs not be defined here), relates to one or more concepts we need for the pattern, 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.
\ No newline at end of file
doc-sources/pattern-list.md deleted 100644 → 0
View file @ 1907afd3
---
id: essifLab-pattern-list
title: "eSSIF-Lab List of Patterns"
---
:::note Editor's note
TNO to write the introduction paragraph
:::
doc-sources/ssi-standards.md deleted 100644 → 0
View file @ 1907afd3
---
id: ssi-standards
title: SSI Standards
---
The purpose of this document is to provide an overview of standards activities for self-sovereign identity (SSI) and their relevance to eSSIF-Lab.
## 1. Introduction
Self-sovereign identity (SSI) is work in progress, which includes the work on standards for SSI. Such standards include frameworks, schemas, data models, protocols, APIs, open-source code and more. The present document provides an overview on those standards and work-in-progress. Most pieces of text have been directly copied from the referenced websites.
## 2. W3C CCG: Credentials Community Group
The [W3C Credentials Community Group](https://www.w3.org/community/credentials/) explores the creation, storage, presentation, verification, and user control of credentials. It focuses on a verifiable credential (a set of claims) created by an issuer about a subject—a person, group, or thing—and seek solutions inclusive of approaches such as: self-sovereign identity; presentation of proofs by the bearer; data minimization; and centralized, federated, and decentralized registry and identity systems. Its tasks include drafting and incubating Internet specifications for further standardization and prototyping and testing reference implementations.
W3C CCG has published a first version of [Verifiable Claims Data Model and Representations 1.0](https://www.w3.org/2017/05/vc-data-model/CGFR/2017-05-01/) in May 2017. That specification introduces verifiable claims as follows.
A self-sovereign architecture for verifiable claims is one where the holder of a verifiable claim is in complete control of their identifier, where their verifiable claims are stored, and how they are used. There is currently no widely used self-sovereign, privacy-enhancing standard for expressing and transacting verifiable claims (aka: credentials, attestations) via the Web. This specification describes a data model for a digital [identity profile](https://www.w3.org/2017/05/vc-data-model/CGFR/2017-05-01/#dfn-identity-profile) and a collection of digital [entity credentials](https://www.w3.org/2017/05/vc-data-model/CGFR/2017-05-01/#dfn-entity-credential) that assert verifiable [claims](https://www.w3.org/2017/05/vc-data-model/CGFR/2017-05-01/#dfn-claim) about that [identity profile](https://www.w3.org/2017/05/vc-data-model/CGFR/2017-05-01/#dfn-identity-profile). It also describes how to express that data model in JSON, JSON-LD, and WebIDL.
## 3. W3C DID: Decentralized Identifier
The [W3C DID Working Group](https://www.w3.org/2019/did-wg/) standardizes the DID URI scheme, the data model and syntax of DID Documents, which contain information related to DIDs that enable the aforementioned initial use cases, and the requirements for DID Method specifications.
W3C DID is working on [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/). The June 2020 version of the working document introduces DIDs as follows.
<a>Decentralized identifiers</a> (DIDs) are a new type of identifier that enables verifiable, decentralized digital identity. A <a>DID</a> identifies any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) that the controller of the <a>DID</a> decides that it identifies. These new identifiers are designed to enable the controller of a <a>DID</a> to prove control over it and to be implemented independently of any centralized registry, identity provider, or certificate authority. <a>DID</a>s are URLs that associate a <a>DID subject</a> with a <a>DID document</a> allowing trustable interactions associated with that subject. Each <a>DID document</a> can express cryptographic material, verification methods, or <a>service endpoints</a>, which provide a set of mechanisms enabling a <a>DID controller</a> to prove control of the <a>DID</a>. <a>Service endpoints</a> enable trusted interactions associated with the <a>DID subject</a>. A <a>DID document</a> might contain semantics about the subject that it identifies. A <a>DID document</a> might contain the <a>DID
subject</a> itself (e.g. a data model).
## 4. Hyperledger Indy: distributed ledger software
[Hyperledger Indy](https://www.hyperledger.org/use/hyperledger-indy) provides tools, libraries, and reusable components for providing digital identities rooted on blockchains or other distributed ledgers so that they are interoperable across administrative domains, applications, and any other silo. Indy is interoperable with other blockchains or can be used standalone powering the decentralization of identity. The Indy repository can be found [here](https://wiki.hyperledger.org/display/indy/Hyperledger+Indy).
## 5. Hyperledger Aries: protocols for communication of VC and DID
[Hyperledger Aries](https://www.hyperledger.org/use/aries) provides a shared, reusable, interoperable tool kit designed for initiatives and solutions focused on creating, transmitting and storing digital verifiable credentials (VCs). It is infrastructure for blockchain-rooted, peer-to-peer interactions. The project consumes the cryptographic support provided by Hyperledger Ursa, to provide secure secret management and decentralized key management functionality.
Hyperledger Aries allows trusted online peer-to-peer interactions based on decentralized identities and verifiable credentials. Aries includes a protocol definition, tools, and reference implementations. The Aries protocol supports identities rooted in a variety of distributed ledgers or blockchains. This approach to identity is often called Self Sovereign Identity (SSI).
Key components of an [Aries solution](https://github.com/hyperledger/aries) are:
- [agents](https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0004-agents/README.md),
- [DID communications](https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0005-didcomm/README.md),
- [protocols](https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0003-protocols/README.md),
- and [key management](https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0051-dkms/README.md).
Moreover, Hyperledger Aries develops a set of Request for Comment (RFCs) that describe important topics standardize across the Aries ecosystem. There are 2 types of Aries RFCs:
- RFCs that describe individual features (in the [features](https://github.com/hyperledger/aries-rfcs/blob/master/features) folder)
- RFCs that explain concepts underpinning many features (in the [concepts](https://github.com/hyperledger/aries-rfcs/blob/master/concepts) folder)
RFCs are for developers *building on* Aries. They don't provide guidance on how Aries components implement features internally; individual Aries repos have design docs for that. Each Aries RFC includes an "implementations" section and all RFCs with a status greater than Proposed should have at least one listed implementation.
## 6. Hyperledger Ursa: cryptographic library
[Hyperledger Ursa](https://www.hyperledger.org/use/ursa) is a shared cryptographic library, it enables implementations to avoid duplicating other cryptographic work and hopefully increase security in the process. The library is an opt-in repository (for Hyperledger and non Hyperledger projects) to place and use crypto. Hyperledger Ursa consists of sub-projects, which are cohesive implementations of cryptographic code or interfaces to cryptographic code. The Ursa repository can be found [here](https://github.com/hyperledger/ursa).
## 7. DIF: Decentralized identity Foundation
[Decentralized Identity Foundation](https://identity.foundation/) (DIF) is an engineering-driven organization focused on developing the foundational elements necessary to establish an open ecosystem for decentralized identity and ensure interop between all participants.
DIF builds on W3C and Hyperledger work referenced above. Some of its work originates from Hyperledger Aries and has been moved to DIF for more effective management of IPR. DIF has among others the following working groups.
* [Identifiers and Discovery](https://identity.foundation/working-groups/identifiers-discovery.html): A key piece of the decentralized identity equation is how people, organizations, and devices can be identified and located without centralized systems of identifiers (e.g. email addresses). DIF members are actively working on protocols and implementations that enable creation, resolution, and discovery of decentralized identifiers and names across decentralized systems, like blockchains and distributed ledgers.
* [Storage and Compute](https://identity.foundation/working-groups/storage-compute.html): Secure, encrypted, privacy-preserving storage and computation of data is a critical component of decentralized identity systems. As with identifiers and names must be self-sovereign to the owning entity, a user's identity data must remain private, only accessible to the entities they allow. DIF members are actively developing specs and reference implementations for provider-agnostic, run-anywhere solutions that provides these features.
* [Authentication](https://identity.foundation/working-groups/authentication.html): Designing and implementing DID-based authentication specs, standards, and libraries used in authenticating DIDs across a wide variety of exchanges and use cases.
* [Claims and Credentials](https://identity.foundation/working-groups/claims-credentials.html): The ability to verify the claims and assertions of identities is key in establishing trust among entities on a decentralized system that lacks a centralized hierarchy. The DIF Foundation has recently begun work on defining the specs, protocols, and tools it can provide to the ecosystem to help ecosystem participants and their customers easily integrate DID-signed claims into their apps and services.
* [DID Communication](https://identity.foundation/working-groups/did-comm.html): Produce one or more high-quality specs that embody a method (“DIDComm”) for secure, private and (where applicable) authenticated message-based communication, where trust is rooted in DIDs and depends on the messages themselves, not on the external properties of the transport(s) used.
* [Secure Data Storage](https://identity.foundation/working-groups/secure-data-storage.html): Create one or more specifications to establish a foundational layer for secure data storage (including personal data), specifically data models for storage and transport, syntax, data at rest protection, CRUD API, access control, synchronization, and at least a minimum viable HTTP-based interface compatible with W3C DIDs/VCs.
## 7. Sovrin: SSI blockchain
The [Sovrin Foundation](https://sovrin.org/) is a private-sector, international non-profit that was established to govern the world's first self-sovereign identity (SSI) network. The Sovrin blockchain network is based on Hyperledger Indy. Sovrin is governed by the [Sovrin Governance Framework](https://sovrin.org/library/sovrin-governance-framework/), which is a set of official documents that include legal agreements between participants in Sovrin. The services of Sovrin are registrations on the Sovrin blockchain: DIDs and DID Documents, VC schemas (generic), VC definitions (issuer-specific) and VC revocations. From 2017-2020, Sovrin has been funded via donations (Sovrin Alliance) and sale of future SOV tokens. In 2020, Sovrin started a transition process, revising its financing and structure.
## 8. Trust-over-IP: full-stack governance
The [Trust-over-IP foundation](https://trustoverip.org/) was founded mid 2020. It is defining a complete architecture for Internet-scale digital trust that combines both cryptographic trust at the machine layer and human trust at the business, legal, and social layers. It is has the following working group, as well as a few more that are still being started.
* [Governance Stack](https://trustoverip.org/working-groups/governance-stack/): The scope of the Governance Stack Working Group is to define models and interoperability standards for governance frameworks that enable business, legal, and social trust between entities implementing the Trust over IP architecture stack as defined in [Hyperledger Aries RFC 0289](https://github.com/hyperledger/aries-rfcs/tree/master/concepts/0289-toip-stack) (or its successor as identified in the RFC document itself).
* [Technical Stack](https://trustoverip.org/working-groups/technical-stack/): The scope of the Technical Stack Working Group is to define (directly or by reference) the technical standards, test suites, and interoperability certification standards for the Trust over IP architecture stack as defined in [Hyperledger Aries RFC 0289](https://github.com/hyperledger/aries-rfcs/tree/master/concepts/0289-toip-stack) (or its successor as identified in the RFC document itself).
* [Utility Foundry](https://trustoverip.org/working-groups/utility-foundry/): The scope of the Utility Foundry Working Group is to facilitate a community of practice among governance authorities, implementers, operators, and service providers for Trust over IP Layer One utilities. The WG will provide process guidance for the establishment and monitoring of new ToIP Layer One utility projects, whether hosted at the Linux Foundation or external to it. Other WG activities will include creating template RFPs for service providers, maintaining a list of affiliated Foundry Service Providers, identifying areas of collaboration and alignment between associated and/or disparate Utilities, and where possible serving as a center of competence for the education and promotion of the role of ToIP Layer One utilities.
* [Ecosystem Foundry](https://trustoverip.org/working-groups/ecosystem-foundry/): The scope of the Ecosystem Foundry Working Group is to facilitate a community of practice among governance authorities, implementers, operators, and service providers of Trust over IP Layer Four ecosystems. The WG will provide process guidance for the establishment and monitoring of new ToIP Layer Four ecosystem projects, whether hosted at the Linux Foundation or external to it. Other WG activities will include creating template RFPs for service providers, maintaining a list of affiliated Foundry Service Providers, identifying areas of collaboration and alignment between associated and/or disparate ecosystems, and where possible serving as a center of competence for the education and promotion of the role of ToIP Layer Four ecosystems.
## 9. Relevance to eSSIF-Lab
The above-mentioned standards, open source and governance are relevant to eSSIF-Lab in multiple ways.
* Using: Subgrantees of eSSIF-Lab will implement some of these standards, and fork existing open-source code.
* Testing: Subgrantees of eSSIF-Lab will perform interoperability tests of their implementations against other within eSSIF-Lab and outside, likely including the European [EBSI-ESSIF](https://www.eesc.europa.eu/sites/default/files/files/1._panel_-_daniel_du_seuil.pdf), the American [DHS-SVIP](https://www.dhs.gov/science-and-technology/svip).
* Contributing: Subgrantees of eSSIF-Lab will also be required to contribute to standards development where relevant.
\ No newline at end of file
doc-sources/terminology-plugin-instructions.md deleted 100644 → 0
View file @ 1907afd3
---
id: terminology-plugin-instructions
title: Terminology & Glossary plugin docs
---
import useBaseUrl from '@docusaurus/useBaseUrl';
### How it works
This plugin parses docs in two ways:
1. Parses all `*.mdx` files under `docs/` and replaces each pattern with an
appropriate React component supporting a tooltip functionality (see below)
2. Generates a glossary with all terms corresponding to the `*.md` files under `docs/terms/`.
Parses all markdown files and generates a glossary page with all the pattern terms found in the .md files
## Replace patterns with dynamical elements
When writing docs, in order to refer to a term, you may use the following syntax:
```
%%term_text|term_name%%
```
where:
- `term_text`: The terminology text you want it to be visible in the documentation
page
- `term_name`: The filename of the term file, which resides under `./docs/terms` directory.
inside `docs/*.mdx` files. After successfully running the script, the above occurrence
will be replaced by a React component, which will render `term_text` as a link to the
corresponding term page, which is in turn generated from the `term_name` attribute;
furthermore, *hovering* over `term_text` displays a term summary, as extracted from the
corresponding term page.
### Example usage
Say you want to reference a term that exists under the `./docs/terms/` directory,
e.g. `./docs/terms/party.md`. You can use the following syntax to reference
this term in your documentation page:
```
Some content that wants to reference the %%Party|party%% term
```
When the script runs, this will be replaced as follows:
```
Some content that wants to reference the <Term reference="party" popup="Popup text">Party</Term> term
```
which supports the functionality explained above.
### How to correctly write a term
This plugin assumes that you follow the structure, as explained below:
Each term should have its own `.md` file, inside the `./docs/terms` directory,
and it needs to consist of the following structure:
```title="./docs/terms/term.md"
---
id: term
title: Term page
stage: draft
hoverText: This hover text will appear in the documentation page that you reference this term
---
### Term explanation
content here
```
> Pay attention to the `hoverText` attribute, as it's important to provide this
>attribute (along with the default docusaurus attributes), so the plugin can
>fetch the correct popup text to show when referencing a term.
### Running the script
When you are finished referencing terms and have written corresponding term pages,
you can test this locally by running the following command:
```.shell script
$ yarn parse
yarn run v1.22.5
docusaurus parse
Replacing patterns with <Term />
Done in 1.41s.
```
This will replace all `%%term_text|term_name%%` occurrences with the React component
supporting the required functionality.
Here's an example where the terms have been replaced. When the project is up
and running, you can visit the test example on the `/docs/replacement-test` page:
<img alt="replacement-test" src={useBaseUrl('images/replacement-test.png')}/>
## Generate the glossary page
If everything works well with the above procedure, you can then generate a
glossary page, by running the following command:
```.shell script
$ yarn glossary
yarn run v1.22.5
docusaurus glossary
Alphabetical list of terms
Done in 1.53s.
```
This will generate a file in `./docs/glossary.md` where every term that has been
mentioned above, will be populated in the `glossary.md` page.
When the project is up and running, you can visit the glossary on the `/docs/essifLab-glossary` page:
<img alt="glossary-page" src={useBaseUrl('images/glossary-page.png')}/>
doc-sources/terminology.md deleted 100644 → 0
View file @ 1907afd3
---
id: terminology
title: "eSSIF-Lab: Concepts and Terminology"
scopeid: essifLab
---
:::info **UNDER CONSTRUCTION**
*This (initial version of the) terminology chapter is currently under construction. If you feel like making a contribution, please contact [the editor](mailto:rieks.joosten@tno.nl)*
:::
The purpose of the eSSIF-Lab Terminology is to provide mental models that all of its stakeholders interpret in sufficiently the same way, so as to be able to talk, think and discuss about what it is we try to achieve and ways to achieve this.
## Introduction
Contributors to and users of eSSIF-Lab come from various backgrounds. Their culture may not be Western. English may not be their native tongue. They may be experts in non-technological topics. Working with one another presumes a setting where participants have some level of shared understanding. Often, sharing one's understanding at a superficial level suffices. Other situations require that underlying concepts are shared in a more in-depth fashion. It's like cars: people buying, selling, or driving cars do not need in-depth shared knowledge about cars, whereas (maintenance or construction) engineers or liability lawyers need to share a deeper knowledge of how cars do (or do not) work.
We expect to see situations of "language confusion", i.e. in which people use words or phrases, the intension (not: intention) of which differs from the interpretation of some listeners/readers. Sometimes a casual glance at a dictionary or glossary is the solution. In other cases, deeper understanding matters, e.g. in when drafting specifications or contracts. Then [we need more than a set of definitions](https://www.sfu.ca/~swartz/definitions.htm).
The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community participants understand one another at whatever level of precision they need.
## Glossaries
The traditional tool for fostering common understanding is using glossaries, i.e. alphabetical lists of words relating to a specific subject, text, or dialect, with explanations; a brief dictionary ([OED](https://www.lexico.com/definition/glossary)). Examples include the [Sovrin Glossary](https://sovrin.org/library/glossary/) and the [NIST Glossary](https://csrc.nist.gov/glossary). Other initiatives attempt to provide more background, e.g. the [terminology for talking about privacy by data minimization](https://dud.inf.tu-dresden.de/literatur/Anon_Terminology_v0.34.pdf) by Pfitzmann and Hansen (2010), or the [EBSI Terminology (login required)](https://ec.europa.eu/cefdigital/wiki/display/EBP/EBSI+Terminology).
The eSSIF-Lab project will also develop a [Glossary](/docs/essifLab-glossary).
However, since the use of such glossaries is limited to short explanations, we will also provide (a) mental model(s) that provide a more in-depth explanation of the concepts that underly the words listed in the [eSSIF-Lab Glossary](/docs/essifLab-glossary).
## Mental Models
We have the following mental (conceptual) models:
A Mental Model, or Conceptual Model, is a set of of concepts (i.e. entity classes), relations between such concepts (i.e. sets of pairs of members of classes that a relation connects), and rules/constraints expressed in terms of these relations and concepts.
The first purpose of a Mental Model is to help us think and reason about a certain topic or issue.
One signal that indicates the need of such a model is when we’re running circles in our thoughts, and we have this feeling of not understanding, of the topic being (too) complex. Often, we are thinking in terms of concepts that are not fit for the objectives we pursue.
So a mental model requires careful construction, that allows the choices for its elements to be validated against many use-cases. Such validation instills trust that our model elements (concepts, relations, rules) are well-chosen. It also provides us with the experience (usually after some time) that it has made our thinking easier, and we are better equipped to resolve issues.
The careful construction is comparable to a quest: it takes time, multiple versions, and careful reflection. And it needs continuous validation of its parts, by throwing use-cases at it and verifying that the model can describe such cases, and do some reasoning with them.
This careful construction must ensure that the mental model gets different properties. For starters, the model must be able to reason in (all) static situations, where things do not change, and the so-called ‘invariant’ rules/constraints must hold. Also, the model must be able to cope with time-dependencies and changes, for which other kinds of rules apply.
In the end, the mental model needs to be expressed in several, different ways, depending on whom we want to convey the ideas behind it to. Business people generally need simple models that allow them to (roughly) grasp its gist. Software architects need models with precise definitions that allow them to use its elements in (formal) reasonings. Software engineers (programmers) need all the details that allow them to create applications and databases that work according to the model’s intent. So the level of detail that an expression of the model provides, makes it useful or useless to different audiences.
## Terminology and Definitions
We attempt to create definitions that are both acceptable for business people yet are precise enough to serve as a basis for formal reasoning. We do this by using [intensional definitions](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions), i.e. by defining criteria that specify the necessary and sufficient conditions for when a term should be used. We have tried to craft these definitions such that
- readers are likely to make the same judgements when using them, and
- these distinctions are relevant for our purposes. That’s the important stuff.
The actual texts we choose as the name for a concept is of secondary importance; if in a particular context other names are more suitable, you can rename them there without loss of meaning or consistency.
Together with these criteria, we provide a limited set of examples to help the reader to visualize the defined concepts, and to point out possibly unexpected consequences of the criteria. Also, we may motivate the need for having a concept by showing its relevance for the model.
Here are some examples:
:::note
**The following definitions will be moved to a separate eSSIF-Lab Terminology section**
:::
### Definition
**Entity that comprises at a minimum**:
- **a non-empty set of scopes in each of which specific objectives are being pursued;**
- **a criterion that specifies the necessary and sufficient conditions for being an instance of a named class;**
- **a set of arguments and/or use-cases (that SHOULD not be empty), and that show the relevance of making this distinction within the scope (and for its objectives);**
- **a name that is created and used within the scope that created the definition, for the purpose of referring to the class, or using it as a placeholder for its instances.**
**For the purposes of this document, the scope of every Definition is this Document (with its objectives that have been specified above).**
Note that this definition satisfies itself. Also note that a definition may be used in multiple scopes, where a scope that wants to use the definition that has been defined in another scope, may replace that name with one of its own choosing. This way the meaning expressed by the definition remains preserved.
doc-sources/terminology/README.md deleted 100644 → 0
View file @ 1907afd3
# README for terminology-related files.
:::info
The entire terminology section is still experimental/under construction
:::
## Purpose
The purpose of the eSSIF-Lab Terminology Corpus is to help people that want or need to
- understand the gist of texts about various topics (learners, CxO's);
- write texts on (a) specific topic(s) (authors);
- deeply understand texts (reviewers, domain experts);
- prevent and/or resolve misunderstandings with others working on the same/similar topics (engineers);
- make (e.g. design) decisions concerning specific topics based on solid, consistent and coherent arguments;
- create code and/or data models for automation purposes;
- etc.
We have an [introduction](terminology) that explains how we go about all this.
## Directory Contents
- Directories:
- `eSSIFLab`, which contains all the documents for the scope `eSSIFLab`; its subdirectories contain the documents for the various subscopes, as appropriate.
- `templates` (directory) contains templates that authors may use to [contribute to, or specify new content](readme-making-contributions).
- Files:
- [terminology](terminology) specifies the purposes that the terminology work intends to serve, and the ways in which this is done.
- [readme-making-contributions](readme-making-contributions) is a guide for people that want to create, generate or update new ***content***.
- [readme-generator-extensions](readme-generator-extensions) is a guide for people that want to create or modify the generators that produce the actual terminological artifacts from the content produced by authors.
doc-sources/terminology/essifLab/action.md deleted 100644 → 0
View file @ 1907afd3
---
id: action
title: "Action"
scopeid: essifLab
type: concept
typeid: action
stage: draft
hoverText: "something that is actually done/executed by a single actor (as a single operation) for some party within 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 the %%knowledge|knowledge%% of that party. The actor is assumed to have appropriate access to the knowledge of that party. In order to properly execute the action, the executing actor may also use additional knowledge(s) to which it has access.
## 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), and as a consequence may be permitted and/or required to execute them. Also, this ability enables parties to determine the execution-policy, i.e. the set of rules and other guidance that actors should obey or comply with when exeucting an action on its behalf.
## Criterion:
An **Action** is something that is done by an actor, can be considered a single operation, and is performed in a specific context, for or on behalf of a specific party, i.e. in accordance with the policy rules that this party has established for such actions.
## Examples:
- filling in a form and submitting it.
- cleaning a car.
## Related Concepts
<!--Link to any concepts that are similar but distinct, with a note about the relationship.-->
- OED defines Action as the fact or process of doing something, typically to achieve an aim ([OED](https://www.lexico.com/definition/action)), which is too generic for our purposes.
## Background:
The %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
\ No newline at end of file
doc-sources/terminology/essifLab/actor.md deleted 100644 → 0
View file @ 1907afd3
---
id: actor
title: "Actor"
scopeid: essifLab
type: concept
typeid: actor
stage: draft
hoverText: "Entity that can act (do things), e.g. people, machines, but not organizations."
---
## 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.
## 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).
## Criterion:
Entity that is capable of actually executing %%actions|action%% (acting, doing things).
## Examples:
- People (human beings) obviously qualify, as do robots and other machines.
- Stones, pictures, ideas, etc. do not qualify.
- Software applications qualify, provided they are actually running on hardware. An app that is just sitting e.g. on a mobile phone but isn't executed does not qualify.
- Enterprises, governments, and other %%organizations|organization%% do not qualify.
## Background:
The %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
doc-sources/terminology/essifLab/agent.md deleted 100644 → 0
View file @ 1907afd3
---
id: agent
title: "Agent"
scopeid: essifLab
type: concept
typeid: agent
stage: draft
hoverText: "An actor that is (at that point in time) executing an action for, or on behalf of a Party."
---
## Short Description
%%Actors|actor%% execute %%actions|action%% for, or on behalf of some %%party|party%%, because parties are not considered to be capable of acting.[^1] Agents must act in accordance with the party for which they execute such actions, which means that for every kind of action, such parties must provide the proper guidance for their agents, e.g. in terms of policies (rules), working instructions, programs etc. We use the term %%digital agent|digital-agent%%
## Purpose
The ability to distinguish between (non)agents is relevant in many situations, including:
- electronic communication: the agent
## Criterion:
a property that is attributed to an %%Actor|actor%% whenever it is executing an action for, or on behalf of some %%party|party%%.
## Examples:
- A person that is 'doing its own things' acts as an Agent for himself.
- A person that does things for his employer acts as an Agent for that employer.
- An ambassador, when (s)he is 'in function', acts as an Agent for the country for which (s)he is ambassador.
- A person that fills in the tax return form for someone else acts as an Agent for this someone else.
- 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 %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
doc-sources/terminology/essifLab/digital-agent.md deleted 100644 → 0
View file @ 1907afd3
---
id: digital-agent
title: "Digital Agent"
scopeid: essifLab
type: term
typeid: digital-agent
conceptref: ":Agent"
stage: draft
hoverText: "An Actor in the digital world (e.g. a running app, or a web-server) that executes actions for a specific party."
---
## Purpose
<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
The ability to distinguish between (non)digital actors allows us to exclusively talk about software/hardware actors and their agency.
doc-sources/terminology/essifLab/eSSIFGlue.md deleted 100644 → 0
View file @ 1907afd3
---
id: eSSIFGlue
title: "eSSIF-Glue"
scopeid: essifLab
type: concept
typeid: eSSIFGlue
stage: draft
hoverText: "eSSIFGlue"
---
## Short Description
The **eSSIF-Glue** is an interface layer that consists of a documented set of APIs between the %%TVE|tve%% and %%TRD|trd%% on the one hand, and the Wallet, Holder, Issuer and Verifier (WHIV) components on the other hand.
Ultimately, we would like to see these APIs standardized. Having such APIs allows different Parties to create their own version of the WHIV components, supporting the SSI technologies as they see fit, and shrinking or expanding functionalities as they feel appropriate. Parties can then select such WHIV components as they see fit.
## Purpose
The purpose of the essif-Glue APIs is to make calling the WHIV functions as simple as possible, given the functions of the %%TVE|tve%% and %%TRD|trd%%
## Criterion:
The set of API's described at https://gitlab.grnet.gr/essif-lab/tno-ssi-service/developer-docs.
doc-sources/terminology/essifLab/entity.md deleted 100644 → 0
View file @ 1907afd3
---
id: entity
title: "Entity"
scopeid: essifLab
type: concept
typeid: entity
stage: draft
hoverText: "something that is known to exist"
---