turtle-formatter

turtle-formatter is a Java library for pretty printing RDF/Turtle documents in a configurable and reproducible way.

It takes as input a formatting style and an Apache Jena Model and produces as output a pretty-printed RDF/Turtle document.

Starting from version 1.2.0, turtle-formatter is licensed under Apache 2.0. The current version is 1.2.13.

Current Status: The library is feature-complete.

Why?

Reproducible Formatting

Every RDF library comes with its own serializers, for example an Apache Jena Model can be written in multiple ways, the easiest being calling the write method on a model itself: model.write(System.out, "TURTLE"). However, due to the nature of RDF, outgoing edges of a node in the graph have no order. When serializing a model, there are multiple valid ways to do so. For example, the following two models are identical:

Therefore, when a model is serialized, one of many different (valid) serializations could be the result. This is a problem when different versions of a model file are compared, for example when used as artifacts in a git repository. Additionally, serialized files are often formatted in one style hardcoded in the respective library. So while Apache Jena and for example libraptor2 both write valid RDF/Turtle, the files are formatted differently. You would not want the code of a project formatted differently in different files, would you? turtle-formatter addresses these problems by taking care of serialization order and providing a way to customize the formatting style.

Nice and Configurable Formatting

Most serializers, while creating valid RDF/Turtle, create ugly formatting. Obviously, what is ugly and what isn't is highly subjective, so this should be configurable. turtle-formatter addresses this by making the formatting style configurable, e.g. how alignment should be done, where extra spaces should be inserted and even if indendation is using tabs or spaces. A default style is provided that reflects sane settings (i.e., the author's opinion). An RDF document formatted using the default style could look like this:

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . ①
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix : <http://example.com/relations#> .

:Male a owl:Class ; ②
  owl:disjointWith :Female ; ③
  owl:equivalentClass [ ④
    a owl:Restriction ;
    owl:hasSelf true ; ⑤
    owl:onProperty :isMale ;
  ] ;
  rdfs:subClassOf :Person .

:hasBrother a owl:ObjectProperty ;
  owl:propertyChainAxiom ( :hasSibling :isMale ) ; ⑥
  rdfs:range :Male .

:hasUncle a owl:ObjectProperty, owl:IrreflexiveProperty ; ⑦
  owl:propertyChainAxiom ( :hasParent :hasSibling :hasHusband ) ; ⑦
  owl:propertyChainAxiom ( :hasParent :hasBrother ) ;
  rdfs:range :Male .

• ① Prefixes are sorted by common, then custom. They are not aligned on the colon because that looks bad when one prefix string is much longer than the others.
• ② rdf:type is always written as a. It is always the first predicate and written in the same line as the subject.
• ③ Indentation is done using a fixed size, like in any other format or language. Predicates are not aligned to subjects with an arbitrary length.
• ④ Anonymous nodes are written using the [ ] notation whenever possible.
• ⑤ Literal shortcuts are used where possible (e.g. no "true"^^xsd:boolean).
• ⑥ RDF Lists are always written using the ( ) notation, no blank node IDs or rdf:next/rdf:first seen here.
• ⑦ The same predicates on the same subjects are repeated rather than using the , notation, because especially when the objects are longer (nested anonymous nodes), it is difficult to understand. The exception to this rule is for different rdf:types.

Usage

Usage as a CLI (command line interface)

turtle-formatter itself is only a library and thus intended to be used programmatically, which is explained in the following sections. However, in the sibling project owl-cli, turtle-formatter is used and can be called using a command line interface to pretty-print any OWL or RDF document. See owl-cli's Getting Started to get the tool and the write command documentation to see which command line switches are available to adjust the formatting.

Usage as a library

Add the following dependency to your Maven pom.xml:

<dependency>
  <groupId>de.atextor</groupId>
  <artifactId>turtle-formatter</artifactId>
  <version>1.2.13</version>
</dependency>

Gradle/Groovy: implementation 'de.atextor:turtle-formatter:1.2.13'

Gradle/Kotlin: implementation("de.atextor:turtle-formatter:1.2.13")

Calling the formatter

import java.io.FileInputStream;
import de.atextor.turtle.formatter.FormattingStyle;
import de.atextor.turtle.formatter.TurtleFormatter;
import org.apache.jena.rdf.model.Model;
import org.apache.jena.rdf.model.ModelFactory;

// ...

// Determine formatting style
FormattingStyle style = FormattingStyle.DEFAULT;
TurtleFormatter formatter = new TurtleFormatter(style);
// Build or load a Jena Model.
// Use the style's base URI for loading the model.
Model model = ModelFactory.createDefaultModel();
model.read(new FileInputStream("data.ttl"), style.emptyRdfBase, "TURTLE");
// Either create a string...
String prettyPrintedModel = formatter.apply(model);
// ...or write directly to an OutputStream
formatter.accept(model, System.out);

Customizing the style

Instead of passing FormattingStyle.DEFAULT, you can create a custom FormattingStyle object.

FormattingStyle style = FormattingStyle.builder(). ... .build();

The following options can be set on the FormattingStyle builder:

* Adapted from EditorConfig

Release Notes

• 1.2.13:
  • Feature: Skip double formatting
• 1.2.12:
  • Bugfix: Handle RDF lists that start with a non-anonymous node
  • Bugfix: Handle blank node cycles
  • Bugfix: Ensure constant blank node ordering
  • Bugfix: Set Locale for NumberFormat to US
  • Change default subjectOrder to show rdfs:Class after owl:Ontology
• 1.2.11:
  • Bugfix: rdf:type is not printed as a when used as an object
  • Update all dependencies, including Apache Jena to 4.10.0
• 1.2.10:
  • Configured endOfLine style is honored in prefix formatting
• 1.2.9:
  • The dummy base URI is now configurable in the formatting style. Its default value was changed (to urn:turtleformatter:internal) to make it a valid URI.
• 1.2.8:
  • Bugfix: Quotes that are the last character in a triple-quoted string are escaped correctly
  • New style switch: FormattingStyle.quoteStyle
• 1.2.7:
  • Bugfix: URIs and local names are formatted using Jena RIOT; no invalid local names are printed any longer
• 1.2.6:
  • Fix typo in FormattingStyle property (indentPredicates)
  • Fix alignment of repeated identical predicates
• 1.2.5:
  • Dashes, underscores and full stops in the name part of local names are not escaped any more. Technically not a bug fix since both is valid, but it's nicer to read
• 1.2.4:
  • Bugfix: Dashes in prefixes of local names are not escaped any more
• 1.2.3:
  • Bugfix: Special characters in local names (curies) and literals are properly escaped
• 1.2.2:
  • Enable writing URIs with an empty base: use TurtleFormatter.EMPTY_BASE as value for "base" when reading a model using Jena's model.read()
  • Update build to Java 17
• 1.2.1:
  • Improve formatting for blank nodes nested in lists
  • Use triple quotes for literals containing line breaks
  • Use Jena's mechanisms for escaping special characters in literals
• 1.2.0:
  • Add wrapListItems configuration option
  • Change license from LGPL 3.0 to Apache 2.0
• 1.1.1:
  • Make fields of FormattingStyle public, so that DEFAULT config is readable
• 1.1.0:
  • Bugfix: Subjects with a rdf:type not in subjectOrder are rendered correctly
  • Adjust default subjectOrder and predicateOrder
  • Add new option keepUnusedPrefixes and by default render only used prefixes
• 1.0.1: Fix POM so that dependency can be used as jar
• 1.0.0: First version

Contact

turtle-formatter is developed by Andreas Textor <mail@atextor.de>.