# 4 Areas of Machine Readable Governance

## Summary
1. Who to trust
2. Rules
3. Workflows
4. Trust discovery

## Who to trust
List of schemas in use

List of trusted issuers, verifiers

A machine readable governance file is a great choice for trust because it can be 1) generated from dynamic data sources 2) cached and 3) available offline

Most generic level of governance

## Rules
Roles (permissions), prerequisites, requirements

Role: in order to do X, you need permission/role Y

Prerequisites: before you do X, you need to complete Z (ahead of time); e.g. you need a different credential first

Requirements: in order to do X, please have A, B, and C ready and take steps H, I, J during the process; e.g. you need your birth certificate and passport ready and you will need to verify your email and sign a document

A machine readable governance file is a great choice for rules because it directly ties the rules to the ecosystem they belong to (in addition to the three benefits from "who to trust")

More specific level of governance

## Workflows
Description of processes

Can be described in interaction documents which basically outline the states of a state machine and the transformations between states

Interaction documents start as suggestions but can be referred to in governance as standard procedures, thus making them required

A machine readable governance file is a good place to refer to interaction documents

Very (most?) specific level of governance

## Trust Discovery
Discover governance frameworks, issuers, verifiers, schemas, etc.

How to establish trust in governance

Trust registries should aggregate, share, and (perhaps) rate this information

Trust registries should NOT be the source of truth for the previous sections; each jurisdiction should have one source of truth that applies in their own governance file. The registry is an index and aids discovery.

Help to resolve specificity differences, mediate compromises?

## 5 W's and also How
Another useful way to look at governance is by thinking about the answers to these basic questions:
* What?
* list of schemas
* schema requirements
* credential definitions
* Who?
* list of issuers, verifiers
* roles
* Where?
* goes with who (endpoints, URLs, etc.)
* When?
* sequence
* state
* workflow
* Interaction Documents
* How?
* protocols
* Why?
* governance stamp of authority, proof of authority (how to prove authenticity...)
* legal basis
* documentation

## Sample
Our sample includes who to trust, but needs rules and workflows

{
  "@context": ["https://github.com/hyperledger/aries-rfcs/blob/master/0430-machine-readable-governance-frameworks/context.jsonld"],
  "name": "Health Governance",
  "version": "0.1",
  "description": "Issuance and verification of health credentials. Provides a source of truth for current schemas, issuers, and verifiers",
  "last_updated": "2021-06-10",
  "docs_uri": "need_to_create",
  "data_uri": "need_to_create",
  "schemas": ["test_id", "test_result", "trusted_traveler"],
  "roles": ["issuer", "verifier"],
  "define": [
    {
      "name": "Government_Organization",
      "id": "update_with_did",
      "describe": {
        "label": "Government",
        "sublabel": "Full Government Organization Name",
        "website": "issuinggovernmentsite.org",
        "email": "[e-mail]"
      }
    },
    {
      "name": "Lab_Issuer",
      "id": "update_with_did",
      "describe": {
        "label": "Lab Issuer",
        "sublabel": "Full Organization Name",
        "website": "issuinglabsite.com",
        "email": "[e-mail]"
      }
    },
    {
      "name": "Health_Verifier",
      "id": "update_with_did_please",
      "describe": {
        "label": "Health Verifier",
        "sublabel": "Verifying Org",
        "website": "verifyingorgsite.com",
        "email": "[e-mail]"
      }
    }
  ], 
  "rules": [
    {"when": {"name": "Government_Organization"}, "thus": "issuer"},
    {"when": {"name": "Lab_Issuer"}, "thus": "issuer"},
    {"when": {"name": "Government_Organization"}, "thus": "verifier"}
    {"when": {"name": "Health_Verifier"}, "thus": "verifier"}
  ]
}