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.