Commit 073a90a3 authored by Rieks Joosten's avatar Rieks Joosten Committed by fmerg

setting documentation sources apart for future work

parent 248e9941
This diff is collapsed.
---
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.
This diff is collapsed.
This diff is collapsed.
---
id: essif-lab-glossary
title: eSSIF-Lab Glossary
---
---
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
---
id: mdx
title: Powered by MDX
---
You can write JSX and use React components within your Markdown thanks to [MDX](https://mdxjs.com/).
export const Highlight = ({children, color}) => ( <span style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}> {children} </span> );
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
---
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
---
id: NewTermID
title: "Concept: <New Term> (Scope: <Existing Scope>)"
scopeid: <ExistingScopeID>
termid: <NewTermID>
hoverText: "<Text that pops up when the user hovers over a reference to this concept>"
---
<!--A concept tries to capture the idea behind a classification of entities, allowing us to reason about everything in the class as if it were one thing. This file specifies the idea(s) that, within the scope of `<ExistingScopeID>` will be referred to using <New Term>.
Please fill in the placeholders in this file as follows:
- `<ExistingScopeID>`: machine readable text that identifies the scope in which this term is defined;
- `<Existing Scope>`: human readable text that identifies the scope in which this term is defined;
- `<NewTermID>`: machine readable text that identifies this term within <ExistingScopeID>;
- `<New Term>`: human readable text that identifies this term within <Existing Scope>;
-->
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
## Purpose
<!--Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this concept relevant within its scope of definition?-->
## Criteria
<!--REQUIRED--How is this concept different from related ideas? What are essential characteristics that must be true? This is where you specify the [intensional definition](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions) of the concept, i.e. the necessary and sufficient conditions for when the term should be used. This makes that the concept becomes crystal clear. In the case of nouns, this is equivalent to specifying the properties that an object needs to have in order to be counted as a referent of the term.-->
## Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `<New Term>`, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.-->
## Related Concepts
<!--Link to any concepts that are similar but distinct, with a note about the relationship.-->
## Domains
<!--In which general knowledge ecosystems or mental model families does this concept play a role?-->
## Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
## Use-cases
<!--This (optional) section specifies an (optional) introductory paragraph, and a level-3 (i.e. `###`) subsection for every use case it describes. Every such use-case SHOULD
- describe the situation/context of the use-case;
- show how to apply `<New Term>` to/in that situation;
- shows the relevance of having `<New Term>` for the use-case as opposed to not having it.-->
## Notes
<!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
id: ExistingScopeID-conceptproposal-NewTermID
title: "Concept proposal for: <NewTermID> (Scope: <Existing Scope>)"
scopeid: <ExistingScopeID>
term: <NewTerm>
hoverText: "<Text that pops up when the user hovers over a reference to this concept>"
---
<!--A concept tries to capture the idea behind a classification of entities, allowing us to reason about everything in the class as if it were one thing. This file specifies the idea(s) that, within the scope of `<ExistingScopeID>` will be referred to using <New Term>.
Please fill in the placeholders in this file as follows:
- `<ExistingScopeID>`: identifier of the scope in which the term is defined;
- `<Existing Scope>`: human readable text that identifies the scope in which this item is defined;
- `<NewTerm>`: term that will identify the concept within <ExisingScopeID>;
- `<ExistingTerm>`: term by which the concept is concept is known in that scope
-->
## One-line Summary
A single sentence that describe the concept to a layperson with reasonable accuracy. This line may be used to explain `Concept` in a glossary, or as a popover text when it is referred to in other documentation.
For example: "A warm-blooded animal, often having fur or hair, that produces milk to feed its young."
## Short Description
in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.
For example, the concept of a "mammal" in biology might be described as: "A warm-blooded animal, often having fur or hair, that produces milk to feed its young. Examples include rats, whales, and bats." A diagram could be included, if appropriate. The goal here is not perfect clarity; that's the focus of the 'Criteria' section.
## Purpose
Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this concept relevant within its scope of definition?
## Criteria
How is this concept different from related ideas? What are essential characteristics that must be true? This is where you specify the [intensional definition](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions) of the concept, i.e. the necessary and sufficient conditions for when the term should be used. This makes that the concept becomes crystal clear. In the case of nouns, this is equivalent to specifying the properties that an object needs to have in order to be counted as a referent of the term.
a vertibrate that has mammary glands, a neocortex in the brain and 3 middle ear bones.
## Examples
Provide a few sentences in which you give examples that obviously qualify as instances of NewTerm, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.
Primates (humans, monkeys), rodents (mice, rats), bats, and others qualify. Birds and reptiles do not (they lack mammary glands). [Platypus](https://en.wikipedia.org/wiki/Platypus)[^1] is also a mammal, even though it lays eggs.
## Related Concepts
Link to any concepts that are similar but distinct, with a note about the relationship. For example:
* offspring (of a mammal) is the set of mammals that are born from that mammal.
* mate (of a mammal) is any mammal of the same species with which the mammal has created ofspring.
## Domains
In which general knowledge ecosystems or mental model families does this concept play a role? For example:
* Biology
## Tags
Add hash tags here that allow us to group concepts in useful ways.
## Use-cases
<!--This (optional) section specifies an (optional) introductory paragraph, and a level-3 (i.e. `###`) subsection for every use case it describes. Every such use-case SHOULD
- describe the situation/context of the use-case;
- show how to apply `NewTerm` to/in that situation;
- shows the relevance of having `NewTerm` for the use-case as opposed to not having it. -->
## Notes
<!--This (optional) section is the place to put anything for which there is no other good place to put it. -->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
id: ExistingScopeID-dictionary
title: Dictionary for <ExistingScopeID>
scopeid: <ExistingScopeID>
hoverText: "<Text that pops up when the user hovers over a reference to this Dictionary>"
---
<!--A dictionary is a glossary that contains all terms that are defined in a specific scope, as well as every meaning that is defined for each term.
Please fill in the placeholders in this file as follows:
- `<ExistingScopeID>`: identifier of the scope in which the term is defined;
- `<Existing Scope>`: human readable text that identifies the scope in which this item is defined;
-->
## Purpose
<!--State the purpose(s) that this dictionary aims to fulfill, in such a way that readers can easily determine whether or not it is useful for them to use it. This text should appear as the introduction of the (generated) dictionary.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
---
id: ExistingScopeID-glossary-NewGlossaryID
title: "Glossary: <NewGlossary> (Scope: <Existing Scope>)"
scopeid: <ExistingScopeID>
glossaryid: <NewGlossaryID>
hoverText: "<Text that pops up when the user hovers over a reference to this glossary>"
---
<!--A glossary is a list of terms with (short) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s).
Please fill in the placeholders in this file as follows:
- `<ExistingScopeID>`: identifier of the scope in which the term is defined;
- `<Existing Scope>`: human readable text that identifies the scope in which this item is defined;
- `<NewGlossaryID>`: identifier by which the glossary can be identified within <ExistingScopeID>;
-->
## Purpose
<!--State the purpose(s) that this glossary aims to fulfill, in such a way that readers can easily determine whether or not it is useful for them to use it.-->
## Sources
<!--This section specifies the sources from which the glossary entries (and their descriptions) are to be collected. All terms from all sources are included in the glossary. If that is too much, then you should revert to stating individual terms, patterns or concepts (see below).-->
### Terms
<!--Specify the term-files that are to be included in this glossary. If a term is defined in a scope as well as in a term-file, then both are included in the glossary (where the scope identifier is used to distinguish between them). -->
### Concepts
<!--Specify the concept-files that are to serve as a source for this glossary. If a term is defined in a scope, or as a term, or in a pattern as well as in a concept-file, the latter takes precedence.-->
### Patterns
<!--Specify the pattern-files that are to serve as a source for this glossary. If a term is defined in a scope or as a term as well as in a pattern-file, then both are included in the glossary (where the scope identifier is used to distinguish between them).-->
### Glossaries
<!--Specify the glossary-files all terms of which are to be included in this glossary.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
---
id: ExistingScopeID-pattern-NewPatternID
title: "Pattern: <New Pattern> (Scope: <Existing Scope>)"
scopeid: <ExistingScopeID>
patternid: <NewPatternID>
hoverText: "<Text that pops up when the user hovers over a reference to this pattern>"
---
<!-- A pattern captures/describes a set of concepts, relations between them, and rules or constraints that (instances) thereof comply with. As such, it is a concise and possibly formal description of a coherent set of ideas, a mental model if you will, that can be used to facilitate one's thinking about/with these concepts.
Please fill in the placeholders in this file as follows:
- `<ExistingScopeID>`: machine readable text that identifies the scope in which this pattern is defined;
- `<Existing Scope>`: human readable text that identifies the scope in which this pattern is defined;
- `<NewPatternID>`: machine readable text that identifies this pattern within <ExistingScopeID>;
- `<New Pattern>`: human readable text that identifies this pattern within <Existing Scope>;
-->
## Purpose
<!-- Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it. -->
## Introduction
<!-- Gently introduce the pattern, by referring to real-world situations and using colloquial terms, so that when someone has read the text, (s)he knows what it is about, and is ready to delve into the specifics of the pattern. -->
## Notations
<!-- This (optional) section specifies the notations that are used, or refers to such a specification. -->
## <!-- any number of other sections, as is fit for describing the pattern -->
<!-- text as appropriate for such a section -->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
id: NewScopeID-1-scope
title: "Scope: <New Scope>"
scopeid: <NewScopeID>
hoverText: "<Text that pops up when the user hovers over a reference to this item>"
---
<!--A scope is something within which concepts can be associated with terms, thereby creating a vocabulary that can be used to meaningfully express ideas, arguments, etc.
Please fill in the placeholders in this file as follows:
- `<NewScopeID>`: identifier of the scope being defined;
- `<New Scope>`: word or phrase that is used in the title of the scope definition document;
-->
## Governance
<!--This section identifies the organizational body (Jurisdiction) that governs the scope. Optionally, a reference to the governance framework/procedures may be made.-->
## Objectives/Issues
<!--State the purpose for having the scope in terms of objectives that are aimed for and/or issues that are to be addressed.-->
## Scope URI
<!--Optionally specify the URI by which this scope may be identified-->
## Inclusions
<!--This scope may include other scopes, which means that everything in that other scope is also considered part of this scope. In case of collisions, this scope MUST provide a means to resolve such conflicts without modifying anything in included scopes. For eSSIF-Lab, we include `essifLabTerminology`-->
## Notes
<!--Anything els that's worth mentioning.-->
## Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
---
id: NewTermID
title: "Term: <New Term> (Scope: <Existing Scope>)"
scopeid: <ExistingScopeID>
termid: <NewTermID>
conceptref: <ExistingConceptScopeID>:<ExistingTermID>
hoverText: "<Text that pops up when the user hovers over a reference to this term>"
---
<!--A Term is a word or phrase that is used in at least one scope (context and/or for specific purposes) to refer to some concept.
Please fill in the placeholders in this file as follows:
- `<ExistingScopeID>`: machine readable text that identifies the scope in which this term is defined;
- `<Existing Scope>`: human readable text that identifies the scope in which this term is defined;
- `<NewTermID>`: machine readable text that identifies this term within <ExistingScopeID>;
- `<New Term>`: human readable text that identifies this term within <Existing Scope>;
- `<ExistingConceptScopeID>`: identifier of the scope in which the concept, to which the new term will refer, is known;
- `<ExistingTermID>`: machine readable identifier that identifies a concept within <ExistingConceptScopeID>
-->
## Purpose
<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
## Notes
<!--Usually, the meaning of a term will not be _exactly_ the same as that of the concept to which it refers. Often, there are slight differences in meaning, or the term may emphasize specific characteristics of the concept, so as to accommodate specific needs of the scope in which it is defined. Please describe such deviations/emphasized characteristics in this section, and which needs that helps accommodate.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
---
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 markdown files and replaces a specific pattern with a React
component which supports a tooltip functionality (more information below)
2. Parses all markdown files and generates a glossary page with all the
pattern terms found in the `.md` files
## Replace all patterns with tooltip information
When writing documentation, you can 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.
After the successful run of the script, the output of this functionality will be
a React Component, which will render the `term_text` as a link, directing to
the term page (which will be generated from the `term_name` attribute), and
when the user *hovers* the `term_text` it will show a brief summary of the term.
### 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
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