HomeW3C VCDMData Structure

Credential Data Structure

Understanding the anatomy of a W3C Verifiable Credential, its required and optional properties, and how JSON-LD contexts work.

Structure Overview

A Verifiable Credential is a JSON-LD document containing metadata, claims about a subject, and a cryptographic proof. The structure is designed to be extensible while maintaining interoperability.

Required Properties

These properties MUST be present in every conforming Verifiable Credential.

@contextRequired
Type:Array<string | object>

Must start with "https://www.w3.org/ns/credentials/v2". Defines vocabulary and semantics.

typeRequired
Type:Array<string>

Must include "VerifiableCredential". Can include additional types like "UniversityDegreeCredential".

issuerRequired
Type:string | object

Identifier (usually a DID) of the entity that issued the credential. Can include name and other properties.

credentialSubjectRequired
Type:object | Array<object>

Contains claims about one or more subjects. Each subject can have an optional "id" property.

@context Order Matters
The first item in @context MUST be 'https://www.w3.org/ns/credentials/v2'. Additional contexts define domain-specific vocabulary.

Optional Properties

These properties are optional but provide important functionality for many use cases.

idOptional
Type:string (URI)

Unique identifier for the credential. Omitting increases privacy by reducing correlation.

validFromOptional
Type:string (ISO 8601)

Date/time when the credential becomes valid. Before this time, the credential should not be accepted.

validUntilOptional
Type:string (ISO 8601)

Date/time when the credential expires. After this time, the credential should not be accepted.

credentialStatusOptional
Type:object

References a status list for checking revocation or suspension of the credential.

credentialSchemaOptional
Type:object | Array<object>

References schemas that define the structure and validation rules for the credential.

nameOptional
Type:string

Human-readable name for the credential.

descriptionOptional
Type:string

Human-readable description of what the credential represents.

evidenceOptional
Type:Array<object>

Information about how the issuer verified the claims before issuing the credential.

termsOfUseOptional
Type:Array<object>

Conditions or restrictions on the use of the credential.

refreshServiceOptional
Type:object

Service endpoint for refreshing or renewing the credential.

Privacy Tip

Omitting the id property reduces correlation risk. Without a unique ID, different verifiers cannot easily link presentations of the same credential.

Temporal Validity

validFrom and validUntil define the credential's validity window. Verifiers should reject credentials outside this window.

JSON-LD Context

The @context property maps short-form property names to full URIs, enabling semantic interoperability. It defines the vocabulary used in the credential.

Context Example
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2",
    {
      "alumniOf": "https://schema.org/alumniOf",
      "degree": "https://example.org/vocab#degree"
    }
  ]
}

What @context Does

  • Maps short names like "issuer" to full URIs like "https://www.w3.org/2018/credentials#issuer"
  • Enables different systems to understand the same terms consistently
  • Allows extension with domain-specific vocabularies
  • Supports semantic reasoning and data integration

Complete Example

A complete Verifiable Credential for a university degree, showing required and commonly-used optional properties.

University Degree Credential
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": {
    "id": "did:example:76e12ec712ebc6f1c221ebfeb1f",
    "name": "Example University"
  },
  "validFrom": "2024-01-01T00:00:00Z",
  "validUntil": "2029-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Computer Science"
    }
  },
  "credentialStatus": {
    "id": "https://example.edu/status/24",
    "type": "BitstringStatusListEntry",
    "statusPurpose": "revocation",
    "statusListIndex": "94567",
    "statusListCredential": "https://example.edu/status-list/1"
  }
}

Issuer Object

The issuer can be a simple DID string or an object with additional properties like name, image, or url.

Credential Status

Using BitstringStatusListEntry allows efficient revocation checking without revealing which credential is being checked.

Introduction Claims & Subjects