0
# JSON-LD
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: jsonld
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jsonld`
10

11
## Core Imports
12

13
```javascript
14
const jsonld = require('jsonld');
15
```
16

17
For ES modules:
18

19
```javascript
20
import * as jsonld from 'jsonld';
21
// or specific imports
22
import {promises} from 'jsonld';
23
import {JsonLdProcessor} from 'jsonld';
24
```
25

26
## Basic Usage
27

28
```javascript
29
const jsonld = require('jsonld');
30

31
// Sample document
32
const doc = {
33
  "http://schema.org/name": "Manu Sporny",
34
  "http://schema.org/url": {"@id": "http://manu.sporny.org/"},
35
  "http://schema.org/image": {"@id": "http://manu.sporny.org/images/manu.png"}
36
};
37

38
const context = {
39
  "name": "http://schema.org/name",
40
  "homepage": {"@id": "http://schema.org/url", "@type": "@id"},
41
  "image": {"@id": "http://schema.org/image", "@type": "@id"}
42
};
43

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

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

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

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

57
## Architecture
58

59
JSON-LD is built around several key components:
60

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

69
## Capabilities
70

71
### Core Transformations
72

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

75
```javascript { .api }
76
/**
77
 * Performs JSON-LD compaction according to a context
78
 */
79
function compact(input, ctx, options);
80

81
/**
82
 * Performs JSON-LD expansion, removing contexts
83
 */
84
function expand(input, options);
85

86
/**
87
 * Performs JSON-LD flattening
88
 */
89
function flatten(input, ctx, options);
90

91
/**
92
 * Performs JSON-LD framing into specific tree structures
93
 */
94
function frame(input, frame, options);
95
```
96

97
[Core Transformations](./transformations.md)
98

99
### RDF Operations
100

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

103
```javascript { .api }
104
/**
105
 * Converts JSON-LD to RDF dataset
106
 */
107
function toRDF(input, options);
108

109
/**
110
 * Converts RDF dataset to JSON-LD
111
 */
112
function fromRDF(dataset, options);
113

114
/**
115
 * Performs RDF dataset normalization/canonicalization
116
 */
117
function normalize(input, options);
118
function canonize(input, options); // alias for normalize
119
```
120

121
[RDF Operations](./rdf-operations.md)
122

123
### Document Loading
124

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

127
```javascript { .api }
128
/**
129
 * Default document loader for external documents
130
 */
131
let documentLoader;
132

133
/**
134
 * Gets remote JSON-LD document using document loader
135
 */
136
function get(url, options);
137

138
/**
139
 * Sets default document loader to built-in type
140
 */
141
function useDocumentLoader(type, ...params);
142

143
/**
144
 * Registry of available document loaders
145
 */
146
const documentLoaders;
147
```
148

149
[Document Loading](./document-loading.md)
150

151
### Context Processing
152

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

155
```javascript { .api }
156
/**
157
 * Processes a local context and returns new active context
158
 */
159
function processContext(activeCtx, localCtx, options);
160
```
161

162
[Context Processing](./context-processing.md)
163

164
### Utility Operations
165

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

168
```javascript { .api }
169
/**
170
 * Creates a merged node map from JSON-LD input
171
 */
172
function createNodeMap(input, options);
173

174
/**
175
 * Merges multiple JSON-LD documents
176
 */
177
function merge(docs, ctx, options);
178

179
/**
180
 * Links JSON-LD document nodes in memory
181
 */
182
function link(input, ctx, options);
183
```
184

185
[Utility Operations](./utilities.md)
186

187
### Error Handling
188

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

191
```javascript { .api }
192
/**
193
 * Custom error class for JSON-LD operations
194
 */
195
class JsonLdError extends Error {
196
  constructor(message, name, details);
197
}
198
```
199

200
[Error Handling](./error-handling.md)
201

202
### Event Handling
203

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

206
```javascript { .api }
207
/**
208
 * Logs all events to console
209
 */
210
function logEventHandler(event);
211

212
/**
213
 * Sets the default event handler for all operations
214
 */
215
function setDefaultEventHandler(handler);
216

217
/**
218
 * Safe event handler that prevents exceptions
219
 */
220
function safeEventHandler(event);
221
```
222

223
[Event Handling](./event-handling.md)
224

225
### URL Utilities
226

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

229
```javascript { .api }
230
/**
231
 * Parse URL string using specified parser
232
 */
233
function parse(str, parser);
234

235
/**
236
 * Resolve relative IRI against base IRI
237
 */
238
function prependBase(base, iri);
239

240
/**
241
 * Remove base IRI to create relative reference
242
 */
243
function removeBase(base, iri);
244
```
245

246
[URL Utilities](./url-utilities.md)
247

248
## Types
249

250
```javascript { .api }
251
/**
252
 * Options object for JSON-LD operations
253
 */
254
interface JsonLdOptions {
255
  base?: string;
256
  expandContext?: any;
257
  documentLoader?: (url: string, options?: any) => Promise<RemoteDocument>;
258
  safe?: boolean;
259
  [key: string]: any;
260
}
261

262
/**
263
 * Remote document structure returned by document loaders
264
 */
265
interface RemoteDocument {
266
  contextUrl?: string;
267
  document: any;
268
  documentUrl: string;
269
}
270

271
/**
272
 * WebIDL-compatible processor interface for W3C JSON-LD API compliance
273
 */
274
class JsonLdProcessor {
275
  static compact(input, ctx): Promise<any>;
276
  static expand(input): Promise<any>;
277
  static flatten(input): Promise<any>;
278
  toString(): string;
279
}
280

281
/**
282
 * Legacy request queue for backward compatibility
283
 */
284
class RequestQueue {
285
  constructor();
286
}
287

288
/**
289
 * Backward compatibility alias for the main jsonld API
290
 * All functions are available as jsonld.promises.*
291
 */
292
const promises;
293
```