Version: Next

v0.6.0

info

Please note that this content is under development and is not ready for implementation. This status message will be updated as content development progresses.

Overview

This guide covers the migration from UNTP (UN Transparency Protocol) version 0.5.0 to 0.6.0 across all supported data models within the Reference Implementation. The update introduces several structural changes and improvements to schema definitions, data validation patterns, and JSON-LD contexts.

Digital Identity Anchor (DIA)

Summary of Changes

The main change to the Digital Identity Anchor in UNTP 0.6.0 is the same change present for the other UNTP credentials: the credential issuer's otherIdentifier field was changed in name and format. See the details below, together with the other smaller changes that are mostly version number updates.

Data Model Changes

1. JSON-LD Context Updates

Before (0.2.1):

"@context": [
  "https://www.w3.org/ns/credentials/v2",
  "https://vocabulary.uncefact.org/untp/dia/0.2.1/"
]

After (0.6.0):

"@context": [
  "https://www.w3.org/ns/credentials/v2",
  "https://test.uncefact.org/vocabulary/untp/dia/0.6.0/"
]

2. Issuer Identifier Structure Changes

The issuer identifier otherIdentifier property has been replaced with a new issuerAlsoKnownAs property.

Example data structure change:

Before (0.2.1):

{
  "issuer": {
    "type": ["CredentialIssuer"],
    "id": "did:web:identifiers.example-company.com:12345",
    "name": "Example Company Pty Ltd",
    "otherIdentifier": [
      {
        "type": ["Identifier"],
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327",
        "idScheme": {
          "type": ["IdentifierScheme"],
          "id": "https://abr.business.gov.au/ABN/",
          "name": "Australian Business Number (ABN)"
        }
      }
    ]
  }
}

After (0.6.0):

{
  "issuer": {
    "type": ["CredentialIssuer"],
    "id": "did:web:identifiers.example-company.com:12345",
    "name": "Example Company Pty Ltd",
    "issuerAlsoKnownAs": [
      {
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327"
      }
    ]
  }
}

3. RegisteredIdentity Structure Updates

Key Changes:

Removed Identifier type inheritance from RegisteredIdentity

Example: RegisteredIdentity type change

Before (0.2.1):

{
  "credentialSubject": {
    "type": ["RegisteredIdentity", "Identifier"],
    "id": "did:web:samplecompany.com/123456789",
    "name": "Sample business Ltd",
    "registeredId": "123456789",
    "idScheme": {
      "type": ["IdentifierScheme"],
      "id": "https://id.gs1.org/01/",
      "name": "Global Trade Identification Number (GTIN)"
    }
  }
}

After (0.6.0):

{
  "credentialSubject": {
    "type": ["RegisteredIdentity"],
    "id": "did:web:samplecompany.com/123456789",
    "name": "Sample business Ltd",
    "registeredId": "123456789",
    "idScheme": {
      "type": ["IdentifierScheme"],
      "id": "https://id.gs1.org/01/",
      "name": "Global Trade Identification Number (GTIN)"
    }
  }
}

Reference Implementation Updates

1. Schema URL Updates

Before (0.2.1):

"schema": {
  "url": "https://jargon.sh/user/unece/DigitalIdentityAnchor/v/working/artefacts/jsonSchemas/DigitalIdentityAnchor.json"
}

After (0.6.0):

"schema": {
  "url": "https://jargon.sh/user/unece/DigitalIdentityAnchor/v/0.6.0/artefacts/jsonSchemas/RegisteredIdentity.json?class=RegisteredIdentity"
}

2. Context Configuration in Services

Before (0.2.1):

"digitalIdentityAnchor": {
  "context": ["https://test.uncefact.org/vocabulary/untp/dia/0.2.1/"]
}

After (0.6.0):

"digitalIdentityAnchor": {
  "context": ["https://test.uncefact.org/vocabulary/untp/dia/0.6.0/"]
}

3. Form Data Structure Updates

If you're passing pre-populated data into the JsonForm component, update the data structure to conform to the new schema:

