§ Verifiable Trust v1 Specification

Specification Status: Draft

Latest Draft: verana-labs/verifiable-trust-spec

Editors:: Fabrice Rochette (The Verana Foundation, 2060.io)

Participate:: GitHub repo; File a bug; Commit history

§ Abstract

The internet is broken. Existing communication channels are insecure and outdated. Because they rely on public identifiers — like email addresses, usernames, or phone numbers — anyone who knows your identifier can reach you, whether you invited them or not.

Worse, there’s no reliable way to verify the identity of either service providers or users. This leaves the door wide open to spam, phishing, fraud, and identity theft.

On the service side, each provider imposes its own fragmented registration process, often with complex password requirements or forced reliance on federated login systems—effectively handing control over to large third-party platforms.

Although the World Wide Web was originally built for openness and interoperability, dominant players have reshaped it into a closed, centralized system that most people and organizations now depend on. Privacy has become an afterthought, and personal data is routinely harvested, exploited, or leaked.

To rebuild a trustworthy internet, we need new communication channels — channels that are secure by design, based on mutual verification, and governed by decentralized trust.

Connecting to a service, proving who you are, or creating an account should be as simple and safe as presenting a verifiable credential.

A universal, open trust layer is essential for this vision to succeed.

That’s the purpose of Verifiable Trust.

§ About this Document

In order to fully understand the concepts developed in this document, you should have some basic knowledge of DID, DIDComm, VS, trust registry, ledger-based applications, and more generally, all terms present in the Terminology section.

§ Introduction

§ What is a Verifiable Service (VS)?

This section is non-normative.

A verifiable service is a service that provide a way to identify itself before connecting to it. Entities that want to connect to a verifiable service can review its presented verifiable credentials, prove their legitimacy by performing a trust resolution, and based on the result, decide to connect or not.

Additionally, a verifiable service that would like to issue or request verification of credentials must prove it is allowed to do so.

§ What is a Verifiable User Agent (VUA)?

This section is non-normative.

A Verifiable User Agent (VUA) is a software (a browser, an app, a wallet…) for connecting to VSs and other VUAs. When establishing connections, a VUA must verify the connection peer(s) and allow connection(s) only to compliant VS and VUA peers.

Additionally, VUAs must perform a trust resolution by verifying the credentials presented by the peers and query VPR(s) to check that these credentials have been issued by verified issuers.

§ What is a Verifiable Public Registry (VPR)?

This section is non-normative.

A Verifiable Public Registry (VPR) is a “registry of registries” public service, which provides:

trust registry features, that can be used by all its participants: create trust registries, for each trust registry, define its credential schemas, who can issue, verify credential of a specific credential schema,…
a query API, used by VSs, VUAs, to enforce application of governance frameworks and rules of created trust registries.

§ Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT 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.

§ Terminology

credential schema:: An VPR resource which represents a verifiable credential definition and the associated permissions and business rules for issuing, verifying or holding a credential linked to this credential schema.
decentralized identifier:: A decentralized identifier, as specified in [DID-CORE].
decentralized identifier communication:: DIDComm uses DIDs to establish confidential, ongoing connections.
decentralized identifier document:: A DID Document, as specified in [DID-CORE].
verifiable public registry:: a public, normally decentralized network, which provides: trust registry features, that can be used by all its participants: create trust registries, for each trust registry, define its credential schemas, who can issue, verify credential of a specific credential schema,… For more information, please refer to VPR Spec.
verifiable service:: A service, identified by a resolvable DID that can be deployed anywhere by its owner, and that is conforming to this spec and has a resolvable proof of trust.
verifiable user agent:: A user agent for accessing and using VSs. To be considered a VUA, a user agent must conform and enforce this spec, such as presenting a proof of trust to end user before accepting connecting to VS compliant services, and refuse connecting to not compliant services.
essential credential schema:: Default credential schema, owned by a trust registry, that provide the basis for a trust layer to exist in the ecosystem so that VUA can generate a proof of trust.
holder:: A role an entity might perform by possessing one or more verifiable credentials and generating verifiable presentations from them. A holder is often, but not always, a subject of the verifiable credentials they are holding. Holders store their credentials in credential repositories. Example holders include organizations, persons, things.
issuer:: A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder. Example issuers include corporations, non-profit organizations, trade associations, governments, and individuals.
json schema:: A json schema as defined in JSON-SCHEMA.
json schema credential:: A json schema credential as defined in [VC-JSON-SCHEMA].
linked-vp:: A presentation of a verifiable credential as specified in LINKED-VP.
participant:: An entity that uses an VPR and its trust layer to provide or use services.
proof of trust:: Visual representation using essential credential schemas of a trust resolution process of a Verifiable Service, for identifying the VS, its owner, and the issuer of the verifiable credential of its owner.
session:: A session defines a connection to a DID Document provided service from a third party VS or VUA.
subject:: A thing about which claims are made. Example subjects include human beings, animals, things, and organization, a DID…
trust registry: An approved list of issuers and verifiers that are authorized to issue/verify certain credentials in an ecosystem.
trust resolution:: Process run by, for example a VUA or a VS, which purpose is to recursively resolve DID by digging into DID Documents and look for linked-vp entries and their issuer DIDs, and trust-registry entries to gather whether the service provided by the DID is trustable (and legitimate), or not.
verifier:: A role an entity performs by receiving one or more verifiable credentials, optionally inside a verifiable presentation for processing. Example verifiers include service providers.
verifiable credential:: A verifiable credential as defined in [VC-DATA-MODEL].

