Verifiable Credentials Data Model 1.0

1.1 What is a Verifiable Credential?

In the physical world, a credential might consist of:

• Information related to the subject of the credential (for example, a photo, name, and identification number)
• Information related to the issuing authority (for example, a city government, national agency, or certification body)
• Evidence related to how the credential was derived
• Information related to expiration dates.

A verifiable credential can represent all of the same information that a physical credential represents. The addition of technologies such as digital signatures makes verifiable credentials more tamper-evident and therefore more trustworthy than their physical counterparts. Holders can generate presentations and share them with verifiers to prove they possess verifiable credentials with certain characteristics. Both credentials and presentations can be rapidly transmitted, making them more convenient than their physical counterparts when establishing trust at a distance.

While this specification attempts to improve upon the ease of expressing digital credentials, it also attempts to balance this goal with a number of privacy-preserving goals. The persistence of digital information, and the ease with which disparate sources of digital data can be collected and correlated, comprise a privacy concern that the use of verifiable and easily machine-readable credentials threatens to make worse. The Privacy Considerations section in this document outlines and attempts to address a number of these issues. Examples of how to use this data model using privacy-enhancing technologies, such as zero-knowledge proofs, are also provided throughout this document.

1.2 Ecosystem Overview

This section outlines a basic set of roles and an ecosystem where verifiable credentials are expected to be useful. In this section, we describe the essential roles of the core actors and the relationships between them; how do they interact? A role is an abstraction that might be implemented in many different ways. The separation of roles suggests likely interfaces and protocols for standardization. The following roles are introduced in this specification:

holder

A role an entity might perform by possessing one or more verifiable credentials and generating presentations from them. Examples of holders include students, employees, and customers.

issuer

A role an entity might perform by creating a verifiable credential, associating it with a specific subject, and transmitting it to a holder. Examples of issuers include corporations, non-profit organizations, trade associations, governments, and individuals.

verifier

A role an entity might perform by requesting and receiving a verifiable presentation that proves the holder possesses the required verifiable credentials with certain characteristics. Examples of verifiers include employers, security personnel, and websites.

verifiable data registry

A role a system may perform by mediating the creation and verification of issuer identifiers, keys and other relevant data like verifiable credential schemas and revocation registries which might be required to use verifiable credentials. Some configurations might require correlatable identifiers for subjects. Examples of such data repositories include trusted databases, decentralized databases, government ID databases, and distributed ledgers. There is often more than one type of verifiable data registry that is utilized in an ecosystem.

1.3 Use Cases and Requirements

The Verifiable Credentials Use Cases [VC-USECASES] document outlines a number of key topics that readers might find useful, including:

• A more thorough explanation of the roles introduced above
• The needs identified in market verticals, such as education, finance, healthcare, retail, professional licensing, and government
• Common tasks performed by the roles in the ecosystem, as well as their associated requirements
• Common sequences and flows identified by the Working Group.

As a result of documenting and analyzing the use cases document, a number of desirable ecosystem characteristics were identified for this specification, specifically:

• Holders receive and store verifiable credentials from issuers. Holders might interact with an issuer through an agent that the issuer does not need to trust.
• Holders are positioned between issuers and verifiers and use verifiable credentials to make verifiable presentations to verifiers.
• Holders might interact with verifiers through an agent that verifiers do not need to trust; verifiers only need to trust issuers.
• Verifiable credentials are associated with subjects, not specific services; holders decide how to aggregate and manage verifiable credentials and the verifiable presentations associated with them.
• Holders can easily acquire and control their identifiers.
• Holders control which verifiable credentials to use and when.
• Holders can freely choose and change the agents they employ to help them manage their verifiable credentials and generate and share verifiable presentations.
• Holders can share verifiable presentations that can be verified without revealing the identity of the verifier to the issuer.
• Holders in presentations can either disclose the attributes or satisfy derived predicates requested by the verifier. Derived predicates are boolean conditions like greater than, less than, equal to, is in set, and so on.
• Verifiable credentials and verifiable presentations are expressed in one or more standard, machine-readable data formats, which can also be extended with minimal coordination.
• Issuers issue verifiable credentials, and holders store them. Holders offer verifiable presentations, and verifiers verify them. Issuing of credentials, storage of credentials, generation of presentations, sharing of presentations, and verification of presentations are each independent processes.
• Verifiable credentials can be revoked by the issuer.

3.1 Claims

A claim is statement about a subject. A subject is an entity about which claims can be made. Claims are expressed using subject-property-value relationships.

The data model for claims described above is powerful and can be used to express a large variety of statements. For example, whether or not someone graduated from a particular university can be expressed as shown below.

These claims can be merged together to express a graph of information about a subject. The example below extends the previous graph of information by adding claims stating that Pat knows Sam and that Sam is employed as a professor.

To this point, the concept of a claim and a graph of information is introduced. To be able to trust claims, more information must be added.

3.2 Credentials

A credential is set of one or more claims made by the same entity. Credentials might include an identifier as well as metadata to describe properties of the credential, such as the issuer, the expiry time, a representative image, a public key to use for verification purposes, the revocation mechanism, and so on. This metadata might be signed by the issuer. A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it.

Examples of verifiable credentials include digital employee identification cards, digital birth certificates, and digital educational certificates.

The example above provides a simple visual describing the components of a verifiable credential, but abstracts some of the details of how claims are organized into graphs, which are then organized into verifiable credentials. The example below attempts to provide a complete visual depiction of a verifiable credential, which is normally composed of at least two graphs of information. The first information graph expresses the credential itself, which contains credential metadata and claims. The second information graph expresses the digital proof, which is typically a digital signature.

3.3 Presentations

Because this specification takes a privacy-first approach, it is important for entities using this technology to be able to express only the portions of their persona that are appropriate for a given situation. The expression of a subset of one's persona is called a verifiable presentation.

A verifiable presentation expresses data from one or more verifiable credentials, and is packaged in such a way that the authorship of the data is verifiable. If credentials are directly presented, they become a presentation. Data formats derived from credentials that are cryptographically verifiable but do not of themselves contain credentials, might also be presentations.

The data in a presentation is often about the same subject, but was issued by multiple issuers. The aggregation of this information typically expresses an aspect of a person, organization, or entity.

Examples of different presentations include a person's professional persona, their online gaming persona, or their home-life persona.

If a presentation supports derived predicates, a claim about birthdate in a credential can become the basis of proof that at a given point in time, the age of a subject did or will fall within a specified interval. Selective disclosure schemes using zero-knowledge proofs can use claims expressed in this model to prove additional statements about those claims. For example, a claim specifying a subject's date of birth can be used as a predicate to prove that the subject's age is within a given range, and therefore prove the subject qualifies for age-related discounts, without actually revealing the subject's birthdate. The holder has the flexibility to use the claim in any way that is applicable to the desired presentation.

5.1 Contexts

When two software systems need to exchange data, they must use terminology and a protocol that both systems understand. As an analogy, consider how two people communicate. Both people must use the same language and the words they use must mean the same thing to each other. This specification uses the @context property to express the context of a conversation.

@context