Before (0.2.1):

"data": {
  "type": ["RegisteredIdentity", "Identifier"],
  "id": "did:web:samplecompany.com/123456789",
  "name": "Sample business Ltd",
  "registeredId": "123456789",
  "idScheme": {
    "type": ["IdentifierScheme"],
    "id": "https://id.gs1.org/01/",
    "name": "Global Trade Identification Number (GTIN)"
  }
}

After (0.6.0):

"data": {
  "type": ["RegisteredIdentity"],
  "id": "did:web:samplecompany.com/123456789",
  "name": "Sample business Ltd",
  "registeredId": "123456789",
  "idScheme": {
    "type": ["IdentifierScheme"],
    "id": "https://id.gs1.org/01/",
    "name": "Global Trade Identification Number (GTIN)"
  }
}

4. Render Template Updates

Update the render template to use the new 0.6.0 compliant template. The updated template can be found at:

packages/mock-app/src/templates/v0.6.0/digital_identity_anchor/template.hbs

Example template configuration update:

Before (0.2.1):

"renderTemplate": [
  {
    "type": "WebRenderingTemplate2022",
    "template": "{v0.2.1-template}..."
  }
]

After (0.6.0):

"renderTemplate": [
  {
    "type": "WebRenderingTemplate2022",
    "template": "{v0.6.0-template}..."
  }
]

5. VCKit Issuer Structure Updates

Update the VCKit issuer configuration to use the new identifier structure:

Before (0.2.1):

"vckit": {
  "vckitAPIUrl": "http://localhost:3332/v2",
  "issuer": {
    "type": ["CredentialIssuer"],
    "id": "did:web:uncefact.github.io:project-vckit:test-and-development",
    "name": "Example Company Pty Ltd",
    "otherIdentifier": [
      {
        "type": ["Identifier"],
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327",
        "idScheme": {
          "type": ["IdentifierScheme"],
          "id": "https://abr.business.gov.au/ABN/",
          "name": "Australian Business Number (ABN)"
        }
      }
    ]
  },
  "headers": {...}
}

After (0.6.0):

"vckit": {
  "vckitAPIUrl": "http://localhost:3332/v2",
  "issuer": {
    "type": ["CredentialIssuer"],
    "id": "did:web:uncefact.github.io:project-vckit:test-and-development",
    "name": "Example Company Pty Ltd",
    "issuerAlsoKnownAs": [
      {
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327"
      }
    ]
  },
  "headers": {...}
}

Digital Facility Record (DFR)

Summary of Changes

The main changes for Digital Facility Records in UNTP 0.6.0 include:

Enhanced validation patterns: The updated schema validations simplify the extension of UNTP credential types.
Improved identifier structure: Simplified identifier scheme with better organisation and removal of nested idScheme references
Updated JSON-LD contexts: New vocabulary context path structure with improved semantic mappings and vocabulary organisation
Schema refinements: Better property organisation, improved abstraction, and enhanced data model consistency

Data Model Changes

1. JSON-LD Context

Before (0.5.0):

"@context": [
  "https://www.w3.org/ns/credentials/v2",
  "https://vocabulary.uncefact.org/untp/dfr/0.5.0/"
]

After (0.6.0):

"@context": [
  "https://www.w3.org/ns/credentials/v2",
  "https://test.uncefact.org/vocabulary/untp/dfr/0.6.0/"
]

2. Credential Subject Structure

The credentialSubject property has been restructured from a direct Facility reference to a FacilityRecord that contains the facility.

Example data structure change:

Before (0.5.0):

{
  "credentialSubject": {
    "type": ["Facility"],
    "id": "https://id.gs1.org/414/1321202290648",
    "name": "Greenacres battery factory",
    "conformityClaim": [...]
  }
}

After (0.6.0):

{
  "credentialSubject": {
    "type": ["FacilityRecord"],
    "facility": {
      "type": ["Facility"],
      "id": "https://id.gs1.org/414/1321202290648",
      "name": "Greenacres battery factory"
    },
    "conformityClaim": [...]
  }
}

