Loads OAS2 or OAS3 scheme from YAML/JSON file(s), and converts it to OAS3 standard.

Sponsored by Evil Martians

Gem Version Build Status Inline docs


Add this line to your application's Gemfile:

gem 'open_api-loader'

And then execute:

$ bundle

Or install it yourself as:

$ gem install open_api-loader


require "open_api/loader" "path_to/source.yaml"
# => { "openapi" => "3.0.0", ... }

It takes a filename of the specification (it should be in YAML or JSON), and returns a nested hash.

The loader transforms the source in several ways:

  • reads the data,
  • collects all the reference objects both local and remote (like ./models.yaml#/Pet or, and includes them into the specification,
  • converts the specification from OAS2 into OAS3 standard,
  • removes the components because all links to its definitions are dereferenced,
  • denormalizes servers, security, and parameters by moving shared definitions from both root and path items right into the corresponding operations,
  • substitutes server variables into urls to provide "flat" servers list.

You can skip the last 3 steps using option: "path_to/source.yaml", denormalize: false

Development and Contributing

Bug reports and pull requests are welcome on GitHub at

After checking out the repo, run bin/setup to install dependencies.

Before adding a PR, please run rake to run tests, style and documentation linters. You can also run bin/console for an interactive prompt pry that will allow you to experiment.


  1. Check whether a reference objects contain cycles
  2. Add script to run the loader from shell and save results to YAML/JSON file
  $ open_api load -s source.yaml -o output.yaml -d


The gem is available as open source under the terms of the MIT License.