This is the home page for the ToIP Governance Metamodel Specification. Please see the Governance Metamodel Companion Guide for a "user's guide" to this specification. The purpose of this ToIP specification is to provide an overall template for ToIP-compatible governance frameworks from which layer-specific templates are derived. Each layer-specific template MUST comply with this specification. They SHOULD add details such as:
- Layer-specific ToIP roles.
- Layer-specific ToIP processes in which actors in those roles are engaged.
- Layer-specific risks against which a risk assessment should be performed (see the Risk Assessment Worksheet Template).
- Layer-specific elements of a trust assurance framework to address those risks (see the Trust Assurance and Certification Controlled Document Template).
Notation and Keywords
All terms appearing in bold on this page are listed in either the ToIP Core Glossary (based on the ToIP Core terms wiki) or the ToIP Governance Glossary (based on the GSWG terms wiki.) For more information see the Terms Wiki page of the Concepts and Terminology WG.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The primary document is the "home page" for the governance framework (GF). It:
- MUST have a DID (decentralized identifier) that serves as an identifier of the entire GF.
- MUST have a unique DID URL (as defined in the W3C Decentralized Identifiers 1.0 specification) to identify each specific version of the primary document.
- MUST contain authoritative references to all other documents included in the GF, called controlled documents.
This section is a non-normative general introduction to the GF whose purpose is to orient first-time readers as to the overall context of the GF. It:
- SHOULD reference any external websites, white papers, or other helpful background materials.
- SHOULD reference the ToIP Foundation, the ToIP stack, and the specific version of the ToIP governance template upon which the GF is based (if any).
- MAY include an "Acknowledgements" section citing contributors to the GF.
Terminology and Notation
This section asserts the terminology conventions used in the GF. It:
- MUST explicitly specify the use of the ToIP Governance Requirements Glossary (see below).
- MUST reference the GF Glossary controlled document for all other terms (see the Controlled Documents section).
- MAY specify that terms specific to one controlled document are defined in that controlled document.
- MUST specify that all RFC 2119 keywords used with their RFC 2119 meanings are CAPITALIZED.
- SHOULD specify any other formatting, layout, or notation conventions used in the primary document and/or controlled documents.
ToIP Governance Requirements Glossary
In the context of a governance framework (GF), a requirement states a condition that an actor (human or machine) must meet in order to be in conformance. In ToIP-compliant GFs, all requirements MUST be expressed using RFC 2119 keywords.
A requirement expressed using one of the following RFC 2119 keywords: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT".
A requirement expressed using one of the following RFC 2119 keywords: "SHOULD", "SHOULD NOT", "RECOMMENDED".
A requirement expressed using one of the following RFC 2119 keywords: "MAY", "OPTIONAL".
A requirement expressed in a human language that can only be fulfilled by a human actor performing a set of processes and practices against which conformance can only be tested by an auditor of some kind. In a ToIP-compliant governance framework, human-auditable requirements are expressed as policies.
A requirement written in a machine-readable format such that conformance of a software actor implementing the requirement can be tested by an automated test suite or rules engine. In a ToIP-compliant governance framework, machine-readable requirements are expressed as rules in a rules-based language.
A human-auditable requirement that specifies some set of processes and practices that an actor must follow in order to be in conformance with the requirement.
A specified set of actions that an actor must take in order to be in conformance with a policy. A process may consist of a set of practices.
A specified activity that an actor must perform as part of a process.
A machine-testable requirement written in a machine-readable language that can be processed by a rules engine.
A document or set of documents containing any combination of human-auditable requirements and machine-testable requirements needed to produce interoperability amongst implementers. Specifications may be included in (as controlled documents) or referenced from a governance framework.
This section covers the policies governing languages and translations for the GF. It:
- MUST specify the official language or languages for the GF.
- SHOULD use an IETF BCP 47 language tag to identify each official language.
- SHOULD specify and provide links to all official translations of the GF.
- SHOULD specify the policies and/or rules governing the production of translations.
This section asserts the legal authority for governance of the GF.
- For the governing authority (or each interdependent governing authority), this section:
- MUST state the full legal identity including jurisdiction(s).
- MUST state the DID.
- SHOULD include the Legal Entity Identifier (LEI) of the governing authority as defined by the Global Legal Entity Foundation (GLEIF).
- MUST provide contact information for official communication with the governing authority.
- SHOULD provide contact information for official persons acting on behalf of the governing authority.
- For the GF itself, this section:
- SHOULD provide the URL for a publicly-accessible website dedicated to the GF ("GF website").
- The GF website SHOULD include:
- HTML versions of all documents in the GF.
- PDF versions of all documents in the GF.
- Highlighted links to the Governance Requirements controlled document(s) that specify how the governing authority itself is governed.
- If applicable, a primary trust mark displayed prominently on the home page and in the header of every other page.
This section is only REQUIRED if the administering authority for the GF is different from the governing authority. It:
- MUST state the full legal identity of the administering authority.
- SHOULD provide the Legal Entity Identifier (LEI) of the administering authority as defined by the Global Legal Entity Foundation (GLEIF).
- MUST provide contact information for official communication with the administering authority.
- SHOULD provide contact information for official contacts acting on behalf of the administering authority.
- MUST clearly define the role of the administering authority i.e., what administrative authority the governing authority delegates to the administering authority and what decisions and processes remain the responsibility of the governing authority.
This is a short, clear statement of the overall purpose ("mission") of the GF. It:
- SHOULD be as short and concise as possible—ideally one sentence, or at most one paragraph.
This is a statement of what is in and out of scope for the GF. It:
- SHOULD clearly state the primary governed roles in the trust community.
SHOULD state any other relevant stakeholders.
- SHOULD state the primary types of interactions, transactions, or processes in which the actors serving these roles will be engaged.
- SHOULD state what kind of artifacts will be governed.
- SHOULD, if applicable, clearly state what is out of scope.
This section states the high-level outcomes desired by the trust community through its adoption of the GF. It:
- SHOULD specify tangible, achievable results (e.g. SMART criteria and Fit-for-Purpose criteria).
- MUST only contain outcomes over which the GF has the authority and mechanisms to achieve within its scope.
- MUST be consistent with the principles of the GF (below).
This section states the principles by which all members of the trust community agree to abide. It:
- SHOULD serve as a guide to the development of policies, rules, and other requirements in the GF ("principles guide policies").
- SHOULD, if applicable, refer to previously existing principles (whether defined by ToIP or other sources).
- SHOULD be referenced (along with any other relevant parts of the GF) in any Legal Agreement so as to help clarify intent.
- MUST NOT include requirements (e.g., using capitalized RFC 2119 keywords) for which either human or machine conformance can be directly tested — those MUST be stated as policies or rules elsewhere in the GF.
This section contains requirements that apply to the GF as a whole and not just in the context of a particular controlled document. It:
- SHOULD include the requirements that:
- Generally apply to governance of the entire trust community.
- Apply to the structure of the GF (e.g., who is responsible for which controlled documents).
- Guide the development of more specific requirements within the controlled documents.
- SHOULD NOT include requirements that apply only within the context of a specific category addressed by one of the controlled documents.
- MUST include any responsible use policies that apply to infrastructure governed by the GF.
- MUST include any regulatory compliance policies that are not specified within particular controlled documents.
- SHOULD include a Code of Conduct (if not included in the legal documents) that applies to all trust community members.
This section contains the specific requirements governing revisions to the GF. It:
- MUST include requirements specifying:
- How any revisions to the GF will be developed, reviewed, and approved.
- How any new versions will be uniquely identified with a DID URL.
- SHOULD include at least one public review period for any publicly-available GF.
- SHOULD NOT include any other types of requirements that pertain to governance of the governing authorit(ies). Those should be defined in controlled documents in the Governance Requirements category.
This section applies to GFs that permit extension GFs (a common feature of some ecosystem GFs). It:
- MUST state whether the GF can be extended.
- MUST specify the requirements an extension GF must meet in order to be approved.
- MUST specify the process by which an extension GF can be approved.
- MUST define requirements for registration, activation, and deactivation of an approved extension GF.
- MUST define the requirements for notification of trust community members about activation or deactivation of an approved extension GF.
Schedule of Controlled Documents
If controlled documents are included as part of the GF, this section MUST contain an authoritative list of all controlled documents in the GF. It:
- MUST include authoritative references to all controlled documents in the GF.
- MUST identify the exact version of each controlled document with a unique, permanent DID or DID URL.
- SHOULD include a Web link to each controlled documents on the GF website.
- SHOULD include a brief description of the purpose and scope of each controlled document to make it easy for readers to navigate the GF.
Each controlled document covers a specific area of the GF. The following sections are categories of controlled documents where each category MAY contain more than one document. Most (but not all) categories are OPTIONAL.
This category provides a common basis for terminology. It:
- SHOULD be a single controlled document for each applicable language.
- SHOULD provide a common reference for all possibly ambiguous terms used throughout the GF.
- SHOULD reference the ToIP Core Glossary, other relevant ToIP glossary or GF-specific glossary for all relevant terms.
- SHOULD conform to standard requirements for a glossary, i.e., list all terms alphabetically for easy reference.
- MAY tag terms by category or usage.
This category includes an ISO 27005 (or compatible) risk assessment for managing risk. Controlled documents in this category:
- SHOULD identify key risks that MAY negatively affect the achievement of the GF's purpose and objectives within its scope.
- SHOULD include a risk assessment of each key risk that the GF is designed to address and mitigate.
- SHOULD assess which roles and processes specified in the GF are vulnerable to each risk and what impacts could result.
- SHOULD include a risk treatment plan specifying how identified risks are to be treated (e.g. mitigated, avoided, accepted or transferred).
Trust Assurance and Certification
This category specifies trust criteria for governed parties be held accountable against requirements of the GF. Controlled documents in this category:
- SHOULD include a trust assurance framework that defines a scheme in which governed parties assert compliance with the policies of the GF and the mechanisms of assurance over those assertions.
- SHOULD (if applicable) define the roles of auditors and auditor accreditors and the policies governing their actions.
- SHOULD (if applicable) define the roles of certifying parties and the policies governing their actions and relationships with the governing authority, auditors and auditor accreditors.
- SHOULD (if applicable) include requirements supporting the development, licensure, and usage of one or more trust marks.
These are the requirements for governing the GF as a whole. Controlled documents in this category:
- MUST specify governance requirements (e.g., Charter, Bylaws, Operating Rules, and so on) for:
- The governing authority (or all interdependent governing authorities).
- The administering authority, if applicable.
- SHOULD address any policies required for antitrust, intellectual property rights (IPR), confidentiality, responsible use, or other requirements for regulatory compliance that apply to the trust community members.
- SHOULD include any requirements governing enforcement of the GF and how dispute resolution will be handled.
These are the requirements governing the business model(s) and business rules to be followed by the trust community. Controlled documents in this category:
- SHOULD clearly explain any exchange(s) of value between trust community members governed by the GF.
- SHOULD define the policies and/or rules governing how and when these exchanges of value take place.
- SHOULD define the requirements for the use of any decision support systems.
- SHOULD define how all trust community members will be held accountable for their actions in these exchanges.
- SHOULD define how the governing authority, administering authority, and the GF are sustainable under these requirements.
These are the requirements governing technical interoperability. Controlled documents in this category:
- MUST specify how trust community members will interoperate technically using the ToIP technology stack by reference to any relevant ToIP specifications and recommendations.
- SHOULD include any additional specifications and/or specification profiles that are specific to the technical interoperability within this trust community.
- SHOULD include references one or more glossaries (see Glossary section) as needed.
- SHOULD reference any test suites or other testing requirements.
Information Trust Requirements
These are the requirements in the five categories of trust service criteria defined by the American Institute of Certified Public Accountants (AICPA) Assurance Services Executive Committee (ASEC). These can be addressed by implementing internal controls as defined by the Committee on the Sponsoring Organizations of the Treadway Commission (COSO) Guidance on Internal Control. Controlled documents in this category:
- MUST specify the baseline requirements for governed parties with regard to:
- Information security
- Information availability
- Information processing integrity
- Information confidentiality
- Information privacy
- SHOULD specify the relevant information trust policies by reference to:
- ToIP specifications and recommendations.
- Other regulatory or industry standards.
- GF-specific policies.
- GF-compliant decision support systems.
- Trust community member-specific policies.
Inclusion, Equitability, and Accessibility Requirements
These are the requirements governing how the GF enables fair and equal access to all. Controlled documents in this category:
- MUST specify how trust community members will enable and promote inclusion, equitability, and accessibility by reference to:
- ToIP specifications and recommendations.
- Other regulatory or industry standards.
- GF-specific policies.
- GF-compliant decision support systems.
- Trust community member-specific policies.
- SHOULD specifically address how the GF is designed to help bridge (or eliminate) the digital divide.
This category includes any legal agreements specified in the GF. Controlled documents in this category:
- MUST include all specified legal agreements between trust community members.
- SHOULD reference the GF glossary document(s) for all terms not defined internally to the legal agreement.
- MUST clearly state the governed parties to whom these legal agreements apply.
- MUST define or reference all relevant accountability and enforcement mechanisms.
- SHOULD reference any other relevant requirements in the balance of the GF.
This looks great! One thing I'm not clear about - is the idea that the Metamodel template will be used to develop layer-specific GFs, but there will not be an overall GF, i.e. for the entire stack?
The per-layer governance framework model is an aspect that has origins in the 2 column illustration of the ToIP stack. This approach enables the specific requirements and purpose of each layer to be well scoped within a GF and reflect those. For the entire stack perhaps a set of higher order principles would be more appropriate.
A specific real example would be how the Sovrin Foundation is reviewing the existing v2 Governance Framework to address scope statements arising from L1/Utility and L4/Ecosystem via the Sovrin Utility Governance Framework and Sovrin Ecosystem Governance Framework.
We should perform an edit pass to clearly state what components are MUST and what are SHOULD or others not required
Do we want to include a reference to the services offered / published to upper layers and consumed / used from lower levels? That is, something like the old ISO/OSI 7 layer model approach where each layer defined what it did, but also how it connected to the other layers.
Would it be possible for you to provide or even create a trivial example service pattern?
We discussed this in Slack but I'm cc'ing the replies here for the wiki record. I gave this reply:
I definitely understand what you are saying about architectural layering dependencies when it comes to the ToIP Technology Stack. But I don’t see quite how that applies to the ToIP Governance Stack. In other words, to take an example, the purpose of a GF for a ToIP Layer 1 public utility is to define the policies by which higher level GAs and actors (such as Layer 3 issuers) can decide if they will or will not trust the public utility. So the entire GF is “published for the layer(s) above”.
The same is true of GFs at Layers 2 and 3. They exist so the GAs and actors at higher layers can decide if, when, and how much that GF can be trusted in certain interactions. And a ToIP Layer 4 ecosystem governance framework exists so that other ecosystem GAs and GFs can decide how much to trust that ecosystem.
Said in slack already but for the record: "we need a Responsible Use Policy similar to Inclusion… to promote responsibility and to set boundaries. Should be a MUST."
Thanks, Wenjing, that was important enough that we added it to the Core Policies section of the Master Document.
I'm liking the changes. Primary wins the day for inclusivity.
On Glossary -
SHOULD list all terms alphabetically (by language) for easy reference.[Rieks: OED (lexico), cambridge, wikipedia, etc, say that glossary IS already an alphabetically sorted list of words.
Rieks makes an excellent point but I see validity in stating so herein. I would leave in the point but change the word SHOULD to MUST.
As a more general point, I believe that the "SHOULD"s should be "MUST"s and the "MAY"s should be "SHOULD"s. MoSCoW Rules, where the "Would be nice if" = "MAY" here? I haven't applied this logic across the Metamodel but it looks like it could do with a wizz through to validate the MUST/SHOULD/MAY assignations. All may be semantics, (for is that not what a Metamodel is), and possibly pedantry but I'm getting in on behalf of the community before those outside throw at it.
I just did a major edit that touched all parts of the document to make the following changes:
Please do review and comment as to how well these edits do or do not work.
Thank you for clarification! I've left one comment in the Definition section regarding this phrase: "by an audit of people, processes, and procedures."
Victor, thanks much, see my reply to your comment. Scott Perry may want to weigh in on this.
Scott Perry and I made a few minor updates:
Based on feedback from the development of the GHP Ecosystem Governance Framework in the Interoperability Working Group for Good Health Pass, I moved all requirements to provide identification and contact information for the Governance Authorit(ies) (and Governing Entity if different) to a single section of the Primary Document immediately after the Introduction.
Consolidated the Requirements Glossary into a new Terminology section of the Primary Document immediately following the Introduction. This is the convention now being followed by most specifications and similar documents.
Removed "Rules Engines" as they are part of the "Decision Support Systems" from Information Trust Requirements, Business Requirements, and Inclusion, Equitability, and Accessibility Requirements.
Substituted "Standard" term with "Layer specific" term for describing additional Roles, Processes, Risks and Trust Assurance elements relevant for each layer of the stack.
Triggered by the recent walkthrough of this metamodel, the requirement in the "Requirements Glossary" of "Machine-Testable requirements" and "Human Auditable requirements" suggested the need for both machine and human-readable versions of all requirements (specifications). If Governance (and consent as an extension of general governance to individuals/(other actors) about their data) is to be usable and verifiable, it needs to be traceable from legislation through to detailed human & machine-readable (if not executable) specifications. The companion to this would be both human & machine-readable output of logging of actions on data. Without a companion machine-readable specification for generating (not restricted to) data use and manipulation-related logging (particularly for compliance), governance cannot be verifiable via machine (only) validation/testing,
Having said all that, I've not thought through my comments impact the metamodel vs. other aspects of governance in general.
Near the top of the document, it says: "All terms appearing in First Letter Caps on this page MUST be added to the ToIP Governance Glossary as specified by the Concepts and Terminology WG." I changed 'Glossary' to read 'term wiki'. Here's why.
To be clear: CTWG does not specify any terms, terminologies, glossaries etc. other than for its own purposes. However, it does specify the process that TOIP WGs and/or TFs CAN (later perhaps SHOULD, then perhaps MUST) use in order to define their own terminology (i.e. sets of terms they need to do their particular jobs).
It is the intention of CTWG to provide a means by which each WGs/TFs can generate the glossary that they need for their particular work. The required tools for this are being looked at. In the mean time, CTWG has come up with the idea of term wikis as a means by which such groups can define their terms. While some people refer to this as a glossary, that's explicitly not what it is, for one because such a glossary would be expected to also include terms defined by other groups.
I added the word Specification to the title and intro section. I added the intro of the companion guide to the intro section and changed the bullets in the beginning to reflect current working documents.
We are deprecating the terms "ToIP Standard Specification (TSS)" and "ToIP Interoperability Profile (TIP)" in favor of just referring to ToIP Specifications and ToIP Recommendations, so I made those replacements.
Wait! When did TIP get deprecated as a term? This would need a scrub through instances where it occurs in this wiki.
I should have clarified that deprecating the term is still under discussion in the Technical Stack WG. But as we try to finalize the ToIP Governance Metamodel Specification, I want to avoid the risk that the term will be deprecated by not using it it here. And there is an easy solution: since a TIP is a type of ToIP Recommendation, it is completely safe for us to simply refer to compliance with ToIP Recommendations. Make sense?
Way back when the TIP approach was positioned and discussed as a way for additional/alternative implementations to demonstrate equivalence (I am hesitant to use 'compatibility') with an existing model (primarily the Indy/Aries one). Would framing this as a recommendation makes the criteria for interoperability a bit more relaxed one?
I am making a series of small enhancements/wording adjustments to the spec as I edit the ToIP Governance Metamodel Companion Guide. I will note any significant change here in the comments.
The one addition I just made to the metamodel is to add a section on Languages and Translations. We neglected to include this topic which is obviously needed when a GF needs to be published in more than one language (such as English and French as is required in Quebec, Canada).
Changed the title of the "Languages and Translations" section to "Localizations" per the feedback in the 2021-11-18 GSWG meeting.
The last few revisions to this page made the following changes:
Minor edit changes before GSWG Comment Period
Suggest changing the header of Principles to "Guiding Principles" for greater clarity.