Credential Subjects

A credential subject is the entity about which claims are made—a person, organization, device, or other entity. The subject connects claims to a specific entity.

Credential Subject in the Verifiable Credentials Data Model

A verifiable credential contains:

• Issuer: Entity making claims about the subject
• Credential Subject: Entity the claims are about
• Claims: Statements about the subject’s attributes
• Proof: Cryptographic evidence of authenticity

The credential subject appears as the credentialSubject property:

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

Data Model Evolution

The W3C Data Model has evolved: V1 supports simple URL strings or objects with properties, while V2 standardizes on object representation with optional ID.

Components and Structure

A credential subject must have at least one property. The only standard property is the optional id:

"credentialSubject": {
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "name": "Jane Doe"
}

Additional Properties

Beyond the optional id, a credential subject can include any properties representing claims. This enables diverse use cases from academic credentials to identity documents.

Validation

Validation enforces:

• At least one property
• Valid URL for id (typically a DID)
• Additional properties conforming to credential type schema

Identification in Credential Subjects

The optional id property provides a unique identifier, establishing persistent identity across credentials and enabling verification that the presenter is the legitimate subject.

DIDs and Identifiers

Decentralized Identifiers (DIDs) are commonly used as they are globally unique, resolvable to DID documents, and don’t require centralized registration:

"credentialSubject": {
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  ...
}

When Identifiers are Used

The id is technically optional but may be required by specific credential types:

• Required when binding to an identifiable entity
• Optional for attribute-only credentials
• Omitted for anonymous credentials prioritizing privacy

Example Implementations

Educational Credential Example

"credentialSubject": {
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "degree": {
    "type": "BachelorDegree",
    "name": "Bachelor of Science in Mechanical Engineering"
  },
  "college": "College of Engineering",
  "graduationDate": "2020-06-15"
}

Related Concepts

Issuers create credentials and make claims about the subject, digitally signing them for authenticity.

Holders store credentials and present them to verifiers.

Verifiers validate credentials by checking cryptographic proofs and evaluating whether the subject meets their requirements.

Claims are statements about the subject’s attributes, properties, or qualifications.