schema-test 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 260d4172bc31999c0e327e3ac45428d042b7977bbad68c5b5d77e9eadba6765d
+  data.tar.gz: ff9ff5f54b598950d61b955750473007bd66afafeaa0d81cbb937a877c460c36
+SHA512:
+  metadata.gz: 6592e1e7f3b5d0f6ddb2fdfe5099d87de1e2674d3abb5e7a3e3268537ff86ff0bccdf933c4fdf563e581c54b5ec11025db9b16fa05477cf3c24783813e7667a2
+  data.tar.gz: 9d295a52695e323afe73236219694d4e51ea14754e323464f48328bf9421362626bc522ac286211e91a207858b6de25573272949c4e1917f9ae68e24b024f561

data/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at james@lazyatom.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in api-schema.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,50 @@
+PATH
+  remote: .
+  specs:
+    schema-test (0.1.0)
+      json
+      json_schemer
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    byebug (11.1.3)
+    diff-lcs (1.4.4)
+    ecma-re-validator (0.3.0)
+      regexp_parser (~> 2.0)
+    hana (1.3.7)
+    json (2.5.1)
+    json_schemer (0.2.18)
+      ecma-re-validator (~> 0.3)
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      uri_template (~> 0.7)
+    rake (10.5.0)
+    regexp_parser (2.1.1)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    uri_template (0.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2)
+  byebug
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  schema-test!
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 James Adam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,209 @@
+# SchemaTest
+
+This gem provides a convenient and flexible way for specifying and testing schema definitions for JSON API response. The mean features are:
+
+* A simple Ruby-based DSL for capturing JSON objects, including property names, types, and metadata like descriptions
+* Simple ways to _version_ those schemas, and specify new versions efficiently
+* Mechanisms to evaluate a given JSON blob against a schema to verify it matches
+* Mechanisms to write tests for multiple API versions that strike a good balance between efficiency of specifiation vs avoiding unintentional impacts to endpoints. I'll explain that later.
+
+## How & why
+
+This gem provides a way to define JSON Schema objects using a simple Ruby DSL, in a way that allows other schemas to be easily composed of existing ones:
+
+``` ruby
+
+# Define a simple user schema
+SchemaTest.define :user do
+  id
+  string :name
+  url :avatar_url
+end
+
+# Define a new comment schema
+SchemaTest.define :comment do
+  string :body
+
+  # re-use the user schema, but give the object a different name
+  object :user, as: :author
+end
+```
+
+This lets you minimise duplication between your schema definitions in a convenient way. And we can then use the generated JSON-Schema data (see below) to validate our app's generated responses against this.
+
+But JSON-Schema already lets you compose schemas, right? What's the point of this?
+
+### API versioning
+
+Let's imagine we have some test for our comments API output, something like (pseudocode):
+
+``` ruby
+get :comment
+
+assert_schema_matches response.body, schema_for(:comment)
+```
+
+Then, some time later, we create a new version of our API, and some of the serialised objects have changes - new fields, removed fields, fields with different meanings, and so on.
+
+We might change our schema definition:
+
+``` ruby
+SchemaTest.define :user do
+  id
+  string :first_name
+  string :last_name
+  url :avatar_url
+end
+```
+
+... and then we change our user serialiser logic, and write a test for the new API version, and everything passes. Great, right?
+
+No. Not great. Not great because while yes, the tests pass, we've actually _changed_ the output of the previous API version endpoints accidentally, and there will be nothing in the commit that suggests it.
+
+So instead, what we can do is _version_ our schema definitions:
+
+``` ruby
+SchemaTest.define :user, version: 1 do
+  id
+  string :name
+  url :avatar_url
+end
+
+SchemaTest.define :user, version: 2 do
+  id
+  string :first_name
+  string :last_name
+  url :avatar_url
+end
+```
+
+And then use the correct version in each of our tests:
+
+``` ruby
+# v1 comment test
+get :comment
+
+assert_schema_validates response.body, schema_for(:comment, version: 1)
+
+# v2 comment test
+get :comment
+
+assert_schema_validates response.body, schema_for(:comment, version: 2)
+```
+
+This way we can now be confident that our version 1 tests are actually verifying the genuine version 1 schema, and likewise for the version 2 tests.
+
+But there's another hole that we're about to step in...
+
+### Nested schemas
+
+To be written
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'schema-test'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install schema-test
+
+## Usage
+
+Once the gem is in your bundle, add it to your tests:
+
+### Minitest with Rails
+
+At or near the top of `test_helper.rb` add the following:
+
+``` ruby
+require 'schema_test/minitest'
+SchemaTest.configure do |config|
+  config.domain = 'mydomain.com'
+  config.definition_paths << Rails.root.join('test', 'schema_definitions')
+end
+SchemaTest.load!
+```
+
+Within `class ActiveSupport::TestCase` in the same file, add 
+
+``` ruby
+include SchemaTest::Minitest
+```
+
+Create the directory `test/schema_definitions`; within this directory (and any subdirectories) you can start to define your schemas. A simple one would be:
+
+``` ruby
+SchemaTest.define :user, version: 1 do
+  id
+  string :name
+  url :avatar_url
+  integer :follower_count
+end
+```
+
+You can then make assertions using this schema in your tests. For example, if you have a controller action that responds with JSON version of a user, you might write a test like this:
+
+``` ruby
+test 'JSON returned matches schema' do
+  user = User.first
+  get :show, params: { id: user.id }
+
+  json = JSON.parse(response.body)
+  assert_valid_json_for_schema(json, :user, version: 1)
+end
+```
+
+When you run this test, this gem will convert the schema definition you've given into JSON Schema, and then dynamically rewrite your test to verify against the fully-expanded schema. After you run the test, if you reload the file, you should see something like this:
+
+``` ruby
+test 'JSON returned matches schema' do
+  user = User.first
+  get :show, params: { id: user.id }
+
+  json = JSON.parse(response.body)
+  assert_valid_json_for_schema( # EXPANDED
+    json, 
+    {:version=>1,
+      :schema=>
+      {"$schema"=>"http://json-schema.org/draft-07/schema#",
+        "$id"=>"http://mydomain/v1/user.json",
+        "title"=>"user",
+        "type"=>"object",
+        "properties"=>
+        {"id"=>{"type"=>"integer"},
+          "name"=>{"type"=>"string"},
+          "avatar_url"=>{"type"=>"string", "format"=>"uri"},
+          "follower_count"=>{"type"=>"integer}},
+        "required"=>["id", "name", "avatar_url", "follower_count"],
+        "additionalProperties"=>false}}
+  ) # END EXPANDED
+end
+```
+Keeping the full schema directly in the tests means that it is **impossible** for us to accidentally impact any API endpoints with a distant schema change without also producing some change in the test files for those endpoints. That is the main benefit that this library tries to acheive.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/lazyatom/schema-test. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the SchemaTest project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/lazyatom/schema-test/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "api/schema"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/schema_test/collection.rb

