The N3.js library lets you handle RDF in JavaScript easily, in Node.js and the browser. It offers:
- Parsing triples/quads from Turtle, TriG, N-Triples, N-Quads, and Notation3 (N3)
- Writing triples/quads to Turtle, TriG, N-Triples, and N-Quads
- Storage of triples/quads in memory
Parsing and writing is:
- asynchronous – triples arrive as soon as possible
- streaming – streams are parsed as data comes in, so you can parse files larger than memory
- fast – by far the fastest parser in JavaScript
For Node.js, N3.js comes as an npm package.
$ npm install n3var N3 = require('n3');N3.js seamlessly works in browsers. Generate a browser version as follows:
$ cd N3.js
$ npm install
$ npm run browser<script src="n3-browser.min.js"></script>In addition, N3.js is fully compatible with browserify, so you can write code for Node.js and deploy it to browsers.
For maximum performance and ease of use, triples are simple objects with string properties.
URLs, URIs and IRIs are simple strings. For example, parsing this RDF document:
@prefix c: <http:https://example.org/cartoons#>.
c:Tom a c:Cat.results in this JavaScript object:
{
subject: 'http:https://example.org/cartoons#Tom',
predicate: 'http:https://www.w3.org/1999/02/22-rdf-syntax-ns#type',
object: 'http:https://example.org/cartoons#Cat'
}Literals are represented as double quoted strings. For example, parsing this RDF document:
c:Tom c:name "Tom".results in this JavaScript object:
{
subject: 'http:https://example.org/cartoons#Tom',
predicate: 'http:https://example.org/cartoons#name',
object: '"Tom"'
}This allows you to create and compare literals fast and easily:
triple.object === 'http:https://example.org/cartoons#Cat'
triple.object === '"Tom"'For literals with a language or type, add a marker (@ or ^^) and the corresponding value as-is:
'"Tom"@en-gb' // lowercase language
'"1"^^http:https://www.w3.org/2001/XMLSchema#integer' // no angular brackets <>An optional fourth element signals the graph to which a triple belongs:
{
subject: 'http:https://example.org/cartoons#Tom',
predicate: 'http:https://example.org/cartoons#name',
object: '"Tom"',
graph: 'http:https://example.org/mycartoon'
}The N3.js Utility (N3.Util) can help you with these representations.
N3.Parser transforms Turtle, TriG, N-Triples or N-Quads document into triples through a callback:
var parser = N3.Parser();
parser.parse('@prefix c: <http:https://example.org/cartoons#>.\n' +
'c:Tom a c:Cat.\n' +
'c:Jerry a c:Mouse;\n' +
' c:smarterThan c:Tom.',
function (error, triple, prefixes) {
if (triple)
console.log(triple.subject, triple.predicate, triple.object, '.');
else
console.log("# That's all, folks!", prefixes)
});The callback's first argument is an error value, the second is a triple.
If there are no more triples,
the callback is invoked one last time with null for triple
and a hash of prefixes as third argument.
Pass a second callback to parse to retrieve prefixes as they are read.
If no callbacks are provided, parsing happens synchronously.
By default, N3.Parser parses a permissive superset of Turtle, TriG, N-Triples and N-Quads.
For strict compatibility with any of those languages, pass a format argument upon creation:
var parser1 = N3.Parser({ format: 'N-Triples' });
var parser2 = N3.Parser({ format: 'application/trig' });Notation3 (N3) is supported only through the format argument:
var parser3 = N3.Parser({ format: 'N3' });
var parser4 = N3.Parser({ format: 'Notation3' });
var parser5 = N3.Parser({ format: 'text/n3' });N3.Parser can parse Node.js streams as they grow,
returning triples as soon as they're ready.
This behavior sets N3.js apart from most other libraries.
var parser = N3.Parser(),
rdfStream = fs.createReadStream('cartoons.ttl');
parser.parse(rdfStream, console.log);In addition, N3.StreamParser offers a Node.js stream implementation,
so you can transform RDF streams and pipe them to anywhere.
This solution is ideal if your consumer is slower,
since source data is only read when the consumer is ready.
var streamParser = N3.StreamParser(),
rdfStream = fs.createReadStream('cartoons.ttl');
rdfStream.pipe(streamParser);
streamParser.pipe(new SlowConsumer());
function SlowConsumer() {
var writer = new require('stream').Writable({ objectMode: true });
writer._write = function (triple, encoding, done) {
console.log(triple);
setTimeout(done, 1000);
};
return writer;
}A dedicated prefix event signals every prefix with prefix and iri arguments.
N3.Writer serializes triples as an RDF document.
Write triples through addTriple.
var writer = N3.Writer({ prefixes: { c: 'http:https://example.org/cartoons#' } });
writer.addTriple('http:https://example.org/cartoons#Tom',
'http:https://www.w3.org/1999/02/22-rdf-syntax-ns#type',
'http:https://example.org/cartoons#Cat');
writer.addTriple({
subject: 'http:https://example.org/cartoons#Tom',
predicate: 'http:https://example.org/cartoons#name',
object: '"Tom"'
});
writer.end(function (error, result) { console.log(result); });By default, N3.Writer writes Turtle (or TriG for triples with a graph property).
To write N-Triples (or N-Quads) instead, pass a format argument upon creation:
var writer1 = N3.Writer({ format: 'N-Triples' });
var writer2 = N3.Writer({ format: 'application/trig' });N3.Writer can also write triples to a Node.js stream.
var writer = N3.Writer(process.stdout, { prefixes: { c: 'http:https://example.org/cartoons#' } });
writer.addTriple('http:https://example.org/cartoons#Tom',
'http:https://www.w3.org/1999/02/22-rdf-syntax-ns#type',
'http:https://example.org/cartoons#Cat');
writer.addTriple({
subject: 'http:https://example.org/cartoons#Tom',
predicate: 'http:https://example.org/cartoons#name',
object: '"Tom"'
});
writer.end();N3.StreamWriter is a writer implementation as a Node.js stream.
var streamParser = new N3.StreamParser(),
inputStream = fs.createReadStream('cartoons.ttl'),
streamWriter = new N3.StreamWriter({ prefixes: { c: 'http:https://example.org/cartoons#' } });
inputStream.pipe(streamParser);
streamParser.pipe(streamWriter);
streamWriter.pipe(process.stdout);You might want to use the […] and list (…) notations of Turtle and TriG.
However, a streaming writer cannot create these automatically:
the shorthand notations are only possible if blank nodes or list heads are not used later on,
which can only be determined conclusively at the end of the stream.
The blank and list functions allow you to create them manually instead:
var writer = N3.Writer({ prefixes: { c: 'http:https://example.org/cartoons#',
foaf: 'http:https://xmlns.com/foaf/0.1/' } });
writer.addTriple(writer.blank('http:https://xmlns.com/foaf/0.1/givenName', '"Tom"@en'),
'http:https://www.w3.org/1999/02/22-rdf-syntax-ns#type',
'http:https://example.org/cartoons#Cat');
writer.addTriple('http:https://example.org/cartoons#Jerry',
'http:https://xmlns.com/foaf/0.1/knows',
writer.blank([{
predicate: 'http:https://www.w3.org/1999/02/22-rdf-syntax-ns#type',
object: 'http:https://example.org/cartoons#Cat'
},{
predicate: 'http:https://xmlns.com/foaf/0.1/givenName',
object: '"Tom"@en',
}]));
writer.addTriple('http:https://example.org/cartoons#Mammy',
'http:https://example.org/cartoons#hasPets',
writer.list([
'http:https://example.org/cartoons#Tom',
'http:https://example.org/cartoons#Jerry'
]));
writer.end(function (error, result) { console.log(result); });Be careful to use the output of blank and list
only once and only as argument to addTriple of the same writer,
as return values of these functions are unspecified.
N3.Store allows you to store triples in memory and find them fast.
In this example, we create a new store and add the triples :Pluto a :Dog. and :Mickey a :Mouse.
Then, we find a triple with :Mickey as subject.
var store = N3.Store();
store.addTriple('http:https://ex.org/Pluto', 'http:https://ex.org/type', 'http:https://ex.org/Dog');
store.addTriple('http:https://ex.org/Mickey', 'http:https://ex.org/type', 'http:https://ex.org/Mouse');
var mickey = store.find('http:https://ex.org/Mickey', null, null)[0];
console.log(mickey.subject, mickey.predicate, mickey.object, '.');N3.Util offers helpers for IRI and literal representations.
As IRIs are most common, they are represented as simple strings:
var N3Util = N3.Util;
N3Util.isIRI('http:https://example.org/cartoons#Mickey'); // trueLiterals are represented as double quoted strings:
N3Util.isLiteral('"Mickey Mouse"'); // true
N3Util.getLiteralValue('"Mickey Mouse"'); // 'Mickey Mouse'
N3Util.isLiteral('"Mickey Mouse"@en'); // true
N3Util.getLiteralLanguage('"Mickey Mouse"@en'); // 'en'
N3Util.isLiteral('"3"^^http:https://www.w3.org/2001/XMLSchema#integer'); // true
N3Util.getLiteralType('"3"^^http:https://www.w3.org/2001/XMLSchema#integer'); // 'http:https://www.w3.org/2001/XMLSchema#integer'
N3Util.isLiteral('"http:https://example.org/"'); // true
N3Util.getLiteralValue('"http:https://example.org/"'); // 'http:https://example.org/'Note the difference between 'http:https://example.org/' (IRI) and '"http:https://example.org/"' (literal).
Also note that the double quoted literals are not raw Turtle/TriG syntax:
N3Util.isLiteral('"This word is "quoted"!"'); // true
N3Util.isLiteral('"3"^^http:https://www.w3.org/2001/XMLSchema#integer'); // trueThe above string represents the string This word is "quoted"!,
even though the correct Turtle/TriG syntax for that is "This word is \"quoted\"!"
N3.js thus always parses literals, but adds quotes to differentiate from IRIs:
new N3.Parser().parse('<a> <b> "This word is \\"quoted\\"!".', console.log);
// { subject: 'a', predicate: 'b', object: '"This word is "quoted"!"' }Literals can be created with createLiteral:
N3Util.createLiteral('My text', 'en-gb');
N3Util.createLiteral('123', 'http:https://www.w3.org/2001/XMLSchema#integer');
N3Util.createLiteral(123);
N3Util.createLiteral(false);Blank nodes start with _:, and can be tested for as follows:
N3Util.isBlank('_:b1'); // true
N3Util.isIRI('_:b1'); // false
N3Util.isLiteral('_:b1'); // falsePrefixed names can be tested and expanded:
var prefixes = { rdfs: 'http:https://www.w3.org/2000/01/rdf-schema#' };
N3Util.isPrefixedName('rdfs:label'); // true;
N3Util.expandPrefixedName('rdfs:label', prefixes); // http:https://www.w3.org/2000/01/rdf-schema#labelFor convenience, N3Util can be loaded globally:
require('n3').Util(global);
isIRI('http:https://example.org/cartoons#Mickey'); // true
isLiteral('"Mickey Mouse"'); // trueIf desired, its methods can even be added directly on all strings:
require('n3').Util(String, true);
'http:https://example.org/cartoons#Mickey'.isIRI(); // true
'"Mickey Mouse"'.isLiteral(); // trueThe N3.js parser and writer is fully compatible with the following W3C specifications:
- RDF 1.1 Turtle – EARL report
- RDF 1.1 TriG – EARL report
- RDF 1.1 N-Triples – EARL report
- RDF 1.1 N-Quads – EARL report
In addition, the N3.js parser also supports Notation3 (N3) (no official specification yet).
Pass a format option to the constructor with the name or MIME type of a format
for strict, fault-intolerant behavior.
The N3.js library is copyrighted by Ruben Verborgh and released under the MIT License.
Contributions are welcome, and bug reports or pull requests are always helpful. If you plan to implement a larger feature, it's best to contact me first.