Extensions Methodology

info

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

Normative

This page describes the technical methodology for creating UNTP extensions. For the governance rules and registration process, see the Community Extensions Register and its registration guide. For sectoral collaboration and harmonisation, see Sectoral Collaboration.

Overview

UNTP is designed as a common core that is usable by any industry sector or in any regulatory jurisdiction. This extensions methodology describes how to extend UNTP to meet the specific needs of any industry sector or regulated market in such a way that the extension maintains core interoperability with any other extension. This cross-industry and cross-border interoperability is a core value of UNTP because almost every value chain will cross industry and/or national borders.

In some cases, UNTP extensions are themselves UN projects - such as the extensions defined by the UN critical raw materials traceability and transparency project. In most cases however, industry sectors and/or national projects will govern their own extensions.

Anyone can take UNTP and extend it for any purpose. But for the extension to be registered as UNTP conformant, an extension MUST remain interoperable with UNTP. This is achieved by following the governance, methodology, and testing processes described below.

Extension Governance

As shown in the diagram below, UNTP development follows the UN/CEFACT Open Development Process (ODP) and is maintained by a group of experts that are approved by their member state delegate. UNTP Intellectual Property is owned by the UN and the standard is available free for anyone to use. There are formal liaisons with other standards bodies including ISO so that UNTP remains aligned with similar initiatives.

Registered UNTP extensions

• MUST follow an open and transparent development process that is open to participation from representative persons and organisations.
• MUST be freely available under a permissive or creative commons license.
• MUST be version managed (major.minor) and each extension version MUST state which UNTP major version from which it is derived.
• MUST be documented as a public website with reference-able URI for each specification component.

Since registered extensions have a clear vested interest in the ongoing development of UNTP, extension groups SHOULD nominate at least one member as a participant in the UNTP Technical Working Group.

Extension Methodology

UNTP extensions must be interoperable with UNTP core. This means that a credential that conforms to a UNTP extension is also conformant with UNTP core. This requirement ensures that credentials issued in a specific industry or geographical context are still understandable across industry or geographic boundaries.

Schema Extensions

UNTP credential JSON schema allow additional properties in most objects to provide flexibility to accommodate industry extensions.

Core Principles:

1. Additive, Not Redefining

   • Extensions MAY add new properties
   • Extensions MUST NOT change existing UNTP core properties
   • Extensions MUST NOT remove core properties

2. Dual Validation

   • Extension instances MUST validate against extension schema
   • Extension instances MUST validate against UNTP core schema
   • Both validations must pass

3. Multiple Variants

   • Extensions MAY define multiple credential variants
   • Example: Agriculture extension defines both livestock passport AND horticulture passport
   • Each variant extends the same UNTP core credential type

Example: Adding Battery-Specific Properties

UNTP Core Digital Product Passport (simplified):

{
  "@context": ["https://www.w3.org/ns/credentials/v2",
               "https://test.uncefact.org/vocabulary/untp/dpp/0.6.0/"],
  "type": ["VerifiableCredential", "DigitalProductPassport"],
  "credentialSubject": {
    "product": {
      "name": "Product Name",
      "description": "Product description",
      "category": {...}
    }
  }
}

Battery Extension Adds Specific Properties:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://test.uncefact.org/vocabulary/untp/dpp/0.6.0/",
    "https://battery-extension.org/context/1.0/"
  ],
  "type": ["VerifiableCredential", "DigitalProductPassport", "BatteryPassport"],
  "credentialSubject": {
    "product": {
      "name": "Lithium-ion Battery Cell",
      "description": "High-density battery cell for EVs",
      "category": {...},
      "batterySpecifications": {
        "capacity": {"value": 75, "unit": "kWh"},
        "chemistry": "NMC811",
        "voltage": {"value": 400, "unit": "V"}
      }
    }
  }
}

Vocabulary Extensions

Industry extensions will often leverage existing industry specific vocabularies. For example an agriculture extension may reference terms from Codex Alimentarius. This is achieved through JSON-LD @context files.

• Each credential defined by a UNTP extension MUST reference a JSON-LD @context file that defines all additional terms.
• JSON-LD @context files defined by a UNTP extension MUST NOT redefine terms in the corresponding UNTP @context file.
• External vocabularies referenced by UNTP extensions SHOULD be stable, version managed, and should not delete terms.

Technical Reference: How Extensions Work

This section explains the mechanism that lets an extension add fields to a UNTP credential without breaking JSON Schema validation, JSON-LD expansion, or downstream linked-data consumers. Extension developers and UNTP-aware implementers who only want to tack on a few extra fields should both read this section.

The two layers that have to agree

A UNTP credential is validated at two layers, and any extension mechanism has to satisfy both:

• JSON Schema controls which properties are allowed on a given object. Open classes declare additionalProperties: true; closed classes declare additionalProperties: false.
• JSON-LD controls how each property name maps to an RDF IRI when the credential is expanded into a graph. A property name that cannot be resolved to an IRI is either silently dropped (default mode) or reported as an error (safe mode).

UNTP aligns the two layers: every class that is open at the JSON Schema layer also has a per-class @vocab fallback in the JSON-LD context, so unknown keys resolve to a stable IRI instead of being dropped.

Open vs closed classes

Open classes accept extension keys. The JSON Schema permits unknown properties, and the JSON-LD context declares a class-scoped @vocab that points at the class's own vocabulary page using the fragment form (for example https://vocabulary.uncefact.org/untp/Product#). Unknown keys become fragment identifiers on that page, which means the containing class's documentation is where an HTTP client lands when it tries to dereference an extension IRI — the class's vocabulary description serves as the explanation for why the fragment is not a curated term. The currently-open classes are:

Product, Facility, Party, CredentialIssuer, Entity, ConformityScheme, ConformityProfile, Criterion, Claim, Characteristics, ConformityAttestation, ConformityAssessment, Endorsement, ScoringFramework, Regulation, Standard, Material, Package, LifecycleEvent, MakeEvent, MoveEvent, ModifyEvent, RegisteredIdentity, Location, FacilityVerification, ProductVerification, plus the five credential wrappers (DigitalProductPassport, DigitalConformityCredential, DigitalFacilityRecord, DigitalIdentityAnchor, DigitalTraceabilityEvent).

Closed classes reject extension keys. These represent pure data shapes whose semantics are fully specified — adding a property would create ambiguity:

Measure, Dimension, Coordinate, Period, Address, Country, Classification, Score, Link, Image, PartyRole, SensorData, StandardAlignment, RegulatoryAlignment, Performance, IdentifierScheme, BitstringStatusListEntry, RenderTemplate2024, EventProduct, MaterialUsage, PerformanceMetric, ConformityTopic.

If you find yourself wanting to extend a closed class, extend the containing open class instead. For example, don't try to add a property to an embedded Measure; add a sibling property on the Product that carries the extra context.

Default behaviour: automatic per-class namespacing

An extension property added to an open class — with no special setup — expands into the class's synthetic namespace. For example, adding partNumber to a Product:

{
  "type": ["Product"],
  "id": "https://manufacturer.example/p/42",
  "name": "Battery module",
  "partNumber": "BM-18650-3000"
}

produces the triple:

<.../p/42>
  <https://vocabulary.uncefact.org/untp/Product#partNumber>
  "BM-18650-3000" .

The extension key is preserved in the expanded graph, SPARQL and SHACL can target it, and safe-mode validation passes. Each class has its own namespace, so partNumber on a Product and partNumber on a Material land at different IRIs and never collide.

This default works for the 80% case where an implementer has one or two vendor-specific fields to add and does not maintain a formal vocabulary.

Preferred pattern: use your own vocabulary

If your extension is backed by a published industry or organisation vocabulary, redirect extension keys into that namespace by declaring a scoped @context inside the object and using a prefix:

{
  "type": ["Product"],
  "id": "https://manufacturer.example/p/42",
  "name": "Battery module",
  "characteristics": {
    "@context": { "battery": "https://example-industry.org/battery/v1/" },
    "type": ["Characteristics"],
    "battery:batteryChemistry": "NMC 811",
    "battery:batteryCategory": "EV"
  }
}

Here, battery:batteryChemistry expands to https://example-industry.org/battery/v1/batteryChemistry — an IRI owned by the extension body, not by UNTP. The prefix declaration is local to the object; multiple prefixes can coexist in the same document.

This is the pattern extension working groups should document for their implementers. It keeps the extension's semantics under the extension owner's control rather than in UNTP's synthetic fallback namespace.

Curated terms always win