@@ -0,0 +1,23 @@
+require 'schema_test/property'
+
+module SchemaTest
+  class Collection < SchemaTest::Property::Object
+    def initialize(name, of_name, version: nil, description: nil)
+      super(name, version: version, description: description)
+      @item_type = lookup_object(of_name, version)
+      SchemaTest::Definition.register(self)
+    end
+
+    def as_json_schema(domain: SchemaTest.configuration.domain)
+      id_part = version ? "v#{version}/#{name}" : name
+      {
+        '$schema' => SchemaTest::SCHEMA_VERSION,
+        '$id' => "http://#{domain}/#{id_part}.json",
+        'title' => name.to_s,
+        'type' => 'array',
+        'items' => @item_type.as_json_schema(false),
+        'minItems' => 1
+      }
+    end
+  end
+end

data/lib/schema_test/configuration.rb

@@ -0,0 +1,17 @@
+module SchemaTest
+  class Configuration
+    # The domain is used to contstruct the `$id` part of the generated
+    # JSON-Schema definitions. This can be set to anything you like really.
+    attr_accessor :domain
+
+    # This should be an array or one or more paths. All ruby files under these
+    # paths will all be loaded when `SchemaTest.setup!` is called. You can nest
+    # files in as many subdirectories are you like.
+    attr_accessor :definition_paths
+
+    def initialize
+      @domain = 'example.com'
+      @definition_paths = []
+    end
+  end
+end

data/lib/schema_test/definition.rb

@@ -0,0 +1,59 @@
+require 'schema_test/property'
+
+module SchemaTest
+  class Definition < SchemaTest::Property::Object
+    def self.reset!
+      @definitions = nil
+    end
+
+    def self.register(definition)
+      @definitions ||= {}
+      @definitions[definition.name] ||= {}
+      @definitions[definition.name][definition.version] = definition
+    end
+
+    def self.find(name, version)
+      (@definitions || {}).dig(name, version)
+    end
+
+    def self.find!(name, version)
+      found = find(name, version)
+      raise "Could not find schema for #{name.inspect} (version: #{version.inspect})" unless found
+      found
+    end
+
+    def initialize(*args)
+      super
+      self.class.register(self)
+    end
+
+    def type(name, version=nil)
+      lookup_object(name, version || @version)
+    end
+
+    def optional(object)
+      object.optional!
+    end
+
+    def as_structure(_=nil)
+      hashes, others = @properties.values.map(&:as_structure).partition { |x| x.is_a?(Hash) }
+      others + [hashes.inject(&:merge)].compact
+    end
+
+    def as_json_schema(domain: SchemaTest.configuration.domain)
+      id_part = version ? "v#{version}/#{name}" : name
+      {
+        '$schema' => SchemaTest::SCHEMA_VERSION,
+        '$id' => "http://#{domain}/#{id_part}.json",
+        'title' => name.to_s
+      }.merge(super(false))
+    end
+
+    def based_on(name, version: self.version)
+      other_version = self.class.find(name, version)
+      other_version.properties.values.each do |property|
+        define_property(property.dup)
+      end
+    end
+  end
+end

data/lib/schema_test/minitest.rb

@@ -0,0 +1,58 @@
+require 'schema_test'
+
+module SchemaTest
+  module Minitest
+    def assert_valid_json_for_schema(json, name, version:, schema: nil)
+      install_assert_api_expansion_hook
+
+      definition = SchemaTest::Definition.find(name, version)
+      raise "Unknown definition #{name}, version: #{version}" unless definition.present?
+
+      expected_schema = definition.as_json_schema
+
+      if schema != expected_schema
+        if ENV['CI']
+          flunk "Outdated API schema assertion at #{caller[0]}"
+        else
+          queue_write_expanded_assert_api_call(caller[0], __method__, name, version, expected_schema)
+        end
+      end
+
+      assert_json_schema_validates_against(json, expected_schema)
+    end
+
+    def assert_json_schema_validates_against(json, schema)
+      errors = SchemaTest.validate_json(json, schema)
+      assert errors.empty?, "JSON did not pass schema:\n#{errors.join("\n")}"
+    end
+
+    private
+
+    @@__api_schema_calls_for_expansion = {}
+    @@__api_schema_expansion_hook_installed = false
+
+    def queue_write_expanded_assert_api_call(call_site, method, name, version, expected_schema)
+      file, line = call_site.split(':')
+      line_index = line.to_i.pred
+
+      @@__api_schema_calls_for_expansion[file] ||= []
+      @@__api_schema_calls_for_expansion[file] << [line_index, method, name, version, expected_schema]
+    end
+
+    def install_assert_api_expansion_hook
+      return if @@__api_schema_expansion_hook_installed
+      at_exit { expand_assert_api_calls }
+      @@__api_schema_expansion_hook_installed = true
+    end
+
+    def expand_assert_api_calls
+     @@__api_schema_calls_for_expansion.each do |file, line_indexes_with_schemas|
+       original_contents = File.read(file)
+       rewriter = SchemaTest::Rewriter.new(original_contents, line_indexes_with_schemas)
+       new_contents = rewriter.output
+       raise "Error rewriting file" if new_contents.blank?
+       File.open(file, 'w') { |f| f.puts new_contents }
+     end
+    end
+  end
+end