§ Specification

§ VPR stored Verifiable Credential Json Schemas

This section is not part of this specification and is provided for understanding only.

As specified in the VPR spec, Credential Schemas (CS) are created by Ecosystems and linked to a Trust Registry in a VPR.

An ecosystem creates a Trust Registry in a VPR by creating a TrustRegistry entry tr, and create one or more CredentialSchema entry(ies), which definition are Json Schema(s).

Example:

{
  "$id": "vpr-mainnet:/vpr/v1/cs/js/VPR_CREDENTIAL_SCHEMA_ID",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SimpleExampleCredential",
  "description": "SimpleExampleCredential using JsonSchema",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "firstName": {
          "type": "string",
          "minLength": 0,
          "maxLength": 256
        },
        "lastName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "expirationDate": {
          "type": "string",
          "format": "date"
        },
        "countryOfResidence": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        }
      },
      "required": [
        "id",
        "lastName",
        "birthDate",
        "expirationDate",
        "countryOfResidence"
      ]
    }
  }
}

§ [ECS] Essential Credential Schemas

Essential Credential Schemas are the Verifiable Trust basic needed schemas for enabling a minimum trust resolution in Services and User Agents by answering these questions:

who is the provider of this Verifiable Service?
what is the minimum age required to access this service?
is the User Agent trying to connect to a Verifiable Service a Verifiable User Agent?
…

Essential Credential Schemas (ECS) are created and linked to a Trust Registry in a VPR. There are 4 kinds of ECS:

Service;
Organization;
Person;
UserAgent.

A Trust Registry creates itself in a VPR by creating a TrustRegistry entry tr. For this Trust Registry to qualify for being used for trust resolution in VSs and VUAs, it MUST provide, associated to the TrustRegistry entry tr, all 4 CredentialSchema entries, with a respective json_schema attribute defined as follows in [ECS-SERVICE], [ECS-ORG], [ECS-PERSON], [ECS-USER-AGENT].

§ [ECS-SERVICE] Service Credential Json Schema

Credential subject object of schema MUST contain the following attributes:

id (string) (mandatory): the DID of the service the credential will be issued to.
name (string) (mandatory): service name. UTF8 charset, max length: 512 bytes.
type (string) (mandatory): service type. UTF8 charset, max length: 128 bytes. Service types will be defined later.
description (string) (mandatory): service description. UTF8 charset, max length: 4096 bytes.
logo (image) (mandatory): the logo of the service, as it will be shown in browsers and search engines.
minimumAgeRequired (integer) (mandatory): minimum required age to connect to service. Allowed value: 0 to 255. Used by browsers that provide a simple birth date based parental control.
termsAndConditions (string) (mandatory): URL of the terms and conditions of the service. It is recommended to store terms and conditions in a file, in a repository that allows file hash verification (IPFS).
termsAndConditionsHash (string) (optional): If terms and conditions of the service are stored in a file, optional hash of the file for data integrity verification.
privacyPolicy (string) (mandatory): URL of the terms and conditions of the service. MAY be the same URL that terms_and_conditions if file are combined. It is recommended to store privacy policy in a file repository that allows file hash verification (IPFS).
privacyPolicyHash (string) (optional): If privacy policy of the service are stored in a file, optional hash of the file for data integrity verification.

the resulting json_schema attribute will be the following Json Schema.

VPR_CREDENTIAL_SCHEMA_ID is replaced by the schema_id of the created CredentialSchema entry in the VPR.

{
  "$id": "vpr-mainnet:/vpr/v1/cs/js/VPR_CREDENTIAL_SCHEMA_ID",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ServiceCredential",
  "description": "ServiceCredential using JsonSchema",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "type": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "description": {
          "type": "string",
          "minLength": 0,
          "maxLength": 4096
        },
        "logo": {
          "type": "string",
          "contentEncoding": "base64",
          "contentMediaType": "image/png"
        },
        "minimumAgeRequired": {
          "type": "number",
          "minimum": 0,
          "exclusiveMaximum": 150
        },
        "termsAndConditions": {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        },
        "termsAndConditionsHash": {
          "type": "string"
        },
        "privacyPolicy": {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        },
        "privacyPolicyHash": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "type",
        "description",
        "logo",
        "minimumAgeRequired",
        "termsAndConditions",
        "privacyPolicy"
      ]
    }
  }
}

§ [ECS-ORG] OrganizationCredential Json Schema

Credential subject object of schema MUST contain the following attributes:

id (string) (mandatory): the DID of the service the credential has been issued to, which is the subject of the verifiable credential.
name (string) (mandatory): name of the organization.
logo (image) (mandatory): the logo of the organization, as it will be shown in browsers and search engines.
registryId (string) (mandatory): registry id of the organization.
registryUrl (string) (mandatory): link to registry data.
address (string) (mandatory): address of the organization.
type (string) (mandatory): type of organization. PUBLIC, PRIVATE, FOUNDATION.
countryCode (string) (mandatory): country where the company is registered.

the resulting json_schema attribute will be the following Json Schema.

VPR_CREDENTIAL_SCHEMA_ID is replaced by the schema_id of the created CredentialSchema entry in the VPR.

