pragmatic_context 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c7c1851a206e8b77ffbaaae7c8fd88ab89c3e5fe
-  data.tar.gz: 824579bd6aeda691cd918acb53f5690c47d31b60
+  metadata.gz: 40b3f7414a092b590f39f53530c841de2eb6856b
+  data.tar.gz: c2690d5363e6ebe4f97d8ff1bf6f74eda15c9d0c
 SHA512:
-  metadata.gz: 11801a92e11a66751f968cc97322f6f56fee0695c92c1b3618e7b81bb8f1a2694546ba664f0b11d0ac369d7c1c76777a8aae2bd05289ea060fae3db09a6ee80e
-  data.tar.gz: 91fdf01fe732d12623c74246b17d8cdd5961fd09effd0487166167ced7ae235b08025507186b502a8993bb43c21ea44b6d518f82eb0196b05bbbb6fa11416b83
+  metadata.gz: 4c73f9b9644b5cba0eec15b9057fa38d89a951cfbed66e1e20e6e87fbc3ab30140e1e7cf18930f780b2dd9dd320aaec424a941a23e99d3de6e6a3808b583e171
+  data.tar.gz: fdd45f04bd8b81024c96dc441a2b8539d59c77ec32e4a9cbb296a7f3a80a8c21eb6944d7e05d577608f3de4ac88005634c98fbc1cd088ab989ed3d5b3a03681b

data/Guardfile

@@ -0,0 +1,4 @@
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+end

data/README.md

@@ -9,7 +9,7 @@ get your models talking JSON-LD.
 I'm glad you asked. [JSON-LD](http://json-ld.org/) is a lightweight JSON format
 for expressing data within a context (also known as 'Linked Data'). Essentially
 what this means is that it lets you say that the thing your data model calls
