Design your data model

The subsection will guide you in designing the data model that structures the data in your Trust Chain. The goal is to design your data structure, define your JSON schemas, and finally publish the schemas on EBSI.

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.

Now it is time to develop the data model for your EBSI project. You can define and register your data model in three simple steps.

Define your data model
Define your JSON Schema
Publish the schema on EBSI

The following section will detail how to complete all three steps.

Step 1. Understanding the Verifiable Credentials data model

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

Hands on!

1 - Define your data model

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 Section 2 Template #6, including ownership, where the data model is used and other generic information.

Section 2 Template #6

Describe Context

Glossary

OPTIONAL. Using Section 2 Template #7 you can define your glossary and abbreviations.

Section 2 Template #7

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 Section 2 Template #8 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

Section 2 Template #8

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 Section 2 Template #9 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.

Section 2 Template #9

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.

Step 2. Define your JSON Schema

All EBSI schemas are based on the JSON Schema specifications version 2020-12. If your project is developing a use case on EBSI, you must define a JSON Schema.

Introduction to JSON Schemas on EBSI

EBSI use cases must define a JSON schema for their data model to ensure interoperable data validation and to express accreditation information. Use cases may define and use their vocabularies, internationalisation, and other capabilities. When doing so, use cases should define and maintain a JSON-LD context and proper semantics. The EBSI model also supports JSON-LD, facilitating the distribution of the context and aiding use cases in defining their contexts. Schemas are extendable by default, and all schemas must extend from the baseline of Verifiable Attestation.

The W3C Verifiable Credential data model is distinguished by two types of type-driven relationships:

The root type defines the contextual "is a" relationship.
The field-specific type extensions define "has a" relationships.

Both root type and type extensions may define additional properties but must always follow the original definition requirements. Each underlying schema can be translated to the object it represents. This means every existing schema can be read as a Verifiable Attestation, as all schemas must extend it.

All schemas are based on JSON Schema specifications version 2020-12. The 2020-12 version is not backwards compatible with older drafts.

Storing schemas on EBSI

Every JSON Schema developed for EBSI projects is stored and maintained in EBSI's JSON Schema repository.

Examples from the multi-university pilot can be found here.

Reference existing schemas: Additionally, you can reference the EBSI Bitbucket repository for existing schemas and their specifications.

Hands on!

Your JSON Schema should clearly define the properties and constraints of the data elements you defined in Step 1: Define your data model. You should use standardised vocabularies, available on dedicated websites, to define the semantics of the properties. This approach ensures that the terminology used to describe the concepts remains consistent and unambiguous. If necessary, you can create a mapping file to provide translations for property names and descriptions in different languages.

Use the table in the template below to list all of your data model JSON schemas.

Use case-specific schemas

Let's use a verifiable ID (Natural Person) as an example of what information is required for Step 3: Publish the schema on EBSI. Use Section 2 Template #10 to list all of your JSON schemas.

Section 2 Template #10

Verifiable Credential name	Use case	Data model	Schema & Examples	Trusted Schemas Registry (TSR)
Verifiable ID (Natural Person)	SSI	data model	Natural Person Verifiable ID	TSR record (pilot)

Your next task is to write the code found in the Schema & Examples field.

Before registering your schema, it is important to verify its compliance with the JSON Schema guidelines.

