Dynamic population of example json in RAML

Question

I am loving how RAML can dynamically reference different schemas when declaring a resourceType like:

resourceTypes:
  - collection:
      get:
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
      post:
        body:
          application/json:
            schema: <<schema>>Create
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>

Here I am able to use this like

/users:
  type: { collection: { schema: user } }

and RAML will give me user schema responses from GETs and POSTs and also use the userCreate schema for sending POST requests. Cool! Now I can reuse my collection definition with tons of different schemas.

But now that I want to have example json for everything too, I was hoping to utilize the <<schema>> var in another way to leverage "code reuse". I was hoping to be able to do

resourceTypes:
  - collection:
      get:
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
                example: examples/v1-<<schema>>.json
      post:
        body:
          application/json:
            schema: <<schema>>Create
            example: examples/v1-<<schema>>-create.json
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
                example: examples/v1-<<schema>>.json

but unfortunately this does not work. I get an error saying

error: File with path "/examples/v1-%3C%3Cschema%3E%3E.json" does not exist

So now I have resorted to manually adding this to all my collections and the /users example above has become

/users:
  type: { collection: { schema: user } }
  get:
    responses:
      200:
        body:
          application/json:
            example: !include examples/v1-user.json
  post:
    body:
      application/json:
        example: !include examples/v1-user-create.json
    responses:
      200:
        body:
          application/json:
            example: !include examples/v1-user.json

To me, this is a LOT of overhead just to add examples. Especially when I want to repeat the pattern over many resources.

The question: Is there a way to accomplish this?

Inexorable

Answer 1

No, this is not allowed in RAML 0.8 according to the spec. It might be allowed in future versions though.

Bacillary

RAML 1.0 also doesn't allow it, in the specification says: The !include tag argument must be static: namely, it MUST NOT contain any resource type parameters or trait parameters. – Daegal

Answer 2

Since RAML is just a standard, I first would ask: Who/What is throwing that error? (I mean, what tool are you using?) Plus: Are you sure about the example (the first one)? It's not using !include, so, should not be even intending to reach that inexistent file (I'm assumed that you are using !includes in your original script but omitted that when copying here).

Additionally, and I know you are not asking for this, but just in case: - You could pass 2 parameters (as a workaround), one for the schema and another for the example (it's still overhead but not THAT hardcoded). - Do you know about the reserved parameters? Using that + "singularize" or "pluralize" depending the case, could also help you in your reuse enterprise ;) Take a look at http://raml.org/docs-200.html#parameters

Inappreciative