Explore

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.

context

type

holder

verifiableCredential

proof

⁠

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

⁠

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.

context

type

holder

verifiableCredential

proof

⁠

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

context

type

issuer

issuanceDate

issued

validFrom

credentialSubject

credentialSchema

credentialStatus

evidence

proof

termsOfUse

expirationDate

validUntil

⁠

Component

Property

Requirement

Type

Accredited Verifiable Attestation

context

type

issuer

issuanceDate

issued

validFrom

credentialSubject

credentialSchema

credentialStatus

evidence

proof

termsOfUse

validUntil

expirationDate

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.

CredentialSubject

Verifiable Accreditation

Issued to Legal Entities.

General schema for Verifiable Accreditations, containing attributes that are the same for all accreditations.

credentialSubject

authorisationClaims

authorisedSchemaId

limitJurisdiction

Verifiable ID (Legal Entity)

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

legalName

legalPersonalIdentifier

legalAddress

VATRegistration

taxReference

LEI

EORI

SEED

SIC

domainName

Verifiable ID (Natural Person)

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

familyName

firstName

dateOfBirth

personalIdentifier

nameAndFamilyNameAtBirth

placeOfBirth

currentAddress

gender

Other Verifiable Attestations

⁠

Now, each object and its functional value will be defined and a code example will be illustrated.

Objects

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...

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"

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.

credentialStatus

The value of this property must include an id (as a URI) and type.

"credentialStatus": {

"id": "https://example.edu/status/24",

"type": "CredentialStatusList2017"

type

Credential Schema

Include a reference to the schema registered in the TSR.

credentialSchema

type

Evidence

Contains information about the process which resulted in the issuance of the Verifiable Attestation.

evidence

type

Proofs

Contains information about the proof.

Signatures.

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.

created

Defines the date and time, when the proof has been created.

proofPurpose

Defines the purpose of the proof.

verificationMethod

Contains information about the verification method/proof mechanisms.

jws

Defines the proof value in JWS signature format.

domain

challenge

Presentation

Description TBC

type

verifiableCredential

holder

proof

Terms of use

Defines the terms under which the Verifiable Attestation was issued.

termsOfUse

References a record of terms of use.

type

Defines the term of use type.

⁠

Use cases (TBC later)

Use cases (TBC later)

Use case

Component

Schema & Examples

Example

SSI

⁠

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.