Skip to content

Latest commit

 

History

History
156 lines (107 loc) · 6.11 KB

readme.md

File metadata and controls

156 lines (107 loc) · 6.11 KB
Raw

Schema.Org Converter (SDO-Converter)

This is a stand-alone JavaScript (JS) tool that converts the vocabulary of Schema.org into easy to use JSON files with a tree-like data model. This tool comes with a JS library (SDO-Library) that uses the previously mentioned JSON files to provide data-retrieving functions for the Schema.org vocabulary.

The SDO-Converter fetches the vocabulary from the Schema.org website in JSON-LD format (All layers!) and transforms the data into several json files containing structured representations of the vocabulary (classes [most times called "types" in Schema.org], properties, basic data types, enumerations, enumeration members).

There is a Wiki explaining the algorithm and the generated data model of this tool. All data artifacts generated by this tool can be found in the "data_output" directory.

Prerequisites

Install as stand-alone project

Clone the project from the git repository

git clone https://github.com/semantifyit/SDO-Converter.git

In the project's folder to download all dependencies:

npm install

Install as npm package

Download the package

npm install sdo-converter

You can use the package as a stand-alone tool, or use the sdoLibrary in your project. See the example files on how to require/import and use the library.

Usage of SDO-Converter

In the project's folder to start the tool:

node sdoConverter start

Command Syntax:

node sdoConverter COMMAND (--OPTION)*

Commands:

start -> fetches the schema.jsonld from Schema.org AND starts the converting algorithm.

download -> fetches the schema.jsonld from Schema.org.

covert -> starts the converting algorithm.

help -> shows this information.

Options:

--version -> specifies the version of Schema.org to download/convert. e.g. 3.1 or latest

--materialize -> the output data will be saved as one big materialized file. true/false

--minify -> the output data will be saved without white spaces. true/false

Default for options are:

'--version=latest --materialize=false --minify=true'

Output

The data_output directory will contain following files for the specified Schema.org version:

if --materialize=false:

  • sdo_classes.json - Contains the classes of SDO with their characteristics. Properties from their super-classes are not present (see "Usage of data" for details).
  • sdo_properties.json - Contains the properties of SDO with their characteristics.
  • sdo_dataTypes.json - Contains the basic data types of SDO with their characteristics.
  • sdo_enumerations.json - Contains the enumerations of SDO with their characteristics. Properties from their super-classes are not present (see "Usage of data" for details).
  • sdo_enumerationMembers.json - Contains the enumeration instances of SDO with their characteristics.

if --materialize=true:

  • sdo_classesMaterialized.json - Contains the classes (types), data types and enumerations of SDO with their characteristics. Some characteristics are materialized, eg. Class->properties and Enumeration->enumerationMembers. The materialization also includes inheritance for classes, hence all classes list the properties inherited from their super-classes.

Usage of SDO-Library

The user can use the generated data in any way he wishes.

This project provides a library to load and materialize the SDO data (basically stick the parts of the vocabulary together). The possibility to execute the materialization on the target application increases the performance of the application (load small data files, fast creation of materialized objects in-memory).

This library is usable in browsers (file: sdoLibrary_browser.js) and in nodeJS (file: sdoLibrary_node.js).

Two example files are provided to show how the library and the generated data can be used in their respective environments (example for browser: example_browser.html, example for nodeJS: example_node.js)

Usage example for node.js:

sdoLibrary = require("./sdoLibrary_node.js");
sdoLibrary.setVersion("latest");
let addressJSON = sdoLibrary.get_property("address");

Usage example for browsers:

<script src="sdoLibrary_browser.js"></script>
<script>
    (function () {
        sdoLibrary.setVersion("latest");
        //you can implement a callback or a timeout, depending on your used technologies
        setTimeout(function () {
            var personJSON = sdoLibrary.get_classMaterialized("Person");
        }, 1000);
    })();
</script>

Functions provided by the SDO-Library

In general you want to use the materialized data provided by the library, since it contains all classes (things), enumerations, and basic data types from Schema.org along with the properties of their super-classes (based on the inheritance of properties in Schema.org). These properties are provided as complete JSON objects (instead of only their id) with their corresponding ranges, descriptions, etc.

Functions for materialized data:

sdoLibrary.get_classMaterialized("EntityName");
//Returns a JSON object for the Class/DataType/Enumeration with the given entity name. 

sdoLibrary.get_allClassesMaterialized();
//Returns an Array of JSON objects with all Classes, DataTypes, and Enumerations.

Functions for non-materialized data:

sdoLibrary.get_class("ClassName");

sdoLibrary.get_allClasses();
sdoLibrary.get_property("PropertyName");

sdoLibrary.get_allProperties();
sdoLibrary.get_dataType("DataTypeName");

sdoLibrary.get_allDataTypes();
sdoLibrary.get_enumeration("EnumerationName");

sdoLibrary.get_allEnumerations();
sdoLibrary.get_enumerationMember("EnumerationMemberName");

sdoLibrary.get_allEnumerationMembers();

License

MIT © Omar J. A. Holzknecht