RAML Linting Rules


#1

Explanation

I think that it would be beneficial/helpful to allow - optionally - RAML specifications to be parsed with some linting rules in effect. This would help organizations standardize APIs across RAML files and between various developers and teams.

Has there been any discussions on an idea like this?

Does anyone else agree that this could be a good addition?

Examples

#%RAML 0.8
title: API with lint error

/Accounts:
  get:

The standard an organization might want to enforce is lower casing all defined URI parts

#%RAML 0.8
title: Conforming API definition

/accounts:
  get:

Suggestion

To allow RAML editors to “opt-in” to linting a linter preferences file could be added to the project; similarly to something like JSHint. This way rules could be applied for those organizations that would like to define rules while not inconveniencing anyone who would not like to use linting.


#2

That would be more an extension for the designer tools as for the specification, right?


#3

If I understand your comment correctly you are suggesting that this idea is better fit into the API designer than it would be in say the RAML compiler. Is this correct?

If my assumption is correct above then; I can see either being an option. Having the compiler incorporate the concept might be good to allow a compilation to fail if the source RAML does not conform to the rules defined. But I can understand if that is not the goal of the compiler thus making this idea a better fit in a tool like the API designer or other tool.

Either way, I know that we at Quicken Loans will look to devise some way of encouraging/enforcing some additional consistency between our many team members developing our many APIs across teams and projects.

I would be interested in helping to make this something that could be incorporated into a Mulesoft product and available for the opensource community.


#4

So I have actually create a command line tool for this; RAML Lint.

We have been using this internally at Quicken Loans for a few weeks now and it has been a great time saver. I would love to hear any feedback anyone has on it since it could still use some additional development and testing.

Additionally, I think it would be really cool if it could get added as an option in the RAML Designer application.


#5

Hi @kalisjoshua, that is a pretty good idea. Let me contact you offline to talk about the details.


#6

hi @kalisjoshua, is there any way to override rules? for example to avoid this validation error :

RAML section (resource) relativeUri violates: only lowercase letters and underscores allowed [url_lower]
HINT:
/income_tax_documents (good)
/incomeTaxDocuments (bad)
/Income-Tax-Documents (bad)

I use a dash instead of underscore for resources naming.

thanks


#7

hi @kalisjoshua. I made plugin for eslint which help validation. .