Schema versioning
How PoP schemas evolve and how every artifact stays interpretable under its own version.
Every PoP carries a schema_version in its envelope. It names the schema that defines the layout and meaning of the artifact's data payload. The schema_version an artifact carries is authoritative for that artifact: a verifier interprets data under the named version, not under the latest one.
How a version is bound to an artifact
| Aspect | Rule |
|---|---|
| Location | schema_version is an envelope field, alongside kid, alg, iat, and signature. |
| Scope | It applies to the data payload of that single artifact. |
| Authority | The named version — not the latest — defines how to read that artifact's fields. |
| Stability | A published schema version is immutable. The meaning of a given schema_version does not change after release. |
Cross-version interpretation
| Situation | How a verifier MUST behave |
|---|---|
| Artifact names a version you know | Interpret data strictly under that version's field definitions. |
| Artifact names a newer version than you implement | Verify the signature as normal (signing is version-independent), then interpret the fields you recognise under the named version. Do not assume the layout of a version you have not implemented. |
| Artifact names an older version | Interpret under that older version. Do not retrofit newer fields or meanings onto it. |
Signature verification does not depend on the schema version. The signing envelope and the ES256 signature are stable across schema evolution, so an artifact's authenticity can always be checked even before its data layout is interpreted. See Signing and key discovery.
Compatibility policy
| Guarantee | Statement |
|---|---|
| Immutability | Published schema versions are immutable; a version's field set and meanings are fixed at release. |
| Per-artifact interpretation | An artifact MUST be read under the schema_version it carries, never under an assumed current version. |
| Historical interpretability | Artifacts issued under an older schema_version remain interpretable under that version indefinitely. |
| No silent reinterpretation | A field's meaning MUST NOT be assumed to carry across versions; consult the version the artifact names. |
Practical rule
Pin interpretation to the artifact. Read schema_version, interpret data under exactly that version, and keep the artifact retrievable so it can be re-verified and re-read later. Combined with independent signature and on-chain checks (Verifying a PoP), this keeps every PoP interpretable and verifiable for its full lifetime.