0
# RDF Operations
1

2
Bi-directional conversion between JSON-LD and RDF datasets, including canonicalization for cryptographic applications. These operations enable JSON-LD to work seamlessly with RDF data and provide cryptographically secure document canonicalization.
3

4
## Capabilities
5

6
### To RDF
7

8
Converts JSON-LD to RDF dataset format, optionally serializing to N-Quads format.
9

10
```javascript { .api }
11
/**
12
 * Converts JSON-LD to RDF dataset
13
 * @param input - The JSON-LD input
14
 * @param options - Optional configuration object
15
 * @returns Promise resolving to RDF dataset or N-Quads string
16
 */
17
function toRDF(input, options);
18
```
19

20
**Parameters:**
21
- `input` (any): JSON-LD input to convert
22
- `options` (ToRdfOptions, optional): Configuration options
23

24
**Options:**
25
- `base` (string): Base IRI to use (default: input URL if string, empty string otherwise)
26
- `expandContext` (any): Context to expand with
27
- `skipExpansion` (boolean): Skip expansion step (default: false)
28
- `format` (string): Output format: 'application/n-quads' for N-Quads string
29
- `produceGeneralizedRdf` (boolean): Output generalized RDF (default: false)
30
- `documentLoader` (function): Custom document loader
31
- `safe` (boolean): Use safe mode (default: false)
32
- `rdfDirection` (string): Support for @direction: null or 'i18n-datatype' (default: null)
33

34
**Usage Examples:**
35

36
```javascript
37
const jsonld = require('jsonld');
38

39
// Convert to RDF dataset
40
const doc = {
41
  "@context": {"name": "http://schema.org/name"},
42
  "@id": "http://example.org/people/jane",
43
  "name": "Jane Doe"
44
};
45

46
const dataset = await jsonld.toRDF(doc);
47
// Result: RDF dataset object
48

49
// Convert to N-Quads string
50
const nquads = await jsonld.toRDF(doc, {format: 'application/n-quads'});
51
// Result: "<http://example.org/people/jane> <http://schema.org/name> \"Jane Doe\" .\n"
52

53
// Convert with options
54
const rdf = await jsonld.toRDF(doc, {
55
  base: 'http://example.org/',
56
  produceGeneralizedRdf: true
57
});
58
```
59

60
### From RDF
61

62
Converts RDF dataset to JSON-LD format, supporting various RDF serialization formats.
63

64
```javascript { .api }
65
/**
66
 * Converts RDF dataset to JSON-LD
67
 * @param dataset - RDF dataset or serialized string
68
 * @param options - Optional configuration object
69
 * @returns Promise resolving to JSON-LD document
70
 */
71
function fromRDF(dataset, options);
72
```
73

74
**Parameters:**
75
- `dataset` (any): RDF dataset to convert or serialized string
76
- `options` (FromRdfOptions, optional): Configuration options
77

78
**Options:**
79
- `format` (string): Input format if dataset is string: 'application/n-quads' (default for strings)
80
- `rdfParser` (function): Custom RDF parser to use
81
- `useRdfType` (boolean): Use rdf:type instead of @type (default: false)
82
- `useNativeTypes` (boolean): Convert XSD types to native JavaScript types (default: false)
83
- `rdfDirection` (string): Support for @direction: null or 'i18n-datatype' (default: null)
84
- `safe` (boolean): Use safe mode (default: false)
85

86
**Usage Examples:**
87

88
```javascript
89
// Convert from N-Quads string
90
const nquads = '<http://example.org/people/jane> <http://schema.org/name> "Jane Doe" .';
91
const doc = await jsonld.fromRDF(nquads, {format: 'application/n-quads'});
92
// Result: JSON-LD document
93

94
// Convert from RDF dataset object
95
const dataset = [
96
  {
97
    subject: {termType: 'NamedNode', value: 'http://example.org/people/jane'},
98
    predicate: {termType: 'NamedNode', value: 'http://schema.org/name'},
99
    object: {termType: 'Literal', value: 'Jane Doe'},
100
    graph: {termType: 'DefaultGraph', value: ''}
101
  }
102
];
103
const doc2 = await jsonld.fromRDF(dataset);
104

105
// Convert with native types
106
const doc3 = await jsonld.fromRDF(nquads, {
107
  format: 'application/n-quads',
108
  useNativeTypes: true,
109
  useRdfType: false
110
});
111
```
112

113
### Normalize (Canonize)
114

115
Performs RDF dataset normalization using canonicalization algorithms, essential for cryptographic applications and document comparison.
116

117
```javascript { .api }
118
/**
119
 * Performs RDF dataset normalization/canonicalization
120
 * @param input - Input to normalize (JSON-LD or other format)
121
 * @param options - Optional configuration object
122
 * @returns Promise resolving to normalized output
123
 */
124
function normalize(input, options);
125

126
/**
127
 * Alias for normalize
128
 */
129
function canonize(input, options);
130
```
131

132
**Parameters:**
133
- `input` (any): Input to normalize as JSON-LD or specified format
134
- `options` (NormalizeOptions, optional): Configuration options
135

