Support for 1.0 RAML about abao

[ashleydw]

I've got a fork working with RAML 1.0: https://github.com/ashleydw/abao

If anyone can confirm it works for them, I'll propose a PR

I'd say anyone needing it needs to look at examples/schemas/types that can be multiple values, where I just picked the first one, otherwise might want to try and improve on this. e.g: https://github.com/ashleydw/abao/blob/master/lib/add-tests.coffee#L79

[cybertk]

I'm fine to rewrite abao with ES6 or typescript.

[Fleischers]

Is there any work started on RAML 1.0 support?

[galkin]

@oshalygin, @janaaronlee, @sichvoge, @coltonlw, @plroebuck, @cybertk

1. Please look to the @cybertk answer #105 (comment)
   Was there any change?
2. Do we need plain JS version? raml-1-parser uses typescript. Maybe, next abao version should use typescript.
3. The last, but not the least, do we make new project similar abao with JS/coffee/TS or use abao project for the development?

[marcincharezinski]

Any updates on this @plroebuck ? I think it's very desirable feature.

[oshalygin]

+1 I would help but my coffeescript is pretty terrible. If anyone has started an ES6 branch I wouldn't mind lending a hand.

Also +1 on @ashleydw , The current version can stay as is, no need to support 0.8 and 1.0 in the future, let people choose the older version of abao if they would like to use RAML 0.8 specs.

[oshalygin]

@galk-in

1. I understand what changing the underlying language is like, its a huge PITA with little reward. I 100% agree with the fact that coffeescript is dying/dead and the amount of community support is going to be limited because hardly anyone is writing coffeescript these days. Again I'm 100% unlikely to write any coffee script contributions at this time, at least not until I get the RAML 1.0 version working in vanilla ES6.

2. raml-1-parser output is plain JS. If you include it as a module its vanilla JS. Unless we intend to marry those two projects into one(unlikely, because that project is maintained by the raml-org). We just consume it as a module, done!

3. If the response from @cybertk is that we should make a new project then thats the choice I'm perfectly fine with.

Definitely open to feedback and comments, I honestly want to help and don't want to derail any plans that abao currently has on the roadmap.

[oshalygin]

I got wrangled into another side project so its a bit on hold until March 15th(got something going on that day). I'll be full force on it after that, or until someone else jumps in and helps with the core migration(which I'll gladly contribute to)

[oshalygin]

Sorry I've been swamped with another project. I'll push changes shortly and share it here guys.

[ducin]

@sichvoge I remember I spoke to @galkin some time ago about that. So it makes 2 (or 3?) of us.
Language preferences is a never-ending opinionated topic... but the fact is it's gonna be more and more difficult to find CoffeeScript people (or people willing to use it).

[cybertk]

Added, let's go with Javascript ES7

[oshalygin]

I'll be pushing the working branch shortly for review, but it'll definitely be WIP and it won't go into master anytime soon.

[brzuchal]

👍 That would be great!

[sichvoge]

Hi, the JS parser support a JSON representation that is very similar to the 0.8 parser now. Maybe have another go @plroebuck ;)

[sichvoge]

Can you let me know what you struggled with. I might be able to help. there is also a gitter for this project that we can use to further discuss in a more synchronous manner.

@oshalygin Can you start with a fork I can look at? I'd be willing to lend a hand.

Sounds good! I'll be looking at @oshalygin's pure javascript repository and try to help from there.

[oshalygin]

Give me this coming weekend @janaaronlee, I got swamped and didn't get as much done as I had hoped :)

Phase 1 will be to first migrate to ES6 still on 0.8
Phase 2 will be to make sure everything still works
Phase 3 will be to add tests around everything and refactor based on best practices. Right now I'm using http://coffeescript.org/ to convert to plain JS and then I'm manually refactoring all the wonky results it gives. Some of the functions are very bloated with lots of side effects.
Phase 4 will be to seamlessly migrate to RAML 1.0

I'll make an open PR against this repository(please let me know which branch to point to) so that you guys can review the code and make sure I'm not off on a deep end.

[sichvoge]

Hi guys. @ducin @galkin @oshalygin

Any news on this? I think abao is a very popular tool that would immensely gain value from adding RAML 1.0.

Are there any discussions still open?

[oshalygin]

I'm pretty open to restarting this I've just been super swamped the past few days with other side projects.

I honestly need at least one more person who can decipher some of this coffeescript for me. I'm literally doing a 1-1 map on http://js2.coffee/ and then refactoring it for ES6/7/8.

Any interest?

[sichvoge]

@oshalygin Have you had a chance to look into https://github.com/decaffeinate/decaffeinate?

[sichvoge]

What we could do, if @cybertk agrees, is to move that into our "raml-org" organization. I have much more control on there compared to this repo. I want to avoid to disturb @cybertk too many times. :)

But if we decide to create a complete new project, I can create it right away. I don't mind either. I just think that abao is already known in our community, so it's better to stay here.

Hope @cybertk comes back soon :)

[sichvoge]

We could also leave this version specifically for 0.8 and only target RAML 1.0 with the new repo. That would make a few things much easier. What do you think?

[DrummerKH]

Guys, any assumptions when support of RAML1.0 can be ready? Waiting very very long :(. You will make my life alot better guys. Thank you.

[Tzaphkiel]

+1

also looking for support for RAML v1.0

[yakovkhalinsky]

Just wanting to keep this fresh, as my work has decided to try out RAML 1.0 and I am stuck trying to run tests from my fresh new RAML 1.0 spec file

[yakovkhalinsky]

@Fleischers I've resorted to converting our RAML to Open API and using Dredd for testing, it's not a bad solution if you're files are converted with enough strictness

[KennetPL]

+1

[mirobeka]

+1

[mikelaizpurua]

+1

[abienkowski]

+1

[povilasb]

+1

[forrest-ua]

+1

[oharlem]

+1

[plroebuck]

The node module providing RAML-1.0 support was made available Nov 2015; judging from the issue list, it is still in very early beta testing phase. The specification itself is still beta as well.

[iampersistent]

I've started some work on using the new 1.0 parser, there are no 1.0 tests and the failing formatting isn't being handled correctly, based on the tests.

I'll continue to work on it as I have time, but I welcome anyone else to jump in on it.

https://github.com/zestic/abao/tree/raml-1

[plroebuck]

@iampersistent, reading issues for raml-js-parser for RAML 1.0, saw they currently had different (and difficult to digest) format that was inconsistent with 0.8 release. Figured I'd wait until they got that ironed out before I tried. Still many other things on plate for now, and will stick to trying to close other issues for now.

[mostafabarmshory]

+1

[plroebuck]

I tried about a month ago, but it didn't go so well.Not a simple changeover.

[v-kolesnikov]

+1

[sichvoge]

You can also take that example I have created to see if it really works with RAML 1.0. Let me know if it works ;)

[ashleydw]

Is there a mock server running that anywhere? The script can parse it, but obviously cannot check without a server.

[sichvoge]

Unfortunately not no! Let me see what I can do.

[coltonlw]

@ashleydw It looks like your branch removes support for RAML 0.8 and implements 1.0 support only. I would like to see abao get upgraded to use raml-js-parser-2 with RAML 0.8 support intact and tests passing.

[coltonlw]

@ashleydw Can you look at my changes (I link to my feature branch in #177) and see if my method of adding raml-js-parser-2 would work for you? It's great to see other people contributing to this issue, maybe there is a we could consolidate and get your RAML 1.0 support working on my implementation of raml-js-parser-2?

[coltonlw]

@ashleydw Might be a little soon to consolidate, I should get $ref resolution support finished and tests passing. I'd still be really interested to have you review my implementation and see if once I've resolved those issues you'd be willing to accept my implementation of raml-js-parser-2 to build your RAML 1.0 support on

[ashleydw]

I took a quick look. The premise is pretty much the same as mine but I need some extra bits, like schema generation; I see you have used the function schemaContent which I don't think exists on body()?

[coltonlw]

The API for parsing 0.8 and 1.0 is different, and this is one of those
places

Code would have to call body.version() and then get the schema using the
appropriate function for that version

1.0 API lists return type of body() as "TypeDeclaration"

https://raml-org.github.io/raml-js-parser-2/interfaces/_src_raml1_artifacts_raml10parserapi_.typedeclaration.html

TypeDeclaration.schema() returns an array of strings

0.8 API body() return type is "BodyLike", which does have schemaContent
method:

https://raml-org.github.io/raml-js-parser-2/interfaces/_src_raml1_artifacts_raml08parserapi_.bodylike.html

0.8 docs for API object:
https://raml-org.github.io/raml-js-parser-2/interfaces/_src_raml1_artifacts_raml08parserapi_.api.html

1.0 docs for API object:
https://raml-org.github.io/raml-js-parser-2/interfaces/_src_raml1_artifacts_raml10parserapi_.api.html

On Mon, Sep 26, 2016 at 2:20 PM, Ashley White [email protected]
wrote:

I took a quick look. The premise is pretty much the same as mine but I
need some extra bits, like schema generation; I see you have used the
function schemaContent which I don't think exists on body()?

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
#57 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AT8Lk65ZHbFS5fN2hoIWdfngmp07ReQIks5quBr_gaJpZM4GmSda
.

Colton Leekley-Winslow
Software Developer | Scitran Core API
Flywheel.io https://flywheel.io/

[coltonlw]

@ashleydw Your branch confused me because it only supports RAML 1.0 and I overlooked that the interface for raml-js-parser-2 is different between 0.8 and 1.0. I think if we pay attention to whats necessary for supporting both we'll be more on the same page

[sichvoge]

@coltonlw are you using the AST or the JSON output of the parser?

[ashleydw]

@coltonlw I don't plan on adding support for 0.8, sorry

[coltonlw]

@sichvoge AST

@ashleydw You mentioned submitting a PR to cybertk/abao, was your plan to submit one that removes 0.8 support? Or will you maintain your fork until someone else contributes 1.0 support to the main repo?

[ashleydw]

yes probably; 0.8 RAML may as well use the current version as it works - no need to support both raml versions in my opinion.

my fork has many more additions now, so may not good for merging - it now has a mock server and json schema generator inside. if this main is updated to support raml 1 i may think about updating mine, but probably not as it is working for my needs.

right now if anyone needs RAML 1 support, my fork will work, but just be aware that it has deviated somewhat.

[sichvoge]

@coltonlw may i ask why you decided to use the AST? in this scenario i would assume the easier to use JSON would be fully enough.

[coltonlw]

@sichvoge I actually thought using the AST would be easier and cleaner. It gives you access to the methods attached to each object which one day might do things like parse jsonschema $ref's :) I'm not opposed to using the JSON though

[sichvoge]

The current top level might not be supported in the future anymore. It has been developed to replace the JSON output but people did not like it so we switched back. We think that having both including the high level AST does not make sense. BUT, we had a conversation yesterday and see the demand on a very easy to use layer that helps you do things that Abao needs easier. Although, you can do all that using the high-level AST or the JSON output (which Abao used before) as well.

What I would do is to checkout the high level AST (this is the real abstract syntax tree) and the JSON output if they give you what you need. Don't hesitate to give feedback about that to us here so that we understand different use cases better and make the best decision keeping our consumer in mind.

Comments?

[sichvoge]

agree with @oshalygin; thats what we did with raml2html as well.

[sichvoge]

@ashleydw @coltonlw @galk-in is there any update on the support for RAML 1.0 in general?

[oshalygin]

@sichvoge
I tried @ashleydw 's fork and it was definitely flakey but he described it as such. I took a look at the code and I'm tempted to just roll a spinoff with plain JS, but would love to get a bit of help because I'm between like 5 projects.

Unless I'm underestimating this, we're basically just pulling in the latest parser and then writing a test harness over it.

If someone already started I rather not reinvent the wheel.

[oshalygin]

@janaaronlee https://github.com/oshalygin/raml-test

It's not really a fork anymore because I'd like it to be in Vanilla ES5/ES6/ES7 supporting strictly RAML 1.0. It is possible in the future to support 0.8 but that won't be the primary goal initially.

It's just easier to start from scratch and pull in the abao pieces that are necessary to get it to work. I'll be doing quite a bit of work this weekend on it so the repository should have a bit more meat to it and should(hopefully) process RAML 1.0 by the end of the weekend. It'll be rough for a week or so until I can nail everything down and test it up and down.

My intention is to make it as good as abao(great work here guys), but strictly support RAML 1.0 with ES6 so that others can help contribute as the project grows.

[ashleydw]

Just a quick tip. If you're going to do this, you may wish to take note of a rewrite discussion here: raml-org/raml-js-parser-2#564

Also, why not Typescript? You may be able to use the typings in the parser source code to ensure your models match that expected.

[oshalygin]

You can use typings without using TypeScript. That and most editors these days can read typings to validate that you are using the proper API.

TypeScript adds more typing in general and doesnt reduce bug density. I don't want to derail this much further but this post is relevant in regards to TypeScript:
https://medium.com/javascript-scene/the-shocking-secret-about-static-types-514d39bf30a3#.er6ah250m

I'm open to doing TypeScript and it being a superset of JavaScript means it will play together nicely. I've written quite a bit of TypeScript professionally, so I don't have any reservations to writing it, I just wouldn't recommend it without knowing what problem is it going to solve for us and is it worthwhile to add type annotations to everything.

If the goal is to reduce bug density, we should just more/better tests.

[DevWurm]

Can you provide some information about the current state of RAML 1.0 support?

Do you have your work on phase 1 in a branch, @oshalygin ? Then other people might be able to lend a hand.

That would be great, @oshalygin. Understand it isn't always easy to fit projects into life…

[ducin]

@cybertk
| I'm fine to rewrite abao with ES6 or typescript.

I remember asking about the very same thing before, I saw it rejected in #105, glad you changed your mind. If you choose TypeScript, I would join you.

[sichvoge]

@ducin I think thats what @oshalygin wants to do :)

[oshalygin]

I'm not using typescript btw, I've talked about it in this thread and others before but there is very little value in adding "compile" time type checking for JS. I'm a firm believer in writing tests against your code to ensure functionality and not deferring to something like typescript to ensure code quality.

I've used typescript heavily in the past and I see some of the benefits in terms of IDE help but otherwise I don't want to add complexity and piecing everything together into classes. The ROI just isn't there.

[sichvoge]

I am not very familiar with coffeescript and wouldn't be much help in this, to be honest. Let's see if we can find someone in this thread and if not let's try to solve it between you and me :D Can you send me a message to christian (dot) vogel (at) mulesoft (dot) com, please. Let's sync on this.

Regarding typescript, I am definitely not religious and if you prefer pure JS - let's go for it. No need to overcomplicate things :)

[ducin]

@oshalygin you don't have to use classes with TypeScript. You can write in strict functional manner, it's up to you. The same as with ES6+.

| there is very little value in adding "compile" time type checking for JS
That's only your opinion, not a fact ;). For a OSS library (comparing to commercial products), TS might be a better choice because the compile time does handle all type violations. It's easier to do a valuable contribution, when you enter the project, because the platform will handle it for you. Also, it's a lot easier when distributed teams from different timezones co-work on a codebase (static typing is easier to reason about). Whenever you ctrl+click on a type, you can easily see what it returns. When having Functional composition without types - in JS you need to learn all the way down to composed function, whereas in TS you can just see the type. It's just more convenient. I'm a co-creator of JSON Schema Faker, we started it with coffee, 2,5+ years ago, then switched to TS and if I went back in time, I'd still stick to TS. Regarding tests - you just don't write some unit tests that assert what is the result type of a given function/method. Instead, you define the type. Types increase readibility, obviously they introduce cost as well. But you write significantly less unit tests - this amount of time saved can be put into declaring types. A couple of arguments can be also found here.

