Identify best RAML parsing option

[oscaralanpierce]

Summary

Since the raml-rb gem does not support the entire RAML specification, we need to decide whether this is still the best RAML parsing option for Rambo. After some discussion under pull request #23, I did a spike this morning switching to raml_ruby, only to find it supports only RAML 0.8, which is a deal-breaker given that all of the projects I need to test with Rambo use RAML 1.0.

In choosing which option to use, we need to consider the following:

• Support for RAML 1.0
• Secondarily, support for RAML 0.8
• Completeness of RAML parsing functionality
• Size of project, number of maintainers/contributors, frequency of commits
• Quality of documentation
• Possibly other criteria (please comment below with any that come to mind)

Expected Behavior

At minimum, Rambo needs full support for RAML 1.0, and ideally, it should support RAML 0.8 as well. This includes support for include.

Possible Solution

There are 3 RAML parsing gems that I'm aware of:

• raml-rb
• raml_ruby
• raml_parser

raml-rb

This is the only one of the three options that supports RAML 1.0 at all. Since I'm a maintainer, it's also relatively easy to add functionality as needed. On the downside, the parser is less complete than the other gems, and there are only two maintainers (including me).

raml_ruby

The raml_ruby parser is fairly complete, but does not support RAML 1.0 and does not support include, which is used extensively in our apps. We would need to add this support to the gem before it would be suitable for use in this project. The documentation is minimal and out of date.

raml_parser

This one I implemented briefly before switching to raml_ruby. It does not appear to handle RAML 1.0, and the last commit was in September 2015. It also has very limited documentation.

Context

Because development of this project is supported by @projectdx, we have defined an MVP around their needs. Consequently, it is necessary for us to support RAML 1.0 and include due to the requirements of the specified systems to be tested. (Again, sorry, OSS contributors, but the repos are private 😞.)

[oscaralanpierce]

@zeisler - think this is something you could help with?

[zeisler]

@danascheider I don't think repayment_estimatr uses any 1.0 features.

http://raml.org/developers/whats-new-raml-10

Breaking changes

https://github.com/raml-org/raml-spec/wiki/Breaking-Changes

Not the long term solution, but if it works repayment_estimatr could be changes to use RAML 0.8

[oscaralanpierce]

Cool, thanks!

[oscaralanpierce]

Downgrading this to low priority since I seem to be making this functionality work. Also assigning to myself since zeisler has been assigned to another project.