EDCI Standards

Apart from the default white and blue European Digital Credential (EDC) template, a Verifiable Credential can contain its specific version of the EDC to support a customised look and feel. The EDCI Viewer displays an HTML representation of the credential, which is why this custom credential will be built in HTML + CSS (no JS) inside the EDC's XML structure, and will use wildcards to choose EDC content (credential subject's name, titles, descriptions, etc.) and to show EDC non-related translatable labels ("certifies that", "has achieved", etc.)

In the Verifiable Credential XSD standard (see Generic schema XSD), there is a specific section for managing credential customisation:

• <background/>: See MediaObject definition in the European Credential Data Model. For a proper display, image used must have a din A4 ratio.
• <html/>: This html portion will be included in the EDCI Viewer in a div that ensures din A4 ratio and the background image set as background. So the resulting HTML in EDCI Viewer will be:
• <labels/>: Used to define a set of multilanguage labels.

There are two different kinds of wildcards: the ones extracting data from the European Learning Model, and the ones to display custom labels.

In order to reach any Data Model value, XML Path Language version 1.0 (XPath 1.0) must be used in the html wrapped around braces.

Also, labels can be included manually at the <labels> tag of the credential, and then use the key attribute of those labels to reference de html.

The issuer provides the option to upload credentials using an XML file with a special format.  

This format allows to upload multiple credentials in the same file, by specifying those in XML format, and wrapping them in a <europassCredentials> tag. Find below an example of an upload file:

<europassCredentials>

<!-- Credential 1-->

<europassCredential xmlns=”http://data.europa.eu/snb” xmnls:cred=”http://data.europe.eu/europass/model/credentials/w3c#>

<!--Credential 1 Content-->

</europassCredential>

<!--Credential 2-->           <europassCredential xmlns=”http://data.europa.eu/snb” xmnls:cred=”http://data.europe.eu/europass/model/credentials/w3c#>

<!-- Credential 2 Content-->

</europassCredential>

<!--Credential N...-->

</europassCredentials>

Keep in mind that this is not an XML file, but the credentials inside the <europassCredentials> tags must be a valid credential xml following the European Learning Model, and must contain the appropriate namespaces, as in the example above. When uploading, the file will be split, and all the credentials will be processed individually.

Also, it is mandatory that the credentials are not signed to be processed.

A Wallet Address is a pair of keys that form a unique identifier: the wallet URL and the user ID. Each instance of a Wallet API on a server must have a different wallet URL that indicates the server in which the instance of the wallet API resides. Each Wallet server will contain a set of wallets related to users by the userId field.

When creating a wallet, the API will respond with a json containing the wallet address in {walletURL}/{userID} format.

After that, the Wallet Address components are used in a set of REST endpoints to manage the wallet, add credentials or create sharelinks.

There are two main entry points for depositing a credential into a wallet, depending on which information is known at the time of the despoit. The userId endpoint which allows for depositing a credential by knowing the userId of the wallet, and the email endpoint which allows for the same using the email registered for the wallet.

• UserID Endpoint:

Depositing credentials in the wallet is done through a POST call to the

/edci-wallet/api/v1/wallets/{userId}/credentials endpoint, placing the appropiate userId in the {userId} placeHolder.

This endpoint accepts a parameter named “_credentialXML” containing the credential file in XML format. Keep in mind that this endpoint is not protected, and because of this it can be called from anywhere without restrictions.

The userID must correspond to a wallet which already exists on the server, otherwise an error will be returned as there is no wallet creation done in this endpoint.

If there is an error during the process, it will be returned in JSON format, otherwise wallet will respond with a JSON containing the uuid and viewerURL of the credential .

• Email Endpoint:

Depositing credentials in the wallet can also be done through a POST call to the /edci-wallet/api/v1/wallets/email/{email}/credentials  endpoint, placing the appropiate email in the {email} placeholder.

Once again, a parameter named “_credentialXML” containing the credential file is required, and as with previous endpoint, this can be called freely without restrictions, as there is no securization for this endpoint.

One particularity of this endpoint is that it allows to send credentials to a user email that does not have yet a wallet, creating a temporal wallet. Once a wallet is created with the email assigned to the temporal wallet, this will be activated.

Similar to the userId endpoint, if an error is thrown it will be returned in JSON format, otherwise the wallet will respond with a JSON, this time containing only the UUID.

The EDCI wallet can also be used to generate Verifiable Presentations from a credential, either from an XML file or a credential already stored in a wallet.

This can be done either through a viewer which is connected to the desired wallet, in which case the user can download an XML verifiable presentation while visualizing the credential in the viewer.

Also, a verifiable presentation can be generated, by using one of two endpoints in the Wallet REST API, depending if the credential is stored on a wallet or in an XML file:

• Wallet stored credentials endpoint:

A presentation for a credential that is already stored in the wallet can be generated by doing a POST call to the /edci-wallet/api/v1/wallets/{userId}/credentials/verifiable endpoint and changing the “accept” http header o either “application/octet-stream” for XML format or “application/pdf” for PDF format. The body of the request must contain a json with only a “uuid” field, with the uuid of the credential, see example below:

Keep in mind that this endpoint is secured and requires a Bearer Token obtained at the Wallet IDP inside the “authorization” header. Also, only the owner of the credential can generate the verifiable presentation, meaning that the authentication token must belong to the owner.

Any errors that may occur during generation will be returned in JSON format, otherwise the presentation file will be downloaded.

• XML file endpoint:

Another way of generating a presentation is by doing a POST call to the /edci-wallet/api/v1/wallets/credentials/presentation/ endpoint with a “file” parameter containing the credential xml.

To change the format of the verifiable presentation, use the “accept” http header and set it to either “application/octet-stream” for XML or to “application/pdf” for the PDF format.

This endpoint is not secured and can be called freely by any other application.