Extension keys never override curated UNTP terms. When the JSON-LD context defines a property explicitly (for example name on a Product expands to https://schema.org/name), that curated definition shadows the @vocab fallback. An implementer cannot inadvertently redefine a UNTP-standard term as something else — JSON-LD's @protected enforcement catches the attempt at context-loading time.

Promoting an extension to a curated UNTP term

If an extension property becomes widely adopted and standardisation is appropriate, the UNTP governance process may promote it to a curated term in a subsequent version of the core vocabulary. When this happens, the property's IRI changes:

• Before promotion: https://vocabulary.uncefact.org/untp/Product#partNumber (per-class synthetic fragment of the containing class's vocabulary page).
• After promotion: https://vocabulary.uncefact.org/untp/partNumber (curated core term).

This is a breaking change for existing consumers. Producers who had been using the extension key will emit the new IRI automatically once they upgrade the context version they reference, but graphs built from older credentials will still carry the old IRI. Treat extension-namespaced IRIs as stable within a specific UNTP context version but subject to rewrite at major version boundaries.

Validating extended credentials

Two tools in this repository check that extensions behave correctly:

• node .claude/scripts/validate-artefacts.mjs — runs JSON Schema validation AND JSON-LD expansion, including safe-mode. Extensions that would drop silently on expansion fail the safe-mode check.
• node .claude/scripts/audit-context.mjs — verifies the extension mechanism itself: that every open class in the context declares a correctly-namespaced @vocab, that property definitions are consistent, and that context terms resolve to ontology entries.

Extension developers SHOULD add their sample instances to the validator's VALIDATIONS array so the build catches regressions in their extension just like it does for core UNTP.

Identifier Schemes

UNTP and it's extensions have a dependency on resolvable and verifiable identifiers. Industry extension will typically define specific identifier schemes (for products, facilities, and organisations) that are relevant for the specific industry and/or geography. For example, Australian livestock are identified by a National Livestock Identifier that is carried as an RFID tag in the animal's ear.

• All identifier schemes used by registered UNTP extensions MUST be registered in the UNTP identifier scheme register.
• Identifiers used by UNTP extensions SHOULD be resolvable and verifiable as defined by the UNTP Identity Resolver specification.

Conformity Criteria

UNTP is deliberately agnostic of specific standards and regulations. The generic Declaration object that is used by DPP, DFR, and DCC credentials is designed to support any conformity criteria defined by any standard or regulation. UNTP extensions, however, will normally agree a specific set of standards and regulations that are applicable in the extension context.

• UNTP extensions MUST list all relevant standards and regulations on the extension specification website.
• The specific conformity criteria within Standards and Regulations referenced by UNTP extensions SHOULD be reference-able as stable URIs.

Extension Conformity Testing

Extension conformity testing ensures that:

• Extension credentials validate against both extension schema AND UNTP core schema
• Extension maintains interoperability with UNTP core
• Extension credentials are readable by other extensions
• Extension follows all methodology requirements

Level 1: Schema Validation

• Extension schema files MUST validate as proper JSON Schema
• Extension instances MUST validate against extension schema
• Extension instances MUST validate against corresponding UNTP core schema
• No validation errors allowed

Tools: Use UNTP Schema Validator at https://test.uncefact.org/test-untp-playground

Level 2: Interoperability Testing

• Extension credentials MUST be processable by UNTP core-compliant systems
• Extension-specific properties MUST NOT break core processing
• Extension credentials MUST render using UNTP generic rendering templates
• Credentials MUST be verifiable using standard VC verification libraries

Tools: Use UNTP Interoperability Test Suite at https://test.uncefact.org/

Level 3: Cross-Extension Testing (Recommended, not required)

• Test credential exchange with other registered extensions
• Verify supply chain data flows across extension boundaries

Conformance Criteria

To achieve UNTP conformance registration, extensions must:

• ✓ Pass all Level 1 schema validation tests
• ✓ Pass all Level 2 interoperability tests
• ✓ Provide test report documenting results
• ✓ Include minimum 2 example credentials for each extension type
• ✓ Publish test cases on extension website

---

Key Terms and Concepts

JSON Schema: A standard format for describing the structure and validation rules for JSON data.

JSON-LD (JSON Linked Data): A method of encoding linked data using JSON. The @context file maps terms to URLs.

@context file: A JSON-LD file that defines the meaning of terms used in credentials.

Verifiable Credential (VC): A tamper-evident credential with authorship that can be cryptographically verified.

Schema Validation: The process of checking whether a data instance conforms to schema rules.

Interoperability: The ability of different systems to exchange and use information.

Identity Resolver: A system that translates an identifier into a URL where information can be found.

Conformity Criteria: Specific requirements from standards or regulations that products/facilities must meet.

Namespace: A way to group related properties together to avoid naming conflicts.

Extension Instance: An actual credential (data) that follows an extension schema.

---