Schema.org Adapter

Fast, simple & flexible API for the Schema.org Vocabulary (and vocabulary extensions!) for Node and Browsers

// 1. Import the package
const SDOAdapter = require('schema-org-adapter');
// 2. Create a new instance of the SDO-Adapter with no knowledge (it must yet be initialized with vocabularies)
const mySDOAdapter = new SDOAdapter();
// 3. Initialize the SDO-Adapter with a vocabulary/vocabularyURL (SDO-Adapter can help with that!)
await mySDOAdapter.addVocabularies(await mySDOAdapter.constructSDOVocabularyURL('latest'));

// 4. Use the SDO-Adapter!
let Hotel = mySDOAdapter.getClass('schema:Hotel');
Hotel.getProperties(); // -> ["schema:audience", "schema:checkinTime", "schema:availableLanguage", ...]
Hotel.getSuperClasses(false); // Only direct superclasses -> ["schema:LodgingBusiness"]
Hotel.getSuperClasses(); // Also superclasses of superclasses -> ["schema:LodgingBusiness", "schema:LocalBusiness", "schema:Place", "schema:Organization", "schema:Thing"]

let address = mySDOAdapter.getProperty("schema:address");
address.getRanges(); // -> ["schema:PostalAddress", "schema:Text"]
address.getDomains(false); // Only direct domains -> ["schema:Place", "schema:GeoCoordinates", "schema:GeoShape", "schema:Person", "schema:Organization"]
address.getDomains(); // Also subclasses of domains -> ["schema:Place", "schema:Accommodation", "schema:TouristAttraction", ...]

Installation and Use

NPM

Install the npm package:

npm install schema-org-adapter

Node

Require the package:

const SDOAdapter = require('schema-org-adapter');

Browser

Script-include the bundled package in /dist or load via a cdn:

<script src="/dist/schema-org-adapter.min.js"></script>

<script src="https://cdn.jsdelivr.net/gh/semantifyit/schema-org-adapter/dist/schema-org-adapter.min.js"></script>

Features

⌘ Empowers the semantic web: Schema.org has become the standard vocabulary for the semantic web. This Schema.org Adapter gives developers a clear API to access the schema.org vocabulary in a simple way.

★ Clear data model: The data model of the rdf-based, machine-readable version of Schema.org is slightly adapted (see documentation for details) to create the clear and pragmatic data model of this Schema.org Adapter.

↹ Supports schema.org versions and external vocabularies: The Schema.org Adapter is lightweight because it does NOT include the vocabulary data, instead it allows the user to input his needed local/remote vocabularies (JSON-LD or URL to JSON-LD). This gives the user the possibility to specify the version of Schema.org he/she needs, also to use external vocabularies. It is possible to input the wished schema.org vocabulary file/URL directly, or build such a vocabulary URL using functions provided by schema-org-adapter (it uses a repository-fork with daily test-controlled updates from the official schema.org repository to ensure the correct function of the library while also keeping up-to-date with schema.org releases).

♻ Built-in reasoning: The API of Schema.org Adapter offers functions and parameters to enable built-in reasoning on the used vocabulary-terms (e.g. resolution of properties, sub-classes, ranges, etc.)

API

JSDoc

Api documentation generated as Markdown (based on JSDoc) available at GitHub.

You can also download this repository and generate an HTML version of JSDoc with:

npm run-script genJsDoc

Examples

Check the examples for Node and Browser on GitHub.

Support for HTTP and HTTPS versions of schema.org

Schema.org Adapter supports the use of the https-version of schema.org (from vocabulary version 9.0 upwards) as well as the http-version. The wished protocol variant can be given to the SDO-Adapter constructor through a config-object (default for schemaHttps is true, hence, the https version is used if possible).

const SDOAdapter = require('schema-org-adapter');

// uses https version if possible
const mySdoAdapter = new SDOAdapter({schemaHttps: true});

// sdoUrl resolves to file name "schemaorg-all-https.jsonld"
const sdoUrl = await mySDOAdapter.constructSDOVocabularyURL('latest');

const SDOAdapter = require('schema-org-adapter');

// uses http version
const mySdoAdapter = new SDOAdapter({schemaHttps: false}); 

// sdoUrl resolves to file name "schemaorg-all-http.jsonld"
const sdoUrl = await mySDOAdapter.constructSDOVocabularyURL('latest');

Use of filters

It is possible to filter the results of some functions by passing a filter object - The filter options can be:

• "isSuperseded": boolean (e.g. false -> only vocabulary elements that are not superseded will be returned)
• "termType": string/Array (e.g. ['Property', 'Class'] -> only vocabulary elements that are properties or classes will be returned)
• "fromVocabulary": string/Array (e.g. ['https://schema.org/'] -> only vocabulary elements that come from a specific vocabulary will be returned (this may be interesting if you use additional external vocabularies))

const SDOAdapter = require('schema-org-adapter');
const mySdoAdapter = new SDOAdapter();
await mySdoAdapter.addVocabularies(await mySDOAdapter.constructSDOVocabularyURL('latest'));

//get list of classes that are NOT superseded
let listOfClasses = mySdoAdapter.getAllClasses({
  "isSuperseded": false
});

Changelog

See History.md.

Acknowledgement