Skip to content

Creating semantic Models in JSON format

SDI enables the user to map business properties to schema properties present in registry and create queries on business properties (semantic/business queries) and execute them. A user can define business to physical mappings by creating ontology.
Ontology can be created using json file as well as owl file. This section describes how to create an ontology JSON.

Getting Started

Fetching schema details

This section describes how to get the necessary information from SDI to create an ontology.

Retrieving Schemas to create mappings

The input depends upon the schemas to be considered for fetching the data.

Use the following endpoint:

POST api/sdi/v4/searchSchemas

Define the following header:

    Authorization: {Bearer Token}
    Content-Type: application/json

Request example

    {
      "schemas": [
      {
        "schemaName": "nhtsa_vehicles"
      }]
    }

Response example

Response
  {
      "id": "5e4c461c577c210e17e64357",
      "originalFileNames": [
        "vehiclemake.csv"
      ],
      "schemaName": "nhtsa_vehicles",
      "schemaDescription": "",
      "dataRegistryId": "C159F0FFED3B787C283AC467424E40E1",
      "schemaVersion": 0,
      "latestSchemaVersion": 1,
      "createdAt": 1582056988262,
      "lastUpdated": 1582056988286,
      "schema": {
        "vnumber": {
          "dataType": "string",
          "customTypes": [
            "us_state",
            "partnumber1581984706",
            "partnumber1",
            "partnumber1582056922"
          ]
        },
        "vname": {
          "dataType": "String"
        },
        "vcost": {
            "dataType": "Double"
          }
      },
      "storageLocation": [
        {
          "locationType": "s3",
          "location": "s3://parquet-file-storage-dev/ediint2/nhtsa_vehicles",
          "dataType": "parquet"
        }
      ],
      "metadata": {
        "versionSuffix": "v",
        "checksum": "2F9A11BA607CC9E4EA9A90AD23A3BAB2",
        "pointsToVersion": 1
      },
      "dataFolderSize": ""
    }

Ontology creation

Consider a scenario where, it is required to query data of the schema extracted using SDI registry APIs. But, you want to create queries using related business properties and obtain results. To achieve this, you need to map business properties to various schema properties and create queries on them.
You can also create multiple ontologies and map business properties to different schema properties and use those ontologies to create semantic queries.

Create a registry and upload a data file, and the extracted schema name is nhtsa_vehicles.

Schema : nhtsa_vehicles

Property Name Property Type
vnumber String
vname String
vprice Double

Out of these three properties of schema nhtsa_vehicles, vnumber is used for ontology mapping.

Classes and properties (Business entities and their properties):

  1. Make
Property Name Property Type
gmtoffset int
Make int
ModelName int

2.Vehicle

Property Name Property Type
ModelNumber String
Model int
Vin int
StateNum int
RegState int

3.Model

Property Name Property Type
ModelNumber int

4.MakeModel

Property Name Property Type
ModelNumber int
Id int

For example, you want to map vnumber property of nhtsa_vehicles schema to ModelNumber of Vehicle class.

  • classProperty:
Property Name Property Type Parent Class
ModelNumber String Vehicle
  • schemaProperties:

    • First property:
    Property Name Property Type Parent Schema
    vnumber String nhtsa_vehicles

You can specify relations between business properties by defining propertyRelations.

Make.gmtoffset <--> Vehicle.ModelNumber

  • startClassProperty:
Property Name Parent Class
gmtoffset Make
  • endClassProperty:
Property Name Parent Class
ModelNumber Vehicle

Mappings

The following image shows the mapping between business property and schema property:

Mappings

Basic properties of ontology json

The following table describes the basic properties of ontology json:

Property name Description Mandatory
classes A Class represents a business entity. The classes property of ontology JSON describes list of such business entities It is not a mandatory property.
Classes mentioned in class properties, mappings & propertyRelations must be added
schema List of schemas from registry to be added in ontology If schemas mentioned in schema properties, mappings and property relation are already present in the server database, then it is not required to provide schema details in ontology json
classProperties List of class properties (properties of business entity) Only class properties present in mappings and property relations should be provided in ontology
schemaProperties List of schema properties Schema properties which are mentioned in mappings and are not present in the server database must be provided in ontology JSON.
mappings List of mappings.
There are two types of mappings:
1. KeyMapping : Key mapping is the direct mapping between the class property and one or more schema properties.
2. FunctionalMapping : Functional mapping represents a class property as an entity that is calculated based on some arithmetic operation on one or more schema columns.
Current version of service supports only key mapping.
It is not a mandatory property but generally ontology is created to represent mappings
propertyRelations This represents list of property relations.
Basically PropertyRelation is an edge or relation between one class property with one or more class properties. There can be one-to-one or one-to-many property relations types.
No

Description

The detailed description of each property in json is as below:

Details
{
"classes"(List of classes in ontology): [
    {
        "name"(Name of class. Dot( . ) is not allowed in the name): "",
        "description"(More details about class):"",
        "keyMappingType"(More details about class, If 'keyMappingType' is defined at class level then it will override 'keyMappingType' value defined at ontology level. ):"",
        "primarySchema"(More details about class, if more than one keymapping are defined on schema then either of the schema can be as primarySchema):""
    }
],
"schemas"(List of schema details): [
    {
        "name"(Name of schema. Schema must be present in registry): "",
        "description"(More details about schema):""
    }
],
"classProperties"(Array of class properties): [
    {
        "name"(Name of class property): "",
        "datatype"( Datatype of class property. Only primitive datatypes are allowed. Class property datatype should match with mapped schema property datatype): "",
        "parentClass"( Class details to which this property belongs): {
            "name"(Name of parent class): ""
        }
    }
],
"schemaProperties"(Array of schema properties): [
    {
        "name"(Name of schema property): "",
        "parentSchema": {
            "name": ""
        },
        "datatype"( Datatype of schema property. Only premetive datatypes are allowed. Schema property datatype should match with registry property datatype): ""
    }
],
"mappings"(Array of property mappings): [
    {
        "name"(Name given to a mapping): "",
        "keyMapping"(Key mapping is the direct mapping between the class property and one or more schema properties. This is a boolean field which indicates provided mapping is key mapping or not): ,
        "functionalMapping"(Functional mapping represents a class property as an entity that is calculated based on some arithmetic operation on one or more schema columns. This is a boolean field which indicates provided mapping is functional mapping or not ): ,
        "classProperty"(List of class properties): {
            "name" (name of class property): "",
            "parentClass" (Class details to which this property belongs): {
                "name"(name of class): ""
            }
        },
        "schemaProperties" (List of schema properties): [
            {
                "name"(name of schema property): "",
                "parentSchema" (Schema details to which this property belongs): {
                    "name"(name of schema): ""
                }
            }
        ]
    }
],
"propertyRelations"(PropertyRelations is an edge or relation between one class property with one or more class properties. There can be one-to-one or one-to-many property relations types.): [

{
  "name"(Name given to property relation): "",
  "description"(Detail description about property relation): "",
  "relationType"(Possible relation types are one-to-one, one-to-many, many-to-one): "",
  "startClassProperty"(Details about start node of edge): {
    "name"(Name of start node class property): "",
    "parentClass"(Name of class to which this property belongs): {
      "name"(Name of class): ""
    }
  },
  "endClassProperty"(Details about end node of edge): {
    "name"(Name of end node class property): "",
    "parentClass"(Name of class to which this property belongs): {
      "name"(Name of class): ""
          }
        }
      }
    ]
  }

It is necessary to validate the input before saving it to the system. The following requirements should be met:

  1. All the schemas and schema properties mentioned in ontology must be present in the registry.
  2. Datatype of property given in ontology request and the one present in registry should match.
  3. Data type of mapped properties should match (datatype of class property should be same or wider than datatype of mapped schema property) , widening is allowed while defining datatype of class property. The rules are as follows:

    Schema Property Data Type Allowed Class Property Datatype
    integer integer, long, float, double
    long long, float, double
    float float, double
    double double
    string string
    timestamp timestamp
  4. If more than one schema properties are mapped to a class property, then the datatype of all schema properties should be same.

  5. A class property cannot be mapped to two schema properties of the same schema for key mapping.

