json_schema_tools 0.2.3 → 0.2.4

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OTJhOGY1MWU1MjhmMjAwMjg2YmNlMzM4MWY0ZjI0YzE1ZDkxYjAxZQ==
+  data.tar.gz: !binary |-
+    NTY2N2ZmNDg4MDc0NzUzYmFmNzYyODg1MjAwMjA1MzcyNjBjMDZmNg==
+SHA512:
+  metadata.gz: !binary |-
+    MWI1OGE0MTdlNjM3NDYwMGZjMjc5MThhNjRmMjAwNTJjNWViMGJiNThhMGFh
+    M2ZjM2YxMWYxOTk0Y2ViMTU4YjJkMjE4Y2JmY2M3NjQzMzZjOGRiMTNjODg0
+    MmE3MDM1NzZmNmU0NzEwMjE3Y2MyYjcwZDQ0NDljN2ZiYzE5NDI=
+  data.tar.gz: !binary |-
+    YWZlMDgzMDFjZDI1M2IzNDQwNDI5ZTM5MTkzYjg3NzNkMGQwYTExNmZmYzQz
+    ZTdhMDQ4ZmUwMTU2Njg3YTQ4MzI5ZGMwY2VjM2ZhNGVjYzFlNDYyYTA2ZDZk
+    MmE4ZjE3ZDA3ZWM1MThhZDFmOTFmZWI0NmQ2NWI3OTVlNDUzMDc=

data/.gitignore

@@ -7,4 +7,4 @@ Gemfile.lock
 .yardoc
 doc/
 tmp/
-*.*~
+*.swp

data/README.md

