search

ruby-rdf / rdf

RDF.rb is a pure-Ruby library for working with Resource Description Framework (RDF) data.
http://rubygems.org/gems/rdf
The Unlicense
382 stars 98 forks source link
graph linked-data rdf semantic-web

readme

RDF.rb: Linked Data for Ruby

This is a pure-Ruby library for working with Resource Description Framework (RDF) data.

Gem Version Build Status Coverage Status Gitter chat

Table of contents

  1. Features
  2. Differences between RDF 1.0 and RDF 1.1
  3. Differences between RDF 1.1 and RDF 1.2
  4. Tutorials
  5. Command Line
  6. Examples
  7. Reader/Writer convenience methods
  8. RDF 1.2
  9. Documentation
  10. Dependencies
  11. Installation
  12. Download
  13. Resources
  14. Mailing List
  15. Authors
  16. Contributors
  17. Contributing
  18. License

Features

HTTP requests

RDF.rb uses Net::HTTP for retrieving HTTP and HTTPS resources. If the RestClient gem is included, that will be used instead to retrieve remote resources. Clients may also consider using RestClient Components to enable client-side caching of HTTP results using Rack::Cache or other Rack middleware.

See {RDF::Util::File} for configuring other mechanisms for retrieving resources.

Term caching and configuration

RDF.rb uses a weak-reference cache for storing internalized versions of URIs and Nodes. This is particularly useful for Nodes as two nodes are equivalent only if they're the same node.

By default, each cache can grow to an unlimited size, but this can be configured using {RDF.config}, for general limits, along with URI- or Node-specific limits.

For example, to limit the size of the URI intern cache only:

RDF.config.uri_cache_size = 10_000

The default for creating new caches without a specific initialization size can be set using:

RDF.config.cache_size = 100_000

Differences between RDF 1.0 and RDF 1.1

This version of RDF.rb is fully compatible with RDF 1.1, but it creates some marginal incompatibilities with RDF 1.0, as implemented in versions prior to the 1.1 release of RDF.rb:

Notably, {RDF::Queryable#query} and {RDF::Query#execute} are now completely symmetric; this allows an implementation of {RDF::Queryable} to optimize queries using implementation-specific logic, allowing for substantial performance improvements when executing BGP queries.

Differences between RDF 1.1 and RDF 1.2

Tutorials

Command Line

When installed, RDF.rb includes a rdf shell script which acts as a wrapper to perform a number of different operations on RDF files using available readers and writers.

The serialize command can also be used to serialize as a vocabulary.

Different RDF gems will augment the rdf script with more capabilities, which may require specifying the appropriate --input-format option to revel.

Examples

require 'rdf'
include RDF

Writing RDF data using the N-Triples format

require 'rdf/ntriples'
graph = RDF::Graph.new << [:hello, RDF::RDFS.label, "Hello, world!"]
graph.dump(:ntriples)

or

RDF::Writer.open("hello.nt") { |writer| writer << graph }

Reading RDF data in the N-Triples format

require 'rdf/ntriples'
graph = RDF::Graph.load("https://ruby-rdf.github.io/rdf/etc/doap.nt")

or

RDF::Reader.open("https://ruby-rdf.github.io/rdf/etc/doap.nt") do |reader|
  reader.each_statement do |statement|
    puts statement.inspect
  end
end

Reading RDF data in other formats

{RDF::Reader.open} and {RDF::Repository.load} use a number of mechanisms to determine the appropriate reader to use when loading a file. The specific format to use can be forced using, e.g. format: :ntriples option where the specific format symbol is determined by the available readers. Both also use MimeType or file extension, where available.

require 'rdf/nquads'

graph = RDF::Graph.load("https://ruby-rdf.github.io/rdf/etc/doap.nq", format: :nquads)

A specific sub-type of Reader can also be invoked directly:

require 'rdf/nquads'

RDF::NQuads::Reader.open("https://ruby-rdf.github.io/rdf/etc/doap.nq") do |reader|
  reader.each_statement do |statement|
    puts statement.inspect
  end
end

Reader/Writer implementations may override {RDF::Format.detect}, which takes a small sample if input and return a boolean indicating if it matches that specific format. In the case that a format cannot be detected from filename or other options, or that more than one format is identified, {RDF::Format.for} will query each loaded format by invoking it's detect method, and the first successful match will be used to read the input.

Writing RDF data using other formats

{RDF::Writer.open}, {RDF::Enumerable#dump}, {RDF::Writer.dump} take similar options to {RDF::Reader.open} to determine the appropriate writer to use.

require 'linkeddata'

RDF::Writer.open("hello.nq", format: :nquads) do |writer|
  writer << RDF::Repository.new do |repo|
    repo << RDF::Statement.new(:hello, RDF::RDFS.label, "Hello, world!", graph_name: RDF::URI("http://example/graph_name"))
  end
end

A specific sub-type of Writer can also be invoked directly:

require 'rdf/nquads'

repo = RDF::Repository.new << RDF::Statement.new(:hello, RDF::RDFS.label, "Hello, world!", graph_name: RDF::URI("http://example/graph_name"))
File.open("hello.nq", "w") {|f| f << repo.dump(:nquads)}

Reader/Writer convenience methods

{RDF::Enumerable} implements to_{format} for each available instance of {RDF::Reader}. For example, if rdf/turtle is loaded, this allows the following:

graph = RDF::Graph.new << [:hello, RDF::RDFS.label, "Hello, world!"]
graph.to_ttl

Similarly, {RDF::Mutable} implements from_{format} for each available instance of {RDF::Writer}. For example:

graph = RDF::Graph.new
graph.from_ttl("[ a <http://www.w3.org/1999/02/22-rdf-syntax-ns#Resource>]")

Note that no prefixes are loaded automatically, however they can be provided as arguments:

graph.from_ttl("[ a rdf:Resource]", prefixes: {rdf: RDF.to_uri})

Querying RDF data using basic graph patterns (BGPs)

require 'rdf/ntriples'

graph = RDF::Graph.load("https://ruby-rdf.github.io/rdf/etc/doap.nt")
query = RDF::Query.new({
  person: {
    RDF.type  => FOAF.Person,
    FOAF.name => :name,
    FOAF.mbox => :email,
  }
}, **{})

query.execute(graph) do |solution|
  puts "name=#{solution.name} email=#{solution.email}"
end

The same query may also be run from the graph:

graph.query(query) do |solution|
  puts "name=#{solution.name} email=#{solution.email}"
end

In general, querying from using the queryable instance allows a specific implementation of queryable to perform query optimizations specific to the datastore on which it is based.

A separate SPARQL gem builds on basic BGP support to provide full support for SPARQL 1.1 queries.

Using pre-defined RDF vocabularies

DC.title      #=> RDF::URI("http://purl.org/dc/terms/title")
FOAF.knows    #=> RDF::URI("http://xmlns.com/foaf/0.1/knows")
RDF.type      #=> RDF::URI("http://www.w3.org/1999/02/22-rdf-syntax-ns#type")
RDFS.seeAlso  #=> RDF::URI("http://www.w3.org/2000/01/rdf-schema#seeAlso")
RSS.title     #=> RDF::URI("http://purl.org/rss/1.0/title")
OWL.sameAs    #=> RDF::URI("http://www.w3.org/2002/07/owl#sameAs")
XSD.dateTime  #=> RDF::URI("http://www.w3.org/2001/XMLSchema#dateTime")

Using ad-hoc RDF vocabularies

foaf = RDF::Vocabulary.new("http://xmlns.com/foaf/0.1/")
foaf.knows    #=> RDF::URI("http://xmlns.com/foaf/0.1/knows")
foaf[:name]   #=> RDF::URI("http://xmlns.com/foaf/0.1/name")
foaf['mbox']  #=> RDF::URI("http://xmlns.com/foaf/0.1/mbox")

RDF-star CG

RDF.rb includes provisional support for RDF-star with an N-Triples/N-Quads syntax for quoted triples in the subject or object position.

Support for RDF-star quoted triples is now deprecated, use RDF 1.2 triple terms instead.

RDF 1.2

RDF.rb includes provisional support for RDF 1.2 with an N-Triples/N-Quads syntax for triple terms in the object position. RDF.rb includes provisional support for RDF 1.2 directional language-tagged strings, which are literals of type rdf:dirLangString having both a language and direction.

Internally, an RDF::Statement is treated as another resource, along with RDF::URI and RDF::Node, which allows an RDF::Statement to have a #subject or #object which is also an RDF::Statement.

Note: This feature is subject to change or elimination as the standards process progresses.

Serializing a Graph containing quoted triples

require 'rdf/ntriples'
statement = RDF::Statement(RDF::URI('bob'), RDF::Vocab::FOAF.age, RDF::Literal(23))
graph = RDF::Graph.new << [statement, RDF::URI("ex:certainty"), RDF::Literal(0.9)]
graph.dump(:ntriples, validate: false)
# => '<<<bob> <http://xmlns.com/foaf/0.1/age> "23"^^<http://www.w3.org/2001/XMLSchema#integer>>> <ex:certainty> "0.9"^^<http://www.w3.org/2001/XMLSchema#double> .'

Reading a Graph containing quoted triples

By default, the N-Triples reader will reject a document containing a subject resource.

nt = '<<<bob> <http://xmlns.com/foaf/0.1/age> "23"^^<http://www.w3.org/2001/XMLSchema#integer>>> <ex:certainty> "0.9"^^<http://www.w3.org/2001/XMLSchema#double> .'
graph = RDF::Graph.new do |graph|
  RDF::NTriples::Reader.new(nt) {|reader| graph << reader}
end
# => RDF::ReaderError

Documentation

https://ruby-rdf.github.io/rdf

RDF Object Model

RDF Serialization

RDF Serialization Formats

The following is a partial list of RDF formats implemented either natively, or through the inclusion of other gems:

The meta-gem LinkedData includes many of these gems.

RDF Datatypes

RDF.rb only implements core datatypes from the RDF Datatype Map. Most other XSD and RDF datatype implementations can be find in the following:

Graph Isomorphism

Two graphs may be compared with each other to determine if they are isomorphic. As BNodes within two different graphs are no equal, graphs may not be directly compared. The RDF::Isomorphic gem may be used to determine if they make the same statements, aside from BNode identity (i.e., they each entail the other)

RDF Storage

RDF Querying

RDF Vocabularies

Change Log

See Release Notes on GitHub

Dependencies

Installation

The recommended installation method is via RubyGems. To install the latest official release of RDF.rb, do:

% [sudo] gem install rdf             # Ruby 3+

Download

To get a local working copy of the development repository, do:

% git clone git://github.com/ruby-rdf/rdf.git

Alternatively, download the latest development version as a tarball as follows:

% wget https://github.com/ruby-rdf/rdf/tarball/master

Resources

Mailing List

Authors

Contributors

Contributing

This repository uses Git Flow to mange development and release activity. All submissions must be on a feature branch based on the develop branch to ease staging and integration.

License

This is free and unencumbered public domain software. For more information, see https://unlicense.org/ or the accompanying {file:UNLICENSE} file.