Graph Validation

info

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

Draft guidance

This page sets the intended direction for UNTP graph validation. It is guidance, not a finished specification, and does not define any tooling or conformance regime.

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.

UNTP will use SHACL as the normative 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.

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 core, industry extensions, regulators, individual buyers — can each publish their own shapes, and a verifier simply validates against the union of the ones 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 Mix claim, 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.

note

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.

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 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:

@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://vocabulary.uncefact.org/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. How UNTP handles "currently valid" consistently is an open question for the normative work.

Authoring shapes with LLM assistance

Non-normative

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:comment is what non-technical stakeholders rely on, so it must describe what the shape actually does.

Roadmap

Graph validation is intentionally staged. SHACL is settled as the normative constraint language; what remains is how rules are published, reviewed by non-technical stakeholders, and made portable across implementation stacks. Progress is discussed in the Technical Working Group.

Stage	Focus	Outcome
1 — Direction (this page)	SHACL as the normative method; every shape carries a human-readable description (rdfs:comment / sh:message); optional LLM checks that description and shape still say the same thing	Shared architectural decision, without locking a full specification before it is ready
2 — Normative specification	A dedicated specification page (on the Work in Progress site, after the v0.7.0 line) that defines requirements, the annotation conventions, a core UNTP rule set, and how industry / geography / organisation communities layer additional shapes on top	Versioned, citable graph validation rules that implementers can reuse
3 — Presentation layer	Improve how non-technical stakeholders read shapes — starting with mandatory 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 normative source
4 — 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
5 — 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

Stages 3–5 are contingent: each is only taken if the previous stage leaves a real gap. In particular, a controlled English subset and round-trip (English ↔ SHACL) are not assumed yet — descriptions explain the normative SHACL first; generating English from SHACL (or SHACL from English) comes later only if sign-off or authoring still demand it.