Credentials & Data

A Verifiable Credential is a digital certificate or badge — like a diploma, a skill badge, or a license — that proves something about a person. It's cryptographically signed, so anyone can check it's real without calling the issuer, and the person who earned it owns it and can share it anywhere.

Formally, a Verifiable Credential is a W3C standard JSON document: a set of claims about a subject, signed by an issuer. LearnCard issues and verifies two profiles of it:

• Open Badges v3 (OBv3) — badges, certificates, and achievements. This is what send() produces by default and what the examples in these docs use.

• Comprehensive Learner Record v2 (CLR) — a signed bundle of many achievements from one or more issuers, for transcripts and records.

Both are plain W3C credentials underneath, so any conformant wallet or verifier can read them. See Interoperability for the full list of standards LearnCard speaks.

What's inside a credential

LearnCard supports both VC 1.0 and VC 2.0. The shapes are defined as Zod validators in @learncard/types, so what you get back from the SDK is already type-checked.

Component	Description	Required
@context	JSON-LD contexts defining the vocabulary	Yes
id	Unique identifier for the credential	No
type	Array of credential types	Yes
issuer	Entity that issued the credential	Yes
credentialSubject	Entity the credential is about	Yes
proof	Cryptographic proof of authenticity	Yes

The one difference you'll notice between versions: VC 1.0 uses issuanceDate / expirationDate; VC 2.0 uses validFrom / validUntil. New credentials should use 2.0.

https://github.com/learningeconomy/LearnCard/blob/942bb5f7/packages/learn-card-types/src/vc.ts#L129-L177

export const UnsignedVCValidator = z
    .object({
        '@context': ContextValidator,
        id: z.string().optional(),
        type: z.string().array().nonempty(),
        issuer: ProfileValidator,
        credentialSubject: CredentialSubjectValidator.or(CredentialSubjectValidator.array()),
        refreshService: RefreshServiceValidator.or(RefreshServiceValidator.array()).optional(),
        credentialSchema: CredentialSchemaValidator.or(
            CredentialSchemaValidator.array()
        ).optional(),

        // V1
        issuanceDate: z.string().optional(),
        expirationDate: z.string().optional(),
        credentialStatus: CredentialStatusValidator.or(
            CredentialStatusValidator.array()
        ).optional(),

        // V2
        name: z.string().optional(),
        description: z.string().optional(),
        validFrom: z.string().optional(),
        validUntil: z.string().optional(),
        status: CredentialStatusValidator.or(CredentialStatusValidator.array()).optional(),
        termsOfUse: TermsOfUseValidator.or(TermsOfUseValidator.array()).optional(),
        evidence: VC2EvidenceValidator.or(VC2EvidenceValidator.array()).optional(),
    })
    .catchall(z.any());
export type UnsignedVC = z.infer<typeof UnsignedVCValidator>;

export const ProofValidator = z
    .object({
        type: z.string(),
        created: z.string(),
        challenge: z.string().optional(),
        domain: z.string().optional(),
        nonce: z.string().optional(),
        proofPurpose: z.string(),
        verificationMethod: z.string(),
        jws: z.string().optional(),
    })
    .catchall(z.any());
export type Proof = z.infer<typeof ProofValidator>;

export const VCValidator = UnsignedVCValidator.extend({
    proof: ProofValidator.or(ProofValidator.array()),
});
export type VC = z.infer<typeof VCValidator>;

Lifecycle

1. Issue. The issuer builds the claims and signs them — with its own key, or through a signing authority LearnCard hosts for it.

2. Deliver. send() delivers to a LearnCard profile directly, or to an email or phone number through the Universal Inbox, which holds the credential until the recipient claims it.

3. Store. Once claimed, the credential lives in the holder's account, encrypted, under the holder's key.

4. Present. The holder chooses what to share — one credential, or several bundled in a Verifiable Presentation.

5. Verify. The verifier checks the signature, the dates, and the status list. It never needs to contact the issuer.

To do this yourself: Send & Issue Credentials and Verify Credentials.

Verifiable Presentations (VPs)

A Verifiable Presentation is how a holder shares credentials. It wraps one or more credentials and is signed by the holder, which proves two things at once: the credentials are genuine (their issuer signatures still verify) and the person presenting them is the person they were issued to (the holder matches credentialSubject.id). A verifier can add a challenge and domain so a presentation can't be replayed elsewhere.

LearnCard also uses a presentation with no credentials in it — a DID-Auth presentation — as a login proof: signing it shows you control the DID.