Motivation

The [[VSC-REQUIREMENTS]] document established that global supply chains face three structural gaps: fragmentation of event data formats, absence of cryptographic verifiability, and growing regulatory pressure from [[DSCSA]], [[EUDR]], [[EU-DPP]], and [[CBAM]]. The present specification addresses the fragmentation gap by providing a standardized, implementable bridge between the dominant supply chain event standard ([[EPCIS20]]) and the W3C Verifiable Credentials ecosystem.

The VSC Interoperability Toolkit ("the Toolkit") comprises three interlocking components:

1. The VSC Translation API — a set of HTTP endpoints, based on [[VC-API]], that accept [[EPCIS20]] event documents and return signed [=Verifiable Credential=]s (and vice versa).
2. The EPCIS-VC Mapping Rules — normative, field-level transformation rules for all five [[EPCIS20]] event types, including round-trip fidelity requirements.
3. The VSC Conformance Test Suite (VSC-CTS) — a machine-executable test harness, structured around the model established by [[TRACE-INTEROP]] and the W3C VC Data Model test suites, that allows any implementation to demonstrate compliance and report interoperability results.

Relationship to Prior Art

The VSC Toolkit is intentionally downstream of and compatible with:

• [[TRACE-INTEROP]] (W3C CCG, Dec 2024): Defines discovery and exchange mechanisms for supply chain VCs. VSC inherits its HTTP authentication model (OAuth 2.0 Client Credentials), its Postman/GitHub Actions test harness pattern, and its conformance vs. interoperability report separation. VSC extends it with normative EPCIS translation rules and sector-specific profiles.
• [[VC-API]] (W3C CCG): The VSC Translation API is a profile of the VC-API, adding EPCIS-specific request/response fields and error codes without breaking VC-API conformance.
• [[VC-DATA-MODEL]] (W3C Rec, May 2025): All VSC credentials are conformant VC Data Model 2.0 documents.
• [[EPCIS20]] / [[ISO19987]] (GS1/ISO, June 2022): The authoritative source of event semantics and the five EPCIS dimensions preserved in all VSC credentials.

Document Structure

• — normative language and conformance classes
• — key terms
• — component architecture and information flow
• — VSC Translation API specification
• — EPCIS-to-VC and VC-to-EPCIS mapping rules
• — supported cryptographic proof formats
• — sector-specific conformance profiles
• — VSC Conformance Test Suite architecture
• — error codes and error response schema
• — security considerations
• — privacy considerations
• — contribution guidelines

Conformance Classes

This specification defines four conformance classes. An implementation declares which class(es) it conforms to; each class has its own mandatory test subset in the VSC Conformance Test Suite.

VSC-MAPPER VSC Mapper

A software component that transforms [[EPCIS20]] event documents into VSC-conformant [=Verifiable Credential=] documents (forward mapping) and/or transforms VSC credentials back into valid [[EPCIS20]] documents (reverse mapping). A VSC Mapper MUST implement at least the forward mapping for all five [[EPCIS20]] event types as defined in .

VSC-ISSUER VSC Issuer

A system that accepts a VSC Translation API issue request, generates a signed [=Verifiable Credential=], and returns it. A VSC Issuer MUST implement the POST /credentials/issue endpoint as specified in and MUST support at least one proof format listed in .

VSC-VERIFIER VSC Verifier

A system that accepts a VSC Translation API verify request and returns a structured verification result. A VSC Verifier MUST implement the POST /credentials/verify and POST /presentations/verify endpoints as specified in .

VSC-HARNESS VSC Test Harness

A system that executes the VSC Conformance Test Suite against one or more implementations and produces a conformance or interoperability report in the format defined in . A VSC Test Harness MUST implement all mandatory test categories defined in .

A single software system MAY simultaneously conform to multiple conformance classes. For example, a "VSC Broker" that translates, issues, and verifies credentials would conform to VSC-MAPPER, VSC-ISSUER, and VSC-VERIFIER.

