It'd be nice to remove this hard dependency, as node and browsers have promises and consumers might be using a different promise library (bluebird is much more popular, for instance). We could use the global object and recommend people polyfill it instead.

Edit: https://www.npmjs.com/package/native-or-bluebird for not breaking backward compat.

I am getting this error when trying to parse my raml file.
Error parsing: while scanning for the next token found character that cannot start any token in "Todo.raml", line 7, column 1
I don't know what I am doing wrong. Any guidance would be great. This is my raml file:

#%RAML 0.8
title: Todo API
version: v1
baseUri: http://localhost:3000
protocols: [HTTP, HTTPS]
mediaType: application/json
    /tasks:
        get:
            description: Get a list of all Tasks.
            responses:
                200:
                    body:
                        application/json:
                            example: |
                                {
                                    "tasks": [
                                        {
                                            "_id": "556f927e265f627993000012",
                                            "description": "Make dinner",
                                            "name": "task1",
                                            "date_created": "2015-06-03T23:49:18.059Z"
                                         },
                                        {
                                            "_id": "55705da20f014efb93000009",
                                            "description": "Watch your sister",
                                            "name": "task2",
                                            "date_created": "2015-06-04T14:16:02.087Z"
                                        },
                                        {
                                            "_id": "557069295ec4d36d94000006",
                                            "description": "Meeting at 9:30",
                                            "name": "task3",
                                            "date_created": "2015-06-04T15:05:13.612Z"
                                        },
                                        {
                                            "_id": "557088e7c08d7e6495000001",
                                            "description": "Go home",
                                            "name": "task4",
                                            "date_created": "2015-06-04T17:20:39.330Z"
                                        }
                                        {
                                            "_id": "55708ee2efba7e9d95000009",
                                            "description": "Go to bed",
                                            "name": "task5",                                                                                           "date_created": "2015-06-04T17:46:10.530Z"
                                        },
                                        {
                                            "_id": "55807c154790bb000000003a",
                                            "description": "Eat Dinner",
                                            "name": "task 6",
                                            "date_created": "2015-06-16T19:42:13.798Z"
                                        }
                                     ]
                                }
        post:
            description: |
                Add a new task.
            queryParameters:
                task_name:
                    description: "Unique Task name"
                    example: task1
                    required: true
                    type: string
                task_description:
                    description: "Description of the task"
                    example: Mow the lawn.
                    required: true
                    type: string
            body:
                application/json:
                    schema: task
            responses:
                200:
                    body:
                        application/json:
                            example: |
                                {
                                    "message": "Task added with name: task1"
                                }

        put:
            description: |
                Update a task.
            queryParameters:
                task_name:
                    description: "Unique Task name"
                    example: task1
                    required: true
                    type: string
                task_description:
                    description: "Description of the task"
                    example: Mow the lawn.
                    required: true
                    type: string
                task_id:
                    description: "Unique Task id"
                    example: 56f927e265f627993000012
                    required: true
                    type: number

            body:
                application/json:
                    schema: task
            responses:
                200:
                    body:
                        application/json:
                            example: |
                                {
                                    "message": "Task updated"
                                }
        delete:
            description: |
                Remove a task.
            queryParameters:
                task_id:
                    description: "Unique Task id"
                    example: 56f927e265f627993000012
                    required: true
                    type: number

            body:
                application/json:
                    schema: task
            responses:
                200:
                    body:
                        application/json:
                            example: |
                                {
                                    "message": "Task removed"
                                }


    /tasks/{task_id}:
        get:
            description: Get a list of a specific task by id.
            queryParameters:
                task_id:
                    description: "Unique Task id"
                    example: 56f927e265f627993000012
                    required: true
                    type: number
            responses:
                200:
                    body:
                        application/json:
                            example: |
                                {
                                    "_id": "556f927e265f627993000012",
                                    "description": "Make dinner",
                                    "name": "task1",
                                    "date_created": "2015-06-03T23:49:18.059Z"
                                }

I can't use yaml's ability to extend objects defined earlier, I get an error only scalar map keys are allowed in RAML. Here's an example:

extendable: &extendable
  inherited: prop
extended:
  <<: *extendtable
  extra: prop0
items:
  - <<: *extendable
    extra: prop1
  - <<: *extendable
    extra: prop2

which should expand to

...
extended:
  inherited: prop
  extra: prop0
items:
  - inherited: prop
    extra: prop1
  - inherited: prop
    extra: prop2

Is it really true that only scalar map keys are allowed for RAML? Or is it just that the parser doesn't know how to handle the <<: key? (I am not even sure whether << is a scalar or not)

When using library from node.js, occasional errors/exceptions that are caused by my load hander are silently lost without trace. This is not very expected and convenient during development and forces wrapping the handler in custom exception logging handler.

For example, this script won't print anything :

var raml = require('raml-parser');

process.on('uncaughtException', function(err) {
    console.log('Won\'t catch anything: ' + err);
});

var definition = [
    '#%RAML 0.8',
    '---',
    'title: MyApi',
    'baseUri: http://myapi.com',
    '/Root:'
].join('\n');

raml.load(definition).then(function (data) {
    throw "Did something wrong in handling";
}, function (error) {
    console.log('Error parsing: ' + error);
});

Expected behavior: similar to default callback error handling, e.g.

setTimeout(function() {
    nonexistentFunc();
}, 500);

will raise uncaughtException event, and if not handled - an error with stacktrace will be printed in the console:

$ node lib/err.js

<path>/err.js:33
nonexistentFunc();
^
ReferenceError: nonexistentFunc is not defined
    at Object.<anonymous> (<path>/err.js:33:1)

I think there is a bug in the handling of parameters and transformers. The following file is valid but only as long as the specified description spans 2 lines. If it is written as one line it will produce the error "unused parameter: key"

https://gist.github.com/thebinarypenguin/a1cb881d421070048fa2

Hi there,

Does the API provide a way to create the RAML file from an AST? That is, imagine I have a JSON representation of a REST service and I wanted to create a raml representation of such service.

Cheers,
George

https://github.com/raml-org/raml-js-parser/releases doesn't say what's changed and I can't seem to find a changelog.

I've split my (rather large) RAML file up into different files and my main file now looks like this:

#%RAML 0.8
title: Example
version: 1
baseUri: http://example.com/{version}

/account: !include account.raml
/status: !include status.raml
/channels: !include channels.raml
/conversations: !include conversations.raml
/organisations: !include organisations.raml
/users: !include users.raml
/groups: !include groups.raml
/feeds: !include feeds.raml
/switches: !include switches.raml
/locations: !include locations.raml
/shifts: !include shifts.raml
/tasks: !include tasks.raml
/upload: !include upload.raml

Now whenever I parse this via loadFile I get the resources in a random order. This is a problem in my raml2html renderer (see https://github.com/kevinrenskers/raml2html/issues/6) because the html output is now always different, causing much confusion.

So if you define a queryParam inside a trait, and you use this trait for one method but then you override it on the method definition, the enums get added/joined/merged instead of overriden.

Here is the sample RAML file.

#%RAML 0.8

---
title: Data API
version: 2
documentation:
    - title: Description
      content: the doc
baseUri: https://api.midomain.com/api/v2
traits:
  - dateBounded:
      queryParameters:
        group_by:
          required: true
          displayName: Group by
          description: Time aggregation period
          example: month
          enum: [day, week, month]
          type: string      

/zipcodes/{zipcode}:
  displayName: Zipcodes
  uriParameters:
    zipcode:
      required: true
      displayName: Zipcode
      description: Zipcode to be retrieved
      example: 57500
      type: string 

  /consumption_pattern:
    is: [dateBounded]
    displayName: Consumption pattern by zipcode
    description: This service returns, for an specific zipcode....
    get:
      description: Consumption patterns by time and week/day for a zipcode
      queryParameters:
        group_by:
          required: true
          displayName: Group by
          description: Time aggregation period
          default: month
          example: month
          enum: ["month"]
          type: string

In this example the enum [day, month week] defined in the trait, is not overriden by the enum defined in the method definition which is only month. As you can see in the console screenshot, the enum says [day, week, month, month], and it should be only [month] so the raml parser is merging/joining the enums rather than overriding them.

This is the output JSON of the resources properties, after it gets rendered by the raml-js-parser

[
   {
      "displayName": "Zipcodes",
      "uriParameters": {
         "zipcode": {
            "required": true,
            "displayName": "Zipcode",
            "description": "Zipcode to be retrieved",
            "example": 57500,
            "type": "string"
         }
      },
      "relativeUri": "/zipcodes/{zipcode}",
      "resources": [
         {
            "is": [
               "dateBounded"
            ],
            "displayName": "Consumption pattern by zipcode",
            "description": "This service returns, for an specific zipcode....",
            "relativeUri": "/consumption_pattern",
            "methods": [
               {
                  "queryParameters": {
                     "group_by": {
                        "required": true,
                        "displayName": "Group by",
                        "description": "Time aggregation period",
                        "example": "month",
                        "enum": [
                           "day",
                           "week",
                           "month",
                           "month"
                        ],
                        "type": "string",
                        "default": "month"
                     }
                  },
                  "description": "Consumption patterns by time and week/day for a zipcode",
                  "method": "get",
                  "securedBy": [
                     "basic"
                  ]
               }
            ],
            "relativeUriPathSegments": [
               "consumption_pattern"
            ]
         }
      ],
      "relativeUriPathSegments": [
         "zipcodes",
         "{zipcode}"
      ]
   }
]

How can I parse loaded raml file again into raml file?

I did ramlParser.loadFile(raml).then(function(data){...stuff...} and I changed raml file and now I want to convert it again into raml. How can I do this ? :)

I may have interpreted the spec wrong, but shouldn't mediaType be an acceptable property of body, and if set, override the default root property of the same name?

When trying to parse a RAML file with composeFile I always get the following error: Error parsing: ReferenceError: parent is not defined

raml.composeFile('example.raml').then(function(rootNode) {
    console.log('Root Node: ' + rootNode)
}, function(error) {
    console.log('Error parsing: ' + error);
});

Not sure where this error is coming from. This is happening with even the most basic of RAML files.

The published npm module is 5 months old and still depends on json-lint, instead of the updated jju.

I'm trying to run simple validation snippet from the command line:

var raml = require('./lib/raml-parser.js');

raml.loadFile('api.raml').then( function(data) {
    console.log(data);
}, function(error) {
    console.log('Error parsing: ' + error);
});

The error:

○ → node validate.js

/Users/oleksandr/Projects/RAML/sample/lib/raml-parser.js:3135
window.RAML = {}
^
ReferenceError: window is not defined
    at Object.../lib/raml (/Users/oleksandr/Projects/RAML/sample/lib/raml-parser.js:3135:1)
    at i (/Users/oleksandr/Projects/RAML/sample/lib/raml-parser.js:1:281)
    at __indexOf.indexOf.i (/Users/oleksandr/Projects/RAML/sample/lib/raml-parser.js:1:444)
    at Object.<anonymous> (/Users/oleksandr/Projects/RAMLsample/lib/raml-parser.js:1:462)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.require (module.js:364:17)
    at require (module.js:380:17)

Here's my RAML file:

#%RAML 0.8
title: Topics
version: v0.1

I try to create documentation out of it using [email protected] (that uses [email protected]):

raml2html api/discussion/spec.raml -o spec.html

And this is the output I get:

Error parsing: version validation
The first line must be: '#%RAML 0.8'
  in "undefined", line 1, column 1

Given a Resource Type,

resourceTypes:
  - readOnlyCollection:
      description: Collection of available <<resourcePathName>>.
      get:
        description: Get a list of <<resourcePathName>>.
        responses:
          200:
            body:
              example: !include samples/<<resourcePathName|!singularize>>.sample

the !include samples/<<resourcePathName|!singularize>>.sample cannot be parsed as !include samples/resource.sample when apply Resource Type to /resource

According to http://raml.org/spec.html#toc_59 and my understanding, if we specify a parameter inside a trait/resource type, and then try to use this type without providing the parameter value, the parsing should fail:

"The definitions of resource types and traits MAY contain parameters, whose values MUST be specified when applying the resource type or trait, UNLESS the parameter corresponds to a reserved parameter name, in which case its value is provided by the processing application (whatever is consuming the API definition)."

In our resource type we have a parameter called <<commonResourceSchema>> and if we use this resource type in our RAML without specifying the commonResourceSchema parameter, the parsing still passes. Shouldn't it fail, according to the specs?

We have the problem that such RAML is not correctly picked up by other tool, because of "syntax error". We can implement an additional validation ourselves, but I'm just wondering that maybe it should be part of the RAML parser.

Monika

With the following RAML, the parser fails (nevermind the content in tt.yaml):

#%RAML 0.8
title: Address API Specification
traits:
  - !include tt.yaml

It messes with commits greatly and makes history hard to follow. We should pull it into npm and bower preinstall steps so we don't need to worry about it anymore.

JSON-lint doesn't correctly validate unicode format \uFFFF and admits only numeric unicode values in their regular expression (i.e. \u1234).
https://github.com/codenothing/jsonlint/blob/3b09919cb62d4d46d07fd57bf5730b35c87b3c9c/jsonlint.js#L7

This results in errors in raml-parser if a json schema include unicode encodings such as this:

"fieldName":{
   "type":"string",
   "description":"blah blah",
   "maxLength":16,
   "pattern":"^[A-Z\u017D\\u017E]*$"
},

This issue has been raised in JSON-lint but no solution has been yet released:
codenothing/jsonlint#2

When validating the following raml file:

#%RAML 0.8

---
baseUri: http://example.com

securitySchemes:
  - basic:
    type: Basic Authentication

/:
  securedBy: [basic]

The parser returns the error "invalid security scheme property, it must be a map". When you change it to an array, the parser complains "invalid security schemes property, it must be an array". I think the former is the way as de spec describes it, but apparently that doesn't work.

I'm using OSPREY as follows:

var api = osprey.create('/api', app, {
ramlFile: path.join(__dirname, '../raml_spec/api_spec.raml'),
logLevel: app.get('env') !== 'test' ? 'debug' : 'off'
});

The API is loaded OK but when i want to open the console at /api/console it crashes because it can not load any resource file (json and schema) defined in the raml file.

The request to the file should be localhost:3000/api/fileName.json, but instead it's doing localhost:3000/fileName.json

If the context value is "/api/anything" then the console works ok.

Need to add the ability to get the actual !include path for schemas.

I have a resource defined as such:

/ping:
  get:
    securedBy: [null]
    description: Responds with an appropriate HTTP status code & message for the state of the API.
    responses:
      200:
        body:
          application/json:
            example:
              !include examples/ping.json

I'm using raml2html, but parsing my RAML file results in the following error message:

Error parsing: Template render error: (/usr/local/lib/node_modules/raml2html/lib/template.nunjucks)
  Template render error: (/usr/local/lib/node_modules/raml2html/lib/resource.nunjucks) [Line 65, Column 64]
  TypeError: Cannot read property '0' of undefined

Removing securedBy: [null] allows the file to be parsed correctly.

Raml parser doesn't attempt to parse or validate the nested schema.
{
"required": true,
"description": "Bulk buy limit attributes",
"type": [
"object",
"null"
],
"$ref": "bulkbuy-schema.json"
}
In the following example it would just treat this as a text. The fact that $ref is there wouldn't mean anything to RAML parser.

This issue is related to #81 and occurs if the file included as a trait includes a JSON schema file.

Eg.,

%RAML 0.8

title: TT

traits:

• !include http://host/common/traits/tt.yaml

The trait file included contains the below:

CLIENT_ERRORS:
displayName: CLIENT_ERRORS
responses:
400:
description: Client request related errors.
body:
application/json:
schema: !include http://host/common/schema/ErrorSchema.json

ErrorSchema.json contains the following:
{ "$schema": "http://json-schema.org/schema",
"type": "object",
"description": "Error Info",
"properties": {
"errorCode": { "type" : "string" },
"description": { "type" : "string" }
}
}

The error I'm getting is as below:
Object # has no method 'match'

Please let me know if you need more information

This type of inclusion is not working in a resource type.

I have a master file for resource types which I include in the main RAML file as
resourceTypes: !include resource-types.raml

In the resource-types.raml file I have the following definition:

#%RAML 0.8

- collection-controller:
    get:
        responses:
            200:
                body:
                    application/json:
                        schema: <<resourcePathName>>
                        example: !include examples/<<resourcePathName>>-200.json

The raml-js-parser fails to parse the !include examples/<<resourcePathName>>-200.json part.
I expect it to include the example in the file examples/users-200.json for example. The RAML file should be valid as I am also using RAML Java Parser and it works just fine - it parses the RAML files without errors and also generates service interfaces out of it. The error that I get with raml-js-parser is:

...
[19:01:56] Plumber found unhandled error:
Error in plugin 'gulp-raml2html'
Message: .... cannot read examples/%3C%3CresourcePathName%3E%3E-200.json (Error: ENOENT, open 'examples/%3C%3CresourcePathName%3E%3E-200.json'). I guess that the value of the 'example' property is not expanded properly. Workaround would be to pass the contents of the example as a parameter but I wanted to avoid that - I don't want to specify it explicitly for each resource.

Hi,

I recently had the pleasure of writing a library that creates accessible REST resource objects out of RAML descriptor files. For this I used raml-parser as a node module, and things worked out mostly fine. I had a bit of a tricky time getting everything set up though, for two reasons.

Reading a RAML file with multiple files as dependencies takes quite a lot of time comparatively, even on localhost. Like so:

reading a raml schema file
  ✓ should accept a url and return a schema (460ms)

This is surprising, but not a dealbreaker, although it does slow down my test runs and thus requires special attention.

Once I did get the setup right, it would start halting async execution for no apparent reason, then maybe start working again at the next run. I couldn't find a pattern to things, and whether I cleaned up the repo's root from any number of temporary files between runs didn't seem to have any effect. I tracked things down to FileReader::fetchFileAsync, which would apparently not resolve.

I ran ramlParser.loadFile with a FileReader of my own passed to it, and managed to circumvent the problem. Not only does it work consistently, but it's much more performant.

reading a raml schema file
  ✓ should accept a url and return a schema (56ms)

So, heads up: your XMLHttpRequest library of choice is likely broken for some use cases. For what it's worth, I'm running a static express server with node.js to serve static test data and used superagent for the replacement, but YMMV.

Again, thanks, I appreciate your work on RAML! _b

Cheers,
Eevert

It'd be fantastic if there could be an exposed cache of parsed RAML. It'd be a breaking change to the API, but it'd enable much more performant and flexible solution using the RAML parser. For example, having the API designer re-parse every change, generating documentation from a watch server, automatically restarting Osprey during development, etc. Also, it'd fix making multiple requests to the same file on the filesystem or remotely and properly allow composition using the filesystem instead of raml globals.

Existing example: Browserify + watchify

Right now if there is an error, the program fails silently, exits with a success code, and does not give a stack trace. If these could be piped over from its python internals, it would make working with this much more pleasant.

queryParameters:
  from:
    description: Limit results to those created after from.
    example: 2014-12-31T00:00:00.000Z
    type: string
    required: false

Ends up like:

{ queryParameters:
   { from:
      { description: 'Limit results to those created after from.',
        example: Wed Dec 31 2014 00:00:00 GMT+0000 (GMT),
        type: 'string',
        required: false,
        displayName: 'from' } }

Hi there,

I think I discovered an issue.

Having the following:

#%RAML 0.8

---
title: My Sample App
baseUri: http://somwhere.really.cool/{version}/
version: v1
protocols: [HTTPS]
mediaType: application/json

resourceTypes:
  - member: 
      usage: This resourceType should be used for any member of collection.
      get:
        responses:
          200:
            body:
              schema: <<resourcePathName | !singularize>>
              example: <<exampleGetResponse>>

      patch?:
        body:
          example: <<examplePatchRequest>>
          responses:
            201:
              headers:
                location:
                  type: string
                  example: /<<resourcePathName>>/1

/organizations:
  /{id}:
    type:
      member:
        exampleGetResponse: !include examples/organizations/response-get.json
        examplePatchRequest: !include examples/organizations/request-patch.json
    patch:

When the YAML file generated and a JSON is produced, the media type is not present for the method patch for path /organizations/{id}. If I remove the ?, the application/json appears in the parsed content:

Incorrect

...
"methods": [
    {
        "responses": {
            "200": {
                "body": {
                    "application/json": {
                        "schema": "{\n  \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n  \"title\": \"Organization\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\"\n    }\n  },\n  \"required\": [ \"name\" ]\n}",
                        "example": "{\n  \"name\": \"Awesome orga\"\n}"
                    }
                }
            }
        },
        "method": "get"
    },
    {
        "body": {
            "example": "#{\n  \"name\": \"Awesome orga\"\n}"
        },
        "responses": {
            "201": {
                "headers": {
                    "location": {
                        "type": "string",
                        "example": "/organizations/1",
                        "displayName": "location"
                    }
                }
            }
        },
        "method": "patch"
    }
]

Correct

...
"methods": [
    {
        "responses": {
            "200": {
                "body": {
                    "application/json": {
                        "schema": "{\n  \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n  \"title\": \"Organization\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\"\n    }\n  },\n  \"required\": [ \"name\" ]\n}",
                        "example": "{\n  \"name\": \"Awesome orga\"\n}"
                    }
                }
            }
        },
        "method": "get"
    },
    {
        "body": {
            "application/json": {
                "example": "#{\n  \"name\": \"Awesome orga\"\n}"
            }
        },
        "responses": {
            "201": {
                "headers": {
                    "location": {
                        "type": "string",
                        "example": "/organizations/1",
                        "displayName": "location"
                    }
                }
            }
        },
        "method": "patch"
    }
]

During my experimentation, I went to modify this file: https://github.com/raml-org/raml-js-parser/blob/master/src/resourceTypes.coffee#L54-L55

before

    tempType.combine resource[1]
    resource[1] = tempType

after

    tempType.combine resource[1]
    @apply_default_media_type_to_resource tempType
    resource[1] = tempType

Honestly, I really do not know exactly what I did there but it changed the parsed result in a way that the bodies now contain the default media type from the main RAML document when none are specified in my optional resources.

I'm getting a validation error on the following (snippet) -
it flags the 'description' (the first item) as an error - "each header must be a map'.

[see this line in validate_headers: if (!(util.isNullableMapping(param[1]) || util.isNullableSequence(param[1])))]

Here's my RAML, defining headers in a trait:

#%RAML 0.8

---
title: Test Service
baseUri: http://sometest.org/mobile/platform/test
version: 1.0
mediaType: application/json
protocols: [HTTPS]

traits:
  - sql:
      headers:
        test-Mobile-Sql:
        description: blah blah blah
        type: string
        required: true
        example: |
          SELECT "title" from "Movies"

/sql:
  description: |
    blah blah blah
  get:
    description: blah blah blah
    is: [ sql ]
    queryParameters:
      argX:
        description: blah blah blah
        type: string
      parameterX:
        description: blah blah blah
        type: string
    responses:
      200:
        body:
          application/json:
            example: |
              [{ "title" : "The Imitation Game"}]

Could you please specify what is the licensing model for this project?

Hi,

Any reason why you're holding back a version bump on npmjs? The Windows bugs that were fixed would be nice to be published so everybody on the project can use our doc generator. For now we're referencing the GitHub repo directly, but it would be more proper linking to a specific version.

Cheers!

The second example under responses in the spec includes a description inside the body. However, this RAML parser fails on that example.

I added a generic header like so:

#%RAML 0.8

---
title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1

/media/{mediaid}/content:
  displayName: Content
  get:
    description: |
      Get a media file.
    responses:
      200:
        body:
          "*/*":
            description: |
                Returns the media file.

Then I tried to parse this like so:

raml = require('raml-parser')

raml.loadFile('test.raml').then (data)->
  console.log(data)
, (error) ->
  console.log('Error parsing: ' + error)

Running this throws the following error:

Error parsing: while validating body
property: 'description' is invalid in a body
  in "test.raml", line 16, column 13

Please do release merges on master to npm, and tag versions properly.

Currently master is ahead of released 0.8.9. That includes an unreleased fix for #122 that is blocking us. Also tags are not set properly.

That said, thanks for a great API documentation tool!

When a resource URI starts with /type (e.g /types_offres), the parsing fails.
This was experienced with the Raml-Console.

Bellow is the error message:

{"context":"while applying resource type","context_mark":null,"message":"there is no resource type named displayName","problem_mark":{"name":"/api/spec/boutel-rest-api.raml","line":178,"column":8,"buffer":"#%RAML 0.8\n-- .....

With this trait:

- legacyPages:
    description: |
      This is a legacy resource, prefer accessing pages from the `/pages` resource.

and this resource:

/pages:
  is: [legacyPages, subCollection]

the description is not inherited, as it's visible in projects that use raml-js-parser (for ex. api-console and raml2html).

Here is a micro RAML prepared to show the problem:

#%RAML 0.8
title: uri params bug
resourceTypes:
  - base:
      uriParameters:
        mediaTypeExtension: 
          required: true

# OK
/working{mediaTypeExtension}:
  type: base

# bug: should report error "mediaTypeExtension uri parameter unused"
/inherited:
  type: base

# OK, reports error "mediaTypeExtension uri parameter unused"
/explicit:
  uriParameters:
    mediaTypeExtension: 
      required: true

According to RAML spec:

Responses MUST be a map of one or more HTTP status codes, where each status code itself is a map that describes that status code.

But raml-parser validates following constructions:

responses: 
    204: 

Real life example: https://github.com/raml-apis/GitHub/blob/staging/api.raml#L2121

#%RAML 0.8

---
  title: "Test"
  version: "v0.1"
  baseUri: "http://mocksvc.mulesoft.com/mocks/a86239e0-d3af-48c6-9fd5-f8edc7c35d69"
  mediaType: "application/json"
  protocols:
    - "HTTP"
    - "HTTPS"
  documentation:
    -
      title: "Test"
      content: ""
  /test:
    displayName: "test"
    description: ""
    get:
      displayName: ""
      description: ""
      headers: {}
      responses:
        200:
          body:
            application/json:
              schema: "{\"type\":\"string\"}"
              example: "\"the devil's place\""
      queryParameters: {}
  schemas: []

Validated with: http://www.yamllint.com/

The problem is with the string "the devil's place". If I replace the apostrophe with single quote, it works just fine.

An included yaml file s not being validated properly for the following values:

1. "response:" instead of "responses:"
2. "parameters" instead of "formParameters"

I get this error when I run osprey on a hello world project. Same project works on mac but not on windows.

{ [Error: unknown protocol d:]
  context: 'while reading D:\\Dropbox\\projects\\demo\\api\\src\\assets\\raml\\api.raml',
  context_mark: null,
  message: 'unknown protocol d:',
  problem_mark: null,
  note: undefined }

PS: see more details at mulesoft/osprey#61

In original RAML follow field not must required. Why your app crash while not found it in raml doc?

As by @dmartinezg suggested on mulesoft/api-designer#275:

The API Designer (version something on 2015-01-01) reports

Resource name is invalid: illegal character

when there is a hyphen in a uriParameter, e.g.

/bug{a-b}:
  uriParameters:
    a-b:
      enum: [ a-b ]
Quick fix: use underscores instead of hyphens.

Issues:

Hyphen is a legal YAML word character.
Hyphens are allowed in resource names.
Hyphen causes no problems in a uriParameter name.
The hyphen is in the template expression, not in the resource name.
The problem is that RFC 6570 does not allow hyphens in variable names.
Suggestions:

Change the error message to something like
Invalid uriParameter name: illegal character '-'
Check the validity of uriParameter and baseUriParameter names.

Source: http://forums.raml.org/t/resource-name-is-invalid-illegal-character/614/2

raml.load(fileData).then(function(data) {
    ---some code here---
},
function(error) {
   throw new Error('Custom error'); // Doesn't work
});

All promises wrapped with try/catch?

The spec doesn't seem to specifically mention displayName on methods, but examples within the spec include them. See the third example here:

#%RAML 0.8
title: Users API
version: 1
baseUri: https://{apiDomain}.someapi.com
/users:
  displayName: retrieve all users
  baseUriParameters:
    apiDomain:
      enum: [ "api" ]
  /{userId}/image:
    displayName: access users pictures
    baseUriParameters:
      apiDomain:
        enum: [ "static" ]
    get:
      displayName: retrieve a user's picture
    put:
      displayName: update a user's picture
      baseUriParameters:
        apiDomain:
          enum: [ "content-update" ]

The RAML JS parser seems to disallow this.

What about support for new RAML 1.0? http://docs.raml.org/specs/1.0/

Only checks for https? and disallows other protocols.

See code:

See also: mulesoft-labs/raml-client-generator#6