Skip to content
Gallery
Drafts
2.2 Define the Data Model and Schemas
Data models and Schemas
TBC
More
Share
Explore

icon picker
Data models and Schemas

Use-case agnostic, step-by-step guide about what information is needed to define your data model.

Data models

Data models are abstract representations of how data is structured, organized, 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 section XXX aim to help you ensure that data 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 the way data is structured for W3C Verifiable Credentials.

W3C Verifiable Credentials Data Model

This is the basic composition of a W3C compliant Verifiable Credential. The data model has various required and optional properties.
Component
Property
Requirement
Type

Verifiable Credential

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.
6
context
Required
​
type
Required
​
holder
Required
​
verifiableCredential
Required
​
id
Optional
​
proof
Optional
object
⁠
Because the W3C standard is permissionless and decentralised, it is possible to extend the W3C Verifiable Credentials Data Model to tailor utility for EBSI and your use case.
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

⁠
image.png
⁠
⁠
Pragmatically, Verifiable Presentations are what is used to present an element of a Verifiable Credential to an interested party.
Component
Property
Requirement
Type

Verifiable Presentation

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 credential of a subject.
6
context
Required
​
type
Required
​
holder
Required
​
verifiableCredential
Required
​
id
Optional
​
proof
Optional
​
⁠
Lets look at each data structure component extended by the Verifiable Attestation and understand their utility.

Data structure extensions and their properties

The properties of each component will be outlined. In the next section, each object and its functional value will be defined and a code example will be illustrated.

Component
Property
Requirement
Type

Verifiable Attestation

Description TBC
15
context
Required
​
id
Required
​
type
Required
​
issuer
Required
​
issuanceDate
Required
​
issued
Required
​
validFrom
Required
​
credentialSubject
Required
object
credentialSchema
Required
object
credentialStatus
Optional
object
evidence
Optional
object
proof
Optional
object
termsOfUse
Optional
object
expirationDate
Optional
​
validUntil
Optional
​
⁠

Component
Property
Requirement
Type

Accredited Verifiable Attestation

15
context
Required
​
id
Required
​
type
Required
​
issuer
Required
​
issuanceDate
Required
​
issued
Required
​
validFrom
Required
​
credentialSubject
Required
object
credentialSchema
Required
object
credentialStatus
Optional
object
evidence
Optional
object
proof
Optional
object
termsOfUse
Optional
object
validUntil
Optional
​
expirationDate
Optional
​

Verifiable Authorisation

Verifiable Authorisation is a Verifiable Attestation (
data model
⁠
) with the following top-level properties in the credentialSubject as defined in the table below.
1
CredentialSubject
id
Required
object

Verifiable Accreditation

Issued to Legal Entities.
General schema for Verifiable Accreditations, containing attributes that are the same for all accreditations.
5
credentialSubject
​
object
id
​
​
authorisationClaims
​
​
authorisedSchemaId
​
​
limitJurisdiction
​
​

Verifiable ID (Legal Entity)

Type of Verifiable Credentials (VCs) that Legal Entities can put forward as evidence of who they are.
11
id
Required
​
legalName
Required
​
legalPersonalIdentifier
Optional
​
legalAddress
Optional
​
VATRegistration
Optional
​
taxReference
Optional
​
LEI
Optional
​
EORI
Optional
​
SEED
Optional
​
SIC
Optional
​
domainName
​
​

Verifiable ID (Natural Person)

Type of Verifiable Credentials (VCs) that Natural Persons can put forward as evidence of who they are.

9
id
Required
​
familyName
Required
​
firstName
Required
​
dateOfBirth
Required
​
personalIdentifier
Required
​
nameAndFamilyNameAtBirth
Optional
​
placeOfBirth
Optional
​
currentAddress
Optional
​
gender
Optional
​

Other Verifiable Attestations

0
⁠

Now, each object and its functional value will be defined and a code example will be illustrated.
Objects
Object (specification)
Property
Definition
Example
Select list

Credential Subject

Use-case specific set of claims about the subject the VC refers to.
When to use:
For all...
Not all...
2
credentialSubject
The value of this property is a set of objects composed of a set of claims about the subject the credential refers to.

"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
​
id
​
​
​

