RDF/JS CSV on the Web Parser

Common errors

• Error: The metadata option is required

  cause The `metadata` option was not provided during parser instantiation or the `.import` call.
  fix Pass an RDF/JS `Dataset` object containing CSVW metadata to the `metadata` option.

• Error: The baseIRI option is required

  cause The `baseIRI` option was not provided, which is essential for resolving relative IRIs.
  fix Provide a string value for `baseIRI` in the parser options, e.g., `new Parser({ baseIRI: 'http://example.org/' })`.

• Error: Column count mismatch in row X

  cause A row in the CSV stream has a different number of columns than expected, and `relaxColumnCount` is not enabled.
  fix Either fix the malformed CSV data, or set `relaxColumnCount: true` in the parser options to ignore these errors.

• TypeError: parser.import is not a function

  cause The `Parser` class was not correctly instantiated, or `import` was called on the class itself instead of an instance.
  fix Ensure you create an instance of the `Parser` class using `new Parser(options)` before calling `.import()`.

Warnings

• gotcha The `metadata` option is strictly required in the parser constructor or `.import` method. It must be an RDF/JS Dataset representing the CSV on the Web metadata for your CSV file.
  Fix: Ensure the `metadata` option is always provided with a valid RDF/JS Dataset containing CSVW definitions.
• gotcha The `baseIRI` option is strictly required to create Named Nodes from relative IRIs within the CSV data.
  Fix: Provide a valid string `baseIRI` in the parser constructor options or the `.import` method options.
• gotcha The `skipLinesWithError` option is primarily for debugging purposes and should not be used in production environments, as it can lead to silent data loss or inconsistent graph generation from malformed CSV lines.
  Fix: Avoid `skipLinesWithError` in production. Instead, pre-process CSV data to ensure correctness or handle errors robustly.
• gotcha By default, the parser will throw an error if a row's column count does not match the headers. Use `relaxColumnCount` if you expect and want to tolerate such discrepancies.
  Fix: Set `relaxColumnCount: true` in the parser options if column count mismatches should not halt parsing.

Install

• npm install rdf-parser-csvw npm
• yarn add rdf-parser-csvw yarn
• pnpm add rdf-parser-csvw pnpm

Imports

• Parser
  wrong:

  import Parser from 'rdf-parser-csvw'

  correct:

  import { Parser } from 'rdf-parser-csvw'

  The parser is exported as a named class `Parser` in ESM. Do not use default import.
• Parser (CommonJS)
  wrong:

  const Parser = require('rdf-parser-csvw')

  correct:

  const { Parser } = require('rdf-parser-csvw')

  For CommonJS, access the `Parser` class as a named property from the module export.
• Parser (Type Import)

  import type { Parser } from 'rdf-parser-csvw'

  When only importing the type for TypeScript, use `import type` for clarity and bundler optimization.

Quickstart

Demonstrates how to instantiate the `Parser` class, construct a minimal CSVW metadata RDF/JS Dataset, and parse a CSV string into RDF quads using streams.

import { Readable } from 'stream';
import { Parser } from 'rdf-parser-csvw';
import rdf from 'rdf-ext'; // A common RDF/JS implementation for DataFactory and Dataset

async function parseCsvw() {
  const csvString = `Name,Age\nAlice,30\nBob,25\nCharlie,35`;
  const baseIRI = 'http://example.org/data/';

  // Construct a minimal CSVW metadata Dataset using rdf-ext
  const metadataDataset = rdf.dataset();
  const ex = rdf.namedNode(baseIRI);
  const csvw = rdf.namedNode('http://www.w3.org/ns/csvw#');
  const rdfType = rdf.namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type');

  const tableGroup = rdf.blankNode();
  const table = rdf.blankNode();
  const column1 = rdf.blankNode();
  const column2 = rdf.blankNode();

  metadataDataset.add(rdf.quad(ex.file, rdfType, csvw.TableGroup));
  metadataDataset.add(rdf.quad(ex.file, csvw.table, table));
  metadataDataset.add(rdf.quad(table, rdfType, csvw.Table));
  metadataDataset.add(rdf.quad(table, csvw.url, rdf.namedNode(`${baseIRI}data.csv`)));

  // Define columns based on CSV headers
  metadataDataset.add(rdf.quad(table, csvw.column, column1));
  metadataDataset.add(rdf.quad(column1, csvw.name, rdf.literal('Name')));
  metadataDataset.add(rdf.quad(column1, csvw.datatype, csvw.string));

  metadataDataset.add(rdf.quad(table, csvw.column, column2));
  metadataDataset.add(rdf.quad(column2, csvw.name, rdf.literal('Age')));
  metadataDataset.add(rdf.quad(column2, csvw.datatype, csvw.integer));

  // Instantiate the parser with required options
  const parser = new Parser({
    metadata: metadataDataset,
    baseIRI: baseIRI,
    factory: rdf // Use rdf-ext's data factory
  });

  // Create a readable stream from the CSV string
  const csvStream = Readable.from([csvString]);

  console.log('Starting CSVW parsing...');
  // Import the CSV stream and get a stream of RDF quads
  const quadStream = parser.import(csvStream);

  // Consume and log the parsed quads
  for await (const quad of quadStream) {
    console.log(quad.toString());
  }
  console.log('Finished parsing.');
}

parseCsvw().catch(console.error);