Back to top
Vastuu Group

Defining Connector Payload Structure

Last updated: March 16, 2021
|
Reading time: 6 min

Tags: Ontology, Ontology Viewer

It is required to define the Connector payload so that other parties can consume the data provided.

This guide is intended for the Connector developers, who under need to define the structure of Connector payload. It is required to define the Connector payload so that other parties can consume the data provided. We deliver structure definitions in JSON Schema format. All JSON Schemas should be published as a part of the Ontology.

A set of documentation in machine and human-readable formats describing metadata involved in Platform of Trust APIs.

– 

Platform of Trust Ontology

Ontology Viewer

Technologies involved

Platform of Trust uses next-generation technologies to define data in Connectors and Identity networks.

  • The W3C Web Ontology Language (OWL) is a Semantic Web language designed to represent rich and complex knowledge about things, groups of things, and relations between things.
    We use OWL to model Ontology.
  • Data is messy and disconnected. JSON-LD organizes and connects it, creating a better Web.
    We use JSON-LD to provide a machine-readable version of Ontology and connect Ontology to payloads and other data elements.
  • JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.
    We use JSON Schema to map Ontology with data structures in JSON format.
  • We use a custom tool named Ontology viewer to provide Ontology in a human-readable format. It is hosted at the same URL as the Ontology itself.

NOTE: Ontology delivers all URLs in both machine and human-readable format. Server is configured to deliver proper format of Ontology based on Content negotiation principles

HINT: Try to request same URL as Ontology viewer mentioned before in standards , Insomnia or cURL or other tool and see what will be returned in this case.

It is sufficient to understand JSON Schema. On the other hand, you might want to familiarize yourself with other technologies to understand all the nuances. Still, it is not obligatory for the Connector payload structure definition.

If you don't yet have experience with JSON Schema, then step by step instruction set is the fastest way to build up required knowledge.

Defining connector payload process

Current section is a general description. Detailed walkthrough is defined in next section.

Connector developers are advised to follow the next process to define Connector payload structure:

  1. Familiarize with Data Product parameters and output schemas already available using Ontology viewer
  2. If connector payload fits one of the available Data Product schemas, copy JSON Schema and use it to validate parameters and output.
  3. If your Connector payload does not match any of the available Data Product contexts, create your own JSON Schemas and send it to Slack channel connector-engine
  4. After processing on the Ontology team side, we will add respective contexts and JSON Schemas to the ontotest environment
  5. As final step Ontology team provides parameters and output context URL for usage

Step-by-step guide

Let's make a quick walkthrough to define Connector payload structure.

Get a better understanding of JSON Schema.

You may this section if you already have a good understanding of this technology.
Otherwise, you might need to go through this JSON Schema quick start guide. This will be sufficient for the workflow described in this guide. You can use additional materials on JSON Schema website if needed.

Navigate available JSON schemas for connectors

  1. Open Ontology viewer
  2. Here you can find parent DataProductContext and derived contexts already available in the Ontology
  3. Click on the Data Product context of your interest. Review Parameters JSON Schema and Output JSON Schema tabs for parameters and output schemas respectively.

ontology-viewer.png

Data Product Parameter structure

All Data Product contexts are derived from DataProductContext and follow next general structure

{
  "@context": "https://standards.oftrust.net/v2/Context/DataProductParameters/?v=2.0",
  "productCode": "multidata-product-1",
  "timeStamp": "2019-10-19T13:20:09+00:00",
  "parameters": {}
}

Let's review the properties involved in the definition:

  • @context - every JSON Schema has associated static URL that should be used as a value. The exact URL is provided as a const value of @context property in JSON Schema. If you are more interested in what it means, you might need to investigate JSON-LD documentation. For the Connector payload definition, it is enough to know that it should be static and defined in the Ontology.
  • productCode - Data Product code.
  • timeStamp - Timestamp of the request.
  • parameters - actual parameters as a JSON object.

Data Product output structure

All Data Product outputs are derived from DataProductOutput and follow next general structure

{
  "@context": "https://standards.oftrust.net/v2/Context/DataProductOutput/?v=2.0",
  "data": {},
  "signature": {
    "type": "RsaSignature2018",
    "created": "2018-11-22T12:00:00Z",
    "creator": "https://example.org/creator/public_key.pub",
    "signatureValue": "eyJ0eXAiOiJK...gFWFOEjXk"
  }
}

Let's review the properties involved in the definition:

  • @context - every JSON Schema has associated static URL that should be used as a value. The exact URL is provided as a const value of @context property in JSON Schema.
  • data - is actual meaningful Connector payload.
  • signature - the digital signature of the payload.

NOTE:

  • Use the @context attribute in all response bodies. It should be used only once and in the root object
  • Use only agreed data context URL
  • Be aware that ontology base URI and respective @context links differ for test and production environments. Those context URLs need to be changed before deployment

Select data context you will use as a basis

There are several options on what to do next. If Connector payload can be adjusted to one of the existing data contexts - please take the existing data context and develop Connector in a way it provides compatible payload.

If existing contexts do not provide required fields or structures - use parent DataContext or any other contexts as a basis and modify it in a way it provides required structures. Please send it to connector-engine Slack channel (you must be invited to this channel as Connector developer). After JSON Schema is reviewed by Ontology team, it can be used in actual payloads.

Modeling or testing DataContext and Connector payload

Several tools might be useful in creating JSON Schema or testing Connector payload against JSON Schema.

Conclusion

In this guide, we reviewed the process of defining the Connector payload structure and publishing it as part of Platform of Trust Ontology.

Providing structured data with extractable attached metadata is a very significant part of Platform of Trust approach value. Being able to get all required metadata directly from data content provides end-users and developers easy access to definitions required to read and interpret received values.

Ready to explore more?

Try Platform Sandbox

Improvement Suggestions? or a New Guide?

Tell us in GitHub