-a 'last_name' is an embodiment of the abstract idea of a [Family
+a 'last_name' (and what someone else may call 'family_name', or 'surname', or 'apellido') are all embodiments of the same abstract idea of a [Family
 Name](http://xmlns.com/foaf/spec/#term_familyName). JSON-LD is similar in spirit
 (though [vastly different in
 execution](http://manu.sporny.org/2014/json-ld-origins-2/)) to
@@ -116,11 +116,15 @@ it like so:
       contextualize :email, :as => 'http://xmlns.com/foaf/0.1/mbox'
     end
 
-The `Contextualizable` mixin adds a `context` method to the Person object which
-returns a Hash object ready to be serialized into the output object. By wiring
-this up in whatever serializer your application uses, you would end up with
-the following JSON(-LD!) serialization:
+This gives Pragmatic Context everything it needs to be able to create JSON-LD
+representations of your model objects. Getting at these representations is
+discussed in the following section.
 
+### Getting at a JSON-LD representation
+
+The `Contextualizable` mixin adds a `as_jsonld` method that returns a Hash
+representation of your object, ready for serialization. Calling this method on
+the `Person` object described above will produce the following JSON-LD document:
 
     { 
       "@context": {
@@ -133,6 +137,74 @@ the following JSON(-LD!) serialization:
       "email": "mat@geeky.net"
     }
 
+A couple of things to note about this implementation:
+
+* `as_jsonld` will only serialize fields that have matching `contextualize`
+  statements. This is in keeping with JSON-LD's convention of ignoring fields in
+  a document which do not have a context defined.
+* The produced JSON-LD document embeds the context directly in the document,
+  within the `@context` field.
+* For each field present in your object's `as_json` method *that has a matching
+  `contextualize` statement*, `as_jsonld` will:
+    * If the field is a primitive value (string, number, boolean, nil), its
+      value will be copied directly from the output of `as_json`
+    * If the field is a nested object which includes `Contextualizable`, it is
+      recursively converted to JSON-LD by calling its `as_jsonld` method
+    * If the field is a Hash, its keys are copied over to the parent document's
+      representation, namespaced as per the field's `contextualize` statement.
+      More info on this case is given below.
+
+#### Hash subdocuments and namespacing
+
+As dicsussed above, subdocuments which are also `Contextualizable` are
+automatically recused into and serialized into the output of `as_jsonld`. This
+behaviour should be pretty straightforward to understand and make use of, but
+doesn't clearly cover the case where you may want to refer to concepts in
+separate vocabularies with similar names. In this case, Pragmatic Context
+allows for namespacing based on nested hashes.
+
+*This is an advanced use case and probably only useful if you know that you need
+it. If this doesn't make sense to you, feel free to ignore it.*
+
+Nested hashes which have a corresponding `contextualize` statement are copied into the
+parent document within a namespace. This may seem confusing at first, but is
+done principally to realize use cases such as the following:
+
+    class CreativeWork
+      include Mongoid::Document
+      include PragmaticContext::Contextualizable
+
+      field :dc, type: Hash
+      field :mods, type: Hash
+
+      contextualize :dc, :as => 'http://purl.org/dc/terms/'
+      contextualize :mods, :as => 'http://www.loc.gov/mods/rdf/v1#'
+    end
+
+This allows for both dc['title'] and mods['title'] to be set to independent
+values, and for the resulting document to serialize out as something like:
+
+    {
+      "@context": {
+        "dc": "http://purl.org/dc/terms/",
+        "mods": "http://www.loc.gov/mods/rdf/v1#',
+      },
+      "dc:title": "The value of dc['title']",
+      "mods:title": "The value of mods['title']"
+    }
+
+### Custom serializers
+
+If you want to refer to your JSON-LD context by URI (see Example 4 in the [JSON
+spec](http://www.w3.org/TR/json-ld) for more info), or if you want to use your
+own serializer to customize the JSON-LD representaions you produce, you'll want
+to make use of the `Contextualizable` mixin's `context` method.  `context`
+returns a Hash object ready to be serialized into the `@context` field of the
+output object. By wiring this up in whatever serializer your application uses,
+you can easily extend custom serializations to output
+valid JSON-LD.
+
+
 ### Dynamic documents & more complicated cases
 
 There are cases (especially using Monogid's dynamic fields feature) where the
@@ -159,20 +231,6 @@ configured like so:
 
 Examples of this are forthcoming.
 
-## Known Issues
-
-* `@type` values aren't yet handled in any real way. This is next up on my queue
-  and should be done very soon.
-* The above example is purposely short on serialization specifics. I'm trying to
-  be accommodating of various serializers and I'm still figuring out the best
-  way to do this. Hopefully we'll be able to make the process of adding
-  a `@context` automatic (or close to it) for common cases. Suggestions for this
-  point are very welcome.
-* Further to the above, there are many (most, even) use cases where the included
-  `@context` field should simply be a URI pointing to a stand-alone
-  represntation of the object's context. I'm not sure how to flexibly realize
-  this yet. Again, suggestions are very welcome.
-
 ## Contributing
 
 1. Fork it ( http://github.com/mtrudel/pragmatic_context/fork )

data/lib/pragmatic_context/contextualizable.rb

@@ -3,8 +3,6 @@ require 'pragmatic_context/default_contextualizer'
 module PragmaticContext
   module Contextualizable
     def Contextualizable.included(base)
-      base.class_eval do
-      end
       base.extend ClassMethods
     end
 
@@ -30,7 +28,28 @@ module PragmaticContext
     end
 
     def as_jsonld(opts = nil)
-      as_json(opts).merge("@context" => context)
+      # We iterate over terms_with_context because we want to look at our own
+      # fields (and not the fields in 'as_json') to case on their class. In the
+      # case where we want to serialize directly, we rely on the field value as
+      # sourced from as_json
+      terms_with_context = self.class.contextualizer.definitions_for_terms(terms).keys
+      json_results = as_json(opts).slice(*terms_with_context)
+      results = {}
+      terms_with_context.each do |term|
+        # Don't use idiomatic case here since Mongoid relations return proxies
+        # that fail the Contextualizable test
+        value = self.send(term)
+        if (value.is_a? Contextualizable)
+          results[term] = self.send(term).as_jsonld
+        elsif (value.is_a? Hash)
+          self.send(term).each do |key, value|
+            results["#{term}:#{key}"] = value
+          end
+        else
+          results[term] = json_results[term]
+        end
+      end
+      results.merge("@context" => context)
     end
 
     def context
@@ -45,7 +64,7 @@ module PragmaticContext
     private
 
     def terms
-      attributes.keys - ['_id', '_type']
+      as_json.keys
     end
   end
 end

data/lib/pragmatic_context/version.rb

@@ -1,3 +1,3 @@
 module PragmaticContext
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/pragmatic_context.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 2.6"
+  spec.add_development_dependency "guard-rspec"
 
   spec.add_dependency "activesupport"
   spec.add_dependency "activemodel"

data/spec/lib/pragmatic_context/contextualizable_spec.rb

@@ -5,10 +5,10 @@ class Stub
   include ActiveModel::Serializers::JSON
   include PragmaticContext::Contextualizable
 
-  attr_accessor :bacon
+  attr_accessor :bacon, :ham
 
   def attributes
-    { "bacon" => bacon }
+    { "bacon" => bacon, "ham" => ham }
   end
 end
 
@@ -57,12 +57,47 @@ describe PragmaticContext::Contextualizable do
     end
 
     describe 'as_jsonld' do
-      it 'should respond with the underlying as_json result plus the context' do
+      it 'should respond with only contextualized terms plus their context' do
         @contextualizer.stub(:definitions_for_terms) do |terms|
           { 'bacon' => { "@id" => "http://bacon.yum" } }.slice(*terms)
         end
         subject.bacon = 'crispy'
-        subject.as_jsonld.should == subject.as_json.merge("@context" => subject.context)
+        subject.ham = 'honey'
+        subject.as_jsonld.should == { "bacon" => "crispy", "@context" => subject.context }
+      end
+
+      it 'should recurse into Contextualizable subobjects' do
+        @contextualizer.stub(:definitions_for_terms) do |terms|
+          { 'bacon' => { "@id" => "http://bacon.yum" },
+            'ham' => { "@id" => "http://ham.yum" } }.slice(*terms)
+        end
+        subject.bacon = 'crispy'
+        subject.ham = Stub.new
+        subject.ham.bacon = 'nested bacon'
+        subject.ham.ham = 'nested ham'
+        subject.as_jsonld.should == {
+          "@context" => subject.context,
+          "bacon" => "crispy",
+          "ham" => {
+            "@context" => subject.ham.context,
+            "bacon" => "nested bacon",
+            "ham" => "nested ham"
+          }
+        }
+      end
+
+      it 'should compact sub-hashes into namespaced properties on self' do
+        @contextualizer.stub(:definitions_for_terms) do |terms|
+          { 'bacon' => { "@id" => "http://bacon.yum" },
+            'ham' => { "@id" => "http://ham.yum" } }.slice(*terms)
+        end
+        subject.bacon = 'crispy'
+        subject.ham = { 'bacon' => 'nested bacon' }
+        subject.as_jsonld.should == {
+          "@context" => subject.context,
+          "bacon" => "crispy",
+          "ham:bacon" => "nested bacon"
+        }
       end
     end
 
@@ -72,14 +107,16 @@ describe PragmaticContext::Contextualizable do
           { 'bacon' => { "@id" => "http://bacon.yum" } }.slice(*terms)
         end
         subject.bacon = 'crispy'
+        subject.ham = 'honey'
         subject.context['bacon']['@id'].should == 'http://bacon.yum'
+        subject.context['ham'].should == nil
       end
     end
 
     describe 'uncontextualized_terms' do
       it 'should include terms which are not contextualized by the configured Contextualizer' do
         @contextualizer.stub(:definitions_for_terms) { {} }
-        subject.uncontextualized_terms.should == ['bacon']
+        subject.uncontextualized_terms.should == ['bacon', 'ham']
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pragmatic_context
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Mat Trudel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-28 00:00:00.000000000 Z
+date: 2014-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -90,6 +104,7 @@ files:
 - .gitignore
 - .rspec
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -127,4 +142,3 @@ summary: JSON-LD from a JSON perspective
 test_files:
 - spec/lib/pragmatic_context/contextualizable_spec.rb
 - spec/lib/pragmatic_context/default_contextualizer_spec.rb
-has_rdoc: