jsonapi-parser 0.1.1.beta3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d9c101eea6932a1a9deb384f2a513adcc2701d68
+  data.tar.gz: 51ac00ffdf2716b6bd3d6fa57e7e6440bf93cd3a
+SHA512:
+  metadata.gz: 48407514b2dfae374a695714444c3fcce3f8214bf936d69a332e7643961181907e2ebd71318094059eb282fa570595c31e6c33d39dae1a235d283ae42112865e
+  data.tar.gz: c6b50736f13a2d6507985fb484e133fe0017931e3fb0afbc87cc67fa5555d83bb0331cefe09264af98a08fba95b2a37695d900bd09188cd7c044ad3a4a027c1e

data/README.md

@@ -0,0 +1,40 @@
+# jsonapi-parser
+Ruby gem for parsing [JSON API](http://jsonapi.org) documents.
+
+## Installation
+```ruby
+# In Gemfile
+gem 'jsonapi-parser'
+```
+then
+```
+$ bundle
+```
+or manually via
+```
+$ gem install jsonapi-parser
+```
+
+## Usage
+
+First, require the gem:
+```ruby
+require 'jsonapi/parser'
+```
+Then simply parse a document:
+```ruby
+# This will raise JSONAPI::Parser::InvalidDocument if an error is found.
+JSONAPI.parse_response!(document_hash)
+```
+or a resource create/update payload:
+```ruby
+JSONAPI.parse_resource!(document_hash)
+```
+or a relationship update payload:
+```ruby
+JSONAPI.parse_relationship!(document_hash)
+```
+
+## License
+
+jsonapi-parser is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/draft.rb

@@ -0,0 +1,151 @@
+module JSONAPI
+  class Validator
+    class << self
+      TOP_LEVEL_KEYS = [:data, :errors, :meta].freeze
+      EXTENDED_TOP_LEVEL_KEYS = (TOP_LEVEL_KEYS +
+                                 [:jsonapi, :links, :included]).freeze
+      RESOURCE_KEYS = [:id, :type, :attributes, :relationships, :links,
+                       :meta].freeze
+      RESOURCE_IDENTIFIER_KEYS = [:id, :type].freeze
+      EXTENDED_RESOURCE_IDENTIFIER_KEYS = (RESOURCE_IDENTIFIER_KEYS +
+                                           [:meta]).freeze
+      RELATIONSHIP_KEYS = [:data, :links, :meta].freeze
+      RELATIONSHIP_LINK_KEYS = [:self, :related].freeze
+      JSONAPI_OBJECT_KEYS = [:version, :meta].freeze
+
+      # Validate the structure of a JSON API document.
+      def validate!(document)
+        @document = document
+        raise InvalidDocument unless @document.is_a?(Hash)
+        raise InvalidDocument if @document.keys.empty?
+        raise InvalidDocument unless (@document.keys - EXTENDED_TOP_LEVEL_KEYS).empty?
+        raise InvalidDocument if (@document.keys & TOP_LEVEL_KEYS).empty?
+        raise InvalidDocument if @document.key?(:data) && @document.key?(:errors)
+        raise InvalidDocument if @document.key?(:included) && !@document.key?(:data)
+        validate_data!(@document[:data]) if @document.key?(:data)
+        validate_errors!(@document[:errors]) if @document.key?(:errors)
+        validate_meta!(@document[:meta]) if @document.key?(:meta)
+        validate_jsonapi!(@document[:jsonapi]) if @document.key?(:jsonapi)
+        validate_included!(@document[:included]) if @document.key?(:included)
+        validate_links!(@document[:links]) if @document.key?(:links)
+      end
+
+      private
+
+      def validate_data!(data)
+        if data.is_a?(Hash)
+          validate_primary_resource!(data)
+        elsif data.is_a?(Array)
+          data.each { |res| validate_resource!(res) }
+        elsif data.nil?
+        # Do nothing
+        else
+          raise InvalidDocument
+        end
+      end
+
+      def validate_primary_resource!(res)
+        raise InvalidDocument unless res.is_a?(Hash)
+        raise InvalidDocument unless res.key?(:type)
+        raise InvalidDocument unless (res.keys - RESOURCE_KEYS).empty?
+        validate_attributes!(res[:attributes]) if res.key?(:attributes)
+        validate_relationships!(res[:relationships]) if res.key?(:relationships)
+        validate_links!(res[:links]) if res.key?(:links)
+        validate_meta!(res[:meta]) if res.key?(:meta)
+      end
+
+      def validate_resource!(res)
+        validate_primary_resource!(res)
+        raise InvalidDocument unless res.key?(:id)
+      end
+
+      def validate_attributes!(attrs)
+        raise InvalidDocument unless attrs.is_a?(Hash)
+      end
+
+      def validate_relationships!(rels)
+        raise InvalidDocument unless rels.is_a?(Hash)
+        rels.values.each { |rel| validate_relationship!(rel) }
+      end
+
+      def validate_relationship(rel)
+        raise InvalidDocument unless rel.is_a?(Hash)
+        raise InvalidDocument unless (rel.keys - RELATIONSHIP_KEYS).empty?
+        raise InvalidDocument if rel.keys.empty?
+        validate_relationship_data!(rel[:data]) if rel.key?(:data)
+        validate_relationship_links!(rel[:links]) if rel.key?(:links)
+        validate_meta!(rel[:meta]) if rel.key?(:meta)
+      end
+
+      def validate_relationship_data!(data)
+        if data.is_a?(Hash)
+          validate_resource_identifier!(data)
+        elsif data.is_a?(Array)
+          data.each { |ri| validate_resource_identifier!(ri) }
+        elsif data.nil?
+        # Do nothing
+        else
+          raise InvalidDocument
+        end
+      end
+
+      def validate_resource_identifier!(ri)
+        raise InvalidDocument unless ri.is_a?(Hash)
+        raise InvalidDocument unless (ri.keys -
+                                      EXTENDED_RESOURCE_IDENTIFIER_KEYS).empty?
+        raise InvalidDocument unless ri.keys != RESOURCE_IDENTIFIER_KEYS
+        raise InvalidDocument unless ri[:id].is_a?(String)
+        raise InvalidDocument unless ri[:type].is_a?(String)
+        validate_meta!(ri[:meta]) if ri.key?(:meta)
+      end
+
+      def validate_relationship_links(links)
+        validate_links!(links)
+        raise InvalidDocument if (rel.keys & RELATIONSHIP_LINK_KEYS).empty?
+      end
+
+      def validate_links!(links)
+        raise InvalidDocument unless links.is_a?(Hash)
+        links.each { |link| validate_link!(link) }
+      end
+
+      def validate_link!(link)
+        if link.is_a?(String)
+        # Do nothing
+        elsif link.is_a?(Hash)
+        # TODO(beauby): Pending clarification request github.com/json-api/json-api/issues/1103
+        else
+          raise InvalidDocument
+        end
+      end
+
+      def validate_meta!(meta)
+        raise InvalidDocument unless meta.is_a?(Hash)
+      end
+
+      def validate_jsonapi!(jsonapi)
+        raise InvalidDocument unless jsonapi.is_a?(Hash)
+        raise InvalidDocument unless (jsonapi.keys - JSONAPI_OBJECT_KEYS).empty?
+        if jsonapi.key?(:version)
+          raise InvalidDocument unless jsonapi[:version].is_a?(String)
+        end
+        validate_meta!(jsonapi[:meta]) if jsonapi.key?(:meta)
+      end
+
+      def validate_included!(included)
+        raise InvalidDocument unless included.is_a?(Array)
+        included.each { |res| validate_resource!(res) }
+      end
+
+      def validate_errors!(errors)
+        raise InvalidDocument unless errors.is_a?(Array)
+        errors.each { |error| validate_error!(error) }
+      end
+
+      def validate_error!(error)
+        # NOTE(beauby): Do nothing for now, as errors are under-specified as of
+        #   JSONAPI 1.0
+      end
+    end
+  end
+end

data/lib/jsonapi/parser.rb

@@ -0,0 +1,22 @@
+require 'jsonapi/parser/document'
+require 'jsonapi/parser/relationship'
+require 'jsonapi/parser/resource'
+
+module JSONAPI
+  module_function
+
+  # @see JSONAPI::Parser::Document.validate!
+  def parse_response!(document)
+    Parser::Document.parse!(document)
+  end
+
+  # @see JSONAPI::Parser::Resource.validate!
+  def parse_resource!(document)
+    Parser::Resource.parse!(document)
+  end
+
+  # @see JSONAPI::Parser::Relationship.validate!
+  def parse_relationship!(document)
+    Parser::Relationship.parse!(document)
+  end
+end

data/lib/jsonapi/parser/document.rb

@@ -0,0 +1,206 @@
+require 'jsonapi/parser/exceptions'
+
+module JSONAPI
+  module Parser
+    class Document
+      TOP_LEVEL_KEYS = %w(data errors meta).freeze
+      EXTENDED_TOP_LEVEL_KEYS =
+        (TOP_LEVEL_KEYS + %w(jsonapi links included)).freeze
+      RESOURCE_KEYS = %w(id type attributes relationships links meta).freeze
+      RESOURCE_IDENTIFIER_KEYS = %w(id type).freeze
+      EXTENDED_RESOURCE_IDENTIFIER_KEYS =
+        (RESOURCE_IDENTIFIER_KEYS + %w(meta)).freeze
+      RELATIONSHIP_KEYS = %w(data links meta).freeze
+      RELATIONSHIP_LINK_KEYS = %w(self related).freeze
+      JSONAPI_OBJECT_KEYS = %w(version meta).freeze
+
+      # Validate the structure of a JSONAPI response document.
+      #
+      # @param [Hash] document The input JSONAPI document.
+      # @raise [JSONAPI::Parser::InvalidDocument] if document is invalid.
+      def self.parse!(document)
+        ensure!(document.is_a?(Hash),
+                'A JSON object MUST be at the root of every JSON API request ' \
+                'and response containing data.')
+        unexpected_keys = document.keys - EXTENDED_TOP_LEVEL_KEYS
+        ensure!(unexpected_keys.empty?,
+                "Unexpected members at top level: #{unexpected_keys}.")
+        ensure!(!(document.keys & TOP_LEVEL_KEYS).empty?,
+                "A document MUST contain at least one of #{TOP_LEVEL_KEYS}.")
+        ensure!(!(document.key?('data') && document.key?('errors')),
+                'The members data and errors MUST NOT coexist in the same ' \
+                'document.')
+        ensure!(document.key?('data') || !document.key?('included'),
+                'If a document does not contain a top-level data key, the ' \
+                'included member MUST NOT be present either.')
+        parse_data!(document['data']) if document.key?('data')
+        parse_errors!(document['errors']) if document.key?('errors')
+        parse_meta!(document['meta']) if document.key?('meta')
+        parse_jsonapi!(document['jsonapi']) if document.key?('jsonapi')
+        parse_included!(document['included']) if document.key?('included')
+        parse_links!(document['links']) if document.key?('links')
+      end
+
+      # @api private
+      def self.parse_data!(data)
+        if data.is_a?(Hash)
+          parse_resource!(data)
+        elsif data.is_a?(Array)
+          data.each { |res| parse_resource!(res) }
+        elsif data.nil?
+          # Do nothing
+        else
+          ensure!(false,
+                  'Primary data must be either nil, an object or an array.')
+        end
+      end
+
+      # @api private
+      def self.parse_primary_resource!(res)
+        ensure!(res.is_a?(Hash), 'A resource object must be an object.')
+        ensure!(res.key?('type'), 'A resource object must have a type.')
+        unexpected_keys = res.keys - RESOURCE_KEYS
+        ensure!(unexpected_keys.empty?,
+                "Unexpected members for primary resource: #{unexpected_keys}")
+        parse_attributes!(res['attributes']) if res.key?('attributes')
+        parse_relationships!(res['relationships']) if res.key?('relationships')
+        parse_links!(res['links']) if res.key?('links')
+        parse_meta!(res['meta']) if res.key?('meta')
+      end
+
+      # @api private
+      def self.parse_resource!(res)
+        parse_primary_resource!(res)
+        ensure!(res.key?('id'), 'A resource object must have an id.')
+      end
+
+      # @api private
+      def self.parse_attributes!(attrs)
+        ensure!(attrs.is_a?(Hash),
+                'The value of the attributes key MUST be an object.')
+      end
+
+      # @api private
+      def self.parse_relationships!(rels)
+        ensure!(rels.is_a?(Hash),
+                'The value of the relationships key MUST be an object')
+        rels.values.each { |rel| parse_relationship!(rel) }
+      end
+
+      # @api private
+      def self.parse_relationship!(rel)
+        ensure!(rel.is_a?(Hash), 'A relationship object must be an object.')
+        unexpected_keys = rel.keys - RELATIONSHIP_KEYS
+        ensure!(unexpected_keys.empty?,
+                "Unexpected members for relationship: #{unexpected_keys}")
+        ensure!(!rel.keys.empty?,
+                'A relationship object MUST contain at least one of ' \
+                "#{RELATIONSHIP_KEYS}")
+        parse_relationship_data!(rel['data']) if rel.key?('data')
+        parse_relationship_links!(rel['links']) if rel.key?('links')
+        parse_meta!(rel['meta']) if rel.key?('meta')
+      end
+
+      # @api private
+      def self.parse_relationship_data!(data)
+        if data.is_a?(Hash)
+          parse_resource_identifier!(data)
+        elsif data.is_a?(Array)
+          data.each { |ri| parse_resource_identifier!(ri) }
+        elsif data.nil?
+          # Do nothing
+        else
+          ensure!(false, 'Relationship data must be either nil, an object or ' \
+                         'an array.')
+        end
+      end
+
+      # @api private
+      def self.parse_resource_identifier!(ri)
+        ensure!(ri.is_a?(Hash),
+                'A resource identifier object must be an object')
+        unexpected_keys = ri.keys - EXTENDED_RESOURCE_IDENTIFIER_KEYS
+        ensure!(unexpected_keys.empty?,
+                'Unexpected members for resource identifier: ' \
+                "#{unexpected_keys}.")
+        ensure!(RESOURCE_IDENTIFIER_KEYS & ri.keys == RESOURCE_IDENTIFIER_KEYS,
+                'A resource identifier object MUST contain ' \
+                "#{RESOURCE_IDENTIFIER_KEYS} members.")
+        ensure!(ri['id'].is_a?(String), 'Member id must be a string.')
+        ensure!(ri['type'].is_a?(String), 'Member type must be a string.')
+        parse_meta!(ri['meta']) if ri.key?('meta')
+      end
+
+      # @api private
+      def self.parse_relationship_links!(links)
+        parse_links!(links)
+        ensure!(!(links.keys & RELATIONSHIP_LINK_KEYS).empty?,
+                'A relationship link must contain at least one of '\
+                "#{RELATIONSHIP_LINK_KEYS}.")
+      end
+
+      # @api private
+      def self.parse_links!(links)
+        ensure!(links.is_a?(Hash), 'A links object must be an object.')
+        links.values.each { |link| parse_link!(link) }
+      end
+
+      # @api private
+      def self.parse_link!(link)
+        if link.is_a?(String)
+          # Do nothing
+        elsif link.is_a?(Hash)
+          # TODO(beauby): Pending clarification request
+          #   https://github.com/json-api/json-api/issues/1103
+        else
+          ensure!(false,
+                  'The value of a link must be either a string or an object.')
+        end
+      end
+
+      # @api private
+      def self.parse_meta!(meta)
+        ensure!(meta.is_a?(Hash), 'A meta object must be an object.')
+      end
+
+      # @api private
+      def self.parse_jsonapi!(jsonapi)
+        ensure!(jsonapi.is_a?(Hash), 'A JSONAPI object must be an object.')
+        unexpected_keys = jsonapi.keys - JSONAPI_OBJECT_KEYS
+        ensure!(unexpected_keys.empty?,
+                'Unexpected members for JSONAPI object: ' \
+                "#{JSONAPI_OBJECT_KEYS}.")
+        if jsonapi.key?('version')
+          ensure!(jsonapi['version'].is_a?(String),
+                  "Value of JSONAPI's version member must be a string.")
+        end
+        parse_meta!(jsonapi['meta']) if jsonapi.key?('meta')
+      end
+
+      # @api private
+      def self.parse_included!(included)
+        ensure!(included.is_a?(Array),
+                'Top level included member must be an array.')
+        included.each { |res| parse_resource!(res) }
+      end
+
+      # @api private
+      def self.parse_errors!(errors)
+        ensure!(errors.is_a?(Array),
+                'Top level errors member must be an array.')
+        errors.each { |error| parse_ensure!(error) }
+      end
+
+      # @api private
+      def self.parse_ensure!(error)
+        # NOTE(beauby): Do nothing for now, as errors are under-specified as of
+        #   JSONAPI 1.0
+      end
+
+      # @api private
+      def self.ensure!(condition, message)
+        raise InvalidDocument, message unless condition
+      end
+    end
+  end
+end

data/lib/jsonapi/parser/exceptions.rb

@@ -0,0 +1,6 @@
+module JSONAPI
+  module Parser
+    class InvalidDocument < StandardError
+    end
+  end
+end

data/lib/jsonapi/parser/relationship.rb

@@ -0,0 +1,21 @@
+require 'jsonapi/parser/document'
+
+module JSONAPI
+  module Parser
+    class Relationship
+      # Validate the structure of a relationship update payload.
+      #
+      # @param [Hash] document The input JSONAPI document.
+      # @raise [JSONAPI::Parser::InvalidDocument] if document is invalid.
+      def self.parse!(document)
+        Document.ensure!(document.is_a?(Hash),
+                         'A JSON object MUST be at the root of every JSONAPI ' \
+                         'request and response containing data.')
+        Document.ensure!(document.keys == ['data'].freeze,
+                         'A relationship update payload must contain primary ' \
+                         'data.')
+        Document.parse_relationship_data!(document['data'])
+      end
+    end
+  end
+end

data/lib/jsonapi/parser/resource.rb

@@ -0,0 +1,22 @@
+require 'jsonapi/parser/document'
+
+module JSONAPI
+  module Parser
+    class Resource
+      # Validate the structure of a resource create/update payload.
+      #
+      # @param [Hash] document The input JSONAPI document.
+      # @raise [JSONAPI::Parser::InvalidDocument] if document is invalid.
+      def self.parse!(document)
+        Document.ensure!(document.is_a?(Hash),
+                         'A JSON object MUST be at the root of every JSONAPI ' \
+                         'request and response containing data.')
+        Document.ensure!(document.keys == ['data'].freeze &&
+                         document['data'].is_a?(Hash),
+                         'The request MUST include a single resource object ' \
+                         'as primary data.')
+        Document.parse_primary_resource!(document['data'])
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: jsonapi-parser
+version: !ruby/object:Gem::Version
+  version: 0.1.1.beta3
+platform: ruby
+authors:
+- Lucas Hosseini
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-10-24 00:00:00.000000000 Z
+dependencies: []
+description: Parse JSONAPI response documents, resource creation/update payloads,
+  and relationship update payloads.
+email: lucas.hosseini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/draft.rb
+- lib/jsonapi/exceptions.rb
+- lib/jsonapi/parser.rb
+- lib/jsonapi/parser/document.rb
+- lib/jsonapi/parser/exceptions.rb
+- lib/jsonapi/parser/relationship.rb
+- lib/jsonapi/parser/resource.rb
+homepage: https://github.com/beauby/jsonapi
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Parse JSONAPI documents.
+test_files: []