Verifiable Credentials

info

Please note that this specification is suitable for pre-production pilot implementations.

Overview

The World-Wide-Web Consortium (W3C) has defined a data model for Verifiable Credentials (VCs). A VC is a portable digital version of everyday credentials like education certificates, permits, licenses, and registrations. VCs are digitally signed by the issuing party and are tamper-evident, privacy-preserving, revocable, and independently verifiable.

The UN has previously assessed this standard and has recommended its use for a variety of cross-border trade use cases in a recent white paper. VCs are inherently decentralised and so are an excellent fit for UNTP, which recommends that passports, credentials, and traceability events are all issued as W3C VCs.

A related W3C standard called Decentralized Identifiers (DIDs) provides a mechanism to manage the cryptographic keys used by verifiable credentials and to link multiple credentials into verifiable trust graphs. DIDs are not the same as the business, product, or location identifiers maintained by authoritative agencies, but can be linked to them.

Business requirements for UNTP application of VCs

There are many different technical implementation options for verifiable credentials, which presents an interoperability risk — credentials issued by one party may not be understandable or verifiable by another. UNTP does not design new technical standards (that is the role of standards bodies such as W3C or IETF). Instead, UNTP enhances interoperability by recommending the narrowest practical set of technical options for each business requirement.

A key design principle for decentralised ecosystems is Postel's robustness principle: an implementation should be conservative in its sending (issuing) behaviour, and liberal in its receiving (verifying) behaviour. Sustainability evidence in a given value chain may arrive as many different versions of W3C VCs, or as ISO mDL credentials, Hyperledger Anoncreds, or even human-readable PDF documents. Being open in what is received and verified allows sustainability assessments to draw on a wide set of evidence. Conversely, choosing a narrow set of ubiquitous technology options when issuing UNTP credentials simplifies the task of verifiers and minimises costs for the entire ecosystem.

ID	Name	Requirement Statement	Solution Mapping
VC-01	Integrity	Support tamper detection, issuer identity verification, and credential revocation so verifiers can trust the integrity of UNTP credentials.	All VC options support this
VC-02	Compatibility	Recommend the narrowest practical set of technology options aligned with the most ubiquitous global choices to minimise the cost of interoperability.	Basic profile
VC-03	Human readable	Support both human-readable and machine-readable credentials so that actors with lower technical maturity are not blocked from participating.	Render method
VC-04	Discovery	Enable discovery and verification of credentials from product identifiers, so that verifiers need no prior relationship with issuers or subjects.	Identity Resolver
VC-05	Semantics	Use standard web vocabularies so data from independent credentials can be meaningfully aggregated.	Vocabularies
VC-06	Performance	Enable efficient traversal and verification of graphs containing hundreds of credentials.	Basic profile (JOSE proof)
VC-07	Compliance	Meet any technology-based regulatory requirements in the countries where credentials are issued or verified.	Basic profile
VC-08	Openness	Avoid driving users towards closed ecosystems or proprietary ledgers.	DID methods
VC-09	Portability	Allow issuers to move DID documents between service providers so long-duration credentials remain verifiable.	DID methods (webvh method)
VC-10	Evolution	Evolve UNTP recommendations as VC tools and versions mature.	Roadmap

Verifiable Credential Profile

The UNTP Verifiable Credential Profile defines a narrow, interoperable subset of W3C VC technology choices. It comprises four parts: the VCDM profile (the core data model and proof mechanism), the render method (for human-readable presentation), the vocabularies (for semantic interoperability), and the DID methods (for issuer identification).

VCDM profile

The VC basic profile is designed to be as simple, lightweight, and interoperable as possible. A conformant implementation

• MUST implement the W3C VC Data Model v2.0 using the JSON-LD Compacted Document Form
• MUST implement W3C VC Bitstring Status List for credential status management including revocation
• MUST implement W3C-DID-CORE using DID methods defined in DID methods
• MUST implement the enveloping proof mechanism defined in W3C VC JOSE / COSE with JOSE (Section 3.1.1)

Render Method

Human-readable rendering of digital credentials is essential because UNTP must work for every actor in a global supply chain — from multinationals with mature digital systems to small producers with nothing more than a smartphone and a barcode reader. A structured JSON credential is perfectly verifiable by a machine, but it is meaningless to a buyer, an inspector, or a consumer who needs to see what the credential says.

The VC data model addresses this through the renderMethod property, which allows a credential issuer to embed or reference a template that a verifier can use to transform the credential into a human-readable document (typically HTML). The same signed credential can therefore be verified by a machine and displayed as a nicely formatted passport, certificate, or report to a person — without requiring a second, separate human-readable artifact that could drift out of sync with the verified data.

A conformant UNTP implementation:

• SHOULD use the renderMethod property as defined in the VC data model.
• SHOULD implement the html render suite defined in the draft W3C render methods specification.

