Define your Data Model

This page will provide instructions for step 1 of designing and publishing a data model on EBSI: defining your data model.

info

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Introduction

Data models are abstract representations that show how data is structured, organised, and related within an information system. They provide a conceptual framework for understanding data, allowing effective design, implementation, and management of information systems.

The data model templates in this section aim to help you ensure that the data needed for your EBSI project is stored, accessed, and processed accurately and efficiently.

When it comes to structuring data for Verifiable Credentials, EBSI adheres to W3C data model standards, as they are permissionless and decentralised. The next section will define and explain how data is structured for W3C Verifiable Credentials.

The W3C Verifiable Credentials data model

This is the basic composition of a W3C-compliant Verifiable Credential. The data model of this verifiable credential has various required and optional properties.

Component	Property	Requirement
Verifiable Credentials that are compliant with the existing standards and recommendations by W3C. Verifiable credentials provide a way for individuals to present and prove claims about themselves without revealing unnecessary personal information.	context	Required
	type	Required
	holder	Required
	credentialSubject	Required
	issuer	Required

Table 2.2.1

Because the W3C standard for Verifiable Credentials is permissionless and decentralised, it is possible to extend the W3C Verifiable Credentials data model to tailor its utility for your use case.

EBSI employs JSON as its default Verifiable Credential format but also allows use cases to use and extend JSON-LD capabilities. By design, EBSI enables use cases to extend the core data model in a controlled and reusable way, fostering interoperability across various domains.

One key extensions of EBSI's core data models includes Verifiable Attestations (VAs), which can be further extended to fit specific use cases.

By default, all data models must extend the foundational VA schema. The data structure diagram below represents the components EBSI uses to extend the W3C-compliant Verifiable Credentials data model.

EBSI's extended Verifiable Credentials data structure

Diagram 2.2.1

Let's look at each data structure component EBSI has extended from the W3C Verifiable Credential to understand its utility on the EBSI infrastructure.

The aim is for you to grasp how to adapt or restructure the data models for the needs of your use case. Further below, you will find templates to help you build your data model. For now, let's take the time to understand each component.

The table below will list each data structure type. For the present purposes, only the properties of the type object will be listed. This shows every level of the extension of the W3C VC data structure.

For a full list of all required and optional properties for each component please click the link in the column 'All other properties'.

Verifiable Credential types	type (name)	Description	Object properties	All other properties
Verifiable Presentation	VerifiablePresentation	Verifiable presentations combine and present information from single or multiple verifiable credentials in a way that the data is verifiable. It is the presentation of a subset of information from the verifiable credentials of a subject.	-	Verifiable Presentation
Verifiable Attestation	verifiableAttestation	A type of verifiable credential containing claims about certain attributes of an entity for uses other than identification or authentication.	Credential Subject	Verifiable Attestation
			Credential Schema
			Credential Status
			Evidence
			Proof
			Terms Of Use
Verifiable Authorisation	VerifiableAuthorisation	Verifiable Authorisation is a Verifiable Attestation (data model) with the following top-level properties in the credentialSubject as defined in the table below.	Credential Subject	Verifiable Attestation
Verifiable Accreditation	VerifiableAccreditation	Issued to Legal Entities. A general schema for Verifiable Accreditations, containing attributes that are the same for all accreditations.	Credential Subject	Verifiable Accreditation
Other Verifiable Attestations	-	Verifiable ID: Type of Verifiable Credentials (VCs) that Legal Entities or Natural Persons can put forward as evidence of who they are.	-	-

Table 2.2.2

REMEMBER

The aim here is to illustrate how EBSI has extended the W3C VC through the data model shown in Diagram 2.2.1 to facilitate use case development on the EBSI infrastructure. Your task below will be to use our template to begin working on developing your own data model that extends the W3C VC for your specific use case.

The table below will list each object outlined in Table 2.2.2 above. The columns will provide the object's name (human and machine-readable), description, properties, and a code example.

