What is a Claim?
A claim is an assertion made about a subject. It consists of a subject-property-value relationship. For example, "Alice's date of birth is 1990-01-15" is a claim where Alice is the subject, date of birth is the property, and 1990-01-15 is the value.
Subject
The entity the claim is about. Usually identified by a DID.
Property
What aspect of the subject is being described (e.g., name, age).
Value
The actual assertion (e.g., 'Alice', 25, true).
The credentialSubject Property
The credentialSubject property contains all claims about one or more subjects. It can be a single object or an array of objects.
Single Subject
Most credentials have a single subject with an optional id (typically a DID).
{
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"givenName": "Alice",
"familyName": "Smith",
"dateOfBirth": "1990-01-15",
"address": {
"streetAddress": "123 Main St",
"locality": "Anytown",
"region": "CA",
"postalCode": "12345",
"country": "US"
}
}
}Subject Without ID
For privacy-preserving credentials (like age verification), you can omit the subject ID entirely.
{
"credentialSubject": {
"type": "AgeVerification",
"ageOver": 21,
"verificationDate": "2024-01-15T10:30:00Z"
}
}Claim Value Types
Claims can hold different types of values, from simple strings to complex nested objects.
| Type | Example | Use Case |
|---|---|---|
| String | "givenName": "Alice" | Names, identifiers, text values |
| Number | "age": 25 | Quantities, scores, numeric identifiers |
| Boolean | "isActive": true | Binary states, flags |
| Date/Time (ISO 8601) | "dateOfBirth": "1990-01-15" | Dates, timestamps, periods |
| Object | "address": { "city": "..." } | Structured data, nested claims |
| Array | "skills": ["JS", "Python"] | Lists, multiple values |
Nested Claims
Complex data can be represented using nested objects. This is common for addresses, organizational structures, and other hierarchical data.
{
"credentialSubject": {
"id": "did:example:123",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science",
"specialization": {
"field": "Computer Science",
"concentration": "Artificial Intelligence"
}
}
}
}Multiple Subjects
A single credential can make claims about multiple subjects. This is useful when describing relationships between entities.
{
"credentialSubject": [
{
"id": "did:example:alice",
"type": "Employee",
"employeeId": "EMP-12345",
"department": "Engineering"
},
{
"id": "did:example:acme-corp",
"type": "Organization",
"name": "ACME Corporation",
"industry": "Technology"
}
]
}When to Use Multiple Subjects
- Employment credentials (employee + employer)
- Relationship credentials (parent + child)
- Authorization credentials (user + resource)
- Certification credentials (entity + certifying body)
Privacy Considerations
How you structure claims affects the privacy properties of your credential.
Privacy-Preserving
- Omit subject ID when not needed
- Use derived claims (ageOver21 vs. birthDate)
- Structure claims for selective disclosure
- Avoid unique identifiers in claims
Privacy Risks
- Persistent subject IDs enable tracking
- Unique claim values can correlate
- Nested objects may reveal too much
- Timestamps can narrow identity