Vocabularies

A shared understanding of the meaning of claims made in verifiable credentials is essential to interoperability. The UNTP approach is to retain full JSON-LD linked-data compliance while also supporting developers who are unfamiliar with linked data and "just want the JSON schema". This is achieved by maintaining versioned @context files for semantic meaning and complete JSON schemas for each credential type for schema validation.

Key design points:

• Credential instances contain VCDM type references for each uniquely identified linked-data object. Each extension builds on parent types and is enumerated in the type array (e.g. ["Facility", "Farm"]).
• UNTP @context types are protected and MUST NOT be duplicated in extensions. Similarly, the UNTP @context does not duplicate protected terms from the VCDM @context.
• Unlike @context files, the JSON schema for each credential MUST be a complete schema that defines the entire credential including terms from VCDM and UNTP.

Conformant UNTP implementations:

• MUST use the JSON-LD syntax for the representation of data in all issued credentials.
• MUST reference the relevant versioned @context file from the UNTP vocabulary. The UNTP context file is an extension of the W3C VC Data Model 2.0 context.
• MAY extend credentials with additional properties and, if so, SHOULD include an additional @context file reference that defines the extended properties. The @vocab "catch-all" mechanism SHOULD NOT be used.
• SHOULD implement widely used industry vocabularies such as schema.org as a first choice for UNTP extensions requiring terms not in the UN vocabulary.
• MAY use any other published JSON-LD vocabulary for industry or country specific extensions.
• MUST maintain @context files at the same granularity and version as the corresponding credential type. This prevents verification failures when context files change after credentials are issued.
• SHOULD provide a complete and versioned JSON schema for each credential type, to facilitate simple and robust implementation by developers without detailed knowledge of JSON-LD.

DID Methods

UNTP supports the use of decentralised identifiers (DIDs) to uniquely and verifiably represent organisations, facilities, products, and other actors across global supply chains. These identifiers form the foundation for establishing Digital Identity Anchors (DIAs), resolving linksets via an Identity Resolver, and verifying credential issuers.

The W3C DID Core specification allows for a broad range of DID methods, many of which are registered in the W3C DID Extensions registry. Not all methods offer equivalent levels of verifiability, governance assurance, or operational fit for UNTP's trust model. Some methods rely solely on DNS and HTTPS infrastructure; others incorporate explicit proofs, registries, or governance contracts to strengthen control verification. The choice of DID method directly impacts the integrity of identity resolution and the downstream reliability of linked credentials. The UNTP working group expects that the proliferation of DID methods will consolidate over time to a much smaller number of methods, each designed to meet specific business needs.

Acknowledged DID methods

An acknowledged DID method is one that the UNTP working group has evaluated and determined to offer appropriate levels of verifiability, governance assurance, or operational fit for specific UNTP use cases. The list evolves through working group consensus as new methods mature.

Method	Status	When to use
did:web	✅ Recommended	Simple, widely interoperable organisational identifiers where trust in domain ownership is independently verified
did:webvh	✅ Recommended (Advanced)	Institutional and organisational identifiers requiring verifiable history, key rotation, and auditability

did:web

The did:web method enables identifiers to be derived from domain names and resolved via well-known HTTPS endpoints. It is widely supported and simple to implement, relying on existing DNS and TLS infrastructure to bind identifiers to hosting environments.

Within the UNTP framework, did:web offers a pragmatic entry point for identity publication and resolution. Its structure is compatible with the Digital Identity Anchor model and can be used to expose service endpoints, credential metadata, and other linkable assets.

However, did:web relies on implicit trust in domain ownership and HTTPS hosting. It does not by itself provide strong or auditable guarantees of control — particularly in shared hosting environments, federated platforms, or supply chains involving resellers and intermediaries. Its use is sensitive to domain expiration, certificate mismanagement, and untracked delegation. UNTP implementations MAY use did:web where simplicity and broad interoperability are prioritised, and where trust in domain ownership is independently verified.

A conformant UNTP implementation:

• MUST implement the did:web method as an Organisational Identifier
• SHOULD implement the did:web method using the web domain of the issuer to avoid portability challenges

Field	Description
Method Name	did:web
Identifier Syntax	did:web:<domain> or did:web:<domain>:<path>
Status	✅ Recommended — widely interoperable and suitable for institutional and organisational identifiers
Governance	W3C-registered DID method maintained by the Decentralized Identity Foundation (DIF) and the W3C community
Resolution	Well-known HTTPS endpoints (typically /.well-known/did.json or /did.json), resolved via DNS and TLS infrastructure
Use Case in UNTP	Organisational identifiers, Digital Identity Anchors, identity publication and resolution. Suitable where simplicity and broad interoperability are prioritised.
Advantages	Widely supported, simple to implement, relies on existing DNS and TLS infrastructure. Compatible with the Digital Identity Anchor model.
Known limitations	Relies on implicit trust in domain ownership. No strong or auditable guarantees of control, particularly in shared hosting or federated platforms. Sensitive to domain expiration, certificate mismanagement, and untracked delegation.
Implementation Notes	MUST be implemented as an Organisational Identifier. SHOULD use the issuer's own web domain to avoid portability challenges. Requires independent verification of domain ownership.