{
  "$id": "vpr-mainnet:/vpr/v1/cs/js/VPR_CREDENTIAL_SCHEMA_ID",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "OrganizationCredential",
  "description": "OrganizationCredential using JsonSchema",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "name": {
          "type": "string",
          "minLength": 0,
          "maxLength": 256
        },
        "logo": {
          "type": "string",
          "contentEncoding": "base64",
          "contentMediaType": "image/png"
        },
        "registryId": {
          "type": "string",
          "minLength": 0,
          "maxLength": 256
        },
        "registryUrl": {
          "type": "string",
          "minLength": 0,
          "maxLength": 256
        },
        "address": {
          "type": "string",
          "minLength": 0,
          "maxLength": 1024
        },
        "type": {
          "type": "string",
          "enum": ["PUBLIC", "PRIVATE", "FOUNDATION"]
        },
        "countryCode": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        }
      },
      "required": [
        "id",
        "name",
        "logo",
        "registryId",
        "registryUrl",
        "address",
        "type",
        "countryCode"
      ]
    }
  }
}

§ [ECS-PERSON] Person Credential Json Schema

Credential subject object of schema MUST contain the following attributes:

id (string) (mandatory): the DID of the service the credential has been issued to.
firstName (string) (optional): first name of the person.
lastName (string) (mandatory): last name of the person.
avatar (image) (optional): the avatar of this person, as it will be shown in browsers and search engines.
birthDate (date) (mandatory): date of birth.
countryOfResidence (string) (mandatory): the country of residence.

the resulting json_schema attribute will be the following Json Schema.

VPR_CREDENTIAL_SCHEMA_ID is replaced by the schema_id of the created CredentialSchema entry in the VPR.

{
  "$id": "vpr-mainnet:/vpr/v1/cs/js/VPR_CREDENTIAL_SCHEMA_ID",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "PersonCredential",
  "description": "PersonCredential using JsonSchema",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "firstName": {
          "type": "string",
          "minLength": 0,
          "maxLength": 256
        },
        "lastName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "avatar": {
          "type": "string",
          "contentEncoding": "base64",
          "contentMediaType": "image/png"
        },
        "birthDate": {
          "type": "string",
          "format": "date"
        },
        "countryOfResidence": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        }
      },
      "required": [
        "id",
        "lastName",
        "birthDate",
        "countryOfResidence"
      ]
    }
  }
}

§ [ECS-USER-AGENT] User Agent Credential Json Schema

Credential subject object of schema MUST contain the following attributes:

id (string) (mandatory): the DID of the user agent the credential will be issued to.
name (string) (mandatory): agent name. UTF8 charset, max length: 512 bytes.
description (string) (mandatory): agent description. UTF8 charset, max length: 4096 bytes.
category (string) (mandatory): the category of the agent, ie SOCIAL_NETWORK,…
logo (image) (mandatory): the logo of the agent, as it will be shown in search engines.
wallet (boolean) (mandatory): If the agent implements the DTW (Verifiable Trust Wallet) spec, and thus provides wallet features.
termsAndConditions (string) (mandatory): URL of the terms and conditions of the service. It is recommended to store terms and conditions in a file, in a repository that allows file hash verification (IPFS).
termsAndConditionsHash (string) (optional): If terms and conditions of the service are stored in a file, optional hash of the file for data integrity verification.
privacyPolicy (string) (mandatory): URL of the terms and conditions of the service. MAY be the same URL that terms_and_conditions if file are combined. It is recommended to store privacy policy in a file repository that allows file hash verification (IPFS).
privacyPolicyHash (string) (optional): If privacy policy of the service are stored in a file, optional hash of the file for data integrity verification.

the resulting json_schema attribute will be the following Json Schema.

VPR_CREDENTIAL_SCHEMA_ID is replaced by the schema_id of the created CredentialSchema entry in the VPR.

{
  "$id": "vpr-mainnet:/vpr/v1/cs/js/VPR_CREDENTIAL_SCHEMA_ID",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "UserAgentCredential",
  "description": "UserAgentCredential using JsonSchema",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "description": {
          "type": "string",
          "minLength": 0,
          "maxLength": 4096
        },
        "category": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "logo": {
          "type": "string",
          "contentEncoding": "base64",
          "contentMediaType": "image/png"
        },
        "wallet": {
          "type": "boolean"
        },
        "termsAndConditions": {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        },
        "termsAndConditionsHash": {
          "type": "string"
        },
        "privacyPolicy": {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        },
        "privacyPolicyHash": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "category",
        "logo",
        "wallet",
        "termsAndConditions",
        "privacyPolicy"
      ]
    }
  }
}

§ [VT-JSON-SCHEMA-CRED] Verifiable Trust Json Schema Credential

A Verifiable Trust Json Schema Credential is a json schema credential self-issued by a Trust Registry DID, that MUST refer to the json schema of a CredentialSchema entry created in a VPR. Issuer of the Verifiable Trust Json Schema Credential MUST be the same DID that the DID of the TrustRegistry entry created in the VPR than owns the CredentialSchema entry in the VPR.

A Verifiable Trust Json Schema Credential MUST have a credentialSchema property that contains exactly the following:

  "credentialSchema": {
    "id": "https://w3c.github.io/vc-json-schema/schema/json-schema-credential-schema.json",
    "type": "JsonSchema",
    "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
  }

Additionally, it MUST have a credentialSubject object with:

a id properties that is the URL to access the json schema in the VPR,
type MUST be set to “JsonSchema”,
an object jsonSchema MUST be present with an $ref properties that is the URL to access the json schema in the VPR
a digestSRI property that MUST match the json schema file content hash.

Example of a Verifiable Trust Json Schema Credential:

VtJsonSchemaCredential.json:


{
  "@context": [
      "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "https://ecs-trust-registry/vt-credential-schema-credential.json",
  "type": ["VerifiableCredential", "JsonSchemaCredential"],
  "issuer": "did:example:ecs-trust-registry",
  "issuanceDate": "2024-01-01T19:23:24Z",
  "credentialSchema": {
    "id": "https://w3c.github.io/vc-json-schema/schema/json-schema-credential-schema.json",
    "type": "JsonSchema",
    "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
  },
  "credentialSubject": {
    "id": "https://vpr-hostname/vpr/v1/cs/js/12345678",
    "type": "JsonSchema",
    "jsonSchema": {
      "$ref": "https://vpr-hostname/vpr/v1/cs/js/12345678"
    },
    "digestSRI": "sha384-ABCSGyugst67rs67rdbugsy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCeZ" 
  }
}

NOTE

This is subject to a slight update of vc-json-schema as specified in this

§ [VT-TR-DIDDOC] Trust Registry DID Document

For each CredentialSchema entry a Trust Registry has created in a VPR, the Trust Registry MUST self-issue the corresponding Verifiable Trust Json Schema Credential as specified in [VT-JSON-SCHEMA-CRED].

Additionally, in MUST present the Verifiable Trust Json Schema Credential(s) in its DIDDocument, as well as the corresponding trust registry entry for verification. To do so, it MUST define the following entries in its DIDDocument:

for each CredentialSchema entry it wants to be resolvable, a “LinkedVerifiablePresentation” service entry with a fragment that MUST start with to #vpr-schemas, that MUST point to a self-issued Verifiable Trust Json Schema Credential as specified in [VT-JSON-SCHEMA-CRED].
a “VerifiablePublicRegistry” service entry with fragment name equal to the concatenation of #vpr-schemas-trust-registry and the id of the Trust Registry in the VPR, that MUST point to the API of the DID’s trust registry in the VPR.

Example:

  "service": [
    {
      "id": "did:example:dl-trust-registry#vpr-schemas-driving-license-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://dl-trust-registry/driving-license-credential-schema-presentation.json"]
    },
    {
      "id": "did:example:dl-trust-registry#vpr-schemas-trust-registry-1234",
      "type": "VerifiablePublicRegistry",
      "version": "1.0",
      "serviceEndpoint": ["https://vpr-hostname/vpr/v1/"]
    }
    ...
  ]

If the Trust Registry wishes to provide ECS trust resolution, it MUST present 4 VT Json Credential Schemas of the 4 ECSs required for trust resolution, as well as the corresponding trust registry entry for verification. To do that, it MUST define the following entries in its DIDDocument:

a “LinkedVerifiablePresentation” service entry with fragment name equal to #vpr-essential-schemas-service-credential-schema-credential, that MUST point to a self-issued Service Verifiable Trust Json Schema Credential as specified in [SERVICE-JSON-SCHEMA-CRED] of a service json schema as specified in [ECS-SERVICE].
a “LinkedVerifiablePresentation” service entry with fragment name equal to #vpr-essential-schemas-org-credential-schema-credential, that MUST point to a self-issued json schema credential of a VT json schema as specified in [ECS-ORG].
a “LinkedVerifiablePresentation” service entry with fragment name equal to #vpr-essential-schemas-person-credential-schema-credential, that MUST point to a self-issued json schema credential of a VT json schema as specified in [ECS-PERSON].
a “LinkedVerifiablePresentation” service entry with fragment name equal to #vpr-essential-schemas-user-agent-credential-schema-credential, that MUST point to a self-issued json schema credential of a VT json schema as specified in [ECS-USER-AGENT].
a “VerifiablePublicRegistry” service entry with fragment name equal to #vpr-essential-schemas-trust-registry, that MUST point to the API URL of this DID’s trust registry in the VPR.

Example:

  "service": [
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-service-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://ecs-trust-registry/service-credential-schema-presentation.json"]
    },
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-organization-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://ecs-trust-registry/org-credential-schema-presentation.json"]
    },
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-person-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://ecs-trust-registry/person-credential-schema-presentation.json"]
    },
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-user-agent-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://ecs-trust-registry/user-agent-credential-schema-presentation.json"]
    },
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-trust-registry-789041745",
      "type": "VerifiablePublicRegistry",
      "version": "1.0",
      "serviceEndpoint": ["https://vpr-hostname/vpr/v1/"]
    }
    
    ...
  ]

§ [VT-CRED] Verifiable Trust Credential

A simple diagram for a clear understanding:

A Verifiable Trust Credential MUST have a credentialSchema property:

id must point to a json schema credential issued by the trust registry DID owner of the schema in the VPR;
type MUST be JsonSchemaCredential.

As a matter of fact, a Verifiable Trust Credential MUST conform to the dereferenced json schema of the JsonSchemaCredential.

Example DTCredential.json:


{
  "@context": [
    "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "did:example:user-vs.example.com",
  "type": ["VerifiableCredential", "ServiceCredential"],
  "issuer": "did:example:user-vs.example.com",
  "credentialSubject": {
     "id": "did:example:user-vs.example.com",
    ...
  },
  ...
  "credentialSchema": {
    "id": "https://ecs-trust-registry/service-credential-schema-credential.json",
    "type": "JsonSchemaCredential"
  }
}

§ [VT-EC] VT Essential Credentials

VT Service Essential Credential [VT-EC-SERVICE]: a [VT-CRED] linked to a CredentialSchema entry that conforms to [ECS-SERVICE].
VT Organization Essential Credential [VT-EC-ORG]: a [VT-CRED] linked to a CredentialSchema entry that conforms to [ECS-ORG].
VT Person Essential Credential [VT-EC-PERSON]: a [VT-CRED] linked to a CredentialSchema entry that conforms to [ECS-PERSON].
VT User Agent Essential Credential [VT-EC-USER-AGENT]: a [VT-CRED] linked to a CredentialSchema entry that conforms to [ECS-USER-AGENT].

§ [VS-REQ] Requirements for a service to be a VS

[VS-REQ-1] A VS MUST be identified by a DID. The DID of a VS MUST resolve to a DID Document.
[VS-REQ-2] A VS DID Document MUST present (linked-vp) a VT Service Essential Credential that conforms to [VT-EC-SERVICE].
[VS-REQ-3] If the issuer of the VT Service Essential Credential of [VS-REQ-2] is the DID of this service, service DID Document MUST present a credential that conforms to [VT-EC-ORG] or (exclusive) a [VT-EC-PERSON].
[VS-REQ-4] If the issuer of the VT Service Credential of [VS-REQ-2] is not the DID of this service, issuer service MUST be a [VS-REQ] VS that conforms to [VS-REQ-3].
[VS-REQ-5] A compliant VS MUST dereference all service credentials, User Agent credentials, DID Documents, verify VS Json Schema Credentials, Json Schema hashes, use the Verifiable Trust Registry API,… comply with [TR-WL] to resolve trust and ensure compliance by denying unauthorized actions.

NOTE

In other words, to be a VS, a service MUST identify itself directly by presenting an Organization or a Person Essential Credential, or the issuer of its Service Essential Credential MUST identify itself by presenting an Organization or a Person Essential Credential.

[VS-REQ-5] The service MAY issue, present through linked verifiable presentation entries, or request presentation of any additional VS Credential that conforms to [VT-CRED].

§ [VS-CI] Credential Issuance

[VS-CI-1] A VS CAN issue [VT-CRED] VT Credentials.
[VS-CI-2] A VS MUST NOT issue credentials that are not compliant with [VT-CRED].

§ [VS-PR] Presentation Request

[VS-PR-1] A VS CAN request presentation of [VT-CRED] VT Credentials
[VS-PR-2] A VS MUST NOT request presentation of credentials that are not compliant with [VT-CRED].

§ [VS-LVP] Linked Verifiable Presentations

Linked verifiable presentations of credential CAN be present in service DID Document, if present, they MUST conform to the following:

[VS-LVP-1] Verifiable presentation MUST be signed by the VS DID.
[VS-LVP-2] if linked verifiable presentation id fragment start with #vpr-schemas, presented credential and DID Document MUST conform to [VT-CRED].
[VS-LVP-3] if linked verifiable presentation id fragment is #vpr-essential-schemas-service-credential, presented credential MUST be a VT Service Essential Credential [VT-EC-SERVICE].
[VS-LVP-4] if linked verifiable presentation id fragment is #vpr-essential-schemas-org-credential, presented credential MUST be a VT Organization Essential Credential [VT-EC-ORG].
[VS-LVP-5] if linked verifiable presentation id fragment is #vpr-essential-schemas-person-credential, presented credential MUST be a VT Person Essential Credential [VT-EC-PERSON].

§ [VUA-REQ] Requirements for a User Agent to be a VUA

TODO

ignore for now

[VUA-REQ-1] A VUA MUST be identified by a DID. The DID of a VUA MUST resolve to a DID Document.
[VUA-REQ-2] A VUA DID Document MUST present a VT Organization Essential Credential that conforms to [VT-EC-ORG] or (exclusive) to [VT-EC-PERSON].
[VUA-REQ-3] A VUA The DID of a VUA MUST be an issuer of VT User Agent Essential Credential schema that conforms to [VT-EC-USER-AGENT].
[VUA-REQ-4] A compliant VUA MUST dereference all service credentials, User Agent credentials, DID Documents, verify Verifiable Trust Json Schema Credentials, Json Schema hashes, use the Verifiable Trust Registry API,… comply with [TR-WL] to resolve trust and ensure compliance by denying unauthorized actions.

NOTE

In other words, a to be a VUA, a User Agent MUST identify itself to the other end by sharing its DID, and the other end MUST verify it complies with [VUA-REQ]

TODO

This must be modified as each user agent instance will have its own credential issued.

§ [VS-CONN-VS] Requirements for a VS to accept a connection from another service

When a VS VS-1 receive a connection request from a service Service-2 to one of its services specified in DID Document, VS-1 MUST verify service Service-2 complies with [VS-SPEC], else VS-1 MUST NOT accept the connection. Exception: if provided by VS-1 service Service-2 wants to connect to is an issuer of [VT-EC-ORG] or [VT-EC-PERSON] and Service-2 is just missing a [VT-EC-ORG] / [VT-EC-PERSON] for being compliant, connection CAN be accepted by VS-1.

§ [VS-CONN-VUA] Requirements for a VS to accept a connection from a User Agent

When a User Agent start a session with a compliant VS, VS MUST verify that User Agent complies with [VUA-SPEC], else VS MUST drop the connection.

§ [VUA-CONN-VS] Requirements for a VUA to accept connecting to a service

When a VUA start a session with a service, VUA MUST verify VS complies with [VS-SPEC], else VUA MUST NOT connect to VS.

§ [VUA-CONN-VUA] Requirements for a VUA to accept connecting to a another User Agent

When a VUA start a session with another User Agent, VUA MUST verify that the peer User Agent complies with [VUA-SPEC], else VUA MUST drop the connection.

§ [TR-WL] VPR and Trust Registry whitelists

Compliant VSs and VUAs MUST maintain a list of trusted VPRs and trusted VT Essential Credential issuers, and ignore VPRs and VT ECS issuers that are not in these lists when resolving trust:

[TR-WL-VPR]: A list of prefix URLs of trusted VPRs (registry of registries).

Example:


{ 
  verifiablePublicRegistries: [ 
    { 
      "name": "vpr-mainnet",
      "baseurl": "https://vpr-mainnet/vpr/v1",
      "version": "1"
      "production": true
    },
    { 
      "name": "vpr-testnet",
      "baseurl": "https://vpr-testnet/vpr/v1",
      "version": "1"
      "production": false
    },
    { 
      "name": "vpr-devnet",
      "baseurl": "https://vpr-devnet/vpr/v2",
      "version": "2"
      "production": false
    },
  ]
}

[TR-WL-ES-TR]: A list of DIDs of trusted Trust Registries for providing essential credential schemas.

Example:


{ 
  essentialSchemaTrustRegistries: [ 
    { 
      "tr": "did:example:ecs-trust-registry",
      "vpr": "vpr-mainnet"
    },
    { 
      "tr": "did:efg:ecs-trust-registry",
      "vpr": "vpr-testnet"
    }
  ]
}

§ [VT-RESOL] Verification of permission(s) in Verifiable Public Registries

Please refer to Permission Module in VPR specs.

Process for verifying trust is always following the same rules. You’ll find few examples below.

§ Verify that an Organization Credential has been issued by an authorized issuer

“We” refers to a VUA or a VS.

for a given service, get its Organization credential linked verifiable presentation in its DID Document.
get and load the linked Json Schema Credential. Verify that the issuer (the Trust Registry owner of this schema) of this Json Schema Credential is in your essentialSchemaTrustRegistries list. Verify the digestSRI of the credentialSchema and the credentialSubject properties.
get the credential schema id schema_id from the credentialSubject of the Json Schema Credential.
use the VPR API such as “Get a Credential Schema” and “Get Trust Registry” methods. Verify that the Trust Registry DID matches the DID of the Json Schema Credential. If schema is open for anyone to issue, no need to do any further check.
If schema is not open, call “Find Permissions With DID” method to verify that issuer of the organization credential had a valid permission for this schema at the time the credential was issued. If yes, credential has been issued by an authorized issuer.

§ Verify that a VT Credential has been issued by an authorized issuer

We consider presentation receiver has already performed the checks and credential schema has credential verification set to OPEN (anyone can verify). “We” refers to a VUA or a VS.

receive a credential presentation or get it as a linked verifiable presentation in a DID Document.
get and load the linked Json Schema Credential. Verify that the issuer (the Trust Registry owner of this schema) of this Json Schema Credential is in your trustRegistries list. Verify the digestSRI of the credentialSchema and the credentialSubject properties.
get the credential schema id schema_id from the credentialSubject of the Json Schema Credential.
use the VPR API such as “Get a Credential Schema” and “Get Trust Registry” methods. Verify that the Trust Registry DID matches the DID of the Json Schema Credential. If schema is open for anyone to issue, no need to do any further check.
If schema is not open, call “Find Permissions With DID” method to verify that issuer of the organization credential had a valid permission for this schema at the time the credential was issued. If yes, credential has been issued by an authorized issuer.

§ Verify that a service has the right to request the presentation of a Credential of a given Issuer for a given schema

We consider we verified that the service is complying with this spec before connecting to it. “We” refers to a VUA or a VS.

A requester want to request the presentation of a credential.

the requester shares the schemaId to us;
we use the VPR API such as “Get a Credential Schema” and “Get Trust Registry” methods and check if verification is open for this schema. If schema is not open, then verifier MUST create a transaction. We share a sessionId (uuid) to requester;
we shared a list of found credential in the wallet(s) (issuerPermId, walletAgentPermId) (that implies we resolved the permIds by using the “Find Permissions With DID” method at issuance date)
requester chooses a credential, verifies issuerPermId and walletAgentPermId
if a payment is required, the verifier uses the “Create or update Permission Session” method to pay.
requester inform us which credential it wants.
if schema is not open, we call “Get Permission Session” to verify requester paid using the sessionId.
we present the selected credential to verifier.

NOTE

Services that will want to request presentation of credential will need a crypto wallet and keys if VPR is a blockchain

§ Example

Let’s see a full example in action. Here is a DID Document of a compliant VS:

  "service": [
    {
      "id": "did:example:user-vs.example.com#vpr-essential-schemas-service-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://user-vs.example.com/service-credential-presentation.json"]
    },
    {
      "id": "did:example:user-vs.example.com#vpr-essential-schemas-org-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://user-vs.example.com/org-credential-presentation.json"]
    },
    {
      "id": "did:example:user-vs.example.com#vpr-schemas-trademark-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://user-vs.example.com/trademark-credential-presentation.json"]
    }
    ...
  ]

