§ Trust Establishment 1.0.0

Specification Status: Working Group Draft

Latest Draft: identity.foundation/trust-establishment

Stable Draft: v1.0.0 identity.foundation/trust-establishment/spec/v1

Editors:
Gabe Cohen (Block)
Daniel Buchner (Block)
Mike Ebert (Indicio)
Sam Curren (Indicio)
Contributors:
Juan Caballero (Centre Consortium)
Jen Schreiber (Workday)
Participate:
GitHub repo
File a bug
Commit history

§ Abstract

Supporting trust decisions in decentralized identity architectures, particularly open-world architectures, is a problem that many have tried to solve. This specification aims to describe a practical, interoperable building block for supporting multiple different kinds of trust-decision Trust Establishment solutions. We define here a lightweight trust document: a means by which a Party communicates their assertions for a Topic about a set of Parties.

Not all potential usage will be covered in this specification. This specification describes only the data model of trust documents and is not opinionated on document integrity, format, publication, or discovery. Because of this, the specification alone cannot ensure interoperability and is recommended for use within one or more multi-layered Interoperability Profile(s) which specify those implementation details.

§ Status of This Document

Trust Establishment is a Working Group Draft specification under development within the Decentralized Identity Foundation (DIF). It incorporates requirements and learning from related work of many active industry players into a shared specification that meets the collective needs of the community.

This specification is regularly updated to reflect relevant changes, and we encourage active engagement on GitHub and other mediums (e.g. DIF Slack).

§ Terminology

Claim
An assertion made about a Subject. Used as an umbrella term for Credential, Assertion, Attestation, etc.
Verifiable Credential
Refers to the W3C specification of the Verifiable Credentials Data Model.
Topic
A Schema-defined subject that gives purpose to a trust document. A topic can be anything: from the tangibly measurable (e.g. success rate of a business process) to the intangible (e.g. how one party feels about another).
Trust Establishment
The process by which a Party makes trust statements about a given Party for a given Topic using Trust Establishment Documents.
Identified Parties
Entities that establish their identity by means of a Decentralized Identifier. Parties are commonly referred to as Issuers, Holders, and Verifiers.
Trust Host
Entities that are responsible for hosting and communicating Trust Establishment Documents.
Issuer
Issuers are entities that issue Claims to Holders, and may be represented as an Identified Party inside of a Trust Establishment Document.
Holder
Holders are entities that submit Claims to Verifiers which contain Parties that may be identified in a Trust Establishment Document to satisfy a Presentation interaction.
Verifier
Verifiers are entities that define what Parties they accept a Credential from in order to proceed with an interaction.
Presentation
Presentations are a type of verifiable interaction in which one Party submits a Claim or set of Claims to a Verifier.
Decentralized Identifier
A W3C specification describing an identifier that enables verifiable, decentralized digital identity.
Verifiable Interaction
An interaction (e.g. request a claim, present a claim, establish trust) which happens between Parties using Decentralized Identifiers via [DID-CORE].
Schema
A schema is a vocabulary for a Claim. Commonly used schema formats include JSON Schema or JSON Linked Data as surfaced through schema.org.
Credential Type
A Verifiable Credential always has a type property, referencing one or more URIs to anchor semantic meaning and classification for the data contained in the credential.

§ Structure of this Document

This document has three primary sections: In the first, we define the data models for Topics and Trust Establishment Documents. In the second, we give some examples of some Trust Establishment Documents in different verifiable formats. In the third, we offer some light guidance on possible usages.

Examples in this document use the Verifiable Credentials Data Model [VC-DATA-MODEL] and the [DID-CORE] formats for illustrative purposes only; this specification is intended to support any JSON-serializable Claim format but interoperability across proof mechanisms, claim formats, etc. is out-of-scope.

§ Data Models

Trust Establishment Documents are objects that articulate information a Party publishes in order to share assertions about a set of DID-identified entities. Issuers, Verifiers, and Holders may find utility in understanding a Party's assertions in making decisions in decentralized web interactions.

§ Properties

EXAMPLE
{
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "author": "did:example:alice",
  "created": "2022-04-20T04:20:00Z",
  "version": "0.0.3",
  "entries": {
    "https://example.com/trusted-rice-supplier.schema.json": {
      "did:example:bob": {
        "on_time_percentage": 92,
        "goods": ["basmati", "jasmine", "sushi"]
      },
      "did:example:carol": {
        "on_time_percentage": 74,
        "goods": ["long-grain", "short-grain", "extra glutinous"]
      }
    },
    "https://example.com/other.schema.json":{
      "did:example:bob": {
        "foo": "bar"
      },
      "did:example:carol": {
        "foo": "baz"
      }
    }
  }
}

