Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/deploy-web.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ on:
paths:
- 'web/**'
- 'templates/**'
- 'src/validate.js'
- '.github/workflows/deploy-web.yml'
workflow_dispatch: {}

Expand Down
21 changes: 21 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<TypeName>.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.**

Expand All @@ -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

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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+)

Expand Down
9 changes: 7 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
24 changes: 24 additions & 0 deletions scripts/refresh-golden.js
Original file line number Diff line number Diff line change
@@ -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)`);
146 changes: 146 additions & 0 deletions src/validate.js
Original file line number Diff line number Diff line change
@@ -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 };
}
Loading
Loading