Dialcode context

Owned by Vinu Kumar
Last updated: Mar 03, 2022 by Anil Gupta
15 min read

Introduction:

This document describes how to get the DIAL code context information.

Background:

At present, the dial-service is not storing any information/context about the DIAL code linked to what(ex Textbook, Textbook unit, etc). So if we want to get the DIAL code context information we should always use the content-search API to get the DIAL code linked content details.

If we want to extend the use-case to Bazaar, using DIAL code scan if they want to get the context(like BGMS etc) information to show the relevant contents which adopters having is not possible at the moment.

Jira Story: https://project-sunbird.atlassian.net/browse/SB-28757

Discussion: https://github.com/sunbird-specs/DIAL-specs/discussions/2

Problem Statement:

Should return the context information of the DIAL code to which it is linked?

Key design problems:

How to store the context information of the DIAL code to which it is linked?

How to get the context information using the existing dial/{dialcode} API?

How to validate the context information stored against the DIAL code?

How to define the customized validation schema specific to the domain/product?

Design:

How to define JSON-LD schema?

  • Customize schema: Customer/Host provider can define their own JSON-LD schema to validate the context.

  • Single Schema for all use-cases: The single JSON-LD schema for all the different user-cases of validating the context properties. The same schema can we updated for new properties of new use-cases.

  • Validation: We are validating only the properties which are passing in the request (as context) are exist in schema or not and the property value type. We are not validating the mandatory & optional properties of different use-cases.

Sample JSON-LD schema

https://github.com/sunbird-specs/DIAL-specs/blob/main/v1/schema.jsonld

 

 

JSON-LD Samples

Context whitout @graph

End-point:

{host}/v1/dialcode/update/V1T2P8

note:
V1T2P8 -> DIAL code used to link the content

@context:

Context information will be stored in the JSON file. Which can be configured/defined by the user specific to each context type. User can send the request of specific context, which will be validated against this JSON-LD context file.

note:
Here we are not using @graph object declaration in the context data/file.
Hence all the context information will be stored against single graph node of the DIAL code.(if we use graph DB to store)

Examples:

Textbook: http://example.org/dialcode-textbook.json

Context file data to validation when textbook is linked to dialcode

{ "@context": { "schema": "http://schema.org/", "framework": { "@id": "schema:name#framework", "@type": "schema:name" }, "board": { "@id": "schema:name#board", "@type": "schema:name" }, "medium": { "@id": "schema:name#medium", "@type": "schema:name" }, "gradeLevel": { "@id": "schema:name#grade_level", "@type": "@id", "@container": "@list" }, "subject": { "@id": "schema:name#subject", "@type": "@id", "@container": "@list" }, "textbook": "schema:Book", "textBookUnit": "schema:Chapter", } }

Request:

{ "request": { "dialcode": { "contextInfo": { // OPTIONAL "@context": "http://example.org/dialcode-textbook.json", // URL path of context file "@id": "http://example.org/dialcode/V1T2P8", "board": "AP", "framework": "NCF", "medium": "English", "subject": ["Maths", "Social"], "gradeLevel": "Grande 1", "textbook": { "@id": "http://example.org/collection/4728-2345-2343-3455", "identifier": "4728-2345-2343-3455", "name": "Sample textbook" }, "textBookUnit": { "name": "Unit name" }, } } } }

Response:

Certificate: http://example.org/dialcode-cert.json

Context file data to validation when textbook is linked to dialcode

Request:

Response:

Pros:

  • API request format is simple

  • We can validate any invalid property has sent as part of request against the JSON-LD schema.

Cons:

  • All the properties are storing against the single node object(DIAL code).

Context with @graph

Here we are using @graph declaration in the context for JSON-LD declaration. Hence user has to send the request also in the graph format so that we can validate the request against the @context declaration.

We are taking he same examples of Textbook & Certificate explained above.

Textbook: http://example.org/dialcode-textbook.json

Context file data to validation when textbook is linked to DIAL code

Request:

Response:

Certificate: http://example.org/dialcode-cert.json

Context file data to validation when certificate is linked to dialcode

Request:

Response:

Pros:

  • We can define our own named node-objects & its relations(If we are storing in graph DB)

Cons:

  • User can send the new graph node object which is not present in the JSON-LD context. It is still allowed to store. We have to explicitly validate this.

  • The API request also need to change to send in the format of graph nodes

Context with @graph & Validation

  • Validation of API request with JSON-LD context(Using JSON-LD Frame)

JSON-LD Frame

The frame object is used to validate the required object & properties present in the request or not.

 

JSON-LS Input

 

Sample:

Sample test in playground tool

references:


 

Solution 1:

  • Use the existing metadata(rename to context) column to store the context information of the DIAL code as JSON string.

  • Use DIAL/update API to update the context of the exiting DIAL codes.

  • Add context while Generating the dialcodes(if it is common for all dialcodes which are generting)

  • Restrict the context infomation to max(1000 characters).

Add context to the DIAL code

APIs:

Generate DIAL code API

If user is generating more than one DIAL code and passing the context in request body then same context will be store for all DIAL code. Context will be optional while generate DIAL code.

/v1/dialcode/generate

request:

response:

Update DIAL code API

/v1/dialcode/update/{dialcode}

request:

response:

Read DIAL code API

/v1/dialcode/read/{dialcode}

response:

 

Pros:

  • Easy & quick solution to implement on the existing DB without any modifications in the DB.

  • Discovery by doalcode context. We can do any queries on DIAL code metadata/context.

Cons:

  • Duplicate entries in the context column, if the DIAL codes at linked to the child nodes of the same collection.

  • Any update on the context information on the parent node should update all the child node context(multiple entires in the DB)

Solution 2:

Separate DIAL code context information from dial-service metadata DB.

Post: DIAL code context

Strore DIAL code context in Neo4J & ES

 

Get: DIAL code context

 

Pros:

  • Discovery by context is not possible. We can’t do any queries on DIAL code metadata/context.

  • Easy to store any unstructured data as nodes & give the relation between nodes. This helps to store different types of context with respect to multiple use-cases.

  • Any update of the root level context is just a linking to different node.

Cons:

  • Multiple DB’s involved for the simple service like dial-service.

  •  

Reference links:

  • JSON-LD reference:

  • DIAL spec:

 

MOM:

March 1, 2022

  • Decided to not using @graph object declaration in the context data/file.

  • Decided to use schema instead on frame object for validation. Understanding the frame object is overhead for adopter.

  • Action Item: @Jayaprakash Narayanaswamy needs to build the POC for schema validation while accepting the request and return json-ld object in response.