Add Context::PRELOADED, and Context.add_preloaded. When parsing an otherwise loaded context, if it exists in PRELOADED, use that instead of remotely loading it. Avoids potentially expensive context parsing for common cases.

Addresses #29.

Author: gkellogg

README.md

@@ -240,6 +240,13 @@ Then, when performing something like expansion:
 
     JSON::LD::API.expand(input, documentLoader: load_document_local)
 
+
+## Preloading contexts
+In many cases, for small documents, processing time can be dominated by loading and parsing remote contexts. In particular, a small schema.org example may need to download a large context and turn it into an internal representation, before the actual document can be expanded for processing. Using `JSON::LD::Context.add_preloaded`, an implementation can perform this loading up-front, and make it available to the processor.
+
+    ctx = JSON::LD::Context.new().parse('http://schema.org/')
+    JSON::LD::Context.add_preloaded('http://schema.org/', ctx)
+
 ## RDF Reader and Writer
 {JSON::LD} also acts as a normal RDF reader and writer, using the standard RDF.rb reader/writer interfaces:
 

lib/json/ld/context.rb

@@ -6,6 +6,18 @@ class Context
     include Utils
     include RDF::Util::Logger
 
+    ##
+    # Preloaded contexts.
+    # To avoid runtime context parsing and downloading, contexts may be pre-loaded by implementations.
+    # @return [Hash{Symbol => Context}]
+    PRELOADED = {}
+
+    class << self
+      def add_preloaded(url, context)
+        PRELOADED[url.to_sym] = context
+      end
+    end
+
     # Term Definitions specify how properties and values have to be interpreted as well as the current vocabulary mapping and the default language
     class TermDefinition
       # @return [RDF::URI] IRI map
@@ -279,9 +291,11 @@ def parse(local_context, remote_contexts = [])
             end
           when String, RDF::URI
             log_debug("parse") {"remote: #{context}, base: #{result.context_base || result.base}"}
-            # Load context document, if it is a string
+
             # 3.2.1) Set context to the result of resolving value against the base IRI which is established as specified in section 5.1 Establishing a Base URI of [RFC3986]. Only the basic algorithm in section 5.2 of [RFC3986] is used; neither Syntax-Based Normalization nor Scheme-Based Normalization are performed. Characters additionally allowed in IRI references are treated in the same way that unreserved characters are treated in URI references, per section 6.5 of [RFC3987].
             context = RDF::URI(result.context_base || result.base).join(context)
+            context_canon = RDF::URI(context).canonicalize
+            context_canon.scheme = 'http' if context_canon.scheme == 'https'
 
             raise JsonLdError::RecursiveContextInclusion, "#{context}" if remote_contexts.include?(context.to_s)
             remote_contexts << context.to_s
@@ -290,34 +304,42 @@ def parse(local_context, remote_contexts = [])
             context_no_base.base = nil
             context_no_base.context_base = context.to_s
 
-            begin
-              context_opts = @options.dup
-              context_opts.delete(:headers)
-              @options[:documentLoader].call(context.to_s, context_opts) do |remote_doc|
-                # 3.2.5) Dereference context. If the dereferenced document has no top-level JSON object with an @context member, an invalid remote context has been detected and processing is aborted; otherwise, set context to the value of that member.
-                jo = case remote_doc.document
-                when String then MultiJson.load(remote_doc.document)
-                else remote_doc.document
-                end
-                raise JsonLdError::InvalidRemoteContext, "#{context}" unless jo.is_a?(Hash) && jo.has_key?('@context')
-                context = jo['@context']
-                if @options[:processingMode] == "json-ld-1.0"
-                  context_no_base.provided_context = context.dup
+            if PRELOADED[context_canon.to_s.to_sym]
+              # If we have a cached context, merge it into the current context (result) and use as the new context
+              log_debug("parse") {"=> cached_context: #{context_canon.to_s.inspect}"}
+              context = context_no_base.merge!(PRELOADED[context_canon.to_s.to_sym])
+            else
+
+              # Load context document, if it is a string
+              begin
+                context_opts = @options.dup
+                context_opts.delete(:headers)
+                @options[:documentLoader].call(context.to_s, context_opts) do |remote_doc|
+                  # 3.2.5) Dereference context. If the dereferenced document has no top-level JSON object with an @context member, an invalid remote context has been detected and processing is aborted; otherwise, set context to the value of that member.
+                  jo = case remote_doc.document
+                  when String then MultiJson.load(remote_doc.document)
+                  else remote_doc.document
+                  end
+                  raise JsonLdError::InvalidRemoteContext, "#{context}" unless jo.is_a?(Hash) && jo.has_key?('@context')
+                  context = jo['@context']
+                  if @options[:processingMode] == "json-ld-1.0"
+                    context_no_base.provided_context = context.dup
+                  end
                 end