The value of the @context property MUST be one or more URIs, where the value of the first URI is https://w3.org/2018/credentials/v1. If more than one URI is provided, the URIs MUST be interpreted as an ordered set. It is RECOMMENDED that dereferencing the URIs results in a document containing machine-readable information about the context.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/58473",
  "type": ["VerifiableCredential", "AlumniCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "alumniOf": "Example University"
  },
  "proof": { ... }
}

The example above uses the base context URI (https://w3.org/2018/credentials/v1) to establish that the conversation is about a verifiable credential. The second URI (https://example.com/examples/v1) establishes that the conversation is about examples.

The data available at https://w3.org/2018/credentials/v1 is a static document that is never updated and MAY be downloaded and cached. The associated human-readable vocabulary document for the Verifiable Credentials Data Model is available at: https://w3.org/2018/credentials. This concept is further expanded on in Section 6.1 Extensibility.

5.2 Identifiers

When expressing statements about a specific thing, such as a person, product, or organization, it is often useful to use some kind of identifier so that others can express statements about the same thing. Identifiers that others are expected to use when expressing statements about a specific thing MUST be expressed using the id property.

id

The value of the id property MUST be a single URI. It is RECOMMENDED that dereferencing the URI results in a document containing machine-readable information about the identifier.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "proof": { ... }
}

The example above uses two types of identifiers. The first identifier is for the credential and uses an HTTP-based URL. The second identifier is for the subject of the credential (the thing the claims are about) and uses a Decentralized Identifier, also known as a DID.

5.3 Types

Software systems that process the kinds of objects specified in this document use type information to determine whether or not a provided credential or presentation is appropriate. Type information MUST be expressed using the type property.

type

The value of the type property MUST be, or map to, one or more URIs. If more than one URI is provided, the URIs MUST be interpreted as an unordered set. Syntactic conveniences, such as JSON-LD terms, SHOULD be used to ease developer usage. It is RECOMMENDED that dereferencing the URIs results in a document containing machine-readable information about the type.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "proof": { ... }
}

With respect to this specification, the following table lists the objects that MUST have a type specified.

All credentials, presentations, and encapsulated objects MUST specify, or be associated with, additional more narrow types (like ProofOfAgeCredential, for example) so software systems can process this additional information.

When processing encapsulated objects defined in this specification, (for example, objects associated with the credentialSubject object or deeply nested therein), software systems SHOULD use the type information specified in encapsulating objects higher in the hierarchy. Specifically, an encapsulating object, such as credential, SHOULD convey the associated object types so that verifiers can quickly determine the contents of an associated object based on the encapsulating object type. For example, a credential object with the type of ProofOfAgeCredential, would signal to a verifier that the object associated with the credentialSubject property contains the identifier for the subject in the id property, and the age assertion in the ageOver property. This enables implementers to rely on values associated with the type property for verification purposes. The expectation of types and their associated properties SHOULD be documented in at least a human-readable specification, and preferably, in an additional machine-readable representation.

5.4 Issuer

Issuer information can be expressed using the following properties:

issuer

The value of the issuer property MUST be a URI. It is RECOMMENDED that dereferencing the URI results in a document containing machine-readable information about the issuer that can be used to verify the information expressed in the credential.

issuanceDate

The value of the issuanceDate property MUST be a string value of an [ISO8601] combined date and time string representing the date and time the credential was issued. Note that this date represents the earliest date when the information associated with the credentialSubject property became valid.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "proof": { ... }
}

5.5 Proofs (Signatures)

For a credential or presentation to be verifiable, the following property MUST be present:

proof

The method used for a mathematical proof varies by representation language and the technology used. For example, if digital signatures are used for the proof mechanism, the proof property is expected to have a value that is a set of name-value pairs including at least a signature, a reference to the signing entity, and a representation of the signing date.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu",
  "issuanceDate": "2010-01-01",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "proof": {
    "type": "RsaSignature2018",
    "created": "2017-06-18T21:19:10Z",
    "creator": "https://example.com/jdoe/keys/1",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
      MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
      PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
      +W3JT24="
  }
}

5.6 Expiration

Expiration information for a credential MAY be provided by adding the following property:

expirationDate

The value of the expirationDate property MUST be a string value of an [ISO8601] combined date and time string representing the date and time the credential ceases to be valid.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "expirationDate": "2020-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "proof": { ... }
}

5.7 Status

Information about the current status of a verifiable credential, such as whether it is suspended or revoked, MAY be provided using the credentialStatus property.

credentialStatus

If specified, the value of the credentialStatus property MUST include the:

• Credential status type (also referred to as the credential status scheme), which MUST provide enough information to determine the current status of the credential (for example, suspended or revoked).
• id of the status type instance.

The precise contents of the credential status information is determined by the specific credentialStatus type definition, and varies depending on factors such as whether it is simple to implement or if it is privacy-enhancing.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "credentialStatus": {
    "id": "https://example.edu/status/24,
    "type": "CredentialStatusList2017"
  },
  "proof": { ... }
}

Defining the data model, formats, and protocols for status schemes are out of scope for this specification. A status scheme registry [VC-STATUS-REGISTRY] exists for implementers who want to implement credential status checking.

5.8 Presentations

Verifiable presentations MAY be used to combine and present verifiable credentials.

If verifiable presentations are used, they MUST be constructed from verifiable credentials themselves, or of data derived from verifiable credentials in a cryptographically verifiable format.

The example below shows a verifiable presentation that embeds verifiable credentials.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [{ ... }],
  "proof": [{ ... }]
}

The contents of the verifiableCredential property shown above are verifiable credentials as described by this specification. The contents of the proof property are proofs as described by the Linked Data Proofs [LD-PROOFS] specification. The id property is optional and MAY be used to provide a unique identifier for the presentation. The value associated with the id property MUST be a URI.

Some zero-knowledge cryptography schemes might enable holders to indirectly prove they hold a credential without revealing the credential itself. In these schemes, the original attribute, such as date of birth, might be translated into another value, such as "over the age of 15", which is cryptographically asserted such that a verifier can trust the value if they trust the issuer.

6.1 Extensibility

One of the goals of the Verifiable Credentials Data Model is to enable permissionless innovation. To achieve this, the data model need to be extensible in a number of different ways. The data model is required to:

• Model complex multi-entity relationships through the use of a graph-based data model.
• Extend the machine-readable vocabularies used to describe information in the data model without the use of a centralized system for doing so through the use of [LINKED-DATA].
• Support multiple types of cryptographic proof formats through the use of Linked Data Proofs [LD-PROOFS], Linked Data Signatures [LD-SIGNATURES], and a variety of signature suites.
• Provide all of the extensibility mechanisms outlined above in a data format that is popular with software developers and web page authors, and is enabled through the use of [JSON-LD].

This approach to data modelling is often called an "open world assumption", meaning that any entity can say anything about any other entity. While this approach seems to conflict with building simple and predictable software systems, balancing extensibility with program correctness is always more challenging with an open world assumption than with closed software systems.

The rest of this section describes, through a series of examples, how both extensibility and program correctness are achieved.

Let us assume that we start with the following verifiable credential:

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.com/credentials/4643",
  "type": ["VerifiableCredential"],
  "issuer": "https://example.com/issuers/14",
  "issuanceDate": "2018-02-24T05:28:04Z",
  "credentialSubject": {
    "id": "did:example:abcdef1234567",
    "name": "Jane Doe"
  },
  "proof": { ... }
}

The verifiable credential above states that the entity associated with did:example:abcdef1234567 has a name with a value of Jane Doe.

Now let us assume that a developer wants to extend the verifiable credential to store two additional pieces of information: an internal corporate reference number, and Jane's favorite food.

The first thing to do is to create a JSON-LD Context containing two new terms:

{
  "@context": {
    "referenceNumber": "https://example.com/vocab#referenceNumber",
    "favoriteFood": "https://example.com/vocab#favoriteFood"
  }
}

After the JSON-LD Context is created, the developer must publish it somewhere so it is accessible to verifiers who will be processing the verifiable credential. Assuming the above JSON-LD Context is published at https://example.com/contexts/mycontext.jsonld, we can extend this example by including the context and adding the new properties to the verifiable credential:

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/contexts/mycontext.jsonld"
  ],
  "id": "http://example.com/credentials/4643",
  "type": ["VerifiableCredential"],
  "issuer": "https://example.com/issuers/14",
  "issuanceDate": "2018-02-24T05:28:04Z",
  "referenceNumber": 83294847,
  "credentialSubject": {
    "id": "did:example:abcdef1234567",
    "name": "Jane Doe",
    "favoriteFood": "Papaya"
  },
  "proof": { ... }
}

This example demonstrates that it is possible to extend the Verifiable Credentials Data Model in a permissionless and decentralized way. The mechanism shown also ensures that verifiable credentials created in this way provide a mechanism to prevent namespace conflicts and semantic ambiguity.

A dynamic extensibility model such as this does increase the implementation burden. Software written for such a system has to determine whether verifiable credentials with extensions are acceptable based on the risk profile of the application. Some applications might accept only certain extensions while highly secure environments might not accept any extensions. These decisions are up to the developers of these applications and are specifically not the domain of this specification.

Applications that do not understand the semantic meaning of all properties while processing a verifiable credential or a verifiable presentation MUST produce an error.

Developers are urged to ensure that extension JSON-LD Contexts are highly available. Implementations that cannot fetch a context will produce an error. Strategies for ensuring that extension JSON-LD Contexts are always available include using content-addressed URLs for contexts, bundling context documents with implementations, or enabling aggressive caching of contexts.

{
  "@context": {
    "referenceNumber": "https://example.com/vocab#referenceNumber",
    "credentialSubject": {
      "@id": "https://w3.org/2018/credentials#credentialSubject",
      "@context": {
        "favoriteFood": "https://example.com/vocab#favoriteFood"
      }
    }
  }
}

6.2 Data Schemas

Data schemas are often useful when enforcing a particular structure on a given collection of data. There are at least two types of data schemas that this specification contemplates. The first are data verification schemas, which are used to verify that the structure and contents of a verifiable credential are conformant to a published schema. The second are data encoding schemas, which are used to map the contents of a verifiable credential to an alternative representation format such as a binary format used in a zero-knowledge proof.

The expression of a data schema may be performed via the following property:

credentialSchema

The value of this property MUST be one or more data schemas that provide verifiers with enough information to determine if the provided data is conformant to the provided schema. Each credentialSchema comprises at least its type (e.g. JsonSchemaValidator2018), and an id property that MUST be a URI identifying the schema file. The precise contents of each data schema is determined by the specific type definition.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "credentialSchema": {
    "id": "https://example.org/motorlicense/proof-of-age.json",
    "type": "JsonSchemaValidator2018"
  },
  "proof": { ... }
}

In the example above, the issuer is specifying a credentialSchema that points to a JSON Schema file that can be used by a verifier to determine if the verifiable credential is well formed.

Data schemas can also be used to specify mappings to other binary formats, such as those used to perform zero-knowledge proofs.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "credentialSchema": {
    "id": "https://example.org/motorlicense/proof-of-age.zkp",
    "type": "ZkpExampleSchema2018"
  },
  "proof": { ... }
}

In the example above, the issuer is specifying a credentialSchema that points to a zero-knowledge packed binary data format that is capable of transforming the input data into a format that can then be used by a verifier to determine if the proof provided with the verifiable credential is valid.

6.3 Refreshing

It is often useful for systems to enable the manual or automatic refresh of a expired verifiable credential. This specification enables an issuer to include a link to a refresh service.

The issuer can include the refresh service as an element inside the verifiable credential if it is intended for either the verifier or the holder (or both), or inside the verifiable presentation if it is intended for the holder only.

Including the refresh reference inside the verifiable presentation enables the holder to refresh the credential details before creating a presentation to share with a verifier, while including the refresh reference inside the verifiable credential enables both the holder and the verifier to perform future updates of the credential.

A refresh service can be expressed using the following property:

refreshService

The value of the refreshService property MUST be one or more refresh services that provides enough information to the holder's software such that the holder can refresh the credential. Each refreshService property comprises at least its type (for example, ManualRefreshService2018) and the serviceEndpoint URL. The precise content of each refresh service is determined by the specific refreshService type definition.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "refreshService": {
    "type": "ManualRefreshService2018",
    "serviceEndpoint": "https://example.edu/refresh/283947"
  },
  "proof": { ... }
}

In the example above, the issuer specifies a manual refreshService that can be used by directing the holder to https://dmv.example.gov/refresh/283947.

6.4 Mode of Operation

Section 1.2 Ecosystem Overview provided an overview of the verifiable credential ecosystem. A more detailed look at the way the eco-system is envisaged to operate is as follows.

Note that the following ordering of steps is not fixed and some steps may be repeated multiple times.

• Step 1. The verifier defines its policies for accepting verifiable credentials from holders for its supported actions.
• Step 2. The issuer issues a verifiable credential to the holder.
• Step 3. The holder MAY pass on its verifiable credentials to another holder.
• Step 4. The final holder presents its verifiable credentials to the verifier in a verifiable presentation, requesting a supported action.
• Step 5. The verifier verifies the authenticity of the verifiable presentation and verifiable credentials.
• Step 6. The verifier verifies that the holder may posses the verifiable credentials.
• Step 7. The verifier determines whether to accept the verifiable credentials for the requested action, taking into account its policy, the holder, and the contents of the verifiable credentials.
• Step 8. The verifier either performs the requested action or rejects the request.

This specification does not define any protocol for the transfer of verifiable credentials or verifiable presentations, but assuming that other specifications do specify how they are transferred between the various entities, then:

• This verifiable credentials specification is directly applicable to steps 2, 3, 4, 5 and 6.
• This verifiable credentials specification is not sufficient on its own for steps 1, 7, and 8 as an authorisation framework will be needed as well.

In particular, Section 6.5 Terms of Use and Section 6.7 Subject-Holder Relationships specify how a verifier can determine whether:

• the holder is the subject of a verifiable credential,
• the relationship between the subject and the holder,
• the original holder passed a verifiable credential to a subsequent holder,
• any restrictions on the use of the verifiable credentials by the holder and/or verifier.

6.5 Terms of Use

Terms of use can be used by an issuer, a subject, or a holder to constrain the use of information expressed by the Verifiable Credentials Data Model. The issuer places their terms of use inside the credential before it is converted into a verifiable credential. The holder places holder terms of use inside a presentation.

