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.11.
Current Status: The library is feature-complete.
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:
@prefix : <http://example.com/> .
:test
:blorb "blorb" ;
:floop "floop" . |
@prefix : <http://example.com/> .
:test
:floop "floop" ;
:blorb "blorb" . |
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.
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 asa
. 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 orrdf: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 differentrdf:type
s.
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.
Add the following dependency to your Maven pom.xml
:
<dependency>
<groupId>de.atextor</groupId>
<artifactId>turtle-formatter</artifactId>
<version>1.2.11</version>
</dependency>
Gradle/Groovy: implementation 'de.atextor:turtle-formatter:1.2.11'
Gradle/Kotlin: implementation("de.atextor:turtle-formatter:1.2.11")
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);
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:
Option | Description | Default |
|
Set the URI that should be left out in formatting. If you don't care about this, don't change it and use the FormattingStyle's emptyRdfBase field as the base URI when loading/creating the model that will be formatted, see calling the formatter. | urn:turtleformatter:internal |
|
Boolean. Example:
# true
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix example: <http://example.com/> .
# false
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix example: <http://example.com/> . |
false |
|
Boolean. Example:
# firstPredicateInNewLine false
# alignPredicates true
:test a rdf:Resource ;
:blorb "blorb" ;
:floop "floop" .
# firstPredicateInNewLine false
# alignPredicates false
:test a rdf:Resource ;
:blorb "blorb" ;
:floop "floop" .
# firstPredicateInNewLine true
# alignPredicates does not matter
:test
a rdf:Resource ;
:blorb "blorb" ;
:floop "floop" . |
false (for both) |
|
Boolean. Example: # alignObjects true
:test
a rdf:Resource ;
:blorb "blorb" ;
:floopfloop "floopfloop" .
# alignObjects false
:test
a rdf:Resource ;
:blorb "blorb" ;
:floopfloop "floopfloop" . |
false |
|
One of |
|
|
A NumberFormat that describes how |
|
|
One of |
|
|
|
|
|
|
|
|
Integer. When using |
2 |
|
Boolean. Determines whether there is a line break after the last line | true |
|
Boolean. Determines whether |
true |
|
Boolean. If |
false |
|
Boolean. Determines whether to use commas for identical predicates. Example: # useCommaByDefault false
:test a rdf:Resource ;
:blorb "someBlorb" ;
:blorb "anotherBlorb" .
# useCommaByDefault true
:test a rdf:Resource ;
:blorb "someBlorb", "anotherBlorb" . |
false |
|
A set of predicates that, when used multiple times, are separated by commas, even when
# useCommaByDefault false, commaForPredicate contains
# 'rdf:type', firstPredicateInNewLine true
:test a ex:something, owl:NamedIndividual ;
:blorb "someBlorb" ;
:blorb "anotherBlorb" .
# useCommaByDefault false, commaForPredicate is empty,
# firstPredicateInNewLine false
:test
a ex:something ;
a owl:NamedIndividual ;
:blorb "someBlorb" ;
:blorb "anotherBlorb" . |
Set.of( |
|
Analogous to |
Empty |
|
A list of namespace prefixes that defines the order of # prefixOrder contains "rdf" and "owl" (in this order), so
# they will appear in this order at the top (when the model
# contains them!), followed by all other namespaces
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix example: <http://example.com/> . |
List.of( |
|
A list of resources that determines the order in which subjects appear. For a subject |
List.of( |
|
A list of properties that determine the order in which predicates appear for a subject. First all
properties that are in the list are shown in that order, then everything else lexicographically
sorted. For example, when :test
:z "z" ;
:x "x" ;
:a "a" . |
List.of( |
|
A list of RDFNodes (i.e. resources or literals) that determine the order in which objects appear for
a predicate, when there are multiple statements with the same subject and the same predicate. First
all objects that are in the list are shown in that order, then everything else lexicographically
sorted. For example, when :test a :Foo, :Bar . |
List.of( |
|
A :test :foo _:b0 .
:test2 :bar _:b0 . There is no way to serialize this model in RDF/Turtle while using the inline blank node syntax |
|
{ { |
|
Varied |
|
|
|
* Adapted from EditorConfig
- 1.2.11:
- Bugfix:
rdf:type
is not printed asa
when used as an object - Update all dependencies, including Apache Jena to 4.10.0
- Bugfix:
- 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.
- The dummy base URI is now configurable in the formatting style. Its default
value was changed (to
- 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
- Fix typo in FormattingStyle property (
- 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'smodel.read()
- Update build to Java 17
- Enable writing URIs with an empty base: use
- 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
- Add
- 1.1.1:
- Make fields of
FormattingStyle
public, so thatDEFAULT
config is readable
- Make fields of
- 1.1.0:
- Bugfix: Subjects with a
rdf:type
not insubjectOrder
are rendered correctly - Adjust default
subjectOrder
andpredicateOrder
- Add new option
keepUnusedPrefixes
and by default render only used prefixes
- Bugfix: Subjects with a
- 1.0.1: Fix POM so that dependency can be used as jar
- 1.0.0: First version
turtle-formatter is developed by Andreas Textor <[email protected]>.