Graph Validation
Please note that this specification is suitable for pre-production pilot implementations.
This page is best-practice guidance, not part of the v1.0 specification. The SHACL files are informative examples. The post-1.0 step is to promote a stable subset of them to normative shape constraints. Issuing a credential does not depend on these examples. A relying party may apply any subset, the recommended profile, or none.
Overview
A transparency graph is built by loading UNTP credentials into a linked-data graph. Graph validation is the step that follows: checking the constraints that span several credentials issued by different parties — a product passport, the facility that made the product, the certificate that facility holds, and the body that issued it.
JSON Schema can only see one credential. These examples see the relationships. That is why a well-formed passport, a well-formed facility record, and a well-formed certificate can still describe a non-compliant product.
UNTP uses SHACL as the method for defining these constraints. A SHACL shape is the rule — the executable definition — and the human-readable statement of the rule travels inside the shape as comments, rather than in a separate document that can drift out of step with it. The worked examples below are informative. Applying them is not a v1.0 conformance requirement.
SHACL fits because:
- It runs on the graph UNTP already produces. Every UNTP credential is JSON-LD, so a transparency graph is RDF, and SHACL validates RDF directly — no intermediate rule format to define or maintain.
- Shapes are data. A shape graph is itself RDF that can be published at a stable IRI, versioned, and cited by a regulation or scheme.
- Rule sets compose. Many independent actors — UNTP, industry extensions, regulators, individual buyers — can each publish their own shapes, and a relying party validates against the union of the constraint IRIs it trusts.
Why constraints span credentials
Forest certification shows why per-credential checking is not enough. A chain-of-custody certificate certifies the company or facility — that it operates the systems to keep certified material accounted for. It does not certify an individual board or batch. Product-level assurance travels instead as transaction claims (FSC 100%, FSC Mix Credit) that are recomputed as material is mixed at each step. A buyer reading "FSC Mix 70%" on a passport is trusting a claim whose validity lives elsewhere in the graph.
Each of the following describes credentials that are individually well-formed and pass schema validation, yet together represent a non-compliant product:
- The passport carries a perfectly structured
FSC Mixclaim, but the facility it was produced at holds no chain-of-custody attestation at all. - The facility's attestation is structurally flawless but expired before the transaction date.
- The attestation is current, but was issued by a scheme outside the buyer's sourcing policy.
- The chain has a valid attestation but is missing the plot-level geolocation and legality provenance that the EU Deforestation Regulation requires.
No per-credential check distinguishes these from a compliant product. The constraint being violated is a relationship, and relationships are what graph validation evaluates.
This example illustrates why graph validation matters. It does not settle how UNTP should model a transaction-borne claim such as FSC Mix Credit, nor the credit and mass-balance accounting behind it — those remain open modelling questions.
Expressing a rule as a SHACL shape
The rule lives in the shape; the comment keeps it readable. Every UNTP shape should carry an sh:message (what is wrong, in terms a supply chain participant can act on) and an rdfs:comment (the rule as a policy officer would state it). This is what lets non-technical stakeholders review a rule they cannot write by hand. There is no second English list. If comment and SPARQL disagree, the shape is wrong — fix the shape.
A simple structural rule — a passport must identify where the product was made:
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix untp: <https://vocabulary.uncefact.org/untp/> .
<https://untp.example.org/shapes/core#ProductionFacilityDeclared>
a sh:NodeShape ;
rdfs:comment "A product passport must identify the facility where the product was made. Facility-level claims cannot be checked against the passport unless the producing facility is identified." ;
sh:targetClass untp:Product ;
sh:property [
sh:path untp:producedAtFacility ;
sh:minCount 1 ;
sh:nodeKind sh:IRI ;
sh:class untp:Facility ;
sh:message "This product passport does not identify the facility where the product was produced." ;
] .
The published example uses the same annotation on a stable IRI:
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix unece: <https://test.uncefact.org/vocabulary/> .
<https://vocabulary.uncefact.org/untp/shapes/ProductionFacilityDeclared>
a owl:Ontology, sh:NodeShape ;
owl:versionInfo "0.8.0" ;
rdfs:comment "A product passport must identify the facility where the product was made. …" ;
sh:targetClass unece:Product ;
sh:property <https://vocabulary.uncefact.org/untp/shapes/ProductionFacilityDeclared-producedAtFacility> .
The timber rule becomes a shape that traverses the graph. SHACL property paths (here using inverse paths) reach the conformity assessments naming this facility, and the credential that carries them, where the issuer is recorded. This is an overlay — organisation or industry policy — not one of the published UNTP examples:
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix cred: <https://www.w3.org/2018/credentials#> .
@prefix untp: <https://vocabulary.uncefact.org/untp/> .
@prefix topics: <https://test.uncefact.org/vocabulary/conformity-topics/> .
<https://buyer.example.com/shapes/timber#AcceptedChainOfCustody>
a sh:NodeShape ;
rdfs:comment "A facility shipping material under a forest certification claim must be covered by a forest conservation attestation from a scheme in our sourcing policy: FSC, PEFC or SFI." ;
rdfs:seeAlso <https://buyer.example.com/policy/timber-sourcing/2026> ;
sh:targetClass untp:Facility ;
sh:property [
sh:path ( [ sh:inversePath untp:facility ] [ sh:inversePath untp:assessedFacility ] ) ;
sh:qualifiedMinCount 1 ;
sh:qualifiedValueShape [
sh:property [
sh:path ( untp:assessmentCriteria untp:conformityTopic ) ;
sh:hasValue topics:forest-conservation ;
] ;
sh:property [
sh:path ( [ sh:inversePath untp:conformityAssessment ]
[ sh:inversePath cred:credentialSubject ]
cred:issuer ) ;
sh:in ( <https://fsc.org> <https://pefc.org> <https://forests.org> ) ;
sh:minCount 1 ;
] ;
] ;
sh:message "This facility has no forest conservation attestation from an accepted scheme (FSC, PEFC or SFI), so timber claims on products it produces cannot be substantiated." ;
] .
One caveat worth flagging early: time-dependent constraints such as "currently valid" fall outside SHACL Core, which has no comparison against the moment of validation. They need a SHACL-SPARQL constraint (using NOW()), and engines limited to SHACL Core cannot evaluate them. Those checks are overlays — see Overlays.
Example constraints
Each example constraint is a Turtle file with a stable IRI, owl:versionInfo, rdfs:comment, and sh:message. Failures live in tests/fail/<ConstraintName>.ttl.
| Artifact | Description |
|---|---|
| ProductionFacilityDeclared.ttl | Product passport names its producing facility |
| IssuerDiaSubjectMatch.ttl | Credential issuer DID is a DIA subject |
| IssuerRegisteredIdMatch.ttl | Issuer registeredId matches the DIA pair |
| DataCarrierProductMatch.ttl | Scanned or resolved identifier is this product |
| ClaimHasMatchingAssessment.ttl | Claim has an assessment of the same criterion |
| AssessorAccreditedForScope.ttl | DCC issuer DIA covers this scheme or profile |
| PartyIdentityAnchored.ttl | Facility related party has a DIA |
| resolvedFrom.ttl | Helper property; not a constraint. Imported by DataCarrierProductMatch |
| recommended.ttl | Example profile: owl:imports of the seven constraints |
| README | How to run the suite |
| validate.mjs | Pass/fail suite (yarn validate-shapes) |
Constraint IRIs are https://vocabulary.uncefact.org/untp/shapes/<Name>. Property and class IRIs in this version follow the v0.8.0 JSON-LD context (https://test.uncefact.org/vocabulary/). Files live under v0.8.0 for that vocab generation; SPARQL edits bump owl:versionInfo on that constraint.
Constraint catalogue
| Constraint IRI local name | What the example checks | Typical UNTP use |
|---|---|---|
ProductionFacilityDeclared | A product passport identifies the producing facility. | Facility-level evidence cannot be joined to a passport that does not name where the product was made. |
IssuerDiaSubjectMatch | A credential issuer DID is the credentialSubject of a Digital Identity Anchor in the graph. | A signed credential is not bound to a registered organisation unless a DIA anchors the issuer DID. |
IssuerRegisteredIdMatch | If the issuer states a registeredId under an idScheme, a DIA for that DID carries the same pair. | The DID may verify while the stated company number is not the one on the register. |
DataCarrierProductMatch | The identifier used to discover a passport is the Product IRI or an alsoKnownAs alias (gv:resolvedFrom). | A scanned or resolved identifier must be the product the passport is about. |
ClaimHasMatchingAssessment | A claim that names a criterion has a conformity assessment of that criterion about the same product or producing facility. | A sustainability claim is unverified until a matching assessment exists in the graph. |
AssessorAccreditedForScope | The DCC issuer has a DIA whose recognitionScope covers the attestation's scheme or profile. | Accreditation for one scheme does not authorise assessments under another. |
PartyIdentityAnchored | A facility's related party has a DIA in the graph. | A facility record that names an owner or operator should bind that party to a register. |
Full IRI: https://vocabulary.uncefact.org/untp/shapes/ plus the local name.
Profiles
A profile is a named union of constraint IRIs (owl:imports). It is not itself a rule.
| Profile | IRI | Imports |
|---|---|---|
| Recommended | https://vocabulary.uncefact.org/untp/shapes/profiles/recommended | The seven example constraints above |
The Test Service Tier 3 may use the recommended profile as an optional example suite.
Using these examples
A relying party, test harness, or buyer tool may load any subset of the constraint IRIs, or the recommended profile that unions them.
Cryptographic checks and graph-business-rule checks are different jobs:
- Verify each credential (proof, issuer keys, status) as it is resolved — see the Verifiable Credentials Profile.
- Validate the assembled graph against the example constraint IRIs (or profile) you chose to apply.
DataCarrierProductMatch only applies when the assembled graph includes a gv:resolvedFrom triple on the product, recording the identifier used to discover the passport.
Mass-balance, time-window ("currently valid"), buyer allow-lists, third-party identifier matching, and joining a producing facility through facilityAlsoKnownAs aliases are not in this example set. Communities may publish those as their own shape graphs.
Entity matching
Facilities commonly carry identifiers from more than one register. These examples join a passport to a facility record only when both use the same IRI (see Transparency Graphs). Matching via facilityAlsoKnownAs, scheme-plus-value keys, or a third-party matcher is later work — it needs a schema decision on how alias identifiers carry their scheme.
SHACL Core and SPARQL
ProductionFacilityDeclared is SHACL Core. The other examples use SHACL-SPARQL because they compare identifiers across nodes. Time-dependent constraints such as "currently valid" (NOW()) are not included.
Overlays
Communities may publish additional shape graphs and union them with any of these examples:
| Overlay | Why not in this example set |
|---|---|
Facility alias join (facilityAlsoKnownAs) | Needs a schema decision on how listed aliases carry idScheme |
| Mass-balance / chain-of-custody volume checks | Optional facility accounting; see Chain of Custody |
| Buyer or scheme allow-lists (FSC / PEFC / SFI, …) | Organisation or industry policy; see the timber shape above |
| Geographic accreditation scope, group certificates | Needs richer DIA / CVC data than the core vocabulary currently carries |
| Status or validity as of a recorded time | Needs the retrieval time of the status list, not only a live NOW() check |
Authoring shapes with LLM assistance
This is guidance, not specification. Nothing about how a shape was drafted affects its meaning — the reviewed shape is what matters.
Writing SHACL by hand is a specialist skill: inverse paths and qualified value shapes are unforgiving. Large language models draft this well when given the right context, which makes them a practical bridge between the person who owns a rule and the shape that expresses it. A workflow that produces reviewable results:
- State the rule in plain English, including what should fail. The failing case is what distinguishes a real constraint from one that is trivially satisfied.
- Give the model concrete context: the UNTP JSON-LD context, a sample credential of each type involved, and the conformity topic IRIs the rule refers to. Without sample data, models guess property names and path directions.
- Ask for a passing and a failing example alongside the shape, and run the shape against both. A shape that passes both is wrong — a path that matches nothing is vacuously satisfied, so it reports conformance on data it never examined.
- Check the comment against the shape. The
rdfs:commentis what non-technical stakeholders rely on, so it must describe what the shape actually does.
Roadmap
Graph validation is intentionally staged. SHACL is the constraint language. The examples on this page stay informative for v1.0. They are not specification text. After 1.0, a stable subset is the material for normative shape constraints. Progress is discussed in the Technical Working Group.
| Stage | Focus | Outcome |
|---|---|---|
| 1 — Direction | SHACL as the method; every shape carries a human-readable description (rdfs:comment / sh:message); optional LLM checks that description and shape still say the same thing | Done |
| 2 — Informative examples | Independently published, versioned example constraints and a recommended profile, kept with this design pattern. Not a v1.0 conformance requirement. | Versioned example files plus recommended.ttl (artefacts/shapes/v0.8.0) |
| 3 — Normative constraints | Post 1.0: promote a reviewed subset of these informative examples to normative shape constraints. | A binding profile in the specification |
| 4 — Presentation layer | Improve how non-technical stakeholders read shapes — starting with descriptions that explain the SHACL, then a deterministic verbalizer that renders English from the shape if that proves necessary | Business sign-off without treating English as a second source |
| 5 — Controlled English subset | If authoring for non-technical audiences still needs more than comments and a verbalizer, define a semi-structured English subset (restricted sentence patterns over the UNTP vocabulary) that maps unambiguously to SHACL | An authoring / review surface for policy officers; SHACL remains the published artefact |
| 6 — Portability profile | Profile which SHACL constructs UNTP rules may use, so translations to other execution engines (e.g. Cypher / GQL over labelled property graphs) stay manageable | Stack freedom for implementers who do not run a triplestore |
Stage 3 is the post-1.0 specification step. Stages 4–6 are contingent on one another: each is only taken if the previous one leaves a real gap. In particular, a controlled English subset and round-trip (English ↔ SHACL) are not assumed yet — descriptions explain the SHACL first; generating English from SHACL (or SHACL from English) comes later only if sign-off or authoring still demand it.