Object (human-readable name)	Property	Description	REQUIRED properties	JSON Schema code example
Identifier	id	Globally unique identifiers are tools that allow others to make statements about a specific entity. This specification introduces an optional "id" property for these identifiers. The "id" property facilitates the articulation of statements about particular entities in the verifiable credential.	id	"credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21" }
Credential Status	credentialStatus	This specification defines the following credentialStatus property for the discovery of information about the current status of a verifiable credential , such as whether it is suspended or revoked. Only include this if revocation/suspension is piloted.	id / type	"credentialStatus": { "id": "https://example.edu/status/24", "type": "StatusList2021Entry", "statusPurpose": "revocation", "statusListIndex": "42" }
Credential Schema	credentialSchema	Include a reference to the schema registered in the TSR.	id / type	"credentialSchema": { "id": "https://example.org/examples/degree.json", "type": "FullJsonSchemaValidator2021" }
Evidence	evidence	Contains information about the process which resulted in the issuance of the Verifiable Attestation.	id / type	"evidence": { "id": "https://university.example/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231", "type": ["DocumentVerification"], "verifier": "https://university.example/issuers/14", "evidenceDocument": "DriversLicense", "subjectPresence": "Physical", "documentPresence": "Physical", "licenseNumber": "123AB4567" }
Terms of Use	termsOfUse	The terms of use are a means for both the issuer and the holder to convey the conditions under which a verifiable credential or verifiable presentation was issued. The issuer embeds their terms of use within the verifiable credential, while the holder incorporates their terms of use within a verifiable presentation.	-	"termsOfUse": { "id": "https://api-test.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:zz...", "type": "IssuanceCertificate" }

Table 2.2.3

Define your data model

Hands on!

Now it is time for you to define your data model. To do so, you'll need to complete the four templates below covering the following tasks:

• Context
• Glossary
• Data Model
• Content classes

Context

REQUIRED. Introduce the context of your data model in Data Model Design Template #1, including ownership, where the data model is used and other generic information.

Data Model Design Template #1

Describe Context

Glossary

OPTIONAL. Using Data Model Design Template #2 you can define your glossary and abbreviations.

Data Model Design Template #2

Term	Abbreviations	Definition	Reference
define the term	define the abbreviation if used	term definition	link to the original definition, vocabulary or other reference where readers can find more information

Data Model

REQUIRED. Define the data model or a reference to it.

It is now time to define your data model. Please consult Table 2.2.1 to Table 2.2.3 above, as well as our specifications for each data structure component. These can be found on each subpage of this page.

Data Model Taxonomy

Adhering to EBSI's data model taxonomy ensures that data is stored in a consistent and organised manner. This section presents the structure and rules for defining your data model for EBSI.

Naming convention:

• The author or the use case submitting the schema is responsible for naming it.
• The name cannot include any mention of the version or date of submission.
• The schema's name must match the folder name.

Description convention

Each description must contain a brief summary consisting of:

• The specific item the schema describes.
• The subject the schema pertains to (e.g., verification of documents, products or legal entities).
• The domain or use case the schema is designed for (e.g., education, employment and other relevant contexts)
• The version of the VCDM the schema aligns with (v1.1 or v2.0).
• Ensure that the schema from which it inherits is properly referenced in the schema.json.

EBSI Data Models examples

• For examples of how EBSI defines its data model components, check our Data Model Inventory.

Have questions or want to share feedback regarding data models? Please reach out to EBSI Support Office.

To define your data model please use the rows in Table 2.2.4 below and any other fields that are compliant with the W3C VC specifications to fill in the rows of Data Model Design Template #3 below.

Summary
Name	REQUIRED. Official name of the data model
Type	REQUIRED. Type as used in the Verifiable Credential type property. CamelCase style must be used.
Version	REQUIRED. Data model version. Semantic versioning MUST be used https://semver.org/
Reference	OPTIONAL. One or more references, either to the data model or more information about the data model.
Expires	OPTIONAL. Defines a date and time after which the data model should not be used.
Replaced by	CONDITIONAL. MUST be set if a new version replaces this one.
Owner	REQUIRED. Organisation or person responsible for the data model.
JSON Schema	REQUIRED. Link to the JSON schema in the EBSI JSON Schema Repository.
Examples	REQUIRED. Link to one or more representative examples.

Table 2.2.4

Data Model Design Template #3

Terminology	Description	Type	Other property	Notes
Component	Component description	Component type	Other component property	Component notes

If you have listed certain components that are of type object, then you must define the class of each object using Data Model Design Template #4 below. Please do this for every object (three are listed as examples).

Content Classes

Content Classes for [nameOfTheObject]. The following structure MUST be used to define the data model.

Data Model Design Template #4

Class description: Description of the class goes here. [nameOfTheObjectA]

Property	Description	Type	Format	Cardinality	Validation rules
property	Property definition	Property type	Property format	Property cardinality	Validation rules

Class description: Description of the class goes here. [nameOfTheObjectB]

Property	Description	Type	Format	Cardinality	Validation rules
property	Property definition	Property type	Property format	Property cardinality	Validation rules

Class description: Description of the class goes here. [nameOfTheObjectC]

Property	Description	Type	Format	Cardinality	Validation rules
property	Property definition	Property type	Property format	Property cardinality	Validation rules

If you have listed all required information in this expandable section, it is complete.

Once you have defined your data model, the next step is to convert it into a JSON Schema. Given that you have already defined the properties, relationships, types, and formats in the data model template, this transformation should be straightforward. This takes us to the second phase of the section: defining your JSON Schema.