or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

context-processing.mddocument-loading.mderror-handling.mdevent-handling.mdindex.mdrdf-operations.mdtransformations.mdurl-utilities.mdutilities.md
tile.json

tessl/npm-jsonld

A comprehensive JSON-LD Processor and API implementation in JavaScript for processing Linked Data in JSON format

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jsonld@8.3.x

To install, run

npx @tessl/cli install tessl/npm-jsonld@8.3.0

index.mddocs/

JSON-LD

JSON-LD is a comprehensive JavaScript implementation of the JSON-LD specification for processing Linked Data in JSON format. It provides a complete set of APIs for JSON-LD operations including compacting documents according to contexts, expanding documents by removing contexts, flattening nested structures, framing documents into specific tree structures, and canonicalizing/normalizing documents using RDF Dataset Canonicalization algorithms.

Package Information

  • Package Name: jsonld
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install jsonld

Core Imports

const jsonld = require('jsonld');

For ES modules:

import * as jsonld from 'jsonld';
// or specific imports
import {promises} from 'jsonld';
import {JsonLdProcessor} from 'jsonld';

Basic Usage

const jsonld = require('jsonld');

// Sample document
const doc = {
  "http://schema.org/name": "Manu Sporny",
  "http://schema.org/url": {"@id": "http://manu.sporny.org/"},
  "http://schema.org/image": {"@id": "http://manu.sporny.org/images/manu.png"}
};

const context = {
  "name": "http://schema.org/name",
  "homepage": {"@id": "http://schema.org/url", "@type": "@id"},
  "image": {"@id": "http://schema.org/image", "@type": "@id"}
};

// Compact a document according to a particular context
const compacted = await jsonld.compact(doc, context);

// Expand a document, removing its context
const expanded = await jsonld.expand(compacted);

// Flatten a document
const flattened = await jsonld.flatten(doc);

// Convert to RDF
const nquads = await jsonld.toRDF(doc, {format: 'application/n-quads'});

Architecture

JSON-LD is built around several key components:

  • Core Transformations: Primary JSON-LD processing operations (compact, expand, flatten, frame)
  • RDF Integration: Bi-directional conversion between JSON-LD and RDF datasets
  • Document Loading: Extensible system for loading remote contexts and documents
  • Context Processing: Sophisticated context resolution and caching mechanisms
  • Canonicalization: RDF Dataset Canonicalization for cryptographic applications
  • Utility Functions: Comprehensive utilities for JSON-LD data manipulation
  • Error Handling: Structured error system with detailed error information

Capabilities

Core Transformations

Primary JSON-LD processing operations for transforming documents between different forms. These are the most commonly used functions for JSON-LD data processing.

/**
 * Performs JSON-LD compaction according to a context
 */
function compact(input, ctx, options);

/**
 * Performs JSON-LD expansion, removing contexts
 */
function expand(input, options);

/**
 * Performs JSON-LD flattening
 */
function flatten(input, ctx, options);

/**
 * Performs JSON-LD framing into specific tree structures
 */
function frame(input, frame, options);

Core Transformations

RDF Operations

Bi-directional conversion between JSON-LD and RDF datasets, including canonicalization for cryptographic applications.

/**
 * Converts JSON-LD to RDF dataset
 */
function toRDF(input, options);

/**
 * Converts RDF dataset to JSON-LD
 */
function fromRDF(dataset, options);

/**
 * Performs RDF dataset normalization/canonicalization
 */
function normalize(input, options);
function canonize(input, options); // alias for normalize

RDF Operations

Document Loading

Extensible document loading system for fetching remote contexts and JSON-LD documents with customizable loaders.

/**
 * Default document loader for external documents
 */
let documentLoader;

/**
 * Gets remote JSON-LD document using document loader
 */
function get(url, options);

/**
 * Sets default document loader to built-in type
 */
function useDocumentLoader(type, ...params);

/**
 * Registry of available document loaders
 */
const documentLoaders;

Document Loading

Context Processing

Advanced context processing capabilities for resolving and managing JSON-LD contexts.

/**
 * Processes a local context and returns new active context
 */
function processContext(activeCtx, localCtx, options);

Context Processing

Utility Operations

Comprehensive utility functions for JSON-LD data manipulation, node mapping, and experimental features.

/**
 * Creates a merged node map from JSON-LD input
 */
function createNodeMap(input, options);

/**
 * Merges multiple JSON-LD documents
 */
function merge(docs, ctx, options);

/**
 * Links JSON-LD document nodes in memory
 */
function link(input, ctx, options);

Utility Operations

Error Handling

Structured error system with detailed error information for debugging and error recovery.

/**
 * Custom error class for JSON-LD operations
 */
class JsonLdError extends Error {
  constructor(message, name, details);
}

Error Handling

Event Handling

Event handling system for debugging, monitoring, and safe mode operations with built-in event handlers.

/**
 * Logs all events to console
 */
function logEventHandler(event);

/**
 * Sets the default event handler for all operations
 */
function setDefaultEventHandler(handler);

/**
 * Safe event handler that prevents exceptions
 */
function safeEventHandler(event);

Event Handling

URL Utilities

URL manipulation and parsing utilities for IRI processing in JSON-LD operations.

/**
 * Parse URL string using specified parser
 */
function parse(str, parser);

/**
 * Resolve relative IRI against base IRI
 */
function prependBase(base, iri);

/**
 * Remove base IRI to create relative reference
 */
function removeBase(base, iri);

URL Utilities

Types

/**
 * Options object for JSON-LD operations
 */
interface JsonLdOptions {
  base?: string;
  expandContext?: any;
  documentLoader?: (url: string, options?: any) => Promise<RemoteDocument>;
  safe?: boolean;
  [key: string]: any;
}

/**
 * Remote document structure returned by document loaders
 */
interface RemoteDocument {
  contextUrl?: string;
  document: any;
  documentUrl: string;
}

/**
 * WebIDL-compatible processor interface for W3C JSON-LD API compliance
 */
class JsonLdProcessor {
  static compact(input, ctx): Promise<any>;
  static expand(input): Promise<any>;
  static flatten(input): Promise<any>;
  toString(): string;
}

/**
 * Legacy request queue for backward compatibility
 */
class RequestQueue {
  constructor();
}

/**
 * Backward compatibility alias for the main jsonld API
 * All functions are available as jsonld.promises.*
 */
const promises;