diff --git a/.github/workflows/deploy-web.yml b/.github/workflows/deploy-web.yml index 6818854..74cb7cb 100644 --- a/.github/workflows/deploy-web.yml +++ b/.github/workflows/deploy-web.yml @@ -15,6 +15,7 @@ on: paths: - 'web/**' - 'templates/**' + - 'src/validate.js' - '.github/workflows/deploy-web.yml' workflow_dispatch: {} diff --git a/CHANGELOG.md b/CHANGELOG.md index a33a1b7..9240e24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,27 @@ All notable changes to this project are documented here. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project follows semantic versioning where it makes sense for a content repository. +## Unreleased + +### Changed + +- The JSON-LD check lives in `src/validate.js` (also `@geosuite/schema-templates/validate`), + imported as is by `validate.js` and the web tool, and gives the verdict of + GeoSuite's Schema Helper on every case of `test/fixtures/golden.json`, a + fixture GeoSuite runs too: + - `@graph` and top-level arrays are expanded, and a `@graph` item inherits + the wrapper's `@context` (pasting a Yoast or Rank Math block used to fail + with "missing @type"); + - `http://schema.org` and a trailing slash are accepted, and so is a + non-string `@context` (an array or an object); + - an `@type` list is checked by its first string type; + - an `@type` without a template is no longer an error in the web tool + (`validate.js` still requires a known one for the files the repo ships); + - "invalid JSON" no longer carries the parser message inside the error: the + API returns it as `parseError`, and the page still shows it. +- The golden file pins the sha256 of every template, the copy GeoSuite vendors. + `npm run golden` refreshes the hashes after a template change. + ## 0.3.2 — 2026-05-23 ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42982e6..1c502dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Thanks for your interest in extending this template library. The goal of the rep 4. **Keep it minimal.** Include only the properties that are genuinely necessary for the use case. Resist the urge to ship every optional property — extra fields dilute the signal. 5. **Use placeholders.** Wrap every value the consumer is expected to fill in with `{{DOUBLE_CURLY_PLACEHOLDERS}}`. Use SCREAMING_SNAKE_CASE for placeholder names. 6. **Ship a matching example.** Add `examples/.example.json` with realistic, populated values. Examples in this repo use a fictional Italian SaaS company so contributors can copy the style; you are welcome to use a different fictional brand if it makes the example clearer, as long as values are plausible. -7. **Declare required fields.** Open `validate.js` and add an entry to `REQUIRED_BY_TYPE` listing the top-level fields that must be present for your `@type`. Keep this list short — it is the floor, not the ceiling. +7. **Declare required fields.** Open `src/validate.js` and add an entry to `REQUIRED_BY_TYPE` listing the top-level fields that must be present for your `@type`. Keep this list short: it is the floor, not the ceiling. 8. **Update the README catalog.** Add a row to the catalog table with the schema type, use case, and links to the template and example. 9. **Run the checks locally.** @@ -25,7 +25,9 @@ Thanks for your interest in extending this template library. The goal of the rep ## Modifying an existing template -The same rules apply. If your change adds or removes a top-level property, update `REQUIRED_BY_TYPE` in `validate.js` and the matching example in the same PR. Keep template and example in lockstep. +The same rules apply. If your change adds or removes a top-level property, update `REQUIRED_BY_TYPE` in `src/validate.js` and the matching example in the same PR. Keep template and example in lockstep. + +**Template or rule changes reach GeoSuite too.** GeoSuite's Schema Helper vendors `templates/` and runs the same check: `test/fixtures/golden.json` pins the templates' hashes, `REQUIRED_BY_TYPE` and the expected verdicts, and both repos test against it. After changing a template or a rule, run `npm run golden` to refresh the hashes (add a case to `validate_cases` for a new rule), then copy `templates/` and the fixture to GeoSuite. ## Questions diff --git a/README.md b/README.md index dee1200..423bf78 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ After replacing placeholders, run your JSON through at least one of these: - [Schema.org Validator](https://validator.schema.org/) — checks that your JSON-LD conforms to the schema.org vocabulary. The most strict and the most useful for generic JSON-LD. - [Google Rich Results Test](https://search.google.com/test/rich-results) — checks the subset of properties Google uses for rich results. Helpful but narrower than the schema.org validator. -- The bundled `validate.js` script in this repo runs a fast structural sanity check (`@context`, `@type`, required fields) without any network calls. Run it with `npm run validate` or `node validate.js`. +- The bundled `validate.js` script in this repo runs a fast structural sanity check (`@context`, `@type`, required fields) without any network calls. Run it with `npm run validate` or `node validate.js`. The check itself is `src/validate.js` (`import { validateJsonLd } from '@geosuite/schema-templates/validate'`): the same one the web tool and GeoSuite's Schema Helper run, with the same verdict for the same JSON-LD (one object, an array or a `@graph`). The recommended order is: `validate.js` first to catch typos, then the schema.org validator, then the Google test if you specifically care about Google rich results. @@ -72,7 +72,7 @@ No runtime or dev dependencies. There is no build step. ## Contributing -We welcome new templates and improvements to existing ones. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. The short version: every new template must (a) follow the file-naming convention, (b) ship a matching `examples/*.example.json` with realistic values, (c) declare its required fields in `validate.js`, and (d) pass `npm run validate` and `npm test`. +We welcome new templates and improvements to existing ones. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. The short version: every new template must (a) follow the file-naming convention, (b) ship a matching `examples/*.example.json` with realistic values, (c) declare its required fields in `src/validate.js`, and (d) pass `npm run validate` and `npm test`. ## CLI (0.2+) diff --git a/package.json b/package.json index f657344..82d2d05 100644 --- a/package.json +++ b/package.json @@ -30,11 +30,16 @@ "geosuite-schema": "bin/cli.js", "schema-templates": "bin/cli.js" }, + "exports": { + "./validate": "./src/validate.js", + "./*": "./*" + }, "scripts": { - "lint": "node --check src/ai.js && node --check bin/cli.js && node --check validate.js && node --check test/test-validate.js && node --check test/test-ai.js", + "lint": "node --check src/ai.js && node --check src/validate.js && node --check bin/cli.js && node --check validate.js && node --check scripts/refresh-golden.js && node --check test/test-validate.js && node --check test/test-ai.js && node --check test/test-golden.js", "validate": "node validate.js", "test": "node --test test/*.js", - "coverage": "node --experimental-test-coverage --test test/*.js" + "coverage": "node --experimental-test-coverage --test test/*.js", + "golden": "node scripts/refresh-golden.js" }, "engines": { "node": ">=20" diff --git a/scripts/refresh-golden.js b/scripts/refresh-golden.js new file mode 100644 index 0000000..2c0e9b9 --- /dev/null +++ b/scripts/refresh-golden.js @@ -0,0 +1,24 @@ +#!/usr/bin/env node +// Refreshes the parts of test/fixtures/golden.json that are derived from the +// repo (the templates' sha256 and REQUIRED_BY_TYPE). The expected verdicts in +// `validate_cases` are written by hand on purpose: this script never touches +// them. Copy the result to GeoSuite (backend/tests/fixtures/schema_templates_golden.json) +// together with templates/ (backend/data/schema_templates/). +import { createHash } from "node:crypto"; +import { readFileSync, readdirSync, writeFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { REQUIRED_BY_TYPE } from "../src/validate.js"; + +const root = join(dirname(fileURLToPath(import.meta.url)), ".."); +const path = join(root, "test/fixtures/golden.json"); +const golden = JSON.parse(readFileSync(path, "utf8")); + +const hashes = {}; +for (const name of readdirSync(join(root, "templates")).filter((f) => f.endsWith(".json")).sort()) { + hashes[name] = createHash("sha256").update(readFileSync(join(root, "templates", name))).digest("hex"); +} +golden.required_by_type = REQUIRED_BY_TYPE; +golden.templates_sha256 = hashes; +writeFileSync(path, JSON.stringify(golden, null, 2) + "\n"); +console.log(`golden.json: ${Object.keys(hashes).length} template hash(es), ${Object.keys(REQUIRED_BY_TYPE).length} type(s)`); diff --git a/src/validate.js b/src/validate.js new file mode 100644 index 0000000..508c814 --- /dev/null +++ b/src/validate.js @@ -0,0 +1,146 @@ +// The JSON-LD structural check, shared by validate.js (the repo check), the +// web tool (web/worker.js) and anyone importing the package. +// +// GeoSuite's Schema Helper runs the same check on every JSON-LD block it finds +// on a page (backend/services/tools/schema_helper_service.py, `validate_jsonld` +// and `_validate`). The two must give the same answer for the same input: +// test/fixtures/golden.json holds the cases, and both repos run them (GeoSuite +// keeps a copy in backend/tests/fixtures/schema_templates_golden.json). Change a +// rule here, update the fixture, then port the change and copy the fixture there. +// +// Pure functions, no `node:` imports: the Cloudflare Worker bundles this file. + +export const SCHEMA_CONTEXT = 'https://schema.org'; + +// The @context values we accept: schema.org over https or http, with or +// without the trailing slash. Any non-string @context (an array or an object, +// both valid JSON-LD) is accepted as is. +const ACCEPTED_CONTEXTS = new Set(['https://schema.org', 'http://schema.org']); + +const PLACEHOLDER = /\{\{[A-Z0-9_]+\}\}/; + +// Required top-level fields per @type. Keep this minimal: only the fields +// that are genuinely necessary for the snippet to be useful, not every +// recommended field. When adding a new template, add an entry here. +export const REQUIRED_BY_TYPE = { + Article: ['headline', 'author', 'publisher', 'datePublished'], + BlogPosting: ['headline', 'author', 'publisher', 'datePublished'], + BreadcrumbList: ['itemListElement'], + Course: ['name', 'description', 'provider'], + Dataset: ['name', 'description', 'creator', 'distribution'], + DefinedTerm: ['name', 'description'], + DefinedTermSet: ['name', 'hasDefinedTerm'], + Event: ['name', 'startDate', 'location'], + FAQPage: ['mainEntity'], + HowTo: ['name', 'step'], + HowToTip: ['text'], + ItemList: ['itemListElement'], + JobPosting: ['title', 'description', 'datePosted', 'hiringOrganization'], + LocalBusiness: ['name', 'address', 'telephone'], + Organization: ['name', 'url', 'logo'], + Product: ['name', 'offers'], + ProfilePage: ['mainEntity'], + QAPage: ['mainEntity'], + Recipe: ['name', 'recipeIngredient', 'recipeInstructions'], + Review: ['author', 'itemReviewed', 'reviewRating'], + Service: ['name', 'provider'], + SoftwareApplication: ['name', 'applicationCategory', 'operatingSystem', 'offers'], + VideoObject: ['name', 'description', 'thumbnailUrl', 'uploadDate'], + WebSite: ['name', 'url'], +}; + +const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v); + +// Absent, null, '', [] and {} all count as "not there" (Python's falsy, so +// the platform port reads the same). +function isEmpty(v) { + if (v === undefined || v === null || v === '') return true; + if (Array.isArray(v)) return v.length === 0; + if (isObject(v)) return Object.keys(v).length === 0; + return false; +} + +function hasPlaceholder(node) { + if (typeof node === 'string') return PLACEHOLDER.test(node); + if (Array.isArray(node)) return node.some(hasPlaceholder); + if (isObject(node)) return Object.values(node).some(hasPlaceholder); + return false; +} + +/** + * The label of a node: its @type, or the first string of an @type list. + * Null when there is none. + */ +export function nodeType(node) { + const raw = node['@type']; + const types = typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw : []; + const first = types.find((t) => typeof t === 'string' && t.trim() !== ''); + return first === undefined ? null : first; +} + +/** + * Every JSON-LD object in a parsed document: arrays and @graph are expanded, + * and a node inherits the @context of the wrapper it sits in (that is how + * JSON-LD works, and how most CMSs ship it). + * @returns {Array<{ node: object, context: unknown }>} + */ +export function flattenJsonLd(doc, context) { + if (Array.isArray(doc)) return doc.flatMap((item) => flattenJsonLd(item, context)); + if (!isObject(doc)) return []; + const own = isEmpty(doc['@context']) ? context : doc['@context']; + if (Array.isArray(doc['@graph'])) return doc['@graph'].flatMap((item) => flattenJsonLd(item, own)); + return [{ node: doc, context: own }]; +} + +/** + * Checks one JSON-LD object. `context` is the @context it inherits. + * Unknown @types are not an error: schema.org has hundreds, we only know the + * required fields of the ones we ship a template for. + * @returns {{ type: string, valid: boolean, errors: string[] }} + */ +export function validateNode(node, context, { placeholders = true } = {}) { + const errors = []; + const ctx = isEmpty(node['@context']) ? context : node['@context']; + if (isEmpty(ctx)) errors.push('missing "@context"'); + else if (typeof ctx === 'string' && !ACCEPTED_CONTEXTS.has(ctx.replace(/\/+$/, ''))) { + errors.push('unexpected "@context": ' + JSON.stringify(ctx)); + } + + const type = nodeType(node); + if (type === null) { + errors.push('missing "@type"'); + return { type: 'Unknown', valid: false, errors }; + } + + for (const field of REQUIRED_BY_TYPE[type] || []) { + const v = node[field]; + if (v === undefined || v === null) errors.push('missing required field "' + field + '" for @type "' + type + '"'); + else if (Array.isArray(v) && v.length === 0) errors.push('required field "' + field + '" for @type "' + type + '" is empty'); + else if (typeof v === 'string' && v.trim() === '') errors.push('required field "' + field + '" for @type "' + type + '" is blank'); + } + + if (placeholders && hasPlaceholder(node)) errors.push('still contains unfilled {{PLACEHOLDER}} tokens'); + + return { type, valid: errors.length === 0, errors }; +} + +/** + * Checks a pasted JSON-LD text: one object, an array or a @graph. + * `errors` is every node's errors in order; `items` has them per node. + * `parseError` is the parser's own message when the text is not JSON (it + * depends on the engine, so it is kept apart from `errors`). + * @returns {{ ok: boolean, errors: string[], items: Array<{type: string, valid: boolean, errors: string[]}>, parseError?: string }} + */ +export function validateJsonLd(text, opts = {}) { + if (typeof text !== 'string' || !text.trim()) return { ok: false, errors: ['empty input'], items: [] }; + let doc; + try { + doc = JSON.parse(text); + } catch (e) { + return { ok: false, errors: ['invalid JSON'], items: [], parseError: e.message }; + } + const items = flattenJsonLd(doc).map(({ node, context }) => validateNode(node, context, opts)); + if (!items.length) return { ok: false, errors: ['no JSON-LD object found'], items }; + const errors = items.flatMap((item) => item.errors); + return { ok: errors.length === 0, errors, items }; +} diff --git a/test/fixtures/golden.json b/test/fixtures/golden.json new file mode 100644 index 0000000..fb88bdb --- /dev/null +++ b/test/fixtures/golden.json @@ -0,0 +1,523 @@ +{ + "_about": "Golden cases for the JSON-LD check of @geosuite/schema-templates (src/validate.js) and GeoSuite's Schema Helper (backend/services/tools/schema_helper_service.py). Both repos run every case; GeoSuite keeps a byte-identical copy in backend/tests/fixtures/schema_templates_golden.json. templates_sha256 pins the templates GeoSuite vendors in backend/data/schema_templates/. Change the rule and this file here first, then copy both to GeoSuite.", + "required_by_type": { + "Article": [ + "headline", + "author", + "publisher", + "datePublished" + ], + "BlogPosting": [ + "headline", + "author", + "publisher", + "datePublished" + ], + "BreadcrumbList": [ + "itemListElement" + ], + "Course": [ + "name", + "description", + "provider" + ], + "Dataset": [ + "name", + "description", + "creator", + "distribution" + ], + "DefinedTerm": [ + "name", + "description" + ], + "DefinedTermSet": [ + "name", + "hasDefinedTerm" + ], + "Event": [ + "name", + "startDate", + "location" + ], + "FAQPage": [ + "mainEntity" + ], + "HowTo": [ + "name", + "step" + ], + "HowToTip": [ + "text" + ], + "ItemList": [ + "itemListElement" + ], + "JobPosting": [ + "title", + "description", + "datePosted", + "hiringOrganization" + ], + "LocalBusiness": [ + "name", + "address", + "telephone" + ], + "Organization": [ + "name", + "url", + "logo" + ], + "Product": [ + "name", + "offers" + ], + "ProfilePage": [ + "mainEntity" + ], + "QAPage": [ + "mainEntity" + ], + "Recipe": [ + "name", + "recipeIngredient", + "recipeInstructions" + ], + "Review": [ + "author", + "itemReviewed", + "reviewRating" + ], + "Service": [ + "name", + "provider" + ], + "SoftwareApplication": [ + "name", + "applicationCategory", + "operatingSystem", + "offers" + ], + "VideoObject": [ + "name", + "description", + "thumbnailUrl", + "uploadDate" + ], + "WebSite": [ + "name", + "url" + ] + }, + "templates_sha256": { + "Article.json": "c701551efb01cfb7b1a13513ce4bd9f65bfada30bfebf65ed492626dce01a72d", + "BreadcrumbList.json": "9c9997a4f55ff6808874128b93dee8c82c17d28b001bf855438d510ea280615b", + "Course.json": "7af92eaff846e7facadc362d4206757c1af20e706906d8c4c1f98362115e2952", + "Dataset.json": "5be2cca47df0c5bc34b6d743531f3c423856d8926a520eec5b3067c9a95e4604", + "DefinedTerm.json": "e5c74a7397310d5557a6d11a288e4ad0468cb2daf75ca621fa48fa03b675cce9", + "DefinedTermSet.json": "1aaeacf1fa3a114ca221deb557a5387f933d032eef856aac59bcec7af8ea796e", + "Event.json": "00caf41dc7597e84acd9b608889a89b168df71f896e8158a1a1e3cb93202d195", + "FAQPage.json": "62ce213c9c6794b67992f33c28d358d97340da4ae6d6cd079c17083f758ad0c2", + "HowTo.json": "c7bd96f866ffafd12fdf0cd7d2a15e29e99589789c1c886c68c5f04733bdcc5a", + "HowToTip.json": "1028849eeb38dfcdd6c6b4bc9067e2abe8f612241dbb58703124845137fa7857", + "ItemList.json": "e19d889297b22a84e54ec30ff6e925f7f6f3c349ad0acea78acc1f5ebcbefd1b", + "JobPosting.json": "ec3e2f1ab9cdf2bec9a50a5c077bddd702a0db7eb8599a4c24d5c4fd5b5c5b3b", + "LocalBusiness.json": "ff6e0846ed471c9f63ff3a52cc2ca7de6b2c2ecb74e8063d0c94695e9ddd1ad9", + "Organization.json": "c019c7d392d40781137eb14ccdc48edaecf61a331a9408a0947bc009ca785de6", + "Product.json": "5fe9b174ff012571c758d5b71cba2b11814a8e49c655ab4ad2181a68271a3f87", + "ProfilePage.json": "ea11040ab8ccfcc29ce9680063c1b965bfb5fd6d3972b2f77fb878ce85ad3e9b", + "QAPage.json": "e5a718ff85edf3a59a3f684f563ed9af1c5b428e90f7702e26ad7ab0a26f969d", + "Recipe.json": "60af8ff1f84febd8cf14404ec4cf05f74e9d17e0a4ff496ac03e58db4cef64e1", + "Review.json": "fa44df47d7e72b638ab9a783700fbb08294d79295493203a2efacac242a30683", + "Service.json": "882663ed740eeb1f4d173e36d00bfc0c42b32e05137bb14b30b9f1650df2d747", + "SoftwareApplication.json": "d8bbfd38f933783b462b1300581c71d9ef9f227c251e39489b2b04cbd570bb9a", + "VideoObject.json": "d048de83edd9299cbf8eed97730553e8c6c3fbf12020978e7290efade5e4ad5b", + "WebSite.json": "c160565b9241d42d63b8f5124c4bb5e2ce80114277d587c4be597b300805db97" + }, + "validate_cases": [ + { + "name": "a complete Organization is valid", + "input": "{\"@context\": \"https://schema.org\", \"@type\": \"Organization\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}", + "expected": { + "ok": true, + "errors": [], + "items": [ + { + "type": "Organization", + "valid": true, + "errors": [] + } + ] + } + }, + { + "name": "a Product without offers misses a required field", + "input": "{\"@context\": \"https://schema.org\", \"@type\": \"Product\", \"name\": \"Widget\"}", + "expected": { + "ok": false, + "errors": [ + "missing required field \"offers\" for @type \"Product\"" + ], + "items": [ + { + "type": "Product", + "valid": false, + "errors": [ + "missing required field \"offers\" for @type \"Product\"" + ] + } + ] + } + }, + { + "name": "http and a trailing slash are schema.org too", + "input": "{\"@context\": \"http://schema.org/\", \"@type\": \"Organization\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}", + "expected": { + "ok": true, + "errors": [], + "items": [ + { + "type": "Organization", + "valid": true, + "errors": [] + } + ] + } + }, + { + "name": "a context that is not schema.org is flagged", + "input": "{\"@context\": \"https://example.org/\", \"@type\": \"Organization\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}", + "expected": { + "ok": false, + "errors": [ + "unexpected \"@context\": \"https://example.org/\"" + ], + "items": [ + { + "type": "Organization", + "valid": false, + "errors": [ + "unexpected \"@context\": \"https://example.org/\"" + ] + } + ] + } + }, + { + "name": "a missing context is flagged", + "input": "{\"@type\": \"Organization\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}", + "expected": { + "ok": false, + "errors": [ + "missing \"@context\"" + ], + "items": [ + { + "type": "Organization", + "valid": false, + "errors": [ + "missing \"@context\"" + ] + } + ] + } + }, + { + "name": "an empty-string context counts as missing", + "input": "{\"@context\": \"\", \"@type\": \"Organization\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}", + "expected": { + "ok": false, + "errors": [ + "missing \"@context\"" + ], + "items": [ + { + "type": "Organization", + "valid": false, + "errors": [ + "missing \"@context\"" + ] + } + ] + } + }, + { + "name": "an array context is accepted as is", + "input": "{\"@context\": [\"https://schema.org\", {\"@language\": \"it\"}], \"@type\": \"Organization\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}", + "expected": { + "ok": true, + "errors": [], + "items": [ + { + "type": "Organization", + "valid": true, + "errors": [] + } + ] + } + }, + { + "name": "a list @type is labelled and checked by its first string", + "input": "{\"@context\": \"https://schema.org\", \"@type\": [\"Organization\", \"LocalBusiness\"], \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}", + "expected": { + "ok": true, + "errors": [], + "items": [ + { + "type": "Organization", + "valid": true, + "errors": [] + } + ] + } + }, + { + "name": "a list @type that starts with LocalBusiness needs its fields", + "input": "{\"@context\": \"https://schema.org\", \"@type\": [5, \"LocalBusiness\", \"Organization\"], \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}", + "expected": { + "ok": false, + "errors": [ + "missing required field \"address\" for @type \"LocalBusiness\"", + "missing required field \"telephone\" for @type \"LocalBusiness\"" + ], + "items": [ + { + "type": "LocalBusiness", + "valid": false, + "errors": [ + "missing required field \"address\" for @type \"LocalBusiness\"", + "missing required field \"telephone\" for @type \"LocalBusiness\"" + ] + } + ] + } + }, + { + "name": "a missing @type is flagged", + "input": "{\"@context\": \"https://schema.org\", \"name\": \"Acme\"}", + "expected": { + "ok": false, + "errors": [ + "missing \"@type\"" + ], + "items": [ + { + "type": "Unknown", + "valid": false, + "errors": [ + "missing \"@type\"" + ] + } + ] + } + }, + { + "name": "an empty object misses both context and type", + "input": "{}", + "expected": { + "ok": false, + "errors": [ + "missing \"@context\"", + "missing \"@type\"" + ], + "items": [ + { + "type": "Unknown", + "valid": false, + "errors": [ + "missing \"@context\"", + "missing \"@type\"" + ] + } + ] + } + }, + { + "name": "a type we ship no template for is not an error", + "input": "{\"@context\": \"https://schema.org\", \"@type\": \"Thing\", \"name\": \"x\"}", + "expected": { + "ok": true, + "errors": [], + "items": [ + { + "type": "Thing", + "valid": true, + "errors": [] + } + ] + } + }, + { + "name": "@graph items inherit the wrapper context", + "input": "{\"@context\": \"https://schema.org\", \"@graph\": [{\"@type\": \"Organization\", \"@id\": \"#org\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/l.png\"}, {\"@type\": \"WebSite\", \"name\": \"Acme\", \"url\": \"https://acme.test\"}]}", + "expected": { + "ok": true, + "errors": [], + "items": [ + { + "type": "Organization", + "valid": true, + "errors": [] + }, + { + "type": "WebSite", + "valid": true, + "errors": [] + } + ] + } + }, + { + "name": "a @graph item with its own context uses it", + "input": "{\"@context\": \"https://schema.org\", \"@graph\": [{\"@type\": \"WebSite\", \"name\": \"Acme\", \"url\": \"https://acme.test\"}, {\"@context\": \"https://example.org\", \"@type\": \"Thing\"}]}", + "expected": { + "ok": false, + "errors": [ + "unexpected \"@context\": \"https://example.org\"" + ], + "items": [ + { + "type": "WebSite", + "valid": true, + "errors": [] + }, + { + "type": "Thing", + "valid": false, + "errors": [ + "unexpected \"@context\": \"https://example.org\"" + ] + } + ] + } + }, + { + "name": "a top-level array: each object needs its own context", + "input": "[{\"@context\": \"https://schema.org\", \"@type\": \"Organization\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\"}, {\"@type\": \"WebSite\", \"name\": \"Acme\", \"url\": \"https://acme.test\"}]", + "expected": { + "ok": false, + "errors": [ + "missing \"@context\"" + ], + "items": [ + { + "type": "Organization", + "valid": true, + "errors": [] + }, + { + "type": "WebSite", + "valid": false, + "errors": [ + "missing \"@context\"" + ] + } + ] + } + }, + { + "name": "an empty required list is flagged", + "input": "{\"@context\": \"https://schema.org\", \"@type\": \"FAQPage\", \"mainEntity\": []}", + "expected": { + "ok": false, + "errors": [ + "required field \"mainEntity\" for @type \"FAQPage\" is empty" + ], + "items": [ + { + "type": "FAQPage", + "valid": false, + "errors": [ + "required field \"mainEntity\" for @type \"FAQPage\" is empty" + ] + } + ] + } + }, + { + "name": "blank and null required fields are flagged", + "input": "{\"@context\": \"https://schema.org\", \"@type\": \"Organization\", \"name\": \" \", \"url\": \"https://acme.test\", \"logo\": null}", + "expected": { + "ok": false, + "errors": [ + "required field \"name\" for @type \"Organization\" is blank", + "missing required field \"logo\" for @type \"Organization\"" + ], + "items": [ + { + "type": "Organization", + "valid": false, + "errors": [ + "required field \"name\" for @type \"Organization\" is blank", + "missing required field \"logo\" for @type \"Organization\"" + ] + } + ] + } + }, + { + "name": "a leftover placeholder is flagged", + "input": "{\"@context\": \"https://schema.org\", \"@type\": \"Organization\", \"name\": \"Acme\", \"url\": \"https://acme.test\", \"logo\": \"https://acme.test/logo.png\", \"address\": {\"@type\": \"PostalAddress\", \"streetAddress\": \"{{STREET_ADDRESS}}\"}}", + "expected": { + "ok": false, + "errors": [ + "still contains unfilled {{PLACEHOLDER}} tokens" + ], + "items": [ + { + "type": "Organization", + "valid": false, + "errors": [ + "still contains unfilled {{PLACEHOLDER}} tokens" + ] + } + ] + } + }, + { + "name": "text that is not JSON", + "input": "{\"@context\": \"https://schema.org\",", + "expected": { + "ok": false, + "errors": [ + "invalid JSON" + ], + "items": [] + } + }, + { + "name": "a JSON value with no object in it", + "input": "42", + "expected": { + "ok": false, + "errors": [ + "no JSON-LD object found" + ], + "items": [] + } + }, + { + "name": "an array with no object in it", + "input": "[1, \"two\", null]", + "expected": { + "ok": false, + "errors": [ + "no JSON-LD object found" + ], + "items": [] + } + }, + { + "name": "empty input", + "input": " \n", + "expected": { + "ok": false, + "errors": [ + "empty input" + ], + "items": [] + } + } + ] +} diff --git a/test/test-golden.js b/test/test-golden.js new file mode 100644 index 0000000..6e4be51 --- /dev/null +++ b/test/test-golden.js @@ -0,0 +1,45 @@ +// The golden cases shared with GeoSuite's Schema Helper +// (backend/tests/tools/test_schema_helper_golden.py runs the same file). +// A failure here means the check changed: update test/fixtures/golden.json +// on purpose, then port the change and copy the fixture to GeoSuite. +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { readFileSync, readdirSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { REQUIRED_BY_TYPE, validateJsonLd } from "../src/validate.js"; + +const repoRoot = join(dirname(fileURLToPath(import.meta.url)), ".."); +const golden = JSON.parse(readFileSync(join(repoRoot, "test/fixtures/golden.json"), "utf8")); + +test("REQUIRED_BY_TYPE is the one in the golden file", () => { + assert.deepEqual(REQUIRED_BY_TYPE, golden.required_by_type); +}); + +test("the golden file pins every shipped template", () => { + const actual = {}; + for (const name of readdirSync(join(repoRoot, "templates")).filter((f) => f.endsWith(".json")).sort()) { + actual[name] = createHash("sha256").update(readFileSync(join(repoRoot, "templates", name))).digest("hex"); + } + assert.deepEqual(actual, golden.templates_sha256); +}); + +for (const c of golden.validate_cases) { + test(`golden: ${c.name}`, () => { + const { ok, errors, items } = validateJsonLd(c.input); + assert.deepEqual({ ok, errors, items }, c.expected); + }); +} + +test("a parse error keeps the parser's message apart", () => { + const out = validateJsonLd("{oops"); + assert.deepEqual(out.errors, ["invalid JSON"]); + assert.ok(out.parseError); +}); + +test("the templates themselves pass when placeholders are allowed", () => { + const raw = readFileSync(join(repoRoot, "templates/Organization.json"), "utf8"); + assert.equal(validateJsonLd(raw).ok, false); + assert.equal(validateJsonLd(raw, { placeholders: false }).ok, true); +}); diff --git a/validate.js b/validate.js index 14ba23f..cd03471 100644 --- a/validate.js +++ b/validate.js @@ -5,10 +5,10 @@ * * Checks performed (no network calls): * 1. file is well-formed JSON - * 2. @context is present and equals "https://schema.org" - * 3. @type is present - * 4. all required fields for the declared @type exist (per the - * REQUIRED_BY_TYPE map below) + * 2. the shared JSON-LD check of src/validate.js (@context, @type, the + * required fields of REQUIRED_BY_TYPE, leftover placeholders in examples) + * 3. house rules: the canonical "https://schema.org" @context and a + * string @type that REQUIRED_BY_TYPE knows * * Exits with non-zero status if any file fails. */ @@ -16,41 +16,10 @@ import { readdirSync, readFileSync, statSync } from "node:fs"; import { join, dirname, basename } from "node:path"; import { fileURLToPath } from "node:url"; +import { REQUIRED_BY_TYPE, SCHEMA_CONTEXT, validateJsonLd } from "./src/validate.js"; const __dirname = dirname(fileURLToPath(import.meta.url)); -// Required top-level fields per @type. Keep this minimal: only the fields -// that are genuinely necessary for the snippet to be useful, not every -// recommended field. When adding a new template, add an entry here. -const REQUIRED_BY_TYPE = { - SoftwareApplication: ["name", "applicationCategory", "operatingSystem", "offers"], - HowTo: ["name", "step"], - HowToTip: ["text"], - DefinedTerm: ["name", "description"], - DefinedTermSet: ["name", "hasDefinedTerm"], - FAQPage: ["mainEntity"], - QAPage: ["mainEntity"], - Dataset: ["name", "description", "creator", "distribution"], - BreadcrumbList: ["itemListElement"], - Organization: ["name", "url", "logo"], - LocalBusiness: ["name", "address", "telephone"], - BlogPosting: ["headline", "author", "publisher", "datePublished"], - Article: ["headline", "author", "publisher", "datePublished"], - ItemList: ["itemListElement"], - ProfilePage: ["mainEntity"], - Product: ["name", "offers"], - Review: ["author", "itemReviewed", "reviewRating"], - Event: ["name", "startDate", "location"], - Service: ["name", "provider"], - JobPosting: ["title", "description", "datePosted", "hiringOrganization"], - Course: ["name", "description", "provider"], - Recipe: ["name", "recipeIngredient", "recipeInstructions"], - VideoObject: ["name", "description", "thumbnailUrl", "uploadDate"], - WebSite: ["name", "url"], -}; - -const SCHEMA_CONTEXT = "https://schema.org"; - function listJsonFiles(dir) { if (!statSync(dir, { throwIfNoEntry: false })) return []; return readdirSync(dir) @@ -58,62 +27,30 @@ function listJsonFiles(dir) { .map((f) => join(dir, f)); } +// The shared check (src/validate.js, the same one the web tool and GeoSuite +// run), plus the house rules for the files we ship: one top-level object, +// the canonical "https://schema.org" context, a string @type we know. +// Templates keep their {{PLACEHOLDER}} tokens; examples must have none. function checkFile(path) { - const errors = []; const raw = readFileSync(path, "utf8"); + const isTemplate = basename(dirname(path)) === "templates"; + const result = validateJsonLd(raw, { placeholders: !isTemplate }); + if (result.parseError) return [`invalid JSON: ${result.parseError}`]; - let doc; - try { - doc = JSON.parse(raw); - } catch (err) { - errors.push(`invalid JSON: ${err.message}`); - return errors; - } - + const errors = [...result.errors]; + const doc = JSON.parse(raw); if (typeof doc !== "object" || doc === null || Array.isArray(doc)) { - errors.push("top-level value must be a JSON object"); - return errors; + return ["top-level value must be a JSON object"]; } - - const ctx = doc["@context"]; - if (!ctx) { - errors.push('missing "@context"'); - } else if (ctx !== SCHEMA_CONTEXT) { - errors.push(`"@context" must be "${SCHEMA_CONTEXT}", got ${JSON.stringify(ctx)}`); + if (doc["@context"] && doc["@context"] !== SCHEMA_CONTEXT) { + errors.push(`"@context" must be "${SCHEMA_CONTEXT}", got ${JSON.stringify(doc["@context"])}`); } - const type = doc["@type"]; - if (!type) { - errors.push('missing "@type"'); - return errors; - } - if (typeof type !== "string") { + if (type && typeof type !== "string") { errors.push('"@type" must be a string at the top level'); - return errors; + } else if (type && !REQUIRED_BY_TYPE[type]) { + errors.push(`unknown @type "${type}" (add it to REQUIRED_BY_TYPE in src/validate.js)`); } - - const required = REQUIRED_BY_TYPE[type]; - if (!required) { - errors.push( - `unknown @type "${type}" — add it to REQUIRED_BY_TYPE in validate.js` - ); - return errors; - } - - for (const field of required) { - const v = doc[field]; - if (v === undefined || v === null) { - errors.push(`missing required field "${field}" for @type "${type}"`); - continue; - } - if (Array.isArray(v) && v.length === 0) { - errors.push(`required field "${field}" for @type "${type}" is empty`); - } - if (typeof v === "string" && v.trim() === "") { - errors.push(`required field "${field}" for @type "${type}" is blank`); - } - } - return errors; } diff --git a/web/README.md b/web/README.md index 60c76ad..006528a 100644 --- a/web/README.md +++ b/web/README.md @@ -3,14 +3,14 @@ A [Cloudflare Worker](https://developers.cloudflare.com/workers/) that puts [`schema-templates`](../) on the web: pick a schema.org type and copy the JSON-LD template, or paste your own JSON-LD and validate it. The validator uses -the same structural checks as the repo's `validate.js`. +the repo's `src/validate.js`, the same check GeoSuite's Schema Helper runs. - `GET /` — the page (`page.js`), bilingual **en/it** (auto-detected from `Accept-Language`; `/en` · `/it` force a locale) - `GET /og.png` · `GET /favicon.png` — Open Graph share image (1200×630) + GeoSuite's favicon (also at `/favicon.ico`, `/apple-touch-icon.png` and the old `/favicon.svg`) - `GET /logos/{chatgpt,gemini,perplexity}.svg` — the engine logos in the page's call to action - `GET /api/templates` — list of available types - `GET /api/template?type=Organization` — one template (`{ type, json }`) -- `POST /api/validate` — body is your JSON-LD; returns `{ ok, errors }` +- `POST /api/validate`: body is your JSON-LD; returns `{ ok, errors, items }` (`items`: one entry per object, `@graph` expanded; `parseError` when the text is not JSON) No database, no tracking, no network calls — the templates are bundled and the validator runs in the Worker. @@ -47,7 +47,7 @@ secrets (Settings → Secrets and variables → Actions): ## Notes - `web/templates-bundle.js` imports every `templates/*.json`; add a line there - when you add a template. The validator's `REQUIRED_BY_TYPE` in `worker.js` - mirrors `../validate.js` — keep them in sync. + when you add a template. The validator is `../src/validate.js`, imported + as is: there is no copy to keep in sync. - This directory is **not** part of the npm package, so it never ships to registry consumers. diff --git a/web/page.js b/web/page.js index 68360b9..723b571 100644 --- a/web/page.js +++ b/web/page.js @@ -51,7 +51,7 @@ const S = { inLabel: 'Your JSON-LD', inPlaceholder: 'Paste your JSON-LD here, e.g. { "@context": "https://schema.org", "@type": "Organization", ... }', validate: 'Validate', - validateHint: 'Checks the JSON, @context, @type, the required fields and leftover placeholders.', + validateHint: 'Checks the JSON (one object, an array or a @graph), @context, @type, the required fields and leftover placeholders: the same check GeoSuite runs on your pages.', ctaTitle: 'Readable is step one. Recommended is the goal.', ctaText: 'Structured data tells AI what your business is. GeoSuite checks whether ChatGPT, Gemini and Perplexity actually recommend it: it asks them the questions your customers really ask, and tells you where you appear, who wins instead and what to fix first. The report arrives by email.', ctaButton: 'Get the free analysis', @@ -92,7 +92,7 @@ const S = { inLabel: 'Il tuo JSON-LD', inPlaceholder: 'Incolla qui il tuo JSON-LD, ad esempio { "@context": "https://schema.org", "@type": "Organization", ... }', validate: 'Valida', - validateHint: 'Controlla il JSON, @context, @type, i campi obbligatori e i placeholder rimasti.', + validateHint: 'Controlla il JSON (un oggetto, un array o un @graph), @context, @type, i campi obbligatori e i placeholder rimasti: lo stesso controllo che GeoSuite fa sulle tue pagine.', ctaTitle: 'Farsi leggere è il primo passo. Farsi consigliare è l’obiettivo.', ctaText: 'I dati strutturati dicono alle AI chi sei. GeoSuite verifica se ChatGPT, Gemini e Perplexity ti consigliano davvero: fa loro le domande che fanno i tuoi clienti e ti dice dove compari, chi vince al posto tuo e cosa correggere per primo. Il report arriva via mail.', ctaButton: 'Richiedi l’analisi gratuita', @@ -336,7 +336,10 @@ ${BASE_CSS} .then(function(r){ return r.json(); }) .then(function(d){ if (d.ok){ vout.innerHTML = '