3. Issuer Identifier Structure

The issuer identifier otherIdentifier property has been replaced with a new issuerAlsoKnownAs property.

Example data structure change:

Before (0.5.0):

{
  "issuer": {
    "type": ["CredentialIssuer"],
    "id": "did:web:identifiers.example-company.com:12345",
    "name": "Example Company Pty Ltd",
    "otherIdentifier": [
      {
        "type": ["Identifier"],
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327",
        "idScheme": {
          "type": ["IdentifierScheme"],
          "id": "https://abr.business.gov.au/ABN/",
          "name": "Australian Business Number (ABN)"
        }
      }
    ]
  }
}

After (0.6.0):

{
  "issuer": {
    "type": ["CredentialIssuer"],
    "id": "did:web:identifiers.example-company.com:12345",
    "name": "Example Company Pty Ltd",
    "issuerAlsoKnownAs": [
      {
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327"
      }
    ]
  }
}

4. Facility Structure

Key Changes:

otherIdentifier property replaced with new facilityAlsoKnownAs property
operatedByParty structure simplified from Identifier.

Example: facilityAlsoKnownAs structure change

Before (0.5.0):

{
  "credentialSubject": {
    "type": ["Facility"],
    "otherIdentifier": [
      {
        "type": ["Identifier"],
        "id": "https://id.gs1.org/414/1321202290648",
        "name": "Greenacres battery factory",
        "registeredId": "1321202290648",
        "idScheme": {
          "type": ["IdentifierScheme"],
          "id": "https://id.gs1.org/414/",
          "name": "Global Location Number"
        }
      }
    ]
  }
}

After (0.6.0):

{
  "credentialSubject": {
    "type": ["FacilityRecord"],
    "facility": {
      "type": ["Facility"],
      "facilityAlsoKnownAs": [
        {
          "id": "https://id.gs1.org/414/1321202290648",
          "name": "Greenacres battery factory",
          "registeredId": "1321202290648"
        }
      ]
    }
  }
}

Example: operatedByParty structure change

Before (0.5.0):

{
  "credentialSubject": {
    "type": ["Facility"],
    "operatedByParty": {
      "type": ["Identifier"],
      "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
      "name": "Example Company Pty Ltd.",
      "registeredId": "90664869327",
      "idScheme": {
        "type": ["IdentifierScheme"],
        "id": "https://abr.business.gov.au/ABN/",
        "name": "Australian Business Number (ABN)"
      }
    }
  }
}

After (0.6.0):

{
  "credentialSubject": {
    "type": ["FacilityRecord"],
    "facility": {
      "type": ["Facility"],
      "operatedByParty": {
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327"
      }
    }
  }
}

Reference Implementation Updates

1. Schema URL Updates

Before (0.5.0):

"schema": {
  "url": "https://jargon.sh/user/unece/DigitalFacilityRecord/v/working/artefacts/jsonSchemas/FacilityRecord.json"
}

After (0.6.0):

"schema": {
  "url": "https://jargon.sh/user/unece/DigitalFacilityRecord/v/0.6.0/artefacts/jsonSchemas/FacilityRecord.json?class=FacilityRecord"
}

2. Context Configuration in Services

Before (0.5.0):

"digitalFacilityRecord": {
  "context": ["https://test.uncefact.org/vocabulary/untp/dfr/0.5.0/"]
}

After (0.6.0):

"digitalFacilityRecord": {
  "context": ["https://test.uncefact.org/vocabulary/untp/dfr/0.6.0/"]
}

3. Form Data Structure Updates

If you're passing pre-populated data into the JsonForm component, update the data structure to conform to the new FacilityRecord schema:

Before (0.5.0):

"data": {
  "type": ["Facility"],
  "id": "https://id.gs1.org/414/1321202290648",
  "name": "Greenacres battery factory",
  "operatedByParty": {
    "type": ["Identifier"],
    "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
    "name": "Example Company Pty Ltd.",
    "registeredId": "90664869327",
    "idScheme": {
      "type": ["IdentifierScheme"],
      "id": "https://abr.business.gov.au/ABN/",
      "name": "Australian Business Number (ABN)"
    }
  },
  "conformityClaim": [...]
}

