README.md in jsi-0.1.0 vs README.md in jsi-0.2.0
- old
+ new
@@ -1,14 +1,16 @@
# JSI: JSON-Schema Instantiation
[](https://travis-ci.org/notEthan/jsi)
[](https://coveralls.io/github/notEthan/jsi)
-JSI represents JSON-schemas as ruby classes, and schema instances as instances of those classes.
+JSI offers an Object-Oriented representation for JSON data using JSON Schemas. Given your JSON Schemas, JSI constructs Ruby classes which are used to instantiate your JSON data. These classes let you use JSON with all the niceties of OOP such as property accessors and application-defined instance methods.
-A JSI class aims to be a fairly unobtrusive wrapper around its instance. It adds accessors for known property names, validation methods, and a few other nice things. Mostly though, you use a JSI as you would use its underlying data, calling the same methods (e.g. `#[]`, `#map`, `#repeated_permutation`) and passing it to anything that duck-types expecting #to_ary or #to_hash.
+To learn more about JSON Schema see [https://json-schema.org/]().
+A JSI class aims to be a fairly unobtrusive wrapper around its instance - "instance" here meaning the JSON data which instantiate the JSON Schema. The instance is usually a Hash or an Array but may be basic types, or in fact any object. A JSI class adds accessors for property names described by its schema, schema validation, and other nice things. Mostly though, you use a JSI as you would use its underlying data, calling the same methods (e.g. `#[]`, `#map`, `#repeated_permutation`) and passing it to anything that duck-types expecting #to_ary or #to_hash.
+
## Example
Words are boring, let's code. Here's a schema in yaml:
```yaml
@@ -35,14 +37,15 @@
This definition gives you not just the Contact class, but classes for the whole nested structure. So, if we construct an instance like:
```ruby
bill = Contact.new('name' => 'bill', 'phone' => [{'location' => 'home', 'number' => '555'}], 'nickname' => 'big b')
-# => #{<Contact fragment="#">
-# #{<Contact fragment="#">
-# "phone" => #[<JSI::SchemaClasses["1f97#/properties/phone"] fragment="#/phone">
-# #{<JSI::SchemaClasses["1f97#/properties/phone/items"] fragment="#/phone/0"> "location" => "home", "number" => "555"}
+
+# => #{<Contact Hash>
+# "name" => "bill",
+# "phone" => #[<JSI::SchemaClasses["23d8#/properties/phone"] Array>
+# #{<JSI::SchemaClasses["23d8#/properties/phone/items"] Hash> "location" => "home", "number" => "555"}
# ],
# "nickname" => "big b"
# }
```
@@ -73,19 +76,19 @@
... and validations on the nested schema instances (#phone here), showing in this example validation failure:
```ruby
bad = Contact.new('phone' => [{'number' => [5, 5, 5]}])
-# => #{<Contact fragment="#">
-# "phone" => #[<JSI::SchemaClasses["1f97#/properties/phone"] fragment="#/phone">
-# #{<JSI::SchemaClasses["1f97#/properties/phone/items"] fragment="#/phone/0">
-# "number" => #[<JSI::SchemaClasses["1f97#/properties/phone/items/properties/number"] fragment="#/phone/0/number"> 5, 5, 5]
+# => #{<Contact Hash>
+# "phone" => #[<JSI::SchemaClasses["23d8#/properties/phone"] Array>
+# #{<JSI::SchemaClasses["23d8#/properties/phone/items"] Hash>
+# "number" => #[<JSI::SchemaClasses["23d8#/properties/phone/items/properties/number"] Array> 5, 5, 5]
# }
# ]
# }
bad.phone.fully_validate
-# => ["The property '#/0/number' of type array did not match the following type: string in schema 1f97"]
+# => ["The property '#/0/number' of type array did not match the following type: string in schema 23d8"]
```
These validations are done by the [`json-schema` gem](https://github.com/ruby-json-schema/json-schema) - JSI does not do validations on its own.
Since the underlying instance is a ruby hash (json object), we can use it like a hash with #[] or, say, #transform_values:
@@ -99,15 +102,15 @@
There's plenty more JSI has to offer, but this should give you a pretty good idea of basic usage.
## Terminology and Concepts
-- JSI::Base is the base class from which other classes representing JSON-Schemas inherit.
-- a JSI class refers to a class representing a schema, a subclass of JSI::Base.
+- `JSI::Base` is the base class for each JSI class representing a JSON Schema.
+- a "JSI class" is a subclass of `JSI::Base` representing a JSON schema.
- "instance" is a term that is significantly overloaded in this space, so documentation will attempt to be clear what kind of instance is meant:
- - a schema instance refers broadly to a data structure that is described by a json-schema.
+ - a schema instance refers broadly to a data structure that is described by a JSON schema.
- a JSI instance (or just "a JSI") is a ruby object instantiating a JSI class. it has a method #instance which contains the underlying data.
-- a schema refers to a json-schema. a JSI::Schema represents such a json-schema. a JSI class allows instantiation of such a schema.
+- a schema refers to a JSON schema. a `JSI::Schema` represents such a schema. a JSI class allows instantiation of a schema as a JSI instance.
## JSI classes
A JSI class (that is, subclass of JSI::Base) is a starting point but obviously you want your own methods, so you reopen the class as you would any other. referring back to the Example section above, we reopen the Contact class: