json_schema_tools 0.0.1 → 0.0.2

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.9.2
+  - 1.9.3
+gemfile:
+  - Gemfile

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog JSON Schema Tools
+
+
+12-2012
+
+* initial version with reader, hasher, params cleaner, attributes module

data/README.md

@@ -1,30 +1,29 @@
 # JSON Schema Tools
 
-{<img src="https://secure.travis-ci.org/salesking/json_schema_tools.png?branch=master" alt="Build Status" />}[http://travis-ci.org/salesking/json_schema_tools]
+[![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:
 
 * read schema files into a ruby hash
 * add schema properties to a class
-* convert a model(class instance) into it's schema markup
+* convert any object into it's schema json markup
 * clean parameters according to a schema (e.g. in an api controller)
 
-
 ## Usage
 
 Hook the gem into your app
 
     gem 'json_schema_tools'
 
-### Read Schema
+## Read Schema
 
-Before the fun begins with any of the tools one or multiple JSON schema files
-must be read(into a hash). So first provide a base path where the .json files
-can be found:
+Before the fun begins, with any of the tools, one or multiple JSON schema files
+must be available(read into a hash). So first provide a base path where the
+schema.json files are located.
 
     SchemaTools.schema_path = '/path/to/schema-json-files'
 
-No you can read a single or multiple schemas:
+Now you can read a single or multiple schemas:
 
     schema = SchemaTools::Reader.read :client
     # read all *.json files in schema path
@@ -32,7 +31,7 @@ No you can read a single or multiple schemas:
     # see schema cached in registry
     SchemaTools::Reader.registry[:client]
 
-Read files from another path?
+Read files from a custom path?
 
     schema = SchemaTools::Reader.read :client, 'my/path/to/json-files'
     schemata = SchemaTools::Reader.read_all 'my/path/to/json-files'
@@ -44,30 +43,76 @@ Don't like the global path and registry? Go local:
     reader.registry
 
 
-## Object to schema markup
+## Object to Schema
 
-A schema provides a (public) contract about an object definition. It is
-therefore a common task to convert an internal object to its schema version.
-Before the object can be represented as a json string, it is converted to a
-hash containing only the properties(keys) from its schema definition:
+A schema provides a (public) contract about an object definition. Therefore an
+internal object is converted to it's schema version on delivery(API access).
+First the object is converted to a hash containing only the properties(keys)
+from its schema definition. Afterwards it is a breeze to convert this hash into
+JSON, with your favorite generator.
 
-Following uses client.json schema(same as client.class name) from global
+Following uses client.json schema(same as peter.class name) inside the global
 schema_path and adds properties to the clients_hash simply calling
 client.send('property-name'):
 
-  peter = Client.new name: 'Peter'
-  client_hash = SchemaTools::Hash.from_schema(peter)
-  # to_json is up to you .. or your rails controller
+    peter = Client.new name: 'Peter'
+    client_hash = SchemaTools::Hash.from_schema(peter)
+    #=> "client"=>{"id"=>12, "name"=> "Peter", "email"=>"",..} # whatever else you have as properties
+    # to_json is up to you .. or your rails controller
+
+### Customise Schema Hash
+
+Only use some fields e.g. to save bandwidth
+
+    client_hash = SchemaTools::Hash.from_schema(peter, fields:['id', 'name'])
+    #=> "client"=>{"id"=>12, "name"=> "Peter"}
+
+Use a custom schema name e.g. to represent a client as contact. Assumes you also
+have a schema named contact.json
+
+    client_hash = SchemaTools::Hash.from_schema(peter, class_name: 'contact')
+    #=> "contact"=>{"id"=>12, "name"=> "Peter"}
+
+Use a custom schema path
+
+    client_hash = SchemaTools::Hash.from_schema(peter, path: 'path-to/json-files/')
+    #=> "client"=>{"id"=>12, "name"=> "Peter"}
 
-TODO: explain Options for parsing:
-* custom class name
-* fields include/exclude
-* custom schema name
+## Parameter cleaning
+
+Hate people spamming your api with wrong object fields? Use the Cleaner to
+check incoming params.
+
+For example in a client controller
+
+    def create
+      SchemaTools::Cleaner.clean_params!(:client, params[:client])
+      # params[:client] now only has keys defined as writable in client.json schema
+      #..create and save client
+    end
+
+## Object attributes from Schema
+
+The use-case here is to add methods, defined in schema properties, to an object.
+Very usefull if you are building a API client and don't want to manually add
+methods to you local classes .. like people NOT using JSON schema
+
+    class Contact
+      include SchemaTools::Modules::Attributes
+      has_schema_attrs :client
+    end
+
+    contact = Client.new
+    contact.last_name = 'Rambo'
+    # raw access
+    contact.schema_attrs
 
 ## Test
 
-  bundle install
-  bundle exec rake spec
+Only runs on Ruby 1.9
+
+    bundle install
+    bundle exec rake spec
 
 
 Copyright 2012-1013, Georg Leciejewski, MIT License

data/lib/schema_tools/cleaner.rb

@@ -11,7 +11,7 @@ module SchemaTools
       #
       # @param [String|Symbol] obj_name of the object/schema
       # @param [Hash{String|Symbol=>Mixed}] params properties for the object
-      # @param [Object] opts
+      # @param [Hash] opts
       # @options opts [Array<String|Symbol>] :keep properties not being kicked
       # even if defined as readonly
       def clean_params!(obj_name, params, opts={})
@@ -22,7 +22,8 @@ module SchemaTools
         setters += opts[:keep] if opts[:keep] && opts[:keep].is_a?(Array)
         # kick readonly
         params.delete_if { |k,v| !setters.include?("#{k}")  }
-        #convert to type in schema
+        #convert to type in schema,
+        # atm. only strings since number can vary float, int, BigDec
         params.each do |k,v|
           if schema[:properties]["#{k}"]['type'] == 'string' && !v.is_a?(String)
             params[k] = "#{v}"

data/lib/schema_tools/modules/attributes.rb

@@ -0,0 +1,40 @@
+require 'active_support/concern'
+module SchemaTools
+  module Modules
+    # Add schema properties to a class by including this module and defining from
+    # which schema to inherit attributes.
+    module Attributes
+      extend ActiveSupport::Concern
+
+      def schema_attrs
+        @schema_attrs ||= {}
+      end
+
+      module ClassMethods
+
+        # @param [Symbol|String] schema name
+        # @param [Hash<Symbol|String>] opts
+        # @options opts [String] :path schema path
+        def has_schema_attrs(schema, opts={})
+          schema = SchemaTools::Reader.read(schema, opts[:path])
+          # 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
+          end
+        end
+
+      end # ClassMethods
+
+    end
+  end
+end

data/lib/schema_tools/modules/hash.rb

@@ -12,35 +12,30 @@ module SchemaTools
       # object-to-api-markup workflow
       #
       # === Example
+      #
       #  obj = Invoice.new(:title =>'hello world', :number=>'4711')
       #
-      #  obj_hash = SchemaTools::Hash.from_schema(obj, 'v1.0')
+      #  obj_hash = SchemaTools::Hash.from_schema(obj)
       #   => { 'invoice' =>{'title'=>'hello world', 'number'=>'4711' } }
       #
-      #  obj_hash = Schema.to_hash_from_schema(obj, 'v1.0', :fields=>['title'])
+      #  obj_hash = Schema.to_hash_from_schema(obj, fields: ['title'])
       #   => { 'invoice' =>{'title'=>'hello world' } }
       #
-      #  obj_hash = Schema.to_hash_from_schema(obj, 'v1.0', :class_name=>:document)
+      #  obj_hash = Schema.to_hash_from_schema(obj, class_name: :document)
       #   => { 'document' =>{'title'=>'hello world' } }
       #
-      # === Parameter
-      # obj<Object>:: An ruby object which is returned as hash
-      # version<String>:: the schema version, must be a valid folder name see
-      # #self.read
-      # opts<Hash{Symbol=>Mixed} >:: additional options
-      #
-      # ==== opts Parameter
-      # class_name<String|Symbol>:: Name of the class to use as hash key. Should be
-      # a lowered, underscored name and it MUST have an existing schema file.
+      # @param [Object] obj which is returned as hash
+      # @param [Hash{Symbol=>Mixed}] opts additional options
+      # @options opts [String|Symbol] :class_name used as hash key. Should be
+      # a lowercase underscored name and it MUST have an existing schema file.
       # Use it to override the default, which is obj.class.name
-      # fields<Array[String]>:: Fields/properties to return. If not set all
-      # schema's properties are used.
+      # @options opts [Array<String>] :fields to return. If not set all schema
+      # properties are used.
+      # @options opts [String] :path of the schema files overriding global one
+      #
+      # @return [Hash{String=>{String=>Mixed}}] The object as hash:
+      #   { 'invoice' => {'title'=>'hello world', 'number'=>'4711' } }
       #
-      # === Return
-      # <Hash{String=>{String=>Mixed}}>:: The object as hash:
-      # { invoice =>{'title'=>'hello world', 'number'=>'4711' } }
-      # @param [Object] obj
-      # @param [Object] opts
       def from_schema(obj, opts={})
         fields = opts[:fields]
         # get objects class name without inheritance
@@ -51,7 +46,7 @@ module SchemaTools
 
         data = {}
         # get schema
-        schema = SchemaTools::Reader.read(class_name)
+        schema = SchemaTools::Reader.read(class_name, opts[:path])
         # iterate over the defined schema fields
         schema['properties'].each do |field, prop|
           next if fields && !fields.include?(field)

data/lib/schema_tools/version.rb

@@ -1,3 +1,3 @@
 module SchemaBuilder
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

data/lib/schema_tools.rb

@@ -2,7 +2,9 @@ require 'json'
 require 'schema_tools/version'
 require 'schema_tools/modules/read'
 require 'schema_tools/modules/hash'
+require 'schema_tools/modules/attributes'
 require 'schema_tools/reader'
+require 'schema_tools/cleaner'
 require 'schema_tools/hash'
 
 

data/spec/fixtures/contact.json

@@ -0,0 +1,29 @@
+{"type":"object",
+  "title": "Contact",
+  "name": "contact",
+  "description": "A simple contact",
+  "properties":{
+    "id":{
+      "description":"Unique identifier ",
+      "identity":true,
+      "readonly":true,
+      "type":"number"
+    },
+    "organisation":{
+      "description": "Name of a company. ",
+      "required" : true,
+      "type":"string",
+      "maxLength": 100
+    },
+    "last_name":{
+      "description": "Last name of a person. ",
+      "type":"string",
+      "maxLength": 50
+    },
+    "first_name":{
+      "description": "First name of a person.",
+      "type":"string",
+      "maxLength": 50
+    }
+  }
+}

data/spec/schema_tools/cleaner_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+describe SchemaTools::Cleaner do
+
+  context 'params cleaning' do
+    let(:params){
+      { id: 'some id',
+        last_name: 'Clean',
+        first_name: 'Paul'
+      }
+    }
+
+    after :each do
+      SchemaTools::Reader.registry_reset
+    end
+
+    it 'should remove invalid keys from hash' do
+      SchemaTools::Cleaner.clean_params!(:client, params)
+      params[:last_name].should == 'Clean'
+      params[:id].should be_nil
+    end
+  end
+end
+

data/spec/schema_tools/hash_spec.rb

@@ -11,6 +11,7 @@ describe SchemaTools::Hash do
     before :each do
       client.first_name = 'Peter'
       client.last_name = 'Paul'
+      client.id = 'SomeID'
     end
     after :each do
       SchemaTools::Reader.registry_reset
@@ -20,6 +21,25 @@ describe SchemaTools::Hash do
       hash = SchemaTools::Hash.from_schema(client)
       hash['client']['last_name'].should == 'Paul'
     end
+
+    it 'should use custom schema path' do
+      custom_path = File.expand_path('../../fixtures', __FILE__)
+      hash = SchemaTools::Hash.from_schema(client, path: custom_path)
+      hash['client']['last_name'].should == 'Paul'
+    end
+
+    it 'should use custom schema' do
+      hash = SchemaTools::Hash.from_schema(client, class_name: :contact)
+      hash['contact']['last_name'].should == 'Paul'
+    end
+
+    it 'should use only give fields' do
+      hash = SchemaTools::Hash.from_schema(client, fields: ['id', 'last_name'])
+      hash['client'].keys.length.should == 2
+      hash['client']['last_name'].should == client.last_name
+      hash['client']['id'].should == client.id
+      hash['client']['first_name'].should be_nil
+    end
   end
 end
 

data/spec/schema_tools/modules/attributes_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+class Contact
+  include SchemaTools::Modules::Attributes
+  has_schema_attrs :client
+end
+
+describe SchemaTools::Modules::Attributes do
+
+  context 'included' do
+    let(:contact){Contact.new}
+
+    it 'should add getter methods' do
+      contact.respond_to?(:last_name).should be_true
+    end
+
+    it 'should add setter methods' do
+      contact.respond_to?('first_name=').should be_true
+    end
+
+    it 'should not add setter for readonly properties' do
+      contact.respond_to?('id=').should be_false
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -13,11 +13,6 @@ $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'json_schema_tools'
 
 RSpec.configure do |config|
-  #config.treat_symbols_as_metadata_keys_with_true_values = true
-  #config.run_all_when_everything_filtered = true
-  #config.filter_run :focus
-  #config.after(:all) do
-  #end
 end
 
 # set global json schema path for examples

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json_schema_tools
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -101,6 +101,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
+- CHANGELOG.md
 - Gemfile
 - README.md
 - Rakefile
@@ -109,14 +111,18 @@ files:
 - lib/schema_tools.rb
 - lib/schema_tools/cleaner.rb
 - lib/schema_tools/hash.rb
+- lib/schema_tools/modules/attributes.rb
 - lib/schema_tools/modules/hash.rb
 - lib/schema_tools/modules/read.rb
 - lib/schema_tools/reader.rb
 - lib/schema_tools/version.rb
 - spec/fixtures/address.json
 - spec/fixtures/client.json
+- spec/fixtures/contact.json
 - spec/fixtures/page.json
+- spec/schema_tools/cleaner_spec.rb
 - spec/schema_tools/hash_spec.rb
+- spec/schema_tools/modules/attributes_spec.rb
 - spec/schema_tools/reader_spec.rb
 - spec/spec_helper.rb
 homepage: http://www.salesking.eu/dev
@@ -133,7 +139,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3313090340920384455
+      hash: -438392315177719693
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -142,7 +148,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3313090340920384455
+      hash: -438392315177719693
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24