Terms of use can be expressed using the following property:

termsOfUse

The value of the termsOfUse property MUST be one or more terms of use telling a verifier what actions it MUST perform (Obligations), MUST NOT perform (Prohibitions), or MAY perform (Permissions) if it is to accept the verifiable credential or verifiable presentation. If a verifier is not willing to accept these terms of use, it MUST reject the verifiable credential or verifiable presentation. Each termsOfUse property comprises its type (for example, IssuerPolicy) and optionally its instance id. The precise content of each term of use is determined by the specific TermsOfUse type definition.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "termsOfUse": [{
    "type": "IssuerPolicy",
    "id": "http://example.com/policies/credential/4",
    "profile": "http://example.com/profiles/credential",
    "prohibition": [{
      "assigner": "https://example.edu/issuers/14",
      "assignee": "AllVerifiers",
      "target": "http://example.edu/credentials/3732",
      "action": ["Archival"]
    }]
  },
  "proof": { ... }
}

In the example above, the issuer is prohibiting verifiers from storing the data in an archive.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "type": "VerifiablePresentation",
  "verifiableCredential": [{
    "id": "http://example.edu/credentials/3732",
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "https://example.edu/issuers/14",
    "issuanceDate": "2010-01-01T19:73:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
    },
    "proof": { ... }
  }],
  "termsOfUse": [{
    "type": "HolderPolicy",
    "id": "http://example.com/policies/credential/6",
    "profile": "http://example.com/profiles/credential",
    "prohibition": [{
      "assigner": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "assignee": "https://wineonline.example.org/",
      "target": "http://example.edu/credentials/3732",
      "action": ["3rdPartyCorrelation"]
    }]
  },
  "proof": [ ... ]
}

In the example above, the holder, who is also the subject, is prohibiting a specific verifier (https://wineonline.example.org) from using the information provided to correlate the holder with the subject using a third-party service.

6.6 Evidence

Evidence information is used by an issuer to determine whether to issue a credential. For example, an issuer might check physical documentation provided by a subject or perform a set of background checks before issuing a credential. In some situations, this information is useful to the verifier when determining the risk associated with accepting the credential.

Evidence information can be expressed using the following property:

evidence

The value of the evidence property MUST be one or more evidence schemes providing enough information to a verifier to determine whether the evidence gathered meets their requirements. The precise content of each evidence scheme is determined by the specific evidence type definition.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "evidence": [{
    "id": "https://example.edu/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231",
    "type": ["DocumentVerification"],
    "verifier": "https://example.edu/issuers/14",
    "evidenceDocument": "DriversLicense",
    "subjectPresence": "Physical",
    "documentPresence": "Physical"
  }],
  "proof": { ... }
}

6.7 Subject-Holder Relationships

This section describes the possible relationships between a subject and a holder and how the Verifiable Claims Data Model expresses these relationships. The following diagram illustrates the different types of relationships covered in the rest of this section.

The following sections describe how each of these relationships are handled in the data model.

{
  "@context": ["https://w3.org/2018/credentials/v1", "https://schema.org/"]
  "id": "http://example.edu/credentials/332",
  "type": ["VerifiableCredential", "IdentityCredential"],
  "issuer": "https://example.edu/issuers/4",
  "issued": "2017-02-24",
  "credentialSubject": {
    "name": "J. Doe",
    "address": {
      "streetAddress": "10 Rue de Chose",
      "postalCode": "98052",
      "addressLocality": "Paris",
      "addressCountry": "FR"
    },
    "birthDate": "1989-03-15"
    ...
  },
  "proof": { ... }
}

{
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "termsOfUse": [{
    "type": "SubjectOnly",
    }]
  },
  "proof": { ... }
}

{
  "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [{
      "id": "http://example.gov/credentials/3732",
      "type": ["VerifiableCredential", "PrescriptionCredential"],
      "issuer": "https://example.edu",
      "issued": "2010-01-01",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "prescription": {....}
      },
      "revocation": {
        "id": "http://example.gov/revocations/738",
        "type": "SimpleRevocationList2017"
      },
      "proof": {....}
    },
    {
      "id": "https://example.com/VC/123456789",
      "type": ["VerifiableCredential", "PrescriptionCredential"],
      "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "issued": "2010-01-03",
      "credentialSubject": {
        "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
        "prescription": {....}
      },
      "proof": {
        "type": "RsaSignature2018",
        "created": "2017-06-17T10:03:48Z",
        "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234",
        "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
        "signatureValue": "pYw8XNi1..Cky6Ed = "
      }
    }
  ],
  "proof": [{
    "type": "RsaSignature2018",
    "created": "2017-06-18T21:19:10Z",
    "creator": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1..W3JT24 = "
  }]
}

{
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential", "RelationshipCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageUnder": 16,
    "parent": {
      "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
      "type": "Mother"
    }
  },
  "proof": { ... } // the proof is generated by the DMV
}

{
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "RelationshipCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
    "child": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "type": ["Person", "Child"]
    }
  },
  "proof": { ... } // the proof is generated by the DMV
}

{
  "id": "http://example.org/credentials/23894",
  "type": ["VerifiableCredential", "RelationshipCredential"],
  "issuer": "http://example.org/credentials/23894",
  "issued": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "parent": {
      "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
      "type": "Mother"
    }
  },
  "proof": { ... } // the proof is generated by the child
}

{
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "NameAndAddress"],
  "issuer": "https://example.edu/issuers/14",
  "holder": {
    "type": "LawEnforcement",
    "id": "did:example:ebfeb1276e12ec21f712ebc6f1c"
  },
  "issued": "2010-01-01",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "Mr John Doe",
    "address": "10 Some Street, Anytown, ThisLocal, Country X"
  },
  "proof": {
    "type": "RsaSignature2018",
    "created": "2017-06-17T10:03:48Z",
    "creator": "https://example.edu/issuers/14/keys/234",
    "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
    "signatureValue": "pY9...Cky6Ed = "
  }
}

6.8 Disputes

There are at least two different cases to consider for an entity wanting to dispute a credential issued by an issuer:

• A subject disputes a claim made by the issuer. For example, the address property is out of date.
• An entity disputes a potentially false claim made by the issuer about a different subject. For example, an imposter claims the social security number for an entity.

Only the subject of a verifiable credential is entitled to issue a DisputeCredential. A DisputeCredential issued by anyone other than the subject SHOULD be disregarded by the verifier, unless the verifier has some other way of determining the truth of the dispute. This is to prevent denial of service attacks whereby an attacker falsely disputes a true claim.

The mechanism for issuing a DisputeCredentialis the same as issuing a regular credential except that the credentialSubject identifier in the DisputeCredential property is the identifier of the disputed credential. For example, if a credential with an identifier of https://example.org/credentials/245 is disputed, an entity can issue one of the following credentials. In the first example, the subject might present this to the verifier along with the disputed credential. In the second example, the entity might publish the DisputeCredential in a public venue to make it known that the credential is disputed.

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.com/credentials/123",
  "type": ["VerifiableCredential", "DisputeCredential"],
  "credentialSubject": {
    "id": "http://example.com/credentials/245",
    "currentStatus": "Disputed",
    "statusReason": "Address is out of date"
  },
  "issuer": "https://example.com/people#me",
  "issuanceDate": "2017-12-05T14:27:42Z",
  "proof": { ... }
}

