{"id":21216697,"url":"https://github.com/chharvey/schemaorg-jsd","last_synced_at":"2025-07-10T11:32:26.912Z","repository":{"id":28388137,"uuid":"116412732","full_name":"chharvey/schemaorg-jsd","owner":"chharvey","description":"JSON Schema validation for JSON-LD files using Schema.org vocabulary.","archived":false,"fork":false,"pushed_at":"2022-12-01T22:11:52.000Z","size":1601,"stargazers_count":21,"open_issues_count":8,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-05T06:19:22.953Z","etag":null,"topics":["json-ld","json-schema","schema-org"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/schemaorg-jsd","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chharvey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-05T18:00:58.000Z","updated_at":"2025-05-30T04:47:25.000Z","dependencies_parsed_at":"2023-01-14T08:43:50.556Z","dependency_job_id":null,"html_url":"https://github.com/chharvey/schemaorg-jsd","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/chharvey/schemaorg-jsd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chharvey%2Fschemaorg-jsd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chharvey%2Fschemaorg-jsd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chharvey%2Fschemaorg-jsd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chharvey%2Fschemaorg-jsd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chharvey","download_url":"https://codeload.github.com/chharvey/schemaorg-jsd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chharvey%2Fschemaorg-jsd/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264224070,"owners_count":23575572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-ld","json-schema","schema-org"],"created_at":"2024-11-20T21:55:10.667Z","updated_at":"2025-07-10T11:32:26.530Z","avatar_url":"https://github.com/chharvey.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [schemaorg-jsd](https://chharvey.github.io/schemaorg-jsd/docs/api/)\nJSON Schema validation for JSON-LD files using Schema.org vocabulary.\n\n\n# Usage\n\n## Install\n```\n$ npm install schemaorg-jsd\n```\n\n## Validate Against Schema.org JSON Schema\n\nThis module exports an asynchronous validation function.\nIt returns a Promise object, so you may use `await` or you may use standard `Promise` prototype methods.\nRead the TypeDoc comments in `./src/index.ts` for further details.\n\n```js\nconst { sdoValidate } = require('schemaorg-jsd')\n\nasync function run() {\n\t// example 1: use any javascript object\n\tconst school = {\n\t\t'@context': 'http://schema.org/',\n\t\t'@type': 'Place',\n\t\tname: `Blacksburg, ${usState('Virginia').code}`,\n\t}\n\tschool['@id'] = 'http://www.blacksburg.gov/'\n\ttry {\n\t\tconst is_valid_place = sdoValidate(school, 'Place') // validate against the `Place` schema\n\t\tconsole.log(await is_valid_place) // return `true` if the document passes validation\n\t} catch (err) { // throw a `TypeError` if the document fails validation\n\t\tconsole.error(err)\n\t\tconsole.error(err.filename) // file where the invalidation occurred\n\t\tconsole.error(err.details) // more json-schema specifics; see \u003chttps://github.com/epoberezkin/ajv#validation-errors\u003e\n\t}\n\n\n\t// example 2: require a package\n\tconst me = require('./me.json')\n\tconsole.log(await sdoValidate(me, 'Person')) // return `true` if the document passes validation\n\n\n\t// example 3: use a string (relative path) of the filename\n\tconst org = './my-org.jsonld'\n\tconsole.log(await sdoValidate(org, 'Organization')) // return `true` if the document passes validation\n\n\n\t// example 4: infer the schema from the `'@type'` property\n\tawait sdoValidate(school) // validates against the `Place` schema, since `school['@type'] === 'Place'`\n\n\n\t// example 5: multiple types\n\tconst business = {\n\t\t'@context': 'http://schema.org/',\n\t\t'@type': ['Place', 'LocalBusiness'],\n\t}\n\tawait sdoValidate(business) // validates against all schemata in the array\n\n\n\t// example 6: default type is `Thing` (http://schema.org/Thing)\n\tawait sdoValidate({\n\t\t'@context': 'http://schema.org/',\n\t\t'@type': 'foobar' // validates against the `Thing` schema, since value 'foobar' cannot be found\n\t})\n\tawait sdoValidate({\n\t\t'@context': 'http://schema.org/',\n\t\t// validates against the `Thing` schema, since property '@type' is missing\n\t})\n\n\n\t// example 7: pass options object to Ajv constructor\n\t// (see https://github.com/ajv-validator/ajv/blob/master/docs/api.md#options)\n\tawait sdoValiate(data, type, {\n\t\tstrict: true,\n\t});\n}\n```\n\n\n## Validate Against Your Own JSON Schema\nYou can use [ajv](https://www.npmjs.com/package/ajv) to validate any document against any JSON schema.\nNormally you would do this by adding the schema to the ajv instance, and then checking the document.\nHowever, if you write a schema that references one of this project’s Schema.org schema (via `$ref`),\nyou must add them both to the ajv instance.\n\nDue to the interconnectedness of all Schema.org schemata, it’s faster to add them all at once.\nThis project’s exported `SCHEMATA` object is an array of Schema.org JSON schema,\npre-packaged and ready to add.\n```js\nconst Ajv = require('ajv')\nconst sdo_jsd = require('schemaorg-jsd')\n\nconst my_schema = {\n\t\"$schema\": \"http://json-schema.org/draft-07/schema#\",\n\t\"$id\": \"https://chharvey.github.io/example.jsd\",\n\t\"title\": \"Array\u003cThing\u003e\",\n\t\"description\": \"An array of Schema.org Things.\",\n\t\"type\": \"array\",\n\t\"items\": { \"$ref\": \"https://chharvey.github.io/schemaorg-jsd/schema/Thing.jsd\" }\n}\nconst my_data = [\n\t{ \"@context\": \"http://schema.org/\", \"@type\": \"Thing\", \"name\": \"Thing 1\" },\n\t{ \"@context\": \"http://schema.org/\", \"@type\": \"Thing\", \"name\": \"Thing 2\" }\n]\n\nasync function run() {\n\tconst ajv = new Ajv()\n\t\t.addMetaSchema(await sdo_jsd.META_SCHEMATA)\n\t\t.addSchema(await sdo_jsd.JSONLD_SCHEMA)\n\t\t.addSchema(await sdo_jsd.SCHEMATA)\n\tajv.validate(my_schema, my_data)\n\t/*\n\tNote that the `Ajv#validate()` method’s parameters are reversed from this package’s `sdoValidate()`:\n\n\tAjv#validate(schema, data)     // schema comes before data\n\tsdoValidate(data, schemaTitle) // data comes before schema\n\t */\n}\n```\n\n## View the “API”\nThis project includes a set of [TypeDoc](http://typedoc.org/) declarations describing types and their properties.\nThey’re identical to the specs at [schema.org](https://schema.org/),\nbut you can import the source code in your own project for\n[TypeScript](http://www.typescriptlang.org/) compilation.\n\n[View the docs.](https://chharvey.github.io/schemaorg-jsd/docs/api/)\n\n```ts\nimport * as sdo from 'schemaorg-jsd'\n\nclass Person {\n\t/** This person’s name. */\n\tprivate _name: string;\n\t/**\n\t * Construct a new Person object.\n\t * @param jsondata an object validating against the schemaorg-jsd `Person` schema\n\t */\n\tconstructor(jsondata: sdo.Person) {\n\t\tthis._name = jsondata.name\n\t}\n}\n```\n\n\n# Background Info\n\n## JSON\n[JSON](http://www.json.org/) (JavaScript Object Notation) is a data interchange format,\nbased off of the syntax used to define object literals in JavaScript.\n\n## JSON Schema\n[JSON Schema](http://json-schema.org/) is a subset of JSON\nthat allows you to validate JSON documents.\nIn other words, a particular JSON schema tells you whether your JSON instance file is written correctly,\nif you choose to validate your instance against that schema.\nJSON schema documents *themselves* must also be valid JSON, *as well as* validate against the\n[JSON Meta-Schema specification](http://json-schema.org/draft-07/schema).\nThe JSON Meta-Schema tells you whether your JSON schema document, if you have one, is written correctly.\nThe official MIME Type of JSON schema documents is `application/schema+json`.\n\n*Note: this project uses a `.jsd` (“JSON Schema Definition”) file extension to name JSON schema files, though\nthere is no prevailing convention on JSON schema file extensions.*\n\n## JSON-LD\n[JSON-LD](https://json-ld.org/) (JSON Linked Data) is a syntax used to mark up data in a consistent way.\nRather than everyone using their own data types, JSON-LD standardizes the markup, making it easy\nfor people and data types to communicate.\nJSON-LD has some rules, for example, an object’s `@id` property must be a string.\nTherefore, to enforce these rules, JSON-LD documents should validate against the\n[JSON-LD Schema](https://json-ld.org/schemas/jsonld-schema.json).\nThe official MIME Type of JSON-LD documents is `application/ld+json`,\nand JSON-LD files typically have file extension `.jsonld`.\n\n## Schema.org\n[Schema.org](https://schema.org/) Is a vocabulary that you can use to describe data.\nThese are semantic descriptions that have well-defined meanings.\nFor example, people using different human languages could refer to the unique identifier http://schema.org/givenName\nand know precisely what others are talking about: a person’s given name.\nThe Schema.org vocabulary is syntax-agnostic, meaning you can use whatever format you want to mark up your data.\n[Microdata](https://www.w3.org/TR/microdata/) is one common syntax, and JSON-LD is another.\n\n## TypeScript\n[TypeScript](https://www.typescriptlang.org/) is a strongly-typed language that compiles to JavaScript.\nSome of the biggest features of TypeScript include *interfaces* and *type aliases*, which, respectively,\ndescribe the “shape” (fields and methods) and “structure” (properties) that an object may have.\nThis project includes interfaces and type aliases for Schema.org Classes and Properties, respectively,\nso that you can write a well-typed API for your project.\n\n## Putting It All Together\nYou can semantically mark up your data using the Schema.org vocabulary with JSON-LD syntax.\nIf you have a TypeScript API, you can import this project’s TypeScript to catch any type errors before runtime.\nThen, to prevent additional runtime errors or SEO mistakes, you can validate your markup against\nthe JSON schemata in this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchharvey%2Fschemaorg-jsd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchharvey%2Fschemaorg-jsd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchharvey%2Fschemaorg-jsd/lists"}