Develop a module for RAML data types <> JSON schema

[sichvoge]

Introducing RAML data types in RAML 1.0 was, and still is, a huge success in the RAML community. As this is not a new way to model data, but planned to accompany existing schemas by leveraging an easy to write and human readable language. To achieve that, someone must be able to easily convert a RAML data type into a JSON schema that he can use for his / her existing tool chain, or the other way around from JSON schema to RAML data types.

Our strategy is to develop the conversation between these two in phases.

Phase 1

In the first phase we will use an in-memory canonical form that gets generated from a set of RAML data types as input, to convert that into a single JSON schema. We will use a previous developed module that takes a set of RAML data types and the data type name you want to have a JSON schema to produce a single canonical form of that type which we can easily convert almost 1:1 into JSON. Almost, since there are a couple of things that needs to be mapped differently. That allows us to quickly evaluate the conversion process and gather feedback from our community.

The JSON schema > RAML data types will be a bit different. We plan to preserve all information + definitions that are separated and convert that directly into a RAML data type.

Planned release: 26th September (see milestone v1.0)

Phase 2

Probably, after collecting some feedback, we will change RAM data types > JSON schema to preserve more information including individual types without creating a canonical form first. Thats a lot harder since we have inline unions and inheritance that are currently not 1:1 in JSON schema.

Planned release: TBD

[sichvoge]

There seems to be some confusion about phase 1 around inheritance and if that is supported. To clarify, the input, a set of RAML data types, can have any structure (inheritance, unions, etc.) and the output is a single JSON schema.

[Relequestual]

Part of the team at json-schema-org. Would love to help out with this where possible, giving feedback etc.

[jstoiko]

That would be awesome @Relequestual! Thanks for offering.

A good way to see where we're at with the project is to run the integration tests.

$ node ./test/integration/js2dt_integration_test.js 

and

$ node ./test/integration/dt2js_integration_test.js

The tests that are failing are what needs work, each FAILing test will also output the errors returned by either the RAML or the JSON Schema (ajv) parser.

There are also several examples in that test/ folder but I'm sure we are not covering ALL cases so you're more than welcome to suggest more examples.

[Relequestual]

Great. May be worth adding that information to the readme for those who want to help out. I won't have the time this month to lend a hand, but next month hopefully will look better.

[jstoiko]

Good idea. Will should put a contributing guidelines document together and add this to it.

[sichvoge]

@Relequestual, your support is definitely welcome! If you'd like to help more than just giving feedback at any point, please let me know and I am happy to add you as a contributor.

I believe that RAML data types and JSON schema perfectly complements each other, and this was our original intention anyways. Let me know if you have any questions.

@jstoiko maybe we can reuse https://github.com/raml-org/raml-tutorial#contribution?

[sichvoge]

Also @Relequestual, any feedback on RAML data types itself is very much appreciated as well ;)

[Relequestual]

@sichvoge AHHH you're part of the RAML org, cool. I think it's great that we keep in touch with each other. I see JSON Schema and RAML as very similar in many respects. Also, I like RAML much more than ahem "Open API" aka Swagger.

[Relequestual]

@sichvoge Equally, if you have feedback about the recent changes with JSON Schema, that would be super awesome. We're getting closer and closer to having draft-6 finished off! Feedback from others who are used to digesting the previous drafts would be super!

[sichvoge]

Sounds super cool. Please point me to anything you want us to have a look at ;) As you said, RAML data types and JSON Schema are very similar and I see RAML data types as complementary to JSON schemas even. Would be great if we grow both simultaneously and together.

We definitely want to get close to JSON Schema, since there are still small differences :)

[Relequestual]

Great to hear @sichvoge - The repo readme has links to issues currentlybeing discussed. There aren't MANY issues outstanding for the draft-6 milestone. I believe we will have a period of review and feedback once WE are happy with draft-6, before pushing it out.

[sichvoge]

Perfect! I also make a list of your changes based on that draft to see what we might be able to introduce in the RAML data type system.

[sichvoge]

@Relequestual can you link to that draft please?

[Relequestual]

The current progress on draft-6 can be found on the master branch at https://github.com/json-schema-org/json-schema-spec - There is also a milestone in issues for draft-6, but that won't contain ALL the changes. The changelog is not 100% yet, but that's part of the plan: json-schema-org/json-schema-spec#206

[jstoiko]

Will mark this issue as closed when https://github.com/raml-org/ramldt2jsonschema/milestone/2 is released.

[sichvoge]

@jstoiko are you guys thinking about @Relequestual suggestion to somehow also support draft06? I'd also update the README file to highlight what draft version is supported atm.

[Relequestual]

@sichvoge Probably best to open a new issue for this if one doesn't already exist! draft-6 has been released now.

[sichvoge]

Perfect, thanks @Relequestual. I will leave that with @jstoiko.