data/lib/schema_test/property.rb

@@ -0,0 +1,272 @@
+module SchemaTest
+  class Property
+    attr_reader :name, :type, :description, :optional
+
+    def initialize(name, type, description=nil)
+      @name = name
+      @type = type
+      @description = description
+      @optional = false
+    end
+
+    def as_structure(_=nil)
+      if @optional
+        { name => nil }
+      else
+        name
+      end
+    end
+
+    def as_json_schema
+      json_schema = { 'type' => json_schema_type }
+      json_schema['description'] = description if description
+      json_schema['format'] = json_schema_format if json_schema_format
+      { name.to_s => json_schema }
+    end
+
+    def ==(other)
+      name == other.name &&
+        type == other.type &&
+        description == other.description &&
+        optional == other.optional
+    end
+
+    def optional?
+      optional
+    end
+
+    def optional!
+      @optional = true
+    end
+
+    def json_schema_type
+      @type.to_s
+    end
+
+    def json_schema_format
+      nil
+    end
+
+    class Boolean < SchemaTest::Property
+      def initialize(name, description=nil)
+        super(name, :boolean, description)
+      end
+    end
+
+    class Integer < SchemaTest::Property
+      def initialize(name, description=nil)
+        super(name, :integer, description)
+      end
+    end
+
+    class Float < SchemaTest::Property
+      def initialize(name, description=nil)
+        super(name, :float, description)
+      end
+
+      def json_schema_type
+        'number'
+      end
+    end
+
+    class String < SchemaTest::Property
+      def initialize(name, description=nil)
+        super(name, :string, description)
+      end
+    end
+
+    class DateTime < SchemaTest::Property
+      def initialize(name, description=nil)
+        super(name, :datetime, description)
+      end
+
+      def json_schema_type
+        'string'
+      end
+
+      def json_schema_format
+        'date-time'
+      end
+    end
+
+    class Uri < SchemaTest::Property::String
+      def json_schema_format
+        'uri'
+      end
+    end
+
+    class SchemaTest::Property::Object < SchemaTest::Property
+      attr_reader :version
+
+      def initialize(name, description: nil, version: nil, from: nil, properties: nil, &block)
+        @name = name
+        @description = description
+        @version = version
+        @specific_properties = properties
+        @properties = {}
+        @from = from
+        instance_eval(&block) if block_given?
+      end
+
+      def properties
+        resolve
+        @properties
+      end
+
+      def ==(other)
+        super && properties.all? { |name, property| property == other.properties[name] }
+      end
+
+      def resolve
+        if @from
+          @properties.merge!(@from.properties)
+          @from = nil
+        end
+        if @specific_properties
+          @specific_properties.each { |p| define_property(p) }
+          @specific_properties = nil
+        end
+        self
+      end
+
+      SHORTHAND_ATTRIBUTES = {
+        id: :integer,
+        slug: :string,
+        updated_at: :datetime,
+        created_at: :datetime
+      }
+
+      SHORTHAND_ATTRIBUTES.each do |name, type|
+        define_method(name) { send(type, name) }
+      end
+
+      TYPES = {
+        boolean: SchemaTest::Property::Boolean,
+        integer: SchemaTest::Property::Integer,
+        float: SchemaTest::Property::Float,
+        string: SchemaTest::Property::String,
+        datetime: SchemaTest::Property::DateTime,
+        url: SchemaTest::Property::Uri,
+        html: SchemaTest::Property::String
+      }
+
+      TYPES.each do |method_name, type_class|
+        define_method(method_name) do |name, desc: nil|
+          define_property(type_class.new(name, desc))
+        end
+      end
+
+      def array(name, of: nil, desc: nil, &block)
+        define_property(SchemaTest::Property::Array.new(name, of, desc, &block))
+      end
+
+      def object(name, desc: nil, as: name, version: nil, &block)
+        inferred_version = version || @version
+        if block_given?
+          define_property(SchemaTest::Property::Object.new(as, description: desc, version: inferred_version, &block))
+        else
+          define_property(SchemaTest::Property::Object.new(as, description: desc, version: inferred_version, from: lookup_object(name, inferred_version)))
+        end
+      end
+
+      def as_json_schema(include_root=true)
+        property_values = properties.values
+        required_property_names = property_values.reject(&:optional?).map(&:name).map(&:to_s)
+        schema = {
+          'type' => json_schema_type,
+          'properties' => property_values.inject({}) { |a,p| a.merge(p.as_json_schema) },
+          'required' => required_property_names,
+          'additionalProperties' => false
+        }
+        if include_root
+          { name.to_s => schema }
+        else
+          schema
+        end
+      end
+
+      def as_structure(include_root=true)
+        if include_root
+          { name => properties.values.map(&:as_structure) }
+        else
+          properties.values.map(&:as_structure)
+        end
+      end
+
+      def json_schema_type
+        'object'
+      end
+
+      private
+
+      def define_property(attribute)
+        @properties[attribute.name] = attribute
+      end
+
+      def lookup_object(name, version)
+        UnresolvedProperty.new(name, version: version)
+      end
+    end
+
+    class UnresolvedProperty < SchemaTest::Property::Object
+      def resolve
+        SchemaTest::Definition.find!(name, version)
+      end
+
+      def ==(other)
+        resolve == other
+      end
+
+      def properties
+        resolve.properties
+      end
+
+      def as_structure(*args)
+        resolve.as_structure(*args)
+      end
+    end
+
+    class AnonymousObject < SchemaTest::Property::Object
+      def initialize(properties: nil, &block)
+        super(nil, properties: properties, &block)
+      end
+
+      def as_structure(_=nil)
+        super(false)
+      end
+    end
+
+    class Array < SchemaTest::Property
+      attr_reader :item_type
+
+      def initialize(name, of=nil, description=nil, &block)
+        super(name, :array, description)
+        if block_given?
+          @item_type = AnonymousObject.new(&block)
+        else
+          @item_type = of
+        end
+        # @items = { type: @item_type }
+      end
+
+      def ==(other)
+        super && @item_type == other.item_type
+      end
+
+      def as_structure(_=nil)
+        if @item_type.is_a?(SchemaTest::Property)
+          { name => @item_type.as_structure(false) }
+        else
+          { name => [] }
+        end
+      end
+
+      def as_json_schema
+        super.tap do |json_schema|
+          item_schema = @item_type.is_a?(SchemaTest::Property) ? @item_type.as_json_schema(false) : { 'type' => @item_type.to_s }
+          json_schema[name.to_s]['items'] = item_schema
+        end
+      end
+    end
+  end
+end