Let’s dereference…

service-credential-presentation.json:


{
  "@context": [
    "https://www.w3.org/ns/credentials/v2"
  ],
  "holder": "did:example:user-vs.example.com",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/ns/credentials/v2"
      ],
      "id": "did:example:user-vs.example.com",
      "type": ["VerifiableCredential", "ServiceCredential"],
      "issuer": "did:example:user-vs.example.com",
      "credentialSubject": {
        "id": "did:example:user-vs.example.com",
        ...
      },
      ...
      "credentialSchema": {
        "id": "https://ecs-trust-registry/service-credential-schema-credential.json",
        "type": "JsonSchemaCredential"
      }
    }
  ],
  "id": "https://user-vs.example.com/service-credential-presentation.json",
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2024-02-08T17:38:46Z",
    "verificationMethod": "did:example:user-vs.example.com#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "proofPurpose": "assertionMethod",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..6_k6Dbgug-XvksZvDVi9UxUTAmQ0J76pjdrQyNaQL7eVMmP_SUPZCqso6EN3aEKFSsJrjDJoPJa9rBK99mXvDw"
  }
}

service-credential-schema-credential.json:


{
  "@context": [
      "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "https://ecs-trust-registry/service-credential-schema-credential.json",
  "type": ["VerifiableCredential", "JsonSchemaCredential"],
  "issuer": "did:example:ecs-trust-registry",
  "issuanceDate": "2024-01-01T19:23:24Z",
  "credentialSchema": {
    "id": "https://w3c.github.io/vc-json-schema/schema/json-schema-credential-schema.json",
    "type": "JsonSchema",
    "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
  },
  "credentialSubject": {
    "id": "https://vpr-hostname/vpr/v1/cs/js/12345678",
    "type": "JsonSchema",
    "jsonSchema": {
      "$ref": "https://vpr-hostname/vpr/v1/cs/js/12345678"
    },
    "digestSRI": "sha384-ABCSGyugst67rs67rdbugsy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW" 
  }
}

NOTE

Here for trust resolution we need to get did:example:ecs-trust-registry DIDDocument and verify its TrustRegistry entry (see DID Doc below)

org-credential-presentation.json:


{
  "@context": [
    "https://www.w3.org/ns/credentials/v2"
  ],
  "holder": "did:example:user-vs.example.com",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/ns/credentials/v2"
      ],
      "id": "did:example:user-vs.example.com",
      "type": ["VerifiableCredential", "OrganizationCredential"],
      "issuer": "did:example:certivera.com",
      "credentialSubject": {
        "id": "did:example:user-vs.example.com",
        ...
      },
      ...
      "credentialSchema": {
        "id": "https://ecs-trust-registry/org-credential-schema-credential.json",
        "type": "JsonSchemaCredential"
      }
    }
  ],
  "id": "https://user-vs.example.com/org-credential-presentation.json",
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2024-02-08T17:38:46Z",
    "verificationMethod": "did:example:user-vs.example.com#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "proofPurpose": "assertionMethod",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..6_k6Dbgug-XvksZvDVi9UxUTAmQ0J76pjdrQyNaQL7eVMmP_SUPZCqso6EN3aEKFSsJrjDJoPJa9rBK99mXvDw"
  }
}

org-credential-schema-credential.json:


{
  "@context": [
      "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "https://example.tr/credentials/OrganizationJsonSchemaCredential",
  "type": ["VerifiableCredential", "JsonSchemaCredential"],
  "issuer": "did:example:ecs-trust-registry",
  "issuanceDate": "2024-01-01T19:23:24Z",
  "credentialSchema": {
    "id": "https://w3c.github.io/vc-json-schema/schema/json-schema-credential-schema.json",
    "type": "JsonSchema",
    "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
  },
  "credentialSubject": {
    "id": "https://vpr-hostname/vpr/v1/cs/js/78901234",
    "type": "JsonSchema",
    "jsonSchema": {
      "$ref": "https://vpr-hostname/vpr/v1/cs/js/78901234"
    },
    "digestSRI": "sha384-ABCSGyugst67rs67rdbugsy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"  
  }
}

trademark-credential-presentation.json:


{
  "@context": [
    "https://www.w3.org/ns/credentials/v2"
  ],
  "holder": "did:example:user-vs.example.com",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/ns/credentials/v2"
      ],
      "id": "did:example:user-vs.example.com",
      "type": ["VerifiableCredential", "TrademarkCredential"],
      "issuer": "did:example:trademark.abc",
      "credentialSubject": {
        "id": "did:example:user-vs.example.com",
        ...
      },
      ...
      "credentialSchema": {
        "id": "https://trademark.abc/credentials/TrademarkJsonSchemaCredential",
        "type": "JsonSchemaCredential"
      }
      "credentialSchema": {
        "id": "https://vpr-hostname/vpr/v1/cs/js/7358717246",
        "type": "JsonSchema",
        "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
      }
    }
  ],
  "id": "https://user-vs.example.com/trademark-credential-presentation.json",
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2024-02-08T17:38:46Z",
    "verificationMethod": "did:example:user-vs.example.com#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "proofPurpose": "assertionMethod",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..6_k6Dbgug-XvksZvDVi9UxUTAmQ0J76pjdrQyNaQL7eVMmP_SUPZCqso6EN3aEKFSsJrjDJoPJa9rBK99mXvDw"
  }
}