' + ICONS.ok + '' + I18N.valid + '

'; return; } - var items = (d.errors || []).map(function(e){ return '
  • ' + esc(e) + '
  • '; }).join(''); + var items = (d.errors || []).map(function(e){ + // The parser's own message (line, column) helps more than "invalid JSON" alone. + if (e === 'invalid JSON' && d.parseError) e = e + ': ' + d.parseError; + return '
  • ' + esc(e) + '
  • '; }).join(''); vout.innerHTML = '

    ' + ICONS.missing + '' + I18N.issuesPre + (d.errors || []).length + I18N.issuesPost + '

    '; }) .catch(function(){ vout.innerHTML = '

    ' + ICONS.missing + '' + I18N.networkError + '

    '; }); diff --git a/web/worker.js b/web/worker.js index 6f8f50d..95ade51 100644 --- a/web/worker.js +++ b/web/worker.js @@ -3,9 +3,8 @@ // Two jobs, both offline (no deps, no node:, no nodejs_compat needed): // 1. Hand out copy-paste schema.org JSON-LD templates (the bundled // templates/*.json). -// 2. Validate pasted JSON-LD with the same structural checks as the repo's -// validate.js (reimplemented here as a pure function — keep REQUIRED_BY_TYPE -// in sync with validate.js). +// 2. Validate pasted JSON-LD with ../src/validate.js, the check GeoSuite's +// Schema Helper runs too (same golden cases on both sides). // // Routes: // GET / → the page (web/page.js), locale from Accept-Language @@ -17,10 +16,11 @@ // GET /logos/{chatgpt,gemini,perplexity}.svg → engine logos in the CTA // GET /api/templates → ["Article", "Organization", …] // GET /api/template?type=X → { type, json } -// POST /api/validate (body=JSON-LD text) → { ok, errors } +// POST /api/validate (body=JSON-LD text) → { ok, errors, items[, parseError] } import { TEMPLATES } from './templates-bundle.js'; import { renderPage } from './page.js'; +import { validateJsonLd } from '../src/validate.js'; import OG_PNG from './og.png'; // bundled as ArrayBuffer via the wrangler "Data" rule import FAVICON_PNG from './favicon.png'; // GeoSuite's official favicon, 96px import APPLE_TOUCH_PNG from './apple-touch-icon.png'; // the same, 180px @@ -30,8 +30,6 @@ import LOGO_PERPLEXITY from './logos/perplexity.svg'; const ENGINE_LOGOS = { chatgpt: LOGO_CHATGPT, gemini: LOGO_GEMINI, perplexity: LOGO_PERPLEXITY }; -const SCHEMA_CONTEXT = 'https://schema.org'; - // '/it' → 'it', '/en' → 'en', '/' → first Accept-Language tag (it → 'it', else 'en'). function pickLang(request, path) { if (path === '/it') return 'it'; @@ -40,72 +38,6 @@ function pickLang(request, path) { return first.startsWith('it') ? 'it' : 'en'; } -// Mirror of REQUIRED_BY_TYPE in ../validate.js — keep in sync when that changes. -const REQUIRED_BY_TYPE = { - SoftwareApplication: ['name', 'applicationCategory', 'operatingSystem', 'offers'], - HowTo: ['name', 'step'], - HowToTip: ['text'], - DefinedTerm: ['name', 'description'], - DefinedTermSet: ['name', 'hasDefinedTerm'], - FAQPage: ['mainEntity'], - QAPage: ['mainEntity'], - Dataset: ['name', 'description', 'creator', 'distribution'], - BreadcrumbList: ['itemListElement'], - Organization: ['name', 'url', 'logo'], - LocalBusiness: ['name', 'address', 'telephone'], - BlogPosting: ['headline', 'author', 'publisher', 'datePublished'], - Article: ['headline', 'author', 'publisher', 'datePublished'], - ItemList: ['itemListElement'], - ProfilePage: ['mainEntity'], - Product: ['name', 'offers'], - Review: ['author', 'itemReviewed', 'reviewRating'], - Event: ['name', 'startDate', 'location'], - Service: ['name', 'provider'], - JobPosting: ['title', 'description', 'datePosted', 'hiringOrganization'], - Course: ['name', 'description', 'provider'], - Recipe: ['name', 'recipeIngredient', 'recipeInstructions'], - VideoObject: ['name', 'description', 'thumbnailUrl', 'uploadDate'], - WebSite: ['name', 'url'], -}; - -function validateJsonLd(text) { - const errors = []; - let doc; - try { - doc = JSON.parse(text); - } catch (e) { - return { ok: false, errors: ['invalid JSON: ' + e.message] }; - } - if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) { - return { ok: false, errors: ['top-level value must be a JSON object'] }; - } - - const ctx = doc['@context']; - if (!ctx) errors.push('missing "@context"'); - else if (ctx !== SCHEMA_CONTEXT) errors.push('"@context" must be "' + SCHEMA_CONTEXT + '", got ' + JSON.stringify(ctx)); - - const type = doc['@type']; - if (!type) return { ok: false, errors: errors.concat('missing "@type"') }; - if (typeof type !== 'string') return { ok: false, errors: errors.concat('"@type" must be a string at the top level') }; - - const required = REQUIRED_BY_TYPE[type]; - if (!required) return { ok: false, errors: errors.concat('unknown @type "' + type + '" (not in the template set)') }; - - for (const field of required) { - const v = doc[field]; - if (v === undefined || v === null) { - errors.push('missing required field "' + field + '" for @type "' + type + '"'); - continue; - } - if (Array.isArray(v) && v.length === 0) errors.push('required field "' + field + '" for @type "' + type + '" is empty'); - if (typeof v === 'string' && v.trim() === '') errors.push('required field "' + field + '" for @type "' + type + '" is blank'); - } - - if (/\{\{[A-Z0-9_]+\}\}/.test(text)) errors.push('still contains unfilled {{PLACEHOLDER}} tokens'); - - return { ok: errors.length === 0, errors }; -} - const JSON_HEADERS = { 'content-type': 'application/json; charset=utf-8', 'access-control-allow-origin': '*', @@ -149,9 +81,7 @@ export default { if (url.pathname === '/api/validate') { if (request.method !== 'POST') return json({ error: 'POST your JSON-LD as the request body.' }, 405); - const text = await request.text(); - if (!text.trim()) return json({ ok: false, errors: ['empty input'] }); - return json(validateJsonLd(text)); + return json(validateJsonLd(await request.text())); } if (path === '/' || path === '/en' || path === '/it') {