I wanted to contribute to abao long time ago but, same as others, my coffee is pretty bad. I'd be willing to help if the choice is TypeScript.

[sichvoge]

so what we know is that we need to migrate the current coffeescript code into JS/TS. @ducin would you be fine to help even if we choose pure JS/ES6+?

@oshalygin question to you back, would you be willing to help even if the choice is TS?

I understand that there are advantages coming with TS and I am using it mostly myself. The question is if we can find a compromise quickly?

[oshalygin]

@sichvoge I'd be open to doing TS but along the lines of of what @ducin proposes, in a more functional manner instead of instantiating classes and calling utility methods on those classes. Just to be clear I'm not a fan of ES6 classes either, unless I'm writing React.

I have looked at decaffeinate, but afterwords it still needs a bit of massaging afterwords.

If we start lets start and just start putting code/tests/documentation together. If you guys want I could start the repo or someone else can, just put us in as collaborators and we can get going with issues/etc.

[ducin]

This sounds like a plan. That'd be great if we can agree with going functional TS. We'd just define interfaces for return types in small .d.ts files.

I got some questions on how do we approach this all:

• do we start a new branch for RAML 1.0?
• @oshalygin do I understand correctly that you want to start a new repo?
• do we rewrite existing Coffee into TS in order to support RAML 0.8? We might leave existing coffeescript code supporting old RAML, but that would leave us with two codebases, which would kick our asses in the long run
• @cybertk do you plan to support this project? How much do you want to be involved?

[oshalygin]

@ducin I'll start it, name preferences? I have zero preference, but we need to make sure its available on npm.

• abao-raml
• raml-spec
• raml-test (I already have this one registered)

Throw some names together and I'll put together a repo, register something with npm and add everyone as collaborators

I think we should first aim to support 0.8 as a way to become familiar with the codebase, with the full intent to ALSO support 1.0 and not corner ourselves into a box. I'm open on this as well.

I'm also open to branching here but there's a lot of code here already written in coffeescript and rewriting it from ground up

[oshalygin]

a little late on the reply but I would lean towards creating the repo on raml-org

[oshalygin]

I'd like to still be able to target both, or at least see if its feasible.

Another thought on type checking, what do you guys think of flow? I'll be honest, no experience with it but I've heard only good things.

https://flow.org/

[cybertk]

I'm OK to rewrite with JS for supporting RAML 1.0 and later, see #223.

Prefer releasing the JS version as a normal major release of existing Abao.

[sichvoge]

OK - then let's stay with this repo. @cybertk can you make @oshalygin and @ducin contributor? Would that work for you?

[oshalygin]

Alrighty dudes, this weekend I'm going to put together the initial PR work. I'll create a slew of issues we can reference and dev against.

Stop if anything is crazy :) I promise nothing crazy!

[ralucas]

Is there a list of tasks that are necessary to convert this 1.0? Or where is progress in terms of this?

[mrwersa]

Any update on this one?

[jstoiko]

@plroebuck: I see some activity in the past few days. Any RAML 1.0 -related work in the horizon?
@oshalygin: what ever happened to that RAML 1.0 fork/branch/PR you were working on?

[Fleischers]

@yakovkhalinsky Same happened to us in 2016 #57 (comment)

We had high hopes for abao update back then, as our Java stack already used some automated raml tools, so we wanted to keep Node.js projects in pace.

In the end, our automation team just wrote their own custom testing solution based on raml-1-parser, but it is very project-specific and unfortunately not available as open source