JSON Schema validation for JSON-LD files using vocabulary.

Downloads in past


1770.17.12 years ago5 years agoMinified + gzip package size for schemaorg-jsd in KB


JSON Schema validation for JSON-LD files using vocabulary.


$ npm install schemaorg-jsd

Validate Against 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': '',
		'@type': 'Place',
		name: `Blacksburg, ${usState('Virginia').code}`,
	school['@id'] = ''
	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.filename) // file where the invalidation occurred
		console.error(err.details) // more json-schema specifics; see <>

	// 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': '',
		'@type': ['Place', 'LocalBusiness'],
	await sdoValidate(business) // validates against all schemata in the array

	// example 6: default type is `Thing` (
	await sdoValidate({
		'@context': '',
		'@type': 'foobar' // validates against the `Thing` schema, since value 'foobar' cannot be found
	await sdoValidate({
		'@context': '',
		// validates against the `Thing` schema, since property '@type' is missing

	// example 7: pass options object to Ajv constructor
	// (see
	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 (via $ref), you must add them both to the ajv instance.
Due to the interconnectedness of all schemata, it’s faster to add them all at once. This project’s exported SCHEMATA object is an array of JSON schema, pre-packaged and ready to add.
const Ajv = require('ajv')
const sdo_jsd = require('schemaorg-jsd')

const my_schema = {
	"$schema": "",
	"$id": "",
	"title": "Array<Thing>",
	"description": "An array of Things.",
	"type": "array",
	"items": { "$ref": "" }
const my_data = [
	{ "@context": "", "@type": "Thing", "name": "Thing 1" },
	{ "@context": "", "@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, 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 =
Background Info


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 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. 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 and know precisely what others are talking about: a person’s given name. The 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 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 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 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.