After (0.6.0):

"data": {
  "type": ["FacilityRecord"],
  "facility": {
    "type": ["Facility"],
    "id": "https://id.gs1.org/414/1321202290648",
    "name": "Greenacres battery factory",
    "operatedByParty": {
      "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
      "name": "Example Company Pty Ltd.",
      "registeredId": "90664869327"
    }
  },
  "conformityClaim": [...]
}

4. Render Template Updates

Update the render template to use the new 0.6.0 compliant template. The updated template can be found at:

packages/mock-app/src/templates/v0.6.0/digital_facility_record/template.hbs

Example template configuration update:

Before (0.5.0):

"renderTemplate": [
  {
    "type": "WebRenderingTemplate2022",
    "template": "{v0.5.0-template}..."
  }
]

After (0.6.0):

"renderTemplate": [
  {
    "type": "WebRenderingTemplate2022",
    "template": "{v0.6.0-template}..."
  }
]

5. VCkit Issuer Structure Updates

Update the VCkit issuer configuration to use the new identifier structure:

Before (0.5.0):

"vckit": {
  "vckitAPIUrl": "http://localhost:3332/v2",
  "issuer": {
    "type": ["CredentialIssuer"],
    "id": "did:web:uncefact.github.io:project-vckit:test-and-development",
    "name": "Example Company Pty Ltd",
    "otherIdentifier": [
      {
        "type": ["Identifier"],
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327",
        "idScheme": {
          "type": ["IdentifierScheme"],
          "id": "https://abr.business.gov.au/ABN/",
          "name": "Australian Business Number (ABN)"
        }
      }
    ]
  },
  "headers": {...}
}

After (0.6.0):

"vckit": {
  "vckitAPIUrl": "http://localhost:3332/v2",
  "issuer": {
    "type": ["CredentialIssuer"],
    "id": "did:web:uncefact.github.io:project-vckit:test-and-development",
    "name": "Example Company Pty Ltd",
    "issuerAlsoKnownAs": [
      {
        "id": "https://abr.business.gov.au/ABN/View?abn=90664869327",
        "name": "Example Company Pty Ltd.",
        "registeredId": "90664869327"
      }
    ]
  },
  "headers": {...}
}

Overview​

Digital Identity Anchor (DIA)​

Summary of Changes​

Data Model Changes​

1. JSON-LD Context Updates​

2. Issuer Identifier Structure Changes​

3. RegisteredIdentity Structure Updates​

Reference Implementation Updates​

1. Schema URL Updates​

2. Context Configuration in Services​

3. Form Data Structure Updates​

4. Render Template Updates​

5. VCKit Issuer Structure Updates​

Digital Facility Record (DFR)​

Summary of Changes​

Data Model Changes​

1. JSON-LD Context​

2. Credential Subject Structure​

3. Issuer Identifier Structure​

4. Facility Structure​

Reference Implementation Updates​

1. Schema URL Updates​

2. Context Configuration in Services​

3. Form Data Structure Updates​

4. Render Template Updates​

5. VCkit Issuer Structure Updates​

Overview

Digital Identity Anchor (DIA)

Summary of Changes

Data Model Changes

1. JSON-LD Context Updates

2. Issuer Identifier Structure Changes

3. RegisteredIdentity Structure Updates

Reference Implementation Updates

1. Schema URL Updates

2. Context Configuration in Services

3. Form Data Structure Updates

4. Render Template Updates

5. VCKit Issuer Structure Updates

Digital Facility Record (DFR)

Summary of Changes

Data Model Changes

1. JSON-LD Context

2. Credential Subject Structure

3. Issuer Identifier Structure

4. Facility Structure

Reference Implementation Updates

1. Schema URL Updates

2. Context Configuration in Services

3. Form Data Structure Updates

4. Render Template Updates

5. VCkit Issuer Structure Updates