README.md in jsi-0.6.0 vs README.md in jsi-0.7.0
- old
+ new
@@ -1,8 +1,8 @@
# JSI: JSON Schema Instantiation
-[](https://travis-ci.org/notEthan/jsi)
+
[](https://coveralls.io/github/notEthan/jsi)
JSI offers an Object-Oriented representation for JSON data using JSON Schemas. Given your JSON Schemas, JSI constructs Ruby modules and classes which are used to instantiate your JSON data. These modules let you use JSON with all the niceties of OOP such as property accessors and application-defined instance methods.
To learn more about JSON Schema see [https://json-schema.org/](https://json-schema.org/).
@@ -44,10 +44,12 @@
```ruby
Contact = contact_schema.jsi_schema_module
```
+Note: it is more concise to instantiate the schema module with the shortcut {JSI.new_schema_module}, i.e. `Contact = JSI.new_schema_module(...)`. This example includes the intermediate step to help show all that is happening.
+
To instantiate the schema, we need some JSON data (expressed here as YAML)
```yaml
name: bill
phone:
@@ -171,22 +173,25 @@
def name=(name)
super(name.chomp(' esq.'))
end
end
+bill.phone_numbers
+# => ["555"]
+
bill.name
# => "bill esq."
bill.name = 'rob esq.'
# => "rob esq."
bill['name']
# => "rob"
-bill.phone_numbers
-# => ["555"]
```
-Note the use of `super` - you can call to accessors defined by JSI and make your accessors act as wrappers. You can alternatively use `[]` and `[]=` with the same effect.
+`#phone_numbers` is a new method returning each number in the `phone` array - pretty straightforward.
+For `#name` and `#name=`, we're overriding existing accessor methods. note the use of `super` - this invokes the accessor methods defined by JSI which these override. You could alternatively use `self['name']` and `self['name']=` in these methods, with the same effect as `super`.
+
Working with subschemas is just about as easy as with root schemas.
You can subscript or use property accessors on a JSI schema module to refer to the schema modules of its subschemas, e.g.:
```ruby
@@ -267,18 +272,18 @@
Let's say you're sticking to JSON types in the database - you have to do so if you're using JSON columns, or JSON serialization, and if you have dealt with arbitrary yaml- or marshal-serialized objects in ruby, you have probably found that approach has its shortcomings when the implementation of your classes changes.
But if your database contains JSON, then your deserialized objects in ruby are likewise Hash / Array / basic types. You have to use subscripts instead of accessors, and you don't have any way to add methods to your data types.
-JSI gives you the best of both with JSICoder. This coder dumps objects which are simple JSON types, and loads instances of a specified JSI schema. Here's an example, supposing a `users` table with a JSON column `contact_info`:
+JSI gives you the best of both with {JSI::JSICoder}. This coder dumps objects which are simple JSON types, and loads instances of a specified JSON Schema. Here's an example, supposing a `users` table with a JSON column `contact_info` to be instantiated using the `Contact` schema module defined in the Example section above:
```ruby
class User < ActiveRecord::Base
serialize :contact_info, JSI::JSICoder.new(Contact)
end
```
-Now `user.contact_info` will be instantiated as a Contact JSI instance, from the JSON type in the database, with Contact's accessors, validations, and user-defined instance methods.
+Now `user.contact_info` will be instantiated as a `Contact` JSI instance, from the JSON type in the database, with Contact's accessors, validations, and user-defined instance methods.
See the gem [`arms`](https://github.com/notEthan/arms) if you wish to serialize the dumped JSON-compatible objects further as text.
## Keying Hashes (JSON Objects)