Skip to main content
Version: Next

UNTP v0.7.0

info

Please note that this content is under development and is not ready for implementation. This status message will be updated as content development progresses.

Before you upgrade

Before migrating to version 0.3 of the Reference Implementation, back up the data held in its external systems, in particular the storage service and the identity resolver. Both of these dependent services receive a major upgrade in this release, so review their migration guides first: the storage service v4 migration guide and the Pyx Identity Resolver v4 migration guide.

Overview​

This guide is a high-level summary of what changed in the Reference Implementation for UNTP (UN Transparency Protocol) v0.7.0. It covers the new data models, dependent service updates, and the reworked conformity handling. The credential structures themselves are defined by the published UNTP v0.7.0 schema, which is the source of truth; this guide does not restate them.

UNTP v0.7.0 support is additive: the v0.6.x data models remain available alongside the new v0.7.0 ones, so existing credentials continue to issue and render.

Data Models​

The five UNTP credential types are now available at v0.7.0 (Digital Product Passport, Digital Conformity Credential, Digital Facility Record, Digital Identity Anchor, and Digital Traceability Event), seeded alongside the existing v0.6.x models, each with its own v0.7.0 JSON Schema and render template.

One change is worth calling out because it affects every credential type: in v0.7.0 all five types share a single JSON-LD context, https://vocabulary.uncefact.org/untp/0.7.0/context/, replacing the per-type context URLs used in v0.6.x (for example https://test.uncefact.org/vocabulary/untp/dpp/0.6.0/).

Issuers select the version when issuing; the v0.7.0 core data model IDs available for custom-seed extensions are listed in Custom Seed.

Dependent Service Updates​

The Reference Implementation now uses the following service versions, reflected in the docker-compose configuration. Two of them, the storage service and the identity resolver, were updated to support UNTP v0.7.0:

On the Reference Implementation side, two integration points changed:

  • v4 API path (Storage and Identity Resolver): both adapters now target their service's v4 API. The apiVersion config is 4.0, and requests route under a major-only path segment (/api/v4/...), replacing the full-SemVer path used previously. The storage adapter still supports a 3.x deployment via apiVersion: 3.1.0. See the storage service adapter and the Pyx IDR adapter.
  • Storage digest field: the storage response migrated from a hex hash to digestMultibase (a multibase-encoded digest). The adapter reads digestMultibase when present and, for older storage deployments that still return only a hex hash, transcodes it to a multibase digest, so the adapter's output is always a digestMultibase regardless of the storage version it is talking to.

Digest backfill for existing data​

The storage digest changed from a hex value to a multibase-encoded digest, so credentials and render templates created before the upgrade still carry the old hex format. When the Docker image is started, it automatically converts those existing values to multibase across the stored credentials and render templates. The conversion is safe to repeat, never re-fetches content, and never changes storage URLs.

If you run the Reference Implementation outside the Docker image (for example, on the host during local development), this automatic conversion does not run. Apply the database migrations first, then run the backfill once from the packages/reference-implementation directory. The --env-file flag points it at the root .env for the database connection:

pnpm exec tsx --env-file=../../.env prisma/backfills/2026-05-19-hex-to-multibase.ts

It is the same conversion the Docker image performs on start, and is equally safe to repeat.

The legacy hex digests keep working in the meantime: the verify endpoint still accepts a hex value and the storage adapter handles it, so credentials and resolver links created before the upgrade continue to verify. The conversion simply aligns stored values to the new format; it is not required for existing links to keep working.

Conformity Handling​

UNTP v0.7.0 restructures how conformity vocabulary is published, and the Reference Implementation follows suit.

Previously a single document held the schemes, their versioned profiles, and the versioned criteria together. In v0.7.0 these are separated: UNECE maintains the Conformity Vocabulary Catalogue (CVC), a register of pointer URIs to registered conformity schemes, and each scheme owner publishes its own conformity scheme as an independently dereferenceable JSON-LD document carrying the scheme's details, its versioned profiles, the versioned criteria those profiles reference, and the conformity topics. There is no higher governing document; schemes are registered in the CVC and resolved individually.

In the Reference Implementation:

  • The old single-document CVC data model was removed and replaced with a per-scheme data model and an ingestion pipeline that resolves, validates, and stores a scheme from its URI. Schemes are operator-seeded today. UNTP-discovered ingestion (automatically pulling registered schemes from the CVC register) is not yet operational, pending the register settling; the ingestion and validation pipeline it will use is already in place, but the discovery pass that drives it is not yet wired to run. Tenant-imported schemes are on the roadmap for a future release.
  • Digital Conformity Credential claims are validated against the locally known schemes at issuance. The checks are advisory: a mismatch produces a conformity-* warning and never blocks issuance.
  • A read-only browse API exposes the locally known catalogue by canonical URI: GET /api/v1/cvc/schemes, GET /api/v1/cvc/profiles?schemeId=, and GET /api/v1/cvc/criteria?profileId=.

See Conformity Handling for how conformity data flows through the system.