Credential Status

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.
3
credentialStatus
The value of this property must include an id (as a URI) and type.
"credentialStatus": {
"id": "https://example.edu/status/24",
"type": "CredentialStatusList2017"
​
id
​
​
​
type
​
​
​

Credential Schema

Include a reference to the schema registered in the TSR.
4
credentialSchema
​
​
​
id
​
​
​
type
​
​
​
​
​
​
​

Evidence

Contains information about the process which resulted in the issuance of the Verifiable Attestation.
3
evidence
​
​
​
id
​
​
​
type
​
​
​

Proofs

Contains information about the proof.
Signatures.
8
proof
This mechanism and a set of instructions for its evaluation are necessary to make verifiable credentials and verifiable presentations verifiable against tampering.
"proof": {
"type": "Ed25519Signature2020",
"created": "2021-11-13T18:19:39Z",
"verificationMethod": "https://example.edu/issuers/14#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdo
WhAfGFCF5bppETSTojQCrfFPP2oumHKtz"
​
type
Defines the proof type.
​
Required
created
Defines the date and time, when the proof has been created.
​
Required
proofPurpose
Defines the purpose of the proof.
​
Required
verificationMethod
Contains information about the verification method/proof mechanisms.
​
Required
jws
Defines the proof value in JWS signature format.
​
Required
domain
​
​
Optional
challenge
​
​
Optional

Presentation

Description TBC
5
id
​
​
​
type
​
​
​
verifiableCredential
​
​
​
holder
​
​
​
proof
​
​
​

Terms of use

Defines the terms under which the Verifiable Attestation was issued.
3
termsOfUse
​
​
​
id
References a record of terms of use.
​
​
type
Defines the term of use type.
​
​
⁠
Use cases (TBC later)
Use case
Component
Schema & Examples
Example

SSI

1
​
​
​
⁠

Schemas

What they are.

A schema is a structured description or definition of the data that an information system will work with. Schemas provide a standardized way to represent and organize data, making it easier for different actors to understand and interact with the data.
JSON Schema is a way to describe the structure and validation rules for JSON (JavaScript Object Notation) data. JSON Schema is a declarative language that allows you to annotate and validate JSON documents.
It provides a format for specifying the expected format, types, and constraints for JSON objects, allowing APIs and applications to validate incoming data against a predefined schema.

Why we use them.

Since schemas are machine-readable artifacts, claims are defined in a single language: English. Translating the schemas would not only undermine interoperability and standardisation rules but also require unnecessary maintenance. JSON schema describe the data format, provide human-readable documentation, validate data for automated testing, and ensure the quality and conformance of the submitted data.
The meaning of the properties or claims is defined using a controlled vocabulary consisting of standardised and organised arrangements of words and phrases typically hosted in repositories on dedicated websites. This information is not part of the JSON schema and there are several existing mechanisms to express the vocabulary. These vocabularies define a specific and consistent terminology to describe the different concepts it comprises, enabling the exchange of information in a precise and unambiguous manner.

Mapping files

If a property name or description is needed in different languages, we suggest creating a mapping file to facilitate the understanding and the display of the information to end-users (layout and rendering). This mapping file can be understood as a code list or dictionary that links linguistic information (translations) to each concept of the schema. This file ensures that the same term is always translated the same way and complies with the intended meaning, which is the main purpose of using a controlled vocabulary. Nevertheless, the solution provider is responsible for determining the most appropriate solution according to its specific needs. For more details, please refer to the section on Internationalisation guidelines.

How you use them.

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. In this case, use cases should define and maintain a JSON-LD context and proper semantics. The EBSI model also supports JSON-LD, can facilitate the distribution of the context, and help use cases to define their context.
Schemas are extendable by default (meaning that...), all schemas must extend from the baseline of Verifiable Attestation. The W3C Verifiable Credential data model (seen here...) is a type driven on two ways, the root type defines the contextual "is a" relationship and field specific type extensions define "has a" relationship (this sentence is not clear to me, some rewording would benefit).
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, thus every existing schema can be read as a Verifiable Attestation, as all schemas must extend it.
All schemas are based on json-schema specification of draft 2020-12. The 2020-12 version is not backwards compatible with older drafts.

Applying this to EBSI

We need to create conditional statements to be used as general instructions.
Try and see what these conditionals would be and present to Alen, he can fill the gaps.

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.