Final Ontology JSON request

Request
    {
  "schemas": [
    {
      "name": "sditest_vehicle"
    }
  ],
  "schemaProperties": [
    {
      "name": "vnumber",
      "description": "vnumber property of schema sditest_vehicle",
      "datatype": "Integer",
      "parentSchema": {
        "name": "sditest_vehicle"
      }
    }
  ],
  "classes": [
    {
      "name": "Make",
      "keyMappingType": "FULL OUTER JOIN"
    },
    {
      "name": "Vehicle",
      "description": "Vehicle Class",
      "primarySchema": "sditest_vehicle",
      "keyMappingType": "INNER JOIN"
    },
    {
      "name": "Model",
      "description": "ModelClass"
    },
    {
      "name": "MakeModel"
    }
  ],
  "classProperties": [
    {
      "name": "gmtoffset",
      "datatype": "Integer",
      "parentClass": {
        "name": "Make"
      }
    },
    {
      "name": "ModelNumber",
      "description": "ModelNumber property of class Model",
      "datatype": "Integer",
      "parentClass": {
        "name": "Model"
      }
    },
    {
      "name": "ModelNumber",
      "description": "ModelNumber property of class Vehicle",
      "datatype": "Integer",
      "parentClass": {
        "name": "Vehicle"
      }
    },
    {
      "name": "Model",
      "datatype": "Integer",
      "parentClass": {
        "name": "Vehicle"
      }
    },
    {
      "name": "Vin",
      "datatype": "Integer",
      "parentClass": {
        "name": "Vehicle"
      }
    },
    {
      "name": "StateNum",
      "description": "StateNum property of class Vehicle",
      "datatype": "Integer",
      "parentClass": {
        "name": "Vehicle"
      }
    },
    {
      "name": "RegState",
      "description": "RegState property of class Vehicle",
      "datatype": "Integer",
      "parentClass": {
        "name": "Vehicle"
      }
    },
    {
      "name": "ModelNumber",
      "description": "ModelNumber property of class MakeModel",
      "datatype": "Integer",
      "parentClass": {
        "name": "MakeModel"
      }
    },
    {
      "name": "Id",
      "description": "Id property of class MakeModel",
      "datatype": "Integer",
      "parentClass": {
        "name": "MakeModel"
      }
    },
    {
      "name": "Make",
      "description": "Make property of class Make",
      "datatype": "Integer",
      "parentClass": {
        "name": "Make"
      }
    },
    {
      "name": "ModelName",
      "description": "ModelName Property of class Make",
      "datatype": "Integer",
      "parentClass": {
        "name": "Make"
      }
    }
  ],
  "mappings": [
    {
      "name": "vinaultmapping",
      "description": "Mapping between ModelNumber property of class Vehicle and vnumber property of schema sditest_vehicle ",
      "keyMapping": true,
      "functionalMapping": false,
      "classProperty": {
        "name": "ModelNumber",
        "parentClass": {
          "name": "Vehicle"
        }
      },
      "schemaProperties": [
        {
          "name": "vnumber",
          "parentSchema": {
            "name": "sditest_vehicle"
          }
        }
      ]
    }
  ],
  "propertyRelations": [
    {
      "name": "firstPropertyRelation",
      "description": "property relation between gmtoffset of Make and ModelNumber of Vehicle",
      "relationType": "one-to-one",
      "startClassProperty": {
        "name": "gmtoffset",
        "parentClass": {
          "name": "Make"
        }
      },
      "endClassProperty": {
        "name": "ModelNumber",
        "parentClass": {
          "name": "Vehicle"
          }
        }
      }
    ]
  }

Last update: December 1, 2023

Except where otherwise noted, content on this site is licensed under the Development License Agreement.