§ 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
id
– The object MUST contain anid
property. The value of this property MUST be a string. The string SHOULD provide a unique ID for the desired context. For example, a UUID such as32f54163-7166-48f1-93d8-ff217bdb0653
could provide an ID that is unique in a global context, while a simple string such asmy_trust_establishment-1
could be suitably unique in a local context.author
– The object MUST contain anauthor
property. The value of this property MUST be a string value representing the DID of the author.created
– The object MUST contain acreated
property proving a date-time value for when the object was created. The value of this property MUST be a RFC 3339 compliant timestamp value.validFrom
- The object MUST contain avalidFrom
property proving a date-time value for when the object is to be used. The value of this property MUST be a RFC 3339 compliant timestamp value.validUntil
- The object MAY contain avalidUntil
property proving a date-time value for when the object is no longer to be used. The value of this property MUST be a RFC 3339 compliant timestamp value.version
– The object MAY contain aversion
property. If present, the value of this property MUST be a string that uniquely identifies the instance of this document.entries
- The object MUST contain aentries
property that represents combinations oftopics
and entities for trust statements. Its value MUST be a JSON object composed as follows:- The object MUST have map keys as string values identifying the Topic of the Trust Establishment Document.
- The object MUST have map values as JSON objects, containing JSON maps and MUST be composed as follows:
{
"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
{
"$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.
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
{
"@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
{
"alg": "EdDSA",
"typ": "JWT",
"kid": "did:alice#keys-1"
}
{
"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"
}
}
}
}
}
}
}
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:
- 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.
- 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:
- Who are the intended consumers of this document, and how might they become aware of it?
- Is this document going to be updated? If so, how are updates shared? How may consumers of older versions become aware that there is a more recent version?
- Is hosting this document with a single party a risk: to availablility, privacy erosion, or censorship in some manner?
- If I intend for this document to be replicated, how do I do that? Is there a way to incentivize other parties to index or replicate my documents?
§ 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
{
"$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.
{
"$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.
{
"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.
{
"$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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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 Schema
- JSON Schema: A Media Type for Describing JSON Documents. A. Wright, H. Andrews, B. Hutton, G. Dennis. Status: 28 January 2020. Internet-Draft.
JSON-LD
- JSON-LD
- JSON-LD 1.1, A JSON-based Serialization for Linked Data. Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Pierra-Antoine Champin, Niklas Lindström. 16 July 2020. Status: W3C Recommendation.
Linked Data Proofs
- Data Integrity 1.0. Dave Longley, Manu Sporny. 30 April 2022. Status: W3C Draft Community Report.
- 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.