TODO Onboarding

Overview

This document shows how a new domain, in this case, teacher domain is enabled using OpenSABER. The following are the typical steps an adopter has to do:

Details on modeling the data can be found here and details on modeling validation for Registry can be found here.

1. Creating a new RDF vocabulary of terms, if those terms are not already defined. It is considered best practice, to re-use existing vocabularies. For instance, schema.org defines a Person, so one need not redefine it, but one may choose to extend Person to a specific agent, in this case, a Teacher.
2. Understanding how to call the OpenSABER APIs.
3. Configuring a validator which uses the vocabulary to validate user input.
4. Installing and configuring OpenSABER runtime (software).

Let's take the example of starting from scratch and enabling the Teacher use case and installing OpenSABER as the DIKSHA Teacher Registry.

Progression

Learning to Define a vocabulary

Best Practice

Try to use the schema.org or equivalent vocabulary wherever applicable. If schema.org is insufficient (which is likely), create a RDF file and send in a Pull Request to domains/ for review. While defining a vocabulary for the custom domain, you may end up creating some core classes and properties. You are encouraged to contribute to the core, via the same PR mechanism. To know, how to extend schema.org, read up on the web, or just study the files in domains/ folder. Extending is fairly straightforward.

Core fundamentals in RDF

All information can be represented in Triples of subject, predicate and object. For instance,

ID 456IHO&78 is a Teacher, her name is Lakshmi and she is a PGT.

This can be represented in RDF (here, Turtle) as

OpenSABER:456IHO&78 a OpenSABER:Teacher ;
                    schema:name "Lakshmi" ;
                    OpenSABER:teacherTitle OpenSABER:PGT .

You can see that OpenSABER:456IHO&78 is the subject and there are 3 predicates - a denoting type, schema:name denoting name and OpenSABER:teacherTitle denoting a property which in one out of PGT, TGT and lets say PRT.

schema:name is a short form for http:\schema.org\name. Everything is namespaced, so one can pick and choose properties and classes from any vocabulary which suits the domain definition.

So, if we are starting from scratch, schema.org does not have the concept of a Teacher, so if we had to create the Teacher agent, we can safely assume that it will subclass from Person. Subclassing would mean 2 things:

1. Every instance of Teacher is also an instance of Person, which is true.
2. Every property which has a domain of Person will also be applicable to Teacher. This is really good, because common properties like name, etc are just already available via Person. Of course, there maybe many more properties than the ones you want to use, but that's ok. You can filter out the ones you need via your validators. RDF via nature is more inclusive than not, so be comfortable with taking all what other vocabularies bring on the table.

So, the Teacher RDF if it has to extend from Person would look like

OpenSABER:Teacher a rdfs:Class ;
    rdfs:label "Teacher" ;
    schema:isPartOf <http://teacher.pending.OpenSABER.io> ;
    rdfs:comment "A Teacher." ;
    rdfs:subClassOf schema:Person .

and lets say we need a new property called teacherTitle which is an Enumeration, like PRT, TGT, PGT, etc, all of which are actually instances of the Enumeration. So, the following is how you would create an Enumeration and list out the values of an Enumeration:

OpenSABER:TeacherTitle a rdfs:Class ;
    rdfs:label "TeacherTitle" ;
    rdfs:comment "An enumeration of teacher titles." ;
    rdfs:subClassOf schema:Enumeration .

OpenSABER:PGT a OpenSABER:TeacherTitle ;
    rdfs:label "PGT" ;
    rdfs:comment "Post Graduate Teacher." .

OpenSABER:TGT a OpenSABER:TeacherTitle ;
    rdfs:label "TGT" ;
    rdfs:comment "Trained Graduate Teacher." .

OpenSABER:PRT a OpenSABER:TeacherTitle ;
    rdfs:label "PRT" ;
    rdfs:comment "Primary Teacher." .

OpenSABER:TeacherOtherTitle a OpenSABER:TeacherTitle ;
    rdfs:label "TeacherOtherTitle" ;
    rdfs:comment "Other." .

and we can now create a new property OpenSABER:teacherTitle which can now range into any TeacherTitle.

OpenSABER:teacherTitle a rdf:Property ;
    rdfs:label "teacherTitle" ;
    schema:domainIncludes OpenSABER:Teacher ;
    schema:rangeIncludes OpenSABER:TeacherTitle ;
    rdfs:comment "Title of a Teacher." .

Putting everything together...

@prefix OpenSABER: <http://OpenSABER.io/vocab/2018/01/> .
@prefix schema: <http://schema.org/> .
OpenSABER:Teacher a rdfs:Class ;
    rdfs:label "Teacher" ;
    schema:isPartOf <http://teacher.pending.OpenSABER.io> ;
    rdfs:comment "A Teacher." ;
    rdfs:subClassOf schema:Person .
OpenSABER:TeacherTitle a rdfs:Class ;
    rdfs:label "TeacherTitle" ;
    rdfs:comment "An enumeration of teacher titles." ;
    rdfs:subClassOf schema:Enumeration .
OpenSABER:PGT a OpenSABER:TeacherTitle ;
    rdfs:label "PGT" ;
    rdfs:comment "Post Graduate Teacher." .
OpenSABER:TGT a OpenSABER:TeacherTitle ;
    rdfs:label "TGT" ;
    rdfs:comment "Trained Graduate Teacher." .
OpenSABER:PRT a OpenSABER:TeacherTitle ;
    rdfs:label "PRT" ;
    rdfs:comment "Primary Teacher." .
OpenSABER:TeacherOtherTitle a OpenSABER:TeacherTitle ;
    rdfs:label "TeacherOtherTitle" ;
    rdfs:comment "Other." .
OpenSABER:teacherTitle a rdf:Property ;
    rdfs:label "teacherTitle" ;
    schema:domainIncludes OpenSABER:Teacher ;
    schema:rangeIncludes OpenSABER:TeacherTitle ;
    rdfs:comment "Title of a Teacher." .

We didn't have to define the schema:name property since it already defined by schema.org.

Teacher and Core Vocabulary

Vocabularies are never complete but the first iteration of Teacher and Core vocabularies are at domains/. Go through the RDF files. RDF files are versioned, so if you make an edit in the RDF definitions, it is considered good practice to version the files.

Deploying OpenSABER

Read the Installation Guide for deploying OpenSABER. After deploying

Calling the OpenSABER APIs

OpenSABER APIs can be used to perform CRUD operations on the various subjects of the same type. For instance, in a Teacher registry, the APIs are used to create, read, update or delete facts about a Teacher.

CREATE

The following curl command is an example of creating a Teacher: