rdf-literal

RDF Literal

RDF Literal makes it easier to translate between RDF literals and JavaScript primitives.

This library accepts RDFJS-compliant terms.

Installation

$ yarn add rdf-literal

This package also works out-of-the-box in browsers via tools such as webpack and browserify.

Require

import {
  fromRdf,
  toRdf,
  getSupportedJavaScriptPrimitives,
  getSupportedRdfDatatypes,
  getTermRaw,
} from "rdf-literal";

or

const {
  fromRdf,
  toRdf,
  getSupportedJavaScriptPrimitives,
  getSupportedRdfDatatypes,
  getTermRaw,
} = require("rdf-literal");

Usage

This library offers the following functions:

• fromRdf: Converts an RDF literal to a JavaScript primitive.
• toRdf: Converts a JavaScript primitive to an RDF literal.

Next to that, the following helper functions are provided:

• getSupportedJavaScriptPrimitives: An array of all JavaScript primitive types that can be converted.
• getSupportedRdfDatatypes: An array of all RDF datatypes (as NamedNodes) that can be converted.
• getTermRaw: Converts any RDF term to a JavaScript primitive. If the term is a literal, fromRdf will be called on it. Otherwise, the .value string will be returned.

Examples

Converting JavaScript from RDF

fromRdf(literal, validate?) converts an RDF literal to a JavaScript value.

Optionally, the validate argument can be passed as true to force an error to be thrown if an invalid value for the given datatype is detected.

Converting an RDF string literal

Explicit string datatypes are converted into JS strings.

fromRdf(literal('abc'); // Returns 'abc'
fromRdf(literal('abc', 'en-us'); // Returns 'abc'
fromRdf(literal('abc',
  namedNode('http://www.w3.org/2001/XMLSchema#normalizedString')); // Returns 'abc'

Converting an RDF number literal

Integer-like and double-like literals are converted into JS numbers.

// Integers
fromRdf(literal('123',
  namedNode('http://www.w3.org/2001/XMLSchema#integer')); // Returns 123
fromRdf(literal('123',
  namedNode('http://www.w3.org/2001/XMLSchema#long')); // Returns 123

// Doubles
fromRdf(literal('123.456',
  namedNode('http://www.w3.org/2001/XMLSchema#double')); // Returns 123.456
fromRdf(literal('123.456',
  namedNode('http://www.w3.org/2001/XMLSchema#float')); // Returns 123.456

// Invalid integers
fromRdf(literal('123.456',
  namedNode('http://www.w3.org/2001/XMLSchema#integer')); // Returns 123
fromRdf(literal('123.456',
  namedNode('http://www.w3.org/2001/XMLSchema#integer'), true); // Throws error

Converting an RDF boolean literal

Boolean literals are converted into JS booleans.

fromRdf(literal('true',
  namedNode('http://www.w3.org/2001/XMLSchema#boolean')); // Returns true
fromRdf(literal('0',
  namedNode('http://www.w3.org/2001/XMLSchema#boolean')); // Returns false

Converting an RDF date literal

Date(time) literals are converted into JS Dates.

fromRdf(literal('2012-03-17T23:00:00.000Z',
  namedNode('http://www.w3.org/2001/XMLSchema#dateTime'))); // Returns a Date
fromRdf(literal('2012-03-17',
  namedNode('http://www.w3.org/2001/XMLSchema#date'))); // Returns a Date
fromRdf(literal('2012-03',
  namedNode('http://www.w3.org/2001/XMLSchema#gYearMonth'))); // Returns a Date

Converting an RDF literal with unknown datatype

Unknown datatypes are considered JS strings.

fromRdf(literal('abc',
  namedNode('http://example.org/unknown')); // Returns 'abc'

Converting JavaScript to RDF

toRdf(value, options?) converts a JavaScript value to an RDF literal term.

The optional options object can contain the following optional fields:

Name	Description
datatype	A custom NamedNode datatype that can be forced upon the literal value, which may influence the format of literal values.
dataFactory	DataFactory for creating RDF terms.

Converting a string

JS strings are converted to plain RDF literals.

toRdf('abc'); // Returns literal('abc')

Converting a number

JS numbers are converted to RDF integers or doubles.

toRdf(123); // Returns literal('123',
            //           namedNode('http://www.w3.org/2001/XMLSchema#integer')

toRdf(123.456); // Returns literal('123.456',
                //           namedNode('http://www.w3.org/2001/XMLSchema#double')

Converting a boolean

JS booleans are converted to RDF booleans.

toRdf(true); // Returns literal('true',
             //           namedNode('http://www.w3.org/2001/XMLSchema#boolean')

Converting a Date

JS Dates are converted to RDF date times.

toRdf(new Date('2012-03-17'));
// Returns literal('2012-03-17T00:00:00.000Z',
//           namedNode('http://www.w3.org/2001/XMLSchema#dateTime'))

toRdf(new Date('2012-03-17T23:00:00.000Z'));
// Returns literal('2012-03-17T23:00:00.000Z',
//           namedNode('http://www.w3.org/2001/XMLSchema#dateTime'))

toRdf(new Date('2012-03-17'),
  { datatype: namedNode('http://www.w3.org/2001/XMLSchema#date') });
// Returns literal('2012-03-17',
// namedNode('http://www.w3.org/2001/XMLSchema#date'))

toRdf(2012,
  { datatype: namedNode('http://www.w3.org/2001/XMLSchema#gYear') });
// Returns literal('2012',
//           namedNode('http://www.w3.org/2001/XMLSchema#gYear'))

Conversion range

The following table shows how RDF datatypes and JavaScript primitives are mapped:

JavaScript primitive	RDF Datatype
string	xsd:string
string	xsd:normalizedString
string	xsd:anyURI
string	xsd:base64Binary
string	xsd:language
string	xsd:Name
string	xsd:NCName
string	xsd:NMTOKEN
string	xsd:token
string	xsd:hexBinary
string	rdf:langString
boolean	xsd:boolean
number	xsd:integer
number	xsd:long
number	xsd:int
number	xsd:byte
number	xsd:short
number	xsd:negativeInteger
number	xsd:nonNegativeInteger
number	xsd:nonPositiveInteger
number	xsd:positiveInteger
number	xsd:unsignedByte
number	xsd:unsignedInt
number	xsd:unsignedLong
number	xsd:unsignedShort
number	xsd:double
number	xsd:decimal
number	xsd:float
Date	xsd:dateTime
Date	xsd:date
Date	xsd:gDay
Date	xsd:gMonthDay
Date	xsd:gYear
Date	xsd:gYearMonth

Used prefixes:

• xsd: <http://www.w3.org/2001/XMLSchema#>
• rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

The following XSD datatypes that are standardized in RDF are not supported, and will therefore be interpreted as plain strings:

• xsd:duration
• xsd:time

Any other unknown datatypes will also be interpreted as plain strings.

License

This software is written by Ruben Taelman.

This code is released under the MIT license.