0
# Core Transformations
1

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

4
## Capabilities
5

6
### Compact
7

8
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.
9

10
```javascript { .api }
11
/**
12
 * Performs JSON-LD compaction according to a context
13
 * @param input - The JSON-LD input to compact
14
 * @param ctx - The context to compact with
15
 * @param options - Optional configuration object
16
 * @returns Promise resolving to the compacted output
17
 */
18
function compact(input, ctx, options);
19
```
20

21
**Parameters:**
22
- `input` (any): JSON-LD input to compact, can be a JSON-LD document or URL string
23
- `ctx` (any): Context to compact with, cannot be null
24
- `options` (JsonLdOptions, optional): Configuration options
25

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

36
**Usage Examples:**
37

38
```javascript
39
const jsonld = require('jsonld');
40

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

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

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

55
// Compact using URLs
56
const compacted2 = await jsonld.compact(
57
  'http://example.org/doc', 
58
  'http://example.org/context'
59
);
60

61
// Compact with options
62
const compacted3 = await jsonld.compact(doc, context, {
63
  base: 'http://example.org/',
64
  compactArrays: false
65
});
66
```
67

68
### Expand
69

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

72
```javascript { .api }
73
/**
74
 * Performs JSON-LD expansion, removing contexts
75
 * @param input - The JSON-LD input to expand
76
 * @param options - Optional configuration object
77
 * @returns Promise resolving to the expanded output
78
 */
79
function expand(input, options);
80
```
81

82
**Parameters:**
83
- `input` (any): JSON-LD input to expand
84
- `options` (JsonLdOptions, optional): Configuration options
85

86
**Options:**
87
- `base` (string): Base IRI to use
88
- `expandContext` (any): Context to expand with
89
- `keepFreeFloatingNodes` (boolean): Keep free-floating nodes (default: false)
90
- `documentLoader` (function): Custom document loader
91
- `safe` (boolean): Use safe mode (default: false)
92

93
**Usage Examples:**
94

95
```javascript
96
// Basic expansion
97
const compacted = {
98
  "@context": {
99
    "name": "http://schema.org/name",
100
    "homepage": {"@id": "http://schema.org/url", "@type": "@id"}
101
  },
102
  "name": "Manu Sporny",
103
  "homepage": "http://manu.sporny.org/"
104
};
105

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

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

115
// Expand with options
116
const expanded3 = await jsonld.expand(compacted, {
117
  base: 'http://example.org/',
118
  keepFreeFloatingNodes: true
119
});
120
```
121

122
### Flatten
123

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

126
```javascript { .api }
127
/**
128
 * Performs JSON-LD flattening
129
 * @param input - The JSON-LD to flatten
130
 * @param ctx - The context to use for compaction, or null for no compaction
131
 * @param options - Optional configuration object
132
 * @returns Promise resolving to the flattened output
133
 */
134
function flatten(input, ctx, options);
135
```
136

137
**Parameters:**
138
- `input` (any): JSON-LD to flatten
139
- `ctx` (any): Context for compaction (or null for no compaction)
140
- `options` (JsonLdOptions, optional): Configuration options
141

142
**Options:**
143
- `base` (string): Base IRI to use (default: input URL if string, empty string otherwise)
144
- `expandContext` (any): Context to expand with
145
- `documentLoader` (function): Custom document loader
146

147
**Usage Examples:**
148

149
```javascript
150
// Basic flattening without compaction
151
const doc = {
152
  "@context": {"name": "http://schema.org/name"},
153
  "name": "Manu Sporny",
154
  "knows": {
155
    "name": "Gregg Kellogg"
156
  }
157
};
158

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

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

167
// Flatten without compaction (explicit null)
168
const flattenedOnly = await jsonld.flatten(doc, null);
169
```
170

171
### Frame
172

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

175
```javascript { .api }
176
/**
177
 * Performs JSON-LD framing into specific tree structures
178
 * @param input - The JSON-LD input to frame
179
 * @param frame - The JSON-LD frame to use
180
 * @param options - Optional framing options
181
 * @returns Promise resolving to the framed output
182
 */
183
function frame(input, frame, options);
184
```
185

186
**Parameters:**
187
- `input` (any): JSON-LD input to frame
188
- `frame` (any): JSON-LD frame to use (can be URL string)
189
- `options` (FramingOptions, optional): Framing options
190

191
**Options:**
192
- `base` (string): Base IRI to use (default: input URL if string, empty string otherwise)
193
- `expandContext` (any): Context to expand with
194
- `embed` (string): Default @embed flag: '@last', '@always', '@never', '@link' (default: '@once')
195
- `explicit` (boolean): Default @explicit flag (default: false)
196
- `requireAll` (boolean): Default @requireAll flag (default: false)
197
- `omitDefault` (boolean): Default @omitDefault flag (default: false)
198
- `documentLoader` (function): Custom document loader
199
- `safe` (boolean): Use safe mode (default: false)
200

201
**Usage Examples:**
202

203
```javascript
204
// Basic framing
205
const doc = {
206
  "@context": {
207
    "name": "http://schema.org/name",
208
    "knows": "http://schema.org/knows"
209
  },
210
  "@graph": [
211
    {"@id": "http://example.org/people/jane", "name": "Jane Doe", "knows": {"@id": "http://example.org/people/john"}},
212
    {"@id": "http://example.org/people/john", "name": "John Doe"}
213
  ]
214
};
215

216
const frame = {
217
  "@context": {
218
    "name": "http://schema.org/name",
219
    "knows": "http://schema.org/knows"
220
  },
221
  "@type": "http://schema.org/Person",
222
  "name": {},
223
  "knows": {
224
    "name": {}
225
  }
226
};
227

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

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

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

241
## Types
242

243
```javascript { .api }
244
/**
245
 * Options for compaction operations
246
 */
247
interface CompactionOptions extends JsonLdOptions {
248
  compactArrays?: boolean;
249
  compactToRelative?: boolean;
250
  graph?: boolean;
251
  skipExpansion?: boolean;
252
}
253

254
/**
255
 * Options for expansion operations
256
 */
257
interface ExpansionOptions extends JsonLdOptions {
258
  keepFreeFloatingNodes?: boolean;
259
}
260

261
/**
262
 * Options for flattening operations
263
 */
264
interface FlatteningOptions extends JsonLdOptions {
265
  // Inherits all JsonLdOptions
266
}
267

268
/**
269
 * Options for framing operations
270
 */
271
interface FramingOptions extends JsonLdOptions {
272
  embed?: '@last' | '@always' | '@never' | '@link' | '@once';
273
  explicit?: boolean;
274
  requireAll?: boolean;
275
  omitDefault?: boolean;
276
  omitGraph?: boolean;
277
  pruneBlankNodeIdentifiers?: boolean;
278
}
279
```