JSON-LD Conformance Test Suite

Common errors

• Error: Cannot find module 'json-ld-test-suite/manifest.jsonld'

  cause Incorrect path or attempting to import a non-existent JavaScript module. The `manifest.jsonld` file is located within the `tests/` subdirectory of the package.
  fix Use the correct full path to the JSON file: `import manifest from 'json-ld-test-suite/tests/manifest.jsonld'` (ESM) or `const manifest = require('json-ld-test-suite/tests/manifest.jsonld')` (CJS).

• SyntaxError: Unexpected token '<' at JSON.parse (<anonymous>)

  cause Attempting to parse an XML/HTML file (like vocab.html) or a non-JSON file (like .sparql) as JSON. This can happen if the wrong file is targeted or if a raw import of a `.sparql` file is not handled correctly.
  fix Ensure you are targeting actual JSON-LD (`.jsonld`) files for `JSON.parse`. For `.sparql` files, read them as plain text/strings. For example, using a raw import query parameter in ESM (`import query from './my.sparql?raw'`).

Warnings

• gotcha This npm package (json-ld-test-suite@1.0.1) has not been updated in over eight years. While the underlying JSON-LD Conformance Test Suite at json-ld/json-ld.org is actively maintained, updates to the test suite data are not reflected in this npm package. Users requiring the latest test data should consider fetching directly from the GitHub repository or using a different distribution method.
  Fix: For the latest test suite data, clone the git repository directly: `git clone git://github.com/json-ld/json-ld.org.git` or use a different, more current distribution of the JSON-LD test suite.
• gotcha Tests are often marked with specific `processingMode` requirements (e.g., `json-ld-1.0` or `json-ld-1.1`). Processors must only run tests compatible with their implemented JSON-LD version, otherwise, false positives or negatives will occur.
  Fix: Before running a test, inspect its `processingMode` property. If present, ensure your processor's mode matches or skip the test if incompatible. If `processingMode` is absent, the test is generally compatible with both 1.0 and 1.1.
• gotcha Due to its community-driven nature, the JSON-LD Test Suite (the upstream data, not this npm package) 'may become unstable from time to time.' This means new test contributions or fixes could temporarily introduce regressions or inconsistencies, which are typically resolved quickly.
  Fix: If encountering unexpected test failures that are not due to your processor, check the upstream `json-ld/json-ld.org` repository for recent changes, bug reports, or contact the JSON-LD mailing list (public-linked-json@w3.org) for clarification.

Install

• npm install json-ld-test-suite npm
• yarn add json-ld-test-suite yarn
• pnpm add json-ld-test-suite pnpm

Imports

• manifest
  wrong:

  const manifest = require('json-ld-test-suite/manifest.jsonld')

  correct:

  import manifest from 'json-ld-test-suite/tests/manifest.jsonld'

  The package primarily consists of JSON-LD data files. Direct import/require of specific JSON files is the common access pattern. Use the full path.
• testCase
  wrong:

  const testCase = require('json-ld-test-suite/compact-0001-in.jsonld')

  correct:

  import testCase from 'json-ld-test-suite/tests/compact-0001-in.jsonld'

  Individual test files are also directly accessible via their full path within the 'tests' directory. Path must be exact.
• sparqlQuery

  import sparqlQuery from 'json-ld-test-suite/tests/rdf-0001.sparql?raw'

  Some test files are `.sparql` files. In ESM, use a raw import if your bundler supports it (e.g., Vite, Webpack asset modules) to get the string content. For CJS, use `fs.readFileSync`.

Quickstart

Demonstrates how to programmatically load the `json-ld-test-suite` manifest and individual test files from the file system, typically for building a conformance testing harness. This snippet uses Node.js `fs` and `path` modules to read JSON-LD and SPARQL files as raw data.

import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = fileURLToPath(new URL('.', import.meta.url));

// Assuming the package is installed at node_modules/json-ld-test-suite
const packageRoot = join(__dirname, '../node_modules/json-ld-test-suite');

// Load the main manifest for all tests
const manifestPath = join(packageRoot, 'tests/manifest.jsonld');
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));

console.log(`Loaded JSON-LD Test Suite Manifest (v${manifest.version || 'unknown'})`);
console.log(`Number of manifests: ${manifest.sequence.length}`);

// Example: Accessing a specific test entry
const firstManifest = manifest.sequence[0];
console.log(`First test manifest type: ${firstManifest['@type']}`);

// To load an actual test input file, you'd typically iterate through the manifest
// and construct paths based on the 'input' property of each test entry.
// For example, if a test entry has 'input': 'compact-0001-in.jsonld'
const exampleInputPath = join(packageRoot, 'tests/compact-0001-in.jsonld');
const exampleInput = JSON.parse(readFileSync(exampleInputPath, 'utf8'));
console.log('Example test input data:', exampleInput);