Sunbird RC
v2.0.0
v2.0.0
  • Learn
    • Introduction
    • Sunbird RC Overview
      • Why do we need Sunbird RC?
      • Core Capabilities
      • Core Registry Verbs
      • Workflows
      • What Sunbird RC is and what it's not? (WIP)
      • Possibilities
      • Demo Links
    • Technical Overview
      • Registry
        • High-Level architecture
        • Technical Specification Draft
        • Tech Stack and Requirements
      • Credentialling
        • High-Level Architecture
        • Technical Specification Draft
        • Tech Stack and Requirements
    • Adopters
    • Roadmap
  • Use
    • Getting started
      • Pre-requisites
      • Install Sunbird-RC
    • Developer's Guide
      • Functional Registry
        • Installation Guide
          • Registry CLI
            • Setup A Registry Instance
          • Manual installation through docker-compose
          • Production setup through Helm
        • Working with Source Code
        • Configurations
          • Frontend Configurations
          • Frontend - Proxy configuration
          • Audit Configuration
          • Notifications Configuration
          • View Templates Configuration
        • Schema Setup
          • Introduction To Schemas
          • Creating Your Own Schemas
          • Schema Configuration
          • Create Schemas With Custom Password
        • Setup the Backend
        • Setup the Frontend
        • Backup and Restore
          • PostgreSQL
            • SQL Dump
            • File System Level Backup
            • Continuous Archiving and Point-in-Time Recovery (PITR)
          • Cassandra
            • Snapshot-based backup method
            • Incremental backup method
            • Data Restore
        • Generic Identity And Access Management
        • Metrics
        • Custom Keycloak Build
        • Custom QR Code design
        • VC Verification Module
      • Credentialling Services
        • Installation Guide
          • Run for development
          • Docker compose based
          • Helm based
        • Configurations
        • Working with the Vault
    • Integrations
      • SSO with existing systems
      • Digilocker Meripehchaan SSO
      • Digilocker Integration
    • Connectors
      • G2P Connect
      • Open ID for Verifiable Credentials (OID4VCI)
    • Release Notes
      • Registry
      • Credentialling
    • Admin Portal
      • Login
      • Get Started
        • Create Schema
        • Attestation Workflows (WIP)
        • VC Template
          • Custom VC Template (WIP)
        • Ownership (WIP)
        • Publish (WIP)
      • Dashboard
  • API Reference
    • Registry APIs
      • Registry
        • Using The APIs
        • Create An Entity
        • Invite An Entity
        • Generate token
        • Generate admin token
        • Get An Entity
        • Get An Entity By Id
        • Update An Entity
        • Create A Property Of An Entity
        • Update A Property Of An Entity
        • Revoke a Credential
        • Delete An Entity
      • Schema
        • Create Schema
        • Get Schema
        • Update Schema
        • Delete Schema
        • Publish A Schema
      • Attestation API
        • Raise An Attestation
        • Get Attestation Certificate
      • Claims API
        • Get All Claims
        • Get Claim by ID
        • Attest A Claim
      • Discovery API
        • Search An Entity
      • File Storage API
        • Upload A File
        • Get Uploaded File
        • Delete A File/ Multiple Files
      • Metrics APIs
        • Get Count
        • Get Aggregates
    • Credentialling APIs
      • Identity Service APIs
      • Credential Schema APIs
      • Credential Issuance APIs
    • Other APIs
      • Sign API
      • Verify API
      • Swagger JSON API
      • Health API
  • Reference Solutions for Functional Registries
    • Education
      • Education Ecosystem
        • Installation
      • Education Registries
        • Installation
        • User Guide
    • Health Registries
      • Organ Registries
        • Frontend Setup
        • Backend Setup
        • User Guide
      • Health Facility Registry
    • Govt to Person (G2P)
  • Reference Solutions for Digital Credentials
    • Certificate Issuance
      • Installation(WIP)
      • User Guide
    • eLocker
      • High Level Diagram
      • Installation (WIP)
        • Frontend Setup E-locker
      • User Guide
    • Vaccination Platform
    • Skills & Work Credentials
    • Unified Learners Passport (ULP)
      • ULP Capabilities
      • Example Scenario
      • Technical Components (WIP)
      • Demo/Sandbox Links (WIP)
      • Installation Guide (WIP)
        • Frontend Setup
        • Installation through docker-compose
        • Dummy records setup for refrence
  • Links
    • Source Code
    • Releases & Changelogs
    • Website
    • Roadmap
    • Reference links
    • Design
  • Community
    • Discussion Forum
    • Contributors
    • Contributing
    • Contribution Guidebook
    • Code of Conduct
    • Community Events
    • Status By Track
  • HELP
    • Roadmap
    • FAQs
    • Glossary
    • Guide to Electronic Registries and Verifiable Credentials
      • Verifiable Credentials
        • What issues will Verifiable Credentials address?
        • What are the key roles in Verifiable Credentials?
        • What are the components of Verifiable Credentials?
        • What are the benefits of Verifiable Credentials?
        • Digital Credentials vs Verifiable Credentials
        • QR code vs Verifiable QR code
        • Use Cases
      • Electronic Registries
        • Evolution of Electronic Registries
        • What issues will Electronic Registries address?
        • Benefits of Electronic Registries
        • Registry vs Database
        • Design Principles
        • Use Cases
      • Leveraging Existing data stores
    • External Open Source Software Attributions
Powered by GitBook

Copyright (c) 2023 EkStep Foundation under MIT License

On this page
Edit on GitHub
  1. Use
  2. Developer's Guide
  3. Functional Registry
  4. Schema Setup

Creating Your Own Schemas

Each registry can store data as entities. An entity is defined by its schema. This guide demonstrates how to create a schema to define your own entity.

The following is an example schema for a student entity. The comments should guide you as to which fields are required, and what fields should be adjusted as per your needs.

Note: Schema files cannot contain comments. The following example has been commented for your understanding only.

{
	// This must be at the top of all schemas. See http://json-schema.org/understanding-json-schema/reference/schema.html#schema
	"$schema": "http://json-schema.org/draft-07/schema",
	// This is a schema object...
	"type": "object",
	// ...that declares a Student entity
	"properties": { "Student": { "$ref": "#/definitions/Student" } },
	// The actual definition of the Student entity
	"definitions": {
		// You can declare multiple entities in one schema file, just make sure you
		// add the entity name in the `properties` field above
		"Student": {
			// The path to the declaration in the schema entity
			"$id": "#/properties/Student",
			// A Student is an object...
			"type": "object",
			// ...with the following required fields
			"required": ["name", "phoneNumber", "email", "school"],
			// The `phoneNumber` field must be unique across all Student entities
			"uniqueIndexFields": ["phoneNumber"],
			// The fields a Student entity can have
			"properties": {
				// Full name (string)
				"name": { "type": "string" },
				// Phone number (string)
				"phoneNumber": { "type": "string" },
				// Email (string)
				"email": { "type": "string" },
				// What school they are going to (string)
				"school": { "type": "string" }
				// The password for the Student entity (string)
				"passwordToken": { "type": "string" }
			}
		}
	},
	// Sunbird-RC specific configuration
	"_osConfig": {
        // The following property is used as an access modifier. The fields mentioned 
        // here are accessible by the owner of the entity and other users via consent.  
        // By default all fields are public.
        "privateFields": ["$.phoneNumber"],
        // The following property is used as an access modifier. The fields mentioned 
        // here are accessible only by the owner of the entity.
        // By default all fields are public.
        "internalFields": ["$.school"],
        // The following property is used to add additional audit fields to entity, to know
        // who/when created/updated the entity. 
        "systemFields": [
        "osCreatedAt",
        "osUpdatedAt",
        "osCreatedBy",
        "osUpdatedBy"
        ],
        // The following field is used to define the role who will be allowed to use the POST /api/v1/<Schema> API
        // to create the entity. The role will be validated with jwt token passed with the API.
        // If API does not require any role validation, then it can be set to anonymous
        "roles": ["admin"],
        // The following field is used to define the role who will be allowed to use the POST /api/v1/<Schema>/invite API
        // to invite the entity. The role will be validated with jwt token passed with the API.
        // If API does not require any role validation, then it can be set to anonymous
        "inviteRoles": ["admin"],
      
        // The following field is only needed if the entity is a human that can
        // login, grant consent, and manually attest claims. It will (usually) not
        // be needed for something like a book or toy entity.
        // The following fields are used to create a corresponding user in Keycloak,
        // the authentication service used by Sunbird RC.
      
        "ownershipAttributes": [
            {
                // The path to the field to consider the email of the entity
                "email": "/email",
                // The path to the field to consider the phone number of the entity
                "mobile": "/phoneNumber",
                // The path to the field to consider as unique ID of the entity
                "userId": "/phoneNumber"
                // The path to the field to consider as the password of the entity
                "password": "/passwordToken"
            }
        ],
        "attestationPolicies": [
            // For each field mentioned in the `attestationAttributes` field, add
            // an object like so:
            {
              
                // The unique name for the attestation policy
                "name": "studentInstituteAttest",
                // The schema for the additional input to be captured that is not part of the schema/entity
                "additionalInput": {
                  "enrollmentNumber": {"type": "string"}
                },
                // The fields/properties to be used for attestation. The value of the below mentioned properties
                // will be extracted and sent for attestation.
                // The path to the field (dot-separate fields if the field is nested, $
                // is the root of the entity)
                "attestationProperties": {
                  "name": "$.name",
                  "educationDetails": "$.school"
                },
                // Set the attestation type to `MANUAL` if another entity needs to login
                // and verify the claim
                "type": "MANUAL",
                // What type of entity should be able to attest the claim OR the role an
                // entity should have (in Keycloak) for them to be able to attest the claim
                "attestorPlugin": "did:internal:ClaimPluginActor?entity=Teacher",
                // The condition for a certain entity to be able to attest the claim. In
                // this case, the attestor Teacher entity must be in the same school as
                // the Student entity to attest the claim
                "conditions": "(ATTESTOR#$.school#.contains(REQUESTER#$.school#))"
            }
        ],
        // This property holds the template to be used for generating the VC. It needs to be a template that follows
        // W3C standards. It can be an url or the template object can be defined inline. The signed data (VC) generated by this
        // template will be used to generate a QR Code.
        // Ex: inline: https://github.com/tejash-jl/ref-sunbirdrc-certificate/blob/main/schemas/TrainingCertificate.json#L52
        // Ex: external url: https://github.com/tejash-jl/ref-sunbirdrc-certificate/blob/main/schemas/SkillCertificate.json#L66
        "credentialTemplate": "",
        // This property holds the template to be used for generating visual certificate. The key can be used while 
        // downloading the certificate.
        "certificateTemplates": {
          "svg": "https://raw.githubusercontent.com/dileepbapat/ref-sunbirdrc-certificate/main/schemas/templates/TrainingCertificate.svg"
        }
    }
}

To add a new entity to the registry, place the JSON file defining its schema in the schemas folder. If you have setup the registry using the Registry CLI, place the JSON file in the config/schemas folder. If you are running the registry from its source, place the schemas in the java/registry/src/main/resources/public/_schemas folder. If you are using a docker-compose.yaml file to start the registry, the schema folder will be mentioned in the file under the volumes section in the registry container's configuration.

Then restart the registry by running the following:

# If using a docker-compose file:
$ docker compose up --force-recreate -d
# If using the Registry CLI:
$ registry restart

If you restarted the containers manually (without the CLI), then wait approximately 40 seconds for the containers to start. You can view the status of the registry by running the following:

# If using a docker-compose file:
$ docker compose ps
# If using the Registry CLI:
$ registry status

docker compose up --force-recreate -d is only required when a change is made to the configuration (e.g.: an environment variable is updated in the docker-compose.yaml file, a new entity schema file was placed in the schemas folder). If you simply want to restart the registry process running in the container, a simple docker compose restart or registry restart --soft will suffice.

PreviousIntroduction To SchemasNextSchema Configuration

Last updated 1 year ago