LD4L::OpenAnnotationRDF
¶ ↑
LD4L
Open Annotation RDF provides tools for modeling annotations based on the Open Annotation ontology and persisting to a triplestore.
Installation¶ ↑
Add this line to your application's Gemfile:
gem 'ld4l-open_annotation_rdf'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install ld4l-open_annotation_rdf
Primary Dependencies¶ ↑
Usage¶ ↑
Caveat: This gem is part of the LD4L
Project and is being used in that context. There is no guarantee that the code will work in a usable way outside of its use in LD4L
Use Cases.
Examples¶ ↑
Setup required for all examples.
require 'ld4l/open_annotation_rdf' # create an in-memory repository ActiveTriples::Repositories.add_repository :default, RDF::Repository.new p = LD4L::FoafRDF::Person.new('p4')
Example creating a comment annotation.
ca = LD4L::OpenAnnotationRDF::CommentAnnotation.new('c10') ca.hasTarget = RDF::URI("http://example.org/bibref/br3") cb = ca.setComment("This book is a good resource on archery technique.") ca.annotatedBy = p ca.setAnnotatedAtNow ca.persist! puts ca.dump :ttl puts cb.dump :ttl
Example triples created for a comment annotation.
<http://localhost/c10> a <http://www.w3.org/ns/oa#Annotation>; <http://www.w3.org/ns/oa#annotatedAt> "2014-11-26T15:53:49Z"; <http://www.w3.org/ns/oa#annotatedBy> <http://localhost/p4>; <http://www.w3.org/ns/oa#hasBody> <http://localhost/9c8c8126-2d31-48be-81d8-3cd4748a3351>; <http://www.w3.org/ns/oa#hasTarget> <http://example.org/bibref/br3>; <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#commenting> . <http://localhost/9c8c8126-2d31-48be-81d8-3cd4748a3351> a <http://www.w3.org/2011/content#ContentAsText>, <http://purl.org/dc/dcmitype/Text>; <http://purl.org/dc/terms/format> "text/plain"; <http://www.w3.org/2011/content#chars> "This book is a good resource on archery technique." .
Example creating a tag annotation.
ta = LD4L::OpenAnnotationRDF::TagAnnotation.new('t10') ta.hasTarget = RDF::URI("http://example.org/bibref/br3") tb = ta.setTag("archery") ta.annotatedBy = p ta.setAnnotatedAtNow ta.persist! puts ta.dump :ttl puts tb.dump :ttl
Example triples created for a tag annotation.
<http://localhost/t10> a <http://www.w3.org/ns/oa#Annotation>; <http://www.w3.org/ns/oa#annotatedAt> "2014-11-26T15:56:32Z"; <http://www.w3.org/ns/oa#annotatedBy> <http://localhost/p4>; <http://www.w3.org/ns/oa#hasBody> <http://localhost/88db4b38-8b99-4939-b376-1392019aa30c>; <http://www.w3.org/ns/oa#hasTarget> <http://example.org/bibref/br3>; <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#tagging> . <http://localhost/88db4b38-8b99-4939-b376-1392019aa30c> a <http://www.w3.org/ns/oa#Tag>, <http://www.w3.org/2011/content#ContentAsText>; <http://www.w3.org/2011/content#chars> "archery" .
Example creating a semantic tag annotation.
sta = LD4L::OpenAnnotationRDF::SemanticTagAnnotation.new('st10') sta.hasTarget = RDF::URI("http://example.org/bibref/br3") stb = sta.setTerm(RDF::URI("http://example.org/term/engineering")) sta.annotatedBy = p sta.setAnnotatedAtNow sta.persist! puts sta.dump :ttl puts stb.dump :ttl
Example triples created for a semantic tag annotation.
<http://localhost/st10> a <http://www.w3.org/ns/oa#Annotation>; <http://www.w3.org/ns/oa#annotatedAt> "2014-11-26T15:59:01Z"; <http://www.w3.org/ns/oa#annotatedBy> <http://localhost/p4>; <http://www.w3.org/ns/oa#hasBody> <http://example.org/term/engineering>; <http://www.w3.org/ns/oa#hasTarget> <http://example.org/bibref/br3>; <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#tagging> . <http://example.org/term/engineering> a <http://www.w3.org/ns/oa#SemanticTag> .
Resume annotation of known type. This is the more efficient approach and should be used if the type of the annotation is known.
a1 = LD4L::OpenAnnotationRDF::CommentAnnotation.resume(RDF::URI('http://localhost/c10')) # => #<LD4L::OpenAnnotationRDF::CommentAnnotation:0x3fdd8267adc8(default)> comment = a1.getComment # => "This book is a good resource on archery technique." a2 = LD4L::OpenAnnotationRDF::TagAnnotation.resume(RDF::URI('http://localhost/t10')) # => #<LD4L::OpenAnnotationRDF::TagAnnotation:0x3fdd826073f0(default)> tag = a2.getTag # => "archery" a3 = LD4L::OpenAnnotationRDF::SemanticTagAnnotation.resume(RDF::URI('http://localhost/st10')) # => #<LD4L::OpenAnnotationRDF::SemanticTagAnnotation:0x3fdd8259c7a8(default)> term = a2.getTerm # => #<RDF::URI:0x3fdbb4f37300 URI:http://example.org/term/engineering>
Resume annotation of unknown type.
## Using RDF::URI # Create the annotations first using previous examples. a1 = LD4L::OpenAnnotationRDF::Annotation.resume(RDF::URI('http://localhost/c10')) # => #<LD4L::OpenAnnotationRDF::CommentAnnotation:0x3fdd8267adc8(default)> comment = a1.getComment # => "This book is a good resource on archery technique." a2 = LD4L::OpenAnnotationRDF::Annotation.resume(RDF::URI('http://localhost/t10')) # => #<LD4L::OpenAnnotationRDF::TagAnnotation:0x3fdd826073f0(default)> tag = a2.getTag # => "archery" a3 = LD4L::OpenAnnotationRDF::Annotation.resume(RDF::URI('http://localhost/st10')) # => #<LD4L::OpenAnnotationRDF::SemanticTagAnnotation:0x3fdd8259c7a8(default)> term = a2.getTerm # => #<RDF::URI:0x3fdbb4f37300 URI:http://example.org/term/engineering> ## Using string URI # Create the annotations first using previous examples. a1 = LD4L::OpenAnnotationRDF::Annotation.resume('http://localhost/c10') # => #<LD4L::OpenAnnotationRDF::CommentAnnotation:0x3fdd8267adc8(default)> # => #<LD4L::OpenAnnotationRDF::CommentAnnotation:0x3fdd8267adc8(default)> comment = a1.getComment a2 = LD4L::OpenAnnotationRDF::Annotation.resume('http://localhost/t10') # => #<LD4L::OpenAnnotationRDF::TagAnnotation:0x3fdd826073f0(default)> tag = a2.getTag # => "archery" a3 = LD4L::OpenAnnotationRDF::Annotation.resume('http://localhost/st10') # => #<LD4L::OpenAnnotationRDF::SemanticTagAnnotation:0x3fdd8259c7a8(default)> term = a2.getTerm # => #<RDF::URI:0x3fdbb4f37300 URI:http://example.org/term/engineering> ## Using localname expanded using configured base_uri # Create the annotations first using previous examples. a1 = LD4L::OpenAnnotationRDF::Annotation.resume('c10') # => #<LD4L::OpenAnnotationRDF::CommentAnnotation:0x3fdd8267adc8(default)> comment = a1.getComment # => "This book is a good resource on archery technique." a2 = LD4L::OpenAnnotationRDF::Annotation.resume('t10') # => #<LD4L::OpenAnnotationRDF::TagAnnotation:0x3fdd826073f0(default)> tag = a2.getTag # => "archery" a3 = LD4L::OpenAnnotationRDF::Annotation.resume('st10') # => #<LD4L::OpenAnnotationRDF::SemanticTagAnnotation:0x3fdd8259c7a8(default)> term = a2.getTerm # => #<RDF::URI:0x3fdbb4f37300 URI:http://example.org/term/engineering>
Configurations¶ ↑
-
base_uri - base URI used when new resources are created (default=“localhost/”)
-
localname_minter - minter function to use for creating unique local names (default=nil which uses default minter in active_triples-local_name gem)
-
unique_tags - if true, re-use existing TagBodies only creating a new TagBody if one doesn't exist with the tag value being set; otherwise, if false, create new TagBody when tag value is updated (default=true)
Setup for all examples.
-
Restart your interactive session (e.g. irb, pry).
-
Use the Setup for all examples in main Examples section above.
Example usage using configured base_uri and default localname_minter.¶ ↑
LD4L::OpenAnnotationRDF.reset LD4L::OpenAnnotationRDF.configure do |config| config.base_uri = "http://example.org/" end ca = LD4L::OpenAnnotationRDF::CommentAnnotation.new(ActiveTriples::LocalName::Minter.generate_local_name( LD4L::OpenAnnotationRDF::CommentAnnotation, 10, {:prefix=>'ca'} )) puts ca.dump :ttl ca = LD4L::OpenAnnotationRDF::CommentAnnotation.new(ActiveTriples::LocalName::Minter.generate_local_name( LD4L::OpenAnnotationRDF::CommentAnnotation, 10, {:prefix=>'ca'}, &LD4L::OpenAnnotationRDF.configuration.localname_minter )) puts ca.dump :ttl
NOTE: If base_uri is not used, you need to restart your interactive environment (e.g. irb, pry). Once the CommentAnnotation class is instantiated the first time, the base_uri for the class is set. If you ran through the main Examples, the base_uri was set to the default base_uri.
Example triples created for a person with configured base_uri and default minter.
<http://example.org/ca45c9c85b-25af-4c52-96a4-cf0d8b70a768> a <http://www.w3.org/ns/oa#Annotation>; <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#commenting> .
Example usage using configured base_uri and configured localname_minter.¶ ↑
LD4L::OpenAnnotationRDF.configure do |config| config.base_uri = "http://example.org/" config.localname_minter = lambda { |prefix=""| prefix+'_configured_'+SecureRandom.uuid } end ca = LD4L::OpenAnnotationRDF::CommentAnnotation.new(ActiveTriples::LocalName::Minter.generate_local_name( LD4L::OpenAnnotationRDF::CommentAnnotation, 10, 'ca', &LD4L::OpenAnnotationRDF.configuration.localname_minter )) puts ca.dump :ttl
NOTE: If base_uri is not used, you need to restart your interactive environment (e.g. irb, pry). Once the CommentAnnotation class is instantiated the first time, the base_uri for the class is set. If you ran through the main Examples, the base_uri was set to the default base_uri.
Example triples created for a person with configured base_uri and configured minter.
<http://example.org/ca_configured_6498ba05-8b21-4e8c-b9d4-a6d5d2180966> a <http://www.w3.org/ns/oa#Annotation>; <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#commenting> .
Example configuring unique_tags¶ ↑
# Any of these are valid and will change the configuration of unique_tags LD4L::OpenAnnotationRDF.configuration.unique_tags = true LD4L::OpenAnnotationRDF.configuration.unique_tags = false LD4L::OpenAnnotationRDF.configuration.reset_unique_tags
Models¶ ↑
The LD4L::OpenAnnotationRDF
gem provides model definitions using the ActiveTriples framework extension of ruby-rdf/rdf. The following models are provided:
-
LD4L::OpenAnnotationRDF::Annotation
- Implements an open annotation. -
LD4L::OpenAnnotationRDF::CommentAnnotation
- Extends Annotation to implement a comment annotation of free-form text. -
LD4L::OpenAnnotationRDF::CommentBody
- Implements a body holding free-form text. -
LD4L::OpenAnnotationRDF::TagAnnotation
- Extends Annotation to implement a tag annotation of user specified short phrase tag. -
LD4L::OpenAnnotationRDF::TagBody
- Implements a body holding the short phrase tag. -
LD4L::OpenAnnotationRDF::SemanticTagAnnotation
- Extends Annotation to implement a semantic tag annotation with values limited to a controlled vocabulary. -
LD4L::OpenAnnotationRDF::SemanticTagBody
- Implements a body with rdf_subject equal to the URI of the controlled vocabulary term .
Ontologies¶ ↑
The listed ontologies are used to represent the primary metadata about the annotations. Other ontologies may also be used that aren't listed.
Contributing¶ ↑
-
Fork it ( github.com/[my-github-username]/ld4l-open_annotation_rdf/fork )
-
Create your feature branch (
git checkout -b my-new-feature
) -
Commit your changes (
git commit -am 'Add some feature'
) -
Push to the branch (
git push origin my-new-feature
) -
Create a new Pull Request