Best Practices
Please note that this specification is suitable for pre-production pilot implementations.
Overview
Supply chain transparency is not just a matter of issuing verifiable credentials — it requires solving a series of interconnected challenges that arise when many independent actors exchange sustainability data across complex, multi-tier value chains. This section describes common supply chain challenges and presents how UNTP can be used to address each of them. Each design pattern is non-normative best practice guidance for UNTP implementers.
Transparency Graphs
Challenge: Verifying a single credential proves it hasn't been tampered with and was issued by the stated issuer — but it says nothing about whether the graph of linked claims across many credentials is trustworthy. Real compliance verification requires following chains of evidence across multiple credentials issued by different parties: confirming issuer identity, checking accreditation of conformity assessment bodies, tracing product origins through traceability events, and verifying mass-balance consistency.
Solution: UNTP provides a method to recursively discover credentials via identity resolvers, assemble them into a linked-data transparency graph that represents your value chain, and optionally validate the graph against example SHACL constraints (or the recommended profile), plus industry-specific, geography-specific, and organisation-specific overlays. Those examples are informative and post 1.0. Applying them is not a v1.0 conformance requirement.
Graph Validation
Challenge: The rules that matter span several credentials issued by different parties — a passport, the facility that made the product, the certificate that facility holds, the body that issued it. Each credential can be individually well-formed and pass schema validation while the chain they form is non-compliant. Those rules are also written by many independent actors (UNTP, industry bodies, regulators, individual buyers) who cannot coordinate on a shared rule format.
Solution: Express constraints as SHACL shapes, annotated so that the rule remains readable by the people accountable for it. This page publishes each example independently and a recommended profile that unions them. Overlay publishers add industry, geography, or organisation shapes. A relying party unions the constraint IRIs it trusts. The examples are informative. Promoting a stable subset to normative shape constraints is post-1.0 work, not a v1.0 conformance requirement.
Different Digital Maturities
Challenge: Supply chains will operate with a mix of paper certificates, PDF documents, and digital credentials for years to come. Upstream suppliers may not yet issue verifiable data (no machine-readable structure, no cryptographic integrity, no consistent discovery). Downstream customers may not yet be equipped to consume digital credentials.
Solution: Use AI (Large Language Models) to transform unstructured upstream data into graph-compatible linked data — flagged as unverified — so that the same validation rules can run across the entire graph regardless of source maturity. For downstream consumers, every UNTP credential is designed to be both human-readable (via render templates and hosted verifier links) and machine-readable, so a single credential serves all maturity levels.
Jurisdictional Extension
Challenge: Regulatory obligations attach at market entry, but the data those obligations need originates upstream — with actors who are not economic operators in that market and who often cannot know, at the moment of production, which market the product will reach. A grain lot is binned and split across five destinations; livestock are sold at auction. A regulation that pushes its bespoke schema upstream is asking the producer to answer a question that does not yet have an answer, and most of the world's primary production supplies markets with no passport mandate at all.
Solution: Share the base layer, not the requirements. Where every jurisdiction uses the same identifiers, the same credential format, and the same traceability semantics, a regulator's specific requirements become an additive extension rather than a separate reporting regime. Primary producers publish their conformity, emissions, and provenance evidence once in UNTP form; market-entry operators do the jurisdiction-specific work of registry lodgement, mandated carriers, required attribute sets, and access tiers, because they hold both the market knowledge and the legal obligation.
Sovereignty and Jurisdiction
Challenge: UNTP has no central data store, which is a good start for a government assessing adoption, but decentralised data does not settle who controls what. An issuer may host through a provider in another country. An identifier register keeps its own copy of metadata about what it has numbered. A resolver is a hosted service running under somebody's law, and can see who is asking about what. And a due-diligence obligation in an importing country can require evidence an exporting country forbids from leaving.
Solution: Work out which questions the protocol answers and which it does not. Identity assurance comes from one of three arrangements and they travel across a border differently; data residency has to count the register copies and the provider's hosting, not just the passport; a conflict of law is usually dissolved by sending an attestation where the evidence cannot go; and recognising another jurisdiction's registers scales where re-verifying its exporters does not. Where the answer is a legal instrument rather than a protocol feature, the page says what such an instrument has to settle instead of pretending to settle it.
Chain of Custody and Mass Balance
Challenge: When qualifying and non-qualifying materials are mixed during production, a manufacturer could fraudulently claim the entire output as sustainable — re-using valid input credentials across a larger volume than they cover. Verifying mass-balance integrity requires visibility of all facility inputs, outputs, and production processes, but this data is almost always commercially confidential.
Solution: Record every input shipment, production run, and output shipment as verifiable traceability events with quantity data. An independent auditor verifies that output sustainability claims never exceed input quantities, issuing a conformity credential that attests to mass-balance integrity — without exposing the facility's confidential production data to buyers or competitors. This is the trusted auditor tool in Disclosing the Data.
Accumulating Linked Data
Challenge: The logical view of a product, a facility, or a business draws on data created by different actors, systems, and lifecycle stages. Requiring one publisher to copy every node into one credential creates coordination, provenance, and update problems, while requiring every receiver to assemble a graph may not suit transactional or regulatory snapshots.
Solution: Choose the aggregation boundary that fits the business need. A publisher can assemble related nodes into a larger credential at issue time, or a consumer can discover separate credentials through an identity resolver and assemble the same graph at verification time. Hybrid implementations keep an original record immutable while later audits, assessments, and lifecycle events remain separately discoverable against the same identifier.
Privacy-Preserving Verification
Challenge: A buyer, regulator or customs authority needs confidence in an upstream claim. The upstream actor holds the evidence and cannot publish it: supplier relationships and production volumes are commercially sensitive, and in some jurisdictions the underlying data may not lawfully leave the country.
Solution: Choose what crosses the boundary. An accredited assessor sees the evidence and the verifier receives a signed conclusion with a commitment to the evidence behind it, so the assessor is itself auditable. Or publish a cryptographic commitment to a confidential value, so a relationship is visible without its parties. Or disclose the data to named parties under encryption or as a role-specific variant.
Variant-Based Disclosure
Challenge: Different supply chain actors — the public, customers, regulators, auditors, recyclers — need access to different claims within the same credential. But credential-level access control is too coarse-grained: a party either has access to an entire credential or they don't.
Solution: Publish multiple document variants of the same credential, each containing a role-appropriate subset of claims with stubs indicating what other data exists. The identity resolver routes requests to the appropriate variant based on an access role parameter, enabling claim-level granularity without requiring cryptographic selective disclosure. This is the variant tool in Disclosing the Data; it composes with public discovery, encryption, and trusted-auditor attestations.
Digital Wallets
Challenge: The verifiable credentials ecosystem assumes a human holder presenting credentials from a wallet on demand. But UNTP credentials describe inanimate products — a box of goods, a shipment of steel — that cannot participate in presentation exchanges. The wallet-centric model does not fit supply chain transparency as the primary exchange pattern.
Solution: UNTP centres on resolver-based credential discovery rather than wallet-based presentation, ensuring any party with access to a product identifier can find credentials without prior relationships or specific software. Wallets remain a complementary mechanism for organisational authentication, regulatory compliance in wallet-mandated jurisdictions, and B2B credential exchange.
Durable Storage
Challenge: UNTP credentials must remain verifiable for the lifetime of a product — potentially decades — but issuing organisations may cease operations and stop paying for hosting. Conventional web hosting and even commercial cloud storage fail once the bills stop being paid. Retrieving one passport is still not enough: a later verifier also needs DID documents, status lists, vocabularies, and linked credentials, and a downstream importer or regulator may need to keep that whole graph after the original hosts disappear.
Solution: Non-normative guidance for two roles. Publishers plan for their own closure, keep their verification material available, and can pin credentials in a content-addressable store (IPFS/Filecoin, Arweave, or an equivalent archive). Receivers keep exact signed copies of the upstream evidence their claims depend on, with the verification material and a record of what they checked on receipt, without becoming the issuer of the upstream claims. The guidance is explicit about what copies cannot prove: that an unreachable DID's key was genuine, or that a credential was not revoked at a given time.