Page tree
Skip to end of metadata
Go to start of metadata

This page represents the proposed structure of the ToIP Governance Metamodel. The purpose of the metamodel is to provide an overall template for ToIP-compatible governance frameworks from which the GSWG will then develop layer-specific templates. Each layer-specific template will be an instance of the metamodel that adds details such as:

The balance of this page defines the proposed metamodel and the requirements for each component. In these requirements, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" are to be interpreted as defined in RFC 2119.

All terms appearing in First Letter Caps on this page MUST be added to the ToIP Glossary tagged for inclusion in the ToIP Governance Glossary. (Note: the Concepts and Terminology WG has been briefed on this dependency.) The following terms have specific definitions used in this document:


  • Requirements include any combination of Policies, Rules, and Specifications. Unless otherwise stated, all Requirements MUST be expressed as defined in RFC 2119
  • Machine-Testable Requirements are Requirements with which compliance can be verified using an automated test suite and appropriate scripting or testing software.
  • Human-Auditable Requirements are Requirements with which compliance can only be verified by an audit of people, processes, and procedures.
  • Policies are Human-Readable Requirements. For Policies, the full range of RFC 2119 keywords apply, i.e., "SHOULD", "MAY", and "RECOMMENDED" all have weight from an auditing perspective. An implementer MUST explain why a SHOULD or RECOMMENDED requirement was not implemented and SHOULD explain why a MAY requirement was implemented.
  • Rules are Machine-Readable Requirements that can be processed by a Rules Engine. They are expressed in a structured rules language as specified by the GF.
  • Specifications are documents containing any combination of Machine-Testable Requirements and Human-Auditable Requirements needed to produce technical interoperability.

Primary Document

The Primary Document is the "home page" for the governance framework (GF). It:

  1. MUST have a DID (Decentralized Identifier) that serves as an identifier of the entire GF.
  2. MUST have a unique DID URL (defined in the DID spec) to identify each specific version of the Primary Document.
  3. MUST contain authoritative references to all other documents included in the GF, called the Controlled Documents.
  4. MUST include Policies in the Revisions section stating how the Controlled Documents are governed by the Governance Authority.


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:

  1. SHOULD have a reference to the ToIP Foundation, the ToIP Stack, and the specific version of the ToIP Governance Template from which it was derived.
  2. MAY include an Acknowledgements section to acknowledge the contributors to the GF.


This is a short, clear statement of the overall purpose (mission) of the GF. It:

  1. SHOULD be as short and concise as possible—ideally one sentence, or only a few sentences.


This is a statement of what is in and out of scope of the GF. It:

  1. SHOULD clearly state the primary Governed Actors in the Trust Community.
  2. SHOULD state any other relevant stakeholders.

  3. SHOULD state the primary types of interactions or transactions these Governed Actors will be engaging in. 
  4. SHOULD, if applicable, clearly state who and what are out of scope.


This states the high-level outcomes desired by the Trust Community through its adoption of the Governance Framework. It:

  1. SHOULD specify tangible, achievable results (e.g. SMART criteria and Fit-for-purpose criteria).
  2. SHOULD specify the intended overall outcomes to be produced by conformance with the Requirements in the GF.
  3. MUST only contain outcomes over which the GF has the authority and mechanisms to achieve within its Scope.
  4. MUST be consistent with its Principles.


This section states the Principles by which all members of the Trust Community have agreed to abide. It:

  1. SHOULD serve as a guide to the development of any Requirements based on each Principle ("Principles guide Policies").
  2. SHOULD refer to existing Principles—whether defined by other ToIP GFs or by other sources—whenever possible.
  3. SHOULD be referenced (along with any other relevant parts of the GF) in any Legal Agreement between Members and the Governance Authority.
  4. MUST NOT include requirements using RFC 2119 terms for which either human or machine conformance can be directly tested — those should be stated as Requirements elsewhere in the GF.

General Requirements

This section contains Requirements that apply to the GF as a whole and not just in the context of a particular Controlled Document. It:

  1. SHOULD include the Policies that:
    1. Apply generally to governance of the entire Trust Community;
    2. Apply to the structure of the GF, e.g., what Controlled Documents must be specified by whom and applied to whom.
    3. Guide the development of more specific Policies within the Controlled Documents.
  2. SHOULD NOT include Policies that apply only within the context of a specific category addressed by one of the Controlled Documents.
  3. MUST include Responsible Use Policies that apply generally to infrastructure governed by the GF.
  4. MUST include any Regulatory Compliance Policies that are not specified within particular Controlled Documents.


