tessl/npm-jsonld

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Core Transformations

Name: tessl/npm-jsonld
Author: tessl

Primary JSON-LD processing operations for transforming documents between different forms. These are the most commonly used functions for JSON-LD data processing, each serving a specific purpose in the JSON-LD processing pipeline.

Capabilities

Compact

Performs JSON-LD compaction, which applies a context to a JSON-LD document to make it more concise and human-readable by replacing long IRIs with shorter terms.

/**
 * Performs JSON-LD compaction according to a context
 * @param input - The JSON-LD input to compact
 * @param ctx - The context to compact with
 * @param options - Optional configuration object
 * @returns Promise resolving to the compacted output
 */
function compact(input, ctx, options);

Parameters:

input (any): JSON-LD input to compact, can be a JSON-LD document or URL string
ctx (any): Context to compact with, cannot be null
options (JsonLdOptions, optional): Configuration options

Options:

base (string): Base IRI to use (default: input URL if string, empty string otherwise)
compactArrays (boolean): Compact arrays to single values when appropriate (default: true)
compactToRelative (boolean): Compact IRIs to be relative to document base (default: true)
graph (boolean): Always output a top-level graph (default: false)
expandContext (any): Context to expand with
skipExpansion (boolean): Skip expansion step (default: false)
documentLoader (function): Custom document loader
safe (boolean): Use safe mode (default: false)

Usage Examples:

const jsonld = require('jsonld');

// Basic compaction
const doc = {
  "http://schema.org/name": "Manu Sporny",
  "http://schema.org/url": {"@id": "http://manu.sporny.org/"}
};

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

const compacted = await jsonld.compact(doc, context);
// Result: { "@context": {...}, "name": "Manu Sporny", "homepage": "http://manu.sporny.org/" }

// Compact using URLs
const compacted2 = await jsonld.compact(
  'http://example.org/doc', 
  'http://example.org/context'
);

// Compact with options
const compacted3 = await jsonld.compact(doc, context, {
  base: 'http://example.org/',
  compactArrays: false
});

Expand

Performs JSON-LD expansion, which removes contexts from a JSON-LD document and expands all terms to their full IRI form.

/**
 * Performs JSON-LD expansion, removing contexts
 * @param input - The JSON-LD input to expand
 * @param options - Optional configuration object
 * @returns Promise resolving to the expanded output
 */
function expand(input, options);

Parameters:

input (any): JSON-LD input to expand
options (JsonLdOptions, optional): Configuration options

Options:

base (string): Base IRI to use
expandContext (any): Context to expand with
keepFreeFloatingNodes (boolean): Keep free-floating nodes (default: false)
documentLoader (function): Custom document loader
safe (boolean): Use safe mode (default: false)

Usage Examples:

// Basic expansion
const compacted = {
  "@context": {
    "name": "http://schema.org/name",
    "homepage": {"@id": "http://schema.org/url", "@type": "@id"}
  },
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
};

const expanded = await jsonld.expand(compacted);
// Result: [{
//   "http://schema.org/name": [{"@value": "Manu Sporny"}],
//   "http://schema.org/url": [{"@id": "http://manu.sporny.org/"}]
// }]

// Expand using URLs
const expanded2 = await jsonld.expand('http://example.org/doc');

// Expand with options
const expanded3 = await jsonld.expand(compacted, {
  base: 'http://example.org/',
  keepFreeFloatingNodes: true
});

Flatten

Performs JSON-LD flattening, which produces a flattened array of all nodes in the document, optionally compacted according to a context.

/**
 * Performs JSON-LD flattening
 * @param input - The JSON-LD to flatten
 * @param ctx - The context to use for compaction, or null for no compaction
 * @param options - Optional configuration object
 * @returns Promise resolving to the flattened output
 */
function flatten(input, ctx, options);

Parameters:

input (any): JSON-LD to flatten
ctx (any): Context for compaction (or null for no compaction)
options (JsonLdOptions, optional): Configuration options

Options:

base (string): Base IRI to use (default: input URL if string, empty string otherwise)
expandContext (any): Context to expand with
documentLoader (function): Custom document loader

Usage Examples:

// Basic flattening without compaction
const doc = {
  "@context": {"name": "http://schema.org/name"},
  "name": "Manu Sporny",
  "knows": {
    "name": "Gregg Kellogg"
  }
};

const flattened = await jsonld.flatten(doc);
// Result: Array of all nodes flattened to top-level

// Flatten with compaction
const context = {"name": "http://schema.org/name"};
const flattenedAndCompacted = await jsonld.flatten(doc, context);
// Result: Flattened and compacted according to context

// Flatten without compaction (explicit null)
const flattenedOnly = await jsonld.flatten(doc, null);

Frame

Performs JSON-LD framing, which transforms a JSON-LD document into a specific tree structure according to a frame pattern.

/**
 * Performs JSON-LD framing into specific tree structures
 * @param input - The JSON-LD input to frame
 * @param frame - The JSON-LD frame to use
 * @param options - Optional framing options
 * @returns Promise resolving to the framed output
 */
function frame(input, frame, options);

Parameters:

input (any): JSON-LD input to frame
frame (any): JSON-LD frame to use (can be URL string)
options (FramingOptions, optional): Framing options

Options:

base (string): Base IRI to use (default: input URL if string, empty string otherwise)
expandContext (any): Context to expand with
embed (string): Default @embed flag: '@last', '@always', '@never', '@link' (default: '@once')
explicit (boolean): Default @explicit flag (default: false)
requireAll (boolean): Default @requireAll flag (default: false)
omitDefault (boolean): Default @omitDefault flag (default: false)
documentLoader (function): Custom document loader
safe (boolean): Use safe mode (default: false)

Usage Examples:

// Basic framing
const doc = {
  "@context": {
    "name": "http://schema.org/name",
    "knows": "http://schema.org/knows"
  },
  "@graph": [
    {"@id": "http://example.org/people/jane", "name": "Jane Doe", "knows": {"@id": "http://example.org/people/john"}},
    {"@id": "http://example.org/people/john", "name": "John Doe"}
  ]
};

const frame = {
  "@context": {
    "name": "http://schema.org/name",
    "knows": "http://schema.org/knows"
  },
  "@type": "http://schema.org/Person",
  "name": {},
  "knows": {
    "name": {}
  }
};

const framed = await jsonld.frame(doc, frame);
// Result: Document structured according to frame pattern

// Frame with embedding options
const framedWithOptions = await jsonld.frame(doc, frame, {
  embed: '@always',
  explicit: true
});

// Frame using URLs
const framedFromUrl = await jsonld.frame('http://example.org/doc', 'http://example.org/frame');

Types

/**
 * Options for compaction operations
 */
interface CompactionOptions extends JsonLdOptions {
  compactArrays?: boolean;
  compactToRelative?: boolean;
  graph?: boolean;
  skipExpansion?: boolean;
}

/**
 * Options for expansion operations
 */
interface ExpansionOptions extends JsonLdOptions {
  keepFreeFloatingNodes?: boolean;
}

/**
 * Options for flattening operations
 */
interface FlatteningOptions extends JsonLdOptions {
  // Inherits all JsonLdOptions
}

/**
 * Options for framing operations
 */
interface FramingOptions extends JsonLdOptions {
  embed?: '@last' | '@always' | '@never' | '@link' | '@once';
  explicit?: boolean;
  requireAll?: boolean;
  omitDefault?: boolean;
  omitGraph?: boolean;
  pruneBlankNodeIdentifiers?: boolean;
}