{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://example.com/credentials/321",
  "type": ["VerifiableCredential", "DisputeCredential"],
  "credentialSubject": {
    "id": "http://example.com/credentials/245",
    "currentStatus": "Disputed",
    "statusReason": "Credential contains disputed statements",
    "disputedClaim": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
    }
  },
  "issuer": "https://example.com/people#me",
  "issuanceDate": "2017-12-05T14:27:42Z",
  "proof": { ... }
}

6.9 Authorization

Verifiable credentials are intended as a means of reliably identifying subjects. While it is recognized that Role Based Access Controls (RBAC) and Attribute Based Access Controls (ABAC) rely on this identification as a means of authorizing subjects to access resources, this specification MUST NOT be used for authorization purposes without an accompanying authorization framework.

The Working Group did consider authorization use cases during the creation of this specification and is pursuing that work as an architectural layer built on top of this specification.

6.10 Syntactic Sugar

In general, the data model and syntaxes described in this document are designed such that developers can copy and paste examples to incorporate verifiable credentials into their software systems. The design goal of this approach is to provide a low barrier to entry while still ensuring global interoperability between a heterogenous set of software systems. This section describes some of these approaches, which will most likely go unnoticed by most developers, but whose details will be of interest to implementers. The most noteworthy syntactic sugars used throughout the ecosystem are as follows:

• If processed using a JSON-LD processor:
  • The @id and @type keywords are aliased to id and type respectively, enabling developers to use this specification as idiomatic JSON.
  • Data types, such as integers, dates, units of measure, and URLs, are automatically typed to provide stronger type guarantees for use cases that require them.
  • The verifiableCredential and proof properties are treated as graph containers. That is, mechanisms used to isolate sets of data asserted by different entities. This ensures, for example, proper cryptographic separation between the data graph provided by each issuer and the one provided by the holder presenting the verifiable credential to ensure the provenance of the information for each graph is preserved.

6.11 Conformance

A concrete expression of the data model in this specification is a conforming document if it complies with the normative statements in this specification regarding syntax. That is, the content in the Basic Concepts, Advanced Concepts, and Syntaxes sections of this document. For convenience, normative statements for conforming documents are often phrased as statements on the syntax used in properties and their associated values in the document (for example, "MUST be a URI", or "MUST be a string value of an ISO8601 combined date and time string").

A conforming processor is a software or hardware-based implementation of the normative statements in this specification regarding the expected contents of property-value pairs (for example, the content in Verification). For convenience, normative statements for conforming processors are often phrased as behavioral statements regarding the contents of property-value pairs (for example, "MUST NOT be revoked", or "MUST be in the expected range").

7.1 JSON

The data model as described in Section 3. Core Data Model can be encoded in Javascript Object Notation (JSON) [RFC8259] by mapping property values to JSON types as follows:

• Numeric values representable as IEEE754 SHOULD be represented as a Number type.
• Boolean values SHOULD be represented as a Boolean type.
• Sequence value SHOULD be represented as an Array type.
• Unordered sets of values SHOULD be represented as an Array type.
• Sets of properties SHOULD be represented as an Object type.
• Empty values SHOULD be represented as a null value.
• Other values MUST be represented as a String type.

7.2 JSON-LD

[JSON-LD] is a JSON-based format used to serialize Linked Data. The syntax is designed to easily integrate into deployed systems already using JSON, and provides a smooth upgrade path from JSON to JSON-LD. It is primarily intended to be a way to use Linked Data in Web-based programming environments, to build interoperable Web services, and to store Linked Data in JSON-based storage engines.

JSON-LD is useful when extending the data model described in this specification. Instances of the data model are encoded in JSON-LD in the same way they are encoded in JSON (Section 7.1 JSON), with the addition of the @context property. The JSON-LD Context is described in detail in the [JSON-LD] specification and its use is elaborated on in Section 6.1 Extensibility.

Multiple contexts MAY be used or combined to express any arbitrary information about credentials in idiomatic JSON. If an application is processing a verifiable credential or verifiable presentation, and a @context property is not present at the top-level of the JSON-LD document, then a @context property with a value of https://w3.org/2018/credentials/v1 MUST be assumed. The JSON-LD Context available at https://w3.org/2018/credentials/v1 is a static document that is never updated and can therefore be downloaded and cached client side. The associated vocabulary document for the Verifiable Credentials Data Model is available at https://w3.org/2018/credentials.

7.3 JSON Web Token

JSON Web Token (JWT) [RFC7519] is still a widely used means to express claims to be transferred between two parties. Providing a representation of the verifiable credentials data model for JWT will allow existing systems and libraries to participate in the ecosystem as described in Section 1.2 Ecosystem Overview. A JWT encodes a set of claims as a JSON object that is contained in a JSON Web Signature (JWS) [RFC7515] and/or JWE [RFC7516]. For this specification, the use of JWE is out of scope.

{
    "alg": "RS256",
    "typ": "JWT",
    "kid": "did:example:abfe13f712120431c276e12ecab#keys-1"
}

{
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "jti": "http://example.edu/credentials/3732",
  "iss": "did:example:abfe13f712120431c276e12ecab",
  "iat": "1541493724",
  "exp": "1573029723",
  "nonce": "660!6345FSer",
  "vc": {
    "@context": [
      "https://w3.org/2018/credentials/v1",
      "https://example.com/examples/v1"
    ],
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "credentialSubject": {
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science in Mechanical Engineering"
        }
    }
  }
}

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1"
}

{
  "iss": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "aud": "did:example:4a57546973436f6f6c4a4a57573",
  "iat": "1541493724",
  "exp": "1573029723",
  "nonce": "343s$FSFDa-",
  "vp": {
    "@context": [
      "https://w3.org/2018/credentials/v1",
      "https://example.com/examples/v1"
    ],
    "type": ["VerifiablePresentation"],
    // base64url-encoded JWT as string
    "verifiableCredential": ["..."]
  }
}

8.1 Syntax

The document is syntactically valid. For example, syntactically valid JSON or JSON-LD.

8.2 Credential

Required properties MUST be present. For example, for a verifiable credential, type, and proof properties are required.

Property values MUST match expectations described in this specification. For example, the document type property for a verifiable credential MUST contain the VerifiableCredential class.

8.3 Issuer

The value associated with the issuer property MUST identify an issuer that is known to and trusted by the verifier.

Pertinent metadata about the issuer MUST be available to the verifier. For example, an issuer can publish information containing the public keys it uses to digitally sign verifiable credentials that it has issued. This metadata is pertinent when checking the proofs on the verifiable credential.

8.4 Subject

The value associated with the id property for each credentialSubject MUST identify a subject to the verifier. For example, if a subject is identified and the verifier has public key metadata related to the subject that is used for authentication purposes, the verifier MAY be able to authenticate the subject using a signature generated by the subject contained in the verifiable presentation.

8.5 Proofs (Signatures)