Verifiable ID - JSON Schema code example

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "EBSI Natural Person Verifiable ID",
  "description": "Schema of an EBSI Verifiable ID for a natural person",
  "type": "object",
  "allOf": [
    {
      "$ref": "../../../ebsi-attestation/2022-11/schema.json"
    },
    {
      "properties": {
        "credentialSubject": {
          "description": "Defines additional information about the subject that is described by the Verifiable ID",
          "type": "object",
          "properties": {
            "id": {
              "description": "Defines the DID of the subject that is described by the Verifiable Attestation",
              "type": "string",
              "format": "uri"
            },
            "familyName": {
              "description": "Defines current family name(s) of the credential subject",
              "type": "string"
            },
            "firstName": {
              "description": "Defines current first name(s) of the credential subject",
              "type": "string"
            },
            "dateOfBirth": {
              "description": "Defines date of birth of the credential subject",
              "type": "string",
              "format": "date"
            },
            "personalIdentifier": {
              "description": "Defines the unique national identifier of the credential subject (constructed by the sending Member State in accordance with the technical specifications for the purposes of cross-border identification and which is as persistent as possible in time)",
              "type": "string"
            },
            "nameAndFamilyNameAtBirth": {
              "description": "Defines the first and the family name(s) of the credential subject at the time of their birth",
              "type": "string"
            },
            "placeOfBirth": {
              "description": "Defines the place where the credential subjectis born",
              "type": "string"
            },
            "currentAddress": {
              "description": "Defines the current address of the credential subject",
              "type": "string"
            },
            "gender": {
              "description": "Defines the gender of the credential subject",
              "type": "string"
            }
          },
          "required": [
            "id",
            "familyName",
            "firstName",
            "dateOfBirth",
            "personalIdentifier"
          ]
        }
      }
    }
  ]
}

Step 3. Publish the schema on EBSI

Now that you have defined your data model and JSON Schema, you can register it in the Trusted Schemas Registry. Ideally, the schema registration proposal should be put forward by the use case or domain representative, as only schemas recognised within your operational domain should be registered on EBSI. Registration will be carried out by the Support Office (SO), rather than you directly.

Hands on!

To proceed with the registration, you must submit your schema to the EBSI Support Office for review. After a successful review, the SO will then register your schema.

You will need to provide the following information for the registration:

Completed data model templates from Step 1: Define your data model
JSON Schema
Acknowledgement from domain representatives that the schema is recognised within the domain
Appoint a representative and create a Pull Request to add your example to the schema repository. The naming convention for the example should be as follows: EA-v3-{cluster name}-{name of the example}.json.

You now have a registered JSON Schema for your EBSI project. Congratulations!

You can read more information below about schemas or move onto section Signing & Sealing!

Other information about schemas

Summary of the data model and schema lifecycles

Updates and versions

Any change in the JSON Schema that does not relate to JSON Schema annotations is considered a breaking change and requires the registration of a new schema version.

Schema ID

The schema ID must be computed as follows:

Bundle the JSON Schema. Please see here
Remove JSON Schema annotations (like description, title, examples) from the schema. Thus, changing a description will not change the schema ID.
Canonicalise the bundled JSON Schema using JSON Canonicalization Schema (JCS).
Apply the SHA256 hashing algorithm to the canonicalised document.
The schema ID is a multi-base encoded hash from the previous step, with the default encoding of base58btc.

The Trusted Schemas Registry API computes the schema ID upon schema registration.

Schema versions

All schemas must support JSON Schema 2020-12 as most JSON Schema validators and parsers offer support for this version.

More recent versions of the JSON schema can also be used if required.

HELP?

If you need help, please contact EBSI Support Office

Step 1. Understanding the Verifiable Credentials data model​

The W3C Verifiable Credentials data model​

EBSI’s extended Verifiable Credentials data structure​

1 - Define your data model​

Context​

Glossary​

Data Model​

Content Classes​

Step 2. Define your JSON Schema​

Introduction to JSON Schemas on EBSI​

Storing schemas on EBSI​

Use case-specific schemas​

Step 3. Publish the schema on EBSI​

Other information about schemas​

Summary of the data model and schema lifecycles​

Updates and versions​

Schema ID​

Schema versions​

Step 1. Understanding the Verifiable Credentials data model

The W3C Verifiable Credentials data model

EBSI’s extended Verifiable Credentials data structure

1 - Define your data model

Context

Glossary

Data Model

Content Classes

Step 2. Define your JSON Schema

Introduction to JSON Schemas on EBSI

Storing schemas on EBSI

Use case-specific schemas

Step 3. Publish the schema on EBSI

Other information about schemas

Summary of the data model and schema lifecycles

Updates and versions

Schema ID

Schema versions