Overview

The Toolkit is positioned as an interoperability layer between existing supply chain systems and the W3C Verifiable Credentials ecosystem. The three principal components and their interactions are illustrated below.

  ┌─────────────────────────────────────────────────────────┐
  │              EXISTING SUPPLY CHAIN SYSTEMS              │
  │   ERP · WMS · EPCIS Repository · Logistics Platform    │
  └──────────────────────┬──────────────────────────────────┘
                         │  EPCIS 2.0 JSON-LD / XML
                         ▼
  ┌────────────────────────────────────────────────────────┐
  │             VSC TRANSLATION API (§5)                   │
  │  POST /epcis/translate   →  VSC Credential (JSON-LD)   │
  │  POST /credentials/issue →  Signed VSC Credential      │
  │  POST /credentials/verify→  Verification Result        │
  │  POST /presentations/verify→Presentation Result        │
  │  GET  /epcis/extract     ←  EPCIS 2.0 re-extraction    │
  └──────────┬─────────────────────────────────────────────┘
             │
     ┌───────┴───────────────────────┐
     │  EPCIS-VC MAPPING RULES (§6)  │
     │  Field map · type coercion    │
     │  CBV→VC vocab · round-trip    │
     └───────┬───────────────────────┘
             │
     ┌───────┴───────────────────────┐
     │  PROOF LAYER (§7)             │
     │  EdDSA (eddsa-rdfc-2022)      │
     │  ECDSA (ecdsa-rdfc-2019)      │
     │  VC-JWT (ES256/ES384)         │
     │  SD-JWT (selective disclose)  │
     └───────────────────────────────┘
             │
     ┌───────┴───────────────────────┐
     │  VSC CONFORMANCE TEST SUITE   │
     │  (§8)                         │
     │  Conformance · Interop        │
     │  Positive · Negative          │
     │  Round-trip fidelity          │
     └───────────────────────────────┘
      

Deployment Models

The Toolkit supports three deployment models. All are normatively equivalent; the API surface is the same in each.

Sidecar

The VSC Translation API runs as a microservice alongside an existing EPCIS repository. Events are translated on write or on demand via a query endpoint.

Embedded SDK

The mapping rules are embedded in a supply chain platform's own code, which calls the Translation API internally or exposes the same API surface externally.

Hosted Service

A third-party VSC provider offers the Translation API as a managed service. Authorization uses OAuth 2.0 Client Credentials as specified in .

Authentication and Authorization

All VSC Translation API endpoints MUST be protected. Implementations MUST support OAuth 2.0 Client Credentials Grant (RFC 6749 §4.4) as the baseline authorization mechanism, consistent with [[TRACE-INTEROP]]. Implementations SHOULD additionally support HTTP Message Signatures (RFC 9421) for machine-to-machine scenarios where OAuth infrastructure is unavailable.

Implementations MUST NOT expose endpoints over plain HTTP (non-TLS). TLS 1.2 or later is REQUIRED on all VSC Translation API connections.

Base URL and Versioning

The API MUST be versioned. The base path MUST include the major version number conforming to [[SEMVER]]:

Breaking changes MUST increment the major version. Non-breaking additions MUST increment the minor version. The current version of this specification defines the v1 API surface.

EPCIS Translation Endpoints

The following endpoints are specific to the VSC Toolkit and extend [[VC-API]].

// REQUEST — ObjectEvent (commissioning)
POST /vsc/v1/epcis/translate
Content-Type: application/json
Authorization: Bearer <token>

{
  "@context": ["https://ref.gs1.org/standards/epcis/epcis-context.jsonld"],
  "type": "ObjectEvent",
  "eventTime": "2026-04-15T09:00:00.000Z",
  "eventTimeZoneOffset": "+00:00",
  "epcList": ["https://id.gs1.org/01/09506000134376/21/12345"],
  "action": "ADD",
  "bizStep": "https://ref.gs1.org/cbv/BizStep-commissioning",
  "disposition": "https://ref.gs1.org/cbv/Disp-active",
  "readPoint": {"id": "https://id.gs1.org/414/9506000000000"},
  "bizLocation": {"id": "https://id.gs1.org/414/9506000000000"}
}