did:webvh

The did:webvh method extends did:web by introducing verifiable history — enabling tamper-evident tracking of identifier updates over time. It allows organisations to maintain a cryptographically linked log of key rotations, control changes, and migrations across domains, providing strong assurances of authenticity and continuity.

Within UNTP, did:webvh is recommended for institutional and organisational identifiers where auditability, long-term trust, and accountability are required — such as Digital Identity Anchors, credential issuers, and registry maintainers. It retains the accessibility of web-based publishing via HTTPS while adding a transparent, verifiable chain of control that aligns with UNTP's principles of traceability, integrity, and transparency.

Field	Description
Method Name	did:webvh
Identifier Syntax	did:webvh:<domain> or did:webvh:<domain>:<path>. Resolved via HTTPS to a did.jsonl (JSON Lines) file containing a verifiable chain of DID document versions.
Status	✅ Recommended (Advanced) — suitable for institutional, organisational, and delegated identifiers requiring verifiable history, key rotation, and auditability
Governance	Maintained by the Decentralized Identity Foundation (DIF) as an extension of did:web. Defined in the DIF DID Web Verifiable History specification.
Resolution	HTTPS endpoints hosting a did.jsonl log file, typically at /.well-known/did.jsonl. Resolution verifies a chain of cryptographically linked versions (previousVersionHash + proof) to produce a tamper-evident DID Document history.
Use Case in UNTP	Digital Identity Anchors and institutional identifiers requiring auditability, traceability, and long-term trust. Supports continuity of identity even when domains change.
Advantages	Extends did:web with verifiable, append-only history of updates. Enables tamper-evident key rotation, continuity of trust, and portability between domains. Backward compatible with existing did:web resolvers when version history is ignored.
Known limitations	Still relies on HTTPS hosting and DNS domain ownership. More complex to implement due to the requirement to maintain a valid did.jsonl chain. Historical transparency may expose metadata about operational changes — privacy implications should be assessed per use case.
Implementation Notes	MUST be implemented where auditability of identity control is required (e.g. accredited data publishers, credential issuers). SHOULD maintain the did.jsonl file with proper version linking and proofs. Implementers SHOULD plan for domain portability using the alsoKnownAs and newDomain parameters.

Wallets and Presentations

The verifiable credentials ecosystem is typically designed around a model where a human holder stores credentials in a personal digital wallet and presents them to verifiers on demand. This works well for personal credentials such as driver's licenses or educational certificates, where the holder is a person who can actively participate in a presentation exchange.

UNTP operates in a fundamentally different context. The subject of most UNTP credentials is an inanimate object — a box of goods, a shipment of steel, a battery module. The box of goods cannot create verifiable presentations on demand, and the credential binding is to the identity of the goods rather than to a holder. Any party with access to the product identifier (via a barcode, QR code, or RFID tag) discovers credentials about that product through an Identity Resolver. This is why UNTP's architecture centres on a resolver-based "pull" model rather than a wallet-based "push" model.

Verifiable Presentations

A conformant UNTP implementation:

• MUST issue and publish product passports, product conformity credentials, and traceability events as verifiable credentials and MUST include the identifier of the goods within the VC subject.
• MAY exchange these and any other credentials as verifiable presentations in wallet-to-wallet transfers or any other method.

Wallets

UNTP is wallet-agnostic. It neither mandates nor precludes the use of digital wallets for storing, managing, or exchanging verifiable credentials. Digital wallets are relevant in several legitimate implementation contexts — including organisational identity and accreditation presentation, regulatory compliance in wallet-mandated jurisdictions such as the EU Digital Identity (EUDI) Wallet, and business-to-business credential exchange as part of procurement or onboarding workflows. In these scenarios, wallets are one possible mechanism among several, complementing rather than replacing the resolver-based discovery model.

For detailed guidance on when and how to use digital wallets with UNTP, including design patterns and implementation considerations, see Digital Wallets.

Roadmap

Future versions of this specification will

• Provide richer guidance on DID methods via a decision tree that helps to select the right method for the right purpose
• Address the proliferation of DID methods and their consolidation to meet specific business needs
• Provide guidance for different use cases (e.g. legal entities vs products)
• Provide guidance on selective redaction methods to better support confidentiality goals
• Provide timelines for transition between versions of technical specifications