JSON Schema validation for JSON-LD files using Schema.org vocabulary.
npm install schemaorg-jsd
$ 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
or you may use standard Promise prototype methods.
Read the TypeDoc comments in ./src/index.ts for further details.`js
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
}
// 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
(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 ),
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.
`js
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",
"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.ts
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 .*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`.