// RESPONSE — Unsigned VSC Credential
HTTP/1.1 200 OK
Content-Type: application/vc+ld+json

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://w3c-cg.github.io/vsc/contexts/v1"
  ],
  "type": ["VerifiableCredential", "VSCObjectEvent"],
  "issuer": "did:web:ISSUER_DID_PLACEHOLDER",
  "validFrom": "2026-04-15T09:00:00Z",
  "credentialSubject": {
    "epcisEventType": "ObjectEvent",
    "eventTime": "2026-04-15T09:00:00.000Z",
    "epcList": ["https://id.gs1.org/01/09506000134376/21/12345"],
    "action": "ADD",
    "bizStep": "https://ref.gs1.org/cbv/BizStep-commissioning",
    "disposition": "https://ref.gs1.org/cbv/Disp-active",
    "readPoint": "https://id.gs1.org/414/9506000000000",
    "bizLocation": "https://id.gs1.org/414/9506000000000"
  }
}
        

Credential Issuance

A [=VSC Issuer=] implementing this endpoint MUST conform to the [[VC-API]] POST /credentials/issue behaviour, with the following VSC-specific constraints:

• The request body MUST include a credential object that is a valid unsigned VSC Credential (output of /epcis/translate or manually constructed).
• The request MUST include an options object. The following options are defined:
  • proofFormat (string, REQUIRED) — one of "eddsa-rdfc-2022", "ecdsa-rdfc-2019", "jwt", or "sd-jwt" (see ).
  • credentialStatus (boolean, OPTIONAL, default true) — if true, the issuer MUST add a credentialStatus entry using [[VC-BITSTRING-STATUS]].
  • selectiveDisclosureFields (array of strings, OPTIONAL) — field paths within credentialSubject that MUST be made individually disclosable. Only applicable when proofFormat is "sd-jwt".
• The issuer in the credential MUST be a [[DID-CORE]] URI whose DID document is publicly resolvable and contains a verification method matching the proof's key material.
• A successful response MUST include the HTTP header VSC-Proof-Format identifying the proof format used, to support automated test harness detection.

Credential and Presentation Verification

A [=VSC Verifier=] MUST conform to the [[VC-API]] verification behaviour and additionally:

• Check that the credential type includes at least one of the VSC event type strings defined in (e.g., "VSCObjectEvent").
• Validate credentialStatus using [[VC-BITSTRING-STATUS]] if present. A credential with a revoked status MUST be returned as failed with error code VSC_ERR_CREDENTIAL_REVOKED.
• Return a structured VerificationResult as defined in .

{
  "verified": true | false,
  "checks": ["proof", "status", "expiry", "schema"],
  "warnings": [],
  "errors": [
    {
      "code": "VSC_ERR_*",
      "message": "Human-readable description",
      "field": "credentialSubject.bizStep"   // optional field pointer
    }
  ],
  "vscProfile": "pharmaceuticals-dscsa"   // if a conformance profile was applied
}
      

Discovery

Implementations MUST expose a discovery endpoint that returns a [[JSON-SCHEMA]]-validated VSCConfiguration object. Minimum required fields:

{
  "vscVersion": "0.1",
  "conformanceClasses": ["VSC-MAPPER", "VSC-ISSUER", "VSC-VERIFIER"],
  "supportedEpcisEventTypes": [
    "ObjectEvent", "AggregationEvent", "TransformationEvent",
    "TransactionEvent", "AssociationEvent"
  ],
  "supportedProofFormats": ["eddsa-rdfc-2022", "jwt"],
  "supportedProfiles": ["base", "pharmaceuticals-dscsa"],
  "didMethods": ["did:web", "did:key"],
  "statusListSupport": true,
  "translationEndpoints": {
    "forward": "/vsc/v1/epcis/translate",
    "reverse": "/vsc/v1/epcis/extract"
  }
}
    

