Resource Type Parameter not being properly handled

[cmd-johnson]

I'm currently testing the raml1.0 branch and encountered this error while testing resource types:

Error: Unknown type <<resourcePathName>> in {"test" {:name "test", :displayName "test", :typePropertyKind "TYPE_EXPRESSION", :type ["string"]}, :path [], :fixpoints #object [cljs.core.Atom {:val {}}]}
    at datatype_expansion$utils$error ([...]/osprey-test/node_modules/datatype-expansion/node/datatype_expansion/utils.js:42:8)
    at datatype_expansion$expanded_form$expanded_form_inner ([...]/osprey-test/node_modules/datatype-expansion/node/datatype_expansion/expanded_form.js:319:39)
    at [...]/osprey-test/node_modules/datatype-expansion/node/datatype_expansion/expanded_form.js:218:61
    at [...]/osprey-test/node_modules/datatype-expansion/node/cljs/core.js:17998:135
    at [...]/osprey-test/node_modules/datatype-expansion/node/cljs/core.js:19036:96
    at [...]/osprey-test/node_modules/datatype-expansion/node/cljs/core.js:19037:3
    at cljs.core.PersistentVector.cljs$core$IReduce$_reduce$arity$3 ([...]/osprey-test/node_modules/datatype-expansion/node/cljs/core.js:19052:3)
    at Function.cljs.core.reduce.cljs$core$IFn$_invoke$arity$3 ([...]/osprey-test/node_modules/datatype-expansion/node/cljs/core.js:7733:13)
    at Function.cljs.core.mapv.cljs$core$IFn$_invoke$arity$2 ([...]/osprey-test/node_modules/datatype-expansion/node/cljs/core.js:17997:52)
    at cljs$core$mapv ([...]/osprey-test/node_modules/datatype-expansion/node/cljs/core.js:17978:23)

Looks to me like <<resourcePathName>> is not properly replaced with test before it is passed on to the datatype-expansion module.

I managed to produce this error with this example:

index.js

#!/usr/bin/env node
const { join } = require('path')

require('osprey').loadFile(join(__dirname, 'test.raml'))
  .then(() => console.log('works as intended'))
  .catch(console.error)

test.raml

#%RAML 1.0
title: test
mediaType: application/json
types:
  test: string
resourceTypes:
  testType:
    post:
      body:
        type: <<resourcePathName>>
/test:
  type: testType

[jstoiko]

The underlying library that expands datatypes after it parses the RAML file and before it loads it into Osprey does not support <<resourcePathName>> as a value of type. It would be a nice feature to have though. I created an issue.

BTW, you might want to define your test type some properties, i.e.:

types:
  test: 
    properties:
      test_value: string

In the meantime, you'll have to avoid using type: <<resourcePathName>> if you want to use your RAML in Osprey, i.e.:

#%RAML 1.0
title: test
mediaType: application/json

types:
  test:
    properties:
      test_value: string

resourceTypes:
  testType:
    post:
      body:
        type: test

/test:
  type: testType

[cmd-johnson]

Okay, the <<resourcePathName>> case might be a little special.

However I did some digging, and if I'm not mistaken, the RAML 1.0 specification allows for this syntax:

#%RAML 1.0
title: test
mediaType: application/json

types:
  Client:
    properties:
      id: string

resourceTypes:
  collection:
    get:
      responses:
        200:
          body:
            <<resourceType>>[]

/clients:
  type: { collection: { resourceType: Client } }

After stepping through Osprey's code, I found that in the _expand function in expandTypes in lib/server.js, Osprey tries to expand the <<resourceType>> parameter from the example above within the resourceTypes object. Now that obviously cannot work, because that parameter is a placeholder that can only be replaced as soon as the parameter is assigned a value, which in this case only happens inside the /clients's type definition.

raml-1-parser already takes care of replacing the <<resourceType>> parameter and the /clients resource ends up containing a 200 response with a body containing an array of Clients.

If I'm not mistaken, it should be fine to simply skip expanding Resource Types altogether to prevent this error from happening, since the application of Resource Types seems to be something raml-1-parser takes care of.

Edit

Actually, looking further, I found that raml-1-parser even handles the <<resourcePathName>> case and correctly expands it, so it doesn't appear to me like this is an Issue with the datatype-expansion module after all, but really with Osprey trying to expand the resourceType-object:

raml-1-parser transforms

#%RAML 1.0
title: test
mediaType: application/json

types:
  test:
    properties:
      test_value: string

resourceTypes:
  testType:
    post:
      body:
        type: <<resourcePathName>>

/test:
  type: testType

to

{ types: 
   [ { test: 
        { name: 'test',
          displayName: 'test',
          typePropertyKind: 'TYPE_EXPRESSION',
          type: [ 'object' ],
          properties: 
           { test_value: 
              { name: 'test_value',
                displayName: 'test_value',
                typePropertyKind: 'TYPE_EXPRESSION',
                type: [ 'string' ],
                required: true } } } } ],
  resourceTypes: 
   [ { testType: 
        { name: 'testType',
          post: 
           { body: 
              { body: 
                 { name: 'body',
                   displayName: 'body',
                   typePropertyKind: 'TYPE_EXPRESSION',
                   type: [ '<<resourcePathName>>' ] } },
             method: 'post' } } } ],
  title: 'test',
  mediaType: 'application/json',
  resources: 
   [ { methods: 
        [ { body: 
             { 'application/json': 
                { name: 'application/json',
                  displayName: 'application/json',
                  typePropertyKind: 'TYPE_EXPRESSION',
                  type: [ 'test' ] } },
            method: 'post' } ],
       type: 'testType',
       relativeUri: '/test',
       displayName: '/test',
       relativeUriPathSegments: [ 'test' ],
       absoluteUri: '/test' } ] }

and after applying expandTypes to this object (editing Osprey's code to exclude the resourceTypes object), the /test-resource's application/json body definition is correctly transformed into

{ additionalProperties: true,
  type: 'object',
  displayName: 'application/json',
  name: 'application/json',
  typePropertyKind: 'TYPE_EXPRESSION',
  properties: 
   { test_value: 
      { type: 'string',
        displayName: 'test_value',
        name: 'test_value',
        typePropertyKind: 'TYPE_EXPRESSION',
        required: true } } } }

I'll create a PR for my changes.

[jstoiko]

You are totally right!

Thanks for this. I'll review/comment your PR.

[cmd-johnson]

Looking even further into the issue, I don't see anymore why you're expanding types at all - raml-1-parser takes care of all that and even the extensive GitHub API example turns out exactly the same as before calling expandTypes in server.js.

The type expansion however does have some bugs, but that looks like it's an issue with raml-1-parser. For example I cannot create middleware for the GitHub example using Osprey. Looks like some types aren't fully expanded, resulting in osprey-method-handler not being able to build a validator for them.

Edit:
Okay, Just tried out removing the type expansion and now some tests are failing, looking into it.

Edit2:
Okay, now I see it - raml-1-parser only expands types in traits and resourceTypes and the GitHub example is written in RAML 0.8 (duh). However, that means that the type expansion can be restricted to resources only, making my initial fix obsolete since type parameters should already have been resolved by raml-1-parser.