Skip to content

Clarify VCDM Version Requirements: Resolve Inconsistency Between v1.1 and v2

Created by: ashleythedeveloper

Impacted sections

Issue Description

The current UNTP specification shows inconsistent requirements regarding which VCDM (Verifiable Credentials Data Model) version implementers must support:

  • v1.1 is marked as MUST
  • v2 is marked as SHOULD

MUST implement the W3C VC Data Model v1.1 using the JSON-LD Compacted Document Form SHOULD implement the W3C VC Data Model v2.0 using the JSON-LD Compacted Document Form

Current Challenges

  1. Bitstring Status List Compatibility
    • UNTP requires bitstring status lists
    • Bitstring status list specification requires VCDM v2
    • This creates an implicit requirement for v2 support

MUST implement W3C VC Bitstring Status List for credential status checks including revocation checks

  1. Schema Validation Conflicts
    • UNTP schemas enforce v2 VCDM context in the context array using const
    • Credentials conforming only to v1.1 would fail schema validation
    • This effectively makes v2 mandatory despite being marked as SHOULD

Digital Product Passport (DPP) Example:

"@context": {
      "example": "https://test.uncefact.org/vocabulary/untp/dpp/dpp-context.jsonld",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "https://www.w3.org/ns/credentials/v2",
          "https://test.uncefact.org/vocabulary/untp/dpp/0.5.0/"
        ]
      },
      "description": "A list of JSON-LD context URIs that define the semantic meaning of properties within the credential. ",
      "readOnly": true,
      "const": [
        "https://www.w3.org/ns/credentials/v2",
        "https://test.uncefact.org/vocabulary/untp/dpp/0.5.0/"
      ],
      "default": [
        "https://www.w3.org/ns/credentials/v2",
        "https://test.uncefact.org/vocabulary/untp/dpp/0.5.0/"
      ]
    }
  1. Schema Property Name Alignment with VCDM v2
    • The UNTP schemas enforces v2 VCDM temporal property names (validFrom/validUntil) in the data models
    • This creates a property name mismatch when using v1.1 VCDM since the v1.1 VCDM spec references property names (expirationDate/issuanceDate)
    • There are plans to deprecate expirationDate/issuanceDate in favour of (validFrom/issued)/validUntil as observed in the respective footnote, but there is no indication that this has taken place or when it will take place
    • For UNTP implementers, this means:
      • Must use v2 property names in the credential payload to conform with UNTP schemas otherwise they have extended the data model
      • Must understand both v1.1 and v2 property names
      • Need to maintain duplicate temporal property mappings when handling different VCDM versions
    • This adds unnecessary complexity and potential for errors in implementations

Note that validFrom, issued and validUntil have been included within the v1 VCDM context. The v1.1 VCDM spec eludes to deprecating issuanceDate in favour of the issued property, but I can not find any reference to the definition of the issued property in either the v1.1 or v2 VCDM spec.

It is expected that the next version of this specification will add the validFrom property and will deprecate the issuanceDate property in favor of a new issued property.

DPP Schema Example:

"validFrom": {
      "example": "2024-03-15T12:00:00",
      "type": "string",
      "format": "date-time",
      "description": "The date and time from which the credential is valid."
    },
    "validUntil": {
      "example": "2034-03-15T12:00:00",
      "type": "string",
      "format": "date-time",
      "description": "The expiry date (if applicable) of this verifiable credential."
    }
  1. Render Method Context Dependencies
    • UNTP specification states implementations "SHOULD use the renderMethod property as defined in the VC data model (v2)"
    • However, renderMethod is a term defined in the VCDM v2 base context
    • When using VCDM v1.1:
      • Additional context IRI would be required to define the renderMethod term
      • Options include:
        • Adding v2 base context (creating implicit v2 dependency)
        • Creating custom context defining renderMethod
    • Implementation challenges:
      • Complexity increases for v1.1-only implementations
      • Risk of context conflicts or overriding terms
      • Creates indirect dependency on v2 despite v1.1 being MUST support

Context Example:


“renderMethod": {
  "@id": "https://www.w3.org/2018/credentials#renderMethod",
  "@type": "@id"
}

This demonstrates how even SHOULD requirements for v2 VCDM features create practical implementation burdens when maintaining v1.1 compatibility.

  1. Payload Format Variations
    • VCDM v1.1 and v2 have different payload structures when using enveloping proof/external proof secured using JOSE
    • V1.1 uses a nested format with the verifiable credential inside a vc key: {"vc": {...}} as observed in the v1.1 spec (see note below)
    • V2 uses a flattened format where the credential is directly at the top level: {...} as observed in v2 VCDM and JOSE spec
    • This difference introduces additional complexity for implementers who must:
      • Develop parsing logic to handle both payload structures
      • Ensure proper extraction and validation of credentials across different representations
    • The payload format divergence further compounds the versioning challenges, adding another layer of complexity to maintaining cross-version compatibility

Note that the v1.1 VCDM spec states:

This specification introduces two new registered claim names, which contain those parts of the standard verifiable credentials and verifiable presentations where no explicit encoding rules for JWT exist.

But the JOSE spec only speaks of securing v2 VCDM credentials, creating uncertainty about what the payload of the JWT should be (nested or flattened).

Impact

  • Implementers following the current specification will produce non-compliant credentials
  • Mixed version support creates unnecessary complexity
  • Schema validation will reject v1.1-only credentials

Questions to Address

  1. Should we update the specification to require v2 VCDM exclusively?

Proposal

Consider updating the specification to:

  1. Mark VCDM v2 as MUST
  2. Either deprecate or remove v1.1 support

Additional Context

This issue affects ongoing schema development work to support extensions and test harness development used to ensure conformance with the UNTP specification and needs resolution as soon as possible.