jtd 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 146b3d6415c65ecceea66782e16e722f212c3999f6061cff3c16e167b12f2cec
-  data.tar.gz: 7acf1d589643b11afd706b1353ccd3bb0a8fc69e652f6d08f16389c53592a580
+  metadata.gz: a8db19fa99563fc87cf94665d369a2ab000da1ea9b629c468476f40388587c66
+  data.tar.gz: 59f1124d84474309f31e17caf56a8f6cec5226a2bb842896a3777c471d67642a
 SHA512:
-  metadata.gz: a6272fba6cde2376c0073d4ff0535fa5fc5e214b3581f046ea89092bf1eaf6da9d388bffedaf6a9c714c88f119265a2c2b478b65b749cc79a295c54b2b272456
-  data.tar.gz: 78dc808e525698104a1a274f15a2d023e22d563e5a92864b154d1176d90606a0466e8ab70bf9bf0931608d77ba6b3574e834436f540128b47a84d8120b04e2a1
+  metadata.gz: 14198dced04d5adb6ea790e436291214e9541e4a8641cc86029073401ea8047f0b4487b18821f5e13e347051d9c479d6ae0ca73c40bf62d58c9250cdc928d6df
+  data.tar.gz: 6cb2e3273377f2fa4031db499c2679917fce041eab536913487661d3ab681f053dd84a9f561a11783890852a4c8a7e2b58b0761d7bb9d3aab7c5b21c5a01f290

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jtd (0.1.4)
+    jtd (0.1.5)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1 +1,184 @@
-# jtd: JSON Validation for Ruby
+# jtd: JSON Validation for Python
+
+[![Gem](https://img.shields.io/gem/v/jtd)](https://rubygems.org/gems/jtd)
+
+`jtd` is a Ruby implementation of [JSON Type Definition][jtd], a schema language
+for JSON. `jtd` primarily gives you two things:
+
+1. Validating input data against JSON Typedef schemas.
+2. A Ruby representation of JSON Typedef schemas.
+
+With this package, you can add JSON Typedef-powered validation to your
+application, or you can build your own tooling on top of JSON Type Definition.
+
+## Installation
+
+You can install this package with `gem`:
+
+```bash
+gem install jtd
+```
+
+## Documentation
+
+Detailed API documentation is available online at:
+
+https://rubydoc.info/gems/jtd/JTD
+
+For more high-level documentation about JSON Typedef in general, or JSON Typedef
+in combination with Python in particular, see:
+
+* [The JSON Typedef Website][jtd]
+* ["Validating JSON in Ruby with JSON Typedef"][jtd-ruby-validation]
+
+## Basic Usage
+
+> For a more detailed tutorial and guidance on how to integrate `jtd` in your
+> application, see ["Validating JSON in Ruby with JSON
+> Typedef"][jtd-ruby-validation] in the JSON Typedef docs.
+
+Here's an example of how you can use this package to validate JSON data against
+a JSON Typedef schema:
+
+```ruby
+require 'jtd'
+
+schema = JTD::Schema.from_hash({
+    'properties' => {
+        'name' => { 'type' => 'string' },
+        'age' => { 'type' => 'uint32' },
+        'phones' => {
+            'elements' => {
+                'type' => 'string'
+            }
+        }
+    }
+})
+
+# JTD::validate returns an array of validation errors. If there were no problems
+# with the input, it returns an empty array.
+
+# Outputs: []
+p JTD::validate(schema, {
+  'name' => 'John Doe',
+  'age' => 43,
+  'phones' => ['+44 1234567', '+44 2345678'],
+})
+
+# This next input has three problems with it:
+#
+# 1. It's missing "name", which is a required property.
+# 2. "age" is a string, but it should be an integer.
+# 3. "phones[1]" is a number, but it should be a string.
+#
+# Each of those errors corresponds to one of the errors returned by validate.
+
+# Outputs:
+#
+# [
+#   #<struct JTD::ValidationError
+#     instance_path=[],
+#     schema_path=["properties", "name"]
+#   >,
+#   #<struct JTD::ValidationError
+#     instance_path=["age"],
+#     schema_path=["properties", "age", "type"]
+#   >,
+#   #<struct JTD::ValidationError
+#     instance_path=["phones", "1"],
+#     schema_path=["properties", "phones", "elements", "type"]
+#   >
+# ]
+p JTD::validate(schema, {
+  'age' => '43',
+  'phones' => ['+44 1234567', 442345678],
+})
+```
+
+## Advanced Usage: Limiting Errors Returned
+
+By default, `JTD::validate` returns every error it finds. If you just care about
+whether there are any errors at all, or if you can't show more than some number
+of errors, then you can get better performance out of `JTD::validate` using the
+`max_errors` option.
+
+For example, taking the same example from before, but limiting it to 1 error, we
+get:
+
+```python
+# Outputs:
+#
+# [#<struct JTD::ValidationError instance_path=[], schema_path=["properties", "name"]>]
+options = JTD::ValidationOptions.new(max_errors: 1)
+p JTD::validate(schema, {
+  'age' => '43',
+  'phones' => ['+44 1234567', 442345678],
+}, options)
+```
+
+## Advanced Usage: Handling Untrusted Schemas
+
+If you want to run `jtd` against a schema that you don't trust, then you should:
+
+1. Ensure the schema is well-formed, using the `#verify` method on
+   `JTD::Schema`. That will check things like making sure all `ref`s have
+   corresponding definitions.
+
+2. Call `JTD::validate` with the `max_depth` option. JSON Typedef lets you write
+   recursive schemas -- if you're evaluating against untrusted schemas, you
+   might go into an infinite loop when evaluating against a malicious input,
+   such as this one:
+
+   ```json
+   {
+     "ref": "loop",
+     "definitions": {
+       "loop": {
+         "ref": "loop"
+       }
+     }
+   }
+   ```
+
+   The `max_depth` option tells `JTD::validate` how many `ref`s to follow
+   recursively before giving up and raising `JTD::MaxDepthExceededError`.
+
+Here's an example of how you can use `jtd` to evaluate data against an untrusted
+schema:
+
+```ruby
+require 'jtd'
+
+# validate_untrusted returns true if `data` satisfies `schema`, and false if it
+# does not. Throws an error if `schema` is invalid, or if validation goes in an
+# infinite loop.
+def validate_untrusted(schema, data)
+  schema.verify()
+
+  # You should tune max_depth to be high enough that most legitimate schemas
+  # evaluate without errors, but low enough that an attacker cannot cause a
+  # denial of service attack.
+  options = JTD::ValidationOptions.new(max_depth: 32)
+  JTD::validate(schema, data, options).empty?
+end
+
+# Returns true
+validate_untrusted(JTD::Schema.from_hash({ 'type' => 'string' }), 'foo')
+
+# Returns false
+validate_untrusted(JTD::Schema.from_hash({ 'type' => 'string' }), nil)
+
+# Raises ArgumentError (invalid type: nonsense)
+validate_untrusted(JTD::Schema.from_hash({ 'type' => 'nonsense' }), 'foo')
+
+# Raises JTD::MaxDepthExceededError (max depth exceeded during JTD::validate)
+validate_untrusted(JTD::Schema.from_hash({
+  'definitions' => {
+    'loop' => { 'ref' => 'loop' },
+  },
+  'ref' => 'loop',
+}), nil)
+```
+
+[jtd]: https://jsontypedef.com
+[jtd-ruby-validation]: https://jsontypedef.com/docs/ruby/validation

data/lib/jtd/version.rb

@@ -1,4 +1,4 @@
 module JTD
   # The version of the +jtd+ gem you are using.
-  VERSION = '0.1.4'
+  VERSION = '0.1.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jtd
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Ulysse Carion