Flatten modular RAML into single file



We use getsandbox for our initial API designs, using their functionality for mocking stateful behaviour rather than just using canned responses.

Getsandbox supports RAML, although as mentioned in the link, the RAML file used during the sandbox creation must be a single file, with no includes

Using the API Designer, we’ve created modular RAML, using libraries, types and traits to avoid repetition as makes sense. However, this causes issues when working with other tools, which more often than not want a single file to work with. I can see there’s a project node-flat-raml that can assist with this - is this the only way to flatten a modular RAML file into a single file?

Are there any other recommended ways of achieving the same? Anything in the platform itself that could achieve this?



MH it’s strange that you are getting problems with not having a single flattened file. Can you elaborate a little bit more where you see those issues?

I haven’t seen something like that yet, but the new API Modeling Framework (AMF) that we introduced two weeks ago as an alpha version will do that. It introduces two different models: document and domain. The document model is what you have today, a modular RAML document; and the domain is what you are looking for. Again, the AMF is currently in alpha since there are missing features from the specification but we are working to close the gaps asap.


GetSandbox is where we’re seeing the issue (as per http://blog.getsandbox.com/2015/05/20/raml/) - it expects a single RAML document in order to import it and create your sandbox based on the specification. Import fails when the document is broken into modular sub-files.

AMF looks interesting, I’ll have a look into that to see if it helps our workflow.


Hi Dylan,

You may want to look at HiveMind described here:


This is a UI based approach to the problem you have. Basically it allows you to construct object graphs (ie set of name/value pairs with nesting and arrays)…you can then convert that graph to specific formats (JSON,YAML,XML,HCON…etc)…If you think about it, your API description is just an object graph and you use the syntax of these formats (YAML in this case) to specify the graph. What HiveMind does is bypass the syntax based approach and just allow you to construct the graph directly, then you can convert it back to a specific format for software to consume…You can modularize and recombine the graph however you want.

To try it, you can login to the demo instance described in the link above with: developer/developer.

I am the developer and I am happy to answer questions.


Hi @christian_vogel, is there any working RAML 1.0 flattening tool? AMF is currently deprecated and the other tools mentioned in this thread are either 3 years old or the links are dead.

My client has asked me to publish using OAS3 and since oas-raml-converter crashes converting my projects I am looking for third party converters. However most of the only support single file RAMLs.



@rojocapo: there is a tool called datatype-expansion that helps expand RAML datatypes.

Unfortunately, the newest version of AMF is not public yet in part due to the fact that it’s not yet documented but that will for sure be the best way to go when it is available.

Have you filed an issue on oas-raml-converter? If not, that’s what I would do. Keep me posted and I can help escalate the issue if needed.


@jstoiko issue opened.

Reading the currently open issues I feel like I am reliving raml2html from 2 years ago, but with much less support. At least Kevin Renskers would respond to the issue instead of deliberately ignore major issues. I can’t believe this is an official Mulesoft tools, so half baked.