The cryptographic mechanism used to prove that the information in a verifiable credential or a verifiable presentation has not been tampered with is called a proof. There are many types of cryptographic proofs including, but not limited to, digital signatures, zero-knowledge proofs, proofs of work, and proofs of stake. In general, when verifying proofs implementations MUST ensure that:

• The proof is available in the form of a known proof suite.
• All required proof suite properties are present.
• The proof suite verification agorithm, when applied to the data, results in an acceptable proof.

Some proofs are digital signatures. In general, when verifying digital signatures, implementations MUST ensure that:

• Acceptably recent metadata regarding the public key associated with the signature is available. For example, the metadata might include properties related to expiration, key owner, or key purpose.
• The key MUST NOT be revoked or expired.
• The cryptographic signature MUST verify.
• If the cryptographic suite expects a proofPurpose, it MUST exist and be a valid value (such as credentialIssuance) as per the cryptographic suite.

8.6 Issuance

The issuanceDate MUST be within an expected range for the verifier. For example, a verifier can ensure that the issuance date of a verifiable credential is not in the future.

8.7 Expiration

The expirationDate MUST be within an expected range for the verifier. For example, a verifier can ensure that the expiration date of a verifiable credential is not in the past.

8.8 Revocation

If revocation instructions are present, the credential MUST NOT have been revoked.

8.9 Fitness for Purpose

Custom properties in the credential are appropriate for the purpose of the verifier. For example, if a verifier needs to determine if a subject is older than 21 years of age, they might accept claims of specific birthdate or abstract properties such as ageOver.

The issuer is trusted by the verifier to make the claims at hand. For example, a franchised fast food restaurant location will trust discount coupon claims made by the corporate headquarters of the franchise.

All policy information expressed by an issuer in a verifiable credential MUST be enforced unless verifiers accept the risk of not enforcing the policy information. For example, an issuer might limit the use of a credential to specific verifiers, to holders within a specific age range, or between specific dates.

All policy information expressed by a holder in a verifiable presentation MUST be enforced unless verifiers accept the risk of not enforcing the policy information. For example, a holder might limit the use of a credential to specific verifiers or for specific purposes (such as authentication, but not data mining).

9.1 Data First Approaches

Many physical credentials in use today, such as government identification cards, have poor accessibility characteristics, including, but not limited to, small print, reliance on small and high-resolution images, and no affordances for people with vision impairments.

When utilizing this data model to create verifiable credentials, it is suggested that data model designers use a "data first" approach. For example, given the choice of using data or a graphical image to depict a credential, designers should choose to express every element of the image, such as the name of an institution or the professional credential, in a machine readable way instead of just relying on the image to convey this information. This "data first" approach is preferred because it provides the foundational elements of building different interfaces for people with varying abilities.

10.1 Spectrum of Privacy

It is important to recognize there is a spectrum of privacy ranging from pseudonymous to strongly identified. Depending on the use case, people have different comfort levels about what information they are willing to provide and what information can be derived from what is provided.

For example, most people probably want to remain anonymous when purchasing alcohol because the regulatory check required is solely based on whether a person is above a specific age. Alternatively, for medical prescriptions written by a doctor for a patient, the pharmacy fulfilling the prescription is required to more strongly identify the medical professional. Therefore there is not one approach to privacy that works for all use cases. Privacy solutions are use case specific.

The Verifiable Credentials Data Model strives to support the full privacy spectrum and does not take philosophical positions on the correct level of anonymity for any specific transaction. The following sections provide guidance for implementers who want to avoid specific scenarios that are hostile to privacy.

10.2 Personally Identifiable Information

Data associated with verifiable credentials stored in the credential.credentialSubject field is susceptible to privacy violations when shared with verifiers. Personally identifying data, such as a government-issued identifier, shipping address, and full name, can be easily used to determine, track, and correlate an entity. Even information that does not seem personally identifiable, such as the combination of a birth date and a postal code, has very powerful correlation and de-anonymizing capabilities.

Implementers are strongly advised to warn holders when they share data with these kinds of characteristics. Issuers are strongly advised to provide privacy-protecting credentials when possible. For example, issuing ageOver credentials instead of date of birth credentials when a verifier wants to determine if an entity is over the age of 18.

10.3 Identifier-Based Correlation

Subjects of verifiable credentials are identified using the credential.credentialSubject.id field. The identifiers used to identify a subject create a greater risk of correlation when the identifiers are long-lived or used across more than one web domain.

If strong anti-correlation properties are a requirement in a verifiable credentials system, it is strongly advised that identifiers are either:

• Bound to a single origin
• Single-use
• Not used at all, but instead replaced by short-lived, single-use bearer tokens.

10.4 Signature-Based Correlation

The contents of verifiable credentials are secured using the credential.proof field. The properties in this field create a greater risk of correlation when the same values are used across more than one session or domain and the value does not change. Examples include the creator, created, domain (for very specific domains), nonce, and signatureValue fields.

If strong anti-correlation properties are required, it is advised that signature values and metadata are regenerated each time using technologies like third-party pairwise signatures, zero-knowledge proofs, or group signatures.

10.5 Long Lived Identifier-Based Correlation

Verifiable credentials might contain long-lived identifiers that could be used to correlate individuals. These types of identifiers include subject identifiers, email addresses, government-issued identifiers, organization-issued identifiers, addresses, healthcare vitals, credential-specific JSON-LD contexts, and many other sorts of long-lived identifiers.

Organizations providing software to holders should strive to identify fields in credentials containing information that could be used to correlate individuals and warn holders when this information is shared.

10.6 Device Fingerprinting

There are mechanisms external to verifiable credentials that are used to track and correlate individuals on the Internet and the Web. Some of these mechanisms include Internet protocol (IP) address tracking, web browser fingerprinting, evercookies, advertising network trackers, mobile network position information, and in-application Global Positioning System (GPS) APIs. Using verifiable credentials cannot prevent the use of these other tracking technologies. Also, when these technologies are used in conjunction with verifiable credentials, new correlatable information could be discovered. For example, a birthday coupled with a GPS position can be used to strongly correlate an individual across multiple websites.

It is recommended that privacy-respecting systems prevent the use of these other tracking technologies when verifiable credentials are being used. In some cases, tracking technologies might need to be disabled on devices that transmit verifiable credentials on behalf of a holder.

10.7 Favor Abstract Claims

To enable recipients of verifiable credentials to use them in a variety of circumstances without revealing more personally identifiable information than necessary for transactions, issuers should consider limiting the information published in a credential to a minimal set needed for the expected purposes. One way to avoid placing personally identifiable information in a credential is to use an "abstract" property that meets the needs of verifiers without providing specific information about a subject.

For example, this document uses the ageOver property instead of a specific birthdate, which constitutes much stronger personally identifiable information. If retailers in a specific market commonly require purchasers to be older than a certain age, an issuer trusted in that market might choose to offer a credential claiming that subjects have met that requirement instead of offering credentials containing claims about specific birthdates. This enables individual customers to make purchases without revealing specific personally identifiable information.

10.8 The Principle of Minimum Disclosure

Privacy violations occur when information divulged in one context leaks into another. Accepted best practice for preventing such violations is to limit the information requested, and received, to the absolute minimum necessary. This minimum disclosure approach is required by regulation in multiple jurisdictions, including the Health Insurance Portability and Accountability Act (HIPAA) in the United States and the General Data Protection Regulation (GDPR) in the European Union.

