json-ld 0.0.8 → 0.1.0

data/History.markdown

@@ -0,0 +1,36 @@
+=== 0.0.8
+* RDF.rb 0.3.4 compatibility.
+* Format detection.
+* Use new @list syntax for parsing ordered collections.
+* Separate normalize from canonicalize
+
+
+=== 0.0.7
+* Change MIME Type and extension from application/json, .json to application/ld+json, .jsonld.
+  * Also added application/x-ld+json
+* Process a remote @context
+* Updated to current state of spec, including support for aliased keywords
+* Update Writer to output consistent with current spec.
+
+=== 0.0.6
+* Another order problem (in literals)
+
+=== 0.0.5
+* Fix @literal, @language, @datatype, and @iri serialization
+* Use InsertOrderPreservingHash for Ruby 1.8
+
+=== 0.0.4
+* Fixed ruby 1.8 hash-order problem when parsing @context.
+* Add .jsonld file extention and format
+* JSON-LD Writer
+* Use test suite from json.org
+* Use '@type' instead of 'a' and '@subject' instead of '@'
+
+=== 0.0.3
+* Downgrade RDF.rb requirement from 0.4.0 to 0.3.3.
+
+=== 0.0.2
+* Functional Reader with reasonable test coverage.
+
+=== 0.0.1
+* First release of project scaffold.

data/{README → README.markdown}

