Essential Credential Schemas

The Essential Credential Schemas (ECSs), the minimum needed to enable Trust Resolution and the display of a Proof-of-Trust.

Essential Credential Schemas

The Essential Credential Schemas (ECSs), the minimum needed to enable Trust Resolution and the display of a Proof-of-Trust.
Proof-of-Trust.
Proof-of-Trust.

What Are Essential Credential Schemas (ECS)?

Essential Credential Schemas (ECSs) are a special class of credential schemas that play a foundational role in establishing decentralized trust within and across ecosystems.

Defined and governed by a Trust Registry under the control of a network governance authority (such as the Verana Foundation), ECSs represent high-value, widely recognized credential types that ecosystems and services can rely on when making trust decisions.

Each ECS is registered in a Verifiable Public Registry (VPR) and is governed according to the Ecosystem Governance Framework (EGF) of the controlling Trust Registry.

Why ECSs Matter

In a decentralized world where anyone can define and issue credentials, ECSs provide a critical layer of trusted standardization and interoperability:

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?
  • …

There are 4 kinds of ECS:

  • Service;
  • Organization;
  • Person;
  • UserAgent.

Service ECS

Credential subject object of schema MUST contain the following attributes:

  • id (string) (mandatory): the [[ref: 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"
      ]
    }
  }
}

Organization ECS

Credential subject object of schema MUST contain the following attributes:

  • id (string) (mandatory): the [[ref: DID]] of the service the credential has been issued to, which is the subject of the [[ref: 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"
      ]
    }
  }
}

Person ECS

Credential subject object of schema MUST contain the following attributes:

  • id (string) (mandatory): the [[ref: 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"
      ]
    }
  }
}

User Agent ECS

Credential subject object of schema MUST contain the following attributes:

  • id (string) (mandatory): the [[ref: 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"
      ]
    }
  }
}
(Last modified on April 16, 2025)