data/lib/schema_test/rewriter.rb

@@ -0,0 +1,51 @@
+require 'pp'
+
+module SchemaTest
+  OPENING_COMMENT = '# EXPANDED'.freeze
+  CLOSING_COMMENT = '# END EXPANDED'.freeze
+
+  class Rewriter
+    def initialize(contents, line_indexes_with_schemas)
+      @lines = contents.split("\n")
+      @line_indexes_with_schemas = line_indexes_with_schemas
+    end
+
+    def output
+      current_offset = 0
+      line_indexes_with_schemas.sort_by { |(line,_)| line }.each do |index, method, name, version, expected_schema|
+        start_index = index + current_offset
+        if lines[start_index] =~ /#{OPENING_COMMENT}\s*\z/
+          end_index = start_index + lines[start_index..-1].find_index { |line| line =~ /#{CLOSING_COMMENT}\s*\z/ }
+          json_variable_name = lines[start_index + 1].strip.gsub(/,\z/, '')
+        else
+          end_index = start_index
+          json_variable_name = lines[start_index].match(/\(([^,]+)/)[1]
+        end
+        start_indent = lines[start_index].match(/\A(\s*)/)[0].length
+        (end_index - start_index + 1).times { |i| lines.delete_at(start_index) }
+
+        output = StringIO.new
+        PP.pp([name, version: version, schema: expected_schema], output)
+        output.rewind
+        expanded_schema_lines = output.read.strip.gsub(/\A\[/, '').gsub(/\]\z/, '').split("\n")
+        expanded_schema_lines.unshift(json_variable_name + ',')
+
+        method_string = [
+          (' ' * start_indent) + method.to_s + "( #{OPENING_COMMENT}",
+          *expanded_schema_lines.map { |line| (' ' * (start_indent + 2)) + line },
+          (' ' * start_indent) + ") #{CLOSING_COMMENT}"
+        ]
+
+        method_string.reverse.each { |line| lines.insert(start_index, line) }
+
+        current_offset += method_string.count - 1
+      end
+
+      lines.compact.join("\n") + "\n"
+    end
+
+    private
+
+    attr_reader :lines, :line_indexes_with_schemas
+  end
+end

data/lib/schema_test/test_helper.rb

@@ -0,0 +1,59 @@
+module SchemaTest
+  class TestHelper
+    def assert_api_schema(name, version:, structure: nil)
+      install_asset_api_expansion_hook
+
+      definition = ApiSchema::Definition.find(name, version)
+      raise "Unknown definition #{name}, version: #{version}" unless definition.present?
+
+      expected_structure = definition.as_structure
+
+      if structure != expected_structure
+        if ENV['CI']
+          flunk "Outdated API schema assertion at #{caller[0]}"
+        else
+          queue_write_expanded_assert_api_call(caller[0], __method__, name, version, expected_structure)
+        end
+      end
+
+      assert_json_response_structure(*expected_structure)
+    end
+
+    private
+
+    @@__api_schema_calls_for_expansion = {}
+    @@__api_schema_expansion_hook_installed = false
+
+    def queue_write_expanded_assert_api_call(call_site, method, name, version, expected_structure)
+      file, line = call_site.split(':')
+      line_index = line.to_i.pred
+
+      @@__api_schema_calls_for_expansion[file] ||= []
+      @@__api_schema_calls_for_expansion[file] << [line_index, method, name, version, expected_structure]
+    end
+
+    def install_asset_api_expansion_hook
+      return if @@__api_schema_expansion_hook_installed
+      at_exit { expand_assert_api_calls }
+      @@__api_schema_expansion_hook_installed = true
+    end
+
+    def expand_assert_api_calls
+      @@__api_schema_calls_for_expansion.each do |file, line_indexes_with_structures|
+        rewriter = SchemaTest::Rewriter.new(File.read(file), line_indexes_with_structures)
+        File.open(file, 'w') { f.puts rewriter.output }
+      end
+    end
+  end
+end
+
+if const_defined?(Rails)
+  ActionController::TestCase.send(:include, SchemaTest::TestHelper)
+  ActionDispatch::IntegrationTest.send(:include, SchemaTest::TestHelper)
+
+  SchemaTest.definition_paths << Rails.root.join('test', 'schema_definitions', '**', '*.rb')
+  SchemaTest.definition_paths << Rails.root.join('spec', 'schema_definitions', '**', '*.rb')
+
+  SchemaTest.load_definitions
+end
+

data/lib/schema_test/validator.rb

@@ -0,0 +1,51 @@
+require 'json'
+require 'json_schemer'
+require 'shellwords'
+
+module SchemaTest
+  class Validator
+    def initialize(json_or_data)
+      @data = case json_or_data
+              when Hash, Array
+                JSON.parse(json_or_data.to_json)
+              when String
+                JSON.parse(json_or_data)
+              else
+                json_or_data
+              end
+    end
+
+    def validate_using_definition(definition)
+      validate_using_json_schema(definition.as_json_schema)
+    end
+
+    def validate_using_json_schema(schema)
+      json_schema = JSONSchemer.schema(schema)
+      errors = json_schema.validate(@data).to_a
+      convert_json_schemer_errors(errors)
+    end
+
+    private
+
+    def convert_json_schemer_errors(errors)
+      errors.map { |error| convert_json_schemer_error(error) }
+    end
+
+    def convert_json_schemer_error(error)
+      if error['schema_pointer'] == '/additionalProperties'
+        additional_key = error['data_pointer']
+        "object contains the extra key: #{additional_key}"
+      else
+        message = case error['type']
+                  when 'format'
+                    "format should be #{error['schema']['format']}"
+                  when 'required'
+                    "missing some required attributes"
+                  else
+                    "type should be #{error['type']}"
+                  end
+        "value at #{error['data_pointer']} (#{error['data'].inspect}) failed validation: #{message}"
+      end
+    end
+  end
+end

data/lib/schema_test/version.rb

@@ -0,0 +1,3 @@
+module SchemaTest
+  VERSION = "0.1.0"
+end

data/lib/schema_test.rb

@@ -0,0 +1,69 @@
+require 'schema_test/version'
+require 'schema_test/rewriter'
+require 'schema_test/definition'
+require 'schema_test/collection'
+require 'schema_test/validator'
+require 'schema_test/configuration'
+
+module SchemaTest
+  class Error < StandardError; end
+
+  SCHEMA_VERSION = "http://json-schema.org/draft-07/schema#"
+
+  class << self
+    def reset!
+      @configuration = nil
+      SchemaTest::Definition.reset!
+    end
+
+    # Yields a configuration object, which can be used to set up
+    # various aspects of the library
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= SchemaTest::Configuration.new
+    end
+
+    # Recursively loads all files under the `definition_paths` directories
+    def load!
+      load_definitions
+    end
+
+    # Define a new schema
+    def define(name, collection: nil, **attributes, &block)
+      definition = SchemaTest::Definition.new(name, attributes, &block)
+      if collection
+        collection(collection, of: name, version: attributes[:version])
+      end
+      definition
+    end
+
+    # Explicitly define a new schema collection (an array of other schema
+    # objects)
+    def collection(name, of:, **attributes)
+      SchemaTest::Collection.new(name, of, attributes)
+    end
+
+    # Validate some JSON data against a schema or schema definition
+    def validate_json(json, definition_or_schema)
+      validator = SchemaTest::Validator.new(json)
+      if definition_or_schema.is_a?(SchemaTest::Property::Object)
+        validator.validate_using_definition(definition_or_schema)
+      else
+        validator.validate_using_json_schema(definition_or_schema)
+      end
+    end
+
+    private
+
+    def load_definitions
+      globbed_paths = configuration.definition_paths.map { |path| path.join('**', '*.rb') }
+      Dir[globbed_paths.join(',')].each do |schema_file|
+        require schema_file
+      end
+    end
+
+  end
+end

data/schema-test.gemspec

@@ -0,0 +1,45 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "schema_test/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "schema-test"
+  spec.version       = SchemaTest::VERSION
+  spec.authors       = ["James Adam"]
+  spec.email         = ["james@lazyatom.com"]
+
+  spec.summary       = %q{API testing against declarative schemas}
+  spec.description   = %q{}
+  spec.homepage      = "https://github.com/lazyatom/schema-test"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/lazyatom/schema-test"
+    spec.metadata["changelog_uri"] = "https://github.com/lazyatom/schema-test"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'json'
+  spec.add_dependency 'json_schemer'
+
+  spec.add_development_dependency "bundler", "~> 2"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "byebug"
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: schema-test
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- James Adam
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-09-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ''
+email:
+- james@lazyatom.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/tests.yml"
+- ".gitignore"
+- ".rspec"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/schema_test.rb
+- lib/schema_test/collection.rb
+- lib/schema_test/configuration.rb
+- lib/schema_test/definition.rb
+- lib/schema_test/minitest.rb
+- lib/schema_test/property.rb
+- lib/schema_test/rewriter.rb
+- lib/schema_test/test_helper.rb
+- lib/schema_test/validator.rb
+- lib/schema_test/version.rb
+- schema-test.gemspec
+homepage: https://github.com/lazyatom/schema-test
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/lazyatom/schema-test
+  source_code_uri: https://github.com/lazyatom/schema-test
+  changelog_uri: https://github.com/lazyatom/schema-test
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: API testing against declarative schemas
+test_files: []