@@ -22,7 +22,7 @@ Full documentation available on [RubyDoc](http://rubydoc.info/gems/json-ld/0.0.4
   * {JSON::LD::Reader}
   * {JSON::LD::Writer}
 
-##Dependencies
+## Dependencies
 * [Ruby](http://ruby-lang.org/) (>= 1.8.7) or (>= 1.8.1 with [Backports][])
 * [RDF.rb](http://rubygems.org/gems/rdf) (>= 0.3.4)
 * [JSON](https://rubygems.org/gems/json) (>= 1.5.1)

data/VERSION

@@ -1 +1 @@
-0.0.8
+0.1.0

data/lib/json/ld.rb

@@ -23,27 +23,103 @@ module JSON
     require 'json'
     require 'json/ld/extensions'
     require 'json/ld/format'
-    autoload :Normalize,  'json/ld/normalize'
-    autoload :Reader,     'json/ld/reader'
-    autoload :VERSION,    'json/ld/version'
-    autoload :Writer,     'json/ld/writer'
+    autoload :API,                'json/ld/api'
+    autoload :EvaluationContext,  'json/ld/evaluation_context'
+    autoload :Normalize,          'json/ld/normalize'
+    autoload :Reader,             'json/ld/reader'
+    autoload :VERSION,            'json/ld/version'
+    autoload :Writer,             'json/ld/writer'
     
-    # Default context
-    # @see http://json-ld.org/spec/ED/20110507/#the-default-context
-    DEFAULT_CONTEXT = {
-      '@coerce'       => {
-      '@iri'          => ['@type']
-      }
+    # Initial context
+    # @see http://json-ld.org/spec/latest/json-ld-api/#appendix-b
+    INITIAL_CONTEXT = {
+      RDF.type.to_s => {"@type" => "@id"}
     }.freeze
 
-    # Default type coercion, in property => datatype order
-    DEFAULT_COERCE = {
-      '@type'            => '@iri',
-      RDF.first.to_s  => false,            # Make sure @coerce isn't generated for this
-      RDF.rest.to_s   => '@iri',
-    }.freeze
+    # Regexp matching an NCName.
+    NC_REGEXP = Regexp.new(
+      %{^
+        (?!\\\\u0301)             # ́ is a non-spacing acute accent.
+                                  # It is legal within an XML Name, but not as the first character.
+        (  [a-zA-Z_]
+         | \\\\u[0-9a-fA-F]
+        )
+        (  [0-9a-zA-Z_\.-]
+         | \\\\u([0-9a-fA-F]{4})
+        )*
+      $},
+      Regexp::EXTENDED)
+
+    # Datatypes that are expressed in a native form and don't expand or compact
+    NATIVE_DATATYPES = [RDF::XSD.integer.to_s, RDF::XSD.boolean.to_s, RDF::XSD.double.to_s]
 
     def self.debug?; @debug; end
     def self.debug=(value); @debug = value; end
+    
+    class ProcessingError < Exception
+      # The compaction would lead to a loss of information, such as a @language value.
+      LOSSY_COMPACTION = 1
+
+      # The target datatype specified in the coercion rule and the datatype for the typed literal do not match.
+      CONFLICTING_DATATYPES = 2
+      
+      attr :code
+      
+      class Lossy < ProcessingError
+        def initialize(*args)
+          super
+          @code = LOSSY_COMPACTION
+        end
+      end
+
+      class Conflict < ProcessingError
+        def initialize(*args)
+          super
+          @code = CONFLICTING_DATATYPES
+        end
+      end
+    end
+    
+    class InvalidContext < Exception
+      # A general syntax error was detected in the @context. For example, if a @type key maps to anything
+      # other than @id or an absolute IRI, this exception would be raised.
+      INVALID_SYNTAX	= 1
+
+      # There was a problem encountered loading a remote context.
+      LOAD_ERROR = 2
+      
+      attr :code
+      
+      class Syntax < InvalidContext
+        def initialize(*args)
+          super
+          @code = INVALID_SYNTAX
+        end
+      end
+
+      class LoadError < InvalidContext
+        def initialize(*args)
+          super
+          @code = LOAD_ERROR
+        end
+      end
+    end
+    
+    class InvalidFrame < Exception
+      # A frame must be either an object or an array of objects, if the frame is neither of these types,
+      # this exception is thrown.
+      INVALID_SYNTAX	= 1
+
+      # A subject IRI was specified in more than one place in the input frame.
+      # More than one embed of a given subject IRI is not allowed, and if requested, must result in this exception.
+      MULTIPLE_EMBEDS = 2
+      
+      attr :code
+      
+      def intialize(message, code = nil)
+        super(message)
+        @code = code
+      end
+    end
   end
 end

data/lib/json/ld/api.rb

@@ -0,0 +1,320 @@
+require 'open-uri'
+
+module JSON::LD
+  ##
+  # A JSON-LD processor implementing the JsonLdProcessor interface.
+  #
+  # This API provides a clean mechanism that enables developers to convert JSON-LD data into a a variety of output formats that
+  # are easier to work with in various programming languages. If a JSON-LD API is provided in a programming environment, the
+  # entirety of the following API must be implemented.
+  #
+  # @see http://json-ld.org/spec/latest/json-ld-api/#the-application-programming-interface
+  # @author [Gregg Kellogg](http://greggkellogg.net/)
+  class API
+    attr_accessor :value
+    attr_accessor :context
+
+    ##
+    # Initialize the API, reading in any document and setting global options
+    #
+    # @param [#read, Hash, Array] input
+    # @param [IO, Hash, Array] context
+    #   An external context to use additionally to the context embedded in input when expanding the input.
+    # @param [Hash] options
+    # @yield [api]
+    # @yieldparam [API]
+    def initialize(input, context, options = {})
+      @options = options
+      @value = input.respond_to?(:read) ? JSON.parse(input.read) : input
+      @context = EvaluationContext.new(options)
+      @context = @context.parse(context) if context
+      yield(self) if block_given?
+    end
+    
+    ##
+    # Expands the given input according to the steps in the Expansion Algorithm. The input must be copied, expanded and returned
+    # if there are no errors. If the expansion fails, an appropriate exception must be thrown.
+    #
+    # @param [#read, Hash, Array] input
+    #   The JSON-LD object to copy and perform the expansion upon.
+    # @param [IO, Hash, Array] context
+    #   An external context to use additionally to the context embedded in input when expanding the input.
+    # @param  [Hash{Symbol => Object}] options
+    # @raise [InvalidContext]
+    # @return [Hash, Array]
+    #   The expanded JSON-LD document
+    # @see http://json-ld.org/spec/latest/json-ld-api/#expansion-algorithm
+    def self.expand(input, context = nil, options = {})
+      result = nil
+      API.new(input, context, options) do |api|
+        result = api.expand(api.value, nil, api.context)
+      end
+      result
+    end
+    
+    ##
+    # Expand an Array or Object given an active context and performing local context expansion.
+    #
+    # @param [Array, Hash] input
+    # @param [RDF::URI] predicate
+    # @param [EvaluationContext] context
+    # @return [Array, Hash]
+    def expand(input, predicate, context)
+      debug("expand") {"input: #{input.class}, predicate: #{predicate.inspect}, context: #{context.inspect}"}
+      case input
+      when Array
+        # 1) If value is an array, process each item in value recursively using this algorithm,
+        #    passing copies of the active context and active property.
+        depth {input.map {|v| expand(v, predicate, context)}}
+      when Hash
+        # Merge context
+        context = context.parse(input['@context']) if input['@context']
+      
+        result = Hash.new
+        input.each do |key, value|
+          debug("expand") {"#{key}: #{value.inspect}"}
+          expanded_key = context.mapping(key) || key
+          case expanded_key
+          when '@context'
+            # Ignore in output
+          when '@id', '@type'
+            # If the key is @id or @type and the value is a string, expand the value according to IRI Expansion.
+            result[expanded_key] = case value
+            when String then context.expand_iri(value, :position => :subject, :depth => @depth).to_s
+            else depth { expand(value, predicate, context) }
+            end
+            debug("expand") {" => #{result[expanded_key].inspect}"}
+          when '@literal', '@language'
+            raise ProcessingError::Lossy, "Value of #{expanded_key} must be a string, was #{value.inspect}" unless value.is_a?(String)
+            result[expanded_key] = value
+            debug("expand") {" => #{result[expanded_key].inspect}"}
+          else
+            # 2.2.3) Otherwise, if the key is not a keyword, expand the key according to IRI Expansion rules and set as active property.
+            unless key[0,1] == '@'
+              predicate = context.expand_iri(key, :position => :predicate, :depth => @depth)
+              expanded_key = predicate.to_s
+            end
+
+            # 2.2.4) If the value is an array, and active property is subject to @list expansion,
+            #   replace the value with a new key-value key where the key is @list and value set to the current value.
+            value = {"@list" => value} if value.is_a?(Array) && context.list(predicate)
+            
+            value = case value
+            # 2.2.5) If the value is an array, process each item in the array recursively using this algorithm,
+            #   passing copies of the active context and active property
+            # 2.2.6) If the value is an object, process the object recursively using this algorithm,
+            #   passing copies of the active context and active property.
+            when Array, Hash then depth {expand(value, predicate, context)}
+            else
+              # 2.2.7) Otherwise, expand the value according to the Value Expansion rules, passing active property.
+              context.expand_value(predicate, value, :position => :object, :depth => @depth)
+            end
+            result[expanded_key] = value
+            debug("expand") {" => #{value.inspect}"}
+          end
+        end
+        result
+      else
+        # 2.3) Otherwise, expand the value according to the Value Expansion rules, passing active property.
+        context.expand_value(predicate, input, :position => :object, :depth => @depth)
+      end
+    end
+
+    ##
+    # Compacts the given input according to the steps in the Compaction Algorithm. The input must be copied, compacted and
+    # returned if there are no errors. If the compaction fails, an appropirate exception must be thrown.
+    #
+    # If no context is provided, the input document is compacted using the top-level context of the document
+    #
+    # @param [IO, Hash, Array] input
+    #   The JSON-LD object to copy and perform the compaction upon.
+    # @param [IO, Hash, Array] context
+    #   The base context to use when compacting the input.
+    # @param  [Hash{Symbol => Object}] options
+    # @raise [InvalidContext, ProcessingError]
+    # @return [Hash]
+    #   The compacted JSON-LD document
+    # @see http://json-ld.org/spec/latest/json-ld-api/#compaction-algorithm
+    def self.compact(input, context = nil, options = {})
+      expanded = result = nil
+
+      API.new(input, nil, options) do |api|
+        expanded = api.expand(api.value, nil, api.context)
+      end
+
+      API.new(expanded, context, options) do |api|
+        # 1) Perform the Expansion Algorithm on the JSON-LD input.
+        #    This removes any existing context to allow the given context to be cleanly applied.
+        
+        result = api.compact(api.value, nil)
+
+        # xxx) Add the given context to the output
+        result = case result
+        when Hash then api.context.serialize.merge(result)
+        when Array then api.context.serialize.merge("@id" => result)
+        end
+      end
+      result
+    end
+
+    ##
+    # Compact an expanded Array or Hash given an active property and a context.
+    #
+    # @param [Array, Hash] input
+    # @param [RDF::URI] predicate (nil)
+    # @param [EvaluationContext] context
+    # @return [Array, Hash]
+    def compact(input, predicate = nil)
+      debug("compact") {"input: #{input.class}, predicate: #{predicate.inspect}"}
+      case input
+      when Array
+        # 1) If value is an array, process each item in value recursively using this algorithm,
+        #    passing copies of the active context and active property.
+        debug("compact") {"Array[#{input.length}]"}
+        depth {input.map {|v| compact(v, predicate)}}
+      when Hash
+        result = Hash.new
+        input.each do |key, value|
+          debug("compact") {"#{key}: #{value.inspect}"}
+          compacted_key = context.alias(key)
+          debug("compact") {" => compacted key: #{compacted_key.inspect}"} unless compacted_key == key
+
+          case key
+          when '@id', '@type'
+            # If the key is @id or @type
+            result[compacted_key] = case value
+            when String, RDF::Value
+              # If the value is a string, compact the value according to IRI Compaction.
+              context.compact_iri(value, :position => :subject, :depth => @depth).to_s
+            when Hash
+              # Otherwise, if value is an object containing only the @id key, the compacted value
+              # if the result of performing IRI Compaction on that value.
+              if value.keys == ["@id"]
+                context.compact_iri(value["@id"], :position => :subject, :depth => @depth).to_s
+              else
+                depth { compact(value, predicate) }
+              end
+            else
+              # Otherwise, the compacted value is the result of performing this algorithm on the value
+              # with the current active property.
+              depth { compact(value, predicate) }
+            end
+            debug("compact") {" => compacted value: #{result[compacted_key].inspect}"}
+          else
+            # Otherwise, if the key is not a keyword, set as active property and compact according to IRI Compaction.
+            unless key[0,1] == '@'
+              predicate = RDF::URI(key)
+              compacted_key = context.compact_iri(key, :position => :predicate, :depth => @depth)
+              debug("compact") {" => compacted key: #{compacted_key.inspect}"}
+            end
+
+            # If the value is an object
+            compacted_value = if value.is_a?(Hash)
+              if value.keys == ['@id'] || value['@literal']
+                # If the value contains only an @id key or the value contains a @literal key, the compacted value
+                # is the result of performing Value Compaction on the value.
+                debug("compact") {"keys: #{value.keys.inspect}"}
+                context.compact_value(predicate, value, :depth => @depth)
+              elsif value.keys == ['@list'] && context.list(predicate)
+                # Otherwise, if the value contains only a @list key, and the active property is subject to list coercion,
+                # the compacted value is the result of performing this algorithm on that value.
+                debug("compact") {"list"}
+                depth {compact(value['@list'], predicate)}
+              else
+                # Otherwise, the compacted value is the result of performing this algorithm on the value
+                debug("compact") {"object"}
+                depth {compact(value, predicate)}
+              end
+            elsif value.is_a?(Array)
+              # Otherwise, if the value is an array, the compacted value is the result of performing this algorithm on the value.
+              debug("compact") {"array"}
+              depth {compact(value, predicate)}
+            else
+              # Otherwise, the value is already compacted.
+              debug("compact") {"value"}
+              value
+            end
+            debug("compact") {" => compacted value: #{compacted_value.inspect}"}
+            result[compacted_key || key] = compacted_value
+          end
+        end
+        result
+      else
+        # For other types, the compacted value is the input value
+        debug("compact") {input.class.to_s}
+        input
+      end
+    end
+
+    ##
+    # Frames the given input using the frame according to the steps in the Framing Algorithm. The input is used to build the
+    # framed output and is returned if there are no errors. If there are no matches for the frame, null must be returned.
+    # Exceptions must be thrown if there are errors.
+    #
+    # @param [IO, Hash, Array] input
+    #   The JSON-LD object to copy and perform the framing on.
+    # @param [IO, Hash, Array] frame
+    #   The frame to use when re-arranging the data.
+    # @param  [Hash{Symbol => Object}] options
+    # @raise [InvalidFrame]
+    # @return [Hash]
+    #   The framed JSON-LD document
+    def self.frame(input, frame, options = {})
+    end
+
+    ##
+    # Normalizes the given input according to the steps in the Normalization Algorithm. The input must be copied, normalized and
+    # returned if there are no errors. If the compaction fails, null must be returned.
+    #
+    # @param [IO, Hash, Array] input
+    #   The JSON-LD object to copy and perform the normalization upon.
+    # @param [IO, Hash, Array] context
+    #   An external context to use additionally to the context embedded in input when expanding the input.
+    # @param  [Hash{Symbol => Object}] options
+    # @raise [InvalidContext]
+    # @return [Hash]
+    #   The normalized JSON-LD document
+    def self.normalize(input, object, context = nil, options = {})
+    end
+
+    ##
+    # Processes the input according to the RDF Conversion Algorithm, calling the provided tripleCallback for each triple generated.
+    #
+    # @param [IO, Hash, Array] input
+    #   The JSON-LD object to process when outputting triples.
+    # @param [IO, Hash, Array] context
+    #   An external context to use additionally to the context embedded in input when expanding the input.
+    # @param  [Hash{Symbol => Object}] options
+    # @raise [InvalidContext]
+    # @yield statement
+    # @yieldparam [RDF::Statement] statement
+    # @return [Hash]
+    #   The normalized JSON-LD document
+    def self.triples(input, object, context = nil, options = {})
+    end
+    
+  private
+    # Add debug event to debug array, if specified
+    #
+    # @param [String] message
+    # @yieldreturn [String] appended to message, to allow for lazy-evaulation of message
+    def debug(*args)
+      return unless ::JSON::LD.debug? || @options[:debug]
+      list = args
+      list << yield if block_given?
+      message = " " * (@depth || 0) * 2 + (list.empty? ? "" : list.join(": "))
+      puts message if JSON::LD::debug?
+      @options[:debug] << message if @options[:debug].is_a?(Array)
+    end
+
+    # Increase depth around a method invocation
+    def depth(options = {})
+      old_depth = @depth || 0
+      @depth = (options[:depth] || old_depth) + 1
+      ret = yield
+      @depth = old_depth
+      ret
+    end
+  end
+end
+