TrademarkJsonSchemaCredential.json:


{
  "@context": [
      "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "https://trademark.abc/credentials/TrademarkJsonSchemaCredential",
  "type": ["VerifiableCredential", "JsonSchemaCredential"],
  "issuer": "did:example:trademark-trust-registry",
  "issuanceDate": "2024-01-01T19:23:24Z",
  "credentialSchema": {
    "id": "https://w3c.github.io/vc-json-schema/schema/json-schema-credential-schema.json",
    "type": "JsonSchema",
    "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
  },
  "credentialSubject": {
    "id": "https://example-vpr/cs/js/7358717246",
    "type": "JsonSchema",
    "jsonSchema": {
       "$ref": "https://example-vpr/vpr/v1/cs/js/7358717246",
    }
    "digestSRI": "sha384-GHJSGyugst67rs67rdbugsy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
  }
}

DID Document of did:example:ecs-trust-registry:

  "service": [
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-service-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://ecs-trust-registry/service-credential-schema-presentation.json"]
    },
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-organization-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://ecs-trust-registry/org-credential-schema-presentation.json"]
    },
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-person-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://ecs-trust-registry/person-credential-schema-presentation.json"]
    },
    {
      "id": "did:example:ecs-trust-registry#vpr-essential-schemas-trust-registry-8721547851287",
      "type": "VerifiablePublicRegistry",
      "version": "1.0",
      "serviceEndpoint": ["https://vpr-hostname/vpr/v1/"]
    }
    
    ...
  ]

DID Document of did:example:trademark-trust-registry:

  ...
  "service": [
    {
      "id": "did:example:trademark-trust-registry#vpr-schemas-trademark-credential-schema-credential",
      "type": "LinkedVerifiablePresentation",
      "serviceEndpoint": ["https://trademark.abc/credentials/TrademarkJsonSchemaCredential"]
    },
    {
      "id": "did:example:trademark-trust-registry#vpr-schemas-trust-registry-7890",
      "type": "VerifiablePublicRegistry",
      "version": "1.0",
      "serviceEndpoint": ["https://vpr-hostname/vpr/v1/"]
    }
    
    ...
  ]
  ...

§ Implementations

This section is non-normative.

Implementations are provided by the community, being the Verana Foundation and 2060.io the most active contributors at the moment.

§ Trust Resolution

§ Typescript Implementation

::todo Provide repo info :::

§ VUAs Implementations

§ Hologram Messaging

This section is non-normative.

Hologram Messaging is a Verifiable Credential wallet and messaging app with true privacy preserving features. Unlike other messaging apps, Hologram is a self-custody app, which means user’s data is only stored on device, and exclusively under user’s control.

Hologram is the first ever-built VUA and is already available in the app stores, look for “Hologram Messaging” in apple store, google play or huawei’s app gallery. It has a user interface very similar to that well known apps like whatsapp, signal or telegram.

Based on the DIDComm open protocol, Hologram provides classic features such has peer-to-peer chat with verifiable credential exchange (to be able to verify who I am chatting to), as well as a Verifiable Chatbot browser to connect to any decentralized Hologram Chatbot VS. Anyone can create an Hologram Service, publish its DID, and invite users to connect by using Hologram (or any other compatible User Agent), request Verifiable Credential Presentations, issue credentials, perform calls and video calls, exchange content, read NFC chips, and more. Integration of p2p money transfers and payments are underway.

Because Hologram is using the DIDComm open protocol, anyone can create a new interoperable VUA so that Hologram users will natively be able to chat with users from others compatible VUAs.

§ VSs Implementations

§ Hologram Services

This section is non-normative.

Hologram Services can be of 2 kinds:

Chatbot Services
Basic Out-of-band Services, for Verifiable Credential Presentation Request and/or Verifiable Credential Issuance.

Creation of an Hologram Service is really straightforward, just have a look at 2060.io github repository for examples.

Popular Chatbot Services include:

UnicID, a chatbot service for obtaining a Verifiable Credential by reading a NFC-compatible passport or Id Card with a mobile phone. Service reads the document, then perform a biometric face matching with liveness detection to verify that user of the mobile phone is the same person than the picture of the face registered in the NFC chip of the document, and if there is a match, a Verifiable Credential is issued to user. After issuing the credential, service does not keep any user-related data.
AvatarID, a service for creating a unique avatar, protected by a biometric hash of user’s face. If user looses his/her phone, he/she can restore the Avatar by performing a biometric face matching with liveness detection.

Basic Out-of-band Services include:

VC Authenticator: an OpenID connect plugin for logging-in a user by requesting presentation of a verifiable credential
VC Verifier: a simple service for generating a Verifiable Credential Presentation Request link so that user present the credential and service instantly receives corresponding data to an URL callback.

§ User Agent Display of Trust Resolution

VUAs MUST show a representation of the trust resolution for any connection, with VSs or other VUAs.

§ Credential Wallets

§ Connection Invitation

§ Presentation Request

§ Internationalization

This section is non normative.

It is the responsibility of browsers and search engines to properly translate credential attributes, as credential schemas are always defined in a single language, that SHOULD be english.