The following 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, then define your JSON schemes, and finally publish the schemas on EBSI.
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 of 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 go into detail on 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 the way data is structured for Verifiable Credentials, EBSI is committed to using 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 of the key extensions of EBSI's core data models includes Verifiable Attestations (VAs), which can be further extended to suit 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 so that you can understand its utility on the EBSI infrastructure.
The aim is for you to understand how to best adapt or rewrite the data structure 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 is to see 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
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": "CredentialStatusList2017" |
| Credential Schema | credentialSchema | Include a reference to the schema registered in the TSR. | id / type | "credentialSchema": [{ "id": "https://example.org/examples/degree.json", "type": "JsonSchema" |
| 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/v4/issuers/did:ebsi:zz...", "type": "IssuanceCertificate" |
Table 2.2.3
1 - Define your data model
Now it is time for you to define your data model. To do so, you must fill out the four templates below that cover four different tasks:
- Context
- Glossary
- Data Model
- Content classes
Context
REQUIRED. Introduce the context of your data model in template Section 2 Template #6. Who the owner is, where is it 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 comprehensive specifications for each data structure component which you can find on each subpage of this page.
- For examples of how EBSI defined its data model components, click here.
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 of the information required in this expandable, is complete.
Once you have defined your data model, you must 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 quite straightforward. This takes us to the second step 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, then 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, which can facilitate the distribution of the context, and help use cases to define their context. Schemas are extendable by default, and all schemas must extend from the baseline of Verifiable Attestation.
The W3C Verifiable Credential data model is type-driven in two ways:
The root type defines the contextual "is a" relationship.
Field-specific type extensions define "has a" relationship.
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.
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 us 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. The schema registration proposal should ideally 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), instead of directly by you.
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:
- Filled out the data model templates from Step 1. Define your data model.
- JSON Schema
- Acknowledgement of the domain representatives that the schema is recognised within the domain
- Name 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.
If you need help, please contact EBSI Support Office