Apache Commons RDF logo

Apache Commons RDF

Commons RDF aims to provide a common library for RDF 1.1 that could be implemented by systems on the Java Virtual Machine.

The main motivation behind this simple library is revise an historical incompatibility issue. This library does not pretend to be a generic api wrapping those libraries, but a set of interfaces for the RDF 1.1 concepts that can be used to expose common RDF-1.1 concepts using common Java interfaces. In the initial phase commons-rdf is focused on a subset of the core concepts defined by RDF-1.1 (URI/IRI, Blank Node, Literal, Triple, and Graph). In particular, commons RDF aims to provide a type-safe, non-general API that covers RDF 1.1. In a future phase we may define interfaces for Datasets and Quads.

API

The class diagram on the right depicts the main interfaces which may be included in Commons RDF, specifically:

  • Graph: a graph, a set of RDF triples.
  • Triple: a RDF triple with getSubject(), getPredicate(), getObject().
  • Dataset: a dataset, of RDF quads (or if you like, a set of named graphs).
  • Quad: a RDF quad with with getGraphName(), getSubject(), getPredicate(), getObject().
  • RDFTerm: any RDF 1.1 Term which can be part of a Triple or Quad. IRIs, literals and blank nodes are collectively known as RDF terms.
  • IRI: an Internationalized Resource Identifier (e.g. representing <http://example.com/>)
  • BlankNode: a RDF-1.1 Blank Node, e.g. representing _:b1. Disjoint from IRIs and literals.
  • BlankNodeOrIRI: this interface represents the RDF Terms that may be used in the subject position of an RDF 1.1 Triple, including BlankNode and IRI.
  • Literal: a RDF-1.1 literal, e.g. representing "Hello there"@en.

The design of the API follows the terminology as defined by RDF 1.1 Concepts and Abstract Syntax, a W3C Recommendation published on 25 February 2014. The idea is that Commons RDF provide a common library for RDF 1.1 with multiple implementions for the Java Virtual Machine, allowing the portability across different Commons RDF implementations.

Commons RDF is designed for compatibility between different implementations, e.g. by defining strong equality and hash code semantics (e.g. for triple and literals ); this allows users of Commons RDF to “mix and match”, for instance querying a FooGraphImpl and directly adding its FooTripleImpls to a BarGraphImpl without any explicit convertion.

To create such instances without hard-coding an implementation, one can use:

  • RDF: interface for creating instances of the above types (e.g. LiteralImpl and GraphImpl) as well as converting from/to the underlying framework’s API.

The API also includes a couple of “upper” interfaces which do not have the above equality semantics and bridge the graph/quad duality:

  • TripleLike: common super-interface of Triple and Quad (also a generalised triple).
  • QuadLike: a TripleLike that also has getGraphName() (a generalized quad)
  • GraphLike: common super-interface of Graph and Dataset.

See the the user guide for examples of how to interact with these interfaces.

Modules

The project is composed by two modules:

  • API defines a common library of RDF 1.1 concepts.
  • Simple provides a simple implementation, mainly for internal validation and very simple scenarios.
  • jena provides an Apache Jena-backed implementation
  • rdf4j provides an Eclipse RDF4J-backed implementation
  • jsonld-java provides an JSONLD-Java-backed implementation

These modules follow the semantic versioning principles, where version x.y.z of Simple implements version x.y of the API; i.e., the version z are backwards-compatible patches of the implementation.

For more details, read about the implementations of the Commons RDF API.

Contributing

Everybody is welcomed to join the project and contribute!