schemaorg-jsd

JSON Schema validation for JSON-LD files using Schema.org vocabulary.

Usage

Install

$ npm install schemaorg-jsd

Validate Against Schema.org JSON Schema

This module exports an asynchronous validation function.
It returns a Promise object, so you may use await or you may use standard Promise prototype methods.
Read the TypeDoc comments in ./src/index.ts for further details.

const { sdoValidate } = require('schemaorg-jsd')
async function run() {
    // example 1: use any javascript object
    const school = {
        '@context': 'http://schema.org/',
        '@type': 'Place',
        name: `Blacksburg, ${usState('Virginia').code}`,
    }
    school['@id'] = 'http://www.blacksburg.gov/'
    try {
        const is_valid_place = sdoValidate(school, 'Place') // validate against the `Place` schema
        console.log(await is_valid_place) // return `true` if the document passes validation
    } catch (err) { // throw a `TypeError` if the document fails validation
        console.error(err)
        console.error(err.filename) // file where the invalidation occurred
        console.error(err.details) // more json-schema specifics; see <https://github.com/epoberezkin/ajv#validation-errors>
    }
    // example 2: require a package
    const me = require('./me.json')
    console.log(await sdoValidate(me, 'Person')) // return `true` if the document passes validation
    // example 3: use a string (relative path) of the filename
    const org = './my-org.jsonld'
    console.log(await sdoValidate(org, 'Organization')) // return `true` if the document passes validation
    // example 4: infer the schema from the `'@type'` property
    await sdoValidate(school) // validates against the `Place` schema, since `school['@type'] === 'Place'`
    // example 5: multiple types
    const business = {
        '@context': 'http://schema.org/',
        '@type': ['Place', 'LocalBusiness'],
    }
    await sdoValidate(business) // validates against all schemata in the array
    // example 6: default type is `Thing` (http://schema.org/Thing)
    await sdoValidate({
        '@context': 'http://schema.org/',
        '@type': 'foobar' // validates against the `Thing` schema, since value 'foobar' cannot be found
    })
    await sdoValidate({
        '@context': 'http://schema.org/',
        // validates against the `Thing` schema, since property '@type' is missing
    })
    // example 7: pass options object to Ajv constructor
    // (see https://github.com/ajv-validator/ajv/blob/master/docs/api.md#options)
    await sdoValiate(data, type, {
        strict: true,
    });
}

Validate Against Your Own JSON Schema

You can use ajv to validate any document against any JSON schema.
Normally you would do this by adding the schema to the ajv instance, and then checking the document.
However, if you write a schema that references one of this project’s Schema.org schema (via $ref),
you must add them both to the ajv instance.

Due to the interconnectedness of all Schema.org schemata, it’s faster to add them all at once.
This project’s exported SCHEMATA object is an array of Schema.org JSON schema,
pre-packaged and ready to add.

const Ajv = require('ajv')
const sdo_jsd = require('schemaorg-jsd')
const my_schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://chharvey.github.io/example.jsd",
    "title": "Array<Thing>",
    "description": "An array of Schema.org Things.",
    "type": "array",
    "items": { "$ref": "https://chharvey.github.io/schemaorg-jsd/schema/Thing.jsd" }
}
const my_data = [
    { "@context": "http://schema.org/", "@type": "Thing", "name": "Thing 1" },
    { "@context": "http://schema.org/", "@type": "Thing", "name": "Thing 2" }
]
async function run() {
    const ajv = new Ajv()
        .addMetaSchema(await sdo_jsd.META_SCHEMATA)
        .addSchema(await sdo_jsd.JSONLD_SCHEMA)
        .addSchema(await sdo_jsd.SCHEMATA)
    ajv.validate(my_schema, my_data)
    /*
    Note that the `Ajv#validate()` method’s parameters are reversed from this package’s `sdoValidate()`:
    Ajv#validate(schema, data)     // schema comes before data
    sdoValidate(data, schemaTitle) // data comes before schema
     */
}

View the “API”

This project includes a set of TypeDoc declarations describing types and their properties.
They’re identical to the specs at schema.org,
but you can import the source code in your own project for
TypeScript compilation.

View the docs.

import * as sdo from 'schemaorg-jsd'
class Person {
    /** This person’s name. */
    private _name: string;
    /**
     * Construct a new Person object.
     * @param jsondata an object validating against the schemaorg-jsd `Person` schema
     */
    constructor(jsondata: sdo.Person) {
        this._name = jsondata.name
    }
}

Background Info

JSON

JSON (JavaScript Object Notation) is a data interchange format,
based off of the syntax used to define object literals in JavaScript.

JSON Schema

JSON Schema is a subset of JSON
that allows you to validate JSON documents.
In other words, a particular JSON schema tells you whether your JSON instance file is written correctly,
if you choose to validate your instance against that schema.
JSON schema documents themselves must also be valid JSON, as well as validate against the
JSON Meta-Schema specification.
The JSON Meta-Schema tells you whether your JSON schema document, if you have one, is written correctly.
The official MIME Type of JSON schema documents is application/schema+json.

Note: this project uses a .jsd (“JSON Schema Definition”) file extension to name JSON schema files, though
there is no prevailing convention on JSON schema file extensions.

JSON-LD

JSON-LD (JSON Linked Data) is a syntax used to mark up data in a consistent way.
Rather than everyone using their own data types, JSON-LD standardizes the markup, making it easy
for people and data types to communicate.
JSON-LD has some rules, for example, an object’s @id property must be a string.
Therefore, to enforce these rules, JSON-LD documents should validate against the
JSON-LD Schema.
The official MIME Type of JSON-LD documents is application/ld+json,
and JSON-LD files typically have file extension .jsonld.

Schema.org

Schema.org Is a vocabulary that you can use to describe data.
These are semantic descriptions that have well-defined meanings.
For example, people using different human languages could refer to the unique identifier http://schema.org/givenName
and know precisely what others are talking about: a person’s given name.
The Schema.org vocabulary is syntax-agnostic, meaning you can use whatever format you want to mark up your data.
Microdata is one common syntax, and JSON-LD is another.

TypeScript

TypeScript is a strongly-typed language that compiles to JavaScript.
Some of the biggest features of TypeScript include interfaces and type aliases, which, respectively,
describe the “shape” (fields and methods) and “structure” (properties) that an object may have.
This project includes interfaces and type aliases for Schema.org Classes and Properties, respectively,
so that you can write a well-typed API for your project.

Putting It All Together

You can semantically mark up your data using the Schema.org vocabulary with JSON-LD syntax.
If you have a TypeScript API, you can import this project’s TypeScript to catch any type errors before runtime.
Then, to prevent additional runtime errors or SEO mistakes, you can validate your markup against
the JSON schemata in this project.