@@ -2,12 +2,18 @@
 
 [![Build Status](https://travis-ci.org/salesking/json_schema_tools.png?branch=master)](https://travis-ci.org/salesking/json_schema_tools)
 
-Set of tools to help working with JSON Schemata:
+Toolbox to work with JSON Schema in Ruby:
 
-* read schema files into a ruby hash
-* add schema properties to a class
-* convert any object into it's schema JSON markup
-* clean parameters according to a schema (e.g. in an api controller)
+* blow up classes from schema
+* object.as_json conversion
+* object.valid? validations with object.errors
+
+Simply use full blown classes or customize the bits and pieces:
+
+* add schema properties to an existing class
+* add validations to an existing class
+* clean parameters e.g. in an api controller
+* customize json output, object namespaces, used schema
 
 ## Usage
 
@@ -15,14 +21,33 @@ Hook the gem into your app
 
     gem 'json_schema_tools'
 
-## Read Schema
+Quickstart assuming you have schema definitions [like those](https://github.com/salesking/sk_api_schema/tree/master/json/v1.0) in place.
+
+```ruby
+# add schema directory to the search path
+SchemaTools.schema_path = '/path/to/schema-json-files'
+# blow up classes for each schema file
+SchemaTools::KlassFactory.build
+
+# init with params (assumes a contact.json definition)
+contact = Contact.new first_name: 'Barry', last_name: 'Cade'
+# use setters/getters
+contact.first_name = 'Ahr'
+# validations derived from property definitions
+contact.valid?
+contact.errors.full_messages
+```
+
+## Schema handling
 
 Before the fun begins, with any of the tools, one or multiple JSON schema(files)
 must be available. A schema is converted into a ruby hash and for convenience is
-cached into a registry (global or local). So you only need to initialize them
-once e.g on program start.
+cached into a registry (global or per reader object). Globals are initialized
+once e.g on program start. A reader object allows to handle schemata in dynamic
+ways.
 
-Provide a base path where the schema json files are located.
+When using the global SchemaTools reader simply provide a base path to the
+schema files and you are done.
 
 ```ruby
 SchemaTools.schema_path = '/path/to/schema-json-files'
@@ -69,7 +94,7 @@ reader.registry
 
 ## Object to JSON  - from Schema
 
-As you probably know such is done e.g in rails via object.to_json. While using
+As you probably know such is done e.g in rails via object.as_json. While using
 this might be simple, it has a damn big drawback: There is no transparent
 contract about the data-structure, as rails simply uses all fields defined in the
 database(ActiveRecord model). One side-effect: With each migration you are f***ed
@@ -90,10 +115,10 @@ class Client < ActiveRecord::Base
 end
 
 peter = Client.new name: 'Peter'
-peter.as_schema_json
+peter.as_json
 #=> "client":{"id":12, "name": "Peter", "email":"",..}
 
-peter.as_schema_hash
+peter.as_hash
 #=> "client"=>{"id"=>12, "name"=> "Peter", "email"=>"",..}
 ```
 
@@ -114,7 +139,7 @@ course they can be combined.
 Only use some fields e.g. to save bandwidth
 
 ```ruby
-peter.as_schema_json(fields:['id', 'name'])
+peter.as_json(fields:['id', 'name'])
 #=> "client":{"id":12, "name": "Peter"}
 ```
 
@@ -122,13 +147,13 @@ Use a custom schema name e.g. to represent a client as contact. Assumes you also
 have a schema named contact.json
 
 ```ruby
-peter.as_schema_json(class_name: 'contact')
+peter.as_json(class_name: 'contact')
 ```
 
 Set a custom schema path
 
 ```ruby
-peter.as_schema_json( path: 'path-to/json-files/')
+peter.as_json( path: 'path-to/json-files/')
 ```
 
 By default the object hash has the class name (client) and the link-section on
@@ -140,7 +165,7 @@ inline:
 
 ```ruby
 
-peter.as_schema_json( exclude_root: true )
+peter.as_json( exclude_root: true )
 
 #=> {"id":12, "name"=> "Peter",
 #    "_class_name":"client",
@@ -185,7 +210,7 @@ contact.last_name = 'Rambo'
 # raw access
 contact.schema_attrs
 # to json
-contact.as_schema_json
+contact.as_json
 ```
 
 ## Classes from Schema - KlassFactory

data/lib/schema_tools.rb

@@ -9,6 +9,7 @@ require 'schema_tools/reader'
 require 'schema_tools/cleaner'
 require 'schema_tools/hash'
 require 'schema_tools/klass_factory'
+require 'schema_tools/ref_resolver'
 
 
 module SchemaTools
@@ -22,4 +23,4 @@ module SchemaTools
       @schema_path
     end
   end
-end
+end

data/lib/schema_tools/klass_factory.rb

@@ -32,34 +32,45 @@ module SchemaTools
         reader = opts[:reader] || SchemaTools::Reader
         schemata = reader.read_all( opts[:path] || SchemaTools.schema_path )
         namespace = opts[:namespace] || Object
-        if namespace.is_a?(String) || namespace.is_a?(Symbol)
-          namespace = "#{namespace}".constantize
-        end
+        namespace = "#{namespace}".constantize if namespace.is_a?(String) || namespace.is_a?(Symbol)
         # bake classes
         schemata.each do |schema|
-          klass_name = schema['name'].classify
-          next if namespace.const_defined?(klass_name, false)
-          klass = namespace.const_set(klass_name, Class.new)
-          klass.class_eval do
-            include SchemaTools::Modules::Attributes
-            include ActiveModel::Conversion
-            include SchemaTools::Modules::Validations # +naming + transl + conversion
-            has_schema_attrs schema['name'], reader: reader
-            validate_with schema['name'], reader:reader
-            getter_names = schema['properties'].select{|name,prop| !prop['readonly'] }.keys.map { |name| name.to_sym}
-            attr_accessor *getter_names
+          next if !schema['name'] or namespace.const_defined?(schema['name'].classify, false)
+          build_class(schema, namespace, reader)
+        end
+      end
 
-            def initialize(attributes = {})
-              attributes.each do |name, value|
-                send("#{name}=", value)
-              end
-            end
+      # @param [Object] schema single json schema
+      # @param [Constant] namespace for the new class
+      # @param [SchemaTools::Reader] reader set into new class for validation and attributes
+      def build_class(schema, namespace, reader)
+        klass_name = schema['name'].classify
+        klass = namespace.const_set(klass_name, Class.new)
+        klass.class_eval do
+          include SchemaTools::Modules::Attributes
+          include ActiveModel::Conversion
+          include SchemaTools::Modules::Validations # +naming + transl + conversion
+          has_schema_attrs schema['name'], reader: reader
+          validate_with schema['name'], reader:reader
+          getter_names = schema['properties'].select{|name,prop| !prop['readonly'] }
+                                             .keys.map { |name| name.to_sym}
+          attr_accessor *getter_names
 
-            def persisted?; false end
+          def initialize(attributes = {})
+            attributes.each do |name, value|
+              send("#{name}=", value)
+            end
           end
-        end
+
+          def persisted?; false end
+        end # class
+      end
+
+      # @param [Object] name
+      def namespace(name)
+
       end
 
     end
   end
-end
+end

data/lib/schema_tools/modules/as_schema.rb

@@ -5,16 +5,17 @@ module SchemaTools
     module AsSchema
       extend ActiveSupport::Concern
 
-      # convert this class to a schema markup.
+      # convert object to a schema markup.
       # @param [Hash{Symbol=>Mixed}] opts passed on to #SchemaTools::Hash.from_schema
       # @return [String] json
       def as_schema_json(opts={})
         ActiveSupport::JSON.encode(as_schema_hash(opts))
       end
+      def as_json(opts={}) as_schema_json(opts); end
 
-      # Get the object as hash with fields detected from its schema.
-      # The schema is derived from
-      # * from options[:class_name]
+      # The object as hash with fields detected from its schema.
+      # The schema name is derived from:
+      # * options[:class_name]
       # * has_schema_attrs definition(if used)
       # * the underscored class name
       # @param [Hash{Symbol=>Mixed}] opts passed on to #SchemaTools::Hash.from_schema
@@ -26,9 +27,11 @@ module SchemaTools
         end
         SchemaTools::Hash.from_schema(self, opts)
       end
+      def as_hash(opts={}) as_schema_hash(opts); end
 
       module ClassMethods
         # Get or set the schema name used
+        # @param [Symbol|String] name
         def schema_name(name=nil)
           @schema_name = name if name
           @schema_name

data/lib/schema_tools/modules/attributes.rb

@@ -3,6 +3,15 @@ module SchemaTools
   module Modules
     # Add schema properties to a class by using has_schema_attrs to define from
     # which schema to inherit attributes.
+    # @example
+    #
+    #   class Contact
+    #     has_schema_attrs :contact
+    #   end
+    #   Contact.schema_name #=> contact
+    #   Contact.as_json
+    #   Contact.as_hash
+    #   Contact.schema  #=> json schema hash
     module Attributes
       extend ActiveSupport::Concern
       include SchemaTools::Modules::AsSchema
@@ -11,6 +20,10 @@ module SchemaTools
         @schema_attrs ||= {}
       end
 
+      def schema
+        self.class.schema
+      end
+
       module ClassMethods
 
         # @param [Symbol|String] schema name
@@ -20,27 +33,24 @@ module SchemaTools
         def has_schema_attrs(schema_name, opts={})
           reader          = opts[:reader] || SchemaTools::Reader
           schema_location = opts[:path]   || opts[:schema]
-          schema          = reader.read(schema_name, schema_location)
-          # remember name on class level
+          # remember schema + name on class level
+          self.schema( reader.read(schema_name, schema_location) )
           self.schema_name(schema_name)
           # make getter / setter
-          schema[:properties].each do |key, val|
-            # getter
-            define_method key do
-              schema_attrs[key]
-            end
-            #setter
-            unless val[:readonly]
-              define_method "#{key}=" do |value|
-                #TODO validations?
-                schema_attrs[key] = value
-              end
-            end
+          self.schema[:properties].each do |key, prop|
+            define_method(key) { schema_attrs[key] }
+            define_method("#{key}=") { |value| schema_attrs[key] = value } unless prop[:readonly]
           end
+          #TODO parse links ?? or do it in resource module
         end
 
-      end
+        # @param [Hash] schema_hash
+        def schema(schema_hash=nil)
+          @schema = schema_hash if schema_hash
+          @schema
+        end
 
+      end
     end
   end
 end

data/lib/schema_tools/modules/read.rb

@@ -57,6 +57,7 @@ module SchemaTools
             schema[:properties] = ext[:properties].merge(schema[:properties])
           end
         end
+        _handle_reference_properties schema
         registry[ schema_name ] = schema
       end
 
@@ -74,6 +75,25 @@ module SchemaTools
         end
         schemas
       end
+
+      # Merge referenced property definitions into the given schema.
+      # e.g. each object has an updated_at field which we define in a single
+      # location(external file) instead of repeating the property def in each
+      # schema.
+      # @param [HashWithIndifferentAccess] schema - single schema
+      def _handle_reference_properties(schema)
+        return unless schema["properties"]
+        schema["properties"].each { |key, value|
+          next unless value["$ref"]
+
+          json_pointer = value["$ref"]
+          values_from_pointer = RefResolver.load_json_pointer json_pointer
+          schema["properties"][key].merge!(values_from_pointer) {|key, old, new|
+            old
+          }
+          schema["properties"][key].delete("$ref")
+        }
+      end
     end
   end
 end

data/lib/schema_tools/ref_resolver.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+require 'json'
+
+module SchemaTools
+  class RefResolver
+
+  #
+  # super basic resolving of JSON Pointer stuff in order
+  # to be able to load $ref parameter.
+  #
+  # $refs in JSON Schema are defined in JSON Pointer syntax:
+  # http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07
+  #
+  # @param [String] json_pointer the JSON Pointer expression to evaluate
+  # @param [Hash] schema if the pointer refers to a local schema, this is this
+  # the hash to evaluate it against. If the pointer contains a uri to a
+  # referenced schema, an attempt is made to load
+  def self.load_json_pointer json_pointer, schema = {}
+    # JSON Pointer is a big, abandoned WIP and we're going to
+    # start by only implementing the part's we need ...
+    if nil ==  (json_pointer =~ /^(.*)#(.*)/ )
+      raise "invalid json pointer: #{json_pointer}"
+    end
+
+    uri     = $1.strip
+    pointer = $2
+
+    if ! uri.empty?
+      uri = URI.parse(uri)
+      raise "must currently be a relative uri: #{json_pointer}" if uri.absolute?
+      path = SchemaTools.schema_path + "/" + uri.path
+      open (path) {|f|
+        schema = JSON.parse(f.read)
+      }
+    end
+
+    return self._retrieve_pointer_from_object pointer, schema
+  end
+
+
+  def self._retrieve_pointer_from_object pointer, object
+    # assume path to be the JSONPointer expression:
+    #  json/pointer/expression
+    # and obj to be the ruby hash representation of the json
+    path = pointer.is_a?(Array) ? pointer : pointer.split("/")
+
+    while object != nil && component = path.shift
+      prev   = object
+      component = component.to_i if object.is_a?(Array) && component =~ /^\d+$/
+      object = object[component]
+    end
+
+    return object
+  end
+
+  end # module
+end # module
+
+
+
+

data/lib/schema_tools/version.rb

@@ -1,3 +1,3 @@
 module SchemaTools
-  VERSION = '0.2.3'
+  VERSION = '0.2.4'
 end

data/spec/fixtures/basic_definitions.json

@@ -0,0 +1,13 @@
+{
+    "definitions": {
+        "id": {
+            "description": "some description",
+            "readonly": true,
+            "type": "integer"
+        },
+        "some_other_property": {
+            "description": "whatever",
+            "type": "string"
+        }
+    }
+}

data/spec/fixtures/includes_basic_definitions.json

@@ -0,0 +1,19 @@
+{
+  "type":"object",
+  "title":"test_object",
+  "name":"includes_basic_definitions",
+  "description":"test_object",
+  "properties": {
+    "id":{
+      "$ref" : "./basic_definitions.json#definitions/id"
+    },
+    "id_adding_param": {
+      "$ref"      : "./basic_definitions.json#definitions/id",
+      "maxLength" : 10
+    },
+    "id_overriding_param" : {
+      "$ref"        : "./basic_definitions.json#definitions/id",
+      "description" : "some other description"
+    }
+  }
+}

data/spec/schema_tools/modules/attributes_spec.rb

@@ -31,6 +31,14 @@ describe SchemaTools::Modules::Attributes do
     it 'should add schema_name to class' do
       subject.class.schema_name.should == :client
     end
+
+    it 'should add schema to class' do
+      subject.class.schema.should == SchemaTools::Reader.read(:client)
+    end
+
+    it 'should add schema to object' do
+      subject.schema.should == SchemaTools::Reader.read(:client)
+    end
   end
 
   context 'attributes from dynamic schema' do

data/spec/schema_tools/reader_spec.rb

@@ -33,6 +33,15 @@ describe SchemaTools::Reader do
       schema[:properties][:numbers].should_not be_empty
     end
 
+    it 'should deal with referenced parameters properly' do
+      schema = SchemaTools::Reader.read(:includes_basic_definitions)
+      schema[:properties].should_not be_empty
+      schema[:properties].length.should eq 3
+      schema[:properties][:id][:description].should eq "some description"
+
+      schema[:properties][:id]["$ref"].should be_nil
+    end
+
     it 'should enforce correct parameter usage' do
       expect { SchemaTools::Reader.read(:contact, []) }.to raise_error ArgumentError
     end

data/spec/schema_tools/ref_resolver_spec.rb

@@ -0,0 +1,71 @@
+require 'spec_helper'
+
+describe SchemaTools::RefResolver do
+  context 'class methods' do
+    it 'should handle simple json pointer' do
+      obj = { "bla" => {
+        "blub" => :success
+      }}
+
+      pointer = "bla/blub"
+      found = SchemaTools::RefResolver._retrieve_pointer_from_object pointer, obj
+      # not sure what I am doing wrong here, but:
+      #    found.should eq :success
+      # does not work because
+      #    undefined method `eq'
+      found.should eq :success
+
+      found = SchemaTools::RefResolver._retrieve_pointer_from_object "non/existant/path", obj
+      found.should  be_nil
+    end
+
+    it 'should handle json pointer arrays' do
+      obj = { "bla" => {
+        "blub" => :success,
+        "bling" => [3,2,1]
+      }}
+      pointer = "bla/bling/2"
+      found = SchemaTools::RefResolver._retrieve_pointer_from_object pointer, obj
+      found.should eq 1
+
+      pointer = "bla/bling/3"
+      found = SchemaTools::RefResolver._retrieve_pointer_from_object pointer, obj
+      found.should be_nil
+
+    end
+
+    it 'should handle embedded json pointer arrays' do
+      obj = { "bla" => {
+        "blub" => :success,
+        "bling" => [
+          {"num" => 3},
+          {"num" => 2},
+          {"num" => 1}
+        ]
+      }}
+      pointer = "bla/bling/1/num"
+      found = SchemaTools::RefResolver._retrieve_pointer_from_object pointer, obj
+      found.should eq 2
+    end
+  end
+
+  it 'should throw an exception on an invalid path' do
+    obj = {}
+    expect {
+      SchemaTools::RefResolver.load_json_pointer("bla")
+    }.to raise_error
+  end
+
+  it 'should reject absolute URI part' do
+    obj = {}
+    expect {
+      SchemaTools::RefResolver.load_json_pointer("http://www.example.com/#some/stuff")
+    }.to raise_error
+  end
+
+  it 'should load local ref' do
+    pointer = "./basic_definitions.json#definitions"
+    obj = SchemaTools::RefResolver.load_json_pointer(pointer)
+    obj.length.should eq 2
+  end
+end

data/spec/spec_helper.rb

@@ -16,6 +16,7 @@ require 'test_helpers'
 RSpec.configure do |config|
 end
 
+I18n.enforce_available_locales = false if I18n.respond_to?('enforce_available_locales=')
 # set global json schema path for examples
 SchemaTools.schema_path = File.expand_path('../fixtures', __FILE__)
 

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: json_schema_tools
 version: !ruby/object:Gem::Version
-  version: 0.2.3
-  prerelease: 
+  version: 0.2.4
 platform: ruby
 authors:
 - Georg Leciejewski
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-28 00:00:00.000000000 Z
+date: 2014-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -30,7 +27,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -38,7 +34,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -46,7 +41,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -54,7 +48,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -62,7 +55,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -70,7 +62,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -102,10 +93,13 @@ files:
 - lib/schema_tools/modules/read.rb
 - lib/schema_tools/modules/validations.rb
 - lib/schema_tools/reader.rb
+- lib/schema_tools/ref_resolver.rb
 - lib/schema_tools/version.rb
 - spec/fixtures/address.json
+- spec/fixtures/basic_definitions.json
 - spec/fixtures/client.json
 - spec/fixtures/contact.json
+- spec/fixtures/includes_basic_definitions.json
 - spec/fixtures/lead.json
 - spec/fixtures/page.json
 - spec/schema_tools/cleaner_spec.rb
@@ -114,30 +108,30 @@ files:
 - spec/schema_tools/modules/as_schema_spec.rb
 - spec/schema_tools/modules/attributes_spec.rb
 - spec/schema_tools/reader_spec.rb
+- spec/schema_tools/ref_resolver_spec.rb
 - spec/spec_helper.rb
 - spec/test_helpers.rb
 homepage: https://github.com/salesking/json_schema_tools
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.2.2
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: JSON Schema API tools for server and client side
 test_files: []