Skip to content

ruby-rdf/rdf-vocab

Repository files navigation

rdf-vocab

Common OWL/RDFS Vocabularies for use with Ruby RDF.rb

Gem Version Build Status Coverage Status Gitter chat

Extensions

This gem extends RDF::Vocabulary with #to_ttl, #to_jsonld, and #to_html methods to create special-purpose vocabulary serializations. The HTML version is templated using a Haml template to allow output to be customized.

Also extends RDF::Vocabulary::Format with the gen-vocab command extension to the rdf executable.

Limiting vocabularies used for lookup

As loading vocabularies can dominate processing time, the RDF::Vocabulary.limit_vocabs method can be used to set a specific set of vocabularies over which to reason. For example:

RDF::Vocabulary.limit_vocabs(:rdf, :rdf, :schema)

will limit the vocabularies which are returned from RDF::Vocabulary.each, which is used for reasoning and other operations over vocabularies and terms.

Vocabularies

Installation

Add to your Gemfile

gem "rdf-vocab"

then

bundle install

Usage

require "rdf/vocab"

This will load all the vocabulary classes in the library.

Also adds the gen-vocab command to the rdf command-line executable to generate specifically generated output in Turtle, JSON-LD, and HTML+RDFa for either built-in or arbitrary vocabularies. Other output serialization formats are also supported as generic RDF Writers and may lack the vocabulary-specific formatting of Turtle, JSON-LD, and HTML+RDFa.

Adding new vocabularies

Vocabularies should only be added to this gem if they are widely used. An equivalent process can be used to add a vocabulary to an arbitrary Ruby application or gem if it is more application specific.

New vocabularies should be generated via a pull request after cloning from GitHub. Be sure to use a custom branch name before creating the PR.

  • First, add an entry to lib/rdf/vocab.rb, the key is used to identify the vocabulary, and as the default basis for the prefix label to use for the vocabulary. The key names of the object value come from the following:

    uri (required)
    The namespace URI for the vocabulary.
    module_name (default RDF::Vocab)
    The Ruby module in which the vocabulary class is created.
    class_name (default from uppercase of the vocabulary identity)
    The class name of the vocabulary
    source (default from uri)
    The source used to fetch the RDF vocabulary definition (most formats supported). Defaults to the vocabulary uri.
    strict (default false)
    Creates a _strict_ vocabulary, so that attempts to use undefined terms in the vocabulary namespace become errors.
    alias (Internal only)
    Indicates that this is an alias for a vocabulary defined directly in the RDF namespace.
    skip
    Do not process this vocabulary, typically when the vocabulary source is inaccessible.
    patch
    The value is taken as a string formatted as an LD Patch used to correct issues in the vocabulary source that may show up when the vocabulary is validated.
    extra
    Value is a JSON Object which is added to the resulting vocabulary definition.

    For more information, see the documentation on RDF::Vocabulary.

  • Next, create an empty file in lib/rdf/vocab based on the key name for your vocabulary. For example, if you've added the vocabulary :foo, create a new empty file at lib/rdf/vocab/foo.rb.

  • Create an entry in the README to document the availability of the library within this gem.

  • Run rake gen_vocabs.

After the PR is merged, it will be available in the develop branch until the next library release.

Example vocabulary definition

The following definition is for the EARL vocabulary, which uses the patch capability to address inherent problems in the vocabulary definition.

  earl: {
    uri: "http://www.w3.org/ns/earl#",
    source: "http://www.w3.org/ns/earl",
    patch: %{
      @prefix earl: <http://www.w3.org/ns/earl#>.
      @prefix owl: <http://www.w3.org/2002/07/owl#>.
      @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.

      AddNew {
        # Extends EARL to talk about collections of assertions
        earl:Report a rdfs:Class, owl:Class ;
          rdfs:label "Report" ;
          rdfs:comment "A collection of earl:Assertion" .
        earl:assertion a owl:ObjectProperty, rdfs:Property ;
          rdfs:label "assertion" ;
          rdfs:comment "Test Assertions associated with an earl:Report or earl:TestCase" ;
          rdfs:domain [
            a owl:Class ;
            owl:unionOf (earl:Report earl:TestCase)
          ] ;
          rdfs:range earl:Assertion .
      } .
    }
  }

Change Log

See Release Notes on GitHub

Authors

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.

  • Do your best to adhere to the existing coding conventions and idioms.
  • Don't use hard tabs, and don't leave trailing whitespace on any line. Before committing, run git diff --check to make sure of this.
  • Do document every method you add using YARD annotations. Read the tutorial or just look at the existing code for examples.
  • Don't touch the .gemspec or VERSION files. If you need to change them, do so on your private branch only.
  • Do note that in order for us to merge any non-trivial changes (as a rule of thumb, additions larger than about 15 lines of code), we need an explicit public domain dedication on record from you, which you will be asked to agree to on the first commit to a repo within the organization. Note that the agreement applies to all repos in the Ruby RDF organization.

License

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