136
**Options:**
137
- `algorithm` (string): Normalization algorithm: 'URDNA2015' or 'URGNA2012' (default: 'URDNA2015')
138
- `base` (string): Base IRI to use (default: null for safety)
139
- `expandContext` (any): Context to expand with
140
- `skipExpansion` (boolean): Skip expansion step (default: false)
141
- `inputFormat` (string): Input format if not JSON-LD: 'application/n-quads'
142
- `format` (string): Output format: 'application/n-quads' for N-Quads string
143
- `documentLoader` (function): Custom document loader
144
- `useNative` (boolean): Use native canonize algorithm if available
145
- `rdfDirection` (string): Support for @direction: null or 'i18n-datatype' (default: null)
146
- `safe` (boolean): Use safe mode (default: true, different from other operations)
147

148
**Usage Examples:**
149

150
```javascript
151
// Basic canonicalization
152
const doc = {
153
  "@context": {"name": "http://schema.org/name"},
154
  "name": "Jane Doe"
155
};
156

157
const canonized = await jsonld.canonize(doc, {
158
  algorithm: 'URDNA2015',
159
  format: 'application/n-quads'
160
});
161
// Result: Canonical N-Quads string
162

163
// Canonicalize N-Quads input
164
const nquads = '<http://example.org/s> <http://example.org/p> "value" .';
165
const canonical = await jsonld.normalize(nquads, {
166
  inputFormat: 'application/n-quads',
167
  format: 'application/n-quads'
168
});
169

170
// Canonicalize for digital signing (recommended safe settings)
171
const safeCanonical = await jsonld.canonize(doc, {
172
  algorithm: 'URDNA2015',
173
  format: 'application/n-quads',
174
  safe: true,
175
  base: null
176
});
177
```
178

179
### RDF Parser Registration
180

181
Register custom RDF parsers for additional RDF serialization formats.
182

183
```javascript { .api }
184
/**
185
 * Registers RDF dataset parser by content-type
186
 * @param contentType - Content type for the parser
187
 * @param parser - Parser function
188
 */
189
function registerRDFParser(contentType, parser);
190

191
/**
192
 * Unregisters RDF dataset parser by content-type
193
 * @param contentType - Content type for the parser
194
 */
195
function unregisterRDFParser(contentType);
196
```
197

198
**Usage Examples:**
199

200
```javascript
201
// Register synchronous RDF parser
202
jsonld.registerRDFParser('application/turtle', input => {
203
  // Parse Turtle input to RDF dataset object
204
  return parseToDataset(input);
205
});
206

207
// Register asynchronous RDF parser
208
jsonld.registerRDFParser('application/rdf+xml', async input => {
209
  // Parse RDF/XML input to RDF dataset object
210
  return await parseRdfXmlToDataset(input);
211
});
212

213
// Unregister parser
214
jsonld.unregisterRDFParser('application/turtle');
215
```
216

217
## Types
218

219
```javascript { .api }
220
/**
221
 * Options for toRDF operations
222
 */
223
interface ToRdfOptions extends JsonLdOptions {
224
  format?: 'application/n-quads' | 'application/nquads';
225
  produceGeneralizedRdf?: boolean;
226
  rdfDirection?: null | 'i18n-datatype';
227
  skipExpansion?: boolean;
228
}
229

230
/**
231
 * Options for fromRDF operations
232
 */
233
interface FromRdfOptions {
234
  format?: 'application/n-quads' | 'application/nquads';
235
  rdfParser?: (input: string) => any;
236
  useRdfType?: boolean;
237
  useNativeTypes?: boolean;
238
  rdfDirection?: null | 'i18n-datatype';
239
  safe?: boolean;
240
}
241

242
/**
243
 * Options for normalization/canonicalization operations
244
 */
245
interface NormalizeOptions extends JsonLdOptions {
246
  algorithm?: 'URDNA2015' | 'URGNA2012';
247
  inputFormat?: 'application/n-quads' | 'application/nquads';
248
  format?: 'application/n-quads' | 'application/nquads';
249
  useNative?: boolean;
250
  rdfDirection?: null | 'i18n-datatype';
251
  skipExpansion?: boolean;
252
}
253

254
/**
255
 * RDF parser function type
256
 */
257
type RDFParser = (input: string) => any | Promise<any>;
258

259
/**
260
 * RDF dataset quad structure
261
 */
262
interface Quad {
263
  subject: NamedNode | BlankNode;
264
  predicate: NamedNode;
265
  object: NamedNode | BlankNode | Literal;
266
  graph: NamedNode | BlankNode | DefaultGraph;
267
}
268

269
/**
270
 * RDF term types
271
 */
272
interface NamedNode {
273
  termType: 'NamedNode';
274
  value: string;
275
}
276

277
interface BlankNode {
278
  termType: 'BlankNode';
279
  value: string;
280
}
281

282
interface Literal {
283
  termType: 'Literal';
284
  value: string;
285
  language?: string;
286
  datatype?: NamedNode;
287
}
288

289
interface DefaultGraph {
290
  termType: 'DefaultGraph';
291
  value: '';
292
}
293
```