Credential Subjects

A credential subject is the entity about which claims are made in a verifiable credential. It represents the subject of the credential—the person, organization, device, or other entity that possesses specific attributes being attested to by the issuer. In the verifiable credentials ecosystem, the credential subject forms the core component around which the entire credential is structured.

Credential subjects are essential because they connect the claims in a credential to a specific entity, providing context for the assertions being made. Without a clear subject, a credential’s claims would lack meaning and applicability.

Credential Subject in the Verifiable Credentials Data Model

Within the W3C Verifiable Credentials Data Model, the credential subject occupies a central position as one of the primary components of a verifiable credential.

Relationship to Other Components

A typical verifiable credential contains these key components:

• Issuer: The entity making claims about the subject
• Credential Subject: The entity the claims are about
• Claims: Statements about attributes or properties of the subject
• Proof: Cryptographic evidence that verifies the credential’s authenticity

The credential subject serves as the focal point for the credential’s claims—all assertions within the credential are made about this subject.

Position in the Data Structure

In the JSON-LD representation of a verifiable credential, the credential subject appears as a property called credentialSubject:

{
  "@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": { ... }
}

In this example, the credential subject includes an identifier and a property representing a degree.

Evolution Across Versions

The W3C Verifiable Credentials Data Model has evolved over time, with subtle differences in how credential subjects are handled:

• V1: Supports both a simple URL string or an object with properties
• V2: Standardizes on an object representation with optional ID and required properties

Components and Structure

Required and Optional Properties

A credential subject must have at least one property to be valid, but its specific structure is flexible and depends on the credential type. The Vidos implementation enforces this constraint through schema validation.

The only standard property defined in the W3C specification is id, which is optional:

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

Extensibility Through Additional Properties

One of the key features of the credential subject structure is its extensibility. Beyond the optional id property, a credential subject can include any number of additional properties that represent the claims being made about the subject.

This extensibility allows verifiable credentials to support countless use cases, from academic credentials to identity documents, professional certifications, and more.

Data Validation Requirements

While the credential subject is flexible, implementations typically enforce validation rules:

1. The credential subject must contain at least one property
2. If an id property is included, it must be a valid URL (typically a DID)
3. Any additional properties must conform to the schema defined for that credential type

Identification in Credential Subjects

The Role of the ‘id’ Property

The id property provides a unique identifier for the credential subject. While optional, including an identifier offers several benefits:

• It establishes a persistent identity for the subject across different credentials
• It enables correlation of different credentials about the same subject (when desired)
• It allows verification that the presenter of a credential is the legitimate subject

Using DIDs and Other Identifiers

Decentralized Identifiers (DIDs) are commonly used as identifiers for credential subjects:

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

DIDs are particularly well-suited for this purpose because they:

• Are globally unique
• Can be resolved to DID documents containing verification methods
• Do not require centralized registration
• Support different methods for different use cases and requirements

Other URL-based identifiers can also be used when appropriate for specific applications.

When Identifiers are Optional vs Required

The id property is technically optional in the W3C specification, but specific credential types or implementations may require it depending on the use case:

• Required: When the credential must be bound to a specific, identifiable entity
• Optional: For credentials that describe attributes that don’t need to be tied to a specific identity
• Omitted: For anonymous or minimally identifying credentials where privacy is paramount

Example Implementations

Simple Credential Subject Example

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

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"
}

Professional Certification Example

"credentialSubject": {
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "certification": {
    "name": "Certified Software Developer",
    "level": "Advanced",
    "skills": ["JavaScript", "React", "Node.js"]
  },
  "issueDate": "2022-05-10",
  "expirationDate": "2025-05-10"
}

Best Practices

Data Minimization

When designing credential subjects, include only the properties necessary for the credential’s purpose:

• Limit personal data to what’s essential
• Consider using abstract or derived claims instead of raw data
• Break complex credentials into smaller, purpose-specific credentials

Privacy Considerations

To enhance privacy when working with credential subjects:

• Avoid using persistent identifiers when not needed
• Consider using different identifiers across different contexts
• Use selective disclosure techniques when possible
• Implement zero-knowledge proofs for sensitive attributes

Validation and Verification

For robust credential subject implementation:

• Define and enforce strict schemas for each credential type
• Validate all credential subject properties against expected formats
• Ensure identifiers are valid and resolvable when used
• Consider the relationship between the credential subject and the presenter

Related Concepts

Issuers

The issuer is the entity that creates the credential and makes claims about the credential subject. Issuers digitally sign credentials, establishing their authenticity and integrity.

Holders

Holders store and manage credentials about themselves or other subjects. They present credentials (or parts of them) to verifiers as needed.

Verifiers

Verifiers request and validate credentials. They check the credential’s cryptographic proof, verify the issuer’s authority, and evaluate whether the credential subject meets their requirements.

Claims

Claims are statements about attributes, properties, or qualifications of the credential subject. They represent the actual information being attested to by the issuer.

Conclusion

The credential subject is a fundamental component of the Verifiable Credentials Data Model, representing the entity about which claims are made. Its flexible structure enables a wide range of use cases while maintaining interoperability. Understanding how to properly implement and use credential subjects is essential for building effective verifiable credential ecosystems.

By following best practices for identification, data minimization, and privacy, developers can create credential subject implementations that balance functionality with user privacy and security.