This section contains the specific Policies governing revisions to the GF. It does not include Governance Policies for the Governance Authority or interdependent Governance Authorities (those are defined in Controlled Documents in the Governance category). It:

  1. MUST state the full legal identity and contact information for the primary Governance Authority or interdependent Governance Authorities.
  2. MUST include Policies specifying how any revisions to the GF are identified, developed, reviewed, and approved.
  3. SHOULD include at least one public review period for any GF that will be available to the public.


This section applies to GFs that permit extensions via the incorporation of other GFs (a common feature especially of some ecosystem GFs). It:

  1. MUST state whether the GF can be extended.
  2. MUST specify the requirements an Extension Governance Framework must meet in order to be approved.
  3. MUST specify the process for an Extension Governance Framework to be approved.
  4. MUST define an authoritative mechanism for registration and activation of an approved Extension Governance Framework.
  5. MUST define the requirements for notification of the Trust Community about an approved Extension Governance Framework.

Schedule of Controlled Documents 

This is a listing of all Controlled Documents in the GF. It:

  1. MUST include authoritative references to all Controlled Documents in the GF.
  2. MUST identify the exact version of each Controlled Document with a unique, permanent DID or DID URL.
  3. SHOULD include a Web link to each Controlled Document in the Web version of the GF.
  4. SHOULD include a brief description of the purpose and scope of each Controlled Document to make it easy for readers to navigate the GF.

Controlled Documents

Each Controlled Document covers a specific area of the GF. The following are categories of Controlled Documents where each category MAY include zero or more Controlled Documents.


The Glossary provides a common basis for terminology. It:

  1. SHOULD be a single Controlled Document (even if it is organized by categories or other heuristics).
  2. SHOULD provide a common reference for all possibly ambiguous terms used throughout the GF.
  3. SHOULD reference the ToIP Glossary—or tagged subset(s) of the ToIP Glossary—for all terms defined there.
  4. SHOULD conform to standard requirements for a glossary, i.e., list all terms alphabetically (by language) for easy reference.
  5. MAY tag terms by category or usage.
  6. MAY specify that terms specific to one Controlled Document are defined in that Controlled Document.

Risk Assessment

This category includes links to 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 process output that provides an assessment of each key risk that the GF is designed to address and mitigate.
  • SHOULD assess which Roles and Processes are vulnerable to each risk and how they are affected.
  • MAY include a Risk Treatment Plan (RTP) for how identified risks are treated (e.g. mitigated, avoided, accepted or transferred); however, all risks that are to be mitigated by directives in the GF SHOULD be identified.

Trust Assurance and Certification

This category specifies Policies for Governed Actors be held accountable against Requirements of the GF. Controlled Documents in this category:

  1. SHOULD include a Trust Assurance Framework document that defines a scheme in which Roles assert compliance with the Policies of the GF and the mechanisms of assurance over those assertions.
  2. SHOULD (if applicable) define the roles of Auditors and Auditor Accreditors and the directives governing their actions.
  3. SHOULD (if applicable) define the roles of Certification Authorities and the Policies governing their actions and relationships with the Governance Authority, Auditors, and Auditor Accreditors.
  4. SHOULD (if applicable) include Policies supporting the development, licensure, and usage of one or more Trust Marks.

Governance Requirements

These are the Requirements for governing the GF as a whole. Controlled Documents in this category:

  1. MUST specify the primary Governance Authority or all interdependent Governance Authorities (if any).
  2. MUST include Controlled Documents that specify Governance Policies for the primary Governance Authority or all interdependent Governance Authorities (e.g., Charter, Bylaws, Operating Rules, etc.)
  3. SHOULD address any antitrust Policies, intellectual property rights (IPR) Policies, confidentiality Policies, or other regulatory compliance policies under which the Trust Community Members agree to operate.
  4. SHOULD include any Policies governing enforcement of the GF and how Dispute Resolution will be handled.

Business Requirements