General Mapping Rules

"@context": [
  "https://www.w3.org/ns/credentials/v2",
  "https://w3c-cg.github.io/vsc/contexts/v1",
  "https://ref.gs1.org/standards/epcis/epcis-context.jsonld"
]
      

Per-Event-Type Mapping Supplement

The following rules supplement the general rules for event-type-specific fields. Fields not listed are passed through unchanged into credentialSubject using their EPCIS JSON-LD property names.

Predecessor Link Property

"credentialSubject": {
  ...
  "vscPredecessor": {
    "id": "https://example.com/credentials/abc123",
    "digestSRI": "sha256-BASE64URLENCODE(sha256(predecessorCredentialBytes))"
  }
}
      

Base Profile (vsc-base)

The base profile requires all five EPCIS event types, eddsa-rdfc-2022 proof format, Bitstring Status List revocation, and [[DID-WEB]] or did:key for issuers. All other profiles extend the base profile.

Pharmaceuticals — DSCSA Profile (pharmaceuticals-dscsa)

Food & Agriculture — EUDR Profile (food-eudr)

Critical Minerals & Manufacturing — CBAM/DPP Profile (critical-minerals-cbam)

Architecture

The VSC-CTS is structured after the model of [[TRACE-INTEROP]] and the W3C VC Data Model 2.0 test suite. It uses:

• Mocha + chai as the JavaScript test runner (Node.js 20+), consistent with existing W3C CCG test suites.
• GitHub Actions for nightly scheduled and on-demand CI execution.
• Postman Collections exported alongside the Mocha suite for manual and enterprise firewall-friendly testing, following the [[TRACE-INTEROP]] approach.
• JSON [=Test Vector=] files for each normative assertion, stored in test-suite/vectors/.

Test Categories

Round-Trip Test Vectors

Round-trip fidelity (MAP-G6) is verified using a canonical set of [[EPCIS20]] test vectors, one per event type, stored in the repository at test-suite/vectors/roundtrip/. Each vector is a JSON file containing:

• id — globally unique vector identifier (e.g., vsc-rt-obj-001)
• normativeRef — clause exercised (e.g., MAP-G6)
• epcisInput — the canonical [[EPCIS20]] event
• expectedVscTypes — the expected type array in the produced credential
• mandatoryFields — list of credentialSubject paths that MUST be present and value-equal

The initial set of round-trip vectors covers all five event types and at minimum the following bizStep values from [[CBV20]]: commissioning, shipping, receiving, inspecting, transforming, and sensor_reporting.

Reporting Format

The [=VSC Test Harness=] MUST produce two distinct report types:

Conformance Report

Tests a single implementation against all mandatory test vectors for its declared conformance class(es). Produced as a machine-readable JSON file at reports/conformance/<impl-id>-<date>.json and a human-readable HTML summary.

Interoperability Report

Tests two or more independent implementations against each other on the INTEROP test category scenarios. Produced at reports/interoperability/<date>.json. An implementation is eligible for listing in the VSC Interoperability Registry only after passing the Interoperability Report with at least one other independent implementation.

The report JSON schema is defined in test-suite/schemas/report-schema.json and follows the structure established by [[TRACE-INTEROP]].

Implementation Registration

Any organization wishing to have their implementation tested against the VSC-CTS MUST:

1. Submit a pull request to test-suite/implementations/<org-name>.json containing endpoint URLs, supported conformance classes, supported proof formats, and OAuth 2.0 client credential configuration (using GitHub Secrets for sensitive values).
2. Confirm acceptance of the W3C Community CLA.
3. Ensure the registered endpoint is accessible from GitHub Actions runners. Implementations MAY use an allowlisted outbound IP range to restrict access to GitHub's CI infrastructure.