With verifiable credentials, minimal disclosure for issuers means limiting the content of a credential to the minimum required by potential verifiers for expected use. For verifiers, minimal disclosure means limiting the scope of the information requested or required for accessing services.

For example, a driver's license containing a driver's ID number, height, weight, birthday, and home address is a credential containing more information than is necessary to establish that the person is above a certain age.

It is considered best practice for issuers to atomize information or use a signature scheme that allows for selective disclosure. For example, an issuer of driver's licenses could issue a set of credentials containing every attribute that appears on a driver's license, as well as atomized credentials (for example, a credential containing only a person's birthday), and more abstract atomized credentials (for example, a credential containing only an ageOver attribute). One possible adaptation would be for issuers to provide secure HTTP endpoints for retrieving single-use bearer credentials that promote the pseudonymous usage of credentials. Implementers that find this impractical or unsafe, should consider using selective disclosure schemes that eliminate dependence on issuers at proving time and reduce temporal correlation risk from issuers.

Verifiers are urged to only request information that is absolutely necessary for a specific transaction to occur. This is important for at least two reasons. It:

• Reduces the liability on the verifier for handling highly sensitive information that it does not need to.
• Enhances the privacy of the individual by only asking for information required for a specific transaction.

10.9 Bearer Credentials

A bearer credential is a privacy-enhancing piece of information, such as a concert ticket, which entitles the holder of the credential to a specific resource without divulging sensitive information about the holder.

Verifiable credentials that are bearer credentials are made possible by not specifying the subject identifier, expressed using the id property, which is nested in the credentialSubject property. For example, the following verifiable credential is a bearer credential:

{
  "@context": [
    "https://w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/temporary/28934792387492384",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2017-10-22T12:23:48Z",
  "credentialSubject": {
    // note that the 'id' property is not specified for bearer credentials
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "proof": { ... }
}

While bearer credentials can be privacy-enhancing, they must be carefully crafted so as not accidentally divulge more information than the holder of the credential expects. For example, repeated use of the same bearer credential across multiple sites enables these sites to potentially collude to unduly track or correlate the holder. Likewise, information that might seem non-identifying, such as a birthdate and postal code, can be used to statistically identify an individual when used together in the same credential or session.

Issuers of bearer credentials SHOULD ensure that bearer credentials that are expected to provide privacy-enhancing benefits that:

• Are single-use, where possible
• Do not contain personally identifying information
• Are not unduly correlatable.

Holders SHOULD be warned by their software if bearer credentials containing sensitive information are issued or requested, or if there is a correlation risk when combining two or more bearer credentials across one or more sessions. While it might be impossible to detect all correlation risks, some might certainly be detectable.

Verifiers SHOULD NOT request bearer credentials that can be used to unduly correlate the user.

10.10 Validity Checks

When processing verifiable credentials, verifiers typically perform many of the checks listed in Section 8. Verification as well as a variety of business process-specific checks. For example, validity checks might include checking:

• The professional licensure status of the holder.
• A date of license renewal or revocation.
• Sub-qualifications of an individual.
• A relationship exists between the holder and the entity with whom the holder is attempting to interact.
• The geolocation information associated with the holder.

The process of performing these checks might result in information leakage that leads to a privacy violation of the holder. For example, a simple operation like checking a revocation list can notify the issuer that a specific business is likely interacting with the holder. This could enable issuers to collude and correlate individuals without their knowledge.

Issuers are urged to not use mechanisms, such as credential revocation lists that are unique per credential, during the verification process, which could lead to privacy violations. Organizations providing software to holders should warn when credentials include information that could lead to privacy violations during the verification process. Verifiers should consider rejecting credentials that produce privacy violations or that enable bad privacy practices.

10.11 Storage Providers and Data Mining

When a holder receives a credential from an issuer, the credential needs to be stored somewhere (for example, in a credential repository). Holders are warned that the information in a verifiable credential is sensitive in nature and highly individualized, making it a high value target for data mining. Services that advertise free storage of verifiable credentials might in fact be mining personal data and selling it to organizations wanting to build individualized profiles on people and organizations.

Holders need to be aware of the terms of service for their credential repository, specifically the correlation and data mining protections in place for those who store their verifiable credentials with the service provider.

The following are some effective mitigations for data mining and profiling:

• Use service providers that do not sell your information to third parties.
• Use software that encrypts verifiable credentials such that a service provider cannot view the contents of the credential.
• Use software that stores verifiable credentials locally on a device that you control and that does not upload or analyze your information beyond your expectations.

10.12 Aggregation of Credentials

Two pieces of information about the same subject almost always reveals more about the subject than just a single piece of information, even when delivered through different channels. The aggregation of credentials is a privacy risk and all participants in the ecosystem need to be aware of the risks of data aggregation.

For example, if two bearer credentials, one for an email address and then one stating the holder is over the age of 21, are provided across multiple sessions, the verifier of the information now has a unique identifier plus age-related information for the individual. It is now easy to create and build a profile for the holder such that more and more information is leaked over time. Aggregation of credentials can also be performed across multiple sites in collusion with each other, leading to privacy violations.

From a technological perspective, preventing the aggregation of information is a very difficult privacy problem to address. While new cryptographic techniques, such as zero-knowledge proofs, are being proposed as solutions to the problem of aggregation and correlation, the existence of long-lived identifiers and browser tracking techniques defeats even the most modern cryptographic techniques.

The solution to the privacy implications of correlation or aggregation tend not to be technological in nature, but policy driven instead. Therefore, if a holder does not want information about them to be aggregated, they must express this in the verifiable presentations they transmit.

10.13 Usage Patterns

Despite the best efforts to assure privacy, actually using verifiable credentials can potentially lead to de-anonymization and a loss of privacy. This correlation can occur when:

• The same credential is presented to the same verifier more than once. In this case, the verifier could infer that the holder is the same individual.
• The same credential is presented to different verifiers, and either those verifiers collude or a third party has access to transaction records from both verifiers. In this case, the observant party could infer that the individual presenting the credential is the same person at both services. That is, the accounts are controlled by the same person.
• The same subject identifier of a credential refers to the same subject across presentations or verifiers, then loss of privacy is possible. Even when different credentials are presented, if the subject identifier is the same, verifiers (and those with access to verifier logs) could infer that the holder of the credential is the same person.
• The underlying information in a credential can be used to identify an individual across services. In this case, using information from other sources (including information provided directly by the user), verifiers can use information inside the credential to correlate the individual with an existing profile. For example, if a holder presents credentials that include postal code, age, and sex, a verifier can potentially correlate the subject of that credential with an established profile. For more information, see Sweeney 2000 Simple Demographics Often Identify People Uniquely].
• Passing the identifier of a credential to a centralized revocation server. In this case the centralized server can correlate the credential usage across interactions. For example, if a verifiable credential is used for proof of age in this manner, the centralized service could know everywhere that credential was presented: all liquor stores, bars, adult stores, lottery purchases, and so on.

In part, it is possible to mitigate this de-anonymization and loss of privacy by:

• Using a globally-unique identifier as the subject for any given credential and never re-use that credential.
• If the credential supports revocation, using a globally-distributed service for revocation.
• Designing revocation APIs that do not depend on submitting the ID of the credential. For example, use a revocation list instead of a query.
• Avoiding the association of personally identifiable information with any specific long-lived subject identifier.

It is understood that these mitigation techniques are not always practical or even compatible with necessary usage. Sometimes correlation is a requirement.

For example, in some prescription drug monitoring programs, usage monitoring is a requirement. Enforcement entities need to be able to confirm that individuals are not cheating the system to get multiple prescriptions for controlled substances. This statutory or regulatory need to correlate usage overrides individual privacy concerns.

Verifiable credentials will also be used to intentionally correlate individuals across services, for example, when using a common persona to log in to multiple services, so all activity on each of those services is intentionally linked to the same individual. This is not a privacy issue as long as each of those services uses the correlation in the expected manner.

Privacy risks of credential usage occur when unintended or unexpected correlation arises from the presentation of verifiable credentials.

10.14 Sharing Information with the Wrong Party

When a holder chooses to share information with a verifier, it might be the case that the verifier is acting in bad faith and requests information that could be used to harm the holder. For example, a verifier might ask for a bank account number, which could then be used with other information to defraud the holder or the bank.

Issuers should strive to tokenize as much information as possible such that if a holder accidentally transmits credentials to the wrong verifier, the situation is not catastrophic.

For example, instead of including a bank account number for the purpose of checking a individual's bank balance, provide a token that enables the verifier to check if the balance is above a certain amount. In this case, the bank could issue a verifiable credential containing a balance checking token to a holder. The holder would then include the verifiable credential in a verifiable presentation and bind the token to a credit checking agency using a digital signature. The verifier could then wrap the verifiable presentation in their digital signature, and hand it back to the issuer to dynamically check the account balance.

Using this approach, even if a holder shares the account balance token with the wrong party, an attacker cannot discover the bank account number, nor the exact value in the account. And given the validity period for the counter-signature, does not gain access to the token for more than a few minutes.

10.15 Frequency of Claim Issuance

As detailed in Section 10.13 Usage Patterns, usage patterns can be correlated into certain types of behavior. Part of this correlation is mitigated when a holder uses a verifiable credential without the knowledge of the issuer. Issuers can defeat this protection however, by making their credentials short lived and renewal automatic.

For example, an "over the age of 21" credential is useful for gaining access to a bar. If an issuer issues such a credential with a very short expiration date and an automatic renewal mechanism, then the issuer could possibly correlate the behavior of the holder in a way that negatively impacts the holder.

Organizations providing software to holders should warn them if they repeatedly use credentials with short lifespans, which could result in behavior correlation. Issuers should avoid issuing credentials in a way that enables them to correlate usage patterns.

10.16 Prefer Single-Use Credentials

An ideal privacy-respecting system would require only the information necessary for interaction with the verifier to be disclosed by the holder. The verifier would then record that the disclosure requirement was met and forget any sensitive information that was disclosed. In many cases, competing priorities, such as regulatory burden, prevent this ideal system from being employed. In other cases, long-lived identifiers prevent single use. The design of any verifiable credentials ecosystem, however, should strive to be as privacy-respecting as possible by preferring single-use credentials whenever possible.

Using single-use credentials provides several benefits. The first benefit is to verifiers who can be sure that the data in a credential is fresh. The second benefit is to holders, who know that if there are no long-lived identifiers in the credential, the credential itself cannot be used to track or correlate them online. Finally, the third benefit is that there is nothing for attackers to steal, making the entire ecosystem safer to operate within.

10.17 Avoid Disclosing Credential Identifier

Disclosing the credential identifier leads to situations where multiple verifiers, or an issuer and a verifier, can collude to correlate the holder. If holders want to reduce correlation, they should use credential schemes that allow hiding the identifier during presentation. Such schemes expect the holder to generate the identifier and might even allow hiding the identifier from the issuer, while still keeping the identifier embedded and signed in the credential.

11.1 Cryptography Suites and Libraries

Some aspects of the data model described in this specification can be protected through the use of cryptography. Implementers should be aware of the underlying cryptography suites and libraries used to implement the creation and verification of digital signatures and mathematical proofs used by their systems when processing credentials and presentations. Software developers with extensive experience implementing or auditing systems that use cryptography must be employed to ensure that systems are properly designed. Proper red teaming is also suggested to remove bias from security reviews.

Cryptography suites and libraries have a shelf life and eventually fall to new attacks and technology advances. Production quality systems must take this into account and ensure mechanisms exist to easily and proactively upgrade expired or broken cryptographic suites and libraries. Procedures should also exist to invalidate and replace existing credentials in the event of a cryptography suite or library failure. Regular monitoring of systems to ensure proper upgrades are made in a timely manner are also important to ensure the long term viability of systems processing verifiable credentials.

11.2 Unsigned Claims

This specification allows credentials to be produced that do not contain signatures or proofs of any kind. These types of credentials are often useful for intermediate storage, or self-asserted information, which is analogous to filling out a form on a web page. Implementers should note that these types of credentials are not verifiable because the authorship is either not known or cannot be trusted.

11.3 Token Binding

A verifier might need to ensure it is the intended recipient of a verifiable presentation and not the target of a man-in-the-middle attack. Any protocol that is using the Verifiable Credentials Data Model and requires protection against these kinds of attacks needs to perform some sort of token binding, such as The Token Binding Protocol v1.0, which ties the request for a verifiable presentation with the response. Any protocol that does not perform token binding is susceptible to man-in-the-middle attacks.

11.4 Bundling Dependent Claims

It is considered best practice for issuers to atomize information in a credential, or use a signature scheme that allows for selective disclosure. In the case of atomization, if it is not done securely by the issuer, the holder might bundle together different credentials in a way that was not intended by the issuer.

For example a university might issue two credentials to a person, each containing two properties, for example, "Staff Member" in the "Department of Computing" and "Post Graduate Student" in the "Department of Economics". If these credentials are atomized into separate properties, then the university would issue four credentials to the person, each containing one of the following properties, "Staff Member", "Post Graduate Student", "Department of Computing", and "Department of Economics". The holder could then transfer the "Staff Member" and "Department of Economics" credentials to a verifier, which together would comprise a false claim.

11.5 Highly Dynamic Information

When verifiable credentials are issued for highly dynamic information, implementers should ensure the expiration times are set appropriately. Expiration periods longer than the timeframe where the credential is valid might create exploitable security vulnerabilities. Expiration periods shorter than the timeframe where the information expressed by the credential is valid creates a burden on holders and verifiers. It is therefore important to set validity periods for credentials that are appropriate to the use case and the expected lifetime for the information contained in the credential.

11.6 Device Theft and Impersonation

When verifiable credentials are stored on a device and that device is lost or stolen, it might be possible for an attacker to gain access to systems using the victim's verifiable credentials. Ways to mitigate this type of attack include:

• Enabling password, pin, pattern, or biometric screen unlock protection.
• Enabling password, biometric, or multi-factor authentication for the credential repository.
• Enabling password, biometric, or multi-factor authentication when accessing cryptographic keys.
• Using a separate hardware-based signature device.
• All or any combination of the above.