§ Trust Topic

A topic MUST be encoded as a JSON Schema document that can be applied to any number of Parties identified in the entries property of a Trust Establishment Document.

Example JSON Object

EXAMPLE
{
  "$id": "https://example.com/trusted-supplier.schema.json",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "Supplier Trust",
  "type": "object",
  "properties": {
    "on_time_percentage": {
      "type": "number",
      "min": 0,
      "max": 100
    },
    "goods": {
      "type": "array",
      "items": {
        "format": "string"
      }
    }
  },
  "additionalProperties": false
}

§ Verifiable Trust Document Examples

Trust Establishment Documents may fit into any number of embed targets – verifiable wrappers or embedded proofing formats - to enable data integrity. This specification takes no position on which means are suitable to provide integrity of Trust Establishment Documents or Topics; the examples it provides should be taken as illustrative rather than normative in regards to those decisions at higher layers.

WARNING

This specification details only a data model rather than a complete syntax and is therefore insufficient for coordinating interoperability across implementations.

Interoperability is only possible between two implementations, each of which conform to one or more Interoperability Profile(s) which fully specify the implementation details of document integrity, publication, and discovery supported for the other to target. Conformance to this low-level specification does not guarantee compatibility across implementations; instead, these higher-level Interoperability Profile(s) must be targeted.

§ Trust Document as a Verifiable Credential proofed by Data Integrity

EXAMPLE
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "TrustEstablishment", "TrustedSuppliers"],
  "issuer": "did:example:alice",
  "issuanceDate": "2010-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "trustEstablishment": { 
      "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
      "author": "did:example:alice",
      "created": "2010-01-01T19:23:24Z",
      "version": "0.0.3",
      "entries": {
        "https://example.com/trusted-supplier.schema.json": {
          "did:example:bob": {
            "on_time_percentage": 92,
            "goods": ["basmati", "jasmine", "sushi"]
          },
          "did:example:carol": {
            "on_time_percentage": 74,
            "goods": ["long-grain", "short-grain", "extra glutinous"]
          }
        }
      }
    }
  },
  "proof": {
  	"type": "Ed25519Signature2020",
    "created": "2021-11-13T18:19:39Z",
    "verificationMethod": "did:example:alice#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz"
  }
}

§ Trust Document as a JSON Web Token (JWT)-Encoded Verifiable Credential

EXAMPLE
{
    "alg": "EdDSA",
    "typ": "JWT",
    "kid": "did:alice#keys-1"
}
EXAMPLE
{
  "sub": "did:example:alice",
  "jti": "http://example.com/credentials/3732",
  "iss": "did:alice#keys-1",
  "nbf": 1541493724,
  "iat": 1541493724,
  "exp": 1573029723,
  "nonce": "660!6345FSer",
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": [
      "VerifiableCredential",
      "TrustEstablishment",
      "TrustedSuppliers"
    ],
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "trustEstablishment": {
        "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
        "author": "did:example:alice",
        "created": "2010-01-01T19:23:24Z",
        "version": "0.0.3",
        "entries": {
          "https://example.com/trusted-supplier.schema.json": {
            "did:example:bob": {
              "on_time_percentage": 92,
              "goods": [
                "basmati",
                "jasmine",
                "sushi"
              ]
            },
            "did:example:carol": {
              "on_time_percentage": 74,
              "goods": [
                "long-grain",
                "short-grain",
                "extra glutinous"
            }
          }
        }
      }
    }
  }
}
NOTE

The third component of the JWT, the signature in JWS form, is not shown, as the example is given with payload properties given in OIDC-compatible, rather than VC-conformant keys and values; this is sometimes called the “intermediate” or “unwrapped” form of a VC-JWT. In the process of proofing, it would be formatted as a classic JWT, with header object, payload object, and JWS proof object base64-encoded and concatenated with "."s.

§ Publication & Discovery

While specific recommendations for how to host, publish, and discover Trust Establishment documents is out of scope of this specification, we can raise a number of points for consideration for its users.

The publication of the JSON-based documents defined in this specification is a basic activity required for these expressions of trust and sentiment to be discovered and digested by counterparties, witnesses, and/or aggregators. There are a number of ways to do this, but they should consider the following core capabilities:

  1. Enable Trust Establishment documents to be located via crawling a known set of endpoints or some other common routing mechanisms; DIDs with Service Endpoints offer one abstraction for layering these and integrating them into discovery processes.
  2. Enable querying for all or some subset of Trust Establishment documents from a target entity via common DID-based data query/interaction protocols.

There may be different motivations for interacting with Trust Establishment documents. Across those motivations there are a common set of questions one may ask themselves before publishing, including:

§ Appendix

§ JSON Schema

The Trust Establishment specification adopts and defines the following JSON Schema data format and processing variant, which implementers MUST support for evaluation of the portions of the specification that call for JSON Schema validation: https://json-schema.org/draft/2020-12/json-schema-core.html

EXAMPLE
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Trust Establishment",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "author": {
      "type": "string"
    },
    "created": {
      "type": "string",
      "format": "date-time"
    },
    "validFrom": {
      "type": "string",
      "format": "date-time"
    },
    "validUntil": {
      "type": "string",
      "format": "date-time"
    },
    "version": {
      "type": "integer"
    },
    "entries": {
      "type": "object",
      "patternProperties": {
        "\\w+:(\/?\/?)[^\\s]+": {
          "type": "object"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "author",
    "created",
    "validFrom",
    "version",
    "entries"
  ],
  "additionalProperties": false
}

§ Examples

Example 1 - Sentiment Declaration

Sentiment Declaration is a usage of the Trust Establishment data model that provides a means by which an Entity communicates their sentiment (what they may feel or think) for a Topic about a set of Parties. Sentiment Declaration is intended to be informational, and the prescription of any resulting actions taken based on the contents of the document are out of scope of this specification.

As an example, we think of “My Faves”. The year is 2007 and your pink-colored mobile carrier announces a program to let you make unlimited calls and texts to five contacts of your choosing: your faves. Using the Trust Establishment specification, you create a JSON Schema Topic that supports you enumerating your faves.

EXAMPLE
{
  "$id": "https://example.com/my-faves.schema.json",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "My Faves",
  "type": "object",
  "properties": {
    "faves": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
      },
      "minItems": 1,
      "maxItems": 5
    }
  },
  "required": ["faves"],
  "additionalProperties": false
}

Next, you take the “My Faves” schema, and put it in a Trust Establishment document, which you can share with your mobile carrier, or post it on social media if you’re feeling bold.

EXAMPLE
{
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "author": "did:example:alice",
  "created": "2010-01-01T19:23:24Z",
  "validFrom": "2010-01-01T19:23:24Z",
  "version": "0.0.1",
  "entries": {
    "https://example.com/my-faves.schema.json": {
      "did:phone:1234567890": {
        "faves": ["1-888-867-5309", "1-603-413-4124", "1-605-475-6960", "1-605-475-6968", "911"]
      }
    }
  }
}

You may imagine your carrier similarly using the “My Faves” schema to build a graph of the five favs for all its participating customers, each a separate entity within the Trust Establishment Document.

Example 2 – Trusted Issuers

A common usage of Trust Establishment Documents is by a Verifier wishing to provide information on which Credentials they accept from which Issuers. Using Verifiable Credentials we know that a given Credential may have a single schema, but may also reference multiple schemas or type definitions for the same Credential. Using a “Trusted Issuers for Credential” topic, we can fulfill this use case.

EXAMPLE
{
  "$id": "https://example.com/trusted-issuers-for-credential.schema.json",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "Trusted Issuers for Credential",
  "type": "object",
  "properties": {
    "credential": {
      "type": "array",
      "items": {
        "type": "string",
      },
      "minItems": 1
    }
  },
  "required": ["credential"],
  "additionalProperties": false
}

Next, you take the “Trusted Issuers For Credential” schema, and put it in a Trust Establishment document, which you can share with any relying party aiming to seek your verification services.

EXAMPLE
{
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "author": "did:example:alice",
  "created": "2010-01-01T19:23:24Z",
  "validFrom": "2010-01-01T19:23:24Z",
  "version": "0.0.1",
  "entries": {
    "https://example.com/trusted-issuers-for-credential.schema.json": {
      "did:example:bob": {
        "credentials": ["example.com/dank-meme.schema.json", "example.com/danker-meme.schema.json"]
      },
      "did:example:carol": {
        "credentials": ["example.com/dankest-meme.schema.json", "example.com/dankest-meme.schema.json.ld"]
      }
    }
  }
}

Example 3 - Multiple Topics

Alice is publishing a list about herself, sharing information that could be used in interactions with her.

EXAMPLE
{
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "author": "did:example:alice",
  "created": "2010-01-01T19:23:24Z",
  "validFrom": "2010-01-01T19:23:24Z",
  "version": 3,
  "entries": {
    "https://example.com/favorite-restaurants.schema.json": {
      "did:example:alice": {
        "names": [
          "Web 5 Guys",
          "Slow Foods Inc",
          "Burger Queen"
        ]
      }
    },
    "https://example.com/favorite-clothes-colors.schema.json": {
      "did:example:alice": {
        "clothes": {
          "shirts": [
            "blue",
            "green",
            "purple"
          ],
          "pants": [
            "yellow",
            "turqouise"
          ],
          "socks": [
            "white"
          ]
        }
      }
    }  
  }
}

