Skip to main content

Define schema

This page will provide instructions for step 2 of designing and publishing a data model on EBSI: defining your JSON Schema.

Introduction to JSON Schemas on EBSI​

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.

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 Data Model Design Template #5 to list all of your JSON schemas.

Data Model Design Template #5

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 subject is 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"
          ]
        }
      }
    }
  ]
}
Last updated on