Defining custom datatypes

[AndreaWesterinen]

I see lots of documentation about custom SPARQL functions, but not much detail about custom datatypes.

It would seem that one would start by extending the DatatypeHandler (https://rdf4j.org/javadoc/3.3.0/org/eclipse/rdf4j/rio/DatatypeHandler.html) or one of the implementation classes.

Is there any additional documentation that might help with this?

Andrea

[ate47]

You can add a new handler to a parser, I will use TURTLE for example

RDFParser parser = Rio.createParser(RDFFormat.TURTLE);

You need to get the current handlers, by default this list isn't modifiable so you need to copy it

// clone the list to allow to add our new handlers
List<DatatypeHandler> datatypeHandlers = new ArrayList<>(parser.getParserConfig().get(BasicParserSettings.DATATYPE_HANDLERS));

Then add you custom handler, it was the right interface :)

here a basic DatatypeHandler to detect the string toto for the datatype http://example.org/MyCustomType.

datatypeHandlers.add(new DatatypeHandler() {
	@Override
	public boolean isRecognizedDatatype(IRI datatypeUri) {
		// check if this datatype is handle by this handler, here I simply check the 
		// <http://example.org/MyCustomType> datatype
		return datatypeUri.stringValue().equals("http://example.org/MyCustomType");
	}

	@Override
	public boolean verifyDatatype(String literalValue, IRI datatypeUri) throws LiteralUtilException {
                // you can apply your logic here, for multiple type handler, use datatypeUri to
                // determine which one you are using
		return literalValue.equals("toto");
	}

	@Override
	public Literal normalizeDatatype(String literalValue, IRI datatypeUri, ValueFactory valueFactory) throws LiteralUtilException {
		// if you want to normalize it, to use a custom literal to avoid converting the string
		// value every time, I won't use this feature here, but this is highly recommended
		return valueFactory.createLiteral(literalValue, datatypeUri);
	}

	@Override
	public String getKey() {
		// custom data type key of the handler
		return "com.example.mydatatype";
	}
});

Then config the parser

// set the list of datatypes
parser.getParserConfig().set(BasicParserSettings.DATATYPE_HANDLERS, datatypeHandlers);
// force to verify the datatypes
parser.getParserConfig().set(BasicParserSettings.VERIFY_DATATYPE_VALUES, true);

Examples

// the 'toto'^^ex:MyCustomType is respecting the format, no exception
parser.parse(new StringReader("PREFIX ex: <http://example.org/> "
                           +  "ex:Subject ex:Predicate 'toto'^^ex:MyCustomType ."
));

// the 'toto lulu'^^ex:MyCustomType isn't respecting the format, exception:
// org.eclipse.rdf4j.rio.RDFParseException: 'toto lulu' is not a valid value for datatype
// http://example.org/MyCustomType [line 1]
parser.parse(new StringReader("PREFIX ex: <http://example.org/> "
                           +  "ex:Subject ex:Predicate 'toto lulu'^^ex:MyCustomType ."
));

To use it in a SPARQL function, you need to call by yourself the format verify methods in the function implementation.