Adds RDF serialization, like n-triples, json-ld or turtle, to active model serializers
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
.rubocop.yml
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
rdf-serializers.gemspec

README.md

RDF Serializers

Build Status

About

RDF Serializers enables serialization to RDF formats. It uses your existing active_model_serializers serializers, with a few modifications. The serialization itself is done by the rdf gem.

This was built at Ontola. If you want to know more about our passion for open data, send us an e-mail.

Installation

Add this line to your application's Gemfile:

gem 'rdf-serializers'

And then execute:

$ bundle

Getting started

First, register the formats you wish to serialize to. For example, add the following to config/initializers/rdf_serializers.rb:

require 'rdf/serializers/renderers'

RDF::Serializers::Renderers.register(:ntriples)

This automatically registers the MIME type.

In your controllers, add:

respond_to do |format|
  format.nt { render nt: model }
end

Configuration

Currently, there is one configuration value which can be set using RDF::Serializers.configure.

RDF::Serializers.configure do |config|
  config.always_include_named_graphs = false # true by default. Whether to include named graphs when the serialization format does not support quads.
end

Formats

You can register multiple formats, if you add the correct gems. For example, add rdf-turtle to your gemfile and put this in the initializer:

require 'rdf/serializers/renderers'

opts = {
  prefixes: {
    ns:   'http://rdf.freebase.com/ns/',
    key:  'http://rdf.freebase.com/key/',
    owl:  'http://www.w3.org/2002/07/owl#',
    rdfs: 'http://www.w3.org/2000/01/rdf-schema#',
    rdf:  'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
    xsd:  'http://www.w3.org/2001/XMLSchema#'
  }
}

RDF::Serializers::Renderers.register(%i[ntriples turtle], opts)

The RDF gem has a list of available RDF Serialization Formats, which includes:

  • NTriples
  • Turtle
  • N3
  • RDF/XML
  • JSON::LD

and more

Serializing

Add a predicate to the attributes and relations you wish to serialize.

It's recommended to reuse existing vocabularies provided by the rdf gem, and add your own for missing predicates. For example:

  MY_VOCAB = RDF::Vocabulary.new('http://example.com/')
  SCHEMA = RDF::Vocabulary.new('http://schema.org/')

Now add the predicates to your serializers.

Old:

class PostSerializer < ActiveModel::Serializer
  attributes :title, :body
  belongs_to :author
  has_many :comments
end

New:

class PostSerializer < ActiveModel::Serializer
  attribute :title, predicate: SCHEMA[:name]
  attribute :body, predicate: SCHEMA[:text]
  belongs_to :author, predicate: MY_VOCAB[:author]
  has_many :comments, predicate: MY_VOCAB[:comments]
end

For RDF serialization, you are required to add an rdf_subject method to your serializer or model, which must return a RDF::Resource. For example:

  def rdf_subject
    RDF::URI(Rails.application.routes.url_helpers.comment_url(object))
  end

In contrast to the JSON API serializer, this rdf serializers don't automatically serialize the type and id of your model. It's recommended to add attribute :type, predicate: RDF[:type] and a method defining the type to your serializers to fix this.

Custom triples per model

You can add custom triples to the serialization of a model in the serializer, for example:

class PostSerializer < ActiveModel::Serializer
  triples :my_custom_triples
  
  def my_custom_triples
    [RDF::Statement.new(RDF::URI('https://example.com'), RDF::TEST[:someValue], 1)]
  end
end

Meta triples

You can add additional triples to the serialization in the controller, for example:

render nt: model, meta: [RDF::Statement.new(RDF::URI('https://example.com'), RDF::TEST[:someValue], 1)]

Contributing

The usual stuff. Open an issue to discuss a change, open pull requests directly for bugfixes and refactors.