+              rescue JsonLdError::LoadingDocumentFailed => e
+                log_debug("parse") {"Failed to retrieve @context from remote document at #{context_no_base.context_base.inspect}: #{e.message}"}
+                raise JsonLdError::LoadingRemoteContextFailed, "#{context_no_base.context_base}", e.backtrace
+              rescue JsonLdError
+                raise
+              rescue Exception => e
+                log_debug("parse") {"Failed to retrieve @context from remote document at #{context_no_base.context_base.inspect}: #{e.message}"}
+                raise JsonLdError::LoadingRemoteContextFailed, "#{context_no_base.context_base}", e.backtrace
               end
-            rescue JsonLdError::LoadingDocumentFailed => e
-              log_debug("parse") {"Failed to retrieve @context from remote document at #{context_no_base.context_base.inspect}: #{e.message}"}
-              raise JsonLdError::LoadingRemoteContextFailed, "#{context_no_base.context_base}", e.backtrace
-            rescue JsonLdError
-              raise
-            rescue Exception => e
-              log_debug("parse") {"Failed to retrieve @context from remote document at #{context_no_base.context_base.inspect}: #{e.message}"}
-              raise JsonLdError::LoadingRemoteContextFailed, "#{context_no_base.context_base}", e.backtrace
-            end
 
-            # 3.2.6) Set context to the result of recursively calling this algorithm, passing context no base for active context, context for local context, and remote contexts.
-            context = context_no_base.parse(context, remote_contexts.dup)
-            context.provided_context = result.provided_context
+              # 3.2.6) Set context to the result of recursively calling this algorithm, passing context no base for active context, context for local context, and remote contexts.
+              context = context_no_base.parse(context, remote_contexts.dup)
+              context.provided_context = result.provided_context
+            end
             context.base ||= result.base
             result = context
             log_debug("parse") {"=> provided_context: #{context.inspect}"}
@@ -1314,9 +1336,9 @@ def remove_base(iri)
       b = base.to_s
       return iri[b.length..-1] if iri.start_with?(b) && %w(? #).include?(iri[b.length, 1])
 
-      @base_and_parents.each_with_index do |b, index|
-        next unless iri.start_with?(b)
-        rel = "../" * index + iri[b.length..-1]
+      @base_and_parents.each_with_index do |bb, index|
+        next unless iri.start_with?(bb)
+        rel = "../" * index + iri[bb.length..-1]
         return rel.empty? ? "./" : rel
       end
       iri

spec/context_spec.rb

@@ -92,6 +92,27 @@ def containers
           expect(ec.provided_context).to produce(ctx, logger)
         end
       end
+
+      context "pre-loaded remote" do
+        let(:ctx) {"http://example.com/preloaded"}
+        before(:all) {
+          JSON::LD::Context.add_preloaded("http://example.com/preloaded",
+          JSON::LD::Context.new().parse({'foo' => "http://example.com/"})
+        )}
+        after(:all) {JSON::LD::Context::PRELOADED.clear}
+
+        it "does not load referenced context" do
+          expect(JSON::LD::API).not_to receive(:documentLoader).with(ctx, anything)
+          ec = subject.parse(ctx)
+        end
+
+        it "uses loaded context" do
+          ec = subject.parse(ctx)
+          expect(ec.send(:mappings)).to produce({
+            "foo"   => "http://example.com/"
+          }, logger)
+        end
+      end
     end
 
     context "Array" do