RAML 1.0 !includes spec conflict

#1

Hi there,

I am creating a type library using datatypes to allow type reusing in my APIs, and I am using raml-1-parser to validate my files and generate the equivalent JSON.

Right now I have something like these:

typesLib.raml :

#%RAML 1.0 Library

types:
  TestType: 
    type: !include testType.raml
  OtherTestType:
    type: !include otherTestType.raml

testType.raml :

#%RAML 1.0 DataType

type: object
properties:
  hello: string
  world: string

otherTestType.raml :

#%RAML 1.0 DataType

type: object
properties:
  quote: TestType

The parser says that my API are valid, but the JSON doesn’t include the reference to OtherTestType properties. It also validates the examples in my API.

I am looking at the RAML1.0 spec, but I found some confusing info in the resolving includes topic: the third paragraph said ...an included file SHALL NOT use a YAML reference to an anchor in a separate file..., but, if you look at the example, it tells you quite the opposite! I am also looking in internet and I found other examples using the includes as I use.

I am a bit confused right now, I don’t know if I didn’t understand something or the spec is wrong. Could anyone clarify this?

Thanks!!

#2

I cant wait for all the RAML 1.0 tooling to be working… in the mean time, from several months back, I believe RAML 1.0 uses the USES keyword instead of include. E.g. you would USE another module (giving it an alias name), then in your type: you would use the alias name there.

For example, look at this example here: http://raml.org/developers/whats-new-raml-10

#3

My problem is not the tools, is the conflict in the spec: one paragraph says that I shall not include references to anchor in other files but the example code does exactly the opposite. I don’t know if I am doing it in the right way, so I can’t create a pull request trying to fix the tools.

Pd: yeah, the uses keyword is a bit confusing, I read some post about it and the RAML guys are going to change it in future releases.

#4

Hi @DarkRodry,

Where do you see YAML anchors being used in the example? I don’t see any. Anchors or references in YAML usually start with either “*” or “&”.

Your example should work perfectly fine, but what I don’t understand is what you mean by “… the JSON doesn’t include the reference to OtherTestType properties.”. Can you elaborate exactly what you are executing and your expectations?

Let’s figure out how we can help you! :slight_smile:

#5

Hi!

Sorry for my mistake, I think anchors was references to other files, not YAML anchors :sweat: So there is no problem with the spec.

To parse these files, I uses raml-1-parser with loadRAML() and expand(true) methods with a small API like:

#%RAML 1.0

title: Test

uses:
  t: myLib.raml
/hello:
  post:
    body:
      application/json:
        type: t.OtherTestType
    responses:
      201:

If I have all the includes inside the typesLib.raml (as the previous example code) the raml-1-parser only returns the t.OtherTestType, nothing about TestType.

But, if I use a modified version of the typesLib.raml (the same file replacing the !include ... with the file content):

#%RAML 1.0 Library

types:
  TestType: 
    type: object
    properties:
      hello: string
      world: string
  OtherTestType:
    type: object
    properties:
      quote: TestType

the parser returns both object inside the types properties, TestType and OtherTestType, which I think is the expected output (with these JSON I could execute other tools like datatype expansion).

I could take a look inside the raml-1-parser and try to fix the problem in the !include resolution.

Thanks for your answer and sorry again for my mistake!!!