These are the Polices and/or Rules governing the business model(s) and business rules to be followed by the Trust Community. Controlled Documents in this category:

  1. SHOULD clearly explain the exchange(s) of value within the Trust Community for which the GF is designed.
  2. SHOULD define the Policies and/or Rules governing how and when these exchanges of value take place.
  3. SHOULD define the Requirements for the use of any Rules Engines.
  4. SHOULD define how all Trust Community Members will be accountable for their actions in these exchanges.
  5. SHOULD define how the Governance Authority and the GF are sustainable under these Rules.

Technical Requirements

These are the Requirements governing technical interoperability. Controlled Documents in this category:

  1. MUST specify how Members of the Trust Community will interoperate technically using the ToIP Technology Stack by reference to ToIP Standard Specifications (TSS).
  2. SHOULD (if necessary) reference one or more specific ToIP Interoperability Profiles (TIPs).
  3. SHOULD specify any Specifications that are specific to this Trust Community.

Information Trust Requirements

These are the Requirements governing information security, privacy, availability, confidentiality and processing integrity as these terms are defined by the Committee on the Sponsoring Organizations of the Treadway Commission - (COSO) Internal Control - Integrated FrameworkControlled Documents in this category:

  1. MUST specify how Members of the Trust Community will ensure the following categories of Information Trust:
    1. Information security
    2. Information privacy
    3. Information availability
    4. Information confidentiality
    5. Information processing integrity
  2. SHOULD specify the relevant Information Trust Policies by reference to:
    1. ToIP Standard Specifications (TSS).
    2. Other regulatory or industry standards.
    3. GF-specific Policies.
    4. Trust Community Member-specific Policies.
    5. GF-compliant Rules Engines

Inclusion, Equitability, and Accessibility Requirements

These are the Policies governing how the GF enables fair and equal access to all. Controlled Documents in this category:

  1. MUST specify how Members of the Trust Community will enable and promote inclusion, equitability, and accessibility by reference to:
    1. ToIP Standard Specifications (TSS).
    2. Other regulatory or industry standards/guidelines.
    3. GF-specific Policies.
    4. Member-specific Policies.
    5. GF-compliant Rules Engines
  2. SHOULD specifically address how the GF is designed to help bridge (or eliminate) the digital divide.

Legal Agreements

This category includes any legal agreements or contracts included in the GF. Controlled Documents in this category:

  1. MUST include all legal agreements or contracts between Members and/or the Governance Authority.
  2. SHOULD reference the Glossary document for all terms not defined within.
  3. MUST clearly state the Governed Actors to whom these legal agreements apply.
  4. MUST define or reference all relevant accountability and enforcement mechanisms.
  5. SHOULD reference any other relevant Requirements in the balance of the GF.

  • No labels


  1. 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?

    1. 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.

  2. We should perform an edit pass to clearly state what components are MUST and what are SHOULD or others not required

  3. 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.

    1. Would it be possible for you to provide or even create a trivial example service pattern?

    2. 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.

  4. 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."

    1. Thanks, Wenjing, that was important enough that we added it to the Core Policies section of the Master Document.

  5. 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)cambridgewikipedia, 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.

  6. I just did a major edit that touched all parts of the document to make the following changes:

    1. Because we need to introduce "Rules" and "Rules Engines" as formal terms (learnings from the Good Health Pass WG), we needed to stop using that term in the general way we had before. Scott Perry proposed to fix that to switch from the term "Policies" to "Directives". However, besides issues with the term "Directives" (the EU and GDPR uses that term in a very different way that could be quite confusing), it doesn't give us the full vocabulary we need to distinguish between different types of requirements (machine-readable, human-auditable, or both). It would also move us away from the RFC 2119 terminology that has served us so well (and is so widely adopted and understood). So I added a set of definitions at the start of the document to fix those problems.
    2. I then did a top-to-bottom edit of the document to apply this new vocabulary consistently everywhere, using "Policy" when we mean human-auditable, "Rules" where we mean machine-readable, "Specification" where we mean either for technical interop, and "Requirements" where we mean either for both technical and governance interop.
    3. I marked in red text all the places where Scott had added new text around Rules and Rules Engines.
    4. Lastly, I removed the "New" markers that sankarshanhad applied before to the Objectives section and applied it to the definitions I added at the top of the doc.

    Please do review and comment as to how well these edits do or do not work.

  7. Thank you for clarification! I've left one comment in the Definition section regarding this phrase: "by an audit of people, processes, and procedures."

    1. Victor, thanks much, see my reply to your comment. Scott Perry may want to weigh in on this.