Product Passports

Product passports are the core entity of VERA. They are digital representations of products, containing essential information about their lifecycle, attributes, and compliance with standards. Product passports enable transparency and traceability across the supply chain, allowing stakeholders to access and verify product information easily.

Core Entity

The product passport entity is an abstraction of the digital product passport concept, offering a unified interface to create and interact with the actual instantiations of the product passport according the ecosystem within which the instance is active.

Field	Type	Description
id	String (UUID)	Internal Unique identifier
name	String	Name of the product passport
meta	Json	Additional metadata - DPP Page Display Data
ecosystem	Enum	Ecosystem type (e.g., SSI, CatenaX)
masterData	ProductMasterData?	Associated master data
identifiers	ProductIdentifier[]	Product identifiers
actions	ProductPassportAction[]	Actions/events related to the passport
createdAt	DateTime	Creation timestamp
updatedAt	DateTime	Last update timestamp

Product Identifier

The product identifier is a unique identifier for the product passport, which can be used to track and manage the product throughout its lifecycle. These identifiers can include various types, such as GTIN, VIN, or custom identifiers.

Field	Type	Description
id	String (UUID)	Unique identifier
kind	String	Identifier type (e.g., GTIN, GS1, DID)
value	String	Identifier value
contents	Json (optional)	Additional identifier data
passport	ProductPassport	Linked product passport
createdAt	DateTime	Creation timestamp
updatedAt	DateTime	Last update timestamp

Note: The kind field is a soft enum, meaning it can be extended with custom values as needed.

Note: The combination of the value and kind fields should be unique within the context of the product passport.

Product Passport Action

The product passport action represents an event or action related to the product passport, such as creation, update, or deletion. It provides a history of changes and interactions with the product passport.

Field	Type	Description
id	String (UUID)	Unique identifier
nonce	String	Unique action nonce
type	Enum	Action type (e.g., Create, Update, Delete)
ecosystem	Enum	Ecosystem (e.g., SSI, CatenaX)
state	String	Action state (e.g., Pending, Completed)
payload	Json	Action payload
result	Json	Action result
passport	ProductPassport	Linked product passport
createdAt	DateTime	Creation timestamp
updatedAt	DateTime	Last update timestamp

To perform changes on the underlying product passport instance, a product passport action can be created. This will trigger the creation, update or deletion of the actual product passport instance in the respective ecosystem.

Create a Product Passports

A product passport can be created using the following endpoint:

Example request

POST {{baseUrl}}/core/product-passports?organizationId={{organizationId}}
DATA
{
  "name": "<string>",
  "ecosystem": "<string>",
  "meta": {
    "display": {
      "name": "<string>",
      "description": "<string>"
    }
  },
  "masterDataId": "<string>",
  "identifiers": [
    {
      "kind": "<string>",
      "value": "<string>"
    },
    {
      "kind": "<string>",
      "value": "<string>"
    }
  ],
  "payload": {
    "createWalletParams": {
      "profileId": "<string>",
      "name": "<string>",
      "tags": [
        "<string>",
        "<string>"
      ],
      "settings": {
        "displayConfig": {
          "title": "<string>",
          "subtitle": "<string>",
          "description": "<string>",
          "slogan": "<string>",
          "imageUrl": "<string>",
          "logo": "<string>",
          "primaryColor": "<string>",
          "secondaryColor": "<string>"
        }
      }
    },
    "createDPPCredentialsParams": [
      "<array>",
      "<array>"
    ]
  }
}

The payload field can contain the payload used to create the product passport instance in the respective ecosystem.

Product Identifiers can be provided in the identifiers field, which will be linked to the product passport upon creation. The masterDataId field can be used to link the product passport to a specific product master data instance.

The creation of a product passport entity automatically creates an action of type Create. This will trigger the creation of the actual product passport instance in the respective ecosystem. In the case of the SSI ecosystem, this will create a wallet with the specified profileId, a DID and the associated credentials defined in the createDPPCredentialsParams.

Update a Product Passport

Updating a product passport can be done using the following endpoint:

Example request

PUT {{baseUrl}}/core/product-passports/{{productPassportId}}?organizationId={{organizationId}}
DATA
{
  "name": "<string>",
  "meta": {
    "display": {
      "name": "<string>",
      "description": "<string>"
    }
  },
  "identifiers": [
    {
      "kind": "<string>",
      "value": "<string>"
    },
    {
      "kind": "<string>",
      "value": "<string>"
    }
  ]
}

This endpoint only allows to change the identifiers and the name of the product passport. Performing actual changes on the product passport instance has to be done through the creation of a product passport action.

To update the contents of a product passport, a product passport action with the type Update can be created. This action will trigger the necessary changes in the underlying product passport instance.

The following example show the creation of an Update action in the SSI ecosystem:

Example request

POST {{baseUrl}}/core/product-passport-actions/ssi/update?organizationId=<string>
DATA
{
  "passportId": "<string>",
  "payload": {
    "templateId": "<string>",
    "data": {}
  }
}

This will create an action of type Update for the product passport with the specified passportId. The payload field contains the data that will be used to update the product passport instance in the SSI ecosystem.

Concretely, this action triggers the creation of a credential issuance with the organization DID as issuer and the product passport DID as holder (See the credential-exchange page)