Skip to main content
European CommissionEBSI European Blockchain
Get Help

Design your data model

Last updated on

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.

  1. Define your data model
  2. Define your JSON Schema
  3. 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.

ComponentPropertyRequirement
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.contextRequired
typeRequired
holderRequired
credentialSubjectRequired
issuerRequired

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 typestype (name)DescriptionObject propertiesAll other properties
Verifiable PresentationVerifiablePresentationVerifiable 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 AttestationverifiableAttestationA type of verifiable credential containing claims about certain attributes of an entity for uses other than identification or authentication.Credential SubjectVerifiable Attestation
Credential Schema
Credential Status
Evidence
Proof
Terms Of Use
Verifiable AuthorisationVerifiableAuthorisationVerifiable Authorisation is a Verifiable Attestation (data model) with the following top-level properties in the credentialSubject as defined in the table below.Credential SubjectVerifiable Attestation
Verifiable AccreditationVerifiableAccreditationIssued to Legal Entities. A general schema for Verifiable Accreditations, containing attributes that are the same for all accreditations.Credential SubjectVerifiable 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)PropertyDescriptionREQUIRED propertiesJSON Schema code example
IdentifieridGlobally 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 StatuscredentialStatusThis 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 SchemacredentialSchemaInclude a reference to the schema registered in the TSR.id / type
"credentialSchema": {
  "id": "https://example.org/examples/degree.json",
  "type": "FullJsonSchemaValidator2021"
}
EvidenceevidenceContains 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 UsetermsOfUseThe 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

TermAbbreviationsDefinitionReference
define the termdefine the abbreviation if usedterm definitionlink 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.
  • The version of the VCDM the schema aligns with (v1.1 or v2.0).

EBSI Data Models examples

  • For examples of how EBSI defines its data model components, click here.

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
NameREQUIRED. Official name of the data model
TypeREQUIRED. Type as used in the Verifiable Credential type property. CamelCase style must be used.
VersionREQUIRED. Data model version. Semantic versioning MUST be used https://semver.org/
ReferenceOPTIONAL. One or more references, either to the data model or more information about the data model.
ExpiresOPTIONAL. Defines a date and time after which the data model should not be used.
Replaced byCONDITIONAL. MUST be set if a new version replaces this one.
OwnerREQUIRED. Organisation or person responsible for the data model.
JSON SchemaREQUIRED. Link to the JSON schema in the EBSI JSON Schema Repository.
ExamplesREQUIRED. Link to one or more representative examples.

Table 2.2.4

Section 2 Template #8

TerminologyDescriptionTypeOther propertyNotes
ComponentComponent descriptionComponent typeOther component propertyComponent 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]

PropertyDescriptionTypeFormatCardinalityValidation rules
propertyProperty definitionProperty typeProperty formatProperty cardinalityValidation rules

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

PropertyDescriptionTypeFormatCardinalityValidation rules
propertyProperty definitionProperty typeProperty formatProperty cardinalityValidation rules

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

PropertyDescriptionTypeFormatCardinalityValidation rules
propertyProperty definitionProperty typeProperty formatProperty cardinalityValidation 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:

  1. The root type defines the contextual "is a" relationship.

  2. 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 nameUse caseData modelSchema & ExamplesTrusted Schemas Registry (TSR)
Verifiable ID (Natural Person)SSIdata modelNatural Person Verifiable IDTSR 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:

  1. Completed data model templates from Step 1: Define your data model
  2. JSON Schema
  3. Acknowledgement from domain representatives that the schema is recognised within the domain
  4. 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:

  1. Bundle the JSON Schema. Please see here
  2. Remove JSON Schema annotations (like description, title, examples) from the schema. Thus, changing a description will not change the schema ID.
  3. Canonicalise the bundled JSON Schema using JSON Canonicalization Schema (JCS).
  4. Apply the SHA256 hashing algorithm to the canonicalised document.
  5. 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