-
Notifications
You must be signed in to change notification settings - Fork 5
/
index.html
449 lines (387 loc) · 17.2 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>RDF/JS: Dataset specification 1.0</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<script class="remove">
var respecConfig = {
specStatus: "CG-FINAL",
publishDate: "2019-03-27",
shortName: "rdfjs-dataset",
subtitle: "RDF/JS: Dataset specification 1.0",
edDraftURI: "https://github.com/rdfjs/dataset-spec/",
issueBase: "https://github.com/rdfjs/dataset-spec/issues/",
githubAPI: "https://api.github.com/repos/rdfjs/dataset-spec",
// TODO: testSuiteURIkey: "",
editors: [{
name: "Thomas Bergwinkl",
url: "https://www.bergnet.org/"
}],
authors: [
{
name: "Thomas Bergwinkl",
url: "https://www.bergnet.org/"
},
{
name: "Blake Regalia",
url: "https://blake-regalia.net/#me",
company: "STKO Lab @ University of California, Santa Barbara",
companyURL: "http://stko.geog.ucsb.edu/",
w3cid: 108003
},
{
name: "Victor Felder",
url: "https://draft.li/#me",
company: "Zazuko",
companyURL: "https://zazuko.com",
w3cid: 105931
},
{
name: "Ruben Taelman",
url: "https://www.rubensworks.net/#me",
company: "Ghent University – imec",
companyURL: "http://idlab.ugent.be/",
w3cid: 84199
}
],
bugTracker: {
open: "https://github.com/rdfjs/dataset-spec/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20",
new: "https://github.com/rdfjs/dataset-spec/issues/new"
},
otherLinks: [{
key: "Version control",
data: [{
value: "Github Repository",
href: "https://github.com/rdfjs/dataset-spec"
}]
}],
group: "cg/rdfjs",
wgPublicList: "public-rdfjs",
maxTocLevel: 2
};
</script>
</head>
<body>
<section id="abstract">
<h2>Abstract</h2>
<p>
The scope of this specification is to provide a way to store multiple quads, as defined in the <a href="http://rdf.js.org/data-model-spec/#quad-interface">RDF/JS: Data model specification</a>, in a so-called dataset.
Similar to the <a href="http://rdf.js.org/data-model-spec/">RDF/JS: Data model specification</a>, this is a low-level specification that provides only essential methods for working with multiple quads.
High-level interfaces that work with quads can and should be using libraries that implement this interface.
</p>
<p>The specification itself consists of a core-part that is the base for all other functions defined.</p>
<p>Low-level methods are using explicit parameters that cannot be omitted.</p>
<p>Additional high-level interfaces are outside of the scope of this specification and should be defined elsewhere.</p>
</section>
<section id="sotd">
<p>
</p>
</section>
<section>
<h2>Data interfaces</h2>
<section data-dfn-for="DatasetCore">
<h3><dfn>DatasetCore</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface DatasetCore {
readonly attribute unsigned long size;
Dataset add (Quad quad);
Dataset delete (Quad quad);
boolean has (Quad quad);
Dataset match (optional Term? subject, optional Term? predicate, optional Term? _object, optional Term? graph);
iterable<Quad>;
};
</pre>
<p>
<!-- <a>Dataset</a> is an abstract interface. -->
</p>
<h3>Attributes</h3>
<p>
<dfn>size</dfn>
</p>
<p>A non-negative integer that specifies the number of quads in the set.</p>
<h3>Methods</h3>
<p>
<dfn>add</dfn>
</p>
<p>Adds the specified <code>quad</code> to the dataset.</p>
<p>This method returns the dataset instance it was called on.</p>
<p>Existing quads, as defined in <code>Quad.equals</code>, will be ignored.</p>
<p>
<dfn>delete</dfn>
</p>
<p>Removes the specified <code>quad</code> from the dataset.</p>
<p>This method returns the dataset instance it was called on.</p>
<p>
<dfn>has</dfn>
</p>
<p>Determines whether a dataset includes a certain quad, returning true or false as appropriate.</p>
<p>
<dfn>match</dfn>
</p>
<p>
This method returns a new dataset that is comprised of all quads in the current instance matching the given arguments.
The logic described in <a href="#quad-matching">Quad Matching</a> is applied for each quad in this dataset to check if it should be included in the output dataset.
</p>
<p>Note: This method always returns a new <a>DatasetCore</a>, even if that dataset contains no quads.</p>
<p>Note: Since a <a>DatasetCore</a> is an unordered set, the order of the quads within the returned sequence is arbitrary.</p>
</section>
<section data-dfn-for="DatasetCoreFactory">
<h3><dfn>DatasetCoreFactory</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface DatasetCoreFactory {
DatasetCore dataset (optional sequence<Quad> quads);
};
</pre>
<p>
<code>DatasetCoreFactory</code> provides a <code>dataset</code> method to create instances of <code>DatasetCore</code>.
</p>
<p>
<dfn>dataset</dfn>
</p>
<p>Returns a new dataset and imports all quads, if given.</p>
<div class="note">The given sequence must be treated as immutable (do not <code>.pop()</code>, <code>.splice()</code>, <code>.shift()</code>, etc).</div>
</section>
<div class="warning" title="Experimental!">
<p>
The following interfaces are experimental and will change in future versions of this document:
</p>
<p>
<code>Dataset</code>, <code>DatasetFactory</code>, <code>QuadFilterIteratee</code>, <code>QuadMapIteratee</code>, <code>QuadReduceIteratee</code>, <code>QuadRunIteratee</code>
</p>
</div>
<section data-dfn-for="Dataset">
<h3><dfn>Dataset</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface Dataset : DatasetCore {
Dataset addAll ((Dataset or sequence<Quad>) quads);
boolean contains (Dataset other);
Dataset deleteMatches (optional Term subject, optional Term predicate, optional Term _object, optional Term graph);
Dataset difference (Dataset other);
boolean equals (Dataset other);
boolean every (QuadFilterIteratee iteratee);
Dataset filter (QuadFilterIteratee iteratee);
undefined forEach (QuadRunIteratee iteratee);
Promise<Dataset> import (Stream stream);
Dataset intersection (Dataset other);
Dataset map (QuadMapIteratee iteratee);
any reduce (QuadReduceIteratee iteratee, optional any initialValue);
boolean some (QuadFilterIteratee iteratee);
DOMString toCanonical ();
Stream toStream ();
Dataset union (Dataset quads);
};
</pre>
<p>
A <a>DatasetCore</a> implementation may already implement part of the <a>Dataset</a> interface.
If a <a>Dataset</a> implementation acts as a wrapper for a <a>DatasetCore</a>, the wrapped dataset methods should be used.
</p>
<p>
<b><code>toString</code></b>
<p>Returns an N-Quads string representation of the dataset.</p>
<p>No prior normalization is required, therefore the results for the same quads may vary depending on the Dataset implementation.</p>
</p>
<h3>Attributes</h3>
<h3>Methods</h3>
<p>
<dfn>addAll</dfn>
</p>
<p>Imports the <code>quads</code> into this dataset.</p>
<p>This method returns the dataset instance it was called on.</p>
<p>This method differs from <a>Dataset.union</a> in that it adds all <code>quads</code> to the current instance, rather than combining <code>quads</code> and the current instance to create a new instance.</p>
<div class="note">The given sequence must be treated as immutable (do not <code>.pop()</code>, <code>.splice()</code>, <code>.shift()</code>, etc).</div>
<p>
<dfn>contains</dfn>
</p>
<p>Returns true if the current instance is a superset of the given dataset; differently put: if the given dataset is a subset of, is contained in the current dataset.</p>
<p>Blank Nodes will be normalized.</p>
<div class="note">The given dataset and its content must be treated as immutable (do not cause mutations by calling e.g. <code>.add()</code> or <code>.delete()</code> on it, do not modify the quads you get out of it).</div>
<p>
<dfn>deleteMatches</dfn>
</p>
<p>
This method removes the quads in the current instance that match the given arguments.
The logic described in <a href="#quad-matching">Quad Matching</a> is applied for each quad in this dataset to select the quads which will be deleted.
</p>
<p>This method returns the dataset instance it was called on.</p>
<p>
<dfn>difference</dfn>
</p>
<p>Returns a new dataset that contains alls quads from the current dataset, not included in the given dataset.</p>
<div class="note">The given dataset and its content must be treated as immutable (do not cause mutations by calling e.g. <code>.add()</code> or <code>.delete()</code> on it, do not modify the quads you get out of it).</div>
<p>
<dfn>equals</dfn>
</p>
<p>Returns true if the current instance contains the same graph structure as the given dataset.</p>
<p>Blank Nodes will be normalized.</p>
<div class="note">The given dataset and its content must be treated as immutable (do not cause mutations by calling e.g. <code>.add()</code> or <code>.delete()</code> on it, do not modify the quads you get out of it).</div>
<p>
<dfn>every</dfn>
</p>
<p>Universal quantification method, tests whether every quad in the dataset passes the test implemented by the provided <code>iteratee</code>.</p>
<p>This method immediately returns boolean false once a quad that does not pass the test is found.</p>
<p>This method always returns boolean true on an empty dataset.</p>
<p>Note: This method is aligned with Array.prototype.every() in ECMAScript-262.</p>
<p>
<dfn>filter</dfn>
</p>
<p>Creates a new dataset with all the quads that pass the test implemented by the provided <code>iteratee</code>.</p>
<p>Note: This method is aligned with Array.prototype.filter() in ECMAScript-262.</p>
<p>
<dfn>forEach</dfn>
</p>
<p>Executes the provided <code>iteratee</code> once on each quad in the dataset.</p>
<p>Note: This method is aligned with Array.prototype.forEach() in ECMAScript-262.</p>
<p>
<dfn>import</dfn>
</p>
<p>Imports all quads from the given stream into the dataset.</p>
<p>The stream events <code>end</code> and <code>error</code> are wrapped in a Promise.</p>
<p>
<dfn>intersection</dfn>
</p>
<p>Returns a new dataset containing alls quads from the current dataset that are also included in the given dataset.</p>
<div class="note">The given dataset and its content must be treated as immutable (do not cause mutations by calling e.g. <code>.add()</code> or <code>.delete()</code> on it, do not modify the quads you get out of it).</div>
<p>
<dfn>map</dfn>
</p>
<p>Returns a new dataset containing all quads returned by applying <code>iteratee</code> to each quad in the current dataset.</p>
<p>
<dfn>reduce</dfn>
</p>
<p>
This method calls the <code>iteratee</code> on each <code>quad</code> of the <a>DatasetCore</a>.
The first time the <code>iteratee</code> is called, the <code>accumulator</code> value is the <code>initialValue</code> or, if not given, equals to the first quad of the Dataset.
The return value of the <code>iteratee</code> is used as <code>accumulator</code> value for the next calls.
</p>
<p>This method returns the return value of the last <code>iteratee</code> call.</p>
<p>Note: This method is aligned with Array.prototype.reduce() in ECMAScript-262.</p>
<p>
<dfn>some</dfn>
</p>
<p>Existential quantification method, tests whether some quads in the dataset pass the test implemented by the provided <code>iteratee</code>.</p>
<p>This method immediately returns boolean true once a quad that passes the test is found.</p>
<p>Note: This method is aligned with Array.prototype.some() in ECMAScript-262.</p>
<p>
<dfn>toCanonical</dfn>
</p>
<p>Returns an N-Quads string representation of the dataset, preprocessed with <a href="https://json-ld.github.io/normalization/spec/">RDF Dataset Normalization</a> algorithm.</p>
<p>
<dfn>toStream</dfn>
</p>
<p>Returns a stream that contains all quads of the dataset.</p>
<p>
<dfn>union</dfn>
</p>
<p>Returns a new <a>Dataset</a> that is a concatenation of this dataset and the <code>quads</code> given as an argument.</p>
<div class="note">The given dataset and its content must be treated as immutable (do not cause mutations by calling e.g. <code>.add()</code> or <code>.delete()</code> on it, do not modify the quads you get out of it).</div>
</section>
<section data-dfn-for="DatasetFactory">
<h3><dfn>DatasetFactory</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface DatasetFactory : DataFactory {
Dataset dataset (optional (Dataset or sequence<Quad>) quads);
};
</pre>
<p>
<dfn>dataset</dfn>
</p>
<p>Returns a new dataset and imports all quads, if given.</p>
</section>
<section data-dfn-for="QuadFilterIteratee">
<h3><dfn>QuadFilterIteratee</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface QuadFilterIteratee {
boolean test (Quad quad, Dataset dataset);
};
</pre>
<p>
<dfn>test</dfn>
</p>
<p>A callable function that returns true if the input quad passes the test this function implements.</p>
</section>
<section data-dfn-for="QuadMapIteratee">
<h3><dfn>QuadMapIteratee</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface QuadMapIteratee {
Quad map (Quad quad, Dataset dataset);
};
</pre>
<p>
<dfn>map</dfn>
</p>
<p>A callable function that can be executed on a quad and returns a quad.</p>
<p>The returned quad can be the given quad or a new one.</p>
</section>
<section data-dfn-for="QuadReduceIteratee">
<h3><dfn>QuadReduceIteratee</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface QuadReduceIteratee {
any run (any accumulator, Quad quad, Dataset dataset);
};
</pre>
<p>
<dfn>run</dfn>
</p>
<p>A callable function that can be executed on an accumulator and quad and returns a new accumulator.</p>
</section>
<section data-dfn-for="QuadRunIteratee">
<h3><dfn>QuadRunIteratee</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface QuadRunIteratee {
undefined run (Quad quad, Dataset dataset);
};
</pre>
<p>
<dfn>run</dfn>
</p>
<p>A callable function that can be executed on a quad.</p>
</section>
</section>
<section>
<h2>Runtime Semantics</h2>
<section>
<h3>Quad Matching</h3>
<p>The methods <code>match</code> and <code>deleteMatches</code> select each quad for which the following logic is true:</p>
<ul>
<li>calling <code>quad.subject.equals</code> with the specified subject as argument returns true, or the subject argument is null, AND</li>
<li>calling <code>quad.predicate.equals</code> with the specified predicate as argument returns true, or the predicate argument is null, AND</li>
<li>calling <code>quad.object.equals</code> with the specified object as argument returns true, or the object argument is null, AND</li>
<li>calling <code>quad.graph.equals</code> with the specified graph as argument returns true, or the graph argument is null</li>
</ul>
<p>Only quads matching all of the given non-null arguments will be selected.</p>
</section>
</section>
<section id="conformance"></section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
The authors would like to thank the authors of the <a href="https://www.w3.org/TR/rdf-interfaces/">RDF Interfaces</a> specification.
Many concepts and definitions were adopted from that specification.
</p>
</section>
<section class='appendix'>
<h2>WebIDL references</h2>
<p>
The interfaces in this spec make use of the
<dfn>DataFactory</dfn>,
<dfn>Quad</dfn>, and
<dfn>Term</dfn>
interfaces from the <a href="https://rdf.js.org/data-model-spec/">RDF/JS Data model specification</a>.
</p>
<p>
The interfaces in this spec make use of the
<dfn>Stream</dfn>
interface from the <a href="https://nodejs.org/api/">Node.js API</a>.
</p>
</section>
</body>
</html>