Migration Plan

:::info Source Sourced from services/certification-service/MIGRATION_PLAN.md in the documentation repo. :::

1. Core Rules

• JWS proof schema (F13) frozen M3 start; additive only.
• Verification token format (F14) frozen M3 start.
• Certificate indefinite retention; schema evolution must preserve historical verifiability.

2. Database Evolution

• Additive columns nullable.
• Artifact shape JSONB versioned; older certs may have older artifacts.v — renderer library supports all versions.
• Proof format changes require dual-sign window (new kid + alg; old kid still serves old certs).

3. API Evolution

• URL major on breaking.
• Public /verify response shape must be backward-compatible indefinitely — 3rd-party verifiers rely on it.
• Additive fields to public response only.

4. Event Evolution

Event	v	Policy
certification.certificate.issued.v1	v1	Additive
certification.certificate.revoked.v1	v1	Reason enum additive
certification.offline_claim.submitted.v1	v1	Additive

5. JWS Proof Evolution

• Adding claim fields: additive; verifiers ignore unknown.
• Changing signing algorithm: dual-sign new certs with both algs for ≥ 1 milestone.
• Rotating kid: 2-day overlap minimum.
• Removing kid: only after all certs signed with it expire or migrate.

6. Template Evolution

• Template versions; certs record templateId + version at issuance.
• Rendering historical certs uses template-at-issuance.
• Template deletion: archived state; cannot delete if any cert references it.

7. OpenBadges Evolution

• OpenBadges 2.0 → 3.0 migration: dual-issue during transition.
• OB 3.0 = canonical; OB 2.0 sunset after transition.

8. Wallet Pass Evolution

• Google/Apple wallet: platform-specific signing keys; coordinated rotation.

9. Offline Claim Evolution

• Claim signature format versioned; player supports latest version + backward compat with prior version for 1 milestone.

10. Data Residency

• Certificates pinned to tenant homeRegion.
• Migration: freeze issuance → export certs + artifacts → rebuild in target → unfreeze.
• Public verify: cross-region redirect by certificate lookup.

11. GDPR Evolution

• Anonymization policy per tenant; field user_display_name_at_issuance may be redacted to generic placeholder.
• Certificate existence + course retained for verifiability.
• Compliance-officer export for audit.

12. Changelog

Per-release: template versions, proof alg changes, wallet-pass signing rotations, OpenBadges version support.