Example 4 - Government Flight Regulations

In this example, the government identified by did:example:government is authoring a document showing the qualifications needed that each airline (the given entities) will require of each of their pilots: information about a requisite flight school and medical report.

EXAMPLE
{
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "author": "did:example:government",
  "created": "2010-01-01T19:23:24Z",
  "validFrom": "2010-01-01T19:23:24Z",
  "validUntil": "2020-01-01T19:23:24Z",
  "version": 5,
  "entries": {
    "https://example.com/trusted-flight-schools.schema.json": {
      "did:example:airline-1": {
        "pass_rate": 88,
        "names": [
          "Top Gun Academy",
          "Jim's Good Enough School"
        ]
      },
      "did:example:airline-2": {
        "pass_rate": 88,
        "names": [
          "Winging It",
          "Pretty Fly",
          "Parachutes Not Included"
        ]
      }
    },
    "https://example.com/medical-reports.schema.json": {
      "did:example:airline-1": {
        "state_certification": [
          "California",
          "Arizona",
          "Nevada"
        ],
        "institutions": [
          "99% Germ Free Facility",
          "Southern California's Finest Seal Hospital"
        ]
      },
      "did:example:airline-2": {
        "state_certification": [
        "New York",
        "Colorado",
        "Vermont"
        ],
        "institutions": [
          "Swiss Cheese No More",
          "We Take Your Blood"
        ]
      }
    }
  }
}

Example 5 - Accepted University Degrees

In this example, the author is an employer identified by did:example:employer-1 who is listing which degrees they are willing to accept for applicants from a set of universities.

EXAMPLE
{
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "author": "did:example:employer-1",
  "created": "2010-01-01T19:23:24Z",
  "validFrom": "2010-01-01T19:23:24Z",
  "validUntil": "2020-01-01T19:23:24Z",
  "version": 44,
  "entries": {
    "https://example.com/trusted-bachelors-degrees.schema.json": {
      "did:example:university-1": {
        "fields_of_study": ["Aerospace Engineering", "Scandinavian Literature", "Australian Sign Language"]
      },
      "did:example:university-2": {
        "fields_of_study": ["Philosophy", "Computer Science", "Mechanical Engineering"]
      }
    },
    "https://example.com/trusted-masters-degrees.schema.json":{
      "did:example:university-1": {
        "fields_of_study": ["Art History", "Philosophy", "Computer Science"]
      },
      "did:example:university-3": {
        "fields_of_study": ["Film", "Computer Engineering", "Mathematics"]
      }
    }
  }
}

Example 6 - Pizza Store

A pizza store, identified by did:example:round-n-proud is publishing a list of their chosen vendors, including which products they are willing to purchase for each vendor. This is useful for the vendors, and fans of Round n’ Proud everywhere that want to try to re-create the pizza at home.

EXAMPLE
{
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "author": "did:example:round-n-proud",
  "created": "2010-01-01T19:23:24Z",
  "validFrom": "2010-01-01T19:23:24Z",
  "validUntil": "2020-01-01T19:23:24Z",
  "version": 2,
  "entries": {
    "https://example.com/trusted-pepperoni-supplier.schema.json": {
      "did:example:joes-salamis": {
        "properties": {
          "names": ["Pure Pork", "Pork & Beef Mix", "Cured To Perfection"]
        }
      }
    },
    "https://example.com/trusted-cheese-supplier.schema.json": {
      "did:example:xtracheese": {
        "properties": {
          "mozzarella": ["Buffalo", "Stracciatella", "Nodini"],
          "ricotta": ["Smoked", "Sheep's Milk", "Fresh"]
        }
      }
    },
    "https://example.com/trusted-tomato-supplier.schema.json": {
      "did:example:offthevine": {
        "properties": {
          "tomatos": ["Cherry", "Roma", "Campari", "Better Boy"]
        }
      }
    }
  }
}

§ References

JSON Schema

JSON-LD

Linked Data Proofs

DID-CORE
Decentralized Identifiers (DIDs) v1.0. Drummond Reed; Manu Sporny; Markus Sabadello; Dave Longley; Christopher Allen; Jonathan Holt; 2020-09-07. Status: WD.
VC-DATA-MODEL
Verifiable Credentials Data Model 1.